provider

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

type Deps struct {
	// Runtime is the existing container port (internal/runtime, ADR-0032/0054): Create/Start/
	// Status/Stop/Remove/List. Required.
	Runtime containerrt.Runtime
	// OwnerKind is the kind whose engines this runtime runs (ADR-0152): every engine it creates carries it, and
	// Converge and Teardown act only on workers of this kind. Required.
	OwnerKind v1.Kind
	// Gateway is the ingress reverse-proxy (ADR-0013) — ProgramRoutes is replace-all; used only
	// when a Route is set. Optional: a nil gateway means an internal-only deployment (a provider
	// that declares a Route then is reported Ready but unexposed, with a logged warning).
	Gateway gateway.Gateway
	Logger  *slog.Logger
	// HTTPClient probes ReadinessProbe; nil ⇒ a node client bounded by ProbeTimeout.
	HTTPClient *http.Client
	// ProbeTimeout bounds one readiness probe (lake.engineProbeTimeout, ADR-0163); 0 ⇒ defaultProbeTimeout. Ignored
	// when HTTPClient is set.
	ProbeTimeout time.Duration
	// StorageRoot is the root of the engines' durable directories (ADR-0231); "" ⇒ no durable storage, so a spec with
	// Storage fails Invalid.
	StorageRoot string
	// Now is the clock ProviderSpec.MaxAge is measured with (ADR-0270); nil ⇒ time.Now.
	Now func() time.Time
}

type Descriptor struct {
	Name     string   // stable id, e.g. "kv", "blob", "ingress", "s3", "log-ingest"
	Kind     Kind     // built-in | add-on
	Port     string   // the contract: the port/interface name (e.g. "kvstore.KV"); "" for an infra provider with no function-facing port
	Bindings []string // how a function consumes it (e.g. ["spec.bindings.kv"]); nil for infra (ingress/egress)
	Summary  string   // one-line human description
}

type EnvDeps struct {
	Secrets  SecretResolver                       // ADR-0057 PDP-authorized secret resolution (nil ⇒ secrets unsupported)
	Store    store.Store                          // ConfigMap reads
	Identity func(v1.NamespaceName) auth.Identity // the secret-injector identity for the read
	Logger   *slog.Logger                         // nil-tolerated (the guarded-merge silently drops)
}

type Kind string

type ProviderRef struct {
	Namespace v1.NamespaceName
	Name      v1.ObjectName
}

type ProviderSpec struct {
	Ref       ProviderRef       // (namespace, name) — identity of the provider instance
	Image     string            // the curated engine image ref (ADR-0054 embedded set), e.g. funcd/runtime-duckdb
	Port      int               // the serving port the engine binds in its netns (e.g. 8080)
	Env       map[string]string // injected env (the ADR-0085 keypair, the engine token, config) — caller-assembled
	Readiness ReadinessProbe    // the engine's HTTP readiness probe
	Replicas  int               // pinned count (1 for a stateful single-writer engine); 0 is invalid here
	Resources ResourceSpec      // cpu/mem sizing (forward-compat, mirrors ADR-0086)
	// Route is OPTIONAL ingress exposure. Non-nil ⇒ program a gateway route once Ready (behind the
	// gateway's auth; eventually externally reachable). nil ⇒ INTERNAL-ONLY: no route is programmed;
	// the engine is reachable by in-platform clients via the published netns endpoint
	// (ProviderStatus.Address).
	Route *RouteSpec
	// Storage is OPTIONAL durable storage (ADR-0231); nil ⇒ the engine keeps nothing across re-creations.
	Storage *StorageSpec
	// EgressOnly is copied to the engine's WorkerSpec: nil means no fence (ADR-0269).
	EgressOnly []netip.AddrPort
	// MaxAge, when positive, makes Converge replace a running engine older than it, so a new one carries a fresh key
	// pair (ADR-0270). 0 ⇒ never replaced for age.
	MaxAge time.Duration
	// IssueEnv, when set, returns env issued with each engine as Converge creates it, laid over Env: a key pair valid
	// for that engine's life (ADR-0270 Decision 5). Only its keys are part of the spec an engine is compared by (#1195),
	// so a new key window replaces no engine, while gaining or losing a pair does.
	IssueEnv func() map[string]string
}

type ProviderStatus struct {
	Running  int    // engine replicas running
	Ready    bool   // the readiness probe passed
	Address  string // the engine's in-platform netns endpoint "host:port" — set when running (in-platform clients dial this)
	Endpoint string // the ingress path clients reach when a Route is programmed; "" if internal-only
	Reason   string // when not Ready, why (e.g. "EngineNotReady")
	Report   string // the ready replica's report (runtime.Instance.Report, ADR-0276); only the Lake reads it
}

type ReadinessProbe struct {
	Path         string // e.g. "/" (Quack's RPC endpoint answers 200 there); GET only
	ExpectStatus int    // e.g. 200
}

type ResourceSpec struct {
	CPU    string // e.g. "2" (cores); "" ⇒ unset
	Memory string // e.g. "4Gi"; "" ⇒ unset
}

type RouteSpec struct {
	ID         string // stable route id (e.g. "<ns>/<name>")
	PathPrefix string // the ingress path the engine is exposed at
	Host       string // optional host match ("" = any host)
}

type Runtime interface {
	Converge(ctx context.Context, spec ProviderSpec) (ProviderStatus, error)
	Teardown(ctx context.Context, ref ProviderRef) error
}

type SecretResolver = envresolve.SecretResolver

type StorageSpec struct {
	Path string // the mount path inside the engine, absolute
	UID  int
	GID  int
}

type Volumes interface {
	// Reclaim removes ref's directory; Conflict while a container of ref exists; nil when there is none.
	Reclaim(ctx context.Context, ref ProviderRef) error
	// List returns the engines of the runtime's owner kind that have a directory, sorted.
	List(ctx context.Context) ([]ProviderRef, error)
}