Documentation
¶
Overview ¶
Package confx is the configuration toolkit shared by the products: koanf loading with the YAML < env < changed-flags precedence, the env key mapper, reference-YAML generation from `koanf`+`doc` struct tags, and the config sections (with validation) that both products expose verbatim.
Products own their root Config, DefaultConfig, Validate and any product-only sections (pdbq's Server/TX.PerRequest, pdbr's Server).
Index ¶
- func AuthConfig(c RLS) auth.Config
- func ChangedFlags(fs *flag.FlagSet, except ...string) *flag.FlagSet
- func Discover(names ...string) string
- func EnvKeyMapper(prefix string) func(string) string
- func ExampleYAML(v any, opts ...ExampleOption) string
- func InvalidConfig(errs []string) error
- func Load(envPrefix, path string, flags *flag.FlagSet, dst any) error
- func ParseTrustedProxy(s string) (netip.Prefix, error)
- func ValidChannelName(s string) bool
- func ValidateErrors(e Errors) []string
- func ValidateLog(l Log) []string
- func ValidateRLS(c RLS) []string
- func ValidateSchema(s Schema) []string
- func ValidateTX(t TX) []string
- func ValidateWatch(w Watch, cachePath string) []string
- type Auth
- type Database
- type Errors
- type ExampleOption
- type Filters
- type Log
- type Plugins
- type RLS
- type Schema
- type TX
- type Watch
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthConfig ¶
AuthConfig converts the rls section into an auth.Config. Invalid trusted_proxies entries are dropped (ValidateRLS rejects them; skipping here only shrinks the trusted set, never widens it); nil when none were configured, which auth treats as "trust every peer".
func ChangedFlags ¶
ChangedFlags returns a FlagSet holding only the flags explicitly set on fs, minus any names in except (e.g. "config") — the only-changed-flags bridge products hand to Load.
func Discover ¶
Discover returns the first of names that exists in the working directory (e.g. Discover("pdbq.yaml", "pdbq.yml")), or "".
func EnvKeyMapper ¶
EnvKeyMapper maps PREFIX_SERVER_MAX__DEPTH -> server.max_depth: the prefix is stripped, a double underscore preserves an underscore inside a key, and a single underscore is a level separator.
func ExampleYAML ¶
func ExampleYAML(v any, opts ...ExampleOption) string
ExampleYAML renders the commented reference configuration body from v's struct tags and current values: every `koanf` field in declaration order, its `doc` tag as a comment, nested structs as sections (blank line after each top-level one), embedded structs tagged `koanf:",squash"` (or untagged anonymous structs) inlined. Callers prepend their own header.
func InvalidConfig ¶
InvalidConfig joins validation messages into pdbq's error shape, or nil when there are none.
func Load ¶
Load layers configuration into dst (which already holds the defaults): optional YAML file, then envPrefix-prefixed environment variables, then flags. Pass only the flags the user actually set (see ChangedFlags) so unset flags cannot shadow YAML/env values; flag names are koanf paths. Validation is the caller's job.
func ParseTrustedProxy ¶
ParseTrustedProxy parses one rls.auth.trusted_proxies entry: either a CIDR block ("10.0.0.0/8") or a single IP ("10.0.0.1", treated as /32 or /128).
func ValidChannelName ¶
ValidChannelName restricts the watch NOTIFY channel to [a-zA-Z0-9_]; the value is interpolated into trigger DDL (see package watch) where broader characters cannot be safely escaped.
func ValidateRLS ¶
ValidateRLS checks the rls section: auth mode, trusted proxies, JWT secret/JWKS presence, jwt_type shape, and the anonymous role.
func ValidateTX ¶
ValidateTX checks transactions.isolation and transactions.max_retries.
func ValidateWatch ¶
ValidateWatch checks the watch section against schema.cache_path and the channel name.
Types ¶
type Auth ¶
type Auth struct {
Mode string `koanf:"mode" doc:"Claim source: 'jwt', 'headers' (behind a trusted gateway), or 'none'."`
JWTSecret string `koanf:"jwt_secret" doc:"HMAC secret for HS256/384/512 verification (jwt mode; ignored when jwks_url is set)."`
JWKSURL string `` /* 134-byte string literal not displayed */
JWKSCacheTTL time.Duration `koanf:"jwks_cache_ttl" doc:"How long fetched JWKS keys are cached; an unknown kid triggers an early refresh (key rotation)."`
JWTIssuer string `koanf:"jwt_issuer" doc:"Expected iss claim; empty skips the check."`
JWTAudience string `koanf:"jwt_audience" doc:"Expected aud claim; empty skips the check."`
HeaderPrefix string `koanf:"header_prefix" doc:"Header prefix mapped to claims in headers mode, e.g. X-Pdbq-Claim-."`
TrustedProxies []string `` /* 223-byte string literal not displayed */
JWTType string `` /* 320-byte string literal not displayed */
}
Auth is the claim source (nested under rls.auth).
type Database ¶
type Database struct {
URL string `` /* 131-byte string literal not displayed */
MaxConns int32 `koanf:"max_conns" doc:"Maximum pooled connections."`
ConnectTimeout time.Duration `koanf:"connect_timeout" doc:"Timeout for establishing a connection."`
StatementTimeout time.Duration `koanf:"statement_timeout" doc:"Per-statement timeout applied to every request (0 disables)."`
}
Database is the connection section.
type Errors ¶
type Errors struct {
Detail string `` /* 249-byte string literal not displayed */
}
Errors is the error-detail policy.
type ExampleOption ¶
type ExampleOption func(*exampleOpts)
ExampleOption customises ExampleYAML.
func WithDoc ¶
func WithDoc(path, doc string) ExampleOption
WithDoc overrides the doc comment for one koanf path (e.g. "errors.detail") — for product-specific wording on shared sections.
type Filters ¶
type Filters struct {
IndexedOnly bool `koanf:"indexed_only" doc:"Only allow filtering on columns covered by an index (default policy)."`
AllowColumns map[string][]string `koanf:"allow_columns" doc:"Per-table extra filterable columns, keyed by schema.table, overriding indexed_only."`
}
Filters is the filterable-column policy.
type Log ¶
type Log struct {
Level string `koanf:"level" doc:"Log level: debug, info, warn, error."`
Format string `koanf:"format" doc:"Log format: text or json."`
}
Log is the logging section.
type Plugins ¶
type Plugins struct {
Disabled []string `koanf:"disabled" doc:"Plugin names to disable."`
Settings map[string]map[string]any `koanf:"settings" doc:"Per-plugin configuration, keyed by plugin name."`
}
Plugins disables and configures plugins by name.
func (Plugins) DisabledSet ¶
DisabledSet returns the disabled-plugin set for registry filtering.
type RLS ¶
type RLS struct {
Enabled bool `` /* 180-byte string literal not displayed */
DefaultRole string `koanf:"default_role" doc:"Role assumed for authenticated requests without a role claim."`
AnonymousRole string `koanf:"anonymous_role" doc:"Role assumed for unauthenticated requests."`
RoleClaim string `koanf:"role_claim" doc:"JWT claim (or header name in header mode) carrying the database role."`
AllowedRoles []string `` /* 178-byte string literal not displayed */
ClaimsPrefix string `koanf:"claims_prefix" doc:"set_config namespace for request claims, e.g. pdbq.claims."`
Auth Auth `koanf:"auth"`
}
RLS is the row-level-security / identity section.
type Schema ¶
type Schema struct {
Schemas []string `koanf:"schemas" doc:"PostgreSQL schemas to expose."`
CachePath string `koanf:"cache_path" doc:"Boot from this schema cache file instead of introspecting (see pdbq schema dump)."`
Functions bool `koanf:"functions" doc:"Expose PostgreSQL functions as custom queries/mutations."`
}
Schema selects what is introspected and how.
type TX ¶
type TX struct {
Mutations bool `koanf:"mutations" doc:"Wrap every mutation in a transaction."`
Isolation string `koanf:"isolation" doc:"Transaction isolation level: read_committed, repeatable_read, serializable."`
MaxRetries int `` /* 233-byte string literal not displayed */
}
TX is the transaction policy shared by both products. pdbq adds per_request in its own wrapper.
type Watch ¶
type Watch struct {
Enabled bool `` /* 129-byte string literal not displayed */
PollInterval time.Duration `koanf:"poll_interval" doc:"Poll interval used when event triggers cannot be installed."`
Channel string `koanf:"channel" doc:"NOTIFY channel used by the DDL event trigger."`
}
Watch is the DDL watch (dev mode) section.
Source Files