api

package
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: May 26, 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 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 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 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 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 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 WithRerunInput added in v0.7.0 

func WithRerunInput(input any) RerunOptions

func WithRerunNewInstanceID added in v0.7.0 

func WithRerunNewInstanceID(id InstanceID) RerunOptions

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.

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.