config

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Dec 5, 2025 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Cache Configuration Keys
	TestKeyCacheEnabled    = "cache.enabled"
	TestKeyCacheType       = "cache.type"
	TestKeyCacheRedisHost  = "cache.redis.host"
	TestKeyCacheRedisPort  = "cache.redis.port"
	TestKeyCacheRedisDB    = "cache.redis.database"
	TestKeyCacheManagerMax = "cache.manager.max_size"
	TestKeyCacheManagerTTL = "cache.manager.idle_ttl"

	// Messaging Configuration Keys
	TestKeyMessagingBrokerURL      = "messaging.broker.url"
	TestKeyMessagingBrokerHost     = "messaging.broker.host"
	TestKeyMessagingBrokerPort     = "messaging.broker.port"
	TestKeyMessagingBrokerUser     = "messaging.broker.username"
	TestKeyMessagingBrokerPassword = "messaging.broker.password"

	// Server Configuration Keys
	TestKeyServerPort            = "server.port"
	TestKeyServerHost            = "server.host"
	TestKeyServerTimeoutRead     = "server.timeout.read"
	TestKeyServerTimeoutWrite    = "server.timeout.write"
	TestKeyServerTimeoutIdle     = "server.timeout.idle"
	TestKeyServerTimeoutShutdown = "server.timeout.shutdown"

	// Database Configuration Keys
	TestKeyDatabaseType             = "database.type"
	TestKeyDatabaseHost             = "database.host"
	TestKeyDatabasePort             = "database.port"
	TestKeyDatabaseUsername         = "database.username"
	TestKeyDatabasePassword         = "database.password"
	TestKeyDatabaseName             = "database.database"
	TestKeyDatabaseConnectionString = "database.connection_string"

	// Observability Configuration Keys
	TestKeyObservabilityEnabled        = "observability.enabled"
	TestKeyObservabilityServiceName    = "observability.service.name"
	TestKeyObservabilityTraceEnabled   = "observability.trace.enabled"
	TestKeyObservabilityMetricsEnabled = "observability.metrics.enabled"
	TestKeyObservabilityLogsEnabled    = "observability.logs.enabled"

	// Custom/Mock Configuration Keys
	// These are used in config injection tests (see config/injection_test.go)
	TestKeyCustomAPIKey     = "custom.api.key"
	TestKeyCustomAPITimeout = "custom.api.timeout"
	TestKeyCustomAPIRetries = "custom.api.retries"
)
View Source 
const (
	SourceTypeStatic  = "static"
	SourceTypeDynamic = "dynamic"
)

Source type constants

View Source 
const (
	PostgreSQL = "postgresql"
	Oracle     = "oracle"
	MongoDB    = "mongodb"
)

Database type constants

View Source 
const (
	EnvDevelopment = "development"
	EnvStaging     = "staging"
	EnvProduction  = "production"
)

Environment constants

Variables

View Source 
var (
	// ErrNotConfigured indicates a feature is intentionally not configured (not an error state)
	ErrNotConfigured = errors.New("not configured")
)

Sentinel errors for common configuration states

Functions

func IsDatabaseConfigured added in v0.4.1 

func IsDatabaseConfigured(cfg *DatabaseConfig) bool

IsDatabaseConfigured determines if database is intentionally configured. This mirrors the logic used in app.isDatabaseEnabled() for consistency.

func IsMessagingConfigured added in v0.11.2 

func IsMessagingConfigured(cfg *MessagingConfig) bool

IsMessagingConfigured determines if messaging is intentionally configured. This mirrors the logic used to determine if messaging should be initialized.

func IsNotConfigured added in v0.11.3 

func IsNotConfigured(err error) bool

IsNotConfigured checks if an error indicates a feature is not configured. Returns true for ConfigError with category "not_configured" or errors wrapping ErrNotConfigured.

func Validate 

func Validate(cfg *Config) error

Types

type AppConfig 

type AppConfig struct {
	Name      string        `koanf:"name" json:"name" yaml:"name" toml:"name" mapstructure:"name"`
	Version   string        `koanf:"version" json:"version" yaml:"version" toml:"version" mapstructure:"version"`
	Env       string        `koanf:"env" json:"env" yaml:"env" toml:"env" mapstructure:"env"`
	Debug     bool          `koanf:"debug" json:"debug" yaml:"debug" toml:"debug" mapstructure:"debug"`
	Namespace string        `koanf:"namespace" json:"namespace" yaml:"namespace" toml:"namespace" mapstructure:"namespace"`
	Rate      RateConfig    `koanf:"rate" json:"rate" yaml:"rate" toml:"rate" mapstructure:"rate"`
	Startup   StartupConfig `koanf:"startup" json:"startup" yaml:"startup" toml:"startup" mapstructure:"startup"`
}

AppConfig holds general application settings.

type AuthConfig added in v0.7.1 

type AuthConfig struct {
	Source string `koanf:"source" json:"source" yaml:"source" toml:"source" mapstructure:"source"`
}

AuthConfig holds MongoDB authentication source settings.

type BrokerConfig added in v0.7.1 

type BrokerConfig struct {
	URL         string `koanf:"url" json:"url" yaml:"url" toml:"url" mapstructure:"url"`
	VirtualHost string `koanf:"virtualhost" json:"virtualhost" yaml:"virtualhost" toml:"virtualhost" mapstructure:"virtualhost"`
}

