Documentation
¶
Overview ¶
Plik: flow/runner/config.go
Index ¶
- Variables
- func FormatDuration(d time.Duration) string
- func JSONMapView(value any) any
- func Preflight(ctx context.Context, cfg Config, src, name string) (*core.PreparedSource, error)
- func PrintInfo(w io.Writer, path, _ string, meta map[string]any, ast core.Expr) int
- func PrintInfoJSON(w io.Writer, path string, meta map[string]any, ast core.Expr) error
- func Run(ctx context.Context, cfg Config, path string, payload map[string]any, ...) int
- func RunAssertions(w io.Writer, result any, durationMS int64, actions, asserts []string, ...) int
- func RunSource(ctx context.Context, cfg Config, src, name string, payload map[string]any, ...) int
- func SplitPipelineModifiers(table *core.ModifierTable, mods []string) (wrapper, body []string)
- type Compilation
- type Config
- type EntryPoint
- type Execution
- type Host
- type HostOption
- type InfoShape
- type Observer
- type Opts
- type Record
- type SourcedModifier
Constants ¶
This section is empty.
Variables ¶
var ErrHostAlreadyRunning = errors.New("runner: host invocation is already running")
ErrHostAlreadyRunning is returned when another outer invocation is active.
var ErrHostInvocationRunning = errors.New("runner: host invocation is still running")
ErrHostInvocationRunning is returned when shutdown is requested before the outer invocation callback has completed.
var ErrHostShutdownStarted = errors.New("runner: host shutdown has started")
ErrHostShutdownStarted is returned when resources are adopted after the host has begun shutting down, or when Run is called on a closed host.
Functions ¶
func FormatDuration ¶ added in v0.10.0
FormatDuration handles Windows clock resolution limits cleanly without misleading '0ns' outputs.
func JSONMapView ¶ added in v0.10.0
JSONMapView applies JSON tags to struct outputs before expr evaluation.
func Preflight ¶ added in v0.17.0
Preflight preprocesses source once and returns a value for reuse in ExecutePrepared. Hosts use it to discover @schema declarations and pipeline modifiers before parsing argv, so command-line values can reach compile-time modifiers such as out.file:path=@config.output.
func PrintInfo ¶ added in v0.10.0
PrintInfo describes a .nflow file without executing it. It shows directives from meta, the sequence of atoms from the AST, and expected input.
func PrintInfoJSON ¶ added in v0.14.0
func RunAssertions ¶
func RunAssertions(w io.Writer, result any, durationMS int64, actions, asserts []string, verbosity int) int
RunAssertions ewaluuje @assert: z meta plus CLI --assert.
Env dostępny dla asercji:
result — output ostatniej akcji w pipeline duration_ms — całkowity czas wykonania actions — lista nazw wykonanych akcji
Verbosity < 1 → cisza przy sukcesie.
func RunSource ¶ added in v0.10.0
func RunSource(ctx context.Context, cfg Config, src, name string, payload map[string]any, opts Opts) int
RunSource executes workflow DSL directly from in-memory text.
It is a thin wrapper over Execute: it handles --info, installs the observer, prints the result, and evaluates @assert: directives. Every other piece of orchestration lives in Execute so the same pipeline runs across cli, selftest, and embedded binaries.
func SplitPipelineModifiers ¶ added in v0.14.0
func SplitPipelineModifiers(table *core.ModifierTable, mods []string) (wrapper, body []string)
SplitPipelineModifiers separates a pipeline header's modifiers into those that belong on the wrapper action and those that propagate to the pipeline body. Inheritable policy modifiers (:timeout, :retry, …) propagate; metadata modifiers (:tag, :status, :route, …) stay on the wrapper.
It is shared by compile-time pipeline materialization and callers that need the same wrapper-versus-body modifier split.
Types ¶
type Compilation ¶ added in v0.14.0
type Compilation struct {
Program action.AnyAction
Meta map[string]any
Resolver core.CapabilityResolver
}
Compilation is the result of compiling one source without invoking its workflow actions. Program is nil for declaration-only sources such as a file containing only @pipeline definitions.
type Config ¶ added in v0.10.0
type Config struct {
Resolver core.CapabilityResolver
Directives *core.DirectiveTable
Modifiers *core.ModifierTable
Operators *core.OperatorTable
Primaries *core.PrimaryExtensionTable
Materializers []core.Materializer
CompileOpts []core.CompileOption
// Hooks are applied to every resolver action and to the top-level
// program before execution. Callers that only want to see the
// result set this to nil.
Hooks []action.AnyHook
// EventSink, when non-nil, is wrapped by observe.Hook and appended
// to Hooks. Both paths end up on the execution-local resolver's
// actions; use either, or both.
EventSink observe.Sink
// MeasureAllocs wraps the compile and run phases of Execute with
// MemStats deltas so callers can attribute allocations to the
// compiler versus the runtime. ReadMemStats triggers a brief
// stop-the-world pause; leave false on production hot paths. This
// mirrors the same precedent as CompileDuration and RunDuration:
// Execute already reports per-phase diagnostics, and this is the
// allocation counterpart.
MeasureAllocs bool
// ArgSchemas is the merged per-action argument schema published by
// every mounted bundle. It is exposed so diagnostics (nflow lint
// today) can validate @{...} capability references without building
// the action tree. Build-time advisors are the runtime counterpart;
// this field makes the same checks reachable from a pure parse.
ArgSchemas map[string][]core.ArgFieldSpec
}
Config bundles all compiler tables, capability resolvers, and materializers for a run. It is passed explicitly to prevent mutable package-level state.
func BuildConfig ¶ added in v0.10.0
BuildConfig compiles bundles into execution configuration. It has ZERO knowledge of @require, URLs or module paths.
func (Config) PrimariesFor ¶ added in v0.14.0
func (c Config) PrimariesFor( meta map[string]any, parent ...core.PrimaryExtension, ) *core.PrimaryExtensionTable
PrimariesFor returns the parser primary table the compiler installs for a source that produced meta. Parent primaries, when supplied, are inserted between the base table and the source's own contributions, mirroring CompileReq.InheritedPrimaries.
Every call site that parses a source outside of CompileAction — nflow lint, nflow expand, and any future diagnostic tool — must go through this function. Reading cfg.Primaries directly is only correct for the base table, and doing so silently drops per-source primaries such as the macro engine. A linter that does this rejects a file the runtime accepts, which is exactly the class of "test and production disagree" bug the runner package exists to prevent.
Order of contribution:
- c.Primaries — the base table built at BuildConfig
- parent... — inherited from an outer source
- meta's OnPreprocess output — this source's own contributions
A MergeablePrimary in step 2 or 3 collapses with the same token in step 1 or 2. A plain primary collides and panics, which is the "duplicates fail loudly" rule.
type EntryPoint ¶ added in v0.17.0
type EntryPoint struct {
// Name is the action's registered name, e.g. "pipeline.pack".
Name string
// Payload is the typed request passed to the entrypoint.
Payload any
}
EntryPoint is a named action to invoke after compilation instead of the top-level program. Hosts that route CLI commands to named pipelines use it.
type Execution ¶ added in v0.10.0
type Execution struct {
Output any
Meta map[string]any
Resolver core.CapabilityResolver
CompileDuration time.Duration
RunDuration time.Duration
CompileAllocs uint64
CompileAllocBytes uint64
RunAllocs uint64
RunAllocBytes uint64
}
Execution is the outcome of one Execute call.
func Execute ¶ added in v0.10.0
func Execute(ctx context.Context, cfg Config, src, name string, payload map[string]any) (Execution, error)
Execute compiles and runs a .nflow source under the given configuration.
func ExecutePrepared ¶ added in v0.17.0
func ExecutePrepared( ctx context.Context, cfg Config, prepared *core.PreparedSource, entry EntryPoint, extraOpts ...core.CompileOption, ) (Execution, error)
ExecutePrepared compiles prepared source and invokes the named entrypoint. extraOpts are appended to cfg.CompileOpts for this invocation only, so hosts can inject argv-derived values with core.WithConfigMap without re-running directives.
type Host ¶ added in v0.15.0
type Host struct {
// contains filtered or unexported fields
}
Host owns bundle cleanup callbacks for one outer synchronous invocation. It is intentionally separate from Config so repeated Compile/Execute calls can safely share a configuration and its resources.
func NewHost ¶ added in v0.15.0
func NewHost(opts ...HostOption) *Host
NewHost creates an invocation host.
func (*Host) Own ¶ added in v0.15.0
Own transfers the bundle's cleanup callbacks to this host. Call it once for each constructed bundle instance, immediately after construction; bundle IDs are not identities and are deliberately not used for deduplication.
func (*Host) OwnAll ¶ added in v0.15.0
OwnAll transfers every bundle's cleanup callbacks to this host in slice order. Shutdown invokes all callbacks in reverse order, including callbacks on bundles sharing the same ID.
func (*Host) Run ¶ added in v0.15.0
Run is the outer synchronous lifetime for an invocation. It always shuts down after fn, joins cleanup errors after the primary error, and re-panics with the original panic value if fn panics.
func (*Host) Shutdown ¶ added in v0.15.0
Shutdown invokes every owned callback exactly once in reverse ownership order. Callbacks receive a fresh deadline context that retains values from ctx but is unaffected by its cancellation or deadline. Cleanup callbacks must cooperate with that context; Go cannot forcibly stop a callback that ignores cancellation without abandoning a goroutine.
type HostOption ¶ added in v0.15.0
type HostOption func(*hostOptions)
HostOption configures an invocation host.
func WithShutdownTimeout ¶ added in v0.15.0
func WithShutdownTimeout(timeout time.Duration) HostOption
WithShutdownTimeout sets the maximum time available to bundle cleanup. A non-positive timeout selects the conservative default.
type Observer ¶ added in v0.10.0
type Observer struct {
// contains filtered or unexported fields
}
Observer tracks every action that passes through the runtime.
func (*Observer) ActionNames ¶ added in v0.10.0
func (*Observer) PrintSummary ¶ added in v0.10.0
type SourcedModifier ¶ added in v0.14.0
type SourcedModifier struct {
Raw string
Source core.ModifierSource
}
SourcedModifier is a modifier together with the origin that produced it. SplitPipelineModifiersWithSources returns these so `nflow explain` can attribute modifiers to a pipeline or a profile.
func SplitPipelineModifiersWithSources ¶ added in v0.14.0
func SplitPipelineModifiersWithSources( table *core.ModifierTable, mods []string, sources []core.ModifierSource, ) (wrapper, body []SourcedModifier)
SplitPipelineModifiersWithSources is SplitPipelineModifiers with the per-modifier origin preserved. Sources must be parallel to mods; missing entries default to Kind "pipeline" with no label.
Source Files