nodes

type Emitter interface {
	Log(node, message string)
	Warn(d diag.Diagnostic)
	Digest(node, format, text string)
}

type FuzzSubject struct {
	Body   any            // the good body, decoded JSON with numbers as json.Number
	Schema map[string]any // the stored request-body schema, nil when none is kept
}

type HTTPCall struct {
	Method, URL    string
	Headers, Query map[string]string
	Body           any
}

type HTTPResult struct {
	Response *Response
	Status   Status
	Diags    diag.List
}

type Lane struct {
	Label    string // "[3]", "b1", "then"
	Nodes    []model.Node
	OwnVars  bool // writes stay in the lane (batch iterations)
	OwnNodes bool // nodes.<id> stay in the lane (batch, run_till)
	Item     any
	Index    int
	HasItem  bool // item and index are in scope
}

type LaneOptions struct {
	Concurrency int    // lanes in flight; capped by the run-wide limit
	Wait        string // "all" (default), "any" or "first-success"
	LaneJars    bool   // give lanes their own cookie jars per http.cookies
}

type LaneResult struct {
	Status Status
	Vars   map[string]any
	Nodes  map[string]any
	Diags  diag.List
	First  bool
}

type Masker interface{ String(s string) string }

type MutableRequest struct {
	Mu        sync.Mutex
	Method    *string
	URL       *string
	Headers   map[string]string
	Query     map[string]string
	Body      *any           // replaces the whole body
	BodyPaths map[string]any // dot paths into a JSON body
	Cookies   map[string]string
}

type Outcome struct {
	Outputs map[string]any
	Diags   diag.List
	Status  Status
	// Outcomes are the names of the outcomes a request ended with (success, failure, the ones its version
	// names); empty for a step that is not a request, whose outcome follows its status.
	Outcomes []string
}

type Param struct {
	Name     string
	Kind     ParamKind
	Required bool
	Enum     []string
	Min, Max int64 // ParamInt bounds; 0 and 0 mean unbounded
	Doc      string
}

type ParamKind int

type Phase int

type RequestCall struct {
	Ref     model.Ref
	Version string
	Overlay string // a flowi overlay of the request's collection, "" for none
	// Open, Over and Close are the node's connection use (see model.RequestCall).
	Open, Over string
	Close      bool
	Hooks      model.HookControl
	With       map[string]any
	Headers    map[string]string
	// Outcomes are the step's own outcomes, in place of the version's (see model.RequestCall).
	Outcomes []model.Outcome
	// Body, when set, is sent in place of the request's own body (a fuzz case). A string is sent as text and
	// anything else as JSON.
	Body *any
}

type Response struct {
	Status int
	Header http.Header
	Body   any    // parsed JSON, or the text
	Text   string // the body as text (for regex extraction)
	Time   time.Duration
}

type Runner func(ctx context.Context, n model.Node, s *State) Outcome

type Runtime interface {
	// Lanes runs node lists (parallel branches, batch or run_till
	// iterations) under the run's concurrency and branch-error policies.
	// Results are in lane order.
	Lanes(ctx context.Context, lanes []Lane, o LaneOptions) []LaneResult
	Request(ctx context.Context, c RequestCall) Outcome
	Subflow(ctx context.Context, ref model.Ref, inputs map[string]any) Outcome
	HTTP(ctx context.Context, c HTTPCall) HTTPResult
	// Background sends c without waiting (webhook wait: false); failures
	// become FLW-RUN-016 warnings.
	Background(node string, c HTTPCall)
	Sleep(ctx context.Context, d time.Duration) error
	// StopRun ends the run: running steps finish, no step that has not
	// started will (a stop node). Stopped reports it, for loops.
	StopRun()
	Stopped() bool
	Now() time.Time
	RandomDuration(lo, hi time.Duration) time.Duration // seeded by the run
	// Report is the report so far of the whole run ("run") or of a
	// finished node, by id, as seen from the calling node.
	Report(of string) (report.Run, bool)
	// WriteFile writes under the run's data directory ("saved" or
	// "digests"). name is one or more "/"-separated segments, each a
	// plain file name; anything else wraps ErrFileName.
	WriteFile(dir, name string, data []byte, appendTo bool) (string, error)
	// CheckSchema checks what an earlier request step received against the
	// response schema kept for its request.
	CheckSchema(step string) SchemaCheck
	// FuzzSubject prepares a request step for fuzzing: its body as it would be sent, and the request-body schema
	// kept for it. An error says why the request cannot be fuzzed (it has no JSON body).
	FuzzSubject(ctx context.Context, c RequestCall) (FuzzSubject, error)
}

type SchemaCheck struct {
	Found      bool
	Request    string // the request's path, for messages
	Status     int
	Violations []SchemaViolation
}

type SchemaViolation struct {
	Path    string
	Message string
}

type Spec struct {
	Type    model.NodeType
	Group   string // Call, Data, Check, Control, Output
	Summary string
	Params  []Param
	// MapForm means every key that is not a Param is "<var>: template".
	MapForm bool
	// Typed lists the keys the codec reads into typed fields (request,
	// flow, with, body, branches, …); they are not Params.
	Typed []string
	Run   Runner
}

type State struct {
	Phase    Phase
	Path     string               // the node instance's path, e.g. users[2]/create
	Vars     *Vars                // vars.<name>
	Request  *MutableRequest      // overrides for the request; nil outside pre-hooks
	Response *Response            // nil before the response
	Cookies  []httpx.StoredCookie // the run's cookie jar, for extract from: cookie
	// Scope returns the template scope for the current state (vars,
	// request, response, env, secrets, …); it is rebuilt by the engine on
	// each call so nodes always see the latest values.
	Scope  func() template.Scope
	Emit   Emitter
	Masker Masker
	// Secret registers a value derived from a secret (a template result
	// that read secret.*), so it is masked wherever it appears later. Nil
	// means nothing is registered.
	Secret func(v any)
	// Runtime does what nodes cannot do alone; nil only in contexts
	// that need none of it.
	Runtime Runtime
}

type Status string

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