api

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2026 License: Apache-2.0 Imports: 10 Imported by: 35

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInstanceNotFound  = errors.New("no such instance exists")
	ErrNotStarted        = errors.New("orchestration has not started")
	ErrNotCompleted      = errors.New("orchestration has not yet completed")
	ErrNoFailures        = errors.New("orchestration did not report failure details")
	ErrDuplicateInstance = errors.New("orchestration instance already exists")
	ErrIgnoreInstance    = errors.New("ignore creating orchestration instance")
	ErrTaskCancelled     = errors.New("task was cancelled")
	ErrStalled           = errors.New("workflow is stalled")

	EmptyInstanceID = InstanceID("")
)
View Source 
var ErrPropagationNotFound = errors.New("propagated history: not found")

Functions

func IsUnknownInstanceIDError added in v0.10.2 

func IsUnknownInstanceIDError(err error) bool

func IsUnknownTaskIDError added in v0.10.2 

func IsUnknownTaskIDError(err error) bool

func IsUnsupportedVersionError added in v0.11.0 

func IsUnsupportedVersionError(err error) bool

func NewHistoryPropagationScope added in v0.12.0 

func NewHistoryPropagationScope(opt PropagationOption) protos.HistoryPropagationScope

NewHistoryPropagationScope creates a HistoryPropagationScope from the given option. A nil option is treated as HISTORY_PROPAGATION_SCOPE_NONE.

func NewUnknownInstanceIDError added in v0.10.2 

func NewUnknownInstanceIDError(instanceID string) error

func NewUnknownTaskIDError added in v0.10.2 

func NewUnknownTaskIDError(instanceID string, taskID int32) error

func NewUnsupportedVersionError added in v0.11.0 

func NewUnsupportedVersionError() error

func OrchestrationMetadataIsComplete deprecated 

func OrchestrationMetadataIsComplete(o *protos.WorkflowMetadata) bool

Deprecated: Use WorkflowMetadataIsComplete instead.

func OrchestrationMetadataIsRunning deprecated 

func OrchestrationMetadataIsRunning(o *protos.WorkflowMetadata) bool

Deprecated: Use WorkflowMetadataIsRunning instead.

func ValidatePropagatedHistory added in v0.12.0 

func ValidatePropagatedHistory(ph *protos.PropagatedHistory) error

ValidatePropagatedHistory checks the structural shape of a wire-form PropagatedHistory before any decoding or trust decisions: each chunk must be non-nil and carry a non-empty appId. Signing-material checks (rawSignatures / signingCertChains alignment, cert chain-of-trust, signature verification) live in historysigning.VerifyPropagatedHistory, not here - this function is the lightweight structural gate.

func ValidateTaskRouter added in v0.13.0 

func ValidateTaskRouter(r *protos.TaskRouter) error

ValidateTaskRouter enforces the router invariant that cannot be checked inside a single option because options are order-independent: a target app namespace must be paired with a target app ID. Clients call this after applying all options. A nil router is valid.

func WorkflowMetadataIsComplete added in v0.12.0 

func WorkflowMetadataIsComplete(o *protos.WorkflowMetadata) bool

func WorkflowMetadataIsRunning added in v0.12.0 

func WorkflowMetadataIsRunning(o *protos.WorkflowMetadata) bool

Types

type ActivityResult added in v0.12.0 

type ActivityResult struct {
	Name      string // activity name
	Started   bool
	Completed bool
	Failed    bool
	Input     *wrapperspb.StringValue
	Output    *wrapperspb.StringValue
	Error     *protos.TaskFailureDetails
}

ActivityResult holds the status and data of a named activity.

type ChildWorkflowResult added in v0.12.0 

type ChildWorkflowResult struct {
	Name      string // child wf name
	Started   bool
	Completed bool
	Failed    bool
	Output    *wrapperspb.StringValue
	Error     *protos.TaskFailureDetails
}

ChildWorkflowResult holds the status and data of a named child workflow.

type FetchOrchestrationMetadataOptions deprecated 

type FetchOrchestrationMetadataOptions = FetchWorkflowMetadataOptions

Deprecated: Use FetchWorkflowMetadataOptions instead.

type FetchWorkflowMetadataOptions added in v0.12.0 

type FetchWorkflowMetadataOptions func(*protos.GetInstanceRequest)

GetWorkflowMetadataOptions is a set of options for fetching workflow metadata.

func WithFetchAppID added in v0.13.0 

func WithFetchAppID(appID string) FetchWorkflowMetadataOptions

WithFetchAppID targets the metadata fetch at the workflow instance owned by the app with the given app ID rather than the local app.

func WithFetchPayloads 

func WithFetchPayloads(fetchPayloads bool) FetchWorkflowMetadataOptions

