backend

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

type Backend interface {
	// Provision starts async provisioning of a resource.
	// The backend will call the callback URL when provisioning completes.
	Provision(ctx context.Context, req ProvisionRequest) error

	// GetInfo returns lease information including connection details.
	// Returns ErrNotProvisioned if the lease is not yet provisioned.
	GetInfo(ctx context.Context, leaseUUID string) (*LeaseInfo, error)

	// Deprovision releases resources for a lease. Must be idempotent.
	Deprovision(ctx context.Context, leaseUUID string) error

	// ListProvisions returns all currently provisioned resources.
	// Used by the reconciler for orphan detection.
	ListProvisions(ctx context.Context) ([]ProvisionInfo, error)

	// LookupProvisions returns provision info for the requested lease UUIDs.
	// Missing leases are simply absent from the returned slice (not an error).
	// Used by the /workloads endpoint to fetch metadata for a known set of leases
	// without scanning the full provisions corpus. Caller is responsible for
	// enforcing MaxLookupUUIDs; implementations may also enforce it defensively.
	//
	// Named LookupProvisions (not GetProvisions) to avoid visual ambiguity with
	// the existing singular GetProvision.
	LookupProvisions(ctx context.Context, leaseUUIDs []string) ([]ProvisionInfo, error)

	// Health checks if the backend is reachable and healthy.
	// Returns nil if healthy, error otherwise.
	Health(ctx context.Context) error

	// RefreshState synchronizes in-memory provision state with the
	// underlying infrastructure. Backends should query the real
	// container/VM state and update their internal tracking.
	// Called by the reconciler before ListProvisions to avoid stale reads.
	RefreshState(ctx context.Context) error

	// GetProvision returns status information for a single provision.
	// Returns ErrNotProvisioned if the lease is not found.
	GetProvision(ctx context.Context, leaseUUID string) (*ProvisionInfo, error)

	// GetLogs returns container logs for a provisioned lease.
	// The tail parameter limits the number of log lines per container.
	// Returns ErrNotProvisioned if the lease is not found.
	GetLogs(ctx context.Context, leaseUUID string, tail int) (map[string]string, error)

	// Restart restarts containers for a lease without changing the manifest.
	// Returns ErrNotProvisioned if lease not found, ErrInvalidState if not restartable.
	Restart(ctx context.Context, req RestartRequest) error

	// Update deploys a new manifest for a lease, replacing containers.
	// Returns ErrNotProvisioned if lease not found, ErrInvalidState if not updatable.
	Update(ctx context.Context, req UpdateRequest) error

	// Restore re-provisions a new lease from the retained volumes of a prior
	// soft-deleted lease (ENG-325). Returns ErrNotRetained if no retained data
	// exists for FromLeaseUUID, ErrInvalidState if the target lease is not in
	// a valid state for restore, ErrValidation for bad inputs.
	Restore(ctx context.Context, req RestoreRequest) error

	// ReconcileCustomDomain reapplies the per-LeaseItem custom_domain values
	// from chain onto the running provision. When any item's CustomDomain
	// differs from the in-memory provision state, the backend snapshots the
	// current values, updates them, and triggers a Restart() to re-emit
	// Traefik labels. On Restart failure the in-memory state is rolled back
	// so the next reconciler tick can retry.
	//
	// No-op when:
	//   - the lease is not provisioned by this backend (silent),
	//   - the provision is not currently active,
	//   - all items already match the incoming values.
	//
	// Idempotent: repeated calls with the same items list produce no
	// container churn beyond the first reconciling call.
	ReconcileCustomDomain(ctx context.Context, leaseUUID string, items []LeaseItem) error

	// GetReleases returns the release history for a lease.
	// Returns ErrNotProvisioned if lease not found.
	GetReleases(ctx context.Context, leaseUUID string) ([]ReleaseInfo, error)

	// GetLoadStats returns the backend's current resource-load snapshot,
	// used for least-loaded provision routing. Implementations that do not
	// track load may return a snapshot whose CPUAllocatedRatio is not ok.
	GetLoadStats(ctx context.Context) (*LoadStats, error)

	// ListRetentions returns the leases whose data this backend currently
	// retains (soft-deleted, awaiting restore or grace-reap). Used by the
	// reconciler to keep placement affinity for retained leases (ENG-333).
	// Backends without retention (e.g. k3s) return an empty slice.
	ListRetentions(ctx context.Context) ([]RetainedLease, error)

	// Name returns the backend's configured name.
	Name() string
}

type BackendEntry struct {
	Backend   Backend
	Match     MatchCriteria
	IsDefault bool
}

