config

type DB ¶

type DB struct {
	DSN         Secret `conf:"dsn" json:"dsn" doc:"runtime database DSN (app_rt role) as a secretref:// reference"`
	MigrateDSN  Secret `` /* 142-byte string literal not displayed */
	PlatformDSN Secret `` /* 444-byte string literal not displayed */
	Pool               // embedded: pool knobs stay flat under db.* and flow to every process view wholesale
}

DB configures the Postgres pools. DSNs are optional at load time and validated at process-view narrowing instead: api/worker require DSN, migrate requires MigrateDSN (D-0021) — the framework repo's config tooling and DB-less tests must stay loadable.

type Env ¶

type Env string

Env is the deployment environment. It gates dev-only behavior: anything marked unsafe refuses to run when the environment is Prod.

const (
	EnvLocal Env = "local"
	EnvDev   Env = "dev"
	EnvStage Env = "stage"
	EnvProd  Env = "prod"
)

func (e Env) IsProd() bool

func (e Env) Valid() bool

type Fingerprint ¶

type Fingerprint [sha256.Size]byte

Fingerprint identifies an effective configuration: the SHA-256 of its canonical *redacted* JSON rendering. Secret values never enter the hash (Secret marshals as its redaction marker), so the fingerprint is safe to log, expose as a metric label, and include in /readyz output — and two processes sharing config sections can be compared for drift (12 §7).

Note the redaction consequence: rotating a secret's VALUE (same ref) does not change the fingerprint; changing the reference does.

func FingerprintOf(v any) (Fingerprint, error)

func Load[T any](opts Options) (T, Fingerprint, error)

func (f Fingerprint) Short() string

func (f Fingerprint) String() string

type Framework ¶

type Framework struct {
	// Environment carries NO default tag: it is fail-closed (D-0010/SEC-1) —
	// the loader errors when it is absent from every layer. The compiled
	// `local` value exists only through Defaults() for tests/local tooling.
	Environment   Env       `` /* 135-byte string literal not displayed */
	SchemaVersion int       `conf:"schema_version" default:"1" json:"schema_version" doc:"config file format version"`
	HTTP          HTTP      `conf:"http" json:"http"`
	Log           Log       `conf:"log" json:"log"`
	DB            DB        `conf:"db" json:"db"`
	Telemetry     Telemetry `conf:"telemetry" json:"telemetry"`
}

Framework is the framework-owned configuration. It is loaded and validated once at boot and is immutable afterwards; hot paths read precomputed values, never stores. Fields grow phase by phase with the components that consume them (DB in Phase 2, Auth in Phase 4, …).

func Defaults() Framework

func (f Framework) CheckSharedDrift(expected string) error

func (f Framework) SharedFingerprint() (Fingerprint, error)

func (f Framework) SharedSection() SharedSection

func (f Framework) Validate() error

type HTTP ¶

type HTTP struct {
	Addr              string        `conf:"addr" default:":8080" json:"addr" doc:"HTTP listen address"`
	ReadHeaderTimeout time.Duration `conf:"read_header_timeout" default:"5s" json:"read_header_timeout" doc:"maximum time to read request headers"`
	RequestTimeout    time.Duration `conf:"request_timeout" default:"30s" json:"request_timeout" doc:"per-request handler timeout"`
	MaxBodyBytes      int64         `conf:"max_body_bytes" default:"1048576" json:"max_body_bytes" doc:"maximum request body size in bytes"`
	// CORSAllowedOrigins is the exact-match CORS allowlist (deny-by-default when
	// empty). Set per environment, e.g. modules-free base leaves it empty and the
	// prod overlay lists the product's web origins.
	CORSAllowedOrigins []string  `` /* 127-byte string literal not displayed */
	RateLimit          RateLimit `conf:"rate_limit" json:"rate_limit"`
}

HTTP holds server guardrails. Zero values are replaced by Defaults.

type Layer ¶

type Layer string

Layer identifies which precedence layer supplied a config value (blueprint 12 §3; surfaced by `wowapi config doctor`).

const (
	LayerDefault  Layer = "default"   // compiled default tag
	LayerBaseFile Layer = "base-file" // configs/base.yaml
	LayerEnvFile  Layer = "env-file"  // configs/<env>.yaml overlay
	LayerEnvVar   Layer = "env"       // PREFIX__SECTION__FIELD environment variable
	LayerFlag     Layer = "flag"      // local-only CLI flag
	LayerSecret   Layer = "secret"    // value resolved through the secret provider
)

type Loaded ¶

type Loaded[T any] struct {
	Config      T
	Fingerprint Fingerprint
	Provenance  Provenance
	// Warnings carries non-fatal findings (e.g. unsafe knobs enabled in stage).
	Warnings []string
}

Loaded is the full result of LoadDetailed.

func LoadDetailed[T any](opts Options) (Loaded[T], error)

type Log ¶

type Log struct {
	Level  string `conf:"level" default:"info" json:"level" doc:"log level: debug|info|warn|error"`
	Format string `conf:"format" default:"json" json:"format" doc:"log output format: json|text (prod requires json)"`
}