WithFetchPayloads configures whether to load workflow inputs, outputs, and custom status values, which could be large.

type GetInstanceHistoryOptions added in v0.11.0 

type GetInstanceHistoryOptions func(*protos.GetInstanceHistoryRequest) error

type InstanceID 

type InstanceID string

InstanceID is a unique identifier for a workflow instance.

func (InstanceID) String added in v0.7.0 

func (i InstanceID) String() string

type ListInstanceIDsOptions added in v0.11.0 

type ListInstanceIDsOptions func(*protos.ListInstanceIDsRequest) error

func WithListInstanceIDsContinuationToken added in v0.11.0 

func WithListInstanceIDsContinuationToken(token string) ListInstanceIDsOptions

func WithListInstanceIDsPageSize added in v0.11.0 

func WithListInstanceIDsPageSize(pageSize uint32) ListInstanceIDsOptions

type NewOrchestrationOptions deprecated 

type NewOrchestrationOptions = NewWorkflowOptions

Deprecated: Use NewWorkflowOptions instead.

type NewWorkflowOptions added in v0.12.0 

type NewWorkflowOptions func(*protos.CreateInstanceRequest) error

NewWorkflowOptions configures options for starting a new workflow.

func WithAppID added in v0.13.0 

func WithAppID(appID string) NewWorkflowOptions

WithAppID targets the new workflow at the app with the given app ID rather than the local app. The target app's access policy governs whether the schedule is permitted.

func WithEnforceUniqueInstanceID added in v0.13.0 

func WithEnforceUniqueInstanceID() NewWorkflowOptions

WithEnforceUniqueInstanceID configures scheduling to fail if an instance with the same ID already exists, whether active or completed. The gRPC client surfaces the failure as a gRPC ALREADY_EXISTS status, while the in-process client returns an error wrapping api.ErrDuplicateInstance. Without it, an existing completed instance is restarted.

func WithInput 

func WithInput(input any) NewWorkflowOptions

WithInput configures an input for the workflow. The specified input must be serializable. Proto message types are serialized with protojson; all other types use encoding/json.

func WithInstanceID 

func WithInstanceID(id InstanceID) NewWorkflowOptions

WithInstanceID configures an explicit workflow instance ID. If not specified, a random UUID value will be used for the workflow instance ID.

func WithOrchestrationIdReusePolicy deprecated 

func WithOrchestrationIdReusePolicy(policy interface{}) NewWorkflowOptions

Deprecated: Use WithOrchestrationIdReusePolicy is no longer supported.

func WithRawInput 

func WithRawInput(rawInput *wrapperspb.StringValue) NewWorkflowOptions

WithRawInput configures an input for the workflow. The specified input must be a string.

func WithStartTime 

func WithStartTime(startTime time.Time) NewWorkflowOptions

WithStartTime configures a start time at which the workflow should start running. Note that the actual start time could be later than the specified start time if the task hub is under load or if the app is not running at the specified start time.

type OrchestrationStatus 

type OrchestrationStatus = protos.OrchestrationStatus
const (
	RUNTIME_STATUS_RUNNING          OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_RUNNING
	RUNTIME_STATUS_COMPLETED        OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_COMPLETED
	RUNTIME_STATUS_CONTINUED_AS_NEW OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_CONTINUED_AS_NEW
	RUNTIME_STATUS_FAILED           OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_FAILED
	RUNTIME_STATUS_CANCELED         OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_CANCELED
	RUNTIME_STATUS_TERMINATED       OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_TERMINATED
	RUNTIME_STATUS_PENDING          OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_PENDING
	RUNTIME_STATUS_SUSPENDED        OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_SUSPENDED
	RUNTIME_STATUS_STALLED          OrchestrationStatus = protos.OrchestrationStatus_ORCHESTRATION_STATUS_STALLED
)

type PropagatedHistory added in v0.12.0 

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

PropagatedHistory is the history propagated from a parent workflow to a child wf or activity

func PropagatedHistoryFromProto added in v0.12.0 

func PropagatedHistoryFromProto(ph *protos.PropagatedHistory) (*PropagatedHistory, error)

PropagatedHistoryFromProto converts a proto PropagatedHistory to the Go type. Each chunk owns its raw event bytes; this decodes them into typed HistoryEvents once and concatenates the per-chunk events into a single ordered slice for SDK consumption. This runs at the trust boundary (task/executor parsing inbound propagated history), so structural validation runs first via ValidatePropagatedHistory and the function returns a structured error rather than panicking on malformed input.

func (*PropagatedHistory) Events added in v0.12.0 

func (ph *PropagatedHistory) Events() []*protos.HistoryEvent

Events returns all propagated history events.

