coil

README

Coil

Coil is a lightweight Go package for configuration management, built on top of Viper and Cobra. It simplifies configuration handling by allowing you to compose and layer settings using Go structs. Configuration values are automatically exposed as both CLI flags and config file options, providing flexible deployment options for your applications.

➕ Install

go get github.com/cvlsoft/coil

📦 Prebuilt Configurations

Coil ships with a number of very basic and useful configurations. These out-of-the-box options cover basic functions like API keys, database connections, and authentication etc:

• coil.Config: Base Coil configuration used on all struct definitions.
• coil.APIServiceConfig: Defines fundamental configurations for an API service
• coil.DatabaseConfig: Helps define standard database connection details.

We hope to expand this list of predefined types with community contributions.

⚡️ Quickstart

package config

import (
	configs "github.com/cvlsoft/coil"
)

// Config represents your app's local config
type Config struct {
	coil.Config
	coil.APIServiceConfig
	coil.DatabaseConfig
	MyCustomConfig
}

// MyCustomConfig representsa custom configuration
type MyCustomConfig struct {
	FooBar string `type:"string" name:"foo_bar" default:"static" desc:"Foo bar value"`
}

// NewConfig is a factory generator for your configuration
func NewConfig() *Config {
	c := coil.NewConfig(&Config{})
	return c.(*Config)
}

This simple declaration will allow you to define your YAML config file like so:

name: "prod"
dbhost: 192.168.1.1
dbname: my_name
dbuser: my_user
dbpass: my_pass
dbport: 25061
port: 8443
host: 0.0.0.0
api_url: https://api.myservice.com
foo_bar: override

You can also use any of the configuration format supported by Viper (JSON, TOML, YAML, ENV, etc.). You can also automatically use your CLI for defining config overrides:

go run main.go --foo_bar=dynamic

🔀 Using Prefixes for Multiple Instances

When you need to use the same configuration type multiple times (e.g., multiple database connections), use the prefix tag to avoid naming collisions:

type Config struct {
    coil.Config
    PrimaryDB coil.DatabaseConfig `prefix:"primary"`
    ReplicaDB coil.DatabaseConfig `prefix:"replica"`
}

This allows you to configure each instance independently via environment variables:

# Primary database
export PRIMARY_DBHOST=primary.example.com
export PRIMARY_DBPORT=5432
export PRIMARY_DBUSER=primary_user

# Replica database
export REPLICA_DBHOST=replica.example.com
export REPLICA_DBPORT=5433
export REPLICA_DBUSER=replica_user

Or via CLI flags:

go run main.go --primary_dbhost=primary.example.com --replica_dbhost=replica.example.com

Or in your config file:

primary_dbhost: primary.example.com
primary_dbport: 5432
replica_dbhost: replica.example.com
replica_dbport: 5433

🌐 Community Contributions

We welcome contributions from the community to expand the list of predefined types. If you have a configuration type that you think would be useful for others, please submit a pull request with your contribution.

📃 License

Coil is released under the MIT. See LICENSE.txt

Documentation

Index

• func CreateViper() (v *viper.Viper)
• func CreateViperWithFlagSet(fs *pflag.FlagSet) (v *viper.Viper)
• type APIServiceConfig
• type Config
  • func (c *Config) HasConfig(checkType any) bool
• type Configer
  • func NewConfig(c Configer, merge ...bool) Configer
  • func NewConfigWithFlagSet(c Configer, fs *pflag.FlagSet) Configer
• type DatabaseConfig
• type LogConfig

Functions

func CreateViper

func CreateViper() (v *viper.Viper)

CreateViper creates a parser instance to configure CLI. It can be used for packages that re-implement the command line flags

func CreateViperWithFlagSet

func CreateViperWithFlagSet(fs *pflag.FlagSet) (v *viper.Viper)

CreateViperWithFlagSet creates a parser instance with a custom flagset This is useful for testing

