value

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: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const EnvSourceStep = EnvSourceOutput

EnvSourceStep is deprecated: use EnvSourceOutput instead

Variables

This section is empty.

Functions

func ExpandEnvContext 

func ExpandEnvContext(ctx context.Context, s string) string

ExpandEnvContext expands ${VAR} and $VAR in s using EnvScope from context, falling back to the process environment, as a workflow sees it, if no scope is in context. Variables not found are preserved in their original form.

func HasAnyReference 

func HasAnyReference(raw string) bool

HasAnyReference reports whether raw contains an unescaped ${...}, $NAME, or $N reference anywhere in the text, in any form value resolution may expand.

func HasReferenceToNamespace added in v2.13.0 

func HasReferenceToNamespace(raw string, namespaces ...string) bool

HasReferenceToNamespace reports whether raw references one of the named scopes.

func HasStepRuntimeOutputReference added in v2.13.0 

func HasStepRuntimeOutputReference(raw, stepID string) bool

HasStepRuntimeOutputReference reports whether raw reads an attempt result from stepID.

func HasValueReference 

func HasValueReference(raw string) bool

HasValueReference reports whether raw contains a supported value-reference form.

func IsExactRef 

func IsExactRef(token string) bool

IsExactRef reports whether token is an exact canonical scoped reference.

func IsStepOutputReferenceToken 

func IsStepOutputReferenceToken(token string) bool

IsStepOutputReferenceToken reports whether token is an exact Spec 007 reference.

func IsWholeReference added in v2.17.0 

func IsWholeReference(text string) bool

IsWholeReference reports whether text is exactly one value reference and nothing else.

It accepts the canonical scoped forms IsExactRef accepts, and the unqualified environment forms ${NAME} and $NAME, which resolve wherever a field expands environment values.

func NormalizeJSONNumbers added in v2.17.0 

func NormalizeJSONNumbers(v any) any

NormalizeJSONNumbers converts values decoded as json.Number to float64, keeping the literal only for integers a float64 cannot hold exactly. Maps and slices are normalized in place.

func ReportStepOutputReferenceNotice 

func ReportStepOutputReferenceNotice(sink ValueReferenceNoticeSink, field, token string, reason ValueReferenceNoticeReason)

ReportStepOutputReferenceNotice reports a passive Spec 007 step-output notice.

func ReportUnresolvedEnvExpansionNotices 

func ReportUnresolvedEnvExpansionNotices(input string, field Field, scope *EnvScope, sink ValueReferenceNoticeSink)

ReportUnresolvedEnvExpansionNotices reports missing simple shell-style env references in input, read as a value of field.

func ValidEnvName 

func ValidEnvName(name string) bool

ValidEnvName reports whether name is a valid environment variable name.

func WithCommandSubstitutionShell 

func WithCommandSubstitutionShell(ctx context.Context, shell []string) context.Context

WithCommandSubstitutionShell sets the shell used by command substitutions.

func WithCommandSubstitutionWorkingDir 

func WithCommandSubstitutionWorkingDir(ctx context.Context, dir string) context.Context

WithCommandSubstitutionWorkingDir sets the working directory used by command substitutions.

func WithEnvScope 

func WithEnvScope(ctx context.Context, scope *EnvScope) context.Context

WithEnvScope returns a context with the given EnvScope

Types

type BuiltinContext 

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

BuiltinContext contains scalar Dagu-managed context values for strict value references such as ${context.run.id} and compatibility aliases such as ${run.id}.

func NewBuiltinContext 

func NewBuiltinContext(values map[string]string) BuiltinContext

NewBuiltinContext returns a built-in context with the provided scalar values.

func (BuiltinContext) Value 

func (c BuiltinContext) Value(path string) (string, bool)

Value returns a scalar built-in context value.

type CommandContext 

type CommandContext struct {
	Target          CommandTarget
	Shell           []string
	ShellConfigured bool
}

