provisioner

type Closer interface {
	Stop()
}

type HostRef struct {
	// HostID is the store-internal UUID of this host record. Used by
	// the caller to invoke SuspendHost or DestroyHost later.
	HostID string

	// URL is the base URL the gateway will proxy to. For Sprites and
	// Fly Machines it is the public host URL; for the local-subprocess
	// provider it is http://127.0.0.1:<port>.
	URL string

	// Transport is the fully-wired http.RoundTripper that injects
	// every header required to reach this host: the universal
	// capability-token (Authorization: Bearer) plus any provider-edge
	// auth (e.g. a provider-edge preview token). Consumers
	// construct an HTTP client as `hostclient.NewHTTP(ref.URL,
	// ref.Transport)` and stay agnostic to the auth chain shape.
	//
	// Non-nil. The provisioner builds the chain and validates its
	// pieces before returning.
	Transport http.RoundTripper

	// AuthToken is the bearer token baked into the host's clank-host
	// require-bearer middleware. Surfaced separately from Transport
	// for storage/logging purposes; the same value is already wired
	// into Transport for outbound requests.
	AuthToken string

	// AutoWake indicates the provider's URL wakes the underlying
	// compute on incoming traffic without an explicit API call. True
	// for Sprites and Fly Machines (Flycast); false for the local
	// subprocess. The gateway uses this to decide
	// whether a probe failure means "stale URL, re-resolve" (false) or
	// "edge will wake on retry" (true).
	// todo(ae): Leaky abstraction. The provisioner should instead always implement auto-wake.
	AutoWake bool

	// Hostname is the stable identifier surfaced to upper layers
	// (session metadata, hub catalog). Stable across stop/resume of
	// the same underlying host.
	Hostname string
}

type Provisioner interface {
	// EnsureHost resolves (or creates, or wakes) the persistent host
	// for userID. Idempotent across calls within a daemon lifetime AND
	// across daemon restarts (state survives via the underlying
	// store). Returns a HostRef pointing at a host that has just
	// passed a readiness probe.
	EnsureHost(ctx context.Context, userID string) (HostRef, error)

	// SuspendHost issues a cooperative suspend on the underlying
	// compute (Sprite hibernate, Machine stop, etc.) so the user's
	// workspace stops billing for compute. State is preserved; a
	// subsequent EnsureHost wakes it.
	//
	// Idempotent: suspending an already-stopped host is not an error.
	SuspendHost(ctx context.Context, hostID string) error

	// DestroyHost permanently deletes the underlying compute and
	// removes the store row. Used for explicit account/workspace
	// teardown. Out-of-band deletion at the provider is detected
	// inside EnsureHost (NotFound from Get) and handled there; callers
	// don't need to invoke DestroyHost for that case.
	DestroyHost(ctx context.Context, hostID string) error

	// DestroyHostsByUser destroys every host this provider holds for
	// userID — the account-erasure counterpart to DestroyHost. It tears
	// down compute and store rows unconditionally (a busy session must
	// not block a GDPR deletion), and is idempotent: a user with no
	// hosts returns nil. The hosts table is UNIQUE(user_id, provider),
	// so a single provider has at most one host per user; a multi-
	// provider control plane implements this over its own store and
	// loops every provider row.
	DestroyHostsByUser(ctx context.Context, userID string) error

	// GetHostByID is the non-mutating counterpart to EnsureHost:
	// resolve a host_id (from a stored row, e.g. preview_routes.host_id)
	// to its current HostRef without provisioning, waking, or creating
	// anything. Used by the preview-route proxy to resolve a token's
	// target host before tunneling — the proxy mustn't wake hosts as
	// a side effect of someone hitting a stale URL.
	//
	// Returns hoststore.ErrHostNotFound (wrapped) when no row matches.
	GetHostByID(ctx context.Context, hostID string) (HostRef, error)

	// OpenInternalConn returns a net.Conn to (hostID, port) inside
	// the provider's private network. For Sprites this is the WSS
	// proxy at api.sprites.dev/v1/sprites/{name}/proxy; for the local
	// provisioner it's a direct dial to 127.0.0.1:port; for providers
	// without such a primitive it's ErrUnsupported.
	//
	// Used by pkg/gateway/previewtunnel to fan out preview-app
	// traffic to per-worktree dev servers running on private ports.
	// The returned conn is single-shot — Close releases the tunnel —
	// but the caller (stdlib http.Transport) handles pooling.
	OpenInternalConn(ctx context.Context, hostID string, port int) (net.Conn, error)
}

type Template struct {
	DisplayName string `json:"display_name"`
	CloneURL    string `json:"clone_url"`
}