api

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

type Check struct {
	Name string
	// Run reports why the dependency cannot do its part, nil while it can.
	Run func(context.Context) error
}

type DLQHandler struct {
	Counts mq.DeadLetterStats
}

type Dependencies struct {
	Ingest          *IngestHandler
	Query           *QueryHandler
	SSE             *StreamHandler
	Health          *HealthHandler
	Version         *VersionHandler
	Schema          *SchemaHandler
	DLQ             *DLQHandler
	Pipes           *PipesHandler
	StructuredQuery *StructuredQueryHandler
	// Settings, if non-nil, mounts POST /v1/ops/settings/reload — the API
	// trigger for reloading the settings directory. Nil when no settings
	// directory is configured (nothing to reload).
	Settings *SettingsHandler
	AuthMW   func(http.Handler) http.Handler
	// Tenants resolves the tenant.Header of every tenant route to that
	// tenant's settings store (TenantMW), ahead of AuthMW. The probes,
	// /version, the metrics path, and /v1/ops/* are tenant-exempt.
	Tenants *settings.Registry
	// PolicySource backs the RequireAdmin gate: the admin role (policy.AdminRole)
	// is read live from the adopted policy, so admin_role changes apply on reload.
	// NewRouter ignores it when Tenants is nested, whatever was wired here: the
	// ops gate then admits the operator key alone (see NewRouter).
	PolicySource policy.Source
	// CORSOrigins yields one tenant's allowed CORS origins, read per request
	// so a settings reload applies immediately ((*settings.Store).CORSOrigins
	// in production); which tenant's list answers a request is corsOrigins'
	// rule. An empty or nil list — including a nil func, or no Tenants —
	// denies every browser origin; ["*"] is the only allow-all spelling.
	CORSOrigins func(*settings.Store) []string
	// MetricsHandler, if non-nil, is mounted at MetricsPath as an unauthenticated
	// endpoint (Prometheus convention). Wired by internal/app from the OTel Prometheus
	// exporter when observability.metrics.prometheus.enabled is true AND port is 0.
	MetricsHandler http.Handler
	MetricsPath    string
}

type HealthHandler struct {
	// Checks are Readiness's dependency checks, every one run on every call
	// so the 503 names each one that failed, not just the first. Which
	// dependencies a process has is internal/app's to wire: the ClickHouse
	// pools (chconn.Pools.Ping: every open pool at once, ready at the first
	// answer) and the external NATS; a handler with none is ready once
	// booted.
	Checks []Check
	// Boot is consulted by both Liveness and Readiness. When non-nil and
	// its Err() is non-nil, both endpoints report 503 with the diagnostic
	// — used while boot-time schema discovery is still failing in the
	// retry loop. A nil Boot preserves the pre-retry-loop behaviour
	// (Liveness always 200; Readiness 503 only on a failed check).
	Boot *BootState
}

type IngestFormat int

type IngestHandler struct {
	// Registry yields the request tenant's schema registry.
	Registry RegistrySource
	// Dedup resolves the request tenant's deduplicator — the tenant's own
	// store, picked off the store the handler already holds (#583 story 7;
	// dedupe.Stores in production). nil when no dedupe store is wired (tests).
	Dedup func(store *settings.Store) dedupe.Deduplicator
	// DedupeSettings resolves the effective dedupe settings for a table of the
	// request's tenant ((*settings.Store).DedupeFor in production). Called
	// once per record so a settings reload lands at a record boundary — one
	// record never mixes two documents' values. Dedup is skipped when nil.
	DedupeSettings func(store *settings.Store, table string) settings.Dedupe
	// DedupeLease is how long a record's claimed id stays pending while it is
	// published; 0 means dedupe.DefaultLease.
	DedupeLease  time.Duration
	Publisher    mq.Publisher
	PolicySource PolicySource

	// Validator and Checker are the per-record seams a native type layer will
	// take over (see ingest_seams.go). Both are optional: nil means the default
	// implementation, which is today's behavior unchanged.
	Validator RecordValidator
	Checker   InsertChecker
	// contains filtered or unexported fields
}

