settings

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package settings defines the on-disk settings directory — the JSON documents that hold WaveHouse's hot-reloadable configuration — and Validate, the single gate every consumer of that directory runs before adopting its contents.

The directory holds exactly four files: roles.json (the role registry), policies.json (the access-control policy), pipes.json (named queries), and config.json (behavioral tunables migrated out of boot config) — or, nested, one folder per tenant, each holding those four (see Tree). Validate is deliberately pure — no network, no ClickHouse, no side effects — so the same function can gate the `wavehouse validate` CLI, boot, and a live reload. Table/column existence is out of scope by design: WaveHouse is Bring-Your-Own-Schema, and schema discovery owns what exists in ClickHouse.

The package is importable from outside the module (#834): a program that writes settings directories checks them with ValidateFiles, over bytes, using the package from the same release tag as the server, and so with exactly the rules that server applies. It imports nothing under internal/ and none of the server's runtime dependencies; the runtime half — the adopted snapshot, the reload triggers, the directory watcher — is internal/settings.

Index

Constants

View Source
const (
	FileRoles    = "roles.json"
	FilePolicies = "policies.json"
	FilePipes    = "pipes.json"
	FileConfig   = "config.json"
)

The four settings files. Any other entry in the directory is rejected — a typoed filename must fail loudly, not be silently ignored. The one exception is dot-prefixed entries (vim swap files, the `..data` machinery Kubernetes ConfigMap mounts publish through), which are skipped.

View Source
const MaxKeepaliveBuckets = 100

MaxKeepaliveBuckets caps stream.keepalive_buckets. The wheel ticks once per bucket per keepalive_interval, and holds a subscriber set per bucket, so the count is both a tenant's tick rate and the size of its ring: at the cap, a tenant at the 1-second minimum interval ticks a hundred times a second, and its ring is a hundred empty sets. A hundred buckets already spreads the writes to 1% of the tenant's streams per tick, past which more buckets buy nothing a proxy or client can tell apart.

View Source
const MinDedupeRetention = 2 * time.Minute

MinDedupeRetention is the shortest finite dedupe retention: the embedded queue's duplicate window (mq.EmbeddedDuplicateWindow). A record is published under an idempotency key derived from its id, so an id re-sent after a shorter retention but inside the window is claimed again and then dropped by the queue as a copy, while the client is told it was accepted.

Variables

This section is empty.

Functions

func Files

func Files() []string

Files returns every expected file. All four must exist (an empty document is written as {}), so an accidental deletion reads as an error, never as "defaults". A function rather than a package variable because Go has no const slices — this keeps the set genuinely immutable.

func HasErrors

func HasErrors(findings []Finding) bool

HasErrors reports whether any finding is an error (warnings alone leave the directory valid).

func Seed

func Seed() (map[string][]byte, error)

Seed returns the starter settings directory's files by name.

func Validate

func Validate(root string) (*Tree, []Finding)

Validate checks a settings root of either shape in one pass and returns every finding, the way ValidateDir does for one directory. The shape is read off the root: holding any of the four settings file names makes it flat, whatever else is there; otherwise holding a folder makes it nested; otherwise — empty, missing, unreadable — it is flat again, so ValidateDir names the problem exactly as it always has. Mixing the shapes needs no rule of its own: a flat root rejects a folder and a nested root rejects a loose file.

A flat root's findings are ValidateDir's, untouched. A nested root's carry the tenant folder in File ("acme/policies.json"), and a folder whose name is not a tenant id is a finding against that folder alone. The Tree is nil when the finding is about the root itself — it cannot be listed, or a nested root holds a loose file or an entry that cannot be stat'ed — since no tenant can then be trusted to be what the root's author meant.

func ValidateDir

func ValidateDir(dir string) (*Document, []Finding)

ValidateDir reads, decodes, and checks one directory of the four settings files — a flat root, or one tenant's folder of a nested one — in one pass and returns every finding it can discover — an operator fixing a hand-edited directory wants the whole list, not a fix-rerun-fix loop. No side effects: no network, no ClickHouse, nothing written. The Document is returned only when no finding is an error (warnings alone leave it usable), so what a node adopts is byte-for-byte what was validated — this is the single checking path, and every consumer (the `wavehouse validate` CLI, boot, a live reload) goes through it, by way of Validate. Callers translate the result per their own contract: the CLI exits non-zero, boot refuses to start, and a live reload keeps serving the previous good document.

It is ValidateFiles over the directory's bytes, after the checks only a directory can fail: that it exists, that each file is a regular file, and config.json's permission bits.

func ValidateFiles

func ValidateFiles(files map[string][]byte) (*Document, []Finding)

ValidateFiles is ValidateDir for a directory that exists only in memory: the settings files by name (see Files), as a program that writes a settings directory holds them before it does. It checks them with the rules ValidateDir applies, at the version it applies them, so a writer built against this package at the server's release tag can refuse a directory the server would refuse before anything reaches disk. The findings are ValidateDir's but for the checks that need a directory (listed there). Names are read as directory entries are: a dot-prefixed name is skipped, any other name not among Files is an unexpected file, and a file that is absent or nil is missing.

func ValidateFolder

func ValidateFolder(root, folder string) (*Document, []Finding)

ValidateFolder is ValidateDir for one tenant folder of a nested root, with the folder leading each finding's File — what checks one tenant's folder on its own, as the Registry does for a reload of that tenant alone.

This is the one place a tenant id becomes a filesystem path: the dedupe store keys by tenant, not by directory (internal/dedupe's Embedded). Every caller already hands it an id that passed tenant.Parse (which forbids '.', '/' and '\'), so the check below is never reached today; it is here so the guarantee that a name resolves to one folder under root — never root itself, never outside it — lives beside the join that depends on it, rather than in two callers — and it is the check CodeQL's path-injection query recognizes as a sanitizer, which the grammar in tenant.Parse is not.

Types

type AuthConfig

type AuthConfig struct {
	// JWKSURL, when non-empty, makes JWKS the sole verifier (the HMAC
	// secret is then ignored). Must be an absolute http(s) URL.
	JWKSURL *string `json:"jwks_url"`
	// JWTSecret is the HMAC secret tokens are verified with when JWKSURL is
	// empty; with both empty no token validates, and every request is the
	// policy default_role.
	JWTSecret *string `json:"jwt_secret"`
	// RoleClaim is the dot-separated claim path the role is read from.
	RoleClaim *string `json:"role_claim"`
}

AuthConfig is the JWT verifier wiring, the HMAC secret included; the operator key is boot config (`auth.operator_key`), a credential of the platform, not of a tenant. A reload that changes it rebuilds the tenant's verifier; until a JWKS endpoint's key set has been fetched, a token-bearing request is refused (503) rather than verified.

type CORSConfig

type CORSConfig struct {
	AllowedOrigins []string `json:"allowed_origins"`
}

CORSConfig carries the per-request CORS allowlist. ["*"] allows any browser origin; see corsMiddleware in internal/api for why that is safe for a Bearer-token API.

type ClickHouseConfig

type ClickHouseConfig struct {
	// Addr is the native-protocol host:port (schema discovery, structured
	// queries, pipes, /readyz).
	Addr *string `json:"addr"`
	// HTTPPort and HTTPScheme address the HTTP interface (ingest INSERTs and
	// the raw-SQL proxy) on the same host as Addr.
	HTTPPort   *int    `json:"http_port"`
	HTTPScheme *string `json:"http_scheme"`
	Database   *string `json:"database"`
	Username   *string `json:"username"`
	// Password pairs with Username; may be empty (a passwordless user).
	Password *string `json:"password"`
	// QueryTimeout is the deadline in seconds (>= 1) of a call on the query
	// paths: structured queries, pipes (writes included) and the raw-SQL proxy.
	QueryTimeout *int `json:"query_timeout"`
	// TLS is the TLS wiring of both hops: `enabled` switches the native
	// protocol to TLS, `http_scheme` stays the HTTP hop's switch, and the
	// material applies to whichever hop uses TLS. Paths, checked for shape
	// only — the files are read when the connection is (re)built.
	TLS *ClickHouseTLS `json:"tls"`
	// Headers are set on every HTTP-interface request (ingest INSERTs, the
	// raw-SQL proxy) ahead of WaveHouse's own credential and content-type
	// headers, which therefore win. The native protocol carries none.
	Headers map[string]string `json:"headers"`
	// MaxOpenConns and MaxIdleConns size the native driver's pool: each
	// >= 1, open >= idle.
	MaxOpenConns *int `json:"max_open_conns"`
	MaxIdleConns *int `json:"max_idle_conns"`
}

ClickHouseConfig is the ClickHouse wiring, password included. A reload that changes any of it swaps the connection unconditionally; reachability is a runtime concern (schema discovery, /readyz), never a reload one. A certificate file that cannot be read or parsed is the one exception: boot refuses, and a reload keeps the previous connection.

type ClickHouseTLS

type ClickHouseTLS struct {
	Enabled            *bool   `json:"enabled"`
	CAFile             *string `json:"ca_file"`
	CertFile           *string `json:"cert_file"`
	KeyFile            *string `json:"key_file"`
	InsecureSkipVerify *bool   `json:"insecure_skip_verify"`
	ServerName         *string `json:"server_name"`
}

ClickHouseTLS is the `clickhouse.tls` block. Every key is required, like the rest of config.json; cert_file and key_file go together.

type DLQConfig

type DLQConfig struct {
	Enabled *bool `json:"enabled"`
	// Tables holds per-table overrides keyed by ClickHouse table name.
	Tables map[string]TableDLQ `json:"tables,omitempty"`
}

DLQConfig gates the Dead Letter Queue: whether a row ClickHouse still rejects after the row-by-row isolation retry is parked on the tenant's dead-letter queue (and its original acked) or left unacked to be redelivered indefinitely. The queue is opened when the tenant is first served — empty until something lands on it — so the switch is purely behavioral and resolves per table through the same override cascade as dedupe.

type DedupeConfig

type DedupeConfig struct {
	Enabled   *bool   `json:"enabled"`
	IDField   *string `json:"id_field"`
	RequireID *bool   `json:"require_id"`
	// Retention is how long a committed id stays a duplicate, as a Go
	// duration ("720h"); "0", or leaving it out, keeps it forever. A change
	// applies to ids committed after it.
	Retention *string `json:"retention,omitempty"`
	// Tables holds per-table overrides keyed by ClickHouse table name (#222).
	// Names are format-checked only — existence is schema discovery's runtime
	// concern, same as policies.json table keys.
	Tables map[string]TableDedupe `json:"tables,omitempty"`
}

DedupeConfig tunes dedupe behavior, including the switch itself: a reload that flips enabled opens or closes the tenant's store on the fly (dedupe.Managed, one per tenant, each a share of the one embedded Pebble instance), so the whole block is tenant-owned.

id_field and require_id are required here; retention is optional, and missing means "0" (forever). Every field is optional per table: a table override inherits whichever field it doesn't name. An empty, whitespace-only, or whitespace-padded id_field is rejected at every level, so the effective id_field can never be empty or silently unmatchable.

type Document

type Document struct {
	// Roles is the role registry every role reference is checked against.
	Roles []string
	// Policy is nil when policies.json is an empty document — no policy,
	// fail closed (matching the deleted-policy semantics of the store).
	Policy *policy.Policy
	Pipes  []pipes.NamedQuery
	Config TenantConfig
}

Document is a fully parsed and validated settings directory.

type Finding

type Finding struct {
	Severity Severity `json:"severity"`
	File     string   `json:"file,omitempty"`
	Path     string   `json:"path,omitempty"`
	Message  string   `json:"message"`
}

Finding is one validation result, located as precisely as the failure allows: File is empty for directory-level findings and, in a nested root, leads with the tenant folder ("acme/policies.json", or "acme" alone for a finding about the folder); Path is a dotted JSON path ("tables.clicks.analyst") and empty for whole-file findings. The JSON shape is part of the ops API: POST /v1/ops/settings/reload returns findings verbatim.

func (Finding) String

func (f Finding) String() string

String renders "error: policies.json: tables.clicks.admin: <message>", dropping the locators a finding doesn't have.

type MQConfig

type MQConfig struct {
	// MaxBytesGB caps the tenant's ingest queue (its dead-letter queue gets a
	// tenth of it). Must be >= 1. A reload updates the live queues in place:
	// growing takes effect immediately; shrinking below what is currently
	// buffered makes the ingest queue refuse new publishes (DiscardNew → 503
	// backpressure) until the sweeper purges it back under the limit —
	// nothing already buffered is dropped — and a dead-letter queue holding
	// more than a tenth of the new budget keeps what it holds rather than
	// dropping its oldest rows.
	MaxBytesGB *int `json:"max_bytes_gb"`
}

MQConfig sizes the tenant's message queue on disk.

type PipesFile

type PipesFile struct {
	Pipes []pipes.NamedQuery `json:"pipes"`
}

PipesFile is the shape of pipes.json.

type QueryConfig

type QueryConfig struct {
	// DefaultMaxRows is the result LIMIT applied to a structured query when
	// the caller and policy specify none. Must be >= 1.
	DefaultMaxRows *int `json:"default_max_rows"`
	// TimestampBucketSeconds truncates a structured query's relative time
	// range to this bucket so near-identical queries share a cache entry.
	// Must be >= 0; 0 disables bucketing.
	TimestampBucketSeconds *int `json:"timestamp_bucket_seconds"`
}

QueryConfig holds query-shaping defaults. Server-wide *resource* limits (memory, rows scanned, execution time) deliberately live in ClickHouse itself — its settings profiles and quotas — so they apply uniformly to every query; this block holds the result-LIMIT default and the time-range normalization that drives cache hits.

type RolesFile

type RolesFile struct {
	Roles []string `json:"roles"`
}

RolesFile is the shape of roles.json.

type SchemaConfig

type SchemaConfig struct {
	// RefreshInterval is the auto-refresh period in seconds. Must be >= 1.
	RefreshInterval *int `json:"refresh_interval"`
}

SchemaConfig tunes ClickHouse schema discovery.

type Severity

type Severity string

Severity classifies a finding. Errors make the directory invalid; warnings flag config that is legal but almost certainly not what the author meant (e.g. a grant scoping the admin role, which is an unconditional bypass).

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

type StreamConfig

type StreamConfig struct {
	// KeepaliveInterval is the effective per-connection keepalive period in
	// seconds — the longest a quiet stream goes unwritten before a ":"
	// comment. Must be >= 1. A reload rebuilds the wheel in place; live
	// connections keep streaming.
	KeepaliveInterval *int `json:"keepalive_interval"`
	// KeepaliveBuckets spreads the keepalive writes across the interval so
	// each tick nudges ~1/N of live streams. Must be in 1-MaxKeepaliveBuckets.
	KeepaliveBuckets *int `json:"keepalive_buckets"`
	// GapWindowMinutes is how many minutes of ACKed messages the sweeper
	// keeps in NATS for SSE gap-fill (Last-Event-ID replay). Must be >= 0;
	// applies from the next sweep.
	GapWindowMinutes *int `json:"gap_window_minutes"`
}

StreamConfig tunes GET /v1/stream: the tenant's SSE keepalive wheel and how much NATS history the Active Sweeper keeps for its gap-fill. Keepalives are set to the proxy in front of the tenant's streams and the gap window is its replay budget, both of which change while the server runs.

type TableDLQ

type TableDLQ struct {
	Enabled *bool `json:"enabled,omitempty"`
}

TableDLQ is one table's DLQ override.

type TableDedupe

type TableDedupe struct {
	IDField   *string `json:"id_field,omitempty"`
	RequireID *bool   `json:"require_id,omitempty"`
	Retention *string `json:"retention,omitempty"`
}

TableDedupe is one table's dedupe override; it overrides only the fields it names.

type TenantConfig

type TenantConfig struct {
	ClickHouse *ClickHouseConfig `json:"clickhouse"`
	Auth       *AuthConfig       `json:"auth"`
	Dedupe     *DedupeConfig     `json:"dedupe"`
	DLQ        *DLQConfig        `json:"dlq"`
	Query      *QueryConfig      `json:"query"`
	Schema     *SchemaConfig     `json:"schema"`
	Stream     *StreamConfig     `json:"stream"`
	MQ         *MQConfig         `json:"mq"`
	CORS       *CORSConfig       `json:"cors"`
}

TenantConfig is the shape of config.json: the behavioral tunables that migrate out of boot config. Boot config (config.yaml/env) keeps only what cannot change under a running process — the implementation each layer runs on (`mq.backend`, `cache.backend`, `dedupe.backend`, `coord.backend`), resource sizing (`data_dir`, `cache.l1_max_cost`, `clickhouse.max_total_conns`), listeners, the observability exporters — and the process-level secrets (`auth.operator_key`, `cache.redis.password`). A tenant's own secrets — `clickhouse.password`, `auth.jwt_secret` — live here with the wiring they belong to, so they reload with it (#529). Every block and every top-level key inside it is REQUIRED, but dedupe.retention (missing means "0", forever): the binary carries no other compiled default, so the adopted snapshot is exactly what the files say. Defaults live in the seed directory (see Seed) that `wavehouse bootstrap` writes. The fields are pointers only so Validate can tell "absent" from the zero value and report it by path.

type TenantResult

type TenantResult struct {
	Doc      *Document
	Findings []Finding
}

TenantResult is one tenant's share of a validation pass.

type Tree

type Tree struct {
	Nested bool
	// Tenants holds every tenant the root defines. Doc is nil for a tenant
	// whose folder has an error finding.
	Tenants map[tenant.ID]TenantResult
}

Tree is a validated settings root (#583). A flat root — the four files in the root itself — is tenant.Default alone. A nested root holds one folder per tenant and nothing else, the folder name being the tenant id.

func (*Tree) Serves

func (t *Tree) Serves() bool

Serves reports whether the tree holds a tenant with a document to serve.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL