protocol

type ActionSchema ¶

type ActionSchema struct {
	Description string                `json:"description,omitempty"`
	Notes       string                `json:"notes,omitempty"`
	Attrs       map[string]AttrSchema `json:"attrs"`
	Outputs     *AttrSchema           `json:"outputs,omitempty"`
	Examples    []Example             `json:"examples,omitempty"`
}

ActionSchema describes one action type offered by a provider.

type AttrSchema ¶

type AttrSchema struct {
	Type        string          `json:"type"`
	Required    bool            `json:"required,omitempty"`
	Default     json.RawMessage `json:"default,omitempty"`
	Description string          `json:"description,omitempty"`
	// Path marks a string provider config attribute as a file path. A
	// relative value is resolved against the scenario file's directory
	// before Configure, the same as action `file` attributes and exec:
	// sources, so a scenario works from any working directory. Values
	// starting with ':' (special names like SQLite's :memory:) pass
	// through unchanged.
	Path bool `json:"path,omitempty"`
}

AttrSchema describes a single attribute or an output shape.

Type is a cty type expression in textual form ("string", "list(number)", "object({id=number, name=string})", "any"). It is parsed by CtyType.

Default is optional. When present, it carries a JSON-encoded cty value compatible with Type; the engine applies it when the attribute is omitted from an action body.

func (a AttrSchema) CtyType() (cty.Type, error)

type ConfigureParams ¶

type ConfigureParams struct {
	Config map[string]json.RawMessage `json:"config,omitempty"`
}

ConfigureParams carries the evaluated `provider "name" {}` block from the scenario, encoded as JSON-serialized cty values keyed by attribute name. Decoding back to cty values is the caller's responsibility using the type information from ProviderSchema.Config.

type ConfigureResult ¶

type ConfigureResult struct{}

ConfigureResult is the successful response to a configure call. Empty today; kept as a named type so providers can grow the response shape (observability hints, capability advertisements) without breaking the protocol.

type DescribeParams ¶

type DescribeParams struct{}

DescribeParams is the payload of a describe request. Empty today; the named type reserves room for future additions (capability negotiation, requested-schema filters) without bumping the protocol version.

type DescribeResult ¶

type DescribeResult struct {
	Schema ProviderSchema `json:"schema"`
}

DescribeResult returns the provider's full schema. Callers use it to validate action bodies and type-check output references.

type Error ¶

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Detail  string `json:"detail,omitempty"`
}

Error is a structured failure returned by a provider.

func (e *Error) Error() string

type Example ¶

type Example struct {
	Description string `json:"description,omitempty"`
	Code        string `json:"code"`
}

Example is a worked HCL snippet attached to a provider or action. It is carried in the schema so tooling — docs generation in particular — can render authoritative, schema-adjacent examples without a separate templates tree.

Code is the raw HCL as it should appear in documentation. Description is an optional one-line caption rendered above the snippet.

type ExecuteParams ¶

type ExecuteParams struct {
	Action string                     `json:"action"`
	Attrs  map[string]json.RawMessage `json:"attrs"`
	Undo   *UndoOptions               `json:"undo,omitempty"`
}

ExecuteParams is the payload of an execute request.

Attrs values are JSON-encoded cty values. The engine has already evaluated the HCL action body against the scenario's eval context, so attribute values are fully resolved.

Undo is set when Orchard will record an undo for this action: it has no `lifecycle { teardown { } }` block and doesn't opt out with `managed_teardown = false`. A provider that knows how to reverse the action returns ExecuteResult.Undo; one that doesn't ignores it.

type ExecuteResult ¶

type ExecuteResult struct {
	Outputs map[string]json.RawMessage `json:"outputs"`
	Undo    *Invocation                `json:"undo,omitempty"`
}

ExecuteResult is the payload of an execute response.

Outputs values are JSON-encoded cty values. They are made available to downstream nodes as `action.<provider>.<name>.<output>` references.

Undo, returned only when the request carried ExecuteParams.Undo, is the call that reverses this action. Orchard stores it in the run record and `orchard teardown` executes it.

type Invocation ¶ added in v0.3.0

type Invocation struct {
	Action string                     `json:"action"`
	Attrs  map[string]json.RawMessage `json:"attrs"`
}

Invocation is an action call to make later: one of the provider's own action types and its attributes, encoded as in ExecuteParams.

type ProviderSchema ¶

type ProviderSchema struct {
	Name        string                  `json:"name"`
	Version     string                  `json:"version"`
	Protocol    string                  `json:"protocol"`
	Description string                  `json:"description,omitempty"`
	Notes       string                  `json:"notes,omitempty"`
	Config      map[string]AttrSchema   `json:"config,omitempty"`
	Actions     map[string]ActionSchema `json:"actions"`
	Examples    []Example               `json:"examples,omitempty"`
}

ProviderSchema is the self-description a provider returns during initialize. It is also the parse target for schema.hcl files.

Description is rendered immediately after the page header and carries the provider's intro prose. Notes is rendered at the bottom of the page — the field exists so end-of-page caveats (runtime behaviour, limitations, migration notes) have a natural home without being tucked into the intro.

func MustParseHCL(src []byte) ProviderSchema

func ParseHCLSchema(src []byte, filename string) (ProviderSchema, error)

provider "name" {
  version  = "1"
  protocol = "1"

  config {
    attribute "dsn" { type = string, required = true }
  }

  action "sql" {
    attribute "query" { type = string, required = true }
    output { type = any }
  }
}

func (s ProviderSchema) ActionNames() []string

func (s ProviderSchema) Validate() error

type Request ¶

type Request struct {
	ID     int64           `json:"id"`
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
}

Request is a single message from Orchard to a provider.

Params is held as a raw JSON payload so that callers can unmarshal it into a method-specific struct (InitializeParams, ExecuteParams, ...) without the envelope needing to know about every method.

type Response ¶

type Response struct {
	ID     int64           `json:"id"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *Error          `json:"error,omitempty"`
}

Response is a single message from a provider back to Orchard. Exactly one of Result or Error is populated.

type ShutdownParams ¶

type ShutdownParams struct{}

ShutdownParams is the payload of a shutdown request. Empty today but named so fields (drain timeouts, final flush flags) can be added without a protocol version bump.

type ShutdownResult ¶

type ShutdownResult struct{}

ShutdownResult is the payload of a shutdown response.

type UndoOptions ¶ added in v0.3.0

type UndoOptions struct {
	// Requested is true when the action sets
	// `lifecycle { managed_teardown = true }`: return an undo even where
	// the provider wouldn't by default.
	Requested bool `json:"requested,omitempty"`
}

UndoOptions carries the scenario's say in automatic teardown.