func (*PropagatedHistory) GetAppIDs added in v0.12.0 

func (ph *PropagatedHistory) GetAppIDs() []string

GetAppIDs returns the ordered, deduplicated list of app IDs in the history chain.

func (*PropagatedHistory) GetEventsByAppID added in v0.12.0 

func (ph *PropagatedHistory) GetEventsByAppID(appID string) []*protos.HistoryEvent

GetEventsByAppID returns only the events produced by the given app.

func (*PropagatedHistory) GetEventsByInstanceID added in v0.12.0 

func (ph *PropagatedHistory) GetEventsByInstanceID(instanceID string) []*protos.HistoryEvent

GetEventsByInstanceID returns only the events produced by the given workflow instance.

func (*PropagatedHistory) GetEventsByWorkflowName added in v0.12.0 

func (ph *PropagatedHistory) GetEventsByWorkflowName(name string) []*protos.HistoryEvent

GetEventsByWorkflowName returns only the events produced by workflows with the given name.

func (*PropagatedHistory) GetLastWorkflowByName added in v0.12.0 

func (ph *PropagatedHistory) GetLastWorkflowByName(name string) (*WorkflowResult, error)

GetLastWorkflowByName returns the last workflow chunk in the propagated history whose workflow name matches. When the chain contains the same workflow name more than once (eg a workflow that does ContinueAsNew, or a recursive child workflow) this returns the most-recent occurrence — equivalent to the last element of GetWorkflowsByName. Returns ErrPropagationNotFound when no chunk matches.

func (*PropagatedHistory) GetWorkflows added in v0.12.0 

func (ph *PropagatedHistory) GetWorkflows() []*WorkflowResult

GetWorkflows returns all workflow results in the propagated history chain, in execution order (ancestor first, then own)

func (*PropagatedHistory) GetWorkflowsByName added in v0.12.0 

func (ph *PropagatedHistory) GetWorkflowsByName(name string) []*WorkflowResult

GetWorkflowsByName returns all workflow results matching the given name, in execution order. Returns nil if none found.

func (*PropagatedHistory) Scope added in v0.12.0 

func (ph *PropagatedHistory) Scope() protos.HistoryPropagationScope

Scope returns the propagation scope used to produce this history.

type PropagationOption added in v0.12.0 

type PropagationOption func(*protos.HistoryPropagationScope)

PropagationOption is a functional option for configuring history propagation. Pass one of PropagateOwnHistory() or PropagateLineage().

func PropagateLineage added in v0.12.0 

func PropagateLineage() PropagationOption

PropagateLineage configures propagation to include the caller's own history events AND the full ancestor chain. Any propagated history this workflow received from its own parent is forwarded to the child, preserving the full chain of custody.

func PropagateOwnHistory added in v0.12.0 

func PropagateOwnHistory() PropagationOption

PropagateOwnHistory configures propagation to include the caller's own history events (activities, child workflows, timers, etc.). The child only sees events from the immediate parent, not the ancestor chain.

type PurgeOptions 

type PurgeOptions func(*protos.PurgeInstancesRequest) error

PurgeOptions is a set of options for purging a workflow.

func WithForcePurge added in v0.11.0 

func WithForcePurge(force bool) PurgeOptions

WithForcePurge configures whether to purge a workflow, regardless of its state or if it is processable/being processed. Highly discouraged to use unless you know what you are doing.

func WithPurgeAppID added in v0.13.0 

func WithPurgeAppID(appID string) PurgeOptions

WithPurgeAppID targets the purge at the workflow instance owned by the app with the given app ID rather than the local app. The purge is delegated to the target app, which honours the caller's recursive flag.

func WithRecursivePurge 

func WithRecursivePurge(recursive bool) PurgeOptions

WithRecursivePurge configures whether to purge all child workflows created by the target workflow.

type RaiseEventOptions 

type RaiseEventOptions func(*protos.RaiseEventRequest) error

RaiseEventOptions is a set of options for raising a workflow event.

func WithEventPayload 

func WithEventPayload(data any) RaiseEventOptions

WithEventPayload configures an event payload. The specified payload must be serializable.

func WithRaiseEventAppID added in v0.13.0 

func WithRaiseEventAppID(appID string) RaiseEventOptions

WithRaiseEventAppID targets the event at the workflow instance owned by the app with the given app ID rather than the local app.

func WithRawEventData 

func WithRawEventData(data *wrapperspb.StringValue) RaiseEventOptions

WithRawEventData configures an event payload that is a raw, unprocessed string (e.g. JSON data).

type RerunOptions added in v0.7.0 

type RerunOptions func(*protos.RerunWorkflowFromEventRequest) error

func WithRerunAppID added in v0.13.0 

