controlplane

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

type ConfigStoreInterface interface {
	ResolveDatabase(database string) (orgID string)
	DatabaseNameForSNIPrefix(prefix string) string // translates SNI hostname prefix → canonical database_name (alias-aware)
	// ResolveSNIPrefix maps a managed hostname prefix to its org and database.
	// It accepts hostname_alias, database_name, and DNS-safe org names.
	ResolveSNIPrefix(prefix string) (orgID, databaseName string)
	ResolvePostgresConnection(startupDatabase, sniPrefix string, useManagedSNI bool, username, password string) configstore.PostgresConnectionResolution
	ValidateOrgUser(orgID, username, password string) bool
	// ValidateOrgUserAndGetPassthrough does both lookups against the same
	// snapshot — the auth path needs both, and a single read closes the
	// window where the snapshot could swap between two separate calls.
	// passthrough is always false when valid is false.
	ValidateOrgUserAndGetPassthrough(orgID, username, password string) (valid, passthrough bool)
	// OrgWarehouseStatus reports an org's current warehouse provisioning state so
	// connection-time errors can distinguish "no such org" from "warehouse not
	// ready yet". Returns (state, orgExists). state is "" when the org has no
	// warehouse row (legacy single-tenant orgs); otherwise it is the lifecycle
	// string (pending/provisioning/ready/failed/deleting/deleted).
	OrgWarehouseStatus(orgID string) (state string, orgExists bool)
	// OrgDefaultWorkerProfile returns the org's operator-set default worker
	// profile (config-store columns default_worker_cpu/memory/ttl): cpu and
	// memory as k8s resource-quantity strings, ttl as a Go duration string.
	// Empty strings mean "not set" (including unknown orgs). Raw stored
	// values — validation happens in resolveWorkerProfile.
	OrgDefaultWorkerProfile(orgID string) (cpu, memory, ttl string)
	UpsertFlightSessionRecord(record *configstore.FlightSessionRecord) error
	GetFlightSessionRecord(sessionToken string) (*configstore.FlightSessionRecord, error)
	TouchFlightSessionRecord(sessionToken string, lastSeenAt time.Time) error
	CloseFlightSessionRecord(sessionToken string, closedAt time.Time) error
}

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

type ControlPlaneConfig struct {
	server.Config

	Process ProcessConfig

	SocketDir            string
	ConfigPath           string // Path to config file, passed to workers
	HealthCheckInterval  time.Duration
	WorkerQueueTimeout   time.Duration // How long to wait for an available worker/org connection slot (default: 60s)
	WorkerIdleTimeout    time.Duration // How long to keep an idle worker alive (default: 5m)
	RetireOnSessionEnd   bool          // When true, process workers are retired immediately after their last session ends.
	HandoverDrainTimeout time.Duration // How long to wait for connections to drain during upgrade. 0 = unbounded (wait until k8s SIGKILL via terminationGracePeriodSeconds). Default: 0 in remote mode (so a CP rolling out doesn't kill in-flight customer queries at a self-imposed wall — see drainAndShutdown), 24h in process mode.
	MetricsServer        *http.Server  // Optional metrics server to shut down during upgrade

	// WorkerBackend selects the worker management backend.
	// "process" (default): workers are local child processes communicating over Unix sockets.
	// "remote": Kubernetes-backed multitenant workers communicating over TCP.
	//           Requires ConfigStoreConn and a binary built with -tags kubernetes.
	WorkerBackend string

	// K8s contains Kubernetes-specific configuration. Only used for remote
	// multitenant mode.
	K8s K8sConfig

	// ConfigStoreConn is the PostgreSQL connection string for the config store.
	// Required when WorkerBackend == "remote".
	ConfigStoreConn string

	// ConfigPollInterval is how often to poll the config store for changes.
	// Default: 30s.
	ConfigPollInterval time.Duration

	// InternalSecret is the shared secret for API authentication.
	// When empty, a random secret is generated and logged at startup.
	InternalSecret string

	// InternalSecretFallbacks are previous internal secrets still accepted
	// for API authentication during a rotation (newest first). Clients always
	// send the primary InternalSecret; the server accepts any of
	// {primary ∪ fallbacks}. Mirrors posthog's SECRET_KEY_FALLBACKS.
	InternalSecretFallbacks []string

	// UserSecretKey is the base64-encoded 32-byte AES key for encrypting
	// user persistent secrets in the config store (env-only:
	// DUCKGRES_USER_SECRET_KEY). Empty disables the persistent secret
	// manager: CREATE PERSISTENT SECRET is rejected with a clear error.
	// Only used in multitenant remote mode.
	UserSecretKey string

	// SNIRoutingMode controls hostname-based org routing. Values:
	//   "" or "off"   - SNI is ignored; legacy database-param routing only
	//                   (default).
	//   "passthrough" - Managed Postgres SNI must resolve to the same org as
	//                   the requested startup database; when startup database is
	//                   empty, use the SNI-derived database fallback. Legacy
	//                   hostnames still fall back with a warn log.
	//   "enforce"     - Reject connections whose SNI doesn't match a managed
	//                   suffix. Explicit startup database still takes
	//                   priority when SNI is present, but must resolve to the
	//                   same org as the managed hostname.
	// Unknown values behave like "off" in the connection path.
	// Only consulted in multi-tenant control-plane builds (kubernetes tag);
	// other builds always behave as "off".
	SNIRoutingMode string

	// ManagedHostnameSuffixes lists DNS suffixes (each starting with a dot) for
	// managed tenant hostnames. When SNI matches one of these suffixes, the
	// single-label prefix is resolved as hostname_alias, database_name, or org
	// name. Postgres still honors an explicit startup database, but only when it
	// resolves to the same org as the managed hostname.
	ManagedHostnameSuffixes []string

	// DucklingBucketSuffix is the env suffix the control plane uses to name a
	// type=s3bucket Duckling's per-org S3 bucket
	// (posthog-duckling-<compact-org>-<suffix>). It MUST equal the
	// crossplane-config chart's envSuffix for this environment so the name the
	// CP writes onto the Duckling CR's spec.dataStore.bucketName is exactly what
	// the composition provisions. Empty ⇒ the CP does not name buckets and the
	// composition derives the name (legacy behavior). See
	// configstore.DucklingBucketName.
	DucklingBucketSuffix string

	// DuckLakeDefaultSpecVersion is the global default DuckLake spec version
	// used for migration checks when an org doesn't specify an override.
	DuckLakeDefaultSpecVersion string
}

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

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

