config

README

config

A utility for loading configuration YAML files.

Design

The config package provides a way to load configuration from YAML files. By default it will load a file named app-config.yaml in the root directory where your main package resides. Then it will load a file named app-config.<env>.yaml and use those values to override the previous configuration. The environment is determined by the value of the APP_ENV environment variable. If APP_ENV is not set, it will fall back to the value of the DEPLOYEMENT_STAGE environment variable. If neither are set, no override file will be loaded. The config package also supports loading configuration from a custom directory.

Custom Configuration Directory

There are two ways to specify a custom directory to load configuration files from. The first is to set the CONFIG_YAML_DIRECTORY environment variable. The second is to use the WithConfigYamlDir option when calling LoadConfiguration.

Configuration Structs

The config package uses the mapstructure package to load configuration into a struct. This allows for the use of tags to map configuration fields to struct fields. For example, the following YAML file:

auth:
  enable: true

can be loaded into the following struct:

type AuthConfiguration struct {
  Enable    *bool  `mapstructure:"enable"`
}

type Configuration struct {
  Auth     AuthConfiguration     `mapstructure:"auth"`
}

Environment Variables

The config package supports templated injection of environment variables in your YAML files to avoid storing sensitive values in the YAMLs. For example, the following YAML file:

database:
  driver: postgres
  data_source_name: host={{.PLATFORM_DATABASE_HOST}} user={{.PLATFORM_DATABASE_USER}} password={{.PLATFORM_DATABASE_PASSWORD}} port={{.PLATFORM_DATABASE_PORT}} dbname={{.PLATFORM_DATABASE_NAME}}

will have the environment variables PLATFORM_DATABASE_HOST, PLATFORM_DATABASE_USER, PLATFORM_DATABASE_PASSWORD, PLATFORM_DATABASE_PORT, and PLATFORM_DATABASE_NAME injected into the data_source_name field prior to loading into your configuration struct.

Usage

Example:

package main

import (
  "fmt"

  "github.com/chanzuckerberg/go-misc/config"
)

type AuthConfiguration struct {
	Enable    *bool  `mapstructure:"enable"`
}

type ApiConfiguration struct {
	Port                uint   `mapstructure:"port"`
	LogLevel            string `mapstructure:"log_level"`
}

type DBDriver string

func (d *DBDriver) String() string {
	return string(*d)
}

const (
	Sqlite   DBDriver = "sqlite"
	Postgres DBDriver = "postgres"
)

type DatabaseConfiguration struct {
	Driver         DBDriver `mapstructure:"driver"`
	DataSourceName string   `mapstructure:"data_source_name"`
}

type Configuration struct {
	Auth     AuthConfiguration     `mapstructure:"auth"`
	Api      ApiConfiguration      `mapstructure:"api"`
	Database DatabaseConfiguration `mapstructure:"database"`
}

func main() {
  cfg := &Configuration{}

  configOpts := []config.ConfigOption[Configuration]{
    config.WithConfigYamlDir[Configuration]("./configs"),
    config.WithConfigEditorFn(func(cfg *Configuration) error {
      // default to having auth enabled
      if cfg.Auth.Enable == nil {
        enable := true
        cfg.Auth.Enable = &enable
      }
      return nil
    }),
  }

  err := config.LoadConfiguration(cfg, configOpts...)
  if err != nil {
    panic(fmt.Sprintf("Failed to load app configuration: %s", err.Error()))
  }
}

Documentation

Index

• func LoadConfiguration[T any](cfg *T, opts ...ConfigOption[T]) error
• type ConfigEditorFn
• type ConfigLoader
• type ConfigOption
  • func WithConfigEditorFn[T any](fn ConfigEditorFn[T]) ConfigOption[T]
  • func WithConfigYamlDir[T any](dir string) ConfigOption[T]

Functions

func LoadConfiguration

func LoadConfiguration[T any](cfg *T, opts ...ConfigOption[T]) error

LoadConfiguration loads the configuration from the app-config.yaml and app-config.<env>.yaml files

Types

type ConfigEditorFn

type ConfigEditorFn[T any] func(cfg *T) error

ConfigEditorFn is a function that can be used to modify the configuration values after they have been loaded

type ConfigLoader

type ConfigLoader[T any] struct {
	ConfigEditors []ConfigEditorFn[T]
	ConfigYamlDir string
}

type ConfigOption

type ConfigOption[T any] func(*ConfigLoader[T]) error

ConfigOption is a function that can be used to modify the configuration loader

func WithConfigEditorFn

func WithConfigEditorFn[T any](fn ConfigEditorFn[T]) ConfigOption[T]

WithConfigEditorFn allows setting up a callback function, which will be called right after loading the configs. This can be used to mutate the config, for example to set default values where none were set by the call to LoadConfiguration.

func WithConfigYamlDir

func WithConfigYamlDir[T any](dir string) ConfigOption[T]