Documentation
¶
Overview ¶
Package config provides configuration management for Forge microservices.
The config package implements environment-based configuration with comprehensive validation, sensible defaults, and support for multiple deployment environments.
Basic Usage ¶
Embed BaseConfig in your service-specific configuration:
type MyServiceConfig struct {
config.BaseConfig `yaml:",inline"`
// Service-specific fields
DatabaseURL string `yaml:"database_url" env:"DATABASE_URL"`
APIKey string `yaml:"api_key" env:"API_KEY"`
}
func LoadConfig() (*MyServiceConfig, error) {
cfg := &MyServiceConfig{
BaseConfig: config.DefaultBaseConfig(),
}
// Load from environment, config files, etc.
// Then validate
if err := cfg.Validate(); err != nil {
return nil, err
}
return cfg, nil
}
Environment Variables ¶
All configuration fields can be set via environment variables. The package supports automatic environment variable binding with struct tags.
Validation ¶
The package provides comprehensive validation including:
- Required field validation
- URL format validation
- Address format validation
- Timeout and duration validation
- Environment-specific validation
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BaseConfig ¶
type BaseConfig struct {
// ServiceName is the name of the service (e.g., "user-service", "auth-service")
ServiceName string `yaml:"service_name" env:"SERVICE_NAME"`
// AppEnv indicates the deployment environment (development, staging, production)
AppEnv string `yaml:"app_env" env:"APP_ENV"`
// GRPCAddr is the address to bind the gRPC server (e.g., ":8080")
GRPCAddr string `yaml:"grpc_addr" env:"GRPC_ADDR"`
// HTTPAddr is the address to bind the HTTP health/metrics server (e.g., ":8081")
HTTPAddr string `yaml:"http_addr" env:"HTTP_ADDR"`
// LogLevel controls the logging level (debug, info, warn, error)
LogLevel string `yaml:"log_level" env:"LOG_LEVEL"`
// ShutdownTimeout is the maximum time to wait for graceful shutdown
ShutdownTimeout time.Duration `yaml:"shutdown_timeout" env:"SHUTDOWN_TIMEOUT"`
// ReadinessInitialDelay is the time to wait before marking the service as ready
ReadinessInitialDelay time.Duration `yaml:"readiness_initial_delay" env:"READINESS_INITIAL_DELAY"`
// Optional dependency URLs - only required if service uses them
DatabaseURL string `yaml:"database_url" env:"DATABASE_URL"`
RedisURL string `yaml:"redis_url" env:"REDIS_URL"`
// OpenTelemetry configuration
OTELEndpoint string `yaml:"otel_endpoint" env:"OTEL_EXPORTER_OTLP_ENDPOINT"`
OTELSampleRate float64 `yaml:"otel_sample_rate" env:"OTEL_SAMPLE_RATE"`
// gRPC server configuration
GRPCMaxRecvMsgSize int `yaml:"grpc_max_recv_msg_size" env:"GRPC_MAX_RECV_MSG_SIZE"`
GRPCMaxSendMsgSize int `yaml:"grpc_max_send_msg_size" env:"GRPC_MAX_SEND_MSG_SIZE"`
GRPCTimeout time.Duration `yaml:"grpc_timeout" env:"GRPC_TIMEOUT"`
// HTTP server configuration
HTTPReadTimeout time.Duration `yaml:"http_read_timeout" env:"HTTP_READ_TIMEOUT"`
HTTPWriteTimeout time.Duration `yaml:"http_write_timeout" env:"HTTP_WRITE_TIMEOUT"`
HTTPIdleTimeout time.Duration `yaml:"http_idle_timeout" env:"HTTP_IDLE_TIMEOUT"`
// Optional features
EnablePprof bool `yaml:"enable_pprof" env:"ENABLE_PPROF"`
EnableReflection bool `yaml:"enable_reflection" env:"ENABLE_REFLECTION"`
// HTTP server enhancements
EnableCORS bool `yaml:"enable_cors" env:"ENABLE_CORS"`
CORSOrigins []string `yaml:"cors_origins" env:"CORS_ORIGINS"`
EnableMetrics bool `yaml:"enable_metrics" env:"ENABLE_METRICS"`
EnableRequestLogging bool `yaml:"enable_request_logging" env:"ENABLE_REQUEST_LOGGING"`
}
BaseConfig contains configuration common to all services using the Forge framework. This should be embedded in service-specific configuration structs to inherit standard microservice configuration fields.
BaseConfig provides:
- Service identification (name, environment, version)
- Server configuration (gRPC and HTTP addresses, timeouts)
- Logging configuration (level, format)
- Observability configuration (OpenTelemetry endpoints, sampling)
- Infrastructure URLs (database, Redis, etc.)
- Lifecycle configuration (shutdown timeouts, readiness delays)
All fields support environment variable override using the env struct tag.
Example environment variables:
SERVICE_NAME=user-service APP_ENV=production GRPC_ADDR=:8080 HTTP_ADDR=:8081 LOG_LEVEL=info DATABASE_URL=postgres://localhost:5432/mydb
func DefaultBaseConfig ¶
func DefaultBaseConfig() BaseConfig
DefaultBaseConfig returns a BaseConfig with sensible defaults. Use this as a starting point for your service configuration, then override specific fields as needed.
Default values include:
- ServiceName: "forge-service"
- AppEnv: "development"
- GRPCAddr: ":8080"
- HTTPAddr: ":8081"
- LogLevel: "info"
- ShutdownTimeout: 30 seconds
- OpenTelemetry sample rate: 1.0 (100%)
Example usage:
cfg := config.DefaultBaseConfig() cfg.ServiceName = "my-service" cfg.AppEnv = "production"
func (*BaseConfig) IsDevelopment ¶
func (c *BaseConfig) IsDevelopment() bool
IsDevelopment returns true if the service is running in development mode.
func (*BaseConfig) IsProduction ¶
func (c *BaseConfig) IsProduction() bool
IsProduction returns true if the service is running in production mode.
func (*BaseConfig) ShouldEnableReflection ¶
func (c *BaseConfig) ShouldEnableReflection() bool
ShouldEnableReflection returns true if gRPC reflection should be enabled. Reflection exposes the full service schema and must be explicitly opted into via EnableReflection (env ENABLE_REFLECTION) — it is never enabled implicitly by environment, including in development.
func (*BaseConfig) Validate ¶
func (c *BaseConfig) Validate() error
Validate performs comprehensive validation on all BaseConfig fields. Returns an error if any validation fails, with a descriptive message indicating what needs to be corrected.
Validation includes:
- Required fields (service name, environment, addresses)
- Valid log levels (debug, info, warn, error)
- Valid environments (development, staging, production)
- Positive timeouts and durations
- Valid URL formats for endpoints and infrastructure URLs
- Proper address formats (must contain port)
- OpenTelemetry sample rate between 0 and 1
Call this method after loading configuration from environment or files to ensure all values are valid before starting the application.
Source Files