go-config

A flexible Go library for building and composing configuration for web applications. The library provides a clean, structured approach to handle environment-based configuration with validation support.

Features

• Environment-based configuration: Supports multiple .env files with priority ordering
• Composite configuration: Automatically populate and validate nested configuration structs
• Validation support: Built-in validation using go-playground/validator
• Flexible structure: Implement the Config interface for custom configuration logic
• Zero dependencies: Minimal external dependencies for core functionality

Installation

Add the library to your Go project:

go get github.com/golibry/go-config

Quick Start

1. Define your configuration structs

package main

import (
    "os"
    "github.com/golibry/go-config/config"
)

// DatabaseConfig implements the Config interface
type DatabaseConfig struct {
    Host     string `validate:"required"`
    Port     int    `validate:"min=1,max=65535"`
    Username string `validate:"required"`
    Password string `validate:"required"`
}

func (d *DatabaseConfig) Populate() error {
    d.Host = os.Getenv("DB_HOST")
    d.Username = os.Getenv("DB_USERNAME")
    d.Password = os.Getenv("DB_PASSWORD")
    // Add your custom population logic here
    return nil
}

// AppConfig is your main composite configuration
type AppConfig struct {
    Database DatabaseConfig `validate:"required"`
    AppName  string         `validate:"required"`
    Debug    bool
}

func (a *AppConfig) Populate() error {
    a.AppName = os.Getenv("APP_NAME")
    a.Debug = os.Getenv("DEBUG") == "true"
    return nil
}

2. Load and validate configuration

func main() {
    // Create composite config instance
    compositeConfig := config.NewCompositeConfig()
    
    // Create your application config
    appConfig := &AppConfig{}
    
    // Populate top-level config
    err := appConfig.Populate()
    if err != nil {
        log.Fatalf("Failed to populate app config: %v", err)
    }
    
    // Populate nested configs and validate
    err = compositeConfig.PopulateAndValidate(appConfig, "dev", ".")
    if err != nil {
        log.Fatalf("Configuration error: %v", err)
    }
    
    // Your configuration is now ready to use
    fmt.Printf("App: %s, DB Host: %s\n", appConfig.AppName, appConfig.Database.Host)
}

Environment File Priority

The library loads environment files in the following order (first found takes priority):

1. .env.{env}.local (e.g., .env.dev.local)
2. .env.local (not loaded in test environment)
3. .env.{env} (e.g., .env.dev)
4. .env

Configuration Interface

Implement the Config interface for any struct that needs custom population logic:

type Config interface {
    Populate() error
}

Validation

The library uses go-playground/validator for struct validation. Add validation tags to your struct fields:

type ServerConfig struct {
    Host string `validate:"required"`
    Port int    `validate:"min=1,max=65535"`
}

Debugging Configuration

The library provides a Debug function to help troubleshoot configuration issues by converting your config structs into readable debug strings. Sensitive fields (like passwords, API keys) are automatically masked for security.

Debug Function

// Debug transforms a config struct recursively into a string for debugging.
// Sensitive attributes (matching keywords in sensitiveKeys) are masked with "***".
debugOutput := config.Debug(yourConfig, []string{"pass", "secret", "key", "dsn"})
fmt.Print(debugOutput)

Example Usage

type AppConfig struct {
    Host     string
    Port     int
    Password string
    APIKey   string
}

config := AppConfig{
    Host:     "localhost",
    Port:     8080,
    Password: "secret123",
    APIKey:   "api_key_abc",
}

// Sensitive fields will be masked automatically
sensitiveKeys := []string{"pass", "key", "secret"}
debugOutput := config.Debug(config, sensitiveKeys)
fmt.Print(debugOutput)

Examples

For complete working examples, see the _examples directory:

• Configuration Loading: Demonstrates composite configuration with database, Redis, and server configs
• Debug Configuration: Shows how to debug configuration as a string with sensitive field masking

Run the examples:

cd _examples
go run config_load.go
go run debug.go

Requirements

• Go 1.21 or later

Dependencies

• github.com/go-playground/validator/v10 - Struct validation
• github.com/joho/godotenv - Environment file loading

License

This project is licensed under the terms specified in the LICENSE file.