Documentation
¶
Overview ¶
Package taskgraph resolves and executes named cross-unit dependencies (dependencies.commands / dependencies.workflows) declared on custom commands and workflows. It builds a pkg/dependency.Graph from the transitive closure of declared dependency references and runs it via the same generic pkg/scheduler DAG engine already used by parallel/matrix `needs:` (pkg/workflow/control.go) and Terraform's dependencies.components (pkg/scheduler/adapters/terraform.go) — concurrent by default, with automatic dedup of identical (kind, name, parameters) references.
Index ¶
Constants ¶
const ( // KindCommand identifies a Ref that targets a named custom command. KindCommand = "command" // KindWorkflow identifies a Ref that targets a named workflow. KindWorkflow = "workflow" )
const ( FailWaitAll = "wait_all" FailFast = "fail_fast" FailBestEffort = "best_effort" )
Fail modes, mirroring pkg/workflow/control.go's ControlFailWaitAll/ControlFailFast/ ControlFailBestEffort exactly (same vocabulary, not re-exported to avoid pulling pkg/taskgraph's lean, execution-callback-only dependency surface into pkg/workflow's much larger one).
Variables ¶
var ( // ErrUnknownDependency is returned when a dependencies.commands/dependencies.workflows // entry references a name that does not resolve to any known command or workflow. ErrUnknownDependency = errors.New("unknown dependency") // ErrUnknownDependencyKind is returned when a Ref carries a Kind other than // KindCommand/KindWorkflow. ErrUnknownDependencyKind = errors.New("unknown dependency kind") // ErrMissingRunner is returned when Run is called without a CommandRunner/WorkflowRunner // configured for a Kind actually present in the dependency graph. ErrMissingRunner = errors.New("no runner configured for dependency kind") // ErrMissingLookup is returned when Run is called without a // CommandDependencyLookup/WorkflowDependencyLookup configured for a Kind actually // present in the dependency graph. ErrMissingLookup = errors.New("no dependency lookup configured for dependency kind") // ErrMissingRefMetadata is returned when the scheduler dispatches a graph node whose // Metadata["ref"] is missing or not a Ref -- an internal invariant violation (every node // is seeded with its own Ref in graphVisitor.visit), not an unknown Kind, so it gets its // own sentinel rather than reusing ErrUnknownDependencyKind. ErrMissingRefMetadata = errors.New("dependency graph node has no ref metadata") )
Functions ¶
func Run ¶
Run resolves the transitive dependency closure of direct (a command's or workflow's own dependencies.commands/dependencies.workflows entries) and executes it via the generic pkg/scheduler DAG engine -- the same engine already used for parallel/matrix `needs:` (pkg/workflow/control.go) and Terraform's dependencies.components (pkg/scheduler/adapters/terraform.go). Concurrent by default; two Refs with identical Kind/Name/File/Flags/Args collapse into a single executed node.
The overall fail mode is derived from direct entries' Fail field: best_effort if any direct entry sets it, else fail_fast if any direct entry sets it, else wait_all (the default -- every dependency runs to completion regardless of siblings' failures, and Run returns the combined error at the end). This derivation is run-wide, not per-entry: one direct dependency declaring `fail: best_effort` forgives the whole graph's failures, including siblings that declared no `fail:` at all (see UnitDependency.Fail's doc comment) -- swallowed failures are still logged at warn level below so they aren't silently invisible.
Types ¶
type Lookup ¶
Lookup returns the direct dependency Refs declared by a named command or workflow, so the graph builder can walk the transitive closure. Found=false means the name does not resolve to any known command/workflow at all (a hard error, not "has no dependencies" — that case returns an empty, non-nil-error slice with found=true).
type Option ¶
type Option func(*Options)
Option configures Options.
func WithCommandLookup ¶
WithCommandLookup supplies the callback used to resolve a KindCommand Ref's own nested dependencies (and to confirm the referenced command exists at all).
func WithCommandRunner ¶
WithCommandRunner supplies the callback that actually executes a KindCommand Ref.
func WithMaxConcurrency ¶
WithMaxConcurrency bounds how many dependency nodes run concurrently. Unset (zero) means unbounded -- concurrent by default, matching go-task's `deps:` default.
func WithWorkflowLookup ¶
WithWorkflowLookup supplies the callback used to resolve a KindWorkflow Ref's own nested dependencies (and to confirm the referenced workflow exists at all).
func WithWorkflowRunner ¶
WithWorkflowRunner supplies the callback that actually executes a KindWorkflow Ref.
type Options ¶
type Options struct {
// contains filtered or unexported fields
}
Options configures Run. Constructed via the With* functions below (Options pattern per project convention, since Run takes more than 2-3 logical dependencies).
type Ref ¶
type Ref struct {
Kind string
Name string
File string
Flags map[string]string
Args []string
Fail string
}
Ref identifies one dependency to resolve and run: a named command or workflow, optionally parameterized (Flags/Args) and, for workflows, an explicit File for cross-file resolution.
func RefsFromDependencies ¶
func RefsFromDependencies(deps schema.Dependencies) []Ref
RefsFromDependencies converts a schema.Dependencies' Commands/Workflows entries into Refs, the shared conversion needed by both custom-command and workflow call sites so neither package has to duplicate this mapping. Takes deps by value (not *schema.Dependencies) to keep every call site's fluent `x.Dependencies.OrEmpty()` chaining intact -- OrEmpty returns a value, and a pointer parameter here would force every caller to introduce an intermediate variable.
func (*Ref) NodeID ¶
NodeID returns the deterministic graph-node identity for a Ref. Two Refs with the same Kind/Name/File/Flags/Args always produce the same NodeID, so the graph builder collapses them into a single executed node (automatic dedup); any difference in parameters produces a distinct NodeID, so differently-parameterized invocations of the same command/workflow both execute.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package adapters wires pkg/taskgraph's generic dependency runner to specific integrations -- mirroring pkg/scheduler/adapters' role for the scheduler.
|
Package adapters wires pkg/taskgraph's generic dependency runner to specific integrations -- mirroring pkg/scheduler/adapters' role for the scheduler. |