watch

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (

	// EventsCursorVersion namespaces durable watch-event cursor values.
	EventsCursorVersion = 1
)

Variables

View Source
var (
	// ErrPollerRequired reports a missing watch-source poll dependency.
	ErrPollerRequired = errors.New("loop watch poller is required")
	// ErrSpecRequired reports an empty watch-source spec.
	ErrSpecRequired = errors.New("loop watch spec is required")
	// ErrSpecInvalid reports a malformed watch-source spec.
	ErrSpecInvalid = errors.New("loop watch spec is invalid")
)

Functions

func ConfirmedOutputRef

func ConfirmedOutputRef(response PollResponse) (string, error)

ConfirmedOutputRef stores the confirmed ready payload as the source node output.

func EventsConfirmedOutputPayload

func EventsConfirmedOutputPayload(events any, cursors map[string]int64) (json.RawMessage, error)

EventsConfirmedOutputPayload returns the complete confirmed watch-events JSON payload. Callers may persist it inline or by content-addressed output ref.

func EventsConfirmedOutputRef

func EventsConfirmedOutputRef(events any, cursors map[string]int64) (string, error)

EventsConfirmedOutputRef stores the confirmed watch-events batch inline.

func EventsPendingOutputRef

func EventsPendingOutputRef(state EventsPendingState) (string, error)

EventsPendingOutputRef stores rendered subscriptions and stream cursors while a watch-events loop is dormant.

func ExpectedStateDigestFromOutputRef

func ExpectedStateDigestFromOutputRef(ref string) (string, error)

ExpectedStateDigestFromOutputRef recovers the prior state digest for the next poll.

func NormalizeEventKey

func NormalizeEventKey(value string) (string, error)

NormalizeEventKey validates and canonicalizes one stable watch delivery identity.

func PendingOutputRef

func PendingOutputRef(response PollResponse) (string, error)

PendingOutputRef stores the last observed source digest while a loop is watching.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter runs one callback-free poll -> ready -> settle -> confirm claim cycle.

func NewAdapter

func NewAdapter(poller Poller) (*Adapter, error)

NewAdapter constructs a watch-source adapter for coordinator claims.

func (*Adapter) Tick

func (a *Adapter) Tick(ctx context.Context, req TickRequest) (TickResult, error)

Tick runs exactly one watch-source claim cycle. It never parks a goroutine.

type EventSubscriptionRef

type EventSubscriptionRef struct {
	Kind   string `json:"kind"`
	Filter string `json:"filter,omitempty"`
}

EventSubscriptionRef is the durable subscription shape stored while a watch-events node is parked.

type EventsPendingState

type EventsPendingState struct {
	Subscriptions []EventSubscriptionRef `json:"subscriptions"`
	Cursors       map[string]int64       `json:"cursors"`
	CursorVersion int                    `json:"cursor_version"`
}

EventsPendingState is the parked watch-events output_ref state.

func EventsPendingFromOutputRef

func EventsPendingFromOutputRef(ref string) (EventsPendingState, bool, error)

EventsPendingFromOutputRef recovers parked watch-events state.

type Outcome

type Outcome string

Outcome classifies the coordinator-owned watch claim result.

const (
	OutcomeWaiting Outcome = "waiting"
	OutcomeReady   Outcome = "ready"
	OutcomeStalled Outcome = "stalled"
)

type OutputRef

type OutputRef struct {
	Kind          string                 `json:"kind"`
	StateDigest   string                 `json:"state_digest,omitempty"`
	EventKey      string                 `json:"event_key,omitempty"`
	Payload       json.RawMessage        `json:"payload,omitempty"`
	SettledAt     *time.Time             `json:"settled_at,omitempty"`
	Subscriptions []EventSubscriptionRef `json:"subscriptions,omitempty"`
	Cursors       map[string]int64       `json:"cursors,omitempty"`
	CursorVersion int                    `json:"cursor_version,omitzero"`
	Events        json.RawMessage        `json:"events,omitempty"`
}

OutputRef is the JSON payload persisted in loop_generation_outputs.output_ref for coordinator-owned watch nodes.

type PollRequest

type PollRequest struct {
	Spec                json.RawMessage `json:"spec"`
	ExpectedStateDigest string          `json:"expected_state_digest,omitempty"`
}

PollRequest is the daemon -> extension watch/poll service payload.

type PollResponse

type PollResponse struct {
	Ready       bool            `json:"ready"`
	EventKey    string          `json:"event_key"`
	StateDigest string          `json:"state_digest,omitempty"`
	Payload     json.RawMessage `json:"payload,omitempty"`
	SettledAt   *time.Time      `json:"settled_at,omitempty"`
}

PollResponse is the extension -> daemon watch/poll service result.

type Poller

type Poller interface {
	Poll(ctx context.Context, req PollRequest) (PollResponse, error)
}

Poller calls one watch-source provider for a coordinator-owned poll cycle.

type PollerFunc

type PollerFunc func(context.Context, PollRequest) (PollResponse, error)

PollerFunc adapts a function to Poller.

func (PollerFunc) Poll

Poll implements Poller.

type TickRequest

type TickRequest struct {
	Spec                json.RawMessage
	ExpectedStateDigest string
	LastProgressAt      time.Time
	SilenceWindow       time.Duration
	Now                 time.Time
}

TickRequest carries durable re-entry state plus the current poll input.

type TickResult

type TickResult struct {
	Outcome     Outcome
	Response    PollResponse
	Transitions []Transition
}

TickResult is the adapter result consumed by the loop coordinator.

type Transition

type Transition struct {
	Event string
	From  string
	To    string
}

Transition records one ephemeral FSM transition from a coordinator-owned tick.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL