config

package
v1.0.10 Latest Latest
Warning

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

 Go to latest Published: Jan 2, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

ResolveSpec Configuration System

A centralized configuration system with support for multiple configuration sources: config files (YAML, TOML, JSON), environment variables, and programmatic configuration.

Features

  • Multiple Config Sources: Config files, environment variables, and code
  • Priority Order: Environment variables > Config file > Defaults
  • Multiple Formats: YAML, TOML, JSON supported
  • Type Safety: Strongly-typed configuration structs
  • Sensible Defaults: Works out of the box with reasonable defaults

Quick Start

Basic Usage
import "github.com/heinhel/ResolveSpec/pkg/config"

// Create a new config manager
mgr := config.NewManager()

// Load configuration from file and environment
if err := mgr.Load(); err != nil {
    log.Fatal(err)
}

// Get the complete configuration
cfg, err := mgr.GetConfig()
if err != nil {
    log.Fatal(err)
}

// Use the configuration
fmt.Println("Server address:", cfg.Server.Addr)
Custom Configuration Paths
mgr := config.NewManagerWithOptions(
    config.WithConfigFile("/path/to/config.yaml"),
    config.WithEnvPrefix("MYAPP"),
)

Configuration Sources

1. Config Files

Place a config.yaml file in one of these locations:

  • Current directory (.)
  • ./config/
  • /etc/resolvespec/
  • $HOME/.resolvespec/

Example config.yaml:

server:
  addr: ":8080"
  shutdown_timeout: 30s

tracing:
  enabled: true
  service_name: "my-service"

cache:
  provider: "redis"
  redis:
    host: "localhost"
    port: 6379
2. Environment Variables

All configuration can be set via environment variables with the RESOLVESPEC_ prefix:

export RESOLVESPEC_SERVER_ADDR=":9090"
export RESOLVESPEC_TRACING_ENABLED=true
export RESOLVESPEC_CACHE_PROVIDER=redis
export RESOLVESPEC_CACHE_REDIS_HOST=localhost

Nested configuration uses underscores:

  • server.addr → RESOLVESPEC_SERVER_ADDR
  • cache.redis.host → RESOLVESPEC_CACHE_REDIS_HOST
3. Programmatic Configuration
mgr := config.NewManager()
mgr.Set("server.addr", ":9090")
mgr.Set("tracing.enabled", true)

cfg, _ := mgr.GetConfig()

Configuration Options

Server Configuration
server:
  addr: ":8080"              # Server address
  shutdown_timeout: 30s       # Graceful shutdown timeout
  drain_timeout: 25s          # Connection drain timeout
  read_timeout: 10s           # HTTP read timeout
  write_timeout: 10s          # HTTP write timeout
  idle_timeout: 120s          # HTTP idle timeout
Tracing Configuration
tracing:
  enabled: false                                  # Enable/disable tracing
  service_name: "resolvespec"                     # Service name
  service_version: "1.0.0"                        # Service version
  endpoint: "http://localhost:4318/v1/traces"     # OTLP endpoint
Cache Configuration
cache:
  provider: "memory"  # Options: memory, redis, memcache

  redis:
    host: "localhost"
    port: 6379
    password: ""
    db: 0

  memcache:
    servers:
      - "localhost:11211"
    max_idle_conns: 10
    timeout: 100ms
Logger Configuration
logger:
  dev: false    # Development mode (human-readable output)
  path: ""      # Log file path (empty = stdout)
Middleware Configuration
middleware:
  rate_limit_rps: 100.0       # Requests per second
  rate_limit_burst: 200        # Burst size
  max_request_size: 10485760   # Max request size in bytes (10MB)
CORS Configuration
cors:
  allowed_origins:
    - "*"
  allowed_methods:
    - "GET"
    - "POST"
    - "PUT"
    - "DELETE"
    - "OPTIONS"
  allowed_headers:
    - "*"
  max_age: 3600
