model

type Arrow struct {
	From      string
	OnSuccess bool
	OnFailure bool
	On        []string
}

type Async struct {
	Protocol string // ws, sse, mqtt, kafka, amqp or nats
	Server   string // templated; e.g. mqtt://host:1883
	Channel  string // topic, subject, queue, or routing key
	Send     *AsyncSend
	Receive  *AsyncReceive
	// Binding is the protocol's own options (qos, key, exchange, …), in
	// file order; the allowed names depend on the protocol.
	Binding []KeyValue
}

type AsyncReceive struct {
	Count   int
	Timeout time.Duration
	// Match, when set, is an expression a message must satisfy to count.
	Match string
}

type AsyncSend struct {
	Body    Body
	Headers []KeyValue
}

type Auth struct {
	Type   string
	Params []KeyValue
}

type Blueprint struct {
	Meta
	Path string
	// Phase says which hooks of a request the blueprint's nodes can be: "pre"
	// or "post"; empty means post. It does not matter to a blueprint used to
	// make a flow.
	Phase  string
	Params []Param
	// Outcomes are the outcomes a request starts with when it is seeded from the blueprint (see Outcome): the
	// same list for the request's opening version, unless that already writes its own.
	Outcomes []Outcome
	Body     Flow
	File     string
}

type Body struct {
	JSON      string
	Text      string
	File      string
	Form      []KeyValue
	Multipart []Field
}

type Branch struct {
	ID    string
	Nodes []Node
}

type Case struct {
	When  string
	Nodes []Node
}

type Collection struct {
	Root         string
	Manifest     Manifest
	Folders      []Folder
	Environments []Environment
	Requests     []Request
	Flows        []Flow
	Blueprints   []Blueprint
	Overlays     []Overlay
}

type Dataset struct {
	// Driver is the store: postgres, mysql, mariadb or sqlite.
	Driver string
	// Server is the connection string, templated: a postgres:// or mysql:// URL, or for sqlite a file path
	// relative to the collection.
	Server string
	// Query is one SELECT (or WITH, VALUES, SHOW, EXPLAIN, DESCRIBE) statement. It is not templated: values go in
	// Params, which are sent to the store separately from the statement, so a value can never change what the
	// statement means.
	Query string
	// Params are the values of the query's placeholders, in order, templated. Placeholders are $1, $2 … for postgres
	// and sqlite, and ? for mysql, mariadb and sqlite.
	Params []string
	// Limit is the most rows kept; 0 means DefaultDatasetLimit. More rows than that are cut and the result says so.
	Limit int
}

type Dependency struct {
	ID   ID
	Name string
	Repo string // optional clone URL shown when the dependency is not mounted
}

type EnvVar struct {
	Name   string
	Value  string // the text form; for VarJSON, JSON text
	Secret bool
	// Kind says what Value is read as. "" is text. A number, a boolean or an object keeps its type when
	// the variable is used on its own, so {"n": {{env.count}}} sends a number and not "5".
	Kind VarKind
}

type Environment struct {
	Meta
	Vars []EnvVar
	File string
	// Colour marks the environment wherever it is chosen, so that one is not mistaken for another.
	// It is one of EnvColours(), or empty for the default; an unknown name is shown as the default.
	Colour string
	// Extends names the environment this one builds on: its plain variables apply unless this one sets the same name.
	// Secrets are not inherited, because a secret's value lives in the vault under the environment that declares it.
	Extends string
	// Scope is the vault scope of this environment's secrets. Empty means
	// the owning collection; global environments carry the workspace scope.
	Scope ID
}

type Exchange uint8

type Execution struct {
	MaxConcurrency int
	RateLimit      string
	HostRateLimits []KeyValue
	OnBranchError  string
}

type Extraction struct {
	Name   string
	From   string
	Path   string
	Header string
	Cookie string
	Regex  string
}

type Family string

type Field struct {
	Key   string
	Value any
}

type Flow struct {
	Meta
	// Tags label the flow for `flowi run --tag`; the tags of its folders apply as well.
	Tags          []string
	Path          string
	PreferVersion string
	Inputs        []Input
	Outputs       []Output // rendered when the flow ends, in this order
	Execution     Execution
	Run           *RunTill
	Nodes         []Node
	File          string
}

type Folder struct {
	Dir      string
	Settings Settings
	Hooks    Hooks
	// Order lists the names of the folder's entries (a request or flow without its
	// file suffix, or a sub-folder's name) in the order they are shown. Entries it
	// does not name follow, by name; a name that matches nothing is ignored.
	Order []string
	// Tags apply to every flow and request under the folder.
	Tags []string
	File string
}