CommandContext contains command execution facts used by semantic policies.

type CommandTarget 

type CommandTarget int

CommandTarget identifies where a command is executed. 

const (
	CommandTargetLocal CommandTarget = iota
	CommandTargetSSH
	CommandTargetDocker
)

type EnvEntry 

type EnvEntry struct {
	Key    string
	Value  string
	Source EnvSource
	Origin string // stepID for outputs, filepath for dotenv (optional metadata)
}

EnvEntry represents a single environment variable with metadata

type EnvScope 

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

EnvScope is an isolated, immutable environment scope for DAG loading/execution. It does NOT modify the global os.Env.

func GetEnvScope 

func GetEnvScope(ctx context.Context) *EnvScope

GetEnvScope retrieves the EnvScope from context. Returns nil if context is nil or no EnvScope is set.

func NewEnvScope 

func NewEnvScope(parent *EnvScope, includeOS bool) *EnvScope

NewEnvScope creates a new EnvScope, optionally inheriting from parent. If includeOS is true, it includes os.Environ() as the base layer.

func (*EnvScope) AllBySource 

func (e *EnvScope) AllBySource(source EnvSource) map[string]string

AllBySource returns all entries with the given source. This is useful for getting all secrets for masking, all params, etc.

func (*EnvScope) AllSecrets 

func (e *EnvScope) AllSecrets() map[string]string

AllSecrets returns all entries with EnvSourceSecret. This is a convenience method for output masking.

func (*EnvScope) AllUserEnvs 

func (e *EnvScope) AllUserEnvs() map[string]string

AllUserEnvs returns all entries excluding OS environment.

func (*EnvScope) Debug 

func (e *EnvScope) Debug() string

Debug returns a string representation for debugging

func (*EnvScope) EntriesWithoutOrigin added in v2.18.0 

func (e *EnvScope) EntriesWithoutOrigin(origin string) []EnvEntry

EntriesWithoutOrigin returns the effective entries except those carrying the given origin. Each entry keeps the source and origin metadata it holds in this scope, so provenance survives transport into another run's scope. When an excluded entry shadows a lower-precedence entry with the same name, the shadowed entry is still collected. The result is sorted by key for a stable representation.

func (*EnvScope) Expand 

func (e *EnvScope) Expand(s string) string

Expand expands ${VAR} and $VAR in s using this scope. Variables not found in the scope are preserved in their original form.

func (*EnvScope) ExpandPath 

func (e *EnvScope) ExpandPath(s string) string

ExpandPath expands ${VAR} and $VAR in the filesystem path s using this scope. A backslash in s is path text, never an escape marker. Variables not found in the scope are preserved in their original form.

func (*EnvScope) Get 

func (e *EnvScope) Get(key string) (string, bool)

Get retrieves a variable value, checking this scope then parent scopes.

func (*EnvScope) GetEntry 

func (e *EnvScope) GetEntry(key string) (EnvEntry, bool)

GetEntry retrieves the full entry with metadata, checking this scope then parent scopes.

func (*EnvScope) Provenance 

func (e *EnvScope) Provenance(key string) string

Provenance returns a human-readable description of where a variable came from. Returns empty string if the variable is not found.

func (*EnvScope) ToMap 

func (e *EnvScope) ToMap() map[string]string

ToMap returns all variables as a map, with child entries overriding parent entries.

func (*EnvScope) ToSlice 

func (e *EnvScope) ToSlice() []string

ToSlice returns all variables as KEY=value strings (for cmd.Env)

func (*EnvScope) ToSliceWithoutOrigin added in v2.15.4 

func (e *EnvScope) ToSliceWithoutOrigin(origin string) []string

ToSliceWithoutOrigin returns variables except entries from one origin.

func (*EnvScope) ToSliceWithoutOriginOrSources added in v2.17.0 

func (e *EnvScope) ToSliceWithoutOriginOrSources(origin string, sources ...EnvSource) []string

