engine

type AttemptRecord struct {
	Status   int           `json:"status,omitempty"`
	Error    string        `json:"error,omitempty"`
	Duration time.Duration `json:"duration"`
	Wait     time.Duration `json:"wait,omitempty"`
}

type AuthPrompted struct {
	RunID, Path string // Path is the request node's path; "" for a standalone send
	Kind        string
	URL, Code   string
	Expires     time.Time
}

type Body struct {
	Text        string `json:"text,omitempty"`        // UTF-8 bodies
	Base64      string `json:"base64,omitempty"`      // other bodies
	JSON        any    `json:"json,omitempty"`        // parsed, when the body is JSON
	ParseErr    string `json:"parse_error,omitempty"` // the body claimed JSON but is not
	File        string `json:"file,omitempty"`        // a streamed download, or an uploaded file
	SHA256      string `json:"sha256,omitempty"`
	Size        int64  `json:"size"`
	RawSize     int64  `json:"raw_size,omitempty"`
	ContentType string `json:"content_type,omitempty"`
}

type DatasetRunner interface {
	Run(ctx context.Context, q dataset.Query) (dataset.Result, error)
}

type Deps struct {
	Lookup  Lookup
	Schemas SchemaChecker // nil: bodies are not checked or learned
	// Transports runs async requests, by protocol (nil → every protocol this
	// build speaks); tests pass fakes.
	Transports transport.Registry
	// GRPC makes gRPC calls (nil → the real client, grpcx.Run); tests pass fakes.
	GRPC GRPCRunner
	// Dataset runs dataset queries (nil → the real stores, dataset.Default); tests pass fakes.
	Dataset DatasetRunner
	Vault   *vault.Vault
	Environ []string // for the proxy fallback (HTTP_PROXY, …)
	DataDir func(collection model.ID) string
	Clock   func() time.Time
	NewID   func() string // ULIDs for runs and records
	// After waits like time.After (nil → time.After); tests pass a
	// controllable clock so delays and grace periods need no sleeping.
	After func(time.Duration) <-chan time.Time
	// Nodes returns a node type's runner (nil → nodes.Lookup); tests add
	// recording or blocking node types.
	Nodes func(model.NodeType) (nodes.Runner, bool)
	// Observe, when set, receives every event of every run as it is
	// emitted, in order, on the emitting goroutine under the run's emit
	// lock. It must return quickly and must not call back into the run.
	Observe func(Event)
	// UserAgent is the User-Agent requests send unless a setting or the
	// request names one ("" → "Flowi").
	UserAgent string
	// Traceparent, when set, returns the W3C traceparent header value for
	// the call made by node path ("" for a standalone send) of run runID.
	// It is added to outgoing requests that do not carry one already.
	Traceparent func(runID, path string) string
	// AuthTokens keeps OAuth 2.0 tokens between sends (nil: every send asks
	// the token endpoint again).
	AuthTokens *authx.TokenCache
	// Transport, when set, sends every HTTP attempt instead of the network (nil: the real one). A run played
	// back from a recording uses it.
	Transport http.RoundTripper
}

type Digest struct {
	RunID, Path, Node, Format, Text string
}

type Event interface{ EventName() string }

type GRPCRunner interface {
	Run(ctx context.Context, c grpcx.Call) (grpcx.Result, error)
}

type Header struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type HookChain struct {
	Pre, Post, Message []HookRef
}

type HookFinished struct {
	RunID, Path, Level, Phase, Step string
	Index, Depth                    int
	Status                          Status
	Duration                        time.Duration
	Diags                           diag.List
}

type HookRef struct {
	Level string // collection | folder | request | version
	Step  model.HookStep
}

type HookStarted struct {
	RunID, Path, Level, Phase, Step string
	Index, Depth                    int
}

type Hop struct {
	Status   int      `json:"status"`
	URL      string   `json:"url"`
	Location string   `json:"location"`
	Header   []Header `json:"headers,omitempty"`
	// Forwarded names the credential headers sent on to Location although
	// it is another origin, because http.redirect_credentials or
	// http.redirect_keep_headers allows it.
	Forwarded []string `json:"forwarded,omitempty"`
}

type Log struct {
	RunID, Path, Node, Message string
}

type Lookup interface {
	Collection(id model.ID) (model.Collection, bool)
	// Request and Flow resolve a reference made from collection from
	// (cross-collection references name their collection).
	Request(ref model.Ref, from model.ID) (model.Collection, model.Request, bool)
	Flow(ref model.Ref, from model.ID) (model.Collection, model.Flow, bool)
	// Settings resolves every layer for a request version in folder
	// (collection-relative, e.g. "requests/auth"), including the user,
	// workspace, environment-variable and flag layers.
	Settings(collection model.ID, folder string, version model.Settings) settings.Resolved
}

type MessageReceived struct {
	RunID, Path, RequestID string
	Seq                    int
	Message                RecordMessage
	Depth                  int
}

type NodeFinished struct {
	RunID, Path, Parent, Lane string
	Node, Type                string
	Status                    Status
	Handled                   bool
	Duration                  time.Duration
	Outputs                   map[string]any
	Diags                     diag.List
	Depth                     int
	// Reason says why a node was skipped by the person ("skipped by you");
	// "" otherwise, including a node skipped by its when.
	Reason string
}

type NodeStarted struct {
	RunID, Path, Parent, Lane string
	Node, Type, Name          string
	Depth                     int
}

type Overlay struct {
	Name string
	Ops  []model.OverlayOp
}

type Preview struct {
	Masked PreviewRequest
	Real   *PreviewRequest
	Diags  diag.List
}

type PreviewPart struct {
	Name, Value, File, ContentType string
}

type PreviewRequest struct {
	Method   string
	URL      string
	Headers  []Header
	BodyKind string
	Body     string
	File     string
	Parts    []PreviewPart
}

type Record struct {
	ID            string   `json:"id"`
	RunID         string   `json:"run_id"`
	CollectionID  model.ID `json:"collection_id"`
	RequestID     model.ID `json:"request_id"`
	RequestPath   string   `json:"request_path"`
	Version       string   `json:"version"`
	VersionSource string   `json:"version_source"` // pinned | preferred | default | highest
	// Overlay names the flowi overlay the request was sent with, if any.
	Overlay   string          `json:"overlay,omitempty"`
	At        time.Time       `json:"at"`
	Request   SentRequest     `json:"request"`
	Status    int             `json:"status"`
	Proto     string          `json:"proto,omitempty"`
	Header    []Header        `json:"headers,omitempty"`
	Body      Body            `json:"body"`
	Redirects []Hop           `json:"redirects,omitempty"`
	Timings   Timings         `json:"timings"`
	Attempts  []AttemptRecord `json:"attempts"`
	Outputs   map[string]any  `json:"outputs,omitempty"`

	// Kind is "async" for an async request; "" is an HTTP one. An async
	// record has Status 0, Request.Method is the protocol and Outcome says
	// how it ended. Body is the first message received (else the one sent).
	Kind     string          `json:"kind,omitempty"`
	Outcome  string          `json:"outcome,omitempty"`
	Messages []RecordMessage `json:"messages,omitempty"`

	// A gRPC record ("grpc" kind) is also message based: Messages holds the
	// request as sent and the responses, Header the response metadata, and
	// these the final status (its name, e.g. NOT_FOUND, and message) and the
	// trailers. Status stays 0.
	GRPCCode    string   `json:"grpc_code,omitempty"`
	GRPCMessage string   `json:"grpc_message,omitempty"`
	Trailers    []Header `json:"trailers,omitempty"`
}

type RecordCaptured struct {
	RunID, Path, Node string
	Depth             int
	Record            Record
}

type RecordMessage struct {
	Direction string    `json:"direction"` // sent | received
	At        time.Time `json:"at"`
	Headers   []Header  `json:"headers,omitempty"`
	Body      Body      `json:"body"`
	Key       string    `json:"key,omitempty"`
	Partition int32     `json:"partition,omitempty"`
	Offset    int64     `json:"offset,omitempty"`
	Sequence  uint64    `json:"sequence,omitempty"`
}

type RequestSchemer interface {
	RequestSchema(c model.Collection, r model.Request, version string) (schema map[string]any, ok bool)
}

type RequestSent struct {
	RunID, Path, RequestID, Version string
	RequestPath                     string // the saved request's path; "" for ad-hoc calls
	VersionSource                   string // pinned, preferred, default, highest
	Method, URL                     string
	Attempt                         int
	Depth                           int // 0 for the request being sent, >0 inside hook flows
}

type ResponseReceived struct {
	RunID, Path, RequestID string
	Status                 int
	Error                  string
	Duration               time.Duration
	Wait                   time.Duration // backoff before the next attempt, if any
	Attempt                int
	Depth                  int
	Outcome                string // async requests: ok, timeout or error (Status stays 0)
}

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