type GRPC struct {
	// Server is grpc://host:port (plaintext), grpcs://host:port (TLS) or a bare
	// host:port; templated, e.g. {{env.api}}.
	Server string
	// Method is package.Service/Method.
	Method string
	// Body is the request message, as JSON (or text holding JSON).
	Body Body
	// Proto lists .proto files, relative to the collection. Empty: the schema
	// is asked of the server by reflection.
	Proto []string
	// Import lists the roots .proto imports are resolved against, relative to
	// the collection.
	Import []string
	// Receive says which messages of a server stream to keep; unused for a
	// unary call. Count 0 means 1 and Timeout 0 means 30s when it runs.
	Receive *AsyncReceive
	// Web makes the call over gRPC-Web: an HTTP POST to Server, which is then
	// an http:// or https:// address, for a proxy or gateway that speaks it.
	// It needs Proto files (such a proxy has no reflection) and a method that
	// does not stream from the client.
	Web bool
}

type HookControl struct {
	Mode string
	Skip []string
}

type HookStep struct {
	Flow   *Ref
	Inline []Node
}

type Hooks struct {
	Pre     []HookStep
	Post    []HookStep
	Message []HookStep
}

type ID string

type Input struct {
	Name    string
	Type    string
	Default string
}

type KeyValue struct {
	Key   string
	Value string
	// Description says what the entry is for; only requests keep it (query,
	// headers, variables).
	Description string
}

type Layout struct {
	Flow      ID
	Nodes     map[string]Point // manual positions by node id
	Collapsed []string         // collapsed action strips, by first node id
	File      string
}

type Manifest struct {
	Format int
	Meta
	DependsOn []Dependency
	// Variables are the collection's own values, read as {{collection_var.name}}
	// by its requests and flows. The selected environment overrides one of
	// the same name, so the value that differs per API (a base URL) can still
	// differ per environment.
	Variables []KeyValue
	Settings  Settings
	Hooks     Hooks
	File      string
}

type Meta struct {
	ID          ID
	Name        string
	Description string
}

type Mount struct {
	ID   ID
	Path string // as the user gave it; may start with "~"
}

type Node struct {
	ID          string
	Type        NodeType
	Name        string
	Description string
	Needs       []string
	// AfterFailureOf lists the steps of the same list whose failure starts this one. Needs and
	// AfterFailureOf are the arrows into a step: a name in Needs is an arrow taken when that step
	// succeeds, one in AfterFailureOf when it fails, one in both whichever way it ends. With neither,
	// the step follows the step before it, on success.
	AfterFailureOf []string
	// AfterOutcome lists "step:outcome" entries: the step starts this one when its request ends with that
	// outcome (one of the outcomes the request names, or success or failure).
	AfterOutcome []string
	// Unlinked says the step has no arrow into it: it does not follow the step before it. The arrow from that step
	// was taken away on purpose. It is ignored when the step has arrows of its own.
	Unlinked   bool
	When       string
	Concurrent bool
	OnError    string
	Timeout    time.Duration
	// Attach names a request or subflow node of the same list that this node is shown
	// with: the canvas draws them as one block. It is a view only; the run order is
	// the list order, as always.
	Attach string
	// AttachAt says where, around that request, the canvas draws the node: "above" or
	// "below" it in a stack, or "" beside it (before it in the list is drawn left of it,
	// after it right of it). Like Attach it is a view only.
	AttachAt string
	// Color is a colour from NodeColors the canvas draws the step in; "" for
	// the category's own. It is cosmetic: a run never reads it.
	Color string

	Request  *RequestCall
	Subflow  *SubflowCall
	Body     []Node
	Branches []Branch
	Then     []Node
	Else     []Node
	Cases    []Case
	// Values are what a set node writes, in order; a later one may read an
	// earlier one. A set node with a target (and no values) writes one
	// variable or request field instead.
	Values []SetValue
	Params []Field
}

type NodeType string

type Outcome struct {
	Name     string
	When     string
	Disabled bool // kept in the list, but never matched
	// Color is one of NodeColors, for the port and arrows of the outcome; "" is the outcome's own (green for
	// success, red for failure, blue for a named one). Description says what it is for, shown beside it.
	Color       string
	Description string
}

type Output struct {
	Name  string
	Type  string
	Value string
}

type Overlay struct {
	Name        string
	Description string
	Shared      []OverlayOp
	Requests    []RequestOverlay
	File        string
}

type OverlayOp struct {
	Verb  string
	Path  string
	Value any
	Was   any
}

type Param struct {
	Name        string
	Type        ParamType
	Description string
	Default     string
}