BrokerConfig holds message broker connection settings.

type CacheConfig added in v0.18.0 

type CacheConfig struct {
	Enabled bool               `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`
	Type    string             `koanf:"type" json:"type" yaml:"type" toml:"type" mapstructure:"type"` // redis
	Redis   RedisConfig        `koanf:"redis" json:"redis" yaml:"redis" toml:"redis" mapstructure:"redis"`
	Manager CacheManagerConfig `koanf:"manager" json:"manager" yaml:"manager" toml:"manager" mapstructure:"manager"`
}

CacheConfig holds cache backend settings. Production-safe defaults are applied automatically when cache is enabled.

type CacheManagerConfig added in v0.19.0 

type CacheManagerConfig struct {
	// MaxSize is the maximum number of active cache instances.
	// 0 = use default (100); negative values are invalid.
	// Set higher for applications with many tenants.
	MaxSize int `koanf:"max_size" json:"max_size" yaml:"max_size" toml:"max_size" mapstructure:"max_size"`

	// IdleTTL is the idle timeout before cache instances are closed.
	// Default: 15m. Set lower for memory-constrained environments.
	IdleTTL time.Duration `koanf:"idle_ttl" json:"idle_ttl" yaml:"idle_ttl" toml:"idle_ttl" mapstructure:"idle_ttl"`

	// CleanupInterval is how often the cleanup goroutine runs.
	// Default: 5m. Should be less than IdleTTL for effective cleanup.
	CleanupInterval time.Duration `` /* 128-byte string literal not displayed */
}

CacheManagerConfig holds cache manager lifecycle settings. Production-safe defaults are applied automatically:

  • MaxSize: 100 (maximum tenant cache instances)
  • IdleTTL: 15m (idle timeout per cache)
  • CleanupInterval: 5m (cleanup goroutine frequency)

type ConcernConfig added in v0.7.1 

type ConcernConfig struct {
	Write string `koanf:"write" json:"write" yaml:"write" toml:"write" mapstructure:"write"`
}

ConcernConfig holds MongoDB write concern settings.

type Config 

type Config struct {
	App         AppConfig         `koanf:"app" json:"app" yaml:"app" toml:"app" mapstructure:"app"`
	Server      ServerConfig      `koanf:"server" json:"server" yaml:"server" toml:"server" mapstructure:"server"`
	Database    DatabaseConfig    `koanf:"database" json:"database" yaml:"database" toml:"database" mapstructure:"database"`
	Cache       CacheConfig       `koanf:"cache" json:"cache" yaml:"cache" toml:"cache" mapstructure:"cache"`
	Log         LogConfig         `koanf:"log" json:"log" yaml:"log" toml:"log" mapstructure:"log"`
	Messaging   MessagingConfig   `koanf:"messaging" json:"messaging" yaml:"messaging" toml:"messaging" mapstructure:"messaging"`
	Multitenant MultitenantConfig `koanf:"multitenant" json:"multitenant" yaml:"multitenant" toml:"multitenant" mapstructure:"multitenant"`
	Debug       DebugConfig       `koanf:"debug" json:"debug" yaml:"debug" toml:"debug" mapstructure:"debug"`
	Source      SourceConfig      `koanf:"source" json:"source" yaml:"source" toml:"source" mapstructure:"source"`
	Scheduler   SchedulerConfig   `koanf:"scheduler" json:"scheduler" yaml:"scheduler" toml:"scheduler" mapstructure:"scheduler"`
	// contains filtered or unexported fields
}

Config represents the overall application configuration structure. It includes sections for application settings, server parameters, database connection details, logging preferences, and messaging options. The embedded koanf.Koanf instance allows for flexible access to additional custom configurations not explicitly defined in the struct.

func Load 

func Load() (*Config, error)

Load loads configuration from multiple sources with priority: 1. Environment variables (highest priority) 2. YAML configuration files 3. Default values (lowest priority)

func (*Config) All added in v0.4.0 

func (c *Config) All() map[string]any

All returns all configuration as a flattened map.

func (*Config) Bool added in v0.19.0 

func (c *Config) Bool(key string, defaultVal ...bool) bool

Bool retrieves a bool value from the configuration or the provided default.

func (*Config) Custom added in v0.4.0 

func (c *Config) Custom() map[string]any

Custom returns the values under the `custom` namespace.

func (*Config) Exists added in v0.4.0 

func (c *Config) Exists(key string) bool

Exists checks if a configuration key exists.

func (*Config) Float64 added in v0.19.0 

func (c *Config) Float64(key string, defaultVal ...float64) float64

Float64 retrieves a float64 value from the configuration or the provided default.

func (*Config) InjectInto added in v0.6.0 

func (c *Config) InjectInto(target any) error

InjectInto populates a struct with configuration values based on struct tags. It supports the following struct tags:

  • `config:"key.path"` - specifies the configuration key to use
  • `required:"true"` - marks the field as required (default: false)
  • `default:"value"` - provides a default value if the config key is missing

Supported field types: string, int, int64, float64, bool, time.Duration

func (*Config) Int added in v0.19.0 

func (c *Config) Int(key string, defaultVal ...int) int

Int retrieves an int value from the configuration or the provided default.

func (*Config) Int64 added in v0.19.0 

func (c *Config) Int64(key string, defaultVal ...int64) int64

Int64 retrieves an int64 value from the configuration or the provided default.

func (*Config) RequiredBool added in v0.19.0 