type RunAborted struct {
	RunID    string
	Reason   string // grace_period_exceeded
	Grace    time.Duration
	Inflight []string
}

type RunCancelled struct{ RunID string }

type RunFinished struct {
	RunID    string
	Status   Status
	Duration time.Duration
}

type RunInput struct {
	Collection    model.Collection
	Flow          model.Flow
	Env           string            // environment name; "" → defaults.environment
	PreferVersion string            // run preference; beats the flow's prefer_version
	Inputs        map[string]string // templates for the flow's declared inputs
	Seed          uint64            // 0 → a random seed, reported in the result
	Grace         time.Duration     // 0 → the run.grace setting
	// Only, when non-nil, runs just these top-level nodes (in flow order);
	// the rest are left out of the run and its report. Prior holds the
	// outputs of the nodes left out, as an earlier run reported them
	// (masked, so a secret in them reads as the mask), for the chosen nodes'
	// templates to read as nodes.<id>. Prior is read by a plain flow only,
	// not by a flow-level run: loop.
	Only  []string
	Prior map[string]map[string]any
	// Skip lists node ids (or node paths) that do not run this time: they
	// finish as skipped with the reason "skipped by you", wherever they are,
	// in every iteration of a loop. A skipped node whose id is in Prior keeps
	// those outputs ("hold"), so later steps read the old values; the
	// flow's variables come from PriorVars as for a partial run.
	Skip []string
	// Overlay is a flowi overlay (or a stack, "vip+slow") laid over every request step that names no overlay of
	// its own. A step's own overlay wins. "" lays none.
	Overlay string
	// PriorVars are the flow's variables as an earlier run ended (masked),
	// for the chosen nodes' templates to read as vars.<name>: a node left out
	// of a partial run may have set them.
	PriorVars map[string]any
}

type RunResult struct {
	RunID  string
	Seed   uint64
	Status Status
	// Diags are the unhandled failure's diagnostics and every warning.
	Diags diag.List
	Saved []string // files written (saved responses, values, digests)
	// Captured are the masked records of every call the run made, in the order they finished: what a HAR
	// file is written from. A hook flow's calls are included.
	Captured []Record
	// Report is the run's report; ReportFile where it was saved
	// (runs/<flow-id>/<run-id>.json in the workspace data dir).
	Report     report.Run
	ReportFile string
	// Err is a system failure that did not stop the run (a file could not
	// be saved).
	Err error
}

type RunStarted struct {
	RunID         string
	Kind          string
	FlowID        string
	FlowPath, Env string
	Overlay       string // the run-level flowi overlay, if any
	Seed          uint64
	At            time.Time
}

type SchemaChecker interface {
	Check(c model.Collection, r model.Request, version string, rec Record) diag.List
}

type SchemaMatcher interface {
	Match(c model.Collection, r model.Request, version string, status int, body any) (violations []SchemaViolation, found bool)
}

type SchemaViolation struct {
	Path    string
	Message string
}

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

type SendInput struct {
	Collection    model.Collection
	Request       model.Request
	Env           string // environment name; "" → defaults.environment; still "" → no environment
	PinnedVersion string
	PreferVersion string
	With          map[string]string // templates, rendered once against env and generators
	Hooks         model.HookControl
	Seed          uint64 // 0 → a random seed, reported in the result
	Save          string // "" → the responses.save setting

	// Overlay, when set, is laid over the resolved version before anything is
	// rendered or sent. What does not fit is reported as warnings.
	Overlay *Overlay
}

type SendResult struct {
	RunID  string
	Seed   uint64
	Status Status
	Record *Record        // nil when nothing was sent
	Vars   map[string]any // variables set by hooks
	Diags  diag.List
	Saved  []string // files written (saved responses)
	// Err is a system failure that did not stop the send (saving a
	// response or the cookie jar failed).
	Err error
}

type SentRequest struct {
	Method string   `json:"method"`
	URL    string   `json:"url"`
	Header []Header `json:"headers,omitempty"`
	Body   *Body    `json:"body,omitempty"`
}

type Status string

type Timings struct {
	DNS     time.Duration `json:"dns"`
	Connect time.Duration `json:"connect"`
	TLS     time.Duration `json:"tls"`
	TTFB    time.Duration `json:"ttfb"`
	Total   time.Duration `json:"total"`
}

type Warning struct {
	RunID string
	Diag  diag.Diagnostic
}