type InsertChecker interface {
	Matches(actual, required any) bool
	InSet(v any, set []any) bool
}

type OpsDependencies struct {
	Health  *HealthHandler
	Version *VersionHandler
	// Settings mounts POST /v1/ops/settings/reload.
	Settings *SettingsHandler
	// AuthMW authenticates the reload. It runs no token verifier (those are
	// the api role's), so the operator key is the one credential that passes.
	AuthMW         func(http.Handler) http.Handler
	MetricsHandler http.Handler
	MetricsPath    string
}

type PipesHandler struct {
	// Source yields a tenant's pipes (the store itself in production).
	Source       func(*settings.Store) pipes.Source
	PolicySource PolicySource // resolves empty role to default_role; may be nil
	// Tenants resolves the tenant the admin reads (List, Get) serve: /v1/ops
	// is tenant-exempt, so they carry no request tenant and read the one
	// ?tenant= names, the default one without it (opsStore).
	Tenants *settings.Registry
	// CHConn yields the request tenant's connection (chconn.Pools.For in
	// production); nil is a tenant on no pool, a 503.
	CHConn func(*settings.Store) driver.Conn
	Cache  cache.Cache
	// contains filtered or unexported fields
}

type PolicySource func(*settings.Store) *policy.Policy

type QueryHandler struct {

	// Tenants resolves the tenant the proxy queries: /v1/ops is
	// tenant-exempt, so the request carries no tenant and the query runs
	// against the one ?tenant= names, the default one without it (opsStore).
	Tenants *settings.Registry
	// contains filtered or unexported fields
}

type RecordValidator interface {
	Validate(schema *discovery.TableSchema, record map[string]any) error
	CanonicalizeTimestamps(schema *discovery.TableSchema, record map[string]any)
}

type RegistrySource func(*settings.Store) *discovery.SchemaRegistry

type SchemaHandler struct {
	Registry RegistrySource
	// Tenants resolves the tenant the reads and the refresh serve: /v1/ops
	// is tenant-exempt, so they carry no request tenant and read the one
	// ?tenant= names, the default one without it (opsStore).
	Tenants *settings.Registry
}

type SettingsHandler struct {
	Tenants *settings.Registry
}

type StreamHandler struct {
	Hub      *stream.Hub
	Replayer mq.Replayer // gap-fill source; nil disables replay
	// Heartbeater yields the request tenant's keepalive wheel — its own, at
	// its own stream.keepalive_* settings (#597) — or nil for a tenant no
	// longer served, whose streams are ending (Hub.Prune, Served). A nil func
	// means no keepalive is wired (tests).
	Heartbeater func(*settings.Store) *stream.Heartbeater
	Metrics     *stream.Metrics
	// Closing, when set, is closed as the server begins shutting down, and
	// every open stream ends at once — mid-replay too: a stream is a
	// connection to close, not in-flight work for the drain to wait on, and
	// the client reconnects and gap-fills via Last-Event-ID. A nil channel
	// never fires (a harness that serves the handler itself).
	Closing <-chan struct{}
	// Served, when set, reports whether a tenant is still being served. A
	// reload that stops serving one evicts its streams (Hub.Prune), but not a
	// stream TenantMW admitted just before the reload and registered with the
	// Hub just after it: this check, made after registering, ends that one.
	Served func(tenant.ID) bool
}

type StructuredQueryHandler struct {
	// CHConn yields the request tenant's connection (chconn.Pools.For in
	// production); nil is a tenant on no pool, a 503.
	CHConn       func(*settings.Store) driver.Conn
	Cache        cache.Cache
	Registry     RegistrySource
	PolicySource PolicySource
	// contains filtered or unexported fields
}

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