riverworkflow

type Gate struct {/* contains filtered or unexported fields */}

type GateMetadataDecodeError struct {
	// Err is the underlying decode failure.
	Err error
	// Field is the metadata field that failed decoding.
	Field string
}

type GatePhase int

const (
	// GatePhaseNone indicates the task has no gate.
	GatePhaseNone GatePhase = iota

	// GatePhaseInactive indicates a gate exists but has not been activated yet.
	GatePhaseInactive

	// GatePhaseWaiting indicates a gate is active but not yet satisfied.
	GatePhaseWaiting

	// GatePhaseSatisfied indicates a gate is satisfied.
	GatePhaseSatisfied
)

type GateSatisfaction struct {/* contains filtered or unexported fields */}

type GateSatisfactionSignalBoundary struct {
	// Count is the number of visible signals for the key at satisfaction time.
	Count int64
	// LastSignalID is the maximum visible signal ID for the key.
	LastSignalID int64
}

type GateSatisfactionSignalView struct {
	// Count is the number of visible signals for the key at satisfaction time.
	Count int64
	// Key identifies the signal stream within the workflow.
	Key string
	// LastSignalID is the maximum visible signal ID for the key.
	LastSignalID int64
}

type GateSatisfactionTimer struct {
	// FireAt is the timer's effective fire time when known.
	FireAt *time.Time
	// Fired reports whether the timer was fired at satisfaction time.
	Fired bool
}

type GateSatisfactionTimerView struct {
	// FireAt is the timer's effective fire time when known.
	FireAt *time.Time
	// Fired reports whether the timer was fired at satisfaction time.
	Fired bool
	// Name is the declared timer name.
	Name string
}

type GateSatisfactionView struct {
	// AsOf is the evaluator timestamp used when the gate was satisfied.
	AsOf time.Time
	// Attempt is the workflow attempt active when the snapshot was captured.
	Attempt int
	// Signals contains captured signal boundaries sorted by key.
	Signals []*GateSatisfactionSignalView
	// Timers contains captured timer statuses sorted by name.
	Timers []*GateSatisfactionTimerView
}

type GateSpec struct {
	// Expr is a CEL expression that must evaluate to true for the gate to be
	// satisfied.
	//
	// Available variables (field names use snake_case JSON tags):
	//   - signals: map[string][]SignalEvent
	//     - SignalEvent fields: attempt (int), created_at (time), id (int64),
	//       key (string), payload (map[string]any)
	//   - timers: map[string]TimerStatus
	//     - TimerStatus fields: fired (bool), fire_at (*time)
	//   - deps: map[string]Dep
	//     - Dep fields: finalized_at (*time), output (map[string]any),
	//       state (string job state)
	//   - workflow: WorkflowVars
	//     - WorkflowVars fields: attempt (int), created_at (time), id (string),
	//       metadata (map[string]any)
	//
	// Keys referenced in signals/timers/deps must be declared in
	// GateSpec.Signals, GateSpec.Timers, and the task's workflow deps.
	// Time-based waiting should use declared timers such as
	// `timers["timeout"].fired`.
	//
	// Examples:
	//   signals["approval"].exists(s, s.payload.approved == true)
	//   timers["timeout"].fired
	//   deps["build"].state == "completed" && deps["build"].output.sha != ""
	Expr string
	// Signals declares which signal keys the gate expression may read.
	//
	// Gate evaluation only exposes declared keys in `signals["key"]`, and signal
	// emissions on those keys enqueue gate reevaluation.
	Signals []string
	// Timers declares named timers used by the gate expression.
	//
	// Declared timers are materialized when the gate becomes active and are then
	// exposed to CEL as `timers["name"]` with `fire_at` and `fired` fields. Timer
	// progression also triggers reevaluation.
	Timers []Timer
}

type GateTimer struct {
	// Anchor describes how a relative timer is anchored.
	//
	// Absolute timers use the zero [TimerAnchor].
	Anchor TimerAnchor
	// After is the declared relative duration for timers authored with `after`.
	After time.Duration
	// FireAt is the effective absolute fire time when known. For authored
	// absolute timers this is the declared fire time. For relative timers it is
	// populated once the gate is active and the anchor has been resolved.
	FireAt time.Time
	// HasAfter reports whether After was explicitly declared.
	HasAfter bool
	// HasFireAt reports whether FireAt is known.
	HasFireAt bool
	// Name is the timer name referenced in CEL (`timers["name"]`).
	Name string
}

