provider

type ActionPlanner ¶

type ActionPlanner interface {
	PlanAction(ctx context.Context, action string, attrs map[string]cty.Value) (Plan, error)
}

ActionPlanner is implemented by providers whose actions can be checked against external state, such as a database's schema. It's optional; the engine calls it, when present, for each action before a run starts (and during `orchard plan`), so problems surface before any action has side effects.

attrs are the action's evaluated attributes. Values that depend on other actions' outputs aren't known yet and are cty unknowns, of a known type where one can be inferred. PlanAction returns what it learned in a Plan; an error means the action is invalid.

A provider with nothing to check an action against (no snapshot at plan time) returns an error wrapping ErrNoSchema; the engine treats that as "unchecked", not as a failure.

type BuiltinFactory ¶

type BuiltinFactory func() Provider

BuiltinFactory constructs an unconfigured Provider. It is called each time a scenario declares the corresponding source — one instance per scenario — so factories should return fresh state rather than a shared singleton.

type Capture ¶

type Capture struct {
	// Kind names the body's format, e.g. "database" (pkg/dbschema).
	Kind string
	// Target identifies what was captured, without secrets, e.g.
	// "postgres/app_dev". `schema pull` uses it to avoid overwriting
	// one database's snapshot with another's.
	Target string
	// Body is the kind-specific JSON body.
	Body json.RawMessage
}

Capture is what a SchemaSource returns.

type InverseOptions ¶

type InverseOptions struct {
	// Requested is true when the action sets
	// `lifecycle { managed_teardown = true }`: record an undo even where
	// the provider wouldn't by default (a typed update of rows Orchard
	// didn't create).
	Requested bool
}

InverseOptions carries the scenario's say in automatic teardown.

type Invocation ¶

type Invocation struct {
	Action string
	Attrs  map[string]cty.Value
}

Invocation is an action call to make later: the action type and its already-evaluated attributes.

type Plan ¶

type Plan struct {
	// Outputs is the type of the action's outputs, or
	// cty.DynamicPseudoType (or the zero Type) when it can't say. A
	// concrete type lets references to the outputs be type-checked.
	Outputs cty.Type
	// Hints are non-fatal observations worth showing the author, such
	// as a foreign key set to a fixed value. `orchard plan` prints them.
	Hints []string
}

Plan is what an ActionPlanner learned about one action.

type PlanConfigurer ¶

type PlanConfigurer interface {
	PlanConfigure(ctx context.Context, config map[string]cty.Value, snap *snapshot.Snapshot) error
}

PlanConfigurer is implemented by providers that check actions at plan time from a snapshot, since `orchard plan` doesn't call Configure. PlanConfigure receives the provider's evaluated config and its snapshot (nil when there isn't one). It must not open connections or have other side effects.

type Provider ¶

type Provider interface {
	// Schema returns the provider's self-description. It must be
	// stable across a single process lifetime — the engine caches it
	// after Configure and uses it to validate action bodies.
	Schema() protocol.ProviderSchema

	// Configure initializes the provider with evaluated config values.
	// It is called exactly once, before any Execute calls. Providers
	// that require no configuration may ignore the argument.
	Configure(ctx context.Context, config map[string]cty.Value) error

	// Execute performs the named action with the given attribute map
	// and returns the action's outputs. The engine has already
	// validated attrs against the schema, so providers can assume
	// required fields are present and types match.
	Execute(ctx context.Context, action string, attrs map[string]cty.Value) (map[string]cty.Value, error)

	// Close releases any resources the provider holds (database
	// connections, subprocess handles, ...). It is called during
	// engine shutdown even if Configure failed, so implementations
	// must tolerate being called on a partially-initialized provider.
	Close() error
}

Provider executes actions and advertises the schema that describes them.

Lifecycle: after registration the engine calls Configure once with the evaluated `provider "name" {}` config from the scenario, then makes zero or more Execute calls, and finally calls Close during engine shutdown. Configure may be called with a nil/empty map when the provider declares no config attributes.

func NewBuiltin(source string) (Provider, error)

type PullOptions ¶

type PullOptions struct {
	// Schemas limits database providers to the named schemas
	// (namespaces). Empty means all. Providers without namespaces
	// ignore it.
	Schemas []string
}

PullOptions narrows what a SchemaSource captures.

type Registry ¶

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

Registry holds the set of providers available to an engine run, keyed by their scenario-local name (the alias chosen in `required_providers`). Two provider instances built from the same source can coexist under different names.

A Registry goes through three phases: providers are added with Register, then Configure is called to initialize each one with the config block from the scenario, then Execute dispatches actions to the right provider. Close tears everything down in reverse order.

func NewRegistry() *Registry

func (r *Registry) Close() error

func (r *Registry) Configure(ctx context.Context, configs map[string]map[string]cty.Value) error

func (r *Registry) Get(name string) (Provider, error)

func (r *Registry) Names() []string

func (r *Registry) PlanConfigure(ctx context.Context, configs map[string]map[string]cty.Value, snaps map[string]*snapshot.Snapshot) error

func (r *Registry) Register(name string, p Provider) error

required_providers {
  db = { source = "builtin/postgres" }
}

func (r *Registry) SetBaseDir(dir string)

func (r *Registry) ValidateConfigs(configs map[string]map[string]cty.Value) error

type SchemaSource ¶

type SchemaSource interface {
	PullSchema(ctx context.Context, opts PullOptions) (*Capture, error)
}

SchemaSource is implemented by providers that can capture the shape of the system they act on (a database's tables, later an API spec), for `orchard schema pull` to store as a snapshot. It's optional; providers that don't implement it are skipped by `schema pull`.

PullSchema is called after Configure. It must only read metadata, never data, and the capture must not contain connection details or secrets, since snapshots are committed.

type Undoer ¶

type Undoer interface {
	ExecuteUndo(ctx context.Context, action string, attrs map[string]cty.Value, opts InverseOptions) (outputs map[string]cty.Value, undo *Invocation, err error)
}

Undoer is implemented by providers that know how to undo some of their actions, so `orchard teardown` can clean them up without an explicit `lifecycle { teardown {} }` block (for instance, a typed insert is undone by deleting the row by its primary key). It's optional.

The engine calls ExecuteUndo in place of Execute when the action has no explicit teardown block and hasn't opted out with `managed_teardown = false`. It runs the action as Execute does and also returns the invocation that undoes it, or nil when there's no automatic undo; the engine stores it in the run record once the outputs pass validation. Returning the undo from the same call keeps what a provider learns while executing (a typed update's previous values, whether a key already existed) local to that call, so concurrent actions don't share state.