func (c *Config) RequiredBool(key string) (bool, error)

RequiredBool retrieves a required bool value from the configuration.

func (*Config) RequiredFloat64 added in v0.19.0 

func (c *Config) RequiredFloat64(key string) (float64, error)

RequiredFloat64 retrieves a required float64 value from the configuration.

func (*Config) RequiredInt added in v0.19.0 

func (c *Config) RequiredInt(key string) (int, error)

RequiredInt retrieves a required int value from the configuration.

func (*Config) RequiredInt64 added in v0.19.0 

func (c *Config) RequiredInt64(key string) (int64, error)

RequiredInt64 retrieves a required int64 value from the configuration.

func (*Config) RequiredString added in v0.19.0 

func (c *Config) RequiredString(key string) (string, error)

RequiredString retrieves a required string value from the configuration.

func (*Config) String added in v0.19.0 

func (c *Config) String(key string, defaultVal ...string) string

String retrieves a string value from the configuration or the provided default.

func (*Config) Unmarshal added in v0.4.0 

func (c *Config) Unmarshal(key string, out any) error

Unmarshal unmarshals a configuration section into the provided struct.

type ConfigError added in v0.11.3 

type ConfigError struct {
	Category string   // error category: "missing", "invalid", "not_configured", "connection"
	Field    string   // config field path (e.g., "database.host", "messaging.broker.url")
	Message  string   // user-friendly error message (lowercase)
	Action   string   // actionable instruction (lowercase)
	Details  []string // additional details or examples
}

ConfigError represents a configuration error with actionable guidance. All error messages are lowercase following Go conventions.

func NewConnectionError added in v0.11.3 

func NewConnectionError(resource, message string, troubleshooting []string) *ConfigError

NewConnectionError creates an error for connection failures with configured resources.

func NewInvalidFieldError added in v0.11.3 

func NewInvalidFieldError(field, message string, validOptions []string) *ConfigError

NewInvalidFieldError creates an error for an invalid configuration value.

func NewMissingFieldError added in v0.11.3 

func NewMissingFieldError(field, envVar, yamlPath string) *ConfigError

NewMissingFieldError creates an error for a required missing configuration field.

func NewMultiTenantError added in v0.11.3 

func NewMultiTenantError(tenantID, field, message, action string) *ConfigError

NewMultiTenantError creates an error specific to multi-tenant configuration.

func NewNotConfiguredError added in v0.11.3 

func NewNotConfiguredError(feature, envVar, yamlPath string) *ConfigError

NewNotConfiguredError creates an informational error for optional features. This indicates the feature is intentionally not configured, not an error state.

func NewValidationError added in v0.11.3 

func NewValidationError(field, message string) *ConfigError

NewValidationError creates a general validation error with custom message.

func (*ConfigError) Error added in v0.11.3 

func (e *ConfigError) Error() string

Error implements the error interface with lowercase formatting.

func (*ConfigError) Unwrap added in v0.11.3 

func (e *ConfigError) Unwrap() error

Unwrap returns nil to maintain compatibility with error wrapping. ConfigError is a leaf error that contains all necessary context.

type DatabaseConfig 

type DatabaseConfig struct {
	Type     string `koanf:"type" json:"type" yaml:"type" toml:"type" mapstructure:"type"`
	Host     string `koanf:"host" json:"host" yaml:"host" toml:"host" mapstructure:"host"`
	Port     int    `koanf:"port" json:"port" yaml:"port" toml:"port" mapstructure:"port"`
	Database string `koanf:"database" json:"database" yaml:"database" toml:"database" mapstructure:"database"`
	Username string `koanf:"username" json:"username" yaml:"username" toml:"username" mapstructure:"username"`
	Password string `koanf:"password" json:"password" yaml:"password" toml:"password" mapstructure:"password"`

	ConnectionString string `` /* 128-byte string literal not displayed */

	Pool  PoolConfig  `koanf:"pool" json:"pool" yaml:"pool" toml:"pool" mapstructure:"pool"`
	Query QueryConfig `koanf:"query" json:"query" yaml:"query" toml:"query" mapstructure:"query"`
	TLS   TLSConfig   `koanf:"tls" json:"tls" yaml:"tls" toml:"tls" mapstructure:"tls"`

	PostgreSQL PostgreSQLConfig `koanf:"postgresql" json:"postgresql" yaml:"postgresql" toml:"postgresql" mapstructure:"postgresql"`
	Oracle     OracleConfig     `koanf:"oracle" json:"oracle" yaml:"oracle" toml:"oracle" mapstructure:"oracle"`
	Mongo      MongoConfig      `koanf:"mongo" json:"mongo" yaml:"mongo" toml:"mongo" mapstructure:"mongo"`
}

DatabaseConfig holds database connection settings.

type DebugConfig added in v0.11.0 

type DebugConfig struct {
	Enabled     bool                 `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`                     // Enable debug endpoints
	PathPrefix  string               `koanf:"pathprefix" json:"pathprefix" yaml:"pathprefix" toml:"pathprefix" mapstructure:"pathprefix"`      // URL path prefix for debug endpoints
	AllowedIPs  []string             `koanf:"allowedips" json:"allowedips" yaml:"allowedips" toml:"allowedips" mapstructure:"allowedips"`      // List of allowed IP addresses/CIDRs
	BearerToken string               `koanf:"bearertoken" json:"bearertoken" yaml:"bearertoken" toml:"bearertoken" mapstructure:"bearertoken"` // Optional bearer token for authentication
	Endpoints   DebugEndpointsConfig `koanf:"endpoints" json:"endpoints" yaml:"endpoints" toml:"endpoints" mapstructure:"endpoints"`           // Individual endpoint settings
}