type GateTimerAnchorView struct {
	// Kind identifies the source time used to resolve a relative timer.
	Kind TimerAnchorKind
	// Task is the dependency task name for dependency-finalized timers.
	Task string
}

type GateTimerView struct {
	// After is the declared relative duration for timers authored with `after`.
	After string
	// AfterUS is the declared relative duration in microseconds.
	AfterUS *int64
	// Anchor describes how a relative timer is anchored.
	Anchor *GateTimerAnchorView
	// FireAt is the effective absolute fire time when known.
	FireAt *time.Time
	// HasAfter reports whether After was explicitly declared.
	HasAfter bool
	// HasFireAt reports whether FireAt is known.
	HasFireAt bool
	// Name is the timer name referenced in CEL.
	Name string
}

type GateValidationError struct {
	// Err is the underlying validation failure.
	Err error
	// GateExpr is the gate CEL expression being validated, when available.
	GateExpr string
	// TaskName is the workflow task whose gate failed validation, when
	// available.
	TaskName string
	// WorkflowID is the ID of the workflow containing the failing task, when
	// available.
	WorkflowID string
}

type GateView struct {
	// ActiveAt is when the gate became active, when known.
	ActiveAt *time.Time
	// DeclaredSignals contains signal keys referenced by the gate.
	DeclaredSignals []string
	// Enabled reports whether the task has a gate.
	Enabled bool
	// ExprCEL is the CEL expression that controls the gate.
	ExprCEL string
	// Phase summarizes the gate lifecycle.
	Phase string
	// Satisfaction captures what made the gate pass.
	Satisfaction *GateSatisfactionView
	// SatisfiedAt is when the gate became satisfied, when known.
	SatisfiedAt *time.Time
	// Timers contains declared timers sorted by name.
	Timers []*GateTimerView
}

type Signal struct {
	// Attempt is the workflow attempt number from when this signal was emitted.
	Attempt int
	// CreatedAt is when the signal row was inserted.
	CreatedAt time.Time
	// ID is the unique identifier of the signal row.
	ID int64
	// Key identifies the signal stream within the workflow. Gate
	// definitions reference signal keys (for example, signals["approval"]) to
	// decide which signals can satisfy a task's gate expression.
	Key string
	// Payload is the JSON payload associated with the signal.
	Payload json.RawMessage
	// Source is immutable JSON metadata describing the emitter for audit and
	// correlation (for example emitter type or request IDs).
	Source json.RawMessage
	// WorkflowID is the ID of the workflow that this signal belongs to.
	WorkflowID string
}

type SignalAttemptMismatchError struct {
	// RequestedAttempt is the attempt requested by the emitter.
	RequestedAttempt int
	// SignalAttempt is the attempt stamped on the inserted signal row.
	SignalAttempt int
	// WorkflowID is the ID of the workflow associated with the signal.
	WorkflowID string
}

type SignalKeyUndeclaredError struct {
	Key string

	TaskName   string
	WorkflowID string
}

type SignalPayloadMismatchError struct {
	// SignalID is the existing signal ID returned by the idempotent insert path.
	SignalID *int64
	// WorkflowID is the ID of the workflow associated with the signal.
	WorkflowID string
}

type SignalTaskDeclaresNoSignalKeysError struct {
	TaskName   string
	WorkflowID string
}

type SignalUnknownTaskError struct {
	TaskName   string
	WorkflowID string
}

type Timer struct {/* contains filtered or unexported fields */}

type TimerAnchor struct {
	// DepTask is the dependency task name for dependency-finalized timers.
	DepTask string
	// Kind identifies the source time used to resolve a relative timer.
	Kind TimerAnchorKind
}

type TimerAnchorKind string

const (
	// TimerAnchorKindDepFinalizedAt anchors relative timers to a dependency's
	// finalization time.
	TimerAnchorKindDepFinalizedAt TimerAnchorKind = "dep_finalized_at"

	// TimerAnchorKindGateActiveAt anchors relative timers to gate activation
	// time.
	TimerAnchorKindGateActiveAt TimerAnchorKind = "gate_active_at"

	// TimerAnchorKindWorkflowCreatedAt anchors relative timers to the workflow's
	// creation time.
	TimerAnchorKindWorkflowCreatedAt TimerAnchorKind = "workflow_created_at"
)