Documentation
¶
Overview ¶
Package uws1 provides Go types for parsing and generating Udon Workflow Specification (UWS) 1.x documents.
The types in this package are standalone data-interchange types with JSON serialization and struct tags for YAML/HCL conversion helpers. They support source-bound workflow operations, execution control (depends_on, when, for_each, wait, workflow, parallel_group), structural constructs (parallel, switch, merge, loop), triggers, and JSON specification extensions (x-* fields). Use the convert package for extension-preserving YAML conversion and HCL helper APIs.
Package uws1 provides Go types for parsing and generating Udon Workflow Specification (UWS) 1.x documents.
Index ¶
- Constants
- func AllowsCases(typeName string) bool
- func AllowsDefault(typeName string) bool
- func IsStructuralResultKind(kind string) bool
- func IsWorkflowType(typeName string) bool
- func RequiresDependsOnForMerge(typeName string) bool
- func RequiresItems(typeName string) bool
- func RequiresWait(typeName string) bool
- func WithExecutionContext(ctx context.Context, state *ExecutionContext) context.Context
- type AwaitTimeoutError
- type Case
- type CaseFields
- type Components
- type ContentTrust
- type ContentTrustLevel
- type Criterion
- type CriterionExpressionType
- type CurrentExecutionContext
- type Document
- func (d *Document) DispatchTrigger(ctx context.Context, triggerID string, output int, payload any) error
- func (d *Document) Execute(ctx context.Context) error
- func (d *Document) ExecutionRecords() map[string]ExecutionRecord
- func (d *Document) MarshalHCL() ([]byte, error)
- func (d Document) MarshalJSON() ([]byte, error)
- func (d *Document) SetRuntime(r Runtime)
- func (d *Document) UnmarshalHCL(data []byte, labels ...string) error
- func (d *Document) UnmarshalJSON(data []byte) error
- func (d *Document) Validate() error
- func (d *Document) ValidateExecutable() error
- func (d *Document) ValidateExecutionEntrypoint() error
- func (d *Document) ValidateResult() *ValidationResult
- type ExecutionContext
- type ExecutionOptions
- type ExecutionRecord
- type FailureAction
- type Idempotency
- type Info
- type IterationContext
- type Operation
- func (o *Operation) Execute(ctx context.Context, d *Document) error
- func (o *Operation) ExtensionProfile() string
- func (o *Operation) HasCompleteOpenAPIBinding() bool
- func (o *Operation) HasCompleteSourceBinding() bool
- func (o *Operation) HasOpenAPIBinding() bool
- func (o *Operation) HasSourceBinding() bool
- func (o *Operation) IsExtensionOwned() bool
- func (o Operation) MarshalJSON() ([]byte, error)
- func (o *Operation) UnmarshalHCL(data []byte, labels ...string) error
- func (o *Operation) UnmarshalJSON(data []byte) error
- type OperationContentTrust
- type OperationEffect
- type OperationExecutionFields
- type Orchestrator
- func (o *Orchestrator) Execute(ctx context.Context) error
- func (o *Orchestrator) ExecuteStep(ctx context.Context, step *Step) error
- func (o *Orchestrator) ExecuteTrigger(ctx context.Context, triggerID string, output int, payload any) error
- func (o *Orchestrator) ExecuteWorkflow(ctx context.Context, wf *Workflow) error
- type ParamSchema
- type PendingStep
- type RunnableExecutionFields
- type Runtime
- type RuntimeWithResult
- type SourceDescription
- type SourceDescriptionType
- type Step
- type StepExecutionFields
- type StructuralFields
- type StructuralResult
- type SuccessAction
- type Trigger
- type TriggerExecutionContext
- type TriggerFields
- type TriggerRoute
- type TriggerRouteFields
- type ValidationError
- type ValidationResult
- type Workflow
- type WorkflowContentTrust
- type WorkflowExecutionFields
Constants ¶
const ( WorkflowTypeSequence = "sequence" WorkflowTypeParallel = "parallel" WorkflowTypeSwitch = "switch" WorkflowTypeMerge = "merge" WorkflowTypeLoop = "loop" WorkflowTypeAwait = "await" )
const ( StructuralResultKindSwitch = WorkflowTypeSwitch StructuralResultKindMerge = WorkflowTypeMerge StructuralResultKindLoop = WorkflowTypeLoop )
const ExtensionOperationProfile = "x-uws-operation-profile"
ExtensionOperationProfile is the x-* extension key that names the implementation profile for an extension-owned operation. Operations without a source binding must carry this extension to be executable.
Variables ¶
This section is empty.
Functions ¶
func AllowsCases ¶
AllowsCases reports whether the workflow type permits case blocks.
func AllowsDefault ¶
AllowsDefault reports whether the workflow type permits default blocks.
func IsStructuralResultKind ¶
IsStructuralResultKind reports whether kind names a supported structural result source kind.
func IsWorkflowType ¶
IsWorkflowType reports whether typeName names a standard structural workflow type.
func RequiresDependsOnForMerge ¶
RequiresDependsOnForMerge reports whether the workflow type requires dependsOn to name upstream constructs.
func RequiresItems ¶
RequiresItems reports whether the workflow type requires an items selector.
func RequiresWait ¶
RequiresWait reports whether the workflow type requires a wait selector.
func WithExecutionContext ¶
func WithExecutionContext(ctx context.Context, state *ExecutionContext) context.Context
WithExecutionContext returns a new context carrying the given execution state.
Types ¶
type AwaitTimeoutError ¶
AwaitTimeoutError reports that an await construct exceeded the executor's configured internal timeout.
func (*AwaitTimeoutError) Error ¶
func (e *AwaitTimeoutError) Error() string
func (*AwaitTimeoutError) Is ¶
func (e *AwaitTimeoutError) Is(target error) bool
type Case ¶
type Case struct {
CaseFields
Body map[string]any `json:"body,omitempty" yaml:"body,omitempty" hcl:"body,optional"`
Steps []*Step `json:"steps,omitempty" yaml:"steps,omitempty" hcl:"step,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Case describes a single branch within a switch construct.
func (Case) MarshalJSON ¶
func (*Case) UnmarshalJSON ¶
type CaseFields ¶
type CaseFields struct {
Name string `json:"name" yaml:"name" hcl:"name,label"`
When string `json:"when,omitempty" yaml:"when,omitempty" hcl:"when,optional"`
}
CaseFields captures format-agnostic switch-branch metadata.
type Components ¶
type Components struct {
// Variables is an open-shape map of JSON-compatible values. Keys follow the
// historical componentNamePattern before UWS 1.10; 1.10+ additionally
// requires expression-addressable names.
Variables map[string]any `json:"variables,omitempty" yaml:"variables,omitempty" hcl:"variables,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Components holds reusable objects scoped to the UWS document.
func (Components) MarshalJSON ¶
func (c Components) MarshalJSON() ([]byte, error)
func (*Components) UnmarshalHCL ¶
func (c *Components) UnmarshalHCL(data []byte, labels ...string) error
func (*Components) UnmarshalJSON ¶
func (c *Components) UnmarshalJSON(data []byte) error
type ContentTrust ¶
type ContentTrust struct {
SourceDescriptions map[string]ContentTrustLevel `json:"sourceDescriptions,omitempty" yaml:"sourceDescriptions,omitempty" hcl:"sourceDescriptions,optional"`
Operations map[string]*OperationContentTrust `json:"operations,omitempty" yaml:"operations,omitempty" hcl:"operations,optional"`
Triggers map[string]ContentTrustLevel `json:"triggers,omitempty" yaml:"triggers,omitempty" hcl:"triggers,optional"`
Workflows map[string]*WorkflowContentTrust `json:"workflows,omitempty" yaml:"workflows,omitempty" hcl:"workflows,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
ContentTrust contains optional, reviewable provenance declarations for source descriptions, operations, triggers, and workflow entry inputs.
func (ContentTrust) MarshalJSON ¶
func (c ContentTrust) MarshalJSON() ([]byte, error)
func (*ContentTrust) UnmarshalHCL ¶
func (c *ContentTrust) UnmarshalHCL(data []byte, labels ...string) error
func (*ContentTrust) UnmarshalJSON ¶
func (c *ContentTrust) UnmarshalJSON(data []byte) error
type ContentTrustLevel ¶
type ContentTrustLevel string
ContentTrustLevel describes the reviewed integrity provenance of content. It is intentionally independent of the value's runtime type or capability.
const ( ContentTrustUnknown ContentTrustLevel = "unknown" ContentTrustTrusted ContentTrustLevel = "trusted" ContentTrustUntrusted ContentTrustLevel = "untrusted" )
type Criterion ¶
type Criterion struct {
Condition string `json:"condition" yaml:"condition" hcl:"condition"`
Type CriterionExpressionType `json:"type,omitempty" yaml:"type,omitempty" hcl:"type,optional"`
Context string `json:"context,omitempty" yaml:"context,omitempty" hcl:"context,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Criterion describes a success or failure condition for an operation.
func (Criterion) MarshalJSON ¶
func (*Criterion) UnmarshalHCL ¶
func (*Criterion) UnmarshalJSON ¶
type CriterionExpressionType ¶
type CriterionExpressionType string
CriterionExpressionType defines how a criterion condition is evaluated.
const ( CriterionSimple CriterionExpressionType = "simple" CriterionRegex CriterionExpressionType = "regex" CriterionJSONPath CriterionExpressionType = "jsonpath" CriterionXPath CriterionExpressionType = "xpath" )
type CurrentExecutionContext ¶
type CurrentExecutionContext struct {
Key string
ID string
Kind string
ResponseID string
Outputs map[string]any
}
CurrentExecutionContext describes the construct currently being evaluated.
type Document ¶
type Document struct {
UWS string `json:"uws" yaml:"uws" hcl:"uws"`
Info *Info `json:"info" yaml:"info" hcl:"info,block"`
SourceDescriptions []*SourceDescription `json:"sourceDescriptions,omitempty" yaml:"sourceDescriptions,omitempty" hcl:"sourceDescription,block"`
// Variables values remain open-shape JSON. Names use the historical schema
// rules before UWS 1.10; 1.10+ restricts names to those addressable by the
// runtime-expression grammar.
Variables map[string]any `json:"variables,omitempty" yaml:"variables,omitempty" hcl:"variables,optional"`
Operations []*Operation `json:"operations" yaml:"operations" hcl:"operation,block"`
Workflows []*Workflow `json:"workflows,omitempty" yaml:"workflows,omitempty" hcl:"workflow,block"`
Triggers []*Trigger `json:"triggers,omitempty" yaml:"triggers,omitempty" hcl:"trigger,block"`
Results []*StructuralResult `json:"results,omitempty" yaml:"results,omitempty" hcl:"result,block"`
Components *Components `json:"components,omitempty" yaml:"components,omitempty" hcl:"components,block"`
ContentTrust *ContentTrust `json:"contentTrust,omitempty" yaml:"contentTrust,omitempty" hcl:"contentTrust,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
// Runtime is the specialized executor bound to this document. Runtime
// rebinding and execution-record reads are not synchronized; callers that
// share a document across goroutines must provide their own synchronization.
Runtime Runtime `json:"-" yaml:"-" hcl:"-"`
// ExecutionOptions are executor-owned knobs and are not part of the UWS wire
// contract.
ExecutionOptions ExecutionOptions `json:"-" yaml:"-" hcl:"-"`
// contains filtered or unexported fields
}
Document is the root object of a UWS 1.x document.
func (*Document) DispatchTrigger ¶
func (d *Document) DispatchTrigger(ctx context.Context, triggerID string, output int, payload any) error
DispatchTrigger routes one trigger event into the document's executable targets using the bound runtime. It mutates execution state and is not safe to run concurrently on the same document unless the caller synchronizes access.
func (*Document) Execute ¶
Execute executes the document using the bound runtime. It mutates execution state and is not safe to run concurrently on the same document unless the caller synchronizes access.
func (*Document) ExecutionRecords ¶
func (d *Document) ExecutionRecords() map[string]ExecutionRecord
ExecutionRecords returns the last orchestrator execution snapshot captured on the document. The returned map is a defensive copy. It is not safe to call concurrently with Execute, DispatchTrigger, or SetRuntime unless the caller synchronizes access to the document.
func (*Document) MarshalHCL ¶
MarshalHCL marshals a UWS document to native UWS HCL. Equivalent documents produce byte-stable output, including maps and extension payloads.
func (Document) MarshalJSON ¶
func (*Document) SetRuntime ¶
SetRuntime binds a specialized runtime to the document. It is not safe to call concurrently with Execute, DispatchTrigger, or ExecutionRecords unless the caller synchronizes access to the document.
func (*Document) UnmarshalHCL ¶
UnmarshalHCL unmarshals native UWS HCL into a document.
func (*Document) UnmarshalJSON ¶
func (*Document) Validate ¶
Validate runs the semantic validation layer and returns the first error as a single error, or nil if the document passes.
Validate assumes the document has already been checked against the matching versions/1.x JSON Schema via a JSON Schema validator. The schema layer enforces structural shape (required fields, enum values, patterns, uniqueness of array items). Validate layers semantic rules on top: duplicate identifiers, reference integrity, binding mutual exclusivity, structural-type field constraints, and dependsOn cycles. Callers that invoke Validate without the schema pre-pass bypass the structural checks.
Use ValidateResult when callers need path-tagged errors instead of a single collapsed error.
func (*Document) ValidateExecutable ¶
ValidateExecutable checks whether the current core executor can run the document without relying on ambiguous identifiers or unsupported semantics.
func (*Document) ValidateExecutionEntrypoint ¶
ValidateExecutionEntrypoint checks the additional document-level requirement for Document.Execute(): there must be one executable entry workflow.
func (*Document) ValidateResult ¶
func (d *Document) ValidateResult() *ValidationResult
ValidateResult runs the semantic validation layer and returns every error it finds, each tagged with a structured Path. See Validate for the layering contract between this method and the versions/1.x JSON Schema pre-pass.
type ExecutionContext ¶
type ExecutionContext struct {
Iteration *IterationContext
Trigger *TriggerExecutionContext
Inputs map[string]any
Records map[string]ExecutionRecord
Current *CurrentExecutionContext
// WorkflowScope namespaces nested records for an individual workflow call.
WorkflowScope string
// WorkflowStack detects recursive workflow calls before they wait on their
// own in-flight execution record.
WorkflowStack []string
}
ExecutionContext carries runtime-only orchestration state into runtime hooks.
func ExecutionContextFromContext ¶
func ExecutionContextFromContext(ctx context.Context) (*ExecutionContext, bool)
ExecutionContextFromContext returns the current execution state, if any.
type ExecutionOptions ¶
type ExecutionOptions struct {
// AwaitTimeout bounds await polling inside the core orchestrator. Zero means
// no internal timeout; await still terminates when the context is canceled.
AwaitTimeout time.Duration `json:"-" yaml:"-" hcl:"-"`
// AwaitPollInterval is the interval between wait-expression evaluations in
// await constructs. Zero means use the default (200ms).
AwaitPollInterval time.Duration `json:"-" yaml:"-" hcl:"-"`
}
ExecutionOptions carries executor-owned behavior that is intentionally not serialized into the UWS wire format.
type ExecutionRecord ¶
type ExecutionRecord struct {
ID string
Kind string
Status string
Error string
Result any
Outputs map[string]any
}
ExecutionRecord is the orchestrator-owned summary of one construct execution.
type FailureAction ¶
type FailureAction struct {
Name string `json:"name" yaml:"name" hcl:"name,label"`
Type string `json:"type" yaml:"type" hcl:"type"`
WorkflowID string `json:"workflowId,omitempty" yaml:"workflowId,omitempty" hcl:"workflowId,optional"`
StepID string `json:"stepId,omitempty" yaml:"stepId,omitempty" hcl:"stepId,optional"`
RetryAfter float64 `json:"retryAfter,omitempty" yaml:"retryAfter,omitempty" hcl:"retryAfter,optional"`
RetryLimit int `json:"retryLimit,omitempty" yaml:"retryLimit,omitempty" hcl:"retryLimit,optional"`
Criteria []*Criterion `json:"criteria,omitempty" yaml:"criteria,omitempty" hcl:"criterion,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
FailureAction describes what to do when an operation fails. Type is one of: end, goto, retry.
func (FailureAction) MarshalJSON ¶
func (f FailureAction) MarshalJSON() ([]byte, error)
func (*FailureAction) UnmarshalHCL ¶
func (f *FailureAction) UnmarshalHCL(data []byte, labels ...string) error
func (*FailureAction) UnmarshalJSON ¶
func (f *FailureAction) UnmarshalJSON(data []byte) error
type Idempotency ¶
type Idempotency struct {
Key string `json:"key" yaml:"key" hcl:"key"`
OnConflict string `json:"onConflict,omitempty" yaml:"onConflict,omitempty" hcl:"onConflict,optional"`
TTL *float64 `json:"ttl,omitempty" yaml:"ttl,omitempty" hcl:"ttl,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Idempotency declares workflow-run de-duplication metadata.
func (Idempotency) MarshalJSON ¶
func (i Idempotency) MarshalJSON() ([]byte, error)
func (*Idempotency) UnmarshalHCL ¶
func (i *Idempotency) UnmarshalHCL(data []byte, labels ...string) error
func (*Idempotency) UnmarshalJSON ¶
func (i *Idempotency) UnmarshalJSON(data []byte) error
type Info ¶
type Info struct {
Title string `json:"title" yaml:"title" hcl:"title"`
Summary string `json:"summary,omitempty" yaml:"summary,omitempty" hcl:"summary,optional"`
Description string `json:"description,omitempty" yaml:"description,omitempty" hcl:"description,optional"`
Version string `json:"version" yaml:"version" hcl:"version"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Info provides metadata about the UWS document.
func (Info) MarshalJSON ¶
func (*Info) UnmarshalJSON ¶
type IterationContext ¶
IterationContext describes the current orchestrator-owned iteration scope.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId" yaml:"operationId" hcl:"operationId,label"`
SourceDescription string `json:"sourceDescription,omitempty" yaml:"sourceDescription,omitempty" hcl:"sourceDescription,optional"`
SourceOperationID string `json:"sourceOperationId,omitempty" yaml:"sourceOperationId,omitempty" hcl:"sourceOperationId,optional"`
SourceOperationRef string `json:"sourceOperationRef,omitempty" yaml:"sourceOperationRef,omitempty" hcl:"sourceOperationRef,optional"`
OpenAPIOperationID string `json:"openapiOperationId,omitempty" yaml:"openapiOperationId,omitempty" hcl:"openapiOperationId,optional"`
OpenAPIOperationRef string `json:"openapiOperationRef,omitempty" yaml:"openapiOperationRef,omitempty" hcl:"openapiOperationRef,optional"`
Description string `json:"description,omitempty" yaml:"description,omitempty" hcl:"description,optional"`
Request map[string]any `json:"request,omitempty" yaml:"request,omitempty" hcl:"request,optional"`
Effect OperationEffect `json:"effect,omitempty" yaml:"effect,omitempty" hcl:"effect,optional"`
OperationExecutionFields
// Success criteria and action handlers
SuccessCriteria []*Criterion `json:"successCriteria,omitempty" yaml:"successCriteria,omitempty" hcl:"successCriterion,block"`
OnFailure []*FailureAction `json:"onFailure,omitempty" yaml:"onFailure,omitempty" hcl:"onFailure,block"`
OnSuccess []*SuccessAction `json:"onSuccess,omitempty" yaml:"onSuccess,omitempty" hcl:"onSuccess,block"`
// Outputs map friendly names to runtime expressions.
Outputs map[string]string `json:"outputs,omitempty" yaml:"outputs,omitempty" hcl:"outputs,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Operation describes a UWS-local operation bound to a source operation.
func (*Operation) ExtensionProfile ¶
ExtensionProfile returns the normalized operation profile marker used by extension-owned operations.
func (*Operation) HasCompleteOpenAPIBinding ¶
HasCompleteOpenAPIBinding reports whether the operation has a source description, exactly one legacy openapiOperation* selector, and no generic sourceOperation* selector.
func (*Operation) HasCompleteSourceBinding ¶
HasCompleteSourceBinding reports whether the operation has a source description, exactly one generic source operation selector, and no legacy OpenAPI selector.
func (*Operation) HasOpenAPIBinding ¶
HasOpenAPIBinding reports whether the operation includes any legacy openapiOperation* selector field. A partial legacy binding is still a binding and will be rejected by validation.
OpenAPI sources that use the UWS 1.2 sourceOperation* selectors are source bindings, but this compatibility helper intentionally reports only the legacy OpenAPI selector fields.
func (*Operation) HasSourceBinding ¶
HasSourceBinding reports whether the operation includes any source binding field. A partial binding is still a binding and will be rejected by validation.
func (*Operation) IsExtensionOwned ¶
IsExtensionOwned reports whether this operation is intentionally owned by an extension profile rather than a source operation binding. Source-bound operations may still carry profile metadata, but this is true only for extension-owned operations with no source binding.
func (Operation) MarshalJSON ¶
func (*Operation) UnmarshalHCL ¶
func (*Operation) UnmarshalJSON ¶
type OperationContentTrust ¶
type OperationContentTrust struct {
Default ContentTrustLevel `json:"default,omitempty" yaml:"default,omitempty" hcl:"default,optional"`
Outputs map[string]ContentTrustLevel `json:"outputs,omitempty" yaml:"outputs,omitempty" hcl:"outputs,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
OperationContentTrust declares an operation-wide default and optional overrides for named operation outputs.
func (OperationContentTrust) MarshalJSON ¶
func (c OperationContentTrust) MarshalJSON() ([]byte, error)
func (*OperationContentTrust) UnmarshalHCL ¶
func (c *OperationContentTrust) UnmarshalHCL(data []byte, labels ...string) error
func (*OperationContentTrust) UnmarshalJSON ¶
func (c *OperationContentTrust) UnmarshalJSON(data []byte) error
type OperationEffect ¶
type OperationEffect string
OperationEffect is the author's classification of an operation's expected side effects. An omitted Effect is unknown; consumers must not infer an effect from a source operation's HTTP method.
const ( OperationEffectRead OperationEffect = "read" OperationEffectWrite OperationEffect = "write" OperationEffectUnknown OperationEffect = "unknown" )
type OperationExecutionFields ¶
type OperationExecutionFields struct {
DependsOn []string `json:"dependsOn,omitempty" yaml:"dependsOn,omitempty" hcl:"dependsOn,optional"`
When string `json:"when,omitempty" yaml:"when,omitempty" hcl:"when,optional"`
ForEach string `json:"forEach,omitempty" yaml:"forEach,omitempty" hcl:"forEach,optional"`
Wait string `json:"wait,omitempty" yaml:"wait,omitempty" hcl:"wait,optional"`
Timeout *float64 `json:"timeout,omitempty" yaml:"timeout,omitempty" hcl:"timeout,optional"`
ParallelGroup string `json:"parallelGroup,omitempty" yaml:"parallelGroup,omitempty" hcl:"parallelGroup,optional"`
}
OperationExecutionFields captures execution controls on leaf operations.
type Orchestrator ¶
type Orchestrator struct {
Document *Document
Runtime Runtime
// contains filtered or unexported fields
}
Orchestrator provides the abstract orchestration logic for walking the workflow graph and managing structural state transitions.
func NewOrchestrator ¶
func NewOrchestrator(doc *Document, runtime Runtime) *Orchestrator
NewOrchestrator creates a new Orchestrator for the given document and runtime.
func (*Orchestrator) Execute ¶
func (o *Orchestrator) Execute(ctx context.Context) error
Execute executes the main workflow of the document.
func (*Orchestrator) ExecuteStep ¶
func (o *Orchestrator) ExecuteStep(ctx context.Context, step *Step) error
ExecuteStep executes a single step.
func (*Orchestrator) ExecuteTrigger ¶
func (o *Orchestrator) ExecuteTrigger(ctx context.Context, triggerID string, output int, payload any) error
ExecuteTrigger resolves a trigger event to its routed execution targets.
func (*Orchestrator) ExecuteWorkflow ¶
func (o *Orchestrator) ExecuteWorkflow(ctx context.Context, wf *Workflow) error
ExecuteWorkflow executes a structural workflow.
type ParamSchema ¶
type ParamSchema struct {
Type string `json:"type,omitempty" yaml:"type,omitempty" hcl:"type,optional"`
Format string `json:"format,omitempty" yaml:"format,omitempty" hcl:"format,optional"`
Ref string `json:"$ref,omitempty" yaml:"$ref,omitempty" hcl:"_ref,optional"`
Properties map[string]*ParamSchema `json:"properties,omitempty" yaml:"properties,omitempty" hcl:"properties,optional"`
Required []string `json:"required,omitempty" yaml:"required,omitempty" hcl:"required,optional"`
Items *ParamSchema `json:"items,omitempty" yaml:"items,omitempty" hcl:"items,block"`
AllOf []*ParamSchema `json:"allOf,omitempty" yaml:"allOf,omitempty" hcl:"allOf,block"`
OneOf []*ParamSchema `json:"oneOf,omitempty" yaml:"oneOf,omitempty" hcl:"oneOf,block"`
AnyOf []*ParamSchema `json:"anyOf,omitempty" yaml:"anyOf,omitempty" hcl:"anyOf,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
ParamSchema describes the schema of a parameter, payload, or response (recursive).
func (ParamSchema) MarshalJSON ¶
func (p ParamSchema) MarshalJSON() ([]byte, error)
func (*ParamSchema) UnmarshalHCL ¶
func (p *ParamSchema) UnmarshalHCL(data []byte, labels ...string) error
func (*ParamSchema) UnmarshalJSON ¶
func (p *ParamSchema) UnmarshalJSON(data []byte) error
type PendingStep ¶
type PendingStep struct {
Purpose string `json:"purpose" yaml:"purpose" hcl:"purpose,optional"`
Inputs *ParamSchema `json:"inputs" yaml:"inputs" hcl:"inputs,block"`
Outputs *ParamSchema `json:"outputs" yaml:"outputs" hcl:"outputs,block"`
Effect OperationEffect `json:"effect" yaml:"effect" hcl:"effect,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
PendingStep declares the purpose, input and output schemas, and expected effect of a step that is not yet bound to an executable operation. The schemas are contracts, not runtime input values or output expressions.
func (PendingStep) MarshalJSON ¶
func (p PendingStep) MarshalJSON() ([]byte, error)
func (*PendingStep) UnmarshalHCL ¶
func (p *PendingStep) UnmarshalHCL(data []byte, labels ...string) error
func (*PendingStep) UnmarshalJSON ¶
func (p *PendingStep) UnmarshalJSON(data []byte) error
type RunnableExecutionFields ¶
type RunnableExecutionFields = StepExecutionFields
RunnableExecutionFields is the compatibility name for nested-step execution controls. New code should use StepExecutionFields or OperationExecutionFields depending on which UWS object is being modeled.
type Runtime ¶
type Runtime interface {
// ExecuteLeaf executes a single leaf operation.
ExecuteLeaf(ctx context.Context, op *Operation) error
// EvaluateExpression evaluates a UWS runtime expression against the
// current execution context.
EvaluateExpression(ctx context.Context, expr string) (any, error)
// ResolveItems resolves the items/forEach expression for iterative constructs.
ResolveItems(ctx context.Context, itemsExpr string) ([]any, error)
}
Runtime defines the interface that specialized executors must implement to provide leaf operation execution and expression evaluation for a UWS document.
type RuntimeWithResult ¶
type RuntimeWithResult interface {
ExecuteLeafWithResult(ctx context.Context, op *Operation) (any, error)
}
RuntimeWithResult is an optional additive runtime capability. The orchestrator uses it when present so the returned leaf response is available to response expressions and execution records. Existing Runtime implementations remain valid and continue to use Runtime.ExecuteLeaf. Implementations should return JSON-compatible values; a non-nil JSON null representation such as json.RawMessage("null") distinguishes a JSON null response from an unavailable response.
type SourceDescription ¶
type SourceDescription struct {
Name string `json:"name" yaml:"name" hcl:"name,label"`
URL string `json:"url" yaml:"url" hcl:"url"`
Type SourceDescriptionType `json:"type,omitempty" yaml:"type,omitempty" hcl:"type,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
SourceDescription identifies a source document that operations reference.
func (*SourceDescription) EffectiveType ¶
func (s *SourceDescription) EffectiveType() SourceDescriptionType
EffectiveType returns the source type used for validation and execution. Omitted sourceDescription.type defaults to openapi for backward compatibility.
func (SourceDescription) MarshalJSON ¶
func (s SourceDescription) MarshalJSON() ([]byte, error)
func (*SourceDescription) UnmarshalHCL ¶
func (s *SourceDescription) UnmarshalHCL(data []byte, labels ...string) error
func (*SourceDescription) UnmarshalJSON ¶
func (s *SourceDescription) UnmarshalJSON(data []byte) error
type SourceDescriptionType ¶
type SourceDescriptionType string
SourceDescriptionType represents the type of source description.
const ( SourceDescriptionTypeOpenAPI SourceDescriptionType = "openapi" SourceDescriptionTypeGoogleDiscovery SourceDescriptionType = "google-discovery" SourceDescriptionTypeAWSSmithy SourceDescriptionType = "aws-smithy" SourceDescriptionTypeAsyncAPI SourceDescriptionType = "asyncapi" SourceDescriptionTypeGraphQL SourceDescriptionType = "graphql" SourceDescriptionTypeOpenRPC SourceDescriptionType = "openrpc" SourceDescriptionTypeGRPCProtobuf SourceDescriptionType = "grpc-protobuf" SourceDescriptionTypeOData SourceDescriptionType = "odata" SourceDescriptionTypeBrowserProfile SourceDescriptionType = "browser-profile" SourceDescriptionTypeAnsibleModule SourceDescriptionType = "ansible-module" )
type Step ¶
type Step struct {
StepID string `json:"stepId" yaml:"stepId" hcl:"stepId,label"`
Type string `json:"type,omitempty" yaml:"type,omitempty" hcl:"type,optional"`
Description string `json:"description,omitempty" yaml:"description,omitempty" hcl:"description,optional"`
OperationRef string `json:"operationRef,omitempty" yaml:"operationRef,omitempty" hcl:"operationRef,optional"`
Pending *PendingStep `json:"pending,omitempty" yaml:"pending,omitempty" hcl:"pending,block"`
Body map[string]any `json:"body,omitempty" yaml:"body,omitempty" hcl:"body,optional"`
Inputs map[string]any `json:"inputs,omitempty" yaml:"inputs,omitempty" hcl:"inputs,optional"`
StepExecutionFields
StructuralFields
Steps []*Step `json:"steps,omitempty" yaml:"steps,omitempty" hcl:"step,block"`
Cases []*Case `json:"cases,omitempty" yaml:"cases,omitempty" hcl:"case,block"`
Default []*Step `json:"default,omitempty" yaml:"default,omitempty" hcl:"default,block"`
Outputs map[string]string `json:"outputs,omitempty" yaml:"outputs,omitempty" hcl:"outputs,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Step describes a nested step within a structural workflow.
func (Step) MarshalJSON ¶
func (*Step) UnmarshalJSON ¶
type StepExecutionFields ¶
type StepExecutionFields struct {
DependsOn []string `json:"dependsOn,omitempty" yaml:"dependsOn,omitempty" hcl:"dependsOn,optional"`
When string `json:"when,omitempty" yaml:"when,omitempty" hcl:"when,optional"`
ForEach string `json:"forEach,omitempty" yaml:"forEach,omitempty" hcl:"forEach,optional"`
Wait string `json:"wait,omitempty" yaml:"wait,omitempty" hcl:"wait,optional"`
Timeout *float64 `json:"timeout,omitempty" yaml:"timeout,omitempty" hcl:"timeout,optional"`
Workflow string `json:"workflow,omitempty" yaml:"workflow,omitempty" hcl:"workflow,optional"`
ParallelGroup string `json:"parallelGroup,omitempty" yaml:"parallelGroup,omitempty" hcl:"parallelGroup,optional"`
}
StepExecutionFields captures execution controls on nested steps.
type StructuralFields ¶
type StructuralFields struct {
Items string `json:"items,omitempty" yaml:"items,omitempty" hcl:"items,optional"`
Mode string `json:"mode,omitempty" yaml:"mode,omitempty" hcl:"mode,optional"`
BatchSize string `json:"batchSize,omitempty" yaml:"batchSize,omitempty" hcl:"batchSize,optional"`
}
StructuralFields captures structural-control attributes shared by switch, merge, and loop style nodes.
type StructuralResult ¶
type StructuralResult struct {
Name string `json:"name" yaml:"name" hcl:"name,label"`
Kind string `json:"kind" yaml:"kind" hcl:"kind"`
From string `json:"from" yaml:"from" hcl:"from"`
Value string `json:"value,omitempty" yaml:"value,omitempty" hcl:"value,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
StructuralResult declares a named output from a structural workflow construct.
func (StructuralResult) MarshalJSON ¶
func (s StructuralResult) MarshalJSON() ([]byte, error)
func (*StructuralResult) UnmarshalHCL ¶
func (s *StructuralResult) UnmarshalHCL(data []byte, labels ...string) error
func (*StructuralResult) UnmarshalJSON ¶
func (s *StructuralResult) UnmarshalJSON(data []byte) error
type SuccessAction ¶
type SuccessAction struct {
Name string `json:"name" yaml:"name" hcl:"name,label"`
Type string `json:"type" yaml:"type" hcl:"type"`
WorkflowID string `json:"workflowId,omitempty" yaml:"workflowId,omitempty" hcl:"workflowId,optional"`
StepID string `json:"stepId,omitempty" yaml:"stepId,omitempty" hcl:"stepId,optional"`
Criteria []*Criterion `json:"criteria,omitempty" yaml:"criteria,omitempty" hcl:"criterion,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
SuccessAction describes what to do when an operation succeeds. Type is one of: end, goto.
func (SuccessAction) MarshalJSON ¶
func (s SuccessAction) MarshalJSON() ([]byte, error)
func (*SuccessAction) UnmarshalHCL ¶
func (s *SuccessAction) UnmarshalHCL(data []byte, labels ...string) error
func (*SuccessAction) UnmarshalJSON ¶
func (s *SuccessAction) UnmarshalJSON(data []byte) error
type Trigger ¶
type Trigger struct {
TriggerID string `json:"triggerId" yaml:"triggerId" hcl:"triggerId,label"`
TriggerFields
// Options is an intentionally open-shape map so each trigger implementation
// can carry its own configuration. UWS does not restrict keys or values
// beyond the JSON Schema's object shape.
Options map[string]any `json:"options,omitempty" yaml:"options,omitempty" hcl:"options,optional"`
Outputs []string `json:"outputs,omitempty" yaml:"outputs,omitempty" hcl:"outputs,optional"`
Routes []*TriggerRoute `json:"routes,omitempty" yaml:"routes,omitempty" hcl:"route,block"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Trigger defines an entry point that initiates workflow execution.
func (Trigger) MarshalJSON ¶
func (*Trigger) UnmarshalJSON ¶
type TriggerExecutionContext ¶
TriggerExecutionContext describes the trigger event currently being routed.
type TriggerFields ¶
type TriggerFields struct {
Path string `json:"path,omitempty" yaml:"path,omitempty" hcl:"path,optional"`
Methods []string `json:"methods,omitempty" yaml:"methods,omitempty" hcl:"methods,optional"`
Authentication string `json:"authentication,omitempty" yaml:"authentication,omitempty" hcl:"authentication,optional"`
}
TriggerFields captures generic trigger entrypoint fields.
type TriggerRoute ¶
type TriggerRoute struct {
TriggerRouteFields
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
TriggerRoute maps a trigger output to top-level step or workflow targets.
func (TriggerRoute) MarshalJSON ¶
func (t TriggerRoute) MarshalJSON() ([]byte, error)
func (*TriggerRoute) UnmarshalHCL ¶
func (t *TriggerRoute) UnmarshalHCL(data []byte, labels ...string) error
func (*TriggerRoute) UnmarshalJSON ¶
func (t *TriggerRoute) UnmarshalJSON(data []byte) error
type TriggerRouteFields ¶
type TriggerRouteFields struct {
Output string `json:"output" yaml:"output" hcl:"output"`
To []string `json:"to,omitempty" yaml:"to,omitempty" hcl:"to,optional"`
}
TriggerRouteFields captures generic trigger routing fields.
type ValidationError ¶
ValidationError represents one UWS validation error.
type ValidationResult ¶
type ValidationResult struct {
Errors []ValidationError
}
ValidationResult accumulates all validation errors found in a document.
func (*ValidationResult) Error ¶
func (r *ValidationResult) Error() string
Error returns a compact, path-tagged summary of all validation errors.
func (*ValidationResult) Valid ¶
func (r *ValidationResult) Valid() bool
Valid reports whether validation found no errors.
type Workflow ¶
type Workflow struct {
WorkflowID string `json:"workflowId" yaml:"workflowId" hcl:"workflowId,label"`
Type string `json:"type" yaml:"type" hcl:"type"`
Description string `json:"description,omitempty" yaml:"description,omitempty" hcl:"description,optional"`
Inputs *ParamSchema `json:"inputs,omitempty" yaml:"inputs,omitempty" hcl:"inputs,block"`
Idempotency *Idempotency `json:"idempotency,omitempty" yaml:"idempotency,omitempty" hcl:"idempotency,block"`
WorkflowExecutionFields
StructuralFields
Steps []*Step `json:"steps,omitempty" yaml:"steps,omitempty" hcl:"step,block"`
Cases []*Case `json:"cases,omitempty" yaml:"cases,omitempty" hcl:"case,block"`
Default []*Step `json:"default,omitempty" yaml:"default,omitempty" hcl:"default,block"`
Outputs map[string]string `json:"outputs,omitempty" yaml:"outputs,omitempty" hcl:"outputs,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
Workflow describes a control-flow construct (sequence, parallel, switch, merge, loop, await).
func (Workflow) MarshalJSON ¶
func (*Workflow) UnmarshalHCL ¶
func (*Workflow) UnmarshalJSON ¶
type WorkflowContentTrust ¶
type WorkflowContentTrust struct {
Default ContentTrustLevel `json:"default,omitempty" yaml:"default,omitempty" hcl:"default,optional"`
Inputs map[string]ContentTrustLevel `json:"inputs,omitempty" yaml:"inputs,omitempty" hcl:"inputs,optional"`
Extensions map[string]any `json:"-" yaml:"-" hcl:"extensions,block"`
}
WorkflowContentTrust declares the provenance of externally supplied inputs to a workflow. A same-document workflow call retains the provenance of the values passed by the caller instead of applying this entry declaration.
func (WorkflowContentTrust) MarshalJSON ¶
func (c WorkflowContentTrust) MarshalJSON() ([]byte, error)
func (*WorkflowContentTrust) UnmarshalHCL ¶
func (c *WorkflowContentTrust) UnmarshalHCL(data []byte, labels ...string) error
func (*WorkflowContentTrust) UnmarshalJSON ¶
func (c *WorkflowContentTrust) UnmarshalJSON(data []byte) error
type WorkflowExecutionFields ¶
type WorkflowExecutionFields struct {
DependsOn []string `json:"dependsOn,omitempty" yaml:"dependsOn,omitempty" hcl:"dependsOn,optional"`
When string `json:"when,omitempty" yaml:"when,omitempty" hcl:"when,optional"`
ForEach string `json:"forEach,omitempty" yaml:"forEach,omitempty" hcl:"forEach,optional"`
Wait string `json:"wait,omitempty" yaml:"wait,omitempty" hcl:"wait,optional"`
Timeout *float64 `json:"timeout,omitempty" yaml:"timeout,omitempty" hcl:"timeout,optional"`
}
WorkflowExecutionFields captures execution controls shared by top-level workflow objects.
Source Files
¶
- components.go
- content_trust.go
- criterion.go
- doc.go
- document.go
- document_execution_state.go
- document_index.go
- executable_validation.go
- execution.go
- execution_actions.go
- execution_context.go
- execution_criteria.go
- execution_records.go
- execution_runnable.go
- execution_state.go
- execution_structural.go
- extensions.go
- failure_action.go
- flow_fields.go
- hcl.go
- hcl_walk.go
- idempotency.go
- operation.go
- param_schema.go
- pending_step.go
- result.go
- source_description.go
- step_walk.go
- success_action.go
- trigger.go
- trigger_dispatch.go
- validation.go
- validation_action.go
- validation_graph.go
- validation_operation.go
- validation_result.go
- validation_trigger.go
- validation_version.go
- validation_workflow.go
- workflow.go