Database Configuration
database:
  url: "host=localhost user=postgres password=postgres dbname=mydb port=5432 sslmode=disable"

Priority and Overrides

Configuration sources are applied in this order (highest priority first):

  1. Environment Variables (highest priority)
  2. Config File
  3. Defaults (lowest priority)

This allows you to:

  • Set defaults in code
  • Override with a config file
  • Override specific values with environment variables

Examples

Production Setup
# config.yaml
server:
  addr: ":8080"

tracing:
  enabled: true
  service_name: "myapi"
  endpoint: "http://jaeger:4318/v1/traces"

cache:
  provider: "redis"
  redis:
    host: "redis"
    port: 6379
    password: "${REDIS_PASSWORD}"

logger:
  dev: false
  path: "/var/log/myapi/app.log"
Development Setup
# Use environment variables for development
export RESOLVESPEC_LOGGER_DEV=true
export RESOLVESPEC_TRACING_ENABLED=false
export RESOLVESPEC_CACHE_PROVIDER=memory
Testing Setup
// Override config for tests
mgr := config.NewManager()
mgr.Set("cache.provider", "memory")
mgr.Set("database.url", testDBURL)

cfg, _ := mgr.GetConfig()

Best Practices

  1. Use config files for base configuration - Define your standard settings
  2. Use environment variables for secrets - Never commit passwords/tokens
  3. Use environment variables for deployment-specific values - Different per environment
  4. Keep defaults sensible - Application should work with minimal configuration
  5. Document your configuration - Comment your config.yaml files

Integration with ResolveSpec Components

The configuration system integrates seamlessly with ResolveSpec components:

cfg, _ := config.NewManager().Load().GetConfig()

// Server
srv := server.NewGracefulServer(server.Config{
    Addr:            cfg.Server.Addr,
    ShutdownTimeout: cfg.Server.ShutdownTimeout,
    // ... other fields
})

// Tracing
if cfg.Tracing.Enabled {
    tracer := tracing.Init(tracing.Config{
        ServiceName:    cfg.Tracing.ServiceName,
        ServiceVersion: cfg.Tracing.ServiceVersion,
        Endpoint:       cfg.Tracing.Endpoint,
    })
    defer tracer.Shutdown(context.Background())
}

// Cache
var cacheProvider cache.Provider
switch cfg.Cache.Provider {
case "redis":
    cacheProvider = cache.NewRedisProvider(cfg.Cache.Redis.Host, cfg.Cache.Redis.Port, ...)
case "memcache":
    cacheProvider = cache.NewMemcacheProvider(cfg.Cache.Memcache.Servers, ...)
default:
    cacheProvider = cache.NewMemoryProvider()
}