func WithRerunAppID(appID string) RerunOptions

WithRerunAppID targets the rerun at the workflow instance owned by the app with the given app ID rather than the local app.

func WithRerunInput added in v0.7.0 

func WithRerunInput(input any) RerunOptions

func WithRerunNewInstanceID added in v0.7.0 

func WithRerunNewInstanceID(id InstanceID) RerunOptions

type ResumeOptions added in v0.13.0 

type ResumeOptions func(*protos.ResumeRequest) error

ResumeOptions is a set of options for resuming a workflow.

func WithResumeAppID added in v0.13.0 

func WithResumeAppID(appID string) ResumeOptions

WithResumeAppID targets the resumption at the workflow instance owned by the app with the given app ID rather than the local app.

type SuspendOptions added in v0.13.0 

type SuspendOptions func(*protos.SuspendRequest) error

SuspendOptions is a set of options for suspending a workflow.

func WithSuspendAppID added in v0.13.0 

func WithSuspendAppID(appID string) SuspendOptions

WithSuspendAppID targets the suspension at the workflow instance owned by the app with the given app ID rather than the local app.

type TerminateOptions 

type TerminateOptions func(*protos.TerminateRequest) error

TerminateOptions is a set of options for terminating a workflow.

func WithOutput 

func WithOutput(data any) TerminateOptions

WithOutput configures an output for the terminated workflow. The specified output must be serializable.

func WithRawOutput 

func WithRawOutput(data *wrapperspb.StringValue) TerminateOptions

WithRawOutput configures a raw, unprocessed output (i.e. pre-serialized) for the terminated workflow.

func WithRecursiveTerminate 

func WithRecursiveTerminate(recursive bool) TerminateOptions

WithRecursiveTerminate configures whether to terminate all child workflows created by the target workflow.

func WithTerminateAppID added in v0.13.0 

func WithTerminateAppID(appID string) TerminateOptions

WithTerminateAppID targets the termination at the workflow instance owned by the app with the given app ID rather than the local app.

type UnknownInstanceIDError added in v0.10.2 

type UnknownInstanceIDError struct {
	InstanceID string
}

func (*UnknownInstanceIDError) Error added in v0.10.2 

func (e *UnknownInstanceIDError) Error() string

type UnknownTaskIDError added in v0.10.2 

type UnknownTaskIDError struct {
	TaskID     int32
	InstanceID string
}

func (*UnknownTaskIDError) Error added in v0.10.2 

func (e *UnknownTaskIDError) Error() string

type UnsupportedVersionError added in v0.11.0 

type UnsupportedVersionError struct{}

func (*UnsupportedVersionError) Error added in v0.11.0 

func (e *UnsupportedVersionError) Error() string

type WorkflowResult added in v0.12.0 

type WorkflowResult struct {
	Found      bool
	InstanceID string
	AppID      string
	Name       string // wf name
	// contains filtered or unexported fields
}

WorkflowResult is a scoped view of a single workflow's chunk in propagated history. Use GetLastActivityByName or GetLastChildWorkflowByName to query specific items.

func (WorkflowResult) GetActivitiesByName added in v0.12.0 

func (wr WorkflowResult) GetActivitiesByName(name string) []*ActivityResult

GetActivitiesByName returns all activity results matching the given name, in execution order. Useful when the same activity is called multiple times (ex retries/loops). Returns nil if none found.

func (WorkflowResult) GetChildWorkflowsByName added in v0.12.0 

func (wr WorkflowResult) GetChildWorkflowsByName(name string) []*ChildWorkflowResult

GetChildWorkflowsByName returns all child workflow results matching the given name, in execution order. Returns nil if none found.

func (WorkflowResult) GetLastActivityByName added in v0.12.0 

func (wr WorkflowResult) GetLastActivityByName(name string) (*ActivityResult, error)

GetLastActivityByName returns the last activity scheduled in this workflow's chunk whose name matches. The returned result reflects the most recent invocation; for SDK-driven retries (which reuse the activity name and taskExecutionId) this is the final attempt. Returns ErrPropagationNotFound when the workflow result is empty or no activity event matches.

func (WorkflowResult) GetLastChildWorkflowByName added in v0.12.0 

func (wr WorkflowResult) GetLastChildWorkflowByName(name string) (*ChildWorkflowResult, error)

GetLastChildWorkflowByName returns the last child workflow scheduled in this workflow's chunk whose name matches. When the same child workflow name is invoked more than once from this parent (in a loop), this returns the most recent invocation — equivalent to the last element of GetChildWorkflowsByName. Returns ErrPropagationNotFound when the workflow result is empty or no child workflow event matches.

Source Files

View all Source files

Directories

Path Synopsis

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.