Documentation
¶
Overview ¶
path: nexssp/flow/nodes/bench.go
Benchmark nodes.
Design notes:
- bench.run captures the registry at construction. The registry is a live pointer, so actions registered after construction are visible at invoke time.
- Per-iteration work is a single time.Now / time.Since pair and a slice write. No maps, no reflection, no fmt on the measured path.
- Panic in a target counts as one error and does not abort the run. The defer is function-scoped so the compiler can open-code it.
- bench.save and bench.compare embed BenchRunRes so they chain directly from bench.run without a projection step in the flow.
- All caller-supplied paths go through kernel/xfs.Rel: absolute paths, ".." traversal, ":" (Windows ADS/drive), NUL and control characters, trailing dots, and reserved device names are rejected before any filesystem call.
path: nexssp/flow/nodes/distribute.go
Fan-out / fold primitives.
Contract — distribute.map:
Input : { "items": [ ...anything... ], "action": "...", "concurrency": N }
Output : { "items": [ {ok, result?, error?} ], "succeeded": N, "failed": M }
Order is preserved: output.items[i] corresponds to input.items[i]. This is achieved without a mutex or channel by pre-allocating two slices and writing to distinct slots from each goroutine.
Failure isolation: a failing sub-item does NOT abort its siblings. The error is stored in the slot. errgroup is used only for its bounded concurrency gate (SetLimit), not for error propagation.
Concurrency: the gate caps in-flight goroutines. This is the only backpressure a caller needs — memory and network are bounded by N.
Contract — distribute.reduce:
Input : { "items": [ {ok, result?, error?} ], "strategy": "..." }
Output : depends on strategy (see DistributeReduceRes).
path: nexssp/flow/nodes/log.go
Log nodes. Input is a map so a log node can be inserted anywhere in a pipeline without a projection: the previous node's output is logged as structured attributes and passed through unchanged.
Convention:
"message" : string — the log line (optional) other keys : any — structured attributes
Zero allocation when the level is disabled: slog.Default().Enabled is checked before any work is done.
path: nexssp/flow/nodes/saga.go
Index ¶
- Constants
- func DistributeMaxItemsForTest() int
- func NewBenchCompareAction() action.AnyAction
- func NewBenchRunAction(reg contracts.Registry) action.AnyAction
- func NewBenchSaveAction() action.AnyAction
- func NewDistributeMapAction(reg contracts.Registry) action.AnyAction
- func NewDistributeReduceAction() action.AnyAction
- func NewDynamicSaga(name string, steps []SagaStep) *action.Builder[any, any]
- func NewLogErrorAction() action.AnyAction
- func NewLogInfoAction() action.AnyAction
- func NewLogWarnAction() action.AnyAction
- func NewLoopAction(bodyAction action.AnyAction, untilCondition string, maxTurns int) (*action.BuiltAction[any, any], error)
- func NewProjectionAction(code string) (*action.BuiltAction[any, any], error)
- func NewPromptNode(cfg PromptConfig) action.AnyAction
- func NewSupervisorNode(name string, compiler contracts.PipelineCompiler) action.AnyAction
- type BenchCompareReq
- type BenchCompareRes
- type BenchMetric
- type BenchRunReq
- type BenchRunRes
- type BenchSaveReq
- type BenchSaveRes
- type ChildResult
- type ChildTask
- type DistributeItem
- type DistributeMapReq
- type DistributeMapRes
- type DistributeReduceReq
- type DistributeReduceRes
- type PromptConfig
- type PromptReq
- type PromptRes
- type SagaStep
- type SupervisorReq
- type SupervisorRes
Constants ¶
const ( LogInfoName = "log.info" LogWarnName = "log.warn" LogErrorName = "log.error" )
Variables ¶
This section is empty.
Functions ¶
func DistributeMaxItemsForTest ¶ added in v0.5.0
func DistributeMaxItemsForTest() int
DistributeMaxItemsForTest exposes the item cap so tests do not have to hard-code the same constant in two places. Production code reads distributeMaxItems directly.
func NewBenchCompareAction ¶ added in v0.5.0
func NewBenchRunAction ¶ added in v0.5.0
func NewBenchSaveAction ¶ added in v0.5.0
func NewDistributeMapAction ¶ added in v0.5.0
func NewDistributeReduceAction ¶ added in v0.5.0
func NewDynamicSaga ¶
NewDynamicSaga chains steps: each step's output feeds the next step's input. If a step fails, completed steps are compensated in LIFO order.
This is deliberately distinct from kernel/action.NewSaga, which runs every step against the same input. Here we need transformation chaining with rollback, which the flow DSL authors expect from `A -> B -> C` syntax.
func NewLogErrorAction ¶ added in v0.5.0
func NewLogInfoAction ¶ added in v0.5.0
func NewLogWarnAction ¶ added in v0.5.0
func NewLoopAction ¶
func NewProjectionAction ¶
NewProjectionAction compiles inline data shaping { key: expr } using precompiled expr bytecode. Supports standard expressions, JQ-style field prefixes ({ to: .user }), and root access ({ out: . }).
func NewPromptNode ¶
func NewPromptNode(cfg PromptConfig) action.AnyAction
NewPromptNode creates a reusable, pre-configured prompt template action.
func NewSupervisorNode ¶
func NewSupervisorNode(name string, compiler contracts.PipelineCompiler) action.AnyAction
NewSupervisorNode creates a main orchestrator node that compiles and controls child pipelines dynamically with panic isolation and leak protection.
Types ¶
type BenchCompareReq ¶ added in v0.5.0
type BenchCompareReq struct {
Baseline string `json:"baseline" validate:"required" usage:"Baseline JSON path (validated by xfs.Rel)"`
TolerancePct float64 `json:"tolerance_pct,omitempty" usage:"Allowed regression percent (default 5)"`
BenchRunRes
}
type BenchCompareRes ¶ added in v0.5.0
type BenchCompareRes struct {
Baseline string `json:"baseline"`
Pass bool `json:"pass"`
Regressions []string `json:"regressions,omitempty"`
Metrics map[string]BenchMetric `json:"metrics"`
}
type BenchMetric ¶ added in v0.5.0
type BenchRunReq ¶ added in v0.5.0
type BenchRunReq struct {
Action string `json:"action" validate:"required" usage:"Node name to benchmark"`
Iterations int `json:"iterations,omitempty" usage:"Timed iterations (default 50)"`
Warmup int `json:"warmup,omitempty" usage:"Discarded pre-runs (default 3)"`
Payload map[string]any `json:"payload,omitempty" usage:"Request passed to each invocation"`
}
type BenchRunRes ¶ added in v0.5.0
type BenchRunRes struct {
Action string `json:"action"`
Iterations int `json:"iterations"`
Warmup int `json:"warmup"`
Errors int `json:"errors"`
MinMs float64 `json:"min_ms"`
MaxMs float64 `json:"max_ms"`
MeanMs float64 `json:"mean_ms"`
P50Ms float64 `json:"p50_ms"`
P95Ms float64 `json:"p95_ms"`
P99Ms float64 `json:"p99_ms"`
RPS float64 `json:"rps"`
ElapsedMs int64 `json:"elapsed_ms"`
}
BenchRunRes is the measured distribution. All durations are milliseconds.
type BenchSaveReq ¶ added in v0.5.0
type BenchSaveReq struct {
File string `json:"file" validate:"required" usage:"Relative path to write (validated by xfs.Rel)"`
BenchRunRes
}
type BenchSaveRes ¶ added in v0.5.0
type BenchSaveRes struct {
File string `json:"file"`
Bytes int `json:"bytes"`
BenchRunRes
}
type ChildResult ¶
type DistributeItem ¶ added in v0.5.0
type DistributeItem struct {
OK bool `json:"ok"`
Result any `json:"result,omitempty"`
Error string `json:"error,omitempty"`
}
DistributeItem is the per-slot outcome. Rendered as JSON on the wire.
type DistributeMapReq ¶ added in v0.5.0
type DistributeMapReq struct {
Action string `json:"action" validate:"required" usage:"Node name to invoke for each item"`
Concurrency int `json:"concurrency,omitempty" usage:"Max in-flight invocations (default 4, max 256)"`
Items []any `json:"items" validate:"required" usage:"Items to fan out. Passed unchanged to Action."`
}
type DistributeMapRes ¶ added in v0.5.0
type DistributeMapRes struct {
Items []DistributeItem `json:"items"`
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
}
type DistributeReduceReq ¶ added in v0.5.0
type DistributeReduceReq struct {
Strategy string `json:"strategy" validate:"required,oneof=collect all_pass any_pass first_success count"`
Items []DistributeItem `json:"items" validate:"required"`
}
DistributeReduceReq consumes the output of distribute.map directly.
Strategies:
collect — return every result, in order, skipping failures all_pass — true iff every item succeeded; false otherwise any_pass — true iff at least one item succeeded first_success — first successful result (error if none) count — number of successes / failures
type DistributeReduceRes ¶ added in v0.5.0
type DistributeReduceRes struct {
Strategy string `json:"strategy"`
AllPass bool `json:"all_pass,omitempty"`
AnyPass bool `json:"any_pass,omitempty"`
Succeeded int `json:"succeeded,omitempty"`
Failed int `json:"failed,omitempty"`
Result any `json:"result,omitempty"`
Results []any `json:"results,omitempty"`
}
type PromptConfig ¶
type SupervisorReq ¶
type SupervisorReq struct {
Tasks []ChildTask `json:"tasks" validate:"required"`
}
type SupervisorRes ¶
type SupervisorRes struct {
Total int `json:"total"`
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
Results []ChildResult `json:"results"`
}