config

Documentation

Overview

Package config provides service-global configuration loaded from environment variables. It owns startup validation and fatal-exit behavior for required fields. It does not own observability wiring, network connections, or component construction. Primary dependency: os.Getenv.

Index

• type Config
  • func Load() (*Config, error)

Types

type Config

type Config struct {
	// GRPCAddr is the gRPC server listen address.
	// env: TOKEN_ENGINE_GRPC_ADDR; default: ":9090"
	// parse failure — log warning, use default
	GRPCAddr string

	// HTTPAddr is the HTTP server listen address (health, metrics, JWKS).
	// env: TOKEN_ENGINE_HTTP_ADDR; default: ":8080"
	// parse failure — log warning, use default
	HTTPAddr string

	// TLSMode controls transport security. Accepted values: "mtls", "disabled".
	// Empty string treated as "mtls".
	// env: TOKEN_ENGINE_TLS_MODE; default: "mtls"
	// unknown value — log error and os.Exit(1)
	TLSMode string

	// Issuer is the JWT issuer claim stamped on all issued tokens.
	// env: TOKEN_ENGINE_ISSUER; no default
	// empty string — log error and os.Exit(1)
	Issuer string

	// Audience is the default JWT audience claim for all issued tokens.
	// env: TOKEN_ENGINE_AUDIENCE; no default
	// empty string — log error and os.Exit(1)
	Audience string

	// OTLPEndpoint is the OpenTelemetry collector endpoint for trace export.
	// env: OTEL_EXPORTER_OTLP_ENDPOINT; default: ""
	// empty — OTel SDK no-op TracerProvider used; no traces emitted
	OTLPEndpoint string

	// IdempotencyTTL is the TTL for idempotency store entries.
	// env: TOKEN_ENGINE_IDEMPOTENCY_TTL; default: 24 * time.Hour
	// parse failure — log warning, use default
	IdempotencyTTL time.Duration

	// MaxConnectionAge is the maximum age of a gRPC connection before graceful close.
	// env: TOKEN_ENGINE_MAX_CONNECTION_AGE; default: 30 * time.Minute
	// parse failure — log warning, use default
	MaxConnectionAge time.Duration

	// MaxConnectionAgeGrace is the grace period after MaxConnectionAge before forceful close.
	// env: TOKEN_ENGINE_MAX_CONNECTION_AGE_GRACE; default: 5 * time.Minute
	// parse failure — log warning, use default
	MaxConnectionAgeGrace time.Duration

	// StaticCallerKeys is the API key → caller identity map for StaticKeyAuthenticator.
	// Format: "key1=identity1,key2=identity2". Required when TLSMode == "disabled".
	// env: TOKEN_ENGINE_STATIC_CALLER_KEYS; no default
	// parse failure or empty map when TLSMode=="disabled" — log error and os.Exit(1)
	StaticCallerKeys map[string]string

	// TLSCertFile is the path to the service's TLS certificate file (PEM).
	// env: TOKEN_ENGINE_TLS_CERT_FILE; no default
	// absent when TLSMode == "mtls" — log error and os.Exit(1)
	// ignored when TLSMode == "disabled"
	TLSCertFile string

	// TLSKeyFile is the path to the service's TLS private key file (PEM).
	// env: TOKEN_ENGINE_TLS_KEY_FILE; no default
	// absent when TLSMode == "mtls" — log error and os.Exit(1)
	// ignored when TLSMode == "disabled"
	TLSKeyFile string

	// TLSCAFile is the path to the CA certificate file for client certificate verification (PEM).
	// env: TOKEN_ENGINE_TLS_CA_FILE; no default
	// absent when TLSMode == "mtls" — log error and os.Exit(1)
	// ignored when TLSMode == "disabled"
	TLSCAFile string

	// CallerRegistryPath is the filesystem path to the caller-registry YAML file.
	// env: TOKEN_ENGINE_CALLER_REGISTRY_PATH; no default
	// absent when TLSMode == "mtls" — log error and os.Exit(1)
	// optional when TLSMode == "disabled" — empty string is valid when disabled
	CallerRegistryPath string

	// RedisAddr is the Redis server address.
	// env: TOKEN_ENGINE_REDIS_ADDR; default: "localhost:6379"
	// parse failure — log warning, use default
	RedisAddr string

	// RedisPassword is the Redis AUTH password. Empty string means no authentication.
	// env: TOKEN_ENGINE_REDIS_PASSWORD; default: ""
	// empty allowed
	RedisPassword string

	// RedisDB is the Redis logical database index.
	// env: TOKEN_ENGINE_REDIS_DB; default: 0
	// parse failure — log warning, use default
	RedisDB int

	// JWKSCacheMaxAge is the Cache-Control max-age for the JWKS endpoint response.
	// env: TOKEN_ENGINE_JWKS_CACHE_MAX_AGE; default: 5 * time.Minute
	// parse failure — log warning, use default
	JWKSCacheMaxAge time.Duration

	// LockTTL is the TTL for all distributed lock keys.
	// env: TOKEN_ENGINE_LOCK_TTL; default: 30 * time.Second
	// parse failure — log warning, use default
	LockTTL time.Duration

	// ReconciliationInterval is the time between reconciliation passes.
	// env: TOKEN_ENGINE_RECONCILIATION_INTERVAL; default: 5 * time.Minute
	// parse failure — log warning, use default
	ReconciliationInterval time.Duration

	// ReconciliationPageSize is the number of tokens fetched per ListTokens page.
	// env: TOKEN_ENGINE_RECONCILIATION_PAGE_SIZE; default: 100
	// parse failure — log warning, use default
	ReconciliationPageSize int

	// RotationWindowGuard is the minimum time since last key generation before a new key is generated.
	// env: TOKEN_ENGINE_ROTATION_WINDOW_GUARD; default: 1 * time.Minute
	// parse failure — log warning, use default
	RotationWindowGuard time.Duration
}

Config holds service-global configuration loaded from environment variables. All validation happens during Load() — no network connections are opened. Fatal validation (Issuer, Audience, TLSMode, StaticCallerKeys) occurs before defaults are applied.

func Load

func Load() (*Config, error)

Load reads environment variables and validates them into a *Config. Fatal validation (Issuer, Audience, TLSMode, StaticCallerKeys) occurs before defaults. Duration and integer parse failures log a warning and use defaults. Returns *Config on success or exits fatally on required-field violations.