DebugConfig holds debug endpoint settings.

type DebugEndpointsConfig added in v0.11.0 

type DebugEndpointsConfig struct {
	Goroutines bool `koanf:"goroutines" json:"goroutines" yaml:"goroutines" toml:"goroutines" mapstructure:"goroutines"` // Enable goroutine analysis endpoint
	GC         bool `koanf:"gc" json:"gc" yaml:"gc" toml:"gc" mapstructure:"gc"`                                         // Enable garbage collection endpoints
	Health     bool `koanf:"health" json:"health" yaml:"health" toml:"health" mapstructure:"health"`                     // Enable enhanced health endpoint
	Info       bool `koanf:"info" json:"info" yaml:"info" toml:"info" mapstructure:"info"`                               // Enable system info endpoint
}

DebugEndpointsConfig holds settings for individual debug endpoints.

type IPPreGuardConfig added in v0.9.0 

type IPPreGuardConfig struct {
	Enabled   bool `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`           // enable IP pre-guard rate limiting
	Threshold int  `koanf:"threshold" json:"threshold" yaml:"threshold" toml:"threshold" mapstructure:"threshold"` // requests per second limit per IP
}

IPPreGuardConfig holds IP pre-guard rate limiting settings.

type LifetimeConfig added in v0.7.1 

type LifetimeConfig struct {
	// Max is the maximum duration a connection may be reused before closing.
	// This forces periodic connection recycling for memory hygiene, DNS re-resolution,
	// and server-side resource cleanup.
	// Default: 30m. Set to 0 for no lifetime limit (not recommended for cloud deployments).
	Max time.Duration `koanf:"max" json:"max" yaml:"max" toml:"max" mapstructure:"max"`
}

LifetimeConfig holds maximum lifetime settings for connections.

type LimitsConfig added in v0.9.0 

type LimitsConfig struct {
	Tenants int `koanf:"tenants" json:"tenants" yaml:"tenants" toml:"tenants" mapstructure:"tenants"`
}

LimitsConfig holds resource limits for multi-tenant operation.

type LogConfig 

type LogConfig struct {
	Level  string       `koanf:"level" json:"level" yaml:"level" toml:"level" mapstructure:"level"`
	Pretty bool         `koanf:"pretty" json:"pretty" yaml:"pretty" toml:"pretty" mapstructure:"pretty"`
	Output OutputConfig `koanf:"output" json:"output" yaml:"output" toml:"output" mapstructure:"output"`
}

LogConfig holds logging settings.

type MessagingConfig 

type MessagingConfig struct {
	Broker    BrokerConfig        `koanf:"broker" json:"broker" yaml:"broker" toml:"broker" mapstructure:"broker"`
	Routing   RoutingConfig       `koanf:"routing" json:"routing" yaml:"routing" toml:"routing" mapstructure:"routing"`
	Headers   map[string]string   `koanf:"headers" json:"headers" yaml:"headers" toml:"headers" mapstructure:"headers"`
	Reconnect ReconnectConfig     `koanf:"reconnect" json:"reconnect" yaml:"reconnect" toml:"reconnect" mapstructure:"reconnect"`
	Publisher PublisherPoolConfig `koanf:"publisher" json:"publisher" yaml:"publisher" toml:"publisher" mapstructure:"publisher"`
}

MessagingConfig holds messaging/broker settings. Production-safe defaults are applied automatically when messaging is configured.

type MongoConfig added in v0.7.1 

type MongoConfig struct {
	Replica ReplicaConfig `koanf:"replica" json:"replica" yaml:"replica" toml:"replica" mapstructure:"replica"`
	Auth    AuthConfig    `koanf:"auth" json:"auth" yaml:"auth" toml:"auth" mapstructure:"auth"`
	Concern ConcernConfig `koanf:"concern" json:"concern" yaml:"concern" toml:"concern" mapstructure:"concern"`
}

MongoConfig holds MongoDB-specific database settings.

type MultitenantConfig added in v0.9.0 

type MultitenantConfig struct {
	Enabled  bool                   `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`
	Resolver ResolverConfig         `koanf:"resolver" json:"resolver" yaml:"resolver" toml:"resolver" mapstructure:"resolver"`
	Limits   LimitsConfig           `koanf:"limits" json:"limits" yaml:"limits" toml:"limits" mapstructure:"limits"`
	Tenants  map[string]TenantEntry `koanf:"tenants" json:"tenants" yaml:"tenants" toml:"tenants" mapstructure:"tenants"`
}

MultitenantConfig holds multi-tenant specific settings.

type OracleConfig added in v0.7.1 

type OracleConfig struct {
	Service ServiceConfig `koanf:"service" json:"service" yaml:"service" toml:"service" mapstructure:"service"`
}

OracleConfig holds Oracle-specific database settings.

type OutputConfig added in v0.7.1 

type OutputConfig struct {
	Format string `koanf:"format" json:"format" yaml:"format" toml:"format" mapstructure:"format"`
	File   string `koanf:"file" json:"file" yaml:"file" toml:"file" mapstructure:"file"`
}

OutputConfig holds log output settings.