ToSliceWithoutOriginOrSources returns variables except those whose effective entry comes from one origin or from any of the given sources. Exclusion is decided on the entry that wins the scope chain, so a name shadowed by an excluded entry is dropped rather than falling back to the value it shadows. The result is sorted so callers that transmit or persist it produce a stable representation.

func (*EnvScope) WithEntries 

func (e *EnvScope) WithEntries(entries map[string]string, source EnvSource) *EnvScope

WithEntries returns a new EnvScope with the given entries added. The original scope is not modified (immutable).

func (*EnvScope) WithEntriesOrigin added in v2.15.4 

func (e *EnvScope) WithEntriesOrigin(entries map[string]string, source EnvSource, origin string) *EnvScope

WithEntriesOrigin returns a new scope with source and origin metadata.

func (*EnvScope) WithEntry 

func (e *EnvScope) WithEntry(key, value string, source EnvSource) *EnvScope

WithEntry returns a new EnvScope with the given entry added. The original scope is not modified (immutable).

func (*EnvScope) WithEntryOrigin 

func (e *EnvScope) WithEntryOrigin(key, value string, source EnvSource, origin string) *EnvScope

WithEntryOrigin returns a new EnvScope with the given entry and origin metadata. The original scope is not modified (immutable).

func (*EnvScope) WithEnvEntries added in v2.18.0 

func (e *EnvScope) WithEnvEntries(entries []EnvEntry) *EnvScope

WithEnvEntries returns a new scope holding the given entries as one layer. Each entry keeps the source and origin it already carries.

func (*EnvScope) WithStepOutputs 

func (e *EnvScope) WithStepOutputs(outputs map[string]string, stepID string) *EnvScope

WithStepOutputs returns a new EnvScope with step output variables added. The stepID is recorded as the origin for debugging.

type EnvSource 

type EnvSource string

EnvSource tracks where an environment variable came from (for debugging) 

const (
	EnvSourceOS        EnvSource = "os"              // From os.Environ()
	EnvSourceDAGEnv    EnvSource = "dag_env"         // From DAG env: field
	EnvSourceDotEnv    EnvSource = "dotenv"          // From .env file
	EnvSourceParam     EnvSource = "param"           // From params
	EnvSourceOutput    EnvSource = "output"          // From step output
	EnvSourcePresolved EnvSource = "presolved_build" // From presolved build env transport
	EnvSourceSecret    EnvSource = "secret"          // From secrets
	EnvSourceStepEnv   EnvSource = "step_env"        // From step.env field
)

type Field 

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

Field identifies the workflow value being resolved.

func AgentWorkingDirField 

func AgentWorkingDirField(path string) Field

AgentWorkingDirField returns the policy for agent working directory values.

func CommandScriptField 

func CommandScriptField(path string, command CommandContext) Field

CommandScriptField returns the policy for command executor scripts.

func ConditionCommandField 

func ConditionCommandField(path string, command CommandContext) Field

ConditionCommandField returns the policy for command condition values.

func ConditionEvalField 

func ConditionEvalField(path string) Field

ConditionEvalField returns the runtime policy for dynamic precondition values.

func ConditionRuntimeValueField 

func ConditionRuntimeValueField(path string) Field

ConditionRuntimeValueField returns the runtime policy for value-match condition text.

func ConditionValueField 

func ConditionValueField(path string) Field

ConditionValueField returns the policy for non-command condition values.

func ConstLoadField 

func ConstLoadField(path string) Field

ConstLoadField returns the policy for loading const declarations.

func ContainerEnvField 

func ContainerEnvField(path string) Field

ContainerEnvField returns the policy for container env entries.

func ContainerField 

func ContainerField(path string) Field

ContainerField returns the policy for container scalar values.

func CoordinatorArtifactBaseDirField 

func CoordinatorArtifactBaseDirField(path string) Field

CoordinatorArtifactBaseDirField returns the policy for coordinator artifact roots.

