spec

package
v2.25.2 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: GPL-3.0 Imports: 50 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// CalendarFileExtension is the extension of calendar files.
	CalendarFileExtension = ".yaml"

	// CalendarExpiryWarningDays is how long before a calendar's through date
	// the DAGs that use it warn that its holidays run out.
	CalendarExpiryWarningDays = 30
)

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

View Source 
var ErrUnknownCalendar = errors.New("unknown calendar")

ErrUnknownCalendar reports a calendar name with no built-in calendar and no calendar file.

Functions

func BindScheduleCalendars 

func BindScheduleCalendars(schedules []ir.Schedule, source *CalendarSource)

BindScheduleCalendars binds the calendars that decoded start schedules name, such as schedules rebuilt from an index entry. A calendar that does not load leaves its schedule unbound, so it never fires.

func CalendarExpiryWarning 

func CalendarExpiryWarning(name string, through, today ir.CivilDate) string

CalendarExpiryWarning reports a calendar whose holidays, listed through the given date, run out within CalendarExpiryWarningDays of today, or already have. It is empty otherwise.

func CalendarTemplate 

func CalendarTemplate(year int) []byte

CalendarTemplate returns the content of a new calendar file: Monday to Friday, no holidays yet, maintained through the end of year.

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 ErrorMessages 

func ErrorMessages(data []byte, errs []error) []string

ErrorMessages formats errors about the YAML document data. An error about a field found in data starts with the field's [line:column], the form editors place markers at.

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 LoadCalendar 

func LoadCalendar(dir, name string) (*ir.Calendar, error)

LoadCalendar returns the named calendar: a built-in one, or the calendar file <name>.yaml in dir with the holidays of the calendars it includes.

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 CalendarSource 

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

CalendarSource loads the calendar files of one directory. It keeps each parsed calendar until its file, or a file it includes, changes identity, size or modification time, or until Invalidate, so DAGs that share a calendar parse it once. The content of the files is rechecked too, at most once a second per calendar, for rewrites that keep all three. A file that cannot be read is retried on every call. The calendars it returns are shared and must not be modified.

func NewCalendarSource 

func NewCalendarSource(dir string) *CalendarSource

NewCalendarSource returns a source for the calendar files in dir. With an empty dir, only built-in calendars exist.

func (*CalendarSource) Calendar 

func (s *CalendarSource) Calendar(name string) (*ir.Calendar, error)

Calendar returns the named calendar: a built-in one, or the calendar file <name>.yaml with the holidays of the calendars it includes.

func (*CalendarSource) CalendarFile 

func (s *CalendarSource) CalendarFile(name string) (*ir.Calendar, error)

CalendarFile returns the calendar file <name>.yaml with the holidays of the calendars it includes. A reserved name is an error, even when a file has that name.

func (*CalendarSource) Check 

func (s *CalendarSource) Check(name string, data []byte) (*ir.Calendar, []error)

Check parses data as the content of calendar file <name>.yaml, with the holidays of the calendars it includes from the source's directory, and reports every problem found. A problem with a place in data is a *FieldError. Check returns the calendar built from the valid parts, or nil when data is not a calendar document. Nothing is cached.

func (*CalendarSource) Dir 

func (s *CalendarSource) Dir() string

Dir returns the directory of the calendar files.

func (*CalendarSource) Invalidate 

func (s *CalendarSource) Invalidate()

Invalidate drops every cached calendar, so the next lookups read the files again. Lookups notice files that change identity, size or modification time; Invalidate covers a rewrite that keeps all three.

func (*CalendarSource) List 

func (s *CalendarSource) List() ([]CalendarSummary, error)

List lists the built-in calendars and the calendar files, sorted by name. A missing directory lists only the built-in calendars.

type CalendarSummary 

type CalendarSummary struct {
	Name        string
	Description string
	// Through is the last date the calendar's holidays are maintained for;
	// zero when the calendar does not say.
	Through ir.CivilDate
	Builtin bool
	// Includes names the calendars whose holidays it adds, also when the
	// calendar does not load.
	Includes []string
	// Err is set when the calendar file does not load.
	Err error
}

CalendarSummary describes a calendar for listings.

func ListCalendars 

func ListCalendars(dir string) ([]CalendarSummary, error)

ListCalendars lists the built-in calendars and the calendar files in dir, sorted by name. A missing dir lists only the built-in calendars.

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 FieldError 

type FieldError struct {
	// Path locates the field in the document, such as schedule[1].calendar.
	Path string
	Err  error
}

FieldError is a DAG error about one field of the YAML document.

func (*FieldError) Error 

func (e *FieldError) Error() string

func (*FieldError) Unwrap 

func (e *FieldError) Unwrap() error

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 WithCalendars 

func WithCalendars(source *CalendarSource) LoadOption

WithCalendars sets the source of the calendar files that schedules name. Without one, a schedule naming a calendar file stays unbound and never fires; built-in calendars bind either way.

func WithCalendarsDir 

func WithCalendarsDir(dir string) LoadOption

WithCalendarsDir reads the calendar files that schedules name from dir, without reusing calendars across loads. An empty dir sets no source.

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.