config

package
v1.6.2 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
const DefaultEmptyRulesetPolicy = EmptyRulesetConsistencyFirst

DefaultEmptyRulesetPolicy preserves the historical behavior.

View Source
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

func LoadFromFile(configPath string) (*Config, error)

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

func ParseFromFile(configPath string) (*Config, error)

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

func (c *Config) GetRedisPassword() (string, error)

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

func ParseMergeMode(s string) (MergeMode, bool)

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

func (m MergeMode) IsOnlyLocal() bool

IsOnlyLocal reports whether remote loading is disabled.

func (MergeMode) String added in v0.14.0

func (m MergeMode) String() string

String returns the canonical (upper-case) string form.

func (MergeMode) Validate added in v0.14.0

func (m MergeMode) Validate() bool

Validate reports whether the MergeMode is a recognized value.

type RateLimitConfig

type RateLimitConfig struct {
	Rate   int           `yaml:"rate"`
	Window time.Duration `yaml:"window"`
}

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

type TaskConfig struct {
	Interval time.Duration `yaml:"interval"`
}

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

Jump to

Keyboard shortcuts

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