wait

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package wait defines application-neutral durable wait, resume, and timed activation contracts.

A wait is durable state rather than a blocked worker. Gate, message, timer, callback, child-run, and signal adapters all converge on the same resume operation. Host-specific endpoint materialization and scheduler bindings sit behind the narrow interfaces in this package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DigestToken 

func DigestToken(token string) (string, error)

DigestToken returns the only representation of a resume token that may be persisted. Raw tokens are returned once by the creating host and never stored or logged by core.

func EqualTokenDigest 

func EqualTokenDigest(left, right string) bool

EqualTokenDigest reports whether two validated canonical token digests are equal without using an ordinary credential string comparison. Invalid or non-canonical digests never compare equal.

Types

type Activation 

type Activation struct {
	ID         ActivationID        `json:"id"`
	Kind       string              `json:"kind"`
	RunID      string              `json:"run_id"`
	NodeID     string              `json:"node_id"`
	Iteration  string              `json:"iteration,omitempty"`
	WaitID     string              `json:"wait_id,omitempty"`
	FireAt     time.Time           `json:"fire_at"`
	DedupKey   string              `json:"dedup_key"`
	PayloadRef *values.ValueSetRef `json:"payload_ref,omitempty"`
}

Activation is the core's application-neutral timed activation request.

func (Activation) Validate 

func (a Activation) Validate() error

type ActivationID 

type ActivationID string

type ActivationScheduler 

type ActivationScheduler interface {
	Schedule(context.Context, Activation) error
	Cancel(context.Context, ActivationID) error
}

ActivationScheduler is implemented by a host scheduler adapter. Schedule and Cancel must be idempotent by activation identity.

type AuthorizationRequest 

type AuthorizationRequest struct {
	Record    Record
	Source    WakeSource
	Responder Responder
}

AuthorizationRequest is evaluated by the host before the atomic resume transaction. The store subsequently revalidates all immutable wait fields.

type Kind 

type Kind string

Kind identifies the application-neutral reason an invocation is suspended. 

const (
	KindGate     Kind = "gate"
	KindMessage  Kind = "message"
	KindTimer    Kind = "timer"
	KindCallback Kind = "callback"
	KindChildRun Kind = "child_run"
	KindSignal   Kind = "signal"
)

func (Kind) Valid 

func (k Kind) Valid() bool

type Materialization 

type Materialization struct {
	WaitID    string    `json:"wait_id"`
	Kind      Kind      `json:"kind"`
	ResumeURL string    `json:"resume_url,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	Opaque    string    `json:"-"`
}

Materialization contains no raw resume token. Opaque is host-owned but must not be logged by core.

type Materializer 

type Materializer interface {
	Materialize(context.Context, Materialization) error
	Resolve(context.Context, Materialization) error
}

Materializer lets an application expose a durable wait as a one-shot endpoint or job with a TTL. Calls must be idempotent by wait identity.

type Record 

type Record struct {
	Kind        Kind   `json:"kind"`
	Correlation string `json:"correlation"`
	// SignalName is the stable, typed signal or event name used by named host
	// signal/update lookup. It is optional for backwards compatibility with
	// durable signal rows created before named signals were introduced.
	SignalName string `json:"signal_name,omitempty"`
	// WakeAt is the immutable successful timer firing time. It is distinct
	// from Deadline, which always means timeout-at. Legacy timer records without
	// WakeAt remain timeout-only.
	WakeAt            time.Time           `json:"wake_at,omitempty"`
	Deadline          time.Time           `json:"deadline,omitempty"`
	Payload           *values.ValueSetRef `json:"payload,omitempty"`
	ResumeSchema      SchemaRef           `json:"resume_schema"`
	ResumeTokenDigest string              `json:"resume_token_digest,omitempty"`
	ResumeURL         string              `json:"resume_url,omitempty"`
	Visibility        Visibility          `json:"visibility"`
	Authority         ResponderAuthority  `json:"authority"`
	WakeSource        WakeSource          `json:"wake_source"`
	Status            Status              `json:"status"`
	ResumeValues      *values.ValueSetRef `json:"resume_values,omitempty"`
	Resolution        *Resolution         `json:"resolution,omitempty"`
}

Record is the canonical semantic wait record. Runtime storage envelopes add the wait and invocation identities plus CAS generations and storage times.

func (Record) Validate 

func (r Record) Validate() error

Validate rejects ambiguous records and token-bearing persisted URLs.

type Resolution 

type Resolution struct {
	Source         WakeSource `json:"source"`
	Responder      Responder  `json:"responder"`
	PayloadDigest  string     `json:"payload_digest,omitempty"`
	IdempotencyKey string     `json:"idempotency_key,omitempty"`
	ResolvedAt     time.Time  `json:"resolved_at"`
}

Resolution is immutable terminal provenance. PayloadDigest binds a resumed record to the accepted typed payload without retaining the payload inline.

func (Resolution) Validate 

func (r Resolution) Validate() error

type Responder 

type Responder struct {
	Kind       string            `json:"kind"`
	Reference  string            `json:"reference"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

Responder records the already-authorized principal or adapter that resolved a wait. It is provenance, not a host authorization model.

func (Responder) Validate 

func (r Responder) Validate() error

type ResponderAuthority 

type ResponderAuthority struct {
	Kind       string            `json:"kind"`
	Reference  string            `json:"reference,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

ResponderAuthority declares the host policy that may accept a response. Kind is intentionally open for extraction; Reference is opaque to core.

func (ResponderAuthority) Validate 

func (a ResponderAuthority) Validate() error

type ResponderAuthorizer 

type ResponderAuthorizer interface {
	AuthorizeResume(context.Context, AuthorizationRequest) error
}

ResponderAuthorizer applies host identity and policy without leaking those concepts into the durable wait model.

type SchemaRef 

type SchemaRef struct {
	Digest string       `json:"digest"`
	Schema graph.Schema `json:"schema"`
}

SchemaRef is an immutable digest-bound inline JSON Schema declaration.

func NewSchemaRef 

func NewSchemaRef(schema graph.Schema) (SchemaRef, error)

NewSchemaRef validates and defensively copies a schema.

func (SchemaRef) Validate 

func (r SchemaRef) Validate() error

Validate verifies the schema declaration and its deterministic digest.

type Status 

type Status string

Status is the durable resolution state of a wait. 

const (
	StatusOpen     Status = "open"
	StatusResumed  Status = "resumed"
	StatusTimedOut Status = "timed_out"
	StatusCanceled Status = "canceled"
)

func (Status) Valid 

func (s Status) Valid() bool

type Visibility 

type Visibility string

Visibility describes who may discover a wait without changing value-plane redaction or retention semantics. 

const (
	VisibilityPublic  Visibility = "public"
	VisibilityPrivate Visibility = "private"
	VisibilitySecret  Visibility = "secret"
)

func (Visibility) Valid 

func (v Visibility) Valid() bool

type WakeSource 

type WakeSource string

WakeSource identifies the adapter through which a wait can be resolved. 

const (
	WakeGate     WakeSource = "gate"
	WakeMessage  WakeSource = "message"
	WakeTimer    WakeSource = "timer"
	WakeCallback WakeSource = "callback"
	WakeChildRun WakeSource = "child_run"
	WakeSignal   WakeSource = "signal"
)

func (WakeSource) Valid 

func (s WakeSource) Valid() bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.