Log configures structured logging.

type MapView ¶

type MapView map[string]any

MapView is a ModuleView backed by an in-memory map. The loader produces these from the `modules.<name>` subtree; tests construct them directly.

func (m MapView) Decode(out any) error

type ModuleView ¶

type ModuleView interface {
	// Decode strict-decodes the module's namespace into the module-owned
	// typed struct. Unknown keys in the namespace are an error (typo
	// defense); the module's own validation runs after decoding. Errors here
	// fail application boot.
	Decode(out any) error
}

ModuleView is the ONLY configuration surface a module receives (via module.Context.Config()). It exposes exactly the module's own `modules.<name>.*` namespace: there is deliberately no Get(key), no parent traversal, and no way to read framework or sibling-module configuration.

type Namespaces ¶

type Namespaces map[string]MapView

Namespaces is the raw `modules.*` subtree of a product configuration: one isolated MapView per module name. The binder captures the subtree opaquely (module keys are validated by each module's own strict Decode, not by the framework binder), and the app hands each module exactly its own view — there is no API to traverse from a view back to framework, product, or sibling configuration.

type Options ¶

type Options struct {
	// BaseFile is the committed product config file (configs/base.yaml).
	BaseFile string
	// EnvFile is the environment overlay (configs/<env>.yaml).
	EnvFile string
	// EnvPrefix enables the environment-variable layer:
	// "ACME__" maps ACME__DB__MAX_CONNS=32 onto db.max_conns. Empty = no env layer.
	EnvPrefix string
	// Environ supplies the environment ("KEY=VALUE" pairs); nil = os.Environ().
	Environ []string
	// Secrets resolves secretref:// values at boot. Required if any Secret
	// field is set; resolution failures fail the load.
	Secrets secrets.Provider
	// Flags holds local-tooling overrides by dotted key ("http.addr" → value).
	// The loader refuses to start when flags are set and environment=prod.
	Flags map[string]string
}

Options configures a Load call. Zero-value fields skip their layer.

type Pool ¶

type Pool struct {
	MaxConns     int           `conf:"max_conns" default:"16" json:"max_conns" doc:"maximum pool connections"`
	QueryTimeout time.Duration `conf:"query_timeout" default:"5s" json:"query_timeout" doc:"per-query context deadline"`
}

Pool holds the connection-pool knobs shared by every process view. New pool fields belong HERE, never directly on DB: the app views embed Pool, so additions propagate to api/worker/migrate narrowing automatically instead of silently dropping out of a hand-copied field list (ARCH-17).

type Provenance ¶

type Provenance map[string]Layer

Provenance maps dotted config keys to the layer that supplied their value.

type RateLimit ¶

type RateLimit struct {
	Disabled          bool    `conf:"disabled" json:"disabled" doc:"set true to remove the default per-client rate limiter from the chain"`
	RequestsPerSecond float64 `conf:"requests_per_second" default:"20" json:"requests_per_second" doc:"sustained requests/sec per client key (per replica)"`
	Burst             int     `conf:"burst" default:"40" json:"burst" doc:"burst capacity per client key"`
}

RateLimit configures the in-process per-client rate limiter that the generated api installs in its default middleware chain (roadmap S2/CA-2). It is OPT-OUT: enabled unless Disabled is set, so a scaffolded product is protected against resource-exhaustion by default. Limits are guardrails, not billing.

type Secret ¶

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

Secret holds a resolved secret value with structural redaction: every standard rendering path (fmt verbs, JSON/text marshaling, slog) emits a redaction marker, never the value. The raw value is reachable only via Reveal, whose call sites are restricted by boundary lint to adapters and the app composition root.

The zero Secret is empty and renders as "[redacted]".

func NewSecret(ref, value string) Secret

func (s Secret) Format(f fmt.State, verb rune)

func (s Secret) GoString() string

func (s Secret) IsZero() bool

func (s Secret) LogValue() slog.Value

func (s Secret) MarshalJSON() ([]byte, error)

func (s Secret) MarshalText() ([]byte, error)

func (s Secret) Ref() string

func (s Secret) Reveal() string

func (s Secret) String() string

func (s *Secret) UnmarshalText(b []byte) error

type SharedSection ¶

type SharedSection struct {
	Environment   Env `json:"environment"`
	SchemaVersion int `json:"schema_version"`
	DB            DB  `json:"db"`
}

SharedSection is the config subset that must match across every process of one deployment.

type Telemetry ¶

type Telemetry struct {
	TraceSampleRatio float64 `` /* 176-byte string literal not displayed */
}

Telemetry configures distributed tracing (roadmap O1). Tracing is OFF by default (zero-cost NoOp tracer) and becomes active only when the sample ratio is > 0 — the composition root then wires the OTel adapter with this ratio, exporting to the OTLP endpoint named by the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable (e.g. http://jaeger:4318 in the compose stack). This is the real config key that replaces the previously-documented-but-nonexistent cfg.TraceSampleRatio (roadmap CA-2/CA-7).