Documentation
¶
Overview ¶
Package waitadapter implements durable external wait step kinds over the canonical workflow/wait record and runtime continuation contract.
The executors never poll or retain a worker. Initial execution returns a StepWaiting handoff; accepted resumes re-drive the same attempt with a typed continuation. Host identity, callback materialization, and responder policy are injected. This package owns neither persistence nor transports. Callback-capable wait_for is conservatively unavailable in embedded mode. Callback issuers must honor the stable issuance key and own TTL cleanup if issuance succeeds but durable suspension later fails.
Index ¶
- Constants
- type AuthorityRequest
- type AuthorityResolver
- type AuthorityResolverFunc
- type CallbackCredential
- type CallbackIssuer
- type CallbackIssuerFunc
- type CallbackRequest
- type ChildRunFailure
- type ChildRunTerminalEnvelope
- type ChildRunTerminalStatus
- type MessageWait
- type Options
- type Registration
- type Sleep
- type Source
- type SourceKind
- type WaitFor
Constants ¶
const ( WaitForName = "wait_for" MessageWaitName = "message_wait" SleepName = "sleep" Version = "v1" CapabilityWait = "wait.resume" CapabilityMessage = "message.receive" CodeInvalidInvocation = "wait_invalid_invocation" CodeAuthorityFailed = "wait_authority_failed" CodeCallbackFailed = "wait_callback_failed" CodeContinuation = "wait_continuation_invalid" CodeChildRunFailed = "wait_child_run_unsuccessful" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthorityRequest ¶
type AuthorityRequest struct {
Identity stepkind.InvocationIdentity `json:"identity"`
Source Source `json:"source"`
Correlation string `json:"correlation"`
}
AuthorityRequest supplies immutable invocation and wake details to an application-owned policy resolver. Implementations must be concurrency-safe.
type AuthorityResolver ¶
type AuthorityResolver interface {
ResolveWaitAuthority(context.Context, AuthorityRequest) (workflowwait.ResponderAuthority, error)
}
AuthorityResolver returns the responder authority persisted in the generic wait record. The runtime's ResponderAuthorizer enforces it on resume.
type AuthorityResolverFunc ¶
type AuthorityResolverFunc func(context.Context, AuthorityRequest) (workflowwait.ResponderAuthority, error)
AuthorityResolverFunc adapts a function to AuthorityResolver.
func (AuthorityResolverFunc) ResolveWaitAuthority ¶
func (f AuthorityResolverFunc) ResolveWaitAuthority(ctx context.Context, request AuthorityRequest) (workflowwait.ResponderAuthority, error)
ResolveWaitAuthority implements AuthorityResolver.
type CallbackCredential ¶
CallbackCredential is process-local. Token is returned once in StepWaiting and only its digest is persisted. URL must not contain Token.
type CallbackIssuer ¶
type CallbackIssuer interface {
IssueCallback(context.Context, CallbackRequest) (CallbackCredential, error)
}
CallbackIssuer creates an application-owned one-shot callback endpoint. An implementation must be concurrency-safe and idempotent for the same immutable IdempotencyKey: retrying an invocation must return the same URL and token instead of creating another concurrently live endpoint, even when requested ExpiresAt advances. The host must extend that credential through the requested expiry (or fail); replacement is permitted only after it has expired. Issuers own expiry conflicts and TTL cleanup for a credential created before durable suspension.
type CallbackIssuerFunc ¶
type CallbackIssuerFunc func(context.Context, CallbackRequest) (CallbackCredential, error)
CallbackIssuerFunc adapts a function to CallbackIssuer.
func (CallbackIssuerFunc) IssueCallback ¶
func (f CallbackIssuerFunc) IssueCallback(ctx context.Context, request CallbackRequest) (CallbackCredential, error)
IssueCallback implements CallbackIssuer.
type CallbackRequest ¶
type CallbackRequest struct {
Identity stepkind.InvocationIdentity `json:"identity"`
Path string `json:"path"`
Correlation string `json:"correlation"`
ExpiresAt time.Time `json:"expires_at"`
// IdempotencyKey is derived from immutable invocation, path, and
// correlation identity. ExpiresAt is a requested TTL, not part of identity.
IdempotencyKey string `json:"idempotency_key"`
}
CallbackRequest asks a host to materialize one callback without exposing a host route or credential format to workflow core.
type ChildRunFailure ¶
type ChildRunFailure struct {
Code string `json:"code"`
Message string `json:"message"`
Retryable bool `json:"retryable,omitempty"`
}
ChildRunFailure is safe terminal metadata supplied by the host wake bridge. Provider causes and raw logs must not enter this envelope.
type ChildRunTerminalEnvelope ¶
type ChildRunTerminalEnvelope struct {
Status ChildRunTerminalStatus `json:"status"`
Outputs map[string]any `json:"outputs,omitempty"`
Failure *ChildRunFailure `json:"failure,omitempty"`
}
ChildRunTerminalEnvelope is the generic child-run wake payload. Successful deliveries carry typed JSON outputs; unsuccessful deliveries carry only safe failure metadata and are converted to ordinary step failure when the wait config opts into fail_on_unsuccessful.
func (ChildRunTerminalEnvelope) Validate ¶
func (e ChildRunTerminalEnvelope) Validate() error
type ChildRunTerminalStatus ¶
type ChildRunTerminalStatus string
ChildRunTerminalStatus is the closed status vocabulary accepted by a fail-on-unsuccessful child-run wait.
const ( ChildRunSucceeded ChildRunTerminalStatus = "succeeded" ChildRunFailed ChildRunTerminalStatus = "failed" ChildRunCanceled ChildRunTerminalStatus = "canceled" ChildRunTimedOut ChildRunTerminalStatus = "timed_out" ChildRunCrashed ChildRunTerminalStatus = "crashed" )
type MessageWait ¶
type MessageWait struct {
// contains filtered or unexported fields
}
MessageWait implements message_wait@v1 as a message-arrival resume, never a mailbox poll.
func NewMessageWait ¶
func NewMessageWait(options Options) (*MessageWait, error)
NewMessageWait constructs a fail-closed message wait executor.
func (*MessageWait) Execute ¶
func (e *MessageWait) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)
Execute suspends for a message initially and returns the exact accepted message Value plus safe resume metadata after continuation.
func (*MessageWait) Spec ¶
func (*MessageWait) Spec() stepkind.StepKindSpec
Spec returns immutable message_wait@v1 metadata.
func (*MessageWait) ValidateConfig ¶
func (*MessageWait) ValidateConfig(_ context.Context, input graph.Config) []diagnostic.Diagnostic
ValidateConfig reports deterministic source-addressable config paths.
type Options ¶
type Options struct {
Authority AuthorityResolver
Callbacks CallbackIssuer
Now func() time.Time
}
Options supplies host-owned wait policy and callback construction. Now is injectable for deterministic durable deadlines.
type Registration ¶
type Registration struct {
Sleep *Sleep
WaitFor *WaitFor
MessageWait *MessageWait
}
Registration is the registered wait-backed executor set implemented by this package.
func Register ¶
func Register(registry stepkind.Registry, options Options) (Registration, error)
Register registers sleep@v1, wait_for@v1, and message_wait@v1 from the caller's perspective unless the supplied registry reports a duplicate after the first registration. Registries do not expose rollback; callers should register into a fresh registry during host assembly.
type Sleep ¶
type Sleep struct {
// contains filtered or unexported fields
}
Sleep implements sleep@v1 as a durable successful timer. WakeAt is never a timeout Deadline; runtime schedules a distinct wait_wake activation.
func (*Sleep) Execute ¶
func (e *Sleep) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)
Execute returns StepWaiting initially and completes only from an authorized successful timer continuation.
func (*Sleep) Spec ¶
func (*Sleep) Spec() stepkind.StepKindSpec
Spec returns immutable sleep@v1 metadata.
func (*Sleep) ValidateConfig ¶
func (*Sleep) ValidateConfig(_ context.Context, input graph.Config) []diagnostic.Diagnostic
ValidateConfig reports a deterministic duration diagnostic.
type Source ¶
type Source struct {
Kind SourceKind `json:"kind"`
Reference string `json:"reference"`
Attributes map[string]string `json:"attributes,omitempty"`
}
Source is the normalized source description supplied to host policy. Attributes contain stable non-secret identifiers only.
type SourceKind ¶
type SourceKind string
SourceKind is the adapter-level external wake vocabulary. Event is lowered to the canonical signal wake source and tagged in durable authority metadata.
const ( SourceSignal SourceKind = "signal" SourceEvent SourceKind = "event" SourceCallback SourceKind = "callback" SourceChildRun SourceKind = "child_run" SourceMessage SourceKind = "message" SourceTimer SourceKind = "timer" )
func (SourceKind) Valid ¶
func (s SourceKind) Valid() bool
Valid reports whether s is a supported external wake kind.
type WaitFor ¶
type WaitFor struct {
// contains filtered or unexported fields
}
WaitFor implements wait_for@v1 for signals, callbacks, events, and child-run completion. Event uses the canonical signal wake path with durable event metadata; no source is polled.
func NewWaitFor ¶
NewWaitFor constructs a fail-closed external wait executor.
func (*WaitFor) Execute ¶
func (e *WaitFor) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)
Execute returns a generic wait handoff initially and typed outputs only after the runtime supplies an accepted durable continuation.
func (*WaitFor) Spec ¶
func (*WaitFor) Spec() stepkind.StepKindSpec
Spec returns immutable wait_for@v1 metadata.
func (*WaitFor) ValidateConfig ¶
func (*WaitFor) ValidateConfig(_ context.Context, config graph.Config) []diagnostic.Diagnostic
ValidateConfig reports deterministic source-addressable config paths.
Source Files