type ParamType string

type Point struct{ X, Y int64 }

type Ref struct {
	Collection string
	ID         ID
	Path       string
	// Param, set only inside a blueprint, names the blueprint parameter
	// that fills this reference when the blueprint is used; ID and Path are
	// then empty.
	Param string
}

type Request struct {
	Meta
	// Tags label the request; the tags of its folders apply as well.
	Tags      []string
	Path      string
	Operation string // the OpenAPI operationId of its first version; Arazzo steps refer to it
	Default   string
	Versions  []RequestVersion
	Hooks     Hooks
	File      string

	// Edit is the one dirty edit: an autosaved working copy of a version.
	// Runs, serve and the CLI ignore it; only the GUI sends it. EditBase is
	// the label of the version it started from.
	Edit     *RequestVersion
	EditBase string
	// EditOverlay names the flowi overlay the edit was made with laid over
	// its base version: the edit then shows the overlay's changes too, and the
	// window restores the overlay choice with it. "" when there was none.
	EditOverlay string
}

type RequestCall struct {
	Request Ref
	Version string
	// Overlay names a flowi overlay of the request's collection laid over the
	// version, "" for none.
	Overlay string
	// Open names a connection this step opens and leaves open for later steps
	// (an async request that can be kept open: WebSocket, MQTT 5, NATS); ""
	// for none. The step's own send and receive run on it.
	Open string
	// Over names a connection an earlier step opened: this step sends and
	// receives over it instead of connecting.
	Over string
	// Close ends the connection Over names once this step has run. A
	// connection still open when the run ends is closed then.
	Close   bool
	Hooks   HookControl
	With    []KeyValue
	Headers []KeyValue
	// Outcomes, when set, are this step's outcomes in place of the request version's own: the same request
	// can end in different ways in different flows. See Outcome.
	Outcomes []Outcome
}

type RequestOverlay struct {
	Request ID
	// Path is a readable hint at the request; Request is authoritative.
	Path string
	Ops  []OverlayOp
}

type RequestVersion struct {
	Label string
	// Name is a short title for the version ("Before the tax change"); the label
	// ("1.1") stays what it is called everywhere else. Docs is its description.
	Name    string
	Method  string
	URL     string
	Query   []KeyValue
	Headers []KeyValue
	Body    Body
	Extract []Extraction
	Assert  []string
	// Outcomes are the named ways the request can end (see Outcome). None (or an empty list): success and failure.
	Outcomes []Outcome
	Settings Settings
	Hooks    Hooks
	// Variables are the version's default values for {{var.name}}; the
	// environment's variable of the same name wins.
	Variables []KeyValue
	// Docs is the version's documentation, written as Markdown.
	Docs string
	// Auth, when set, signs or authenticates the request when it is sent: an
	// API key, Digest, OAuth 2.0 or 1.0a, AWS Signature v4, a signed JWT, Hawk
	// or a client certificate. The Authorization header of Headers is the
	// simple form of the same thing.
	Auth *Auth
	// Async, when set, makes this an async (message) request instead of an
	// HTTP one: Method, Query and Body are then unused.
	Async *Async
	// GRPC, when set, makes this a gRPC call instead of an HTTP request. The
	// version's Headers are the call's metadata; Method, URL, Query and Body
	// are unused.
	GRPC *GRPC
	// Dataset, when set, makes this a query of a data store instead of an HTTP
	// request. The version's Headers, Method, URL, Query and Body are unused.
	Dataset *Dataset
}

type RunTill struct {
	Until         string
	MaxIterations int
	MaxDuration   time.Duration
	Interval      time.Duration
}

type Schedule struct {
	Name       string // unique within the workspace; names the schedule in logs and commands
	Flow       string // a flow path or id
	Collection string // optional: a collection name or id when Flow is ambiguous
	Cron       string // five fields, or @hourly, @daily, …
	Env        string // environment name; "" uses defaults.environment
	Inputs     []KeyValue
	TZ         string // IANA zone name; "" is the machine's zone
	Disabled   bool
}

type SetValue struct {
	Name  string
	From  string
	Value any
	// Where, for From "response", is "body", "header", "cookie" or "status";
	// Path, Header, Cookie and Regex then say which part (a body regex wins
	// over the path).
	Where  string
	Path   string
	Header string
	Cookie string
	Regex  string
	Seed   int64
}

type Settings map[string]any

type SubflowCall struct {
	Flow Ref
	With []KeyValue
}

type VarKind string

type Workspace struct {
	Meta
	Collections []Mount
	Schedules   []Schedule
	Settings    Settings
	File        string
}