configuration

configuration

A small Go package for loading and saving application configuration as YAML using the XDG Base Directory specification.

Configuration is stored per executable under:

$XDG_CONFIG_HOME//config

The package provides transparent in-memory caching, and enforces strict type consistency across reads.

Features

• YAML-based configuration files using go.yaml.in/yaml/v4 lib
• XDG-compliant configuration directory resolution
• Generic API (Get[T], Save[T])
• Automatic in-memory caching
• Strict type safety across calls
• Secure file permissions (0600)

Installation

go get github.com/devilcove/configuration

Usage

Define a Configuration Struct

type Config struct {
    Host string `yaml:"host"`
    Port int    `yaml:"port"`
}

Load Configuration

// default file - config
var cfg Config
if err := configuration.Get(&cfg); err != nil {
    log.Fatal(err)
}

// use alternate filename
var cfg Config
if err := configuration.Get(&cfg, "alternate"); err != nil {
    log.Fatal(err)
}

• On first call, the configuration is read from disk and cached.
• Subsequent calls return the cached value.
• The supplied type must match the type used on the first call.

Save Configuration

cfg := Config{
    Host: "localhost",
    Port: 8080,
}

// default filename
if err := configuration.Save(&cfg); err != nil {
    log.Fatal(err)
}
// alternate filename
if err := configuration.Save(&cfg, "alternate"); err != nil {
    log.Fatal(err)
}

• The configuration is serialized to YAML.
• The file is written with permissions 0600.
• The saved configuration replaces the in-memory cache.

Configuration File Location

The configuration file is always stored in:

$XDG_CONFIG_HOME/<executable-name>/

Where:

• XDG_CONFIG_HOME is resolved using os.UserConfigDir()
• <executable-name> is derived from os.Args[0]

the default filename is config; an alternate filename can be passed as additional argument to Get or Save functions

Examples:

Caching Behavior

• Configuration is loaded once per process.
• All subsequent Get calls return the cached value.
• Mixing different configuration types in the same process is not allowed.

Example of invalid usage:

var a ConfigA
var b ConfigB

configuration.Get(&a)
configuration.Get(&b) // returns ErrInterfaceConversion

Error Handling

The package exposes the following sentinel errors:

Errors are returned when:

• No configuration directory can be resolved
• The config file cannot be read or written
• The YAML cannot be unmarshaled into the target type

Licence

MIT Licence. See LICENCE for details.