Config Package

Package Information

• Import Path: rivaas.dev/config
• Go Version: 1.25+
• Documentation: pkg.go.dev/rivaas.dev/config
• Source Code: GitHub

Package Overview

The config package loads settings from files, environment variables, and Consul, merges them in order, and supports validation and struct binding.

Core Features

• Multiple configuration sources (files, environment variables, remote sources)
• Format-agnostic with built-in JSON, YAML, and TOML support
• Hierarchical configuration merging
• Automatic struct binding with type safety
• Multiple validation strategies
• Thread-safe operations
• Nil-safe typed getters (String, Int, Get, and similar); do not call Values() on a nil *Config

Architecture

The package is organized into several key components:

Main Package (rivaas.dev/config)

Core configuration management including:

• Config struct - Main configuration container
• New() / MustNew() - Configuration initialization
• Getter methods - Type-safe value retrieval
• Load() / Dump() - Loading and saving configuration

Sub-packages

• codec - Format encoding/decoding (JSON, YAML, TOML, etc.)
• source - Configuration sources (file, environment, Consul, etc.)
• dumper - Configuration output destinations

Quick API Index

Configuration Creation

cfg, err := config.New(opts...)     // With error handling
cfg := config.MustNew(opts...)      // Panics on error

Options must not be nil; passing a nil option results in a validation error (reported by New, panic by MustNew). This rule applies to all Rivaas packages that use functional options.

Loading Configuration

err := cfg.Load(ctx context.Context)

Accessing Values

// Direct access (returns zero values for missing keys)
value := cfg.String("key")
value := cfg.Int("key")
value := cfg.Bool("key")

// With defaults
value := cfg.StringOr("key", "default")
value := cfg.IntOr("key", 8080)

// With error handling
value, err := config.GetE[Type](cfg, "key")

Dumping Configuration

err := cfg.Dump(ctx context.Context)

Reference Pages

API Reference

Complete documentation of the Config struct and all methods including:

• Configuration lifecycle methods
• All getter method signatures
• Error types and handling
• Nil-safety guarantees

Options

All option functions for New and MustNew:

• Source options (WithFile, WithEnv, WithConsul, WithConsulOptional, etc.)
• Validation options (WithBinding, WithValidator, WithJSONSchema)
• Dumper options (WithFileDumper, WithDumper)

Codecs

Built-in and custom codec documentation:

• Format codecs (JSON, YAML, TOML, EnvVar)
• Caster codecs (Int, Bool, Duration, Time, etc.)
• Creating custom codecs
• File extension auto-detection

Troubleshooting

Common issues and solutions:

• Configuration not loading
• Struct not populating
• Environment variable mapping
• Performance considerations
• Thread-safety information

Type Reference

Config

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

Main configuration container. Thread-safe for concurrent access.

Error

type Error struct {
    Source    string // Where the error occurred
    Field     string // Specific field with error (optional)
    Operation string // Operation being performed
    Err       error  // Underlying error
}

Configuration errors use the exported type config.Error (some comments refer to this shape as “config error”). Use errors.As with *config.Error to inspect Source, Operation, and Err.

Option

Option is a functional option for New / MustNew. It applies to an internal builder type, not *Config directly—pass only values returned from WithFile, WithEnv, and other With… functions. Validation errors from options are collected when the config is built.

Common Patterns

Basic Usage

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithEnv("APP_"),
)
cfg.Load(context.Background())

port := cfg.Int("server.port")

With Struct Binding

type AppConfig struct {
    Server struct {
        Port int `config:"port"`
    } `config:"server"`
}

var appConfig AppConfig
cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithBinding(&appConfig),
)
cfg.Load(context.Background())

With Validation

func (c *AppConfig) Validate() error {
    if c.Server.Port <= 0 {
        return errors.New("port must be positive")
    }
    return nil
}

cfg := config.MustNew(
    config.WithFile("config.yaml"),
    config.WithBinding(&appConfig),  // Validation runs after binding
)

Thread Safety

The Config type is thread-safe for:

• Concurrent Load() operations
• Concurrent getter operations
• Mixed Load() and getter operations

Not thread-safe for:

• Concurrent modification of the same configuration instance during initialization

Performance Notes

• Getter methods are O(1) for simple keys, O(n) for nested dot notation paths
• Load performance depends on source count and data size
• Struct binding uses reflection, minimal overhead for most applications
• Validation overhead depends on validation complexity

Version Compatibility

The config package follows semantic versioning. The API is stable for the v1 series.

Minimum Go version: 1.25

Next Steps

• Read the API Reference for detailed method documentation
• Explore Options for all available configuration options
• Check Codecs for format support details
• Review Troubleshooting for common issues

For learning-focused guides, see the Configuration Guide.