spec

package
v2.22.1 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: GPL-3.0 Imports: 47 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidSchedule                     = errors.New("invalid schedule")
	ErrScheduleMustBeStringOrArray         = errors.New("schedule must be a string or an array of strings")
	ErrInvalidScheduleType                 = errors.New("invalid schedule type")
	ErrDotEnvMustBeStringOrArray           = errors.New("dotenv must be a string or an array of strings")
	ErrPreconditionValueMustBeString       = errors.New("precondition value must be a string")
	ErrPreconditionNegateMustBeBool        = errors.New("precondition negate must be a boolean")
	ErrPreconditionHasInvalidKey           = errors.New("precondition has invalid key")
	ErrPreconditionMustBeArrayOrString     = errors.New("precondition must be a string or an array of strings")
	ErrInvalidStepData                     = errors.New("invalid step data")
	ErrStepsMustBeArrayOrMap               = errors.New("steps must be an array or a map")
	ErrContinueOnExitCodeMustBeIntOrArray  = errors.New("continue_on.exit_code must be an int or an array of ints")
	ErrContinueOnOutputMustBeStringOrArray = errors.New("continue_on.output must be a string or an array of strings")
	ErrContinueOnMustBeStringOrMap         = errors.New("continue_on must be a string ('skipped' or 'failed') or an object")
	ErrContinueOnInvalidStringValue        = errors.New("continue_on string value must be 'skipped' or 'failed'")
	ErrContinueOnFieldMustBeBool           = errors.New("value must be a boolean")
	ErrInvalidSignal                       = errors.New("invalid signal")
	ErrDependsMustBeStringOrArray          = errors.New("depends must be a string or an array of strings")
	ErrInvalidEnvValue                     = errors.New("env config should be map of strings or array of key=value formatted string")
	ErrInvalidParamValue                   = errors.New("invalid parameter value")
	ErrStepCommandIsEmpty                  = errors.New("step command is empty")
	ErrStepCommandMustBeArrayOrString      = errors.New("step command must be an array of strings or a string")
	ErrTimeoutSecMustBeNonNegative         = errors.New("timeout_sec must be >= 0")
	ErrExecutorDoesNotSupportMultipleCmd   = errors.New("action does not support multiple commands")
)
View Source 
var (
	ErrNameOrPathRequired = errors.New("name or path is required")
)

Errors for loading DAGs

Functions

func DeprecatedSyntaxWarnings 

func DeprecatedSyntaxWarnings(data []byte) []string

DeprecatedSyntaxWarnings returns validate-only deprecation warnings for legacy DAG syntax. Runtime loading intentionally does not call this function.

func IsSourceUnavailable added in v2.18.0 

func IsSourceUnavailable(err error) bool

IsSourceUnavailable reports whether a DAG load error was caused by an external source that could not be read, such as a missing file or an unreachable schema URL, rather than by the definition itself. Such errors may resolve without changing the definition.

func IsValidExecutorTypeName 

func IsValidExecutorTypeName(name string) bool

IsValidExecutorTypeName reports whether name is valid for an executor type.

func Load 

func Load(ctx context.Context, nameOrPath string, opts ...LoadOption) (*ir.DAG, error)

Load loads a Directed Acyclic Graph (ir.DAG) from a file path or name with the given options.

The function handles different input formats:

1. Absolute paths:

  • YAML files (.yaml/.yml): Processed with dynamic evaluation, including base configs, parameters, and environment variables

2. Relative paths or filenames:

  • Resolved against the DAGsDir specified in options
  • If DAGsDir is not provided, the current working directory is used
  • For YAML files, the extension is optional

This approach provides a flexible way to load ir.DAG definitions from multiple sources while supporting customization through the LoadOptions.

func LoadYAML 

func LoadYAML(ctx context.Context, data []byte, opts ...LoadOption) (*ir.DAG, error)

LoadYAML loads the ir.DAG from the given YAML data with the specified options.

func LoadYAMLAt added in v2.14.0 

func LoadYAMLAt(ctx context.Context, data []byte, sourcePath string, opts ...LoadOption) (*ir.DAG, error)

LoadYAMLAt loads YAML content as authored at sourcePath, preserving file-relative loading semantics.

func ParseDuration 

func ParseDuration(s string) (time.Duration, error)

ParseDuration extends time.ParseDuration with support for "d" (days = 24h). Rejects empty strings and zero/negative durations.

func ParseLLMConfig 

func ParseLLMConfig(data []byte) (*ir.LLMConfig, error)

ParseLLMConfig reads an llm block, written as a step's llm field is, in YAML or JSON, and checks it as a step's would be.

func PrepareDAGSnapshot added in v2.17.0 

func PrepareDAGSnapshot(dag *ir.DAG) (*ir.DAG, error)

PrepareDAGSnapshot returns a copy without SMTP inherited from base configuration. Authored YAML and all other base settings are preserved, including local DAGs.

func QuoteRuntimeParams 