type PathConfig added in v0.7.1 

type PathConfig struct {
	Base   string `koanf:"base" json:"base" yaml:"base" toml:"base" mapstructure:"base"`
	Health string `koanf:"health" json:"health" yaml:"health" toml:"health" mapstructure:"health"`
	Ready  string `koanf:"ready" json:"ready" yaml:"ready" toml:"ready" mapstructure:"ready"`
}

PathConfig holds URL path settings for the server.

type PoolConfig added in v0.7.1 

type PoolConfig struct {
	Max       PoolMaxConfig       `koanf:"max" json:"max" yaml:"max" toml:"max" mapstructure:"max"`
	Idle      PoolIdleConfig      `koanf:"idle" json:"idle" yaml:"idle" toml:"idle" mapstructure:"idle"`
	Lifetime  LifetimeConfig      `koanf:"lifetime" json:"lifetime" yaml:"lifetime" toml:"lifetime" mapstructure:"lifetime"`
	KeepAlive PoolKeepAliveConfig `koanf:"keepalive" json:"keepalive" yaml:"keepalive" toml:"keepalive" mapstructure:"keepalive"`
}

PoolConfig holds connection pool settings. Production-safe defaults are applied automatically when database is configured:

  • Max.Connections: 25 (maximum open connections)
  • Idle.Connections: 2 (minimum warm connections)
  • Idle.Time: 5m (close idle connections before NAT/firewall timeout)
  • Lifetime.Max: 30m (periodic connection recycling)
  • KeepAlive.Enabled: true (TCP keep-alive probes)
  • KeepAlive.Interval: 60s (probe interval, below typical NAT timeouts)

type PoolIdleConfig added in v0.7.1 

type PoolIdleConfig struct {
	// Connections is the minimum number of idle connections to maintain in the pool.
	// Default: 2. Maintains warm connections to reduce cold-start latency.
	Connections int32 `koanf:"connections" json:"connections" yaml:"connections" toml:"connections" mapstructure:"connections"`

	// Time is the maximum duration an idle connection may remain unused before closing.
	// This prevents stale connections from accumulating when traffic decreases.
	// Default: 5m. Should be shorter than NAT/firewall idle timeouts (AWS: 350s, GCP: 30s).
	// Combined with KeepAlive, connections are recycled before becoming stale.
	Time time.Duration `koanf:"time" json:"time" yaml:"time" toml:"time" mapstructure:"time"`
}

PoolIdleConfig holds idle connections settings.

type PoolKeepAliveConfig added in v0.18.2 

type PoolKeepAliveConfig struct {
	// Enabled enables TCP keep-alive probes on database connections.
	// Default: true. Recommended for all cloud deployments.
	Enabled bool `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`

	// Interval is the time between keep-alive probes (TCP_KEEPINTVL).
	// The kernel sends a probe every Interval to keep the connection alive.
	// Default: 60s. Should be less than NAT/LB idle timeout (AWS: 350s, GCP: 600s).
	Interval time.Duration `koanf:"interval" json:"interval" yaml:"interval" toml:"interval" mapstructure:"interval"`
}

PoolKeepAliveConfig holds TCP keep-alive settings for database connections. TCP Keep-Alive sends periodic probes to prevent NAT gateways, load balancers, and firewalls from dropping idle connections. This is essential for cloud deployments (AWS, GCP, Azure) where infrastructure typically has idle connection timeouts (e.g., AWS NAT Gateway: 350 seconds).

type PoolMaxConfig added in v0.7.1 

type PoolMaxConfig struct {
	// Connections is the maximum number of open connections to the database.
	// Default: 25. Set based on your workload and database server capacity.
	Connections int32 `koanf:"connections" json:"connections" yaml:"connections" toml:"connections" mapstructure:"connections"`
}

PoolMaxConfig holds maximum connections settings.

type PostgreSQLConfig added in v0.12.0 

type PostgreSQLConfig struct {
	Schema string `koanf:"schema" json:"schema" yaml:"schema" toml:"schema" mapstructure:"schema"`
}

PostgreSQLConfig holds PostgreSQL-specific database settings.

type PublisherPoolConfig added in v0.19.0 

type PublisherPoolConfig struct {
	// MaxCached is the maximum number of publisher clients to keep in the cache.
	// Default: 50. Set higher for applications with many tenants.
	MaxCached int `koanf:"max_cached" json:"max_cached" yaml:"max_cached" toml:"max_cached" mapstructure:"max_cached"`

	// IdleTTL is the time after which idle publisher clients are evicted.
	// Default: 10m. Set lower for memory-constrained environments.
	IdleTTL time.Duration `koanf:"idle_ttl" json:"idle_ttl" yaml:"idle_ttl" toml:"idle_ttl" mapstructure:"idle_ttl"`
}

PublisherPoolConfig holds publisher cache/pool settings. Production-safe defaults are applied automatically:

  • MaxCached: 50 (maximum publisher clients in cache)
  • IdleTTL: 10m (time before idle publishers are evicted)

type QueryConfig added in v0.7.1 

type QueryConfig struct {
	Slow SlowQueryConfig `koanf:"slow" json:"slow" yaml:"slow" toml:"slow" mapstructure:"slow"`
	Log  QueryLogConfig  `koanf:"log" json:"log" yaml:"log" toml:"log" mapstructure:"log"`
}

QueryConfig holds settings related to query logging and slow query detection.