func DAGEnvCompletionField added in v2.18.2 

func DAGEnvCompletionField(path string) Field

DAGEnvCompletionField returns the policy for completing a DAG env entry that loading already resolved. Escapes applied at load are not applied again.

func DAGEnvField 

func DAGEnvField(path string) Field

DAGEnvField returns the policy for build-time DAG env entries.

func DAGShellField 

func DAGShellField(path string) Field

DAGShellField returns the policy for DAG shell values.

func DAGWorkingDirField 

func DAGWorkingDirField(path string) Field

DAGWorkingDirField returns the policy for DAG working directory values.

func DirectCommandField 

func DirectCommandField(path string, command CommandContext) Field

DirectCommandField returns the policy for command args executed directly.

func DotenvPathField 

func DotenvPathField(path string) Field

DotenvPathField returns the policy for dotenv path values.

func DynamicParamEvalField 

func DynamicParamEvalField(path string) Field

DynamicParamEvalField returns the policy for dynamic param eval values.

func ExecutorConfigField 

func ExecutorConfigField(path string) Field

ExecutorConfigField returns the policy for executor configuration objects.

func HostConfigObjectField 

func HostConfigObjectField(path string) Field

HostConfigObjectField returns the policy for host-side configuration objects.

func LogPathField 

func LogPathField(path string) Field

LogPathField returns the policy for log path values.

func ParallelItemField 

func ParallelItemField(path string) Field

ParallelItemField returns the policy for parallel item lists.

func ParallelItemParamField 

func ParallelItemParamField(path string) Field

ParallelItemParamField returns the policy for parallel item params.

func ParallelSubDAGField 

func ParallelSubDAGField(path string) Field

ParallelSubDAGField returns the policy for parallel sub-DAG child values.

func RepeatIntegerField 

func RepeatIntegerField(path string) Field

RepeatIntegerField returns the policy for repeat integer values.

func RetryIntegerField 

func RetryIntegerField(path string) Field

RetryIntegerField returns the policy for retry integer values.

func RuntimeDAGEnvField 

func RuntimeDAGEnvField(path string) Field

RuntimeDAGEnvField returns the policy for runtime DAG env entries.

func ServerBasePathField 

func ServerBasePathField(path string) Field

ServerBasePathField returns the policy for frontend server base paths.

func ShellCommandField 

func ShellCommandField(path string, command CommandContext) Field

ShellCommandField returns the policy for command strings executed through a shell.

func StaticValidationField 

func StaticValidationField(path string) Field

StaticValidationField returns the policy for static DAG validation.

func StepArtifactOutputField 

func StepArtifactOutputField(path string) Field

StepArtifactOutputField returns the policy for stdout/stderr artifact paths.

func StepDirField 

func StepDirField(path string) Field

StepDirField returns the policy for step working directory values.

func StepEnvField 

func StepEnvField(path string) Field

StepEnvField returns the policy for step env entries.

func StepShellField 

func StepShellField(path string) Field

StepShellField returns the policy for step shell values.

func StructuredOutputLiteralField 

func StructuredOutputLiteralField(path string) Field

StructuredOutputLiteralField returns the policy for structured literal output values.

func StructuredOutputPathField 

func StructuredOutputPathField(path string) Field

StructuredOutputPathField returns the policy for structured output source paths.

func SubDAGNameField 

func SubDAGNameField(path string) Field

SubDAGNameField returns the policy for sub-DAG names.

func SubDAGParamsField 

func SubDAGParamsField(path string) Field

SubDAGParamsField returns the policy for sub-DAG params.

func TemplateConfigField 

func TemplateConfigField(path string) Field

TemplateConfigField returns the policy for template executor configuration.

func TemplateScriptField 

func TemplateScriptField(path string) Field

TemplateScriptField returns the policy for scripts that executors such as template and js interpret as written.

func WorkflowField 

func WorkflowField(path string) Field