func QuoteRuntimeParams(params []string, paramDefs []ir.ParamDef) []string

QuoteRuntimeParams quotes persisted params so values containing spaces survive re-parsing when a DAG is rebuilt from status metadata.

func RebuildFromYAML 

func RebuildFromYAML(ctx context.Context, dag *ir.DAG, paramsOverride ...[]string) (*ir.DAG, error)

RebuildFromYAML restores the fields of dag that JSON serialization excludes by reloading its YamlData, and returns dag. Fields that survive serialization are preserved as-is. A dag without YamlData is returned unchanged.

Callers must resolve the runtime environment before calling, so those values are visible to the rebuild. When paramsOverride is supplied its first element replaces the DAG's params for the reload.

Env is drawn from the reloaded YAML and from the environment captured when the run was first built. A captured key overrides the YAML's declaration of it, so the rebuild reuses the original value rather than one the current process may resolve differently or fail to resolve at all. Keys the YAML does not declare are appended from the captured environment instead of being dropped.

func RefreshBaseSMTP added in v2.17.0 

func RefreshBaseSMTP(dag *ir.DAG, opts ...LoadOption) (*ir.DAG, error)

RefreshBaseSMTP returns a copy with inherited SMTP from the current base configuration. Other saved settings and authored YAML remain unchanged. If no base configuration was captured, the current base settings are used. Rebuilding the returned DAG applies its original SMTP overrides.

func ReloadRuntimeSnapshot 

func ReloadRuntimeSnapshot(
	ctx context.Context,
	dag *ir.DAG,
	params any,
	opts ResolveRuntimeParamsOptions,
	additional ...LoadOption,
) (*ir.DAG, error)

ReloadRuntimeSnapshot reloads a DAG from its captured source with runtime parameters and additional compiler options applied. Captured YAML is authoritative when available.

func ReportValueReferenceNotices 

func ReportValueReferenceNotices(dag *ir.DAG, sink cmnvalue.ValueReferenceNoticeSink)

ReportValueReferenceNotices reports passive notices for value references in dag.

func ResolveRuntimeParams 

func ResolveRuntimeParams(ctx context.Context, dag *ir.DAG, params any, opts ResolveRuntimeParamsOptions) (*ir.DAG, error)

ResolveRuntimeParams reloads a DAG from its source with runtime params applied. It is intended for entry points that need the same coercion and validation path as execution without duplicating loader setup.

func ValidateStartArgs 

func ValidateStartArgs(hasDash bool, args []string) error

func ValidateStartParams 

func ValidateStartParams(defaultParams string, input StartParamInput) error

ValidateStartParams validates positional params against declared defaults. Rule: allow 0..expected positional params; reject only when positional params exceed expected.

func ValidateStepID 

func ValidateStepID(id string) error

ValidateStepID reports whether id can identify a step: it starts with a letter, holds only letters, digits, and underscores, is not too long, and is not a reserved word.

func ValidateSteps 

func ValidateSteps(dag *ir.DAG) error

ValidateSteps validates all steps in a ir.DAG, collecting all validation errors.

Types

type CustomActionEditorHint 

type CustomActionEditorHint struct {
	Name         string
	Description  string
	InputSchema  map[string]any
	OutputSchema map[string]any
}

CustomActionEditorHint is editor-only metadata for a custom action. It is derived from the same validated spec pipeline as runtime expansion.

func InheritedCustomActionEditorHints 

func InheritedCustomActionEditorHints(baseConfig []byte) ([]CustomActionEditorHint, error)

InheritedCustomActionEditorHints returns editor hints for custom actions declared in base config. The returned schemas are fully resolved JSON Schema objects safe to embed into editor-generated DAG schemas.

type HumanTaskInputResult 

type HumanTaskInputResult struct {
	Canonical json.RawMessage
	Outputs   map[string]string
}

HumanTaskInputResult contains canonical form input and its step outputs.

func ValidateHumanTaskInputs 

func ValidateHumanTaskInputs(form json.RawMessage, inputs map[string]any, coerceStrings bool) (*HumanTaskInputResult, error)

ValidateHumanTaskInputs applies form defaults and validates completion input.

type LegacyDefinitionEditorHint 

type LegacyDefinitionEditorHint struct {
	Name         string
	TargetType   string
	Description  string
	InputSchema  map[string]any
	OutputSchema map[string]any
}

LegacyDefinitionEditorHint is editor-only metadata for a deprecated step_types entry. It is derived from the same validated spec pipeline as runtime expansion.

func InheritedLegacyDefinitionEditorHints 

func InheritedLegacyDefinitionEditorHints(baseConfig []byte) ([]LegacyDefinitionEditorHint, error)

InheritedLegacyDefinitionEditorHints returns editor hints for deprecated step_types declared in base config. The returned schemas are fully resolved JSON Schema objects safe to embed into editor-generated DAG schemas.

type LoadOption 

type LoadOption func(*buildOpts)

LoadOption is a function type for setting load options.

func OnlyMetadata 