type QueryLogConfig added in v0.7.1 

type QueryLogConfig struct {
	Parameters bool `koanf:"parameters" json:"parameters" yaml:"parameters" toml:"parameters" mapstructure:"parameters"`
	MaxLength  int  `koanf:"max" json:"max" yaml:"max" toml:"max" mapstructure:"max"`
}

QueryLogConfig holds settings for query logging.

type RateConfig added in v0.7.0 

type RateConfig struct {
	Limit      int              `koanf:"limit" json:"limit" yaml:"limit" toml:"limit" mapstructure:"limit"`
	Burst      int              `koanf:"burst" json:"burst" yaml:"burst" toml:"burst" mapstructure:"burst"`
	IPPreGuard IPPreGuardConfig `koanf:"ippreguard" json:"ippreguard" yaml:"ippreguard" toml:"ippreguard" mapstructure:"ippreguard"`
}

RateConfig holds rate limiting settings.

type ReconnectConfig added in v0.19.0 

type ReconnectConfig struct {
	// Delay is the initial delay between reconnection attempts.
	// Default: 5s. Set higher for unstable networks.
	Delay time.Duration `koanf:"delay" json:"delay" yaml:"delay" toml:"delay" mapstructure:"delay"`

	// ReinitDelay is the delay before channel reinitialization after failure.
	// Default: 2s.
	ReinitDelay time.Duration `koanf:"reinit_delay" json:"reinit_delay" yaml:"reinit_delay" toml:"reinit_delay" mapstructure:"reinit_delay"`

	// ResendDelay is the delay before retrying a failed publish operation.
	// Default: 5s.
	ResendDelay time.Duration `koanf:"resend_delay" json:"resend_delay" yaml:"resend_delay" toml:"resend_delay" mapstructure:"resend_delay"`

	// ConnectionTimeout is the timeout for connection establishment and publish confirmation.
	// Default: 30s. Set higher for high-latency networks.
	ConnectionTimeout time.Duration `` /* 138-byte string literal not displayed */

	// MaxDelay is the maximum delay for exponential backoff during reconnection.
	// Default: 60s. Prevents unbounded delays during prolonged outages.
	MaxDelay time.Duration `koanf:"max_delay" json:"max_delay" yaml:"max_delay" toml:"max_delay" mapstructure:"max_delay"`
}

ReconnectConfig holds AMQP reconnection settings. Production-safe defaults are applied automatically:

  • Delay: 5s (initial delay between reconnection attempts)
  • ReinitDelay: 2s (delay before channel reinitialization)
  • ResendDelay: 5s (delay before retrying failed publishes)
  • ConnectionTimeout: 30s (timeout for connection/confirmation)
  • MaxDelay: 60s (maximum delay for exponential backoff cap)

type RedisConfig added in v0.18.0 

type RedisConfig struct {
	Host            string        `koanf:"host" json:"host" yaml:"host" toml:"host" mapstructure:"host"`
	Port            int           `koanf:"port" json:"port" yaml:"port" toml:"port" mapstructure:"port"`
	Password        string        `koanf:"password" json:"password" yaml:"password" toml:"password" mapstructure:"password"`
	Database        int           `koanf:"database" json:"database" yaml:"database" toml:"database" mapstructure:"database"`
	PoolSize        int           `koanf:"poolsize" json:"poolsize" yaml:"poolsize" toml:"poolsize" mapstructure:"poolsize"`
	DialTimeout     time.Duration `koanf:"dialtimeout" json:"dialtimeout" yaml:"dialtimeout" toml:"dialtimeout" mapstructure:"dialtimeout"`
	ReadTimeout     time.Duration `koanf:"readtimeout" json:"readtimeout" yaml:"readtimeout" toml:"readtimeout" mapstructure:"readtimeout"`
	WriteTimeout    time.Duration `koanf:"writetimeout" json:"writetimeout" yaml:"writetimeout" toml:"writetimeout" mapstructure:"writetimeout"`
	MaxRetries      int           `koanf:"maxretries" json:"maxretries" yaml:"maxretries" toml:"maxretries" mapstructure:"maxretries"`
	MinRetryBackoff time.Duration `koanf:"minretrybackoff" json:"minretrybackoff" yaml:"minretrybackoff" toml:"minretrybackoff" mapstructure:"minretrybackoff"`
	MaxRetryBackoff time.Duration `koanf:"maxretrybackoff" json:"maxretrybackoff" yaml:"maxretrybackoff" toml:"maxretrybackoff" mapstructure:"maxretrybackoff"`
}

RedisConfig holds Redis-specific cache settings.

type ReplicaConfig added in v0.7.1 

type ReplicaConfig struct {
	Set        string `koanf:"set" json:"set" yaml:"set" toml:"set" mapstructure:"set"`
	Preference string `koanf:"preference" json:"preference" yaml:"preference" toml:"preference" mapstructure:"preference"`
}

ReplicaConfig holds MongoDB replica set and read preference settings.

type ResolverConfig added in v0.9.0 

type ResolverConfig struct {
	Type    string `koanf:"type" json:"type" yaml:"type" toml:"type" mapstructure:"type"`                // header, subdomain, composite
	Header  string `koanf:"header" json:"header" yaml:"header" toml:"header" mapstructure:"header"`      // default: X-Tenant-ID
	Domain  string `koanf:"domain" json:"domain" yaml:"domain" toml:"domain" mapstructure:"domain"`      // e.g., api.example.com or .api.example.com (leading dot optional)
	Proxies bool   `koanf:"proxies" json:"proxies" yaml:"proxies" toml:"proxies" mapstructure:"proxies"` // trust X-Forwarded-Host
}