type BackendHealth struct {
	Name    string `json:"name"`
	Healthy bool   `json:"healthy"`
	Error   string `json:"error,omitempty"`
	// Fenced means the operator fenced this backend, so it is unhealthy by
	// configuration and was not asked.
	Fenced bool `json:"fenced,omitempty"`
	// contains filtered or unexported fields
}

type BackendStorageIdentityResolver interface {
	ExpectedBackendStorageIdentity(string) (backendidentity.ID, bool)
}

type BootstrapInventoryClient interface {
	Name() string
	ListProvisionsWithIdentity(context.Context) ([]ProvisionInfo, backendidentity.ID, error)
	ListRetentionsWithIdentity(context.Context) ([]RetainedLease, backendidentity.ID, error)
}

type CallbackPayload struct {
	// MaintenanceID identifies an exact restart/update completion. It is
	// authenticated in the body and matched to the provider's pending command;
	// ordinary lifecycle observations omit it.
	MaintenanceID string `json:"maintenance_id,omitempty"`
	// MaintenanceAdmittedAt echoes the provider's admission stamp of that
	// command (RFC 3339, UTC), so a stale completion of a reused key cannot
	// settle the provider's newer command. Omitted when the command was
	// unstamped.
	MaintenanceAdmittedAt string         `json:"maintenance_admitted_at,omitempty"`
	LeaseUUID             string         `json:"lease_uuid"`
	Status                CallbackStatus `json:"status"` // "success", "failed", or "deprovisioned"
	Error                 string         `json:"error,omitempty"`
	// BackendStorageID binds the observation to the backend storage lineage
	// that produced it. Upgraded senders persist this value with new outbox
	// entries and include it in the HMAC-covered body on every delivery.
	BackendStorageID string `json:"backend_storage_id,omitempty"`
	// Backend is optional sender metadata retained for bounded metrics on
	// callbacks that have no current operation. It is not lifecycle authority:
	// the exact HMAC-authenticated operation URL or durable lifecycle capability
	// selects the store-authoritative backend.
	Backend string `json:"backend,omitempty"`
	// OperationID is injected by fred's callback HTTP endpoint from the
	// HMAC-authenticated callback URL. Backends need only POST to the URL they
	// received; they do not interpret or echo the token in their JSON body.
	OperationID string `json:"operation_id,omitempty"`
	// LifecycleID is likewise injected from an authenticated lifecycle callback
	// URL. A provider overwrites either body field before application so backend
	// JSON can never mint callback authority.
	LifecycleID string `json:"lifecycle_id,omitempty"`
	// Retained is set true on a deprovisioned callback when the backend actually
	// soft-deleted (retained) the lease's volumes. Best-effort ground truth for
	// the optimistic push; the queryable retention status is the durable backstop.
	Retained bool `json:"retained,omitempty"`
}

type CallbackStatus string

type ConnectionConfig struct {
	Name              string
	BaseURL           string
	Secret            string
	Timeout           time.Duration
	TLSCAFile         string
	TLSSkipVerify     bool
	TLSClientCertFile string
	TLSClientKeyFile  string
}

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

type DeprovisionRefusal uint8

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

type HTTPClientOptions struct {
	MaxIdleConns        int // Max idle connections across all hosts (default: 100)
	MaxIdleConnsPerHost int // Max idle connections per host (default: 10)

	// Circuit breaker settings
	CBMaxRequests   uint32        // Max requests in half-open state (default: 1)
	CBInterval      time.Duration // Interval to clear counts in closed state (default: 0, never clear)
	CBTimeout       time.Duration // Time to wait before transitioning from open to half-open (default: 60s)
	CBFailureThresh uint32        // Number of failures to trip the breaker (default: 5)

	// Response body size limits (0 = use default). Defense-in-depth caps to prevent
	// a buggy or misrouted backend from pressuring memory with unbounded responses.
	MaxInfoBytes             int64 // GetInfo response limit (default: 1 MiB)
	MaxProvisionBytes        int64 // GetProvision response limit (default: 1 MiB)
	MaxProvisionsBytes       int64 // ListProvisions response limit (default: 8 MiB)
	MaxLookupProvisionsBytes int64 // LookupProvisions response limit (default: 8 MiB)
	MaxLogsBytes             int64 // GetLogs encoded response limit (default: MaxProjectedLogsResponseBytes)
	MaxReleasesBytes         int64 // GetReleases response limit (default: 48 MiB projected response)
	MaxStatsBytes            int64 // GetLoadStats response limit (default: 1 MiB)
	MaxRetentionsBytes       int64 // /retentions per-page response limit (default: 1 MiB)
	ProvisionsPageLimit      int   // /provisions page size requested by the client (default: 1000)
	RetentionsPageLimit      int   // /retentions page size requested by the client (default: 1000)

	// Optional Prometheus metrics. When nil, metric recording is skipped.
	// This prevents binaries that don't use these metrics (e.g., docker-backend)
	// from registering phantom fred-level metrics via transitive imports.
	RequestDuration     *prometheus.HistogramVec // labels: backend, operation, status
	RequestsTotal       *prometheus.CounterVec   // labels: backend, operation, status
	CircuitBreakerState *prometheus.GaugeVec     // labels: backend
	// Fenced is set once at construction: 1 for a fenced backend's client,
	// 0 otherwise. It is the operator's signal to silence that backend's
	// availability alerts, and it cannot disagree with the client itself.
	Fenced *prometheus.GaugeVec // labels: backend
	// MalformedErrorBodyTotal counts client-error responses whose body was not
	// the declared JSON error envelope. A backend contributing to this is
	// off-contract (BACKEND_GUIDE.md) and its tenants are getting a generic
	// message in place of a real diagnostic.
	MalformedErrorBodyTotal *prometheus.CounterVec // labels: backend, operation
}

