Documentation
¶
Overview ¶
Package config provides configuration file loading and management functionality. Supports YAML format configuration files, and provides configuration validation and default value handling.
Package config defines the EmptyRulesetPolicy type (empty_ruleset_policy.go).
A load can succeed, return records, and still leave the effective rule set empty: identity validation runs over the whole set, but per-record format validation lives one layer down in the cache and silently drops records it rejects. An upstream that changes its phone-number formatting turns every record invalid at once while the load itself reports success.
That state is genuinely ambiguous and the service cannot tell the two readings apart:
"the upstream revoked everyone" -> the empty set is correct and must propagate "the upstream changed format" -> the empty set is an artifact and must not propagate
EmptyRulesetPolicy makes the operator choose which reading to assume. A load that genuinely returns zero records is NOT ambiguous and always propagates under both policies — otherwise revoking every user would become impossible.
Package config defines the deployment Environment type (environment.go).
Historically a single overloaded "MODE" string conflated two orthogonal concerns: the data merge strategy (ONLY_LOCAL / LOCAL_FIRST / REMOTE_FIRST / ...) and the deployment environment used for security policy (production hardening). This file introduces a dedicated Environment type so security decisions key off ENVIRONMENT only, never off the merge mode.
Package config defines the data MergeMode type (merge_mode.go).
MergeMode controls how local and remote rule sources are combined. It is distinct from Environment (which drives security policy). The legacy overloaded "MODE" env maps onto MergeMode only; it no longer influences production decisions.
Index ¶
Constants ¶
const DefaultEmptyRulesetPolicy = EmptyRulesetConsistencyFirst
DefaultEmptyRulesetPolicy preserves the historical behavior.
const DefaultEnvironment = EnvDevelopment
DefaultEnvironment is used when nothing is configured. Development is the safe default because it does not silently relax production checks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AppConfig ¶
type AppConfig struct {
Mode string `yaml:"mode"`
APIKey string `yaml:"api_key"` // API Key for authentication (recommend env)
DataFile string `yaml:"data_file"` // Local user data file path
DataDir string `yaml:"data_dir"` // Local user data directory (merge all *.json files; can be used with data_file)
ResponseFields []string `yaml:"response_fields"` // API response field whitelist (empty = all fields); e.g. ["phone","mail","user_id","status","scope","role","name"]
}
AppConfig application configuration
type CacheConfig ¶
type CacheConfig struct {
TTL time.Duration `yaml:"ttl"`
UpdateInterval time.Duration `yaml:"update_interval"`
}
CacheConfig cache configuration
type CmdConfigData ¶
type CmdConfigData struct {
Port string // 16 bytes
Redis string // 16 bytes
RedisPassword string // 16 bytes
RedisEnabled bool // 1 byte (padding to 8 bytes)
RemoteConfig string // 16 bytes
RemoteKey string // 16 bytes
Mode string // 16 bytes (merge mode; legacy MODE is a deprecated alias)
Environment string // env ENVIRONMENT: development|test|production
LegacyModeUsedForEnv bool // legacy MODE used to derive environment (deprecation signal)
APIKey string // 16 bytes
DataFile string // 16 bytes - local user data file path
DataDir string // 16 bytes - local user data directory (merge *.json)
ResponseFields []string // API response field whitelist (empty = all)
RemoteDecryptEnabled bool // decrypt remote response with RSA
RemoteRSAPrivateKeyFile string // path to PEM file for RSA decryption (preferred)
RemoteRSAPrivateKey string // inline PEM for RSA decryption (env REMOTE_RSA_PRIVATE_KEY)
RemoteEncryptionRequired bool // env REMOTE_ENCRYPTION_REQUIRED: fail closed on plaintext
RemoteEncryptionFormat string // env REMOTE_ENCRYPTION_FORMAT: auto|v2|legacy
UserIDStrategy string // env USER_ID_STRATEGY: legacy|sha256-128
EmptyRulesetPolicy string // env EMPTY_RULESET_POLICY: consistency-first|availability-first
RequireExplicitUserID bool // env REQUIRE_EXPLICIT_USER_ID: reject records without user_id
TaskInterval int // 8 bytes
HTTPTimeout int // 8 bytes
HTTPMaxIdleConns int // 8 bytes
HTTPInsecureTLS bool // 1 byte (padding to 8 bytes)
HMACKeys string // WARDEN_HMAC_KEYS
HMACToleranceSec int // WARDEN_HMAC_TIMESTAMP_TOLERANCE
TLSCertFile string // WARDEN_TLS_CERT
TLSKeyFile string // WARDEN_TLS_KEY
TLSCAFile string // WARDEN_TLS_CA
TLSRequireClientCert bool // WARDEN_TLS_REQUIRE_CLIENT_CERT
}
CmdConfigData configuration data structure (used to convert to cmd.Config, avoid circular dependency)
type Config ¶
type Config struct {
Server ServerConfig `yaml:"server"`
Redis RedisConfig `yaml:"redis"`
Remote RemoteConfig `yaml:"remote"`
HTTP HTTPConfig `yaml:"http"`
Cache CacheConfig `yaml:"cache"`
RateLimit RateLimitConfig `yaml:"rate_limit"`
App AppConfig `yaml:"app"`
Task TaskConfig `yaml:"task"`
Tracing TracingConfig `yaml:"tracing"`
}
Config application configuration struct
func LoadFromFile ¶
LoadFromFile loads configuration from configuration file Supports YAML and TOML formats (determined by file extension) Priority: configuration file > environment variables > default values
func ParseFromFile ¶ added in v1.0.0
ParseFromFile loads and merges a configuration file without semantic validation. Callers that still need to apply higher-priority CLI values must validate the final merged representation after those overrides are applied.
func (*Config) GetRedisPassword ¶
GetRedisPassword gets Redis password (handles file reading)
func (*Config) ToCmdConfig ¶
func (c *Config) ToCmdConfig() *CmdConfigData
ToCmdConfig converts to cmd.Config format
func (*Config) ToLegacyConfig ¶
func (c *Config) ToLegacyConfig() *LegacyConfig
ToLegacyConfig converts to old Config format (maintains backward compatibility)
type EmptyRulesetPolicy ¶ added in v1.3.0
type EmptyRulesetPolicy string
EmptyRulesetPolicy selects what a refresh does when a successful load returns records but none of them survive validation.
const ( // EmptyRulesetConsistencyFirst applies and publishes the empty effective set, keeping // every replica and the shared cache identical to what this process serves. // // Choose it when the upstream is the single source of truth and divergence is the // worse failure: a legitimate mass revocation propagates immediately, and an upstream // format regression surfaces at once as "everything is denied" instead of hiding // behind stale data. This is the default because failing closed is the right bias for // an allow list — serving users the source of truth no longer contains is a security // failure, while denying users is an availability failure that is loud and obvious. EmptyRulesetConsistencyFirst EmptyRulesetPolicy = "consistency-first" // EmptyRulesetAvailabilityFirst treats the all-rejected load as a failed refresh: the // last known good rule set is kept in memory and in the shared cache, the refresh // failure counter advances, and health reports degraded. // // Choose it when the availability loss outweighs the risk of briefly honouring stale // entries — typically an unstable data source combined with replicas that restart // often, where a transient upstream glitch would otherwise empty every replica and // leave restarted ones with nothing to bootstrap from. EmptyRulesetAvailabilityFirst EmptyRulesetPolicy = "availability-first" )
func ParseEmptyRulesetPolicy ¶ added in v1.3.0
func ParseEmptyRulesetPolicy(s string) (EmptyRulesetPolicy, bool)
ParseEmptyRulesetPolicy normalizes a policy string. The bool is false when the input is non-empty but unrecognized (callers should warn and fall back to the default).
func (EmptyRulesetPolicy) KeepsLastKnownGood ¶ added in v1.3.0
func (p EmptyRulesetPolicy) KeepsLastKnownGood() bool
KeepsLastKnownGood reports whether an all-rejected load must leave the current rule set in place instead of replacing it with the empty one.
func (EmptyRulesetPolicy) String ¶ added in v1.3.0
func (p EmptyRulesetPolicy) String() string
String returns the canonical string form.
func (EmptyRulesetPolicy) Validate ¶ added in v1.3.0
func (p EmptyRulesetPolicy) Validate() bool
Validate reports whether the policy is a recognized value.
type Environment ¶ added in v0.14.0
type Environment string
Environment is the deployment environment used exclusively for security policy (e.g. forbidding InsecureSkipVerify, requiring auth). It is NOT a data merge mode.
const ( // EnvDevelopment is the default, permissive environment. EnvDevelopment Environment = "development" // EnvTest is for automated/integration testing. EnvTest Environment = "test" // EnvProduction enables strict security validation. EnvProduction Environment = "production" )
func ParseEnvironment ¶ added in v0.14.0
func ParseEnvironment(s string) (Environment, bool)
ParseEnvironment normalizes an environment string. It accepts the historical "prod" alias and normalizes it to production. The returned bool is false when the input is non-empty but unrecognized (callers should warn and fall back to default).
func (Environment) IsProduction ¶ added in v0.14.0
func (e Environment) IsProduction() bool
IsProduction reports whether strict production security policy applies.
func (Environment) String ¶ added in v0.14.0
func (e Environment) String() string
String returns the canonical string form.
func (Environment) Validate ¶ added in v0.14.0
func (e Environment) Validate() bool
Validate reports whether the Environment is a recognized value.
type HTTPConfig ¶
type HTTPConfig struct {
Timeout time.Duration `yaml:"timeout"`
MaxIdleConns int `yaml:"max_idle_conns"`
InsecureTLS bool `yaml:"insecure_tls"`
MaxRetries int `yaml:"max_retries"`
RetryDelay time.Duration `yaml:"retry_delay"`
}
HTTPConfig HTTP client configuration
type LegacyConfig ¶
type LegacyConfig struct {
Port string // 16 bytes
Redis string // 16 bytes
RedisPassword string // 16 bytes
RemoteConfig string // 16 bytes
RemoteKey string // 16 bytes
Mode string // 16 bytes
TaskInterval int // 8 bytes
HTTPTimeout int // 8 bytes
HTTPMaxIdleConns int // 8 bytes
HTTPInsecureTLS bool // 1 byte (padding to 8 bytes)
}
LegacyConfig old configuration format (for backward compatibility) Note: this type has the same structure as cmd.Config, but defined in a different package
type MergeMode ¶ added in v0.14.0
type MergeMode string
MergeMode selects how local files and the remote endpoint are combined.
const ( // MergeDefault is the historical default merge behavior (remote-first, tolerant), // preserved so existing deployments that never set MODE keep working unchanged. MergeDefault MergeMode = "DEFAULT" // MergeOnlyLocal loads only local files (no remote). MergeOnlyLocal MergeMode = "ONLY_LOCAL" // MergeOnlyRemote loads only the remote endpoint (strict: remote failure is fatal). MergeOnlyRemote MergeMode = "ONLY_REMOTE" // MergeRemoteFirst prefers remote, then local (strict on remote failure). MergeRemoteFirst MergeMode = "REMOTE_FIRST" // MergeRemoteFirstAllowRemoteFail prefers remote but tolerates remote failure. MergeRemoteFirstAllowRemoteFail MergeMode = "REMOTE_FIRST_ALLOW_REMOTE_FAILED" // MergeLocalFirst prefers local, then remote (tolerant of remote failure). MergeLocalFirst MergeMode = "LOCAL_FIRST" // MergeLocalFirstAllowRemoteFail prefers local and tolerates remote failure. MergeLocalFirstAllowRemoteFail MergeMode = "LOCAL_FIRST_ALLOW_REMOTE_FAILED" )
func DefaultMergeMode ¶ added in v0.14.0
func DefaultMergeMode() MergeMode
DefaultMergeMode preserves the historical default merge behavior.
func ParseMergeMode ¶ added in v0.14.0
ParseMergeMode normalizes a merge-mode string (upper-cased, trimmed). The bool is false when the input is non-empty but unrecognized (callers should warn/fall back).
func (MergeMode) IsOnlyLocal ¶ added in v0.14.0
IsOnlyLocal reports whether remote loading is disabled.
type RateLimitConfig ¶
RateLimitConfig rate limit configuration
type RedisConfig ¶
type RedisConfig struct {
Addr string `yaml:"addr"` // 16 bytes
Password string `yaml:"password"` // 16 bytes
PasswordFile string `yaml:"password_file"` // 16 bytes
DB int `yaml:"db"` // 8 bytes
}
RedisConfig Redis configuration
type RemoteConfig ¶
type RemoteConfig struct {
URL string `yaml:"url"`
Key string `yaml:"key"`
Mode string `yaml:"mode"`
RSAPrivateKeyFile string `yaml:"rsa_private_key_file"` // path to PEM file (preferred over key in env)
DecryptEnabled bool `yaml:"decrypt_enabled"` // decrypt response with RSA private key
}
RemoteConfig remote configuration (field order optimized for alignment).
type ServerConfig ¶
type ServerConfig struct {
Port string `yaml:"port"` // 16 bytes
ReadTimeout time.Duration `yaml:"read_timeout"` // 8 bytes
WriteTimeout time.Duration `yaml:"write_timeout"` // 8 bytes
ShutdownTimeout time.Duration `yaml:"shutdown_timeout"` // 8 bytes
IdleTimeout time.Duration `yaml:"idle_timeout"` // 8 bytes
MaxHeaderBytes int `yaml:"max_header_bytes"` // 8 bytes
}
ServerConfig server configuration
type TaskConfig ¶
TaskConfig task configuration
type TracingConfig ¶ added in v0.7.0
type TracingConfig struct {
Endpoint string `yaml:"endpoint"` // OTLP endpoint (e.g., "http://localhost:4318")
Enabled bool `yaml:"enabled"`
}
TracingConfig OpenTelemetry tracing configuration