Documentation
¶
Overview ¶
Package cmd provides command-line argument parsing and configuration management functionality. Supports loading configuration from command-line arguments, environment variables and configuration files.
Index ¶
- Constants
- func APIKeyWarnings(cfg *Config) []string
- func DefaultSnapshotMaxAge(taskIntervalSec int) time.Duration
- func MissingCredentialWarnings(cfg *Config) []string
- func ParseHMACAllowV1(raw string) (bool, error)
- func ParseHMACAudiences(raw string) ([]string, error)
- func ParseHMACKeys(raw string) (map[string]string, error)
- func ParseHMACRequireAudience(raw string) (bool, error)
- func ParseHTTPTimeout(raw string) (time.Duration, error)
- func ParseRateLimit(raw string) (int, error)
- func ParseRateLimitWindow(raw string) (time.Duration, error)
- func ParseRedisSnapshotRecovery(raw string) (string, error)
- func ParseRedisTLSEnabled(raw string) (bool, error)
- func ParseSnapshotMaxAge(raw string, taskIntervalSec int) (time.Duration, error)
- func ParseSnapshotReadPolicy(raw string, environment ...string) (string, error)
- func RedisSnapshotMode(raw string) string
- func RedisTLSConfig(cfg *Config) (*tls.Config, error)
- func RedisTrustWarnings(cfg *Config) []string
- func ResponseFieldWarnings(cfg *Config) []string
- func UnappliedSettingWarnings(cfg *Config) []string
- func ValidateConfig(cfg *Config) error
- type Config
Constants ¶
const MaxHTTPTimeoutSeconds = 3600
MaxHTTPTimeoutSeconds is the largest HTTP timeout accepted from any source. The timeout is multiplied into a time.Duration and added to the refresh deadline and to the lifetime of the Redis writer lock; an unbounded value overflows that arithmetic. An hour is far above any useful request timeout.
Variables ¶
This section is empty.
Functions ¶
func APIKeyWarnings ¶ added in v1.7.0
APIKeyWarnings returns non-fatal findings about the configured API key for the caller to log at startup. It only reports in production, where the key may be the sole credential. The key value is never included.
func DefaultSnapshotMaxAge ¶ added in v1.2.0
DefaultSnapshotMaxAge derives the default freshness threshold from the configured refresh interval while preserving a minimum scheduling margin.
func MissingCredentialWarnings ¶ added in v1.8.0
MissingCredentialWarnings reports a configuration without any service credential outside production. Production refuses to start in that state; the other environments start, and then every data route answers 401 with nothing in the log to say why. The warning names the settings that provide a credential.
func ParseHMACAllowV1 ¶ added in v1.0.0
ParseHMACAllowV1 parses the legacy HMAC v1 compatibility switch. The empty value is deliberately secure by default; v1 must be enabled explicitly.
func ParseHMACAudiences ¶ added in v1.8.0
ParseHMACAudiences parses WARDEN_HMAC_AUDIENCES: a comma-separated list of the names this instance accepts in a v3 signature. An entry is 1 to 255 printable ASCII characters without spaces or commas; it is lower-cased, and duplicates are dropped. The empty string yields no audience.
func ParseHMACKeys ¶ added in v1.0.0
ParseHMACKeys parses and validates the complete key set. Key identifiers are trimmed for stable lookup; secrets are preserved byte-for-byte but may not be empty or whitespace-only. Invalid entries fail the whole set closed.
func ParseHMACRequireAudience ¶ added in v1.8.0
ParseHMACRequireAudience parses WARDEN_HMAC_REQUIRE_AUDIENCE. The empty value is false: unbound signatures stay accepted unless the operator asks otherwise.
func ParseHTTPTimeout ¶ added in v1.8.0
ParseHTTPTimeout parses HTTP_TIMEOUT: a whole number of seconds ("30") or a Go duration ("30s", "1m30s"), from one second to MaxHTTPTimeoutSeconds.
func ParseRateLimit ¶ added in v1.7.0
ParseRateLimit parses RATE_LIMIT and RATE_LIMIT_AUTHENTICATED: the number of requests one client IP, or one credential, may send per window.
func ParseRateLimitWindow ¶ added in v1.7.0
ParseRateLimitWindow parses RATE_LIMIT_WINDOW. It accepts a Go duration ("30s", "1m") or a bare number of seconds, like HTTP_TIMEOUT.
func ParseRedisSnapshotRecovery ¶ added in v1.5.0
ParseRedisSnapshotRecovery normalizes the environment-only recovery policy.
func ParseRedisTLSEnabled ¶ added in v1.7.0
ParseRedisTLSEnabled parses REDIS_TLS_ENABLED. The empty value means disabled.
func ParseSnapshotMaxAge ¶ added in v1.2.0
ParseSnapshotMaxAge parses the maximum age accepted by health checks. An empty value derives a safe default from the refresh interval, with enough slack for transient scheduling delays. Operators may override it with a Go duration such as "2m"; non-positive values are rejected instead of disabling stale detection.
func ParseSnapshotReadPolicy ¶ added in v1.5.0
ParseSnapshotReadPolicy normalizes the environment-only data read policy.
func RedisSnapshotMode ¶ added in v1.5.0
RedisSnapshotMode normalizes the environment-only migration setting.
func RedisTLSConfig ¶ added in v1.7.0
RedisTLSConfig builds the client TLS configuration for Redis. It returns nil when TLS is disabled. Certificates are verified against REDIS_TLS_CA_FILE when set and against the system roots otherwise.
func RedisTrustWarnings ¶ added in v1.8.0
RedisTrustWarnings reports a production Redis connection without a password while the legacy cache is in use. Outside ONLY_LOCAL, startup adopts the rule set stored under the fixed key warden:users:cache before it reads any source, so whoever can write to that Redis instance decides who is on the allow list. Without a password that is every host that can reach it.
func ResponseFieldWarnings ¶ added in v1.8.0
ResponseFieldWarnings reports a response field allowlist that leaves out "status". The user responses then carry no status, and a caller that decides on it -- the SDK's CheckUserInList does -- reads every user as not active. The configuration is accepted: a deployment that only lists users, or that decides through /v1/lookup, which always returns the status, does not need the field.
func UnappliedSettingWarnings ¶ added in v1.8.0
UnappliedSettingWarnings returns the non-fatal findings about settings that are accepted but do not take effect as written, for the caller to log once at startup.
func ValidateConfig ¶
ValidateConfig validates configuration validity
Types ¶
type Config ¶
type Config struct {
ConfigFile string // resolved application configuration file path
Port string // 16 bytes
Redis string // 16 bytes
RedisPassword string // 16 bytes
RedisEnabled bool // 1 byte (padding to 8 bytes)
RedisUsername string // env REDIS_USERNAME: Redis ACL username (empty = default user)
RedisTLSEnabled bool // env REDIS_TLS_ENABLED: connect to Redis over TLS (default false)
RedisTLSCAFile string // env REDIS_TLS_CA_FILE: CA bundle for the Redis server certificate
RedisTLSServerName string // env REDIS_TLS_SERVER_NAME: expected Redis certificate name
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 (security policy)
LegacyModeUsedForEnv bool // true when legacy MODE was used to derive the environment (deprecation)
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 API response with RSA
RemoteRSAPrivateKeyFile string // path to PEM file for RSA decryption (preferred)
RemoteRSAPrivateKey string // inline PEM for RSA decryption (used when file not set)
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 (default legacy)
RequireExplicitUserID bool // env REQUIRE_EXPLICIT_USER_ID: reject records without user_id
SourceSetID string
SnapshotReadPolicy string
RedisSnapshotRecovery string
RedisSnapshotMode string
RedisSnapshotNamespace string
EmptyRulesetPolicy string // env EMPTY_RULESET_POLICY: consistency-first|availability-first
TaskInterval int // 8 bytes
HTTPTimeout int // 8 bytes
HTTPMaxIdleConns int // 8 bytes
HTTPInsecureTLS bool // 1 byte (padding to 8 bytes)
HMACKeys string // JSON map key_id -> secret (env WARDEN_HMAC_KEYS)
HMACToleranceSec int // env WARDEN_HMAC_TIMESTAMP_TOLERANCE, default 60
TLSCertFile string // env WARDEN_TLS_CERT
TLSKeyFile string // env WARDEN_TLS_KEY
TLSCAFile string // env WARDEN_TLS_CA (client CA for mTLS)
TLSRequireClientCert bool // env WARDEN_TLS_REQUIRE_CLIENT_CERT
// env RATE_LIMIT: requests allowed per window, per client IP
RateLimit int
// env RATE_LIMIT_AUTHENTICATED: requests allowed per window, per credential
RateLimitAuthenticated int
// env RATE_LIMIT_WINDOW
RateLimitWindow time.Duration
}
Config stores application configuration
func GetArgs
deprecated
func GetArgs() *Config
GetArgs parses command-line arguments and environment variables, returning a configuration struct. It panics when explicitly requested configuration cannot be parsed. New callers should use GetArgsWithError so the startup path can report the error cleanly.
Deprecated: use GetArgsWithError.
func GetArgsWithError ¶ added in v1.0.0
GetArgsWithError parses command-line arguments and environment variables. Priority: command-line arguments > environment variables > configuration file > default values The -config-file flag takes precedence over CONFIG_FILE. An explicitly requested configuration file is mandatory: parse, validation and filesystem errors are returned instead of silently falling back to development defaults.
func LoadConfig ¶
LoadConfig loads configuration (new interface, supports configuration file) Priority: command-line arguments > environment variables > configuration file > default values