Documentation
¶
Index ¶
- Variables
- func EvaluateAssertions(result any, asserts []string, ...) []error
- func EvaluateAssertionsContext(ctx context.Context, result any, asserts []string, ...) []error
- func FormatDuration(d time.Duration) string
- func JSONMapView(value any) any
- func Preflight(ctx context.Context, cfg Config, src, name string) (*compiler.PreparedSource, error)
- func PrintInfo(w io.Writer, path, _ string, meta map[string]any, ast compiler.Expr) int
- func PrintInfoJSON(w io.Writer, path string, meta map[string]any, ast compiler.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 RunAssertionsContext(ctx context.Context, w io.Writer, result any, durationMS int64, ...) int
- func RunLean(ctx context.Context, source, name string, bundles []compiler.Bundle, ...) int
- func RunSource(ctx context.Context, cfg Config, src, name string, payload map[string]any, ...) int
- func SplitPipelineModifiers(table *compiler.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 EvaluateAssertions ¶ added in v0.27.0
func EvaluateAssertions(result any, asserts []string, localSymbols ...map[string]compiler.SymbolNamespace) []error
EvaluateAssertions evaluates assertions without rendering CLI output. It is shared with self-test so both paths use the same expression and symbol rules.
func EvaluateAssertionsContext ¶ added in v0.27.0
func EvaluateAssertionsContext(ctx context.Context, result any, asserts []string, localSymbols ...map[string]compiler.SymbolNamespace) []error
EvaluateAssertionsContext evaluates assertions without rendering output and preserves the caller's context.
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 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, localSymbols ...map[string]compiler.SymbolNamespace) int
RunAssertions evaluates every @assert expression against the run result and prints a per-assert pass/fail line.
Failures are tinted red when the output writer is a terminal. When at least one assert fails, a trailing "exit status: N" line reports the process exit code the CLI is about to return, so a caller scanning the tail of the output sees the outcome without inferring it from the individual ✗ marks.
func RunAssertionsContext ¶ added in v0.27.0
func RunAssertionsContext(ctx context.Context, w io.Writer, result any, durationMS int64, actions, asserts []string, verbosity int, localSymbols ...map[string]compiler.SymbolNamespace) int
RunAssertionsContext evaluates every @assert expression using the caller's execution context.
func RunLean ¶ added in v0.23.0
func RunLean(ctx context.Context, source, name string, bundles []compiler.Bundle, args []string) int
RunLean executes an embedded flow source using only the provided bundles. It contains zero CLI, testkit, or development dependencies.
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 *compiler.ModifierTable, mods []string) (wrapper, body []string)
Types ¶
type Compilation ¶ added in v0.14.0
type Compilation struct {
Program action.AnyAction
Meta map[string]any
Resolver compiler.CapabilityResolver
}
func CompileWithOptions ¶ added in v0.23.0
func CompileWithOptions(ctx context.Context, cfg Config, src, name string, opts ...compiler.CompileOption) (Compilation, error)
type Config ¶ added in v0.10.0
type Config struct {
Resolver compiler.CapabilityResolver
Directives *compiler.DirectiveTable
Modifiers *compiler.ModifierTable
Operators *compiler.OperatorTable
Primaries *compiler.PrimaryExtensionTable
Materializers []compiler.Materializer
CompileOpts []compiler.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 graph. Build-time advisors are the runtime counterpart;
// this field makes the same checks reachable from a pure parse.
ArgSchemas map[string][]compiler.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 ...compiler.PrimaryExtension, ) *compiler.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 Execution ¶ added in v0.10.0
type Execution struct {
Output any
Meta map[string]any
Resolver compiler.CapabilityResolver
CompileDuration time.Duration
RunDuration time.Duration
CompileAllocs uint64
CompileAllocBytes uint64
RunAllocs uint64
RunAllocBytes uint64
}
func ExecutePrepared ¶ added in v0.17.0
func ExecutePrepared( ctx context.Context, cfg Config, prepared *compiler.PreparedSource, entry EntryPoint, extraOpts ...compiler.CompileOption, ) (Execution, error)
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 compiler.ModifierSource
}
func SplitPipelineModifiersWithSources ¶ added in v0.14.0
func SplitPipelineModifiersWithSources( table *compiler.ModifierTable, mods []string, sources []compiler.ModifierSource, ) (wrapper, body []SourcedModifier)
Source Files