// Logger
logger.Init(cfg.Logger.Dev)
if cfg.Logger.Path != "" {
    logger.UpdateLoggerPath(cfg.Logger.Path, cfg.Logger.Dev)
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CORSConfig 

type CORSConfig struct {
	AllowedOrigins []string `mapstructure:"allowed_origins"`
	AllowedMethods []string `mapstructure:"allowed_methods"`
	AllowedHeaders []string `mapstructure:"allowed_headers"`
	MaxAge         int      `mapstructure:"max_age"`
}

CORSConfig holds CORS configuration

type CacheConfig 

type CacheConfig struct {
	Provider string         `mapstructure:"provider"` // memory, redis, memcache
	Redis    RedisConfig    `mapstructure:"redis"`
	Memcache MemcacheConfig `mapstructure:"memcache"`
}

CacheConfig holds cache provider configuration

type Config 

type Config struct {
	Server        ServerConfig        `mapstructure:"server"`
	Tracing       TracingConfig       `mapstructure:"tracing"`
	Cache         CacheConfig         `mapstructure:"cache"`
	Logger        LoggerConfig        `mapstructure:"logger"`
	ErrorTracking ErrorTrackingConfig `mapstructure:"error_tracking"`
	Middleware    MiddlewareConfig    `mapstructure:"middleware"`
	CORS          CORSConfig          `mapstructure:"cors"`
	EventBroker   EventBrokerConfig   `mapstructure:"event_broker"`
	DBManager     DBManagerConfig     `mapstructure:"dbmanager"`
}

Config represents the complete application configuration

type DBConnectionConfig added in v1.0.6 

type DBConnectionConfig struct {
	// Name is the unique name of this connection
	Name string `mapstructure:"name"`

	// Type is the database type (postgres, sqlite, mssql, mongodb)
	Type string `mapstructure:"type"`

	// DSN is the complete Data Source Name / connection string
	// If provided, this takes precedence over individual connection parameters
	DSN string `mapstructure:"dsn"`

	// Connection parameters (used if DSN is not provided)
	Host     string `mapstructure:"host"`
	Port     int    `mapstructure:"port"`
	User     string `mapstructure:"user"`
	Password string `mapstructure:"password"`
	Database string `mapstructure:"database"`

	// PostgreSQL/MSSQL specific
	SSLMode string `mapstructure:"sslmode"` // disable, require, verify-ca, verify-full
	Schema  string `mapstructure:"schema"`  // Default schema

	// SQLite specific
	FilePath string `mapstructure:"filepath"`

	// MongoDB specific
	AuthSource     string `mapstructure:"auth_source"`
	ReplicaSet     string `mapstructure:"replica_set"`
	ReadPreference string `mapstructure:"read_preference"` // primary, secondary, etc.

	// Connection pool settings (overrides global defaults)
	MaxOpenConns    *int           `mapstructure:"max_open_conns"`
	MaxIdleConns    *int           `mapstructure:"max_idle_conns"`
	ConnMaxLifetime *time.Duration `mapstructure:"conn_max_lifetime"`
	ConnMaxIdleTime *time.Duration `mapstructure:"conn_max_idle_time"`

	// Timeouts
	ConnectTimeout time.Duration `mapstructure:"connect_timeout"`
	QueryTimeout   time.Duration `mapstructure:"query_timeout"`

	// Features
	EnableTracing bool `mapstructure:"enable_tracing"`
	EnableMetrics bool `mapstructure:"enable_metrics"`
	EnableLogging bool `mapstructure:"enable_logging"`

	// DefaultORM specifies which ORM to use for the Database() method
	// Options: "bun", "gorm", "native"
	DefaultORM string `mapstructure:"default_orm"`

	// Tags for organization and filtering
	Tags map[string]string `mapstructure:"tags"`
}

DBConnectionConfig defines configuration for a single database connection

func (*DBConnectionConfig) PopulateFromDSN added in v1.0.10 

func (cc *DBConnectionConfig) PopulateFromDSN() error

PopulateFromDSN parses a DSN and populates the connection fields

type DBManagerConfig added in v1.0.6 

type DBManagerConfig struct {
	// DefaultConnection is the name of the default connection to use
	DefaultConnection string `mapstructure:"default_connection"`

	// Connections is a map of connection name to connection configuration
	Connections map[string]DBConnectionConfig `mapstructure:"connections"`

	// Global connection pool defaults
	MaxOpenConns    int           `mapstructure:"max_open_conns"`
	MaxIdleConns    int           `mapstructure:"max_idle_conns"`
	ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime"`
	ConnMaxIdleTime time.Duration `mapstructure:"conn_max_idle_time"`

	// Retry policy
	RetryAttempts int           `mapstructure:"retry_attempts"`
	RetryDelay    time.Duration `mapstructure:"retry_delay"`
	RetryMaxDelay time.Duration `mapstructure:"retry_max_delay"`

	// Health checks
	HealthCheckInterval time.Duration `mapstructure:"health_check_interval"`
	EnableAutoReconnect bool          `mapstructure:"enable_auto_reconnect"`
}

DBManagerConfig contains configuration for the database connection manager

func (*DBManagerConfig) ToManagerConfig added in v1.0.6 

func (c *DBManagerConfig) ToManagerConfig() interface{}

ToManagerConfig converts config.DBManagerConfig to dbmanager.ManagerConfig This is used to avoid circular dependencies

func (*DBManagerConfig) Validate added in v1.0.6 

func (c *DBManagerConfig) Validate() error

Validate validates the DBManager configuration

type ErrorTrackingConfig added in v0.0.98 

type ErrorTrackingConfig struct {
	Enabled          bool    `mapstructure:"enabled"`
	Provider         string  `mapstructure:"provider"`           // sentry, noop
	DSN              string  `mapstructure:"dsn"`                // Sentry DSN
	Environment      string  `mapstructure:"environment"`        // e.g., production, staging, development
	Release          string  `mapstructure:"release"`            // Application version/release
	Debug            bool    `mapstructure:"debug"`              // Enable debug mode
	SampleRate       float64 `mapstructure:"sample_rate"`        // Error sample rate (0.0-1.0)
	TracesSampleRate float64 `mapstructure:"traces_sample_rate"` // Traces sample rate (0.0-1.0)
}

ErrorTrackingConfig holds error tracking configuration

type EventBrokerConfig added in v0.0.107 

type EventBrokerConfig struct {
	Enabled     bool                         `mapstructure:"enabled"`
	Provider    string                       `mapstructure:"provider"` // memory, redis, nats, database
	Mode        string                       `mapstructure:"mode"`     // sync, async
	WorkerCount int                          `mapstructure:"worker_count"`
	BufferSize  int                          `mapstructure:"buffer_size"`
	InstanceID  string                       `mapstructure:"instance_id"`
	Redis       EventBrokerRedisConfig       `mapstructure:"redis"`
	NATS        EventBrokerNATSConfig        `mapstructure:"nats"`
	Database    EventBrokerDatabaseConfig    `mapstructure:"database"`
	RetryPolicy EventBrokerRetryPolicyConfig `mapstructure:"retry_policy"`
}

EventBrokerConfig contains configuration for the event broker

type EventBrokerDatabaseConfig added in v0.0.107 

type EventBrokerDatabaseConfig struct {
	TableName    string        `mapstructure:"table_name"`
	Channel      string        `mapstructure:"channel"` // PostgreSQL NOTIFY channel name
	PollInterval time.Duration `mapstructure:"poll_interval"`
}

EventBrokerDatabaseConfig contains database provider configuration

type EventBrokerNATSConfig added in v0.0.107 

type EventBrokerNATSConfig struct {
	URL        string        `mapstructure:"url"`
	StreamName string        `mapstructure:"stream_name"`
	Subjects   []string      `mapstructure:"subjects"`
	Storage    string        `mapstructure:"storage"` // file, memory
	MaxAge     time.Duration `mapstructure:"max_age"`
}

EventBrokerNATSConfig contains NATS-specific configuration

type EventBrokerRedisConfig added in v0.0.107 

type EventBrokerRedisConfig struct {
	StreamName    string `mapstructure:"stream_name"`
	ConsumerGroup string `mapstructure:"consumer_group"`
	MaxLen        int64  `mapstructure:"max_len"`
	Host          string `mapstructure:"host"`
	Port          int    `mapstructure:"port"`
	Password      string `mapstructure:"password"`
	DB            int    `mapstructure:"db"`
}

EventBrokerRedisConfig contains Redis-specific configuration

type EventBrokerRetryPolicyConfig added in v0.0.107 

type EventBrokerRetryPolicyConfig struct {
	MaxRetries    int           `mapstructure:"max_retries"`
	InitialDelay  time.Duration `mapstructure:"initial_delay"`
	MaxDelay      time.Duration `mapstructure:"max_delay"`
	BackoffFactor float64       `mapstructure:"backoff_factor"`
}

EventBrokerRetryPolicyConfig contains retry policy configuration

type LoggerConfig 

type LoggerConfig struct {
	Dev  bool   `mapstructure:"dev"`
	Path string `mapstructure:"path"`
}

LoggerConfig holds logger configuration

type Manager 

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

Manager handles configuration loading from multiple sources

func NewManager 

func NewManager() *Manager

NewManager creates a new configuration manager with defaults

func NewManagerWithOptions 

func NewManagerWithOptions(opts ...Option) *Manager

NewManagerWithOptions creates a new configuration manager with custom options

func (*Manager) Get 

func (m *Manager) Get(key string) interface{}

Get returns a configuration value by key

func (*Manager) GetBool 

func (m *Manager) GetBool(key string) bool

GetBool returns a bool configuration value

func (*Manager) GetConfig 

func (m *Manager) GetConfig() (*Config, error)

GetConfig returns the complete configuration

func (*Manager) GetInt 

func (m *Manager) GetInt(key string) int

GetInt returns an int configuration value

func (*Manager) GetString 

func (m *Manager) GetString(key string) string

GetString returns a string configuration value

func (*Manager) Load 

func (m *Manager) Load() error

Load attempts to load configuration from file and environment

func (*Manager) SaveConfig added in v1.0.8 

func (m *Manager) SaveConfig(path string) error

SaveConfig writes the current configuration to the specified path

func (*Manager) Set 

func (m *Manager) Set(key string, value interface{})

Set sets a configuration value

func (*Manager) SetConfig added in v1.0.10 

func (m *Manager) SetConfig(cfg *Config) error

SetConfig sets the complete configuration

type MemcacheConfig 

type MemcacheConfig struct {
	Servers      []string      `mapstructure:"servers"`
	MaxIdleConns int           `mapstructure:"max_idle_conns"`
	Timeout      time.Duration `mapstructure:"timeout"`
}

MemcacheConfig holds Memcache-specific configuration

type MiddlewareConfig 

type MiddlewareConfig struct {
	RateLimitRPS   float64 `mapstructure:"rate_limit_rps"`
	RateLimitBurst int     `mapstructure:"rate_limit_burst"`
	MaxRequestSize int64   `mapstructure:"max_request_size"`
}

MiddlewareConfig holds middleware configuration

type Option 

type Option func(*Manager)

Option is a functional option for configuring the Manager

func WithConfigFile 

func WithConfigFile(path string) Option

WithConfigFile sets a specific config file path

func WithConfigName 

func WithConfigName(name string) Option

WithConfigName sets the config file name (without extension)

func WithConfigPath 

func WithConfigPath(path string) Option

WithConfigPath adds a path to search for config files

func WithEnvPrefix 

func WithEnvPrefix(prefix string) Option

WithEnvPrefix sets the environment variable prefix

type RedisConfig 

type RedisConfig struct {
	Host     string `mapstructure:"host"`
	Port     int    `mapstructure:"port"`
	Password string `mapstructure:"password"`
	DB       int    `mapstructure:"db"`
}

RedisConfig holds Redis-specific configuration

type ServerConfig 

type ServerConfig struct {
	Addr            string        `mapstructure:"addr"`
	ShutdownTimeout time.Duration `mapstructure:"shutdown_timeout"`
	DrainTimeout    time.Duration `mapstructure:"drain_timeout"`
	ReadTimeout     time.Duration `mapstructure:"read_timeout"`
	WriteTimeout    time.Duration `mapstructure:"write_timeout"`
	IdleTimeout     time.Duration `mapstructure:"idle_timeout"`
}

ServerConfig holds server-related configuration

type TracingConfig 

type TracingConfig struct {
	Enabled        bool   `mapstructure:"enabled"`
	ServiceName    string `mapstructure:"service_name"`
	ServiceVersion string `mapstructure:"service_version"`
	Endpoint       string `mapstructure:"endpoint"`
}

TracingConfig holds OpenTelemetry tracing configuration

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.