signal

type BeforePhaseDecision ¶ added in v0.19.894

type BeforePhaseDecision struct {
	Allow    bool           `json:"allow"`
	Reason   string         `json:"reason,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

func AllowPhaseDecision() BeforePhaseDecision

type CloneStepDef ¶ added in v0.19.894

type CloneStepDef struct {
	Signal        Signal
	Name          string
	ExecutionType string // maps to app.WorkflowStepExecutionType (string to avoid importing app)
}

CloneStepDef describes a step to create when cloning a signal's step for retry.

type Params ¶ added in v0.19.872

type Params struct {
	MW  metrics.Writer
	Cfg *internal.Config
	V   *validator.Validate

	// QueueSignalID is the ID of the queue signal that this signal is associated with.
	// This allows signals to reference their own queue signal record if needed.
	QueueSignalID string
}

NOTE: we have a limited set of FX dependencies we can use in a signal, because they are built with signals and pass to and from workflows.

type Raw ¶ added in v0.19.894

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

Raw is a signal envelope for enqueueing without importing the concrete signal package. The queue handler deserializes into the real registered type via the catalog at execution time.

func (r *Raw) Execute(_ workflow.Context) error

func (r *Raw) MarshalJSON() ([]byte, error)

func (r *Raw) Type() SignalType

func (r *Raw) Validate(_ workflow.Context) error

type RunSignalLifecycleAfterPhaseRequest ¶ added in v0.19.894

type RunSignalLifecycleAfterPhaseRequest struct {
	Event   SignalPhaseEvent   `json:"event" validate:"required"`
	Outcome SignalPhaseOutcome `json:"outcome" validate:"required"`
}

type RunSignalLifecycleBeforePhaseRequest ¶ added in v0.19.894

type RunSignalLifecycleBeforePhaseRequest struct {
	Event SignalPhaseEvent `json:"event" validate:"required"`
}

type RunSignalLifecycleBeforePhaseResponse ¶ added in v0.19.894

type RunSignalLifecycleBeforePhaseResponse struct {
	Allow    bool           `json:"allow"`
	Reason   string         `json:"reason,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type Signal ¶

type Signal interface {
	Type() SignalType

	// workflow handler methods
	Validate(ctx workflow.Context) error
	Execute(ctx workflow.Context) error
}

func NewRaw(typ SignalType, data map[string]any) Signal

type SignalErrExecute ¶ added in v0.19.872

type SignalErrExecute struct {
	Err error
}

SignalErrExecute wraps an error that occurred during signal execution.

func (e *SignalErrExecute) Error() string

func (e *SignalErrExecute) Unwrap() error

type SignalErrInit ¶ added in v0.19.872

type SignalErrInit struct {
	Err error
}

SignalErrInit wraps an error that occurred during signal initialization.

func (e *SignalErrInit) Error() string

func (e *SignalErrInit) Unwrap() error

type SignalErrPanic ¶ added in v0.19.872

type SignalErrPanic struct {
	Value      any
	Phase      string // "init", "validate", or "execute"
	StackTrace string
}

SignalErrPanic wraps a panic that occurred during signal processing.

func NewSignalErrPanic(value any, phase string) *SignalErrPanic

func (e *SignalErrPanic) Error() string

type SignalErrValidate ¶ added in v0.19.872

type SignalErrValidate struct {
	Err error
}

SignalErrValidate wraps an error that occurred during signal validation.

func (e *SignalErrValidate) Error() string

func (e *SignalErrValidate) Unwrap() error

type SignalLifecycleActivities ¶ added in v0.19.894

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

func NewSignalLifecycleActivities(params SignalLifecycleActivitiesParams) *SignalLifecycleActivities

func (a *SignalLifecycleActivities) RunSignalLifecycleAfterPhase(ctx context.Context, req *RunSignalLifecycleAfterPhaseRequest) error

func (a *SignalLifecycleActivities) RunSignalLifecycleBeforePhase(ctx context.Context, req *RunSignalLifecycleBeforePhaseRequest) (*RunSignalLifecycleBeforePhaseResponse, error)

type SignalLifecycleActivitiesParams ¶ added in v0.19.894

type SignalLifecycleActivitiesParams struct {
	fx.In

	Hooks []SignalLifecycleHook `group:"signal_lifecycle_hooks"`
}

type SignalLifecycleContext ¶ added in v0.19.894

type SignalLifecycleContext struct {
	OrgID       string  `json:"org_id"`
	InstallID   *string `json:"install_id,omitempty"`
	ComponentID *string `json:"component_id,omitempty"`
	SandboxID   *string `json:"sandbox_id,omitempty"`
	Operation   string  `json:"operation"`
	Stage       string  `json:"stage,omitempty"`
}

type SignalLifecycleHook ¶ added in v0.19.894

type SignalLifecycleHook interface {
	Name() string
	Supports(event SignalPhaseEvent) bool
	BeforePhase(ctx context.Context, event SignalPhaseEvent) (BeforePhaseDecision, error)
	AfterPhase(ctx context.Context, event SignalPhaseEvent, outcome SignalPhaseOutcome) error
}

type SignalPhase ¶ added in v0.19.894

type SignalPhase string

const (
	SignalPhaseValidate SignalPhase = "validate"
	SignalPhaseExecute  SignalPhase = "execute"
	SignalPhaseCancel   SignalPhase = "cancel"
)

type SignalPhaseEvent ¶ added in v0.19.894

type SignalPhaseEvent struct {
	QueueSignalID string      `json:"queue_signal_id"`
	QueueID       string      `json:"queue_id"`
	SignalType    SignalType  `json:"signal_type"`
	OrgID         string      `json:"org_id"`
	Phase         SignalPhase `json:"phase"`

	InstallID   *string `json:"install_id,omitempty"`
	ComponentID *string `json:"component_id,omitempty"`
	SandboxID   *string `json:"sandbox_id,omitempty"`
	Operation   string  `json:"operation,omitempty"`
	Stage       string  `json:"stage,omitempty"`
}

type SignalPhaseOutcome ¶ added in v0.19.894

type SignalPhaseOutcome struct {
	Status     SignalStatus   `json:"status"`
	ErrMessage string         `json:"err_message,omitempty"`
	Duration   time.Duration  `json:"duration,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

type SignalStatus ¶ added in v0.19.894

type SignalStatus string

SignalStatus mirrors app.Status to avoid an import cycle between signal and app.

const (
	SignalStatusSuccess   SignalStatus = "success"
	SignalStatusError     SignalStatus = "error"
	SignalStatusCancelled SignalStatus = "cancelled"
)

type SignalType ¶

type SignalType string

type SignalWithAutoRetry ¶ added in v0.19.894

type SignalWithAutoRetry interface {
	AutoRetry() bool
}

SignalWithAutoRetry is implemented by signals that should automatically retry on failure without requiring user intervention. The conductor checks this after a step error and triggers a retry if the retry budget hasn't been exhausted.

type SignalWithCancel ¶ added in v0.19.872

type SignalWithCancel interface {
	Signal

	Cancel(ctx workflow.Context) error
}

SignalWithCancel is an optional interface that signals can implement to provide custom cancellation cleanup logic.

type SignalWithCloneSteps ¶ added in v0.19.894

type SignalWithCloneSteps interface {
	CloneSteps(originalStepName string) []CloneStepDef
}

SignalWithCloneSteps is implemented by signals whose steps require prerequisite steps when retried. For example, an apply signal may return a plan step + apply step so that retrying an apply re-runs the plan first.

type SignalWithFetchSteps ¶ added in v0.19.894

type SignalWithFetchSteps interface {
	Signal
	SignalWithUpdateHandlers
}

SignalWithFetchSteps marks a signal as a step generator. The signal must register a "FetchSteps" update handler that returns workflow steps. The conductor enqueues the signal, sends the "FetchSteps" update, and uses the returned steps instead of the hardcoded Generators map.

type SignalWithInit ¶ added in v0.19.872

type SignalWithInit interface {
	Signal

	Init(ctx workflow.Context) error
}

SignalWithInit is an optional interface that signals can implement to perform initialization after params have been applied but before validate/execute are called.

type SignalWithLifecycleContext ¶ added in v0.19.894

type SignalWithLifecycleContext interface {
	Signal

	LifecycleContext() SignalLifecycleContext
}

SignalWithLifecycleContext is an optional interface that signals can implement to provide rich context for lifecycle hook events.

type SignalWithMaxAutoRetries ¶ added in v0.19.894

type SignalWithMaxAutoRetries interface {
	MaxAutoRetries(ctx workflow.Context) int
}

SignalWithMaxAutoRetries is implemented by signals that want a separate limit for automatic retries (as opposed to user-initiated manual retries). When auto-retries are exhausted the step is marked as failed, but the user can still manually retry up to MaxRetries(). If not implemented, all retries up to MaxRetries() are automatic.

Accepts workflow.Context so implementations can fetch configuration dynamically (e.g., from the component config) rather than baking values into the signal at step creation time.

type SignalWithMaxRetries ¶ added in v0.19.894

type SignalWithMaxRetries interface {
	MaxRetries() int
}

SignalWithMaxRetries is implemented by signals that declare a custom maximum retry count. If not implemented, the default max retry count (DefaultMaxRetries) is used. This is the global ceiling for retries — when exhausted, no more retries of any kind.

type SignalWithNoOpCheck ¶ added in v0.19.894

type SignalWithNoOpCheck interface {
	IsNoOpCheckable() bool
}

SignalWithNoOpCheck is implemented by approval-type signals whose plan can have zero changes (noop). When the conductor detects a noop plan, it auto-skips both the approval step and its paired apply step.

type SignalWithOnApprove ¶ added in v0.19.894

type SignalWithOnApprove interface {
	OnApprove(ctx workflow.Context) error
}

SignalWithOnApprove is called when an approval step receives an "approve" response. Signals can implement this to perform side effects after approval is granted.

type SignalWithOnDeny ¶ added in v0.19.894

type SignalWithOnDeny interface {
	OnDeny(ctx workflow.Context) error
}

SignalWithOnDeny is called when an approval step receives a "deny" response. Signals can implement this to perform cleanup when approval is denied.

type SignalWithOnRetry ¶ added in v0.19.894

type SignalWithOnRetry interface {
	OnRetry(ctx workflow.Context) error
}

SignalWithOnRetry is called when an approval step receives a "retry plan" response. Signals can implement this to perform cleanup or preparation before the retry clone is created.

type SignalWithOnSkip ¶ added in v0.19.894

type SignalWithOnSkip interface {
	OnSkip(ctx workflow.Context) error
}

SignalWithOnSkip is called when an approval step receives a "skip" response (either skip-current or skip-current-and-dependents). Distinct from SignalWithSkipCleanup.OnSkipped which is called by the conductor when programmatically skipping a step.

type SignalWithParallelizable ¶ added in v0.19.894

type SignalWithParallelizable interface {
	IsParallelizable() bool
}

SignalWithParallelizable is implemented by signals whose steps can execute in parallel with other steps in the same group. By default, steps within a group execute sequentially. When true, the conductor may dispatch multiple steps concurrently.

type SignalWithParams ¶ added in v0.19.872

type SignalWithParams interface {
	Signal

	WithParams(*Params)
}

type SignalWithPolicyEvaluation ¶ added in v0.19.894

type SignalWithPolicyEvaluation interface {
	RequiresPolicyEvaluation() bool
}

SignalWithPolicyEvaluation is implemented by signals whose steps require policy evaluation before the approval proceeds. The conductor runs policy checks only when this interface is present and returns true.

type SignalWithQueue ¶ added in v0.19.894

type SignalWithQueue interface {
	Queue() string
}

SignalWithQueue is implemented by signals that target a specific workflow queue instead of the conductor's default target queue. The conductor reads this to route the inner signal to the correct queue.

type SignalWithRetryCount ¶ added in v0.19.894

type SignalWithRetryCount interface {
	SetRetryCount(retryIndex, groupRetryIndex int)
}

SignalWithRetryCount is implemented by signals that need to know their retry index at execution time. When a step is executed, the conductor calls SetRetryCount with the step's RetryIndex and GroupRetryIdx before Execute().

type SignalWithRetryGroup ¶ added in v0.19.894

type SignalWithRetryGroup interface {
	RetryGroup() bool
}

SignalWithRetryGroup is implemented by signals whose steps should retry as an entire group. When a retry is triggered for a step whose signal returns RetryGroup() == true, ALL steps sharing the same GroupIdx are cloned and re-executed, not just the individual step.

Mutually exclusive with parallel group execution — when a group has Parallel=true, RetryGroup is not supported and individual step retries are used instead.

type SignalWithSkipCleanup ¶ added in v0.19.894

type SignalWithSkipCleanup interface {
	OnSkipped(ctx workflow.Context) error
}

SignalWithSkipCleanup is implemented by signals that need to perform cleanup when their step is skipped or denied with "skip dependents". For example, sandbox plan signals mark all component deploy steps as skipped. The conductor calls OnSkipped after marking the step itself.

type SignalWithSkipGroup ¶ added in v0.19.894

type SignalWithSkipGroup interface {
	SkipGroup() bool
}

SignalWithSkipGroup is implemented by signals that want a "skip" approval response to skip the entire remaining group (DirectiveSkipGroup). When not implemented or when SkipGroup() returns false, a skip response only skips the current step and continues to the next step in the group (DirectiveContinue).

type SignalWithStepContext ¶ added in v0.19.872

type SignalWithStepContext interface {
	Signal

	SetStepContext(stepID, flowID string)
}

SignalWithStepContext is implemented by signals that need the workflow step ID and flow ID injected at step generation time, before the step is persisted to the database.

type SignalWithTimeout ¶ added in v0.19.903

type SignalWithTimeout interface {
	Timeout() time.Duration
}

SignalWithTimeout is implemented by signals that need a custom execution timeout. The returned duration is used as the ScheduleToCloseTimeout for the execute activity in the queue dispatcher. If not implemented, the default (2 hours) is used.

type SignalWithUpdateHandlers ¶ added in v0.19.894

type SignalWithUpdateHandlers interface {
	Signal

	RegisterUpdateHandlers(ctx workflow.Context) error
}

SignalWithUpdateHandlers is an optional interface that signals can implement to register custom Temporal update handlers on the handler workflow. Called after initializeState() but before the handler is marked ready, so handlers are available for the entire lifecycle of the signal.

type SleepAfter ¶ added in v0.19.894

type SleepAfter interface {
	SleepAfter() time.Duration
}

SleepAfter is an optional interface that signals can implement to control how long the handler workflow stays alive after execution. This grace period allows subsequent signals to reuse the running workflow via update-with-start instead of starting a new one. Defaults to 1 minute if not implemented. Return 0 to terminate the handler workflow immediately after execution.