type FlightIngress = flightsqlingress.FlightIngress

type FlightIngressConfig = flightsqlingress.Config

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

type HealthCheckResult string

type JanitorLeaderManager struct{}

type K8sConfig struct {
	WorkerImage             string // Container image for worker pods (required)
	WorkerNamespace         string // K8s namespace (default: auto-detect from service account)
	ControlPlaneID          string // Unique CP identifier for labeling worker pods (default: os.Hostname())
	WorkerPort              int    // gRPC port on worker pods (default: 8816)
	WorkerSecret            string // Base name for per-worker K8s Secrets containing RPC bearer token and TLS material
	WorkerConfigMap         string // ConfigMap name for duckgres.yaml
	ImagePullPolicy         string // Image pull policy for worker pods (e.g., "Never", "IfNotPresent", "Always")
	ServiceAccount          string // ServiceAccount name for worker pods (default: "duckgres-worker")
	MaxWorkers              int    // Global cap for the shared K8s worker pool (0 = unbounded; cluster autoscaler is the natural ceiling)
	WorkerCPURequest        string // CPU request for worker pods (e.g., "500m")
	WorkerMemoryRequest     string // Memory request for worker pods (e.g., "1Gi")
	WorkerNodeSelector      string // JSON map for worker pod nodeSelector (e.g., '{"posthog.com/nodepool":"workers"}')
	WorkerTolerationKey     string // Taint key for worker pod NoSchedule toleration
	WorkerTolerationValue   string // Taint value for worker pod NoSchedule toleration
	WorkerPriorityClassName string // PriorityClass for worker pods, so they preempt overprovision headroom pause pods (empty = none)
	AWSRegion               string // AWS region for STS client

	// Node-headroom controller: keep HeadroomPercent% of the worker nodepool's
	// allocatable CPU+memory free via low-priority placeholder pods, so a worker
	// spawn schedules immediately (preempting placeholders) rather than waiting
	// on a fresh Karpenter node. 0 = disabled.
	HeadroomPercent              int    // % of worker-nodepool allocatable to hold free (0 = disabled)
	PlaceholderImage             string // Image for placeholder pods (a pause image)
	PlaceholderPriorityClassName string // PriorityClass for placeholder pods — MUST rank below WorkerPriorityClassName

	// Connection-string worker sizing (duckgres.worker_cpu / worker_memory /
	// worker_ttl). All default to the off/empty state, so absent config = the
	// default worker shape. See docs/design/connection-string-worker-profile.md.
	AllowClientWorkerProfile bool          // Master gate: honor duckgres.* startup options at all
	WorkerProfileMinCPU      string        // Clamp floor for a client-supplied cpu (e.g. "1")
	WorkerProfileMaxCPU      string        // Clamp ceiling for a client-supplied cpu (e.g. "16")
	WorkerProfileMinMemory   string        // Clamp floor for a client-supplied memory (e.g. "4Gi")
	WorkerProfileMaxMemory   string        // Clamp ceiling for a client-supplied memory (e.g. "64Gi")
	WorkerMaxTTL             time.Duration // Clamp ceiling for a client-supplied duckgres.worker_ttl (0 = unbounded)

	// WorkerDefaultTTL is the hot-idle TTL applied when a request does not
	// specify duckgres.worker_ttl (and no org default does either) — the
	// "default TTL", pairing with WorkerMaxTTL (the clamp). It governs both
	// no-ttl paths the same way: default-shape workers (reaped by the janitor)
	// and sized-but-no-ttl workers (stamped at profile resolution). Per-request
	// precedence: client GUC > org default > this > built-in (20m,
	// defaultWorkerTTL). Raise it above a tenant's job cadence (e.g. 70m for
	// hourly jobs) so scheduled workloads reuse hot-idle workers instead of
	// cold-spawning every run — at the cost of idle worker nodes.
	WorkerDefaultTTL time.Duration
}