type IdentityInventoryBackend interface {
	ListProvisionsWithIdentity(context.Context) ([]ProvisionInfo, backendidentity.ID, error)
	ListRetentionsWithIdentity(context.Context) ([]RetainedLease, backendidentity.ID, error)
}

type LeaseInfo struct {
	Host      string                  `json:"host,omitempty"`
	FQDN      string                  `json:"fqdn,omitempty"`
	Protocol  string                  `json:"protocol,omitempty"`
	Ports     map[string]PortBinding  `json:"ports,omitempty"`
	Instances []LeaseInstance         `json:"instances,omitempty"`
	Services  map[string]LeaseService `json:"services,omitempty"`
	Metadata  map[string]string       `json:"metadata,omitempty"`
}

type LeaseInstance struct {
	InstanceIndex int                    `json:"instance_index"`
	ContainerID   string                 `json:"container_id,omitempty"`
	Image         string                 `json:"image,omitempty"`
	Status        string                 `json:"status,omitempty"`
	FQDN          string                 `json:"fqdn,omitempty"`
	Ports         map[string]PortBinding `json:"ports,omitempty"`
}

type LeaseItem struct {
	SKU         string `json:"sku"`
	Quantity    int    `json:"quantity"`
	ServiceName string `json:"service_name,omitempty"`
	// CustomDomain is the optional FQDN the tenant has assigned to this item.
	// When non-empty (and the service has a routable HTTP port), the backend
	// emits a secondary Traefik router on the item's container(s) routing
	// Host(<CustomDomain>) to the same loadbalancer service. Validated on-chain
	// in MsgSetItemCustomDomain; Fred re-runs cheap defense-in-depth checks
	// before applying labels.
	CustomDomain string `json:"custom_domain,omitempty"`
}

type LeaseService struct {
	FQDN      string          `json:"fqdn,omitempty"`
	Instances []LeaseInstance `json:"instances,omitempty"`
}