WorkflowField returns the policy for ordinary workflow scalar values.

func WorkflowObjectField 

func WorkflowObjectField(path string) Field

WorkflowObjectField returns the policy for ordinary workflow object values.

func (Field) HasStepRuntimeOutputReference 

func (f Field) HasStepRuntimeOutputReference(raw, stepID string) bool

HasStepRuntimeOutputReference reports whether raw, read as a value of the field, reads an attempt result from stepID.

func (Field) HasValueReference 

func (f Field) HasValueReference(raw string) bool

HasValueReference reports whether raw, read as a value of the field, contains a supported value-reference form.

func (Field) IsTemplateScript 

func (f Field) IsTemplateScript() bool

IsTemplateScript reports whether the field is a script passed to its executor as written rather than value-resolved.

func (Field) Key 

func (f Field) Key(key string) Field

Key returns the field that resolves the value under key in an object field.

func (Field) Path 

func (f Field) Path() string

Path returns the caller-visible field path used in validation errors.

func (Field) StepOutputReferences 

func (f Field) StepOutputReferences(raw string) []StepOutputReference

StepOutputReferences returns the braced step output references the field resolves in raw.

func (Field) WithPathKeys 

func (f Field) WithPathKeys(keys ...string) Field

WithPathKeys returns f for an object value whose listed keys name filesystem paths. A key such as "import.input_file" names a value nested in a map. A backslash in those values is path text, never an escape marker.

type Resolver 

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

Resolver resolves workflow values for semantic fields.

func NewResolver 

func NewResolver(static StaticScope, runtime RuntimeScope, opts ...ResolverOption) Resolver

NewResolver creates a resolver for the provided static and runtime scopes.

func (Resolver) Int 

func (r Resolver) Int(ctx context.Context, raw string, field Field) (int, error)

Int resolves raw according to field and converts the result to an integer.

func (Resolver) Object 

func (r Resolver) Object(ctx context.Context, obj any, field Field) (any, error)

Object resolves every string leaf in obj according to field.

func (Resolver) ResolveRef 

func (r Resolver) ResolveRef(ctx context.Context, token string, field Field) (string, error)

ResolveRef resolves an exact scoped reference to a non-empty string.

func (Resolver) String 

func (r Resolver) String(ctx context.Context, raw string, field Field) (string, error)

String resolves raw according to field.

type ResolverOption 

type ResolverOption func(*Resolver)

ResolverOption configures a Resolver.

func RejectUnqualifiedItemFields 

func RejectUnqualifiedItemFields() ResolverOption

RejectUnqualifiedItemFields makes resolution fail when a field resolved with foreach item scope contains ${<as>.<field>}, the current item's field written without the foreach namespace, and nothing else resolves it.

func WithValueReferenceNotices 

func WithValueReferenceNotices(sink ValueReferenceNoticeSink) ResolverOption

WithValueReferenceNotices reports unresolved value references to sink.

func WithoutCommandSubstitution 

func WithoutCommandSubstitution() ResolverOption

WithoutCommandSubstitution prevents resolver policies from executing command substitutions.

type RuntimeScope 

type RuntimeScope struct {
	Consts         Values
	Params         Values
	ParamsJSON     string
	Env            *EnvScope
	Steps          map[string]StepInfo
	Foreach        Values
	Inputs         Values
	Outputs        Values
	BuiltinContext BuiltinContext
}

RuntimeScope contains actual values available during runtime resolution.

type StaticScope 

type StaticScope struct {
	Consts Values
	Params Values
}

StaticScope contains declarations and contracts used by static validation.

type StepInfo 

type StepInfo struct {
	Stdout          string
	Stderr          string
	ExitCode        string
	Output          *string // nil = no output: configured; non-nil = captured value (may be "")
	Outputs         *string // nil = no outputs published; non-nil = compact JSON object
	DeclaredOutputs *string // nil = no declared file-based outputs published; non-nil = compact JSON object
}