type K8sPoolFactory func(cfg K8sWorkerPoolConfig) (WorkerPool, error)

type K8sWorkerPoolConfig struct {
	Namespace                    string
	CPID                         string // Control plane pod name, used in labels
	CPInstanceID                 string // Durable control-plane instance ID (<pod_uid>:<boot_id>)
	WorkerImage                  string
	WorkerPort                   int
	SecretName                   string // Base name for per-worker K8s Secrets containing RPC bearer token and TLS material
	ConfigMap                    string // ConfigMap name for duckgres.yaml
	MaxWorkers                   int
	IdleTimeout                  time.Duration
	ConfigPath                   string                                       // Path inside worker pod where config is mounted
	ImagePullPolicy              string                                       // Image pull policy for worker pods (e.g., "Never", "IfNotPresent", "Always")
	ServiceAccount               string                                       // ServiceAccount name for worker pods (default: "duckgres-worker")
	WorkerCPURequest             string                                       // CPU request for worker pods (e.g., "500m"). Empty = BestEffort.
	WorkerMemoryRequest          string                                       // Memory request for worker pods (e.g., "1Gi"). Empty = BestEffort.
	WorkerNodeSelector           map[string]string                            // Node selector for worker pods. Nil = no selector.
	WorkerTolerationKey          string                                       // Taint key for worker pod NoSchedule toleration. Empty = no toleration.
	WorkerTolerationValue        string                                       // Taint value for worker pod NoSchedule toleration.
	WorkerPriorityClassName      string                                       // PriorityClass for worker pods (so they preempt overprovision pause pods). Empty = none.
	HeadroomPercent              int                                          // Keep this % of worker-nodepool allocatable CPU+mem free via low-priority placeholder pods (0 = disabled).
	PlaceholderImage             string                                       // Image for headroom placeholder pods (a pause image).
	PlaceholderPriorityClassName string                                       // PriorityClass for placeholder pods — MUST be below WorkerPriorityClassName so workers preempt them.
	OrgID                        string                                       // Org ID for pod labels (multi-tenant mode)
	WorkerIDGenerator            func() int                                   // Shared ID generator across orgs (nil = internal counter)
	ResolveOrgConfig             func(string) (*configstore.OrgConfig, error) // Optional: resolve org config for version-aware reaping
	RuntimeStore                 RuntimeWorkerStore
}

type LifecycleOperation string

type LifecycleOrigin string

type ManagedSession struct {
	PID          int32
	WorkerID     int
	Protocol     string // "postgres" or "flight"
	SessionToken string
	Executor     *flightclient.FlightExecutor
	// contains filtered or unexported fields
}

type ManagedWorker struct {
	ID int
	// contains filtered or unexported fields
}

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

type OrgRouterInterface interface {
	StackForOrg(orgID string) (pool WorkerPool, sessions *SessionManager, rebalancer *MemoryRebalancer, ok bool)
	IcebergConfigForOrg(orgID string) (server.IcebergConfig, bool)
	IsMigratingForOrg(orgID string) bool
	ShutdownAll()
}

type ProcessConfig struct {
	MinWorkers int
	MaxWorkers int
}

type ProgressHandler func(workerID int, progress map[string]*SessionProgress)