type LeaseStatusEvent struct {
	LeaseUUID string          `json:"lease_uuid"`
	Status    ProvisionStatus `json:"status"`
	Error     string          `json:"error,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

type LifecycleGenerationKind string

type LifecycleGenerationObservation struct {
	Kind LifecycleGenerationKind `json:"kind"`
	ID   string                  `json:"id,omitempty"`
}

type ListProvisionsResponse struct {
	Provisions []ProvisionInfo `json:"provisions"`
	// Continue is the keyset cursor for the next page: the LeaseUUID of the last
	// item in this page when more remain, or "" when the set is exhausted.
	// Absent (omitempty) on the unpaginated path and from pre-pagination servers.
	Continue string `json:"continue,omitempty"`
}

type ListRetentionsResponse struct {
	Retentions []RetainedLease `json:"retentions"`
	// Continue is the keyset cursor for the next page: the LeaseUUID of the last
	// item in this page when more remain, or "" when the set is exhausted.
	// Absent (omitempty) on the unpaginated path and from pre-pagination servers.
	Continue string `json:"continue,omitempty"`
}

type LoadStats struct {
	TotalCPUCores     float64 `json:"total_cpu_cores"`
	AllocatedCPUCores float64 `json:"allocated_cpu_cores"`
	ActiveContainers  int     `json:"active_containers"`
	// DiskWithheld: the backend currently admits no disk-bearing allocation,
	// because a footprint of unknown size remains on its disk. Routing prefers
	// any candidate that does not withhold disk. Absent (false) from a backend
	// that never withholds disk.
	DiskWithheld bool `json:"disk_withheld,omitempty"`
}

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

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

type MaintenanceRefusal uint8

type MatchCriteria struct {
	SKUs []string // Match if SKU is in this exact list
}

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

type MockBackendConfig struct {
	Name           string
	ProvisionDelay time.Duration // Simulated provisioning time
}

type PortBinding struct {
	HostIP   string `json:"host_ip"`
	HostPort string `json:"host_port"`
}

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

type ProvisionInfo struct {
	LeaseUUID    string          `json:"lease_uuid"`
	ProviderUUID string          `json:"provider_uuid"`
	Status       ProvisionStatus `json:"status"` // see ProvisionStatus* constants
	CreatedAt    time.Time       `json:"created_at"`
	// FailCount is a lifetime diagnostic: how many failures this lease has
	// recorded, whoever caused them. It never decides whether a lease closes;
	// TerminalBudget does (ENG-799).
	FailCount int `json:"fail_count"`
	// LastError (the verbose operator failure detail) is intentionally NOT on
	// this wire type: it crosses to tenant-facing API responses, and verbose
	// exec output / host paths must never leak there (ENG-508). The curated,
	// tenant-safe (Reason, Message) pair replaces it. The operator-only verbose
	// detail lives on leasesm.ProvisionState.LastError and the diagnostics store
	// (DiagnosticEntry.Error), neither of which is tenant-serialized.
	Reason      Reason `json:"reason,omitempty"`
	Message     string `json:"message,omitempty"`
	BackendName string `json:"-"` // Set by the backend or reconciler; excluded from JSON serialization

	// RetainedUntil is the grace-window deadline (CreatedAt + RetentionMaxAge)
	// for a soft-deleted (Status=retained) lease. Zero, and omitted on the wire,
	// for live provisions or when age-based retention expiry is disabled.
	RetainedUntil time.Time `json:"retained_until,omitzero"`
	// Tenant is the owning tenant. It crosses the backend→providerd hop (an
	// HMAC-signed, trusted internal hop, like RestoreRequest.Tenant) so a complete
	// identity-bearing inventory can bind a live placement's runtime maintenance
	// principal, and so the closed-lease authz fallback (when the chain has no
	// record of the lease) can bind a retained record to its owner. It MUST NOT be
	// copied into tenant-facing API responses (LeaseStatusResponse/
	// LeaseProvisionResponse), which would leak one tenant's address to another.
	Tenant string `json:"tenant,omitempty"`

	// LifecycleGeneration reports only the class and, for current typed
	// callbacks, canonical UUID of the callback pair persisted by the backend.
	// Only an observation from complete identity-bearing ListProvisions inventory
	// is settlement evidence. A point lookup may repeat a historical diagnostics
	// observation for read-model continuity, but it is never settlement authority.
	// The field MUST NOT be copied into a tenant-facing response. Nil means that
	// the backend did not report this upgraded internal observation.
	LifecycleGeneration *LifecycleGenerationObservation `json:"lifecycle_generation,omitempty"`

	// TerminalBudget is the backend's consecutive-failure budget for this lease
	// (ENG-799). providerd closes an ACTIVE lease for repeated failure only when
	// Status is failed, Verdict is exactly exhausted and ConsecutiveFailures is
	// at least 1, read from complete ListProvisions inventory. Nil means the
	// backend does not report a budget (an older or third-party backend), and
	// providerd then never closes the lease for repeated failure. A point read
	// served from diagnostics omits it.
	TerminalBudget *TerminalBudgetObservation `json:"terminal_budget,omitempty"`

	// Partition is the retained record's optional sub-tenant grouping key
	// (retention partitioning). Unlike Tenant above, it MAY be copied into
	// tenant-facing retained responses: retained info is only ever surfaced to
	// its owning tenant (authorizeRetained / verifyLeaseAccess), and the value
	// is that tenant's own declaration — it discloses nothing cross-tenant.
	// It MUST NOT be added to the unauthenticated /workloads, /stats, or
	// /metrics surfaces (see WorkloadEntry).
	Partition string `json:"partition,omitempty"`

	// Workload metadata — populated by ListProvisions/GetProvision to describe what is running.
	Image         string            `json:"image,omitempty"`          // Docker image (non-stack leases)
	SKU           string            `json:"sku,omitempty"`            // SKU identifier (non-stack leases)
	Quantity      int               `json:"quantity"`                 // Total expected container count
	Items         []LeaseItem       `json:"items,omitempty"`          // Per-service items (stack leases)
	ServiceImages map[string]string `json:"service_images,omitempty"` // service name → image (stack leases)
}

type ProvisionRefusal uint8

type ProvisionRequest struct {
	LeaseUUID            string      `json:"lease_uuid"`
	Tenant               string      `json:"tenant"`
	ProviderUUID         string      `json:"provider_uuid"`
	Items                []LeaseItem `json:"items"`
	CallbackURL          string      `json:"callback_url"`
	LifecycleCallbackURL string      `json:"lifecycle_callback_url,omitempty"`
	Payload              []byte      `json:"payload,omitempty"`
	PayloadHash          string      `json:"payload_hash,omitempty"`
}

type ProvisionResponse struct {
	ProvisionID string `json:"provision_id"`
}

type ProvisionStatus string

type Reason string

type ReconcileCustomDomainRequest struct {
	LeaseUUID string      `json:"lease_uuid"`
	Items     []LeaseItem `json:"items"`
}

type ReleaseInfo struct {
	Version   int       `json:"version"`
	Image     string    `json:"image"`
	Status    string    `json:"status"`
	CreatedAt time.Time `json:"created_at"`
	// Error (verbose release-failure detail) is intentionally NOT on this
	// tenant-serialized wire type (ENG-508); the curated (Reason, Message) pair
	// replaces it. Operator-only verbose detail stays in the diagnostics store
	// and structured logs (the release store keeps only the curated pair).
	Reason   Reason `json:"reason,omitempty"`
	Message  string `json:"message,omitempty"`
	Manifest []byte `json:"manifest"`
}

type RestartRequest struct {
	LeaseUUID     string           `json:"lease_uuid"`
	MaintenanceID maintenanceid.ID `json:"maintenance_id"`
	CallbackURL   string           `json:"callback_url"`
	// AdmittedAt is the provider's per-lease admission stamp (RFC 3339, UTC).
	// Every replay of the command sends the same value. Omitted by older
	// providers.
	AdmittedAt time.Time `json:"admitted_at,omitzero"`
}

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

type RestoreRefusal uint8

type RestoreRequest struct {
	LeaseUUID            string      `json:"lease_uuid"`      // NEW lease
	FromLeaseUUID        string      `json:"from_lease_uuid"` // original (retained) lease
	Tenant               string      `json:"tenant"`
	ProviderUUID         string      `json:"provider_uuid"` // when non-empty, cross-checked against the retained record
	Items                []LeaseItem `json:"items"`         // must match the retained set
	CallbackURL          string      `json:"callback_url"`
	LifecycleCallbackURL string      `json:"lifecycle_callback_url,omitempty"`
}

type RetainedLease struct {
	LeaseUUID    string `json:"lease_uuid"`
	ProviderUUID string `json:"provider_uuid,omitempty"`
	Tenant       string `json:"tenant,omitempty"`
}

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

type RouterConfig struct {
	Backends []BackendEntry

	// Optional Prometheus gauge for backend health status. When nil, HealthCheck
	// skips metric recording. This prevents binaries that don't use these metrics
	// from registering phantom fred-level gauges via transitive imports.
	BackendHealthy *prometheus.GaugeVec // labels: backend

	// AllocatedCPURatio, when non-nil, records the allocated-CPU ratio observed
	// for each backend at provision-routing time. Labels: backend.
	AllocatedCPURatio *prometheus.GaugeVec

	// RoutingFallback, when non-nil, counts provision-routing decisions that
	// fell back to round-robin because no candidate exposed usable load stats.
	RoutingFallback prometheus.Counter

	// HealthProbePanics, when non-nil, counts panics recovered inside a
	// per-backend health probe goroutine. Non-zero is always a bug.
	HealthProbePanics prometheus.Counter
}

type TerminalBudgetObservation struct {
	Verdict             TerminalVerdict `json:"verdict"`
	ConsecutiveFailures int             `json:"consecutive_failures"`
}

type TerminalVerdict string

type UpdateRequest struct {
	LeaseUUID     string           `json:"lease_uuid"`
	MaintenanceID maintenanceid.ID `json:"maintenance_id"`
	CallbackURL   string           `json:"callback_url"`
	Payload       []byte           `json:"payload"`
	// AdmittedAt is the provider's per-lease admission stamp; see RestartRequest.
	AdmittedAt time.Time `json:"admitted_at,omitzero"`
}

type ValidationCode string