fig

README

fig

Struct tags in, configuration out.

fig loads configuration from environment variables, secret providers, and defaults using Go struct tags. One function call, predictable resolution order.

Install

go get github.com/zoobz-io/fig

Requires Go 1.24+.

Quick Start

package main

import (
    "log"

    "github.com/zoobz-io/fig"
)

type Config struct {
    Host     string   `env:"APP_HOST" default:"localhost"`
    Port     int      `env:"APP_PORT" default:"8080"`
    Password string   `secret:"db/password"`
    Tags     []string `env:"APP_TAGS"`
    APIKey   string   `env:"API_KEY" required:"true"`
}

func main() {
    var cfg Config
    if err := fig.Load(&cfg); err != nil {
        log.Fatal(err)
    }
    // cfg is now populated
}

Resolution order: secret → env → default → zero value.

Capabilities

Feature	Description
Environment variables	env:"VAR_NAME" tag
Secret providers	secret:"path/to/secret" tag with pluggable backends
Default values	default:"value" tag
Required fields	required:"true" tag
Nested structs	Automatic recursion into embedded structs
Validation	Implement Validator interface for custom checks
Context support	LoadContext for secret provider timeouts

Supported Types

string, int, int8-64, uint, uint8-64, float32, float64, bool, time.Duration, []string (comma-separated), and any type implementing encoding.TextUnmarshaler.

Secret Providers

Pass a provider implementing SecretProvider to load secrets:

type SecretProvider interface {
    Get(ctx context.Context, key string) (string, error)
}

Available Providers

Each provider is a separate module — import only what you need:

# AWS Secrets Manager
go get github.com/zoobz-io/fig/awssm

# GCP Secret Manager
go get github.com/zoobz-io/fig/gcpsm

# HashiCorp Vault
go get github.com/zoobz-io/fig/vault

import "github.com/zoobz-io/fig/vault"

p, err := vault.New()
if err != nil {
    log.Fatal(err)
}
fig.Load(&cfg, p)

Secrets take precedence over environment variables, allowing secure overrides.

Validation

Implement the Validator interface for custom validation after loading:

func (c *Config) Validate() error {
    if c.Port <= 0 || c.Port > 65535 {
        return errors.New("port must be between 1 and 65535")
    }
    return nil
}

Why fig?

No config files. No YAML. No JSON. No builder chains. One function, one resolution order, done.

Contributing

See CONTRIBUTING.md.

License

MIT

Documentation

Overview

Package fig provides configuration loading from environment variables and secret providers.

fig uses struct tags to declare configuration sources:

type Config struct {
    Host     string        `env:"DB_HOST" default:"localhost"`
    Port     int           `env:"DB_PORT" default:"5432"`
    Password string        `secret:"db/password"`
    Timeout  time.Duration `env:"TIMEOUT" default:"30s"`
    Debug    bool          `env:"DEBUG"`
    Tags     []string      `env:"TAGS"`
    Name     string        `env:"NAME" required:"true"`
}

Resolution order: secret -> env -> default -> zero value.

Supported Types

• string
• int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• float32, float64
• bool
• time.Duration
• []string (comma-separated)
• any type implementing encoding.TextUnmarshaler

Secret Providers

Pass a secret provider when loading:

fig.Load(&cfg, vault.New(...))

Validation

If the config struct implements Validator, Validate() is called after loading:

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

Index

• Variables
• func Load[T any](cfg *T, provider ...SecretProvider) error
• func LoadContext[T any](ctx context.Context, cfg *T, provider ...SecretProvider) error
• type FieldError
  • func (e *FieldError) Error() string
  • func (e *FieldError) Unwrap() error
• type SecretProvider
• type Validator

Variables

var (
	// ErrRequired indicates a required field was not set.
	ErrRequired = errors.New("fig: required field not set")

	// ErrInvalidType indicates a value could not be converted to the target type.
	ErrInvalidType = errors.New("fig: invalid type conversion")

	// ErrNotStruct indicates Load was called with a non-struct type.
	ErrNotStruct = errors.New("fig: type must be a struct")

	// ErrSecretNotFound indicates a secret was not found in the provider.
	ErrSecretNotFound = errors.New("fig: secret not found")
)

Sentinel errors for configuration loading.

Functions

func Load

func Load[T any](cfg *T, provider ...SecretProvider) error

Load populates a struct from environment variables, secrets, and defaults. An optional SecretProvider can be passed for secret tag resolution.

func LoadContext

func LoadContext[T any](ctx context.Context, cfg *T, provider ...SecretProvider) error

LoadContext populates a struct with context support for secret provider timeouts. An optional SecretProvider can be passed for secret tag resolution.

Types

type FieldError

type FieldError struct {
	Err   error
	Field string
}

FieldError wraps an error with field context.

func (*FieldError) Error

func (e *FieldError) Error() string

func (*FieldError) Unwrap

func (e *FieldError) Unwrap() error

type SecretProvider

type SecretProvider interface {
	// Get retrieves a secret by key.
	// Returns ErrSecretNotFound if the secret does not exist.
	Get(ctx context.Context, key string) (string, error)
}

SecretProvider defines the interface for secret backends.

type Validator

type Validator interface {
	Validate() error
}

Validator is an optional interface for config validation.