type RuntimeWorkerStore interface {
	UpsertWorkerRecord(record *configstore.WorkerRecord) error
	ClaimHotIdleWorker(ownerCPInstanceID, orgID, image string, profileCPU, profileMemory string, maxOrgWorkers int) (*configstore.WorkerRecord, configstore.WorkerClaimMissReason, error)
	CreateSpawningWorkerSlot(ownerCPInstanceID, orgID, image string, profileCPU, profileMemory string, ownerEpoch int64, podNamePrefix string, maxOrgWorkers, maxGlobalWorkers int) (*configstore.WorkerRecord, error)
	CountHotIdleWorkers(orgID, image, profileCPU, profileMemory string) (int, error)
	GetWorkerRecord(workerID int) (*configstore.WorkerRecord, error)
	ObserveWorker(workerID int) (*configstore.WorkerSnapshot, error)
	TakeOverWorker(workerID int, ownerCPInstanceID, orgID string, expectedOwnerEpoch int64) (*configstore.WorkerRecord, error)
}

type SessionLister interface {
	AllSessions() []*ManagedSession
}

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

type SessionProgress struct {
	Percentage float64
	Rows       uint64
	TotalRows  uint64
	Stalled    bool
}

type SharedWorkerState struct {
	Lifecycle  WorkerLifecycleState
	Assignment *WorkerAssignment
}

type SpawnFailureReason string

type StrandedOutcome string

type WorkerAssignment struct {
	OrgID      string
	MaxWorkers int
	Image      string
	// Profile is the requested worker shape. nil => the default exclusive
	// profile (today's behavior). It is immutable for a reserved worker's life;
	// enforcement is wired in alongside the scheduling changes (see design doc).
	Profile *WorkerProfile
}

type WorkerCapacityExhaustedError struct {
	// RetryAfter is the client-facing retry hint for protocol-specific error responses.
	RetryAfter time.Duration
	// Reason classifies why the worker could not be acquired.
	Reason configstore.WorkerClaimMissReason
}

type WorkerCrashHandler func(workerID int)

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

type WorkerLifecycleState string

type WorkerPhysicalCleanup interface {
	// DeleteWorkerArtifacts schedules deletion of the pod and RPC secret
	// for the named worker. Called only after the durable runtime row
	// has transitioned to terminal. Implementations may also clean up
	// in-memory pool state keyed by workerID.
	DeleteWorkerArtifacts(workerID int, podName string, reason string)
}

type WorkerPool interface {
	// AcquireWorker returns a worker for a new session. The multi-tenant
	// OrgReservedPool (k8s/remote) reuses a hot-idle worker of the requested shape
	// for the org or spawns one on demand; the process FlightWorkerPool reuses an
	// idle worker / assigns least-loaded. profile is the requested pod shape (nil
	// => the default shape) and is honored only by OrgReservedPool.
	AcquireWorker(ctx context.Context, profile *WorkerProfile) (*ManagedWorker, error)

	// ReleaseWorker decrements the active session count for a worker.
	ReleaseWorker(id int)

	// RetireWorker removes a worker from the pool and shuts it down.
	RetireWorker(id int)

	// RetireWorkerIfNoSessions retires a worker only if it has zero active
	// sessions after releasing the caller's claim. Returns true if retired.
	RetireWorkerIfNoSessions(id int) bool

	// Worker returns a worker by ID, or false if not found.
	Worker(id int) (*ManagedWorker, bool)

	// SpawnMinWorkers pre-warms the pool with count workers at startup. Only the
	// process FlightWorkerPool implements this (--process-min-workers); the K8s
	// pool spawns on demand, so its implementation is a no-op.
	SpawnMinWorkers(count int) error

	// HealthCheckLoop runs periodic health checks on all workers.
	// onCrash is called when a worker crash is detected.
	// onProgress is called with per-session progress data after each successful check.
	// Either callback may be nil.
	HealthCheckLoop(ctx context.Context, interval time.Duration, onCrash WorkerCrashHandler, onProgress ProgressHandler)

	// SetMaxWorkers updates the maximum number of workers. 0 means unlimited.
	SetMaxWorkers(n int)

	// ShutdownAll stops all workers gracefully.
	ShutdownAll()
}

type WorkerProfile struct {
	CPU    string        // normalized k8s quantity (e.g. "8"); the worker's CPU size
	Memory string        // normalized k8s quantity (e.g. "16Gi"); the worker's memory size
	TTL    time.Duration // how long the worker stays hot-idle after its last query (reset per query); not part of MatchKey
}