spec

package
v2.11.3 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2026 License: GPL-3.0 Imports: 40 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")
	ErrInvalidJSONFile    = errors.New("invalid JSON file")
)

Errors for loading DAGs

Functions

func BuiltinActionNames 

func BuiltinActionNames() []string

BuiltinActionNames returns the currently accepted built-in action names in sorted order. Redis operations are intentionally exposed as a pattern because they normalize dynamically from any redis.<operation> action.

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 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) (*core.DAG, error)

Load loads a Directed Acyclic Graph (core.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 core.DAG definitions from multiple sources while supporting customization through the LoadOptions.

func LoadBaseConfig 

func LoadBaseConfig(ctx BuildContext, file string) (*core.DAG, error)

LoadBaseConfig loads the global configuration from the given file. The global configuration can be overridden by the core.DAG configuration.

func LoadYAML 

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

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

func LoadYAMLWithOpts 

func LoadYAMLWithOpts(ctx context.Context, data []byte, opts BuildOpts) (*core.DAG, error)

LoadYAMLWithOpts loads the core.DAG configuration from YAML data.

func QuoteRuntimeParams 

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

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

func RegisterExecutorTypeName 

func RegisterExecutorTypeName(name string)

RegisterExecutorTypeName registers a runtime executor type name so DAG loading accepts steps that use it directly in the type field.

func ResolveEnv 

func ResolveEnv(ctx context.Context, dag *core.DAG, params any, opts ResolveEnvOptions) ([]string, error)

ResolveEnv rebuilds the DAG env from source when the current DAG snapshot no longer carries resolved env entries (for example when restored from dag.json).

func ResolveRuntimeParams 

func ResolveRuntimeParams(ctx context.Context, dag *core.DAG, params any, opts ResolveRuntimeParamsOptions) (*core.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 StepTypeNames 

func StepTypeNames() []string

StepTypeNames returns the currently accepted builtin and runtime-registered executor type names in sorted order. It excludes the implicit empty command executor type; callers should mention omitted type handling separately.

func TypedUnionDecodeHook 

func TypedUnionDecodeHook() mapstructure.DecodeHookFunc

TypedUnionDecodeHook returns a decode hook that handles our typed union types. It converts raw map[string]any values to the appropriate typed values.

func UnregisterExecutorTypeName 

func UnregisterExecutorTypeName(name string)

UnregisterExecutorTypeName removes a runtime executor type name that was registered by RegisterExecutorTypeName. Built-in names are retained.

Types

type BuildContext 

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

BuildContext is the context for building a DAG.

func (BuildContext) WithCustomStepTypes 

func (c BuildContext) WithCustomStepTypes(registry *customStepTypeRegistry) BuildContext

func (BuildContext) WithFile 

func (c BuildContext) WithFile(file string) BuildContext

func (BuildContext) WithOpts 

func (c BuildContext) WithOpts(opts BuildOpts) BuildContext

type BuildFlag 

type BuildFlag uint32

BuildFlag represents a bitmask option that influences DAG building behaviour. 

const (
	BuildFlagNone BuildFlag = 0

	BuildFlagNoEval BuildFlag = 1 << iota
	BuildFlagOnlyMetadata
	BuildFlagAllowBuildErrors
	BuildFlagSkipSchemaValidation
	BuildFlagSkipBaseHandlers // Skip merging handlerOn from base config (for sub-DAG runs)
	BuildFlagValidateRuntimeParams
	BuildFlagDeferWorkerSelector
)

type BuildOpts 

type BuildOpts struct {
	// Base specifies the Base configuration file for the DAG.
	Base string
	// BaseConfigContent is the raw base config YAML content.
	// When set, this takes precedence over Base file path.
	BaseConfigContent []byte
	// WorkspaceBaseConfigDir contains per-workspace base configs at <workspace>/base.yaml.
	WorkspaceBaseConfigDir string
	// Parameters specifies the Parameters to the DAG.
	// Parameters are used to override the default Parameters in the DAG.
	Parameters string
	// ParametersList specifies the parameters to the DAG.
	ParametersList []string
	// Name of the core.DAG if it's not defined in the spec
	Name string
	// DAGsDir is the directory containing the core.DAG files.
	DAGsDir string
	// DefaultWorkingDir is the default working directory for DAGs without explicit workingDir.
	DefaultWorkingDir string
	// SourceFile is the path the DAG was authored at. It is set when the
	// definition is loaded from a copy, so relative paths keep resolving
	// against the file the author wrote rather than the copy.
	SourceFile string
	// Flags stores all boolean options controlling build behaviour.
	Flags BuildFlag
	// BuildEnv provides pre-populated environment variables for the build.
	// These are added to envScope before building, allowing YAML to reference
	// them via ${VAR}. Used for retry/restart where dotenv values need to be
	// available during rebuild from YamlData.
	BuildEnv map[string]string
}

BuildOpts is used to control the behavior of the builder.

func (BuildOpts) Has 

func (o BuildOpts) Has(flag BuildFlag) bool

Has reports whether the flag is enabled on the current BuildOpts.

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(*LoadOptions)

LoadOption is a function type for setting LoadOptions.

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 core.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 core.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 core.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 WithBuildEnv 

func WithBuildEnv(env map[string]string) LoadOption

WithBuildEnv provides additional environment variables for the build. These are added to the envScope before building, allowing YAML to reference them via ${VAR}. This is used for retry scenarios where dotenv values need to be available during rebuild from YamlData.

func WithDAGsDir 

func WithDAGsDir(dagsDir string) LoadOption

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

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 LoadOptions 

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

LoadOptions contains options for loading a DAG.

type LoadResult 

type LoadResult struct {
	DAG                   *core.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 ResolveEnvOptions 

type ResolveEnvOptions struct {
	BaseConfig             string
	WorkspaceBaseConfigDir string
}

ResolveEnvOptions controls how a DAG is reloaded to recover resolved env values for subprocess launchers.

type ResolveEnvResult 

type ResolveEnvResult struct {
	Env           []string
	BuildWarnings []string
}

ResolveEnvResult contains resolved env entries and warnings encountered while rebuilding them.

func ResolveEnvWithWarnings 

func ResolveEnvWithWarnings(ctx context.Context, dag *core.DAG, params any, opts ResolveEnvOptions) (ResolveEnvResult, error)

ResolveEnvWithWarnings rebuilds the DAG env and returns warnings emitted during dotenv loading.

type ResolveRuntimeParamsOptions 

type ResolveRuntimeParamsOptions struct {
	BaseConfig             string
	WorkspaceBaseConfigDir string
}

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

type StepBuildContext 

type StepBuildContext struct {
	BuildContext
	// contains filtered or unexported fields
}

StepBuildContext is the context for building a step.

type Transformer 

type Transformer[C any, T any] interface {
	// Transform performs the transformation and sets field(s) on out
	Transform(ctx C, in T, out reflect.Value) error
}

Transformer transforms a spec field into output field(s). C is the context type, T is the input type.

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.