ops

Documentation

Overview

Package ops turns an Extension's "ops" surface into a hosting/operations provider: the deploy, status, logs, list, teardown (and optional provision) operations a provider like Cloudflare, Vercel, or Hetzner exposes. An ops surface is the same declarative-operation model as an API integration, with two additions that make a fleet of providers interchangeable: a small hosting CONTRACT (well-known operation names the operator surface can drive uniformly) and TARGETS (what the provider can host: a static site, a container, a VPS), so a deploy command can pick a provider that satisfies a goal.

The operation mechanics, credential resolution, role enforcement, and egress confinement are not reimplemented here: the handler translates its block into an integration block and delegates to the integration surface, so there is exactly one implementation of "run an authenticated, role-checked, egress-bounded operation flow". This package adds the contract and target classification on top.

Index

• Constants
• func RegisterWith(reg *extension.Registry, opts ...integrations.Option) error
• type Driver
  • func NewDriver(store resource.Store, loader *extension.Loader) *Driver
  • func (d *Driver) Observe(ctx context.Context, svc service.Service) (service.Observation, error)
  • func (d *Driver) Teardown(ctx context.Context, svc service.Service) error
• type Handler
  • func NewHandler(opts ...integrations.Option) *Handler
  • func (h *Handler) Capability() string
  • func (h *Handler) DeployTool(id string) mission.Tool
  • func (h *Handler) OnLoad(ctx context.Context, m extension.Mount) error
  • func (h *Handler) OnUnload(ctx context.Context, id string) error
  • func (h *Handler) Targets(id string) []service.Target
  • func (h *Handler) Tools(id string) []mission.Tool
• type Spec

Constants

const (
	OpStatus    = "status"    // report a workload's state
	OpLogs      = "logs"      // fetch a workload's logs
	OpList      = "list"      // list the provider's workloads
	OpTeardown  = "teardown"  // remove a workload
	OpProvision = "provision" // create raw compute (VPS providers)
)

Well-known hosting-contract operations beyond deploy. They are not required (a provider may expose only what it supports), but when present they are driven by these names so the operator surface and the agent treat every provider the same.

const OpDeploy = "deploy"

OpDeploy is the one operation every hosting provider must declare: it stands a workload up and (by convention) returns the provider's id and the live URL. The operator surface drives it by this name across providers.

Functions

func RegisterWith

func RegisterWith(reg *extension.Registry, opts ...integrations.Option) error

RegisterWith registers an ops-surface handler on an extension registry.

Types

type Driver

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

Driver supervises deployed workloads by running their provider's hosting-contract operations. It is the bridge from the provider-agnostic supervisor to a concrete provider: given a service, it resolves the extension that provider belongs to, loads it, and invokes the well-known "status" or "teardown" operation. The operation runs through the same governed transport, credential resolution, role check, and egress confinement every operation uses, so supervision is no more privileged than a deploy.

It speaks no provider protocol of its own. What a provider needs to re-address its workload (an account id, a project name, a server id) travels on the service's Address map, which the driver replays into the operation input verbatim.

func NewDriver

func NewDriver(store resource.Store, loader *extension.Loader) *Driver

NewDriver builds an ops-backed supervision driver. store is the resource store the extensions live in; loader resolves an extension's surfaces to callable tools (it must have the ops surface handler registered, the same loader the deploy path uses).

func (*Driver) Observe

func (d *Driver) Observe(ctx context.Context, svc service.Service) (service.Observation, error)

Observe runs the provider's "status" operation and reads the workload's health from the result. A provider that declares no status operation cannot be observed, which is not an error: the supervisor keeps the last known status and re-checks later.

func (*Driver) Teardown

func (d *Driver) Teardown(ctx context.Context, svc service.Service) error

Teardown runs the provider's "teardown" operation to remove the workload. A provider that declares no teardown operation cannot retire the workload itself: that is a terminal condition the operator must resolve (remove the workload by hand, then `flynn services rm`), reported rather than retried so the supervisor does not spin.

type Handler

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

Handler is the extension.Point for the "ops" surface. It validates the hosting contract and the provider's targets, then delegates the operation mechanics to an internal integration handler so credential, role, and egress handling live in one place. It is safe for concurrent use.

func NewHandler

func NewHandler(opts ...integrations.Option) *Handler

NewHandler builds an ops-surface handler. The options are the same integration options (transport, secrets, credentials, audit, limits, clock) and configure the internal operation engine, so an ops provider resolves credentials and enforces roles exactly as an API integration does.

func (*Handler) Capability

func (h *Handler) Capability() string

Capability is the surface key this handler serves.

func (*Handler) DeployTool

func (h *Handler) DeployTool(id string) mission.Tool

DeployTool returns the provider's deploy operation as a tool, or nil if the extension is not loaded. It is the entry point the operator surface invokes.

func (*Handler) OnLoad

func (h *Handler) OnLoad(ctx context.Context, m extension.Mount) error

OnLoad validates the ops block (the hosting contract and targets), then mounts its operations through the internal integration handler. A provider that declares no deploy operation, an unknown target, or a malformed operation flow is rejected at load rather than at first deploy.

func (*Handler) OnUnload

func (h *Handler) OnUnload(ctx context.Context, id string) error

OnUnload drops the operations and targets mounted for an extension. It is idempotent.

func (*Handler) Targets

func (h *Handler) Targets(id string) []service.Target

Targets reports the hosting targets an extension declared, so a deploy can pick a provider that can satisfy a goal.

func (*Handler) Tools

func (h *Handler) Tools(id string) []mission.Tool

Tools returns the provider's operations as tools, so the agent can drive a deploy in a goal run and the operator surface can call them directly.

type Spec

type Spec struct {
	// Targets are what this provider can host (static-site, container, vps), so a
	// deploy can select a provider that can satisfy a goal. Empty leaves it
	// unclassified.
	Targets []service.Target `json:"targets,omitempty"`
	// Operations are the provider's hosting operations, each a declarative flow, in the
	// same shape an integration surface uses. At least a "deploy" operation is required.
	Operations []integrations.Operation `json:"operations"`
}

Spec is the typed "ops" surface block of an Extension manifest. It is an integration's operation set plus the provider's hosting targets.