StepInfo contains metadata about a step that can be accessed via property syntax.

type StepOutputReference 

type StepOutputReference struct {
	Expression string
	StepName   string
	Path       []string
}

StepOutputReference describes a step output reference in eval syntax.

func ParseStepOutputReferenceToken 

func ParseStepOutputReferenceToken(token string) (StepOutputReference, bool)

ParseStepOutputReferenceToken parses an exact Spec 007 reference token.

func StepOutputReferences 

func StepOutputReferences(raw string) []StepOutputReference

StepOutputReferences returns braced step output references found in raw.

type ValueReferenceNotice 

type ValueReferenceNotice struct {
	Message   string
	FieldPath string
	Token     string
	Reason    ValueReferenceNoticeReason
	Class     ValueReferenceNoticeClass
}

ValueReferenceNotice describes a supported value reference left unresolved.

type ValueReferenceNoticeClass 

type ValueReferenceNoticeClass string

ValueReferenceNoticeClass separates references that no run can resolve from references whose value simply does not exist yet. 

const (
	// NoticeClassDefect marks a reference the spec cannot resolve in its
	// declared scope, so no run can resolve it.
	NoticeClassDefect ValueReferenceNoticeClass = "defect"
	// NoticeClassRuntimeOnly marks a well-formed reference whose availability
	// depends on runtime values or lifecycle scope.
	NoticeClassRuntimeOnly ValueReferenceNoticeClass = "runtime_only"
)

type ValueReferenceNoticeCollector 

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

ValueReferenceNoticeCollector stores unique notices in insertion order.

func (*ValueReferenceNoticeCollector) Notices 

func (c *ValueReferenceNoticeCollector) Notices() []ValueReferenceNotice

Notices returns recorded notices in insertion order.

func (*ValueReferenceNoticeCollector) Report 

func (c *ValueReferenceNoticeCollector) Report(notice ValueReferenceNotice)

Report records notice unless the same field has already reported the same token.

type ValueReferenceNoticeReason 

type ValueReferenceNoticeReason string

ValueReferenceNoticeReason explains why a supported reference was preserved. 

const (
	ValueReferenceReasonUnknownStepID        ValueReferenceNoticeReason = "unknown_step_id"
	ValueReferenceReasonUnknownOutputName    ValueReferenceNoticeReason = "unknown_output_name"
	ValueReferenceReasonSelfReference        ValueReferenceNoticeReason = "self_reference"
	ValueReferenceReasonNamespaceUnavailable ValueReferenceNoticeReason = "namespace_unavailable"
	ValueReferenceReasonUnknownContextField  ValueReferenceNoticeReason = "unknown_context_field"
	ValueReferenceReasonUnknownEnvBinding    ValueReferenceNoticeReason = "unknown_env_binding"
	ValueReferenceReasonUnknownConstName     ValueReferenceNoticeReason = "unknown_const_name"
)

func (ValueReferenceNoticeReason) Class 

func (r ValueReferenceNoticeReason) Class() ValueReferenceNoticeClass

Class reports whether the reason describes a defect or a runtime-only value.

Reasons that name a missing step, output, or context field are defects. Reasons that only report an absent value are runtime-only, because a scope built for inspection carries far less than a scope built for a run.

type ValueReferenceNoticeSink 

type ValueReferenceNoticeSink interface {
	Report(ValueReferenceNotice)
}

ValueReferenceNoticeSink receives passive value-reference notices.

func SuppressStepOutputReferenceNotices 

func SuppressStepOutputReferenceNotices(sink ValueReferenceNoticeSink) ValueReferenceNoticeSink

SuppressStepOutputReferenceNotices drops generic notices for exact Spec 007 tokens.

type Values 

type Values map[string]any

func ValuesFromStrings 

func ValuesFromStrings(values map[string]string) Values

ValuesFromStrings converts string variables into binding values.

Source Files

View all Source files

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.