temporal

Documentation

Overview

Package temporal hosts a fate statechart actor inside a Temporal workflow.

It is a thin, generic adapter over the clock-agnostic fate core: it drives the actor's pending effects — delayed transitions and invocations — by mapping them onto Temporal primitives inside the single workflow coroutine, and feeds the results back through the core's pull API. The fate engine itself stays dependency-free; this module is where (and the only place where) the Temporal SDK enters.

Mapping:

• PendingTimers → workflow.NewTimer; on fire, Actor.FireTimer.
• PendingInvocations → workflow.ExecuteActivity (Src is the activity name, Input the activity argument); on completion, Actor.ResolveInvocation, or Actor.RejectInvocation on failure.
• external events → a Temporal signal channel; on receive, Actor.Send.

Determinism: every effect is created and selected in a deterministic order (fate's pending lists are sorted by ID), and all actor calls happen on the workflow goroutine via the selector, so workflow replay reproduces identical transitions. The hosted actor must never be driven from another goroutine.

Index

• type Options
• type WorkflowActor
  • func NewWorkflowActor[Ctx any, Evt any](ctx workflow.Context, m *fate.Machine[Ctx, Evt], opts Options) (*WorkflowActor[Ctx, Evt], error)
  • func NewWorkflowActorFromSnapshot[Ctx any, Evt any](ctx workflow.Context, m *fate.Machine[Ctx, Evt], snapshot []byte, opts Options) (*WorkflowActor[Ctx, Evt], error)
  • func (w *WorkflowActor[Ctx, Evt]) Persist() ([]byte, error)
  • func (w *WorkflowActor[Ctx, Evt]) Run() (fate.Snapshot[Ctx], error)
  • func (w *WorkflowActor[Ctx, Evt]) Send(evt Evt) error
  • func (w *WorkflowActor[Ctx, Evt]) Snapshot() fate.Snapshot[Ctx]
  • func (w *WorkflowActor[Ctx, Evt]) Start() error
  • func (w *WorkflowActor[Ctx, Evt]) Stop()

Types

type Options

type Options struct {
	// ActivityOptions are applied to every invocation activity. At minimum a
	// StartToCloseTimeout (or ScheduleToCloseTimeout) is required by Temporal.
	ActivityOptions workflow.ActivityOptions
	// SignalName, if non-empty, is the signal channel the actor consumes
	// external events from. Each signal payload is decoded into Evt and sent to
	// the actor. Leave empty to drive events only via WorkflowActor.Send from
	// workflow code.
	SignalName string
}

Options configures how a WorkflowActor maps invocations and events onto Temporal.

type WorkflowActor

type WorkflowActor[Ctx any, Evt any] struct {
	// contains filtered or unexported fields
}

WorkflowActor hosts a fate Actor inside a Temporal workflow. Construct with NewWorkflowActor (or NewWorkflowActorFromSnapshot to resume), then call Run to drive the machine to completion.

func NewWorkflowActor

func NewWorkflowActor[Ctx any, Evt any](
	ctx workflow.Context,
	m *fate.Machine[Ctx, Evt],
	opts Options,
) (*WorkflowActor[Ctx, Evt], error)

NewWorkflowActor wraps a fresh actor for the given machine and starts it.

func NewWorkflowActorFromSnapshot

func NewWorkflowActorFromSnapshot[Ctx any, Evt any](
	ctx workflow.Context,
	m *fate.Machine[Ctx, Evt],
	snapshot []byte,
	opts Options,
) (*WorkflowActor[Ctx, Evt], error)

NewWorkflowActorFromSnapshot resumes an actor from a persisted snapshot — for example after continue-as-new. The actor's pending effects are re-derived from its restored configuration, so Run re-arms them.

func (*WorkflowActor[Ctx, Evt]) Persist

func (w *WorkflowActor[Ctx, Evt]) Persist() ([]byte, error)

Persist returns the hosted actor's persisted snapshot, e.g. to pass to continue-as-new.

func (*WorkflowActor[Ctx, Evt]) Run

func (w *WorkflowActor[Ctx, Evt]) Run() (fate.Snapshot[Ctx], error)

Run drives the hosted actor until it completes (reaches a top-level final state) or the machine can make no further progress, reconciling Temporal timers and activities against the actor's pending effects after every step and consuming signals if configured. It returns the final snapshot.

func (*WorkflowActor[Ctx, Evt]) Send

func (w *WorkflowActor[Ctx, Evt]) Send(evt Evt) error

Send delivers an event to the hosted actor from workflow code. It must be called on the workflow goroutine.

func (*WorkflowActor[Ctx, Evt]) Snapshot

func (w *WorkflowActor[Ctx, Evt]) Snapshot() fate.Snapshot[Ctx]

Snapshot returns the hosted actor's current snapshot.

func (*WorkflowActor[Ctx, Evt]) Start

func (w *WorkflowActor[Ctx, Evt]) Start() error

Start runs the actor's initial entry. NewWorkflowActor already starts the actor, so Start is idempotent and returns nil when the actor is already running. It is provided for callers that drive the actor manually (one Send per workflow callback, reading Snapshot between them) and prefer an explicit start in their own control flow.

func (*WorkflowActor[Ctx, Evt]) Stop

func (w *WorkflowActor[Ctx, Evt]) Stop()

Stop halts the hosted actor. A subsequent Send returns an error. Manual drivers call this when the workflow's task lifecycle ends.