Types

type APIServiceConfig

type APIServiceConfig struct {
	Version string        `type:"string" name:"version" default:"1.0.0" desc:"API version (follows semver)"`
	Name    string        `type:"string" name:"name" default:"service-api" desc:"Default name of the service"`
	Build   string        `type:"string" name:"build" default:"UNSPECIFIED" desc:"Build version"`
	Host    string        `type:"string" name:"host" default:"localhost" desc:"Server hostname to bind to"`
	URL     string        `type:"string" name:"api_url" default:"" desc:"The URL to the API"`
	Port    int           `type:"int" name:"port" default:"80" desc:"Server port to bind to"`
	Timeout time.Duration `type:"duration" name:"timeout" default:"15s" desc:"Timeout for any connection i.e. 10s"`
}

APIServiceConfig is a global struct passed to all services

type Config

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

Config is a standard definition for config interfaces

func (*Config) HasConfig

func (c *Config) HasConfig(checkType any) bool

HasConfig checks if a specific config type is embedded in the Config struct

type Configer

type Configer interface {
	// contains filtered or unexported methods
}

Configer provides an identifier interface for all configuration types

func NewConfig

func NewConfig(c Configer, merge ...bool) Configer

NewConfig generates a new configuration setup

func NewConfigWithFlagSet

func NewConfigWithFlagSet(c Configer, fs *pflag.FlagSet) Configer

NewConfigWithFlagSet generates a new configuration setup with a custom flagset This is useful for testing or when you want to use a specific flagset

type DatabaseConfig

type DatabaseConfig struct {
	DBHost  string `type:"string" name:"dbhost" default:"localhost" desc:"Database hostname"`
	DBUser  string `type:"string" name:"dbuser" default:"" desc:"Database username"`
	DBName  string `type:"string" name:"dbname" default:"" desc:"Database name"`
	DBPass  string `type:"string" name:"dbpass" default:"" desc:"Database password"`
	DBSSL   string `type:"string" name:"dbssl" default:"disable" desc:"Database SSL mode"`
	DBDebug bool   `type:"string" name:"dbdebug" default:"" desc:"Enable database debug mode"`
	DBPort  int    `type:"int" name:"dbport" default:"5432" desc:"Database port number"`
}

DatabaseConfig represents a composable struct for db connections

type LogConfig

type LogConfig struct {
	// Core logging settings
	Level  string `type:"string" name:"log_level" default:"info" desc:"Log level (trace, debug, info, warn, error, fatal)"`
	Format string `type:"string" name:"log_format" default:"json" desc:"Log format (json, text, logfmt)"`

	// Output configuration
	Output     string `type:"string" name:"log_output" default:"stdout" desc:"Log output destination (stdout, stderr, file)"`
	FilePath   string `type:"string" name:"log_file_path" default:"./logs/app.log" desc:"Path to log file when output is 'file'"`
	MaxSize    int    `type:"int" name:"log_max_size" default:"100" desc:"Maximum size in megabytes before rotation"`
	MaxBackups int    `type:"int" name:"log_max_backups" default:"3" desc:"Maximum number of old log files to retain"`
	MaxAge     int    `type:"int" name:"log_max_age" default:"28" desc:"Maximum number of days to retain old log files"`
	Compress   bool   `type:"bool" name:"log_compress" default:"false" desc:"Whether to compress rotated log files"`

	// Field configuration
	StaticFields string `type:"string" name:"log_static_fields" default:"" desc:"Static fields to include in all logs (JSON format)"`
	ServiceName  string `type:"string" name:"log_service_name" default:"" desc:"Service name to include in logs"`
	Environment  string `type:"string" name:"log_environment" default:"" desc:"Environment name (dev, staging, prod)"`
	InstanceID   string `type:"string" name:"log_instance_id" default:"" desc:"Instance/container ID to include in logs"`
}

LogConfig represents a composable struct for logging