ResolverConfig holds tenant resolution strategy settings.

type RoutingConfig added in v0.7.1 

type RoutingConfig struct {
	Exchange string `koanf:"exchange" json:"exchange" yaml:"exchange" toml:"exchange" mapstructure:"exchange"`
	Key      string `koanf:"key" json:"key" yaml:"key" toml:"key" mapstructure:"key"`
}

RoutingConfig holds message routing settings.

type SchedulerConfig added in v0.14.0 

type SchedulerConfig struct {
	Security SchedulerSecurityConfig `koanf:"security" json:"security" yaml:"security" toml:"security" mapstructure:"security"`
	Timeout  SchedulerTimeoutConfig  `koanf:"timeout" json:"timeout" yaml:"timeout" toml:"timeout" mapstructure:"timeout"`
}

SchedulerConfig holds job scheduler settings.

type SchedulerSecurityConfig added in v0.14.0 

type SchedulerSecurityConfig struct {
	// CIDRAllowlist holds CIDR ranges allowed to access /_sys/job* endpoints.
	// Empty list = localhost-only access (127.0.0.1, ::1).
	// Non-empty list = restrict to matching IP ranges only.
	CIDRAllowlist []string `koanf:"cidrallowlist" json:"cidrallowlist" yaml:"cidrallowlist" toml:"cidrallowlist" mapstructure:"cidrallowlist"`

	// TrustedProxies holds CIDR ranges of trusted reverse proxies.
	// X-Forwarded-For and X-Real-IP headers are ONLY honored if the immediate peer
	// matches one of these CIDR ranges. Empty list = do not trust any proxy headers.
	TrustedProxies []string `koanf:"trustedproxies" json:"trustedproxies" yaml:"trustedproxies" toml:"trustedproxies" mapstructure:"trustedproxies"`
}

SchedulerSecurityConfig holds security settings for scheduler system APIs.

type SchedulerTimeoutConfig added in v0.14.0 

type SchedulerTimeoutConfig struct {
	// Shutdown is the graceful shutdown timeout for in-flight jobs.
	// Default: 30s.
	Shutdown time.Duration `koanf:"shutdown" json:"shutdown" yaml:"shutdown" toml:"shutdown" mapstructure:"shutdown"`

	// SlowJob is the execution duration threshold for marking jobs as slow.
	// Jobs exceeding this duration are logged with result_code="WARN" even if successful.
	// Zero or negative = disabled. Default: 30s.
	SlowJob time.Duration `koanf:"slowjob" json:"slowjob" yaml:"slowjob" toml:"slowjob" mapstructure:"slowjob"`
}

SchedulerTimeoutConfig holds timeout and threshold settings for scheduler operations.

type ServerConfig 

type ServerConfig struct {
	Host    string        `koanf:"host" json:"host" yaml:"host" toml:"host" mapstructure:"host"`
	Port    int           `koanf:"port" json:"port" yaml:"port" toml:"port" mapstructure:"port"`
	Timeout TimeoutConfig `koanf:"timeout" json:"timeout" yaml:"timeout" toml:"timeout" mapstructure:"timeout"`
	Path    PathConfig    `koanf:"path" json:"path" yaml:"path" toml:"path" mapstructure:"path"`
}

ServerConfig holds HTTP server settings.

type ServiceConfig added in v0.7.0 

type ServiceConfig struct {
	Name string `koanf:"name" json:"name" yaml:"name" toml:"name" mapstructure:"name"`
	SID  string `koanf:"sid" json:"sid" yaml:"sid" toml:"sid" mapstructure:"sid"`
}

ServiceConfig holds Oracle service connection settings.

type SlowQueryConfig added in v0.7.1 

type SlowQueryConfig struct {
	Threshold time.Duration `koanf:"threshold" json:"threshold" yaml:"threshold" toml:"threshold" mapstructure:"threshold"`
	Enabled   bool          `koanf:"enabled" json:"enabled" yaml:"enabled" toml:"enabled" mapstructure:"enabled"`
}

SlowQueryConfig holds settings for slow query detection.

type SourceConfig added in v0.11.0 

type SourceConfig struct {
	Type string `koanf:"type" json:"type" yaml:"type" toml:"type" mapstructure:"type"` // SourceTypeStatic for YAML config, SourceTypeDynamic for external stores
}

SourceConfig controls how tenant configuration is loaded.

type StartupConfig added in v0.11.2 

type StartupConfig struct {
	// Timeout is the overall startup timeout (fallback when component-specific not set).
	// Default: 10s.
	Timeout time.Duration `koanf:"timeout" json:"timeout" yaml:"timeout" toml:"timeout" mapstructure:"timeout"`

	// Database is the timeout for database health check during startup.
	// Default: 10s. Set higher for slow network connections.
	Database time.Duration `koanf:"database" json:"database" yaml:"database" toml:"database" mapstructure:"database"`

	// Messaging is the timeout for broker connection during startup.
	// Default: 10s. Set higher for cluster failover scenarios.
	Messaging time.Duration `koanf:"messaging" json:"messaging" yaml:"messaging" toml:"messaging" mapstructure:"messaging"`

	// Cache is the timeout for cache initialization during startup.
	// Default: 5s. Cache is fast to connect; lower timeout prevents blocking.
	Cache time.Duration `koanf:"cache" json:"cache" yaml:"cache" toml:"cache" mapstructure:"cache"`

	// Observability is the timeout for OTLP provider initialization.
	// Default: 15s. Remote OTLP endpoints may need extra time for TLS handshake.
	Observability time.Duration `koanf:"observability" json:"observability" yaml:"observability" toml:"observability" mapstructure:"observability"`
}