func OnlyMetadata() LoadOption

OnlyMetadata sets the flag to load only metadata.

func SkipSchemaValidation 

func SkipSchemaValidation() LoadOption

SkipSchemaValidation disables schema resolution/validation during build.

func WithAllowBuildErrors 

func WithAllowBuildErrors() LoadOption

WithAllowBuildErrors allows build errors to be ignored during ir.DAG loading. This is required for loading DAGs that may have errors in their definitions, such as missing steps or invalid configurations. When this option is set, the loader will return a ir.DAG with the errors included in the DAG's `BuildErrors` field, and will not fail the loading process.

func WithBaseConfig 

func WithBaseConfig(baseDAG string) LoadOption

WithBaseConfig sets the base ir.DAG configuration file.

func WithBaseConfigContent 

func WithBaseConfigContent(content []byte) LoadOption

WithBaseConfigContent sets the raw base config YAML content directly. This is used in distributed mode where workers may not have local base config files. When set, this takes precedence over the base config file path.

func WithBuildEnvSnapshot 

func WithBuildEnvSnapshot(snapshot buildenv.Snapshot) LoadOption

WithBuildEnvSnapshot provides transported build values and their resolution state.

func WithDAGsDir 

func WithDAGsDir(dagsDir string) LoadOption

WithDAGsDir sets the directory containing the ir.DAG files. This directory is used as the base path for resolving relative ir.DAG file paths. When a ir.DAG is loaded by name rather than absolute path, the system will look for the ir.DAG file in this directory. If not specified, the current working directory is used as the default.

func WithDefaultName added in v2.15.0 

func WithDefaultName(name string) LoadOption

WithDefaultName sets the entrypoint DAG name when the manifest omits it.

func WithDefaultWorkingDir 

func WithDefaultWorkingDir(defaultWorkingDir string) LoadOption

WithDefaultWorkingDir sets the default working directory for DAGs without explicit workingDir.

func WithName 

func WithName(name string) LoadOption

WithName sets the name of the DAG.

func WithParams 

func WithParams(params any) LoadOption

WithParams sets the parameters for the DAG.

func WithSkipBaseHandlers 

func WithSkipBaseHandlers() LoadOption

WithSkipBaseHandlers skips merging handlerOn from base config. This is used for sub-DAG runs to prevent handler inheritance from base config. Sub-DAGs should have their own handlers defined explicitly if needed.

func WithSourceFile 

func WithSourceFile(sourceFile string) LoadOption

WithSourceFile sets the path the DAG was authored at. A definition executed from a temporary copy, such as a sub-workflow or a task dispatched to a worker, resolves its relative paths against this rather than against the copy.

func WithWorkspaceBaseConfigDir 

func WithWorkspaceBaseConfigDir(dir string) LoadOption

WithWorkspaceBaseConfigDir sets the directory containing workspace base configs. Named workspace DAGs inherit <dir>/<workspace>/base.yaml after the global base config.

func WithoutEval 

func WithoutEval() LoadOption

WithoutEval disables the evaluation of dynamic fields.

type LoadResult 

type LoadResult struct {
	DAG                   *ir.DAG
	ValueReferenceNotices []cmnvalue.ValueReferenceNotice
}

LoadResult contains a loaded DAG and transient value-reference notices produced by that load operation.

func LoadWithResult 

func LoadWithResult(ctx context.Context, nameOrPath string, opts ...LoadOption) (*LoadResult, error)

LoadWithResult loads a DAG and returns transient value-reference notices produced by that load operation.

func LoadYAMLWithResult 

func LoadYAMLWithResult(ctx context.Context, data []byte, opts ...LoadOption) (*LoadResult, error)

LoadYAMLWithResult loads a DAG from YAML and returns transient value-reference notices produced by that load operation.

type ReferenceField 

type ReferenceField struct {
	Path  string
	Value string

	OwnerStepName string
	OwnerStepID   string
	// OwnerStepPath is the spec path of the owning step, such as "steps[0]" or
	// "handler_on.exit". It is empty for ir.DAG-level fields.
	OwnerStepPath string
	Field         cmnvalue.Field
	// contains filtered or unexported fields
}

func ReferenceFields 

func ReferenceFields(dag *ir.DAG) []ReferenceField

type ResolveRuntimeParamsOptions 

type ResolveRuntimeParamsOptions struct {
	BaseConfig             string
	WorkspaceBaseConfigDir string
}

ResolveRuntimeParamsOptions controls how a DAG is reloaded for runtime param validation.

type StartParamInput 

type StartParamInput struct {
	DashArgs  []string
	RawParams string
}

StartParamInput describes start params regardless of caller (CLI/API). Use DashArgs for parameter tokens or RawParams for parameter text. Quotes in RawParams delimit values rather than wrapping the complete input.

Source Files

View all Source files

Directories

Path Synopsis
Package types provides typed union types for YAML fields that accept multiple formats.
 Package types provides typed union types for YAML fields that accept multiple formats.

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.