Extending Orchard on Orchard

Provider protocol

Mon, 01 Jan 0001 00:00:00 +0000

Provider protocol#

Orchard and its providers communicate using a line-oriented JSON protocol over stdio. This page defines the wire format. If you’re writing a provider, these are the exact bytes you need to read and write.

Framing: JSON Lines#

Every message is a single JSON object on its own line, terminated by \n. Readers split on \n, parse the line as one JSON value, and match it to a request by id.

Execution model

Mon, 01 Jan 0001 00:00:00 +0000

Execution model#

A provider is a process. Orchard starts it, talks to it, and stops it. This page documents that lifecycle in detail so you know exactly what your provider code has to handle.

One process per scenario#

In run mode, Orchard spawns one provider subprocess per provider declaration in the scenario. The process stays alive for the duration of the scenario, handles all actions routed to that provider, and receives shutdown at the end.

Schema and types

Mon, 01 Jan 0001 00:00:00 +0000

Schema and types#

A provider’s schema is its contract with Orchard. It describes what configuration the provider accepts, what action types it handles, and what each action’s attributes and outputs look like. Orchard uses the schema to type-check scenarios at plan time before a single action runs.

`ProviderSchema`#

{
 "name": "stripe",
 "version": "0.3.0",
 "protocol": "1",
 "config": {
 "api_key": { "type": "string", "required": true, "description": "..." }
 },
 "actions": {
 "charge": { ... },
 "refund": { ... }
 }
}

Field	Type	Description
`name`	`string`	Unique provider identifier. Users see this in error messages.
`version`	`string`	Provider version. Freeform string; use semver.
`protocol`	`string`	Wire protocol version. Must be `"1"` today.
`config`	`map[string]AttrSchema`	Attributes accepted in the `provider "name" { }` block.
`actions`	`map[string]ActionSchema`	Action types this provider handles, keyed by action type name.

`ActionSchema`#

{
 "description": "Execute a SQL statement and capture the first row",
 "attrs": {
 "query": { "type": "string", "required": true }
 },
 "outputs": { "type": "any" }
}

Field	Type	Description
`description`	`string`	Free-text description. Surfaced in docs and errors.
`attrs`	`map[string]AttrSchema`	Attributes the action accepts.
`outputs`	`AttrSchema` (optional)	Shape of what the action returns. Omit if the action has no outputs.

`AttrSchema`#

{
 "type": "string",
 "required": true,
 "default": "\"GET\"",
 "description": "HTTP method"
}

Field	Type	Description
`type`	`string`	Textual cty type expression. See below.
`required`	`bool`	Whether the attribute must be provided.
`default`	JSON raw	Optional default value, JSON-encoded cty. Applied when the attribute is omitted.
`description`	`string`	Free-text description.

Type expressions#

Types are written as cty type expressions in string form:

Writing a provider

Mon, 01 Jan 0001 00:00:00 +0000

Writing a provider in Go#

This page walks through building a small custom provider end-to-end. The provider, echo, has two actions:

echo — returns its input attributes as outputs.
randomize — takes a prefix and returns <prefix>-<random-hex>.

The source is tiny (~120 lines) but covers every part of the protocol: the schema subcommand, the RPC loop, method dispatch, and error handling.

Project layout#

orchard-echo/
├── go.mod
└── main.go

mkdir orchard-echo && cd orchard-echo
go mod init github.com/you/orchard-echo

No dependencies — this example talks JSON directly. Providers that want to use Orchard’s types can import github.com/pthm/orchard/pkg/protocol.

Publishing

Mon, 01 Jan 0001 00:00:00 +0000

Publishing a provider#

Once your provider works, users need a way to install and use it. Today that means: give them a binary and have them reference it by path. A registry is future work.

Consumption model#

Scenarios reference providers by source string:

required_providers {
 stripe = { source = "exec:./bin/orchard-stripe" }
}

The path is resolved relative to the scenario file that declares the provider. Absolute paths work too. The binary must be executable.

Extending Orchard on Orchard

Provider protocol

Provider protocol#

Framing: JSON Lines#

Execution model

Execution model#

One process per scenario#

Schema and types

Schema and types#

ProviderSchema#

ActionSchema#

AttrSchema#

Type expressions#

Writing a provider

Writing a provider in Go#

Project layout#

Publishing

Publishing a provider#

Consumption model#

`ProviderSchema`#

`ActionSchema`#

`AttrSchema`#