StartupConfig holds application startup settings. Production-safe defaults are applied automatically:

  • Timeout: 10s (overall startup timeout, fallback for unset components)
  • Database: 10s (database health check timeout)
  • Messaging: 10s (broker connection timeout)
  • Cache: 5s (cache initialization timeout)
  • Observability: 15s (OTLP provider initialization timeout)

type TLSConfig added in v0.7.1 

type TLSConfig struct {
	Mode     string `koanf:"mode" json:"mode" yaml:"mode" toml:"mode" mapstructure:"mode"`
	CertFile string `koanf:"cert" json:"cert" yaml:"cert" toml:"cert" mapstructure:"cert"`
	KeyFile  string `koanf:"key" json:"key" yaml:"key" toml:"key" mapstructure:"key"`
	CAFile   string `koanf:"ca" json:"ca" yaml:"ca" toml:"ca" mapstructure:"ca"`
}

TLSConfig holds TLS/SSL settings for database connections.

type TenantEntry added in v0.9.0 

type TenantEntry struct {
	Database  DatabaseConfig        `koanf:"database" json:"database" yaml:"database" toml:"database" mapstructure:"database"`
	Messaging TenantMessagingConfig `koanf:"messaging" json:"messaging" yaml:"messaging" toml:"messaging" mapstructure:"messaging"`
	Cache     CacheConfig           `koanf:"cache" json:"cache" yaml:"cache" toml:"cache" mapstructure:"cache"`
}

TenantEntry represents a single tenant's resource configuration

type TenantMessagingConfig added in v0.9.0 

type TenantMessagingConfig struct {
	URL string `koanf:"url" json:"url" yaml:"url" toml:"url" mapstructure:"url"`
}

TenantMessagingConfig holds messaging configuration for a tenant

type TenantStore added in v0.9.0 

type TenantStore struct {
	// contains filtered or unexported fields
}

TenantStore provides per-key database, messaging, and cache configurations. This is the default config-backed implementation that uses the static tenant map.

func NewTenantStore added in v0.9.0 

func NewTenantStore(cfg *Config) *TenantStore

NewTenantStore creates a config-backed tenant store

func (*TenantStore) AddTenant added in v0.9.0 

func (s *TenantStore) AddTenant(tenantID string, entry *TenantEntry)

AddTenant adds a new tenant configuration at runtime (useful for dynamic tenant management)

func (*TenantStore) BrokerURL added in v0.11.1 

func (s *TenantStore) BrokerURL(_ context.Context, key string) (string, error)

BrokerURL returns the AMQP broker URL for the given key. For single-tenant (key=""), returns the default broker URL. For multi-tenant (key=tenantID), returns the tenant-specific URL. Returns an error if messaging is not configured or misconfigured.

func (*TenantStore) CacheConfig added in v0.18.0 

func (s *TenantStore) CacheConfig(_ context.Context, key string) (*CacheConfig, error)

CacheConfig returns the cache configuration for the given key. For single-tenant (key=""), returns the default cache config. For multi-tenant (key=tenantID), returns the tenant-specific cache config.

func (*TenantStore) DBConfig added in v0.9.0 

func (s *TenantStore) DBConfig(_ context.Context, key string) (*DatabaseConfig, error)

DBConfig returns the database configuration for the given key. For single-tenant (key=""), returns the default database config. For multi-tenant (key=tenantID), returns the tenant-specific database config.

func (*TenantStore) HasTenant added in v0.9.0 

func (s *TenantStore) HasTenant(tenantID string) bool

HasTenant checks if a tenant configuration exists

func (*TenantStore) IsDynamic added in v0.11.0 

func (s *TenantStore) IsDynamic() bool

IsDynamic returns false since this store uses static YAML configuration

func (*TenantStore) RemoveTenant added in v0.9.0 

func (s *TenantStore) RemoveTenant(tenantID string)

RemoveTenant removes a tenant configuration at runtime

func (*TenantStore) Tenants added in v0.19.0 

func (s *TenantStore) Tenants() map[string]TenantEntry

Tenants returns a copy of all tenant configurations

type TimeoutConfig added in v0.7.1 

type TimeoutConfig struct {
	Read       time.Duration `koanf:"read" json:"read" yaml:"read" toml:"read" mapstructure:"read"`
	Write      time.Duration `koanf:"write" json:"write" yaml:"write" toml:"write" mapstructure:"write"`
	Idle       time.Duration `koanf:"idle" json:"idle" yaml:"idle" toml:"idle" mapstructure:"idle"`
	Middleware time.Duration `koanf:"middleware" json:"middleware" yaml:"middleware" toml:"middleware" mapstructure:"middleware"`
	Shutdown   time.Duration `koanf:"shutdown" json:"shutdown" yaml:"shutdown" toml:"shutdown" mapstructure:"shutdown"`
}

TimeoutConfig holds various timeout durations for the server.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.