confi

README

confi

Configuration parser for Go.

Features

• Read and merge configuration values from environment variables, stdin and files.
• Generate JSON schema for configuration struct based on types and tags.
• Apply default values for configuration values.
• Support for JSON, YAML and Gob.

Usage

go get github.com/jfk9w-go/confi@latest

Command-line options

Option	Description
--config.stdin=<codec>	Read configuration from stdin. Supported codecs: yaml or yml, json, gob.
--config.file=<path>	Read configuration from file. Option may be used several times in order to pass multiple files. Codec is resolved based on filename extension. See supported codecs above.

Environment variables

Environment variables are filtered based on prefix passed to confi.Get() call.

A single configuration file may be specified via <prefix>_CONFIG_FILE environment variable.

Priority

When properties are specified in multiple ways (e.g. environment variable and CLI option), they have the following priority:

1. CLI options.
2. Configuration files.
3. Environment variables.

Arrays (slices) and maps are overridden as a whole.

Example

TODO

Documentation

Index

• Variables
• func CloseQuietly(value any)
• func SpecifyType(source any) any
• type Codec
  • func (c Codec) Marshal(value any, writer io.Writer) error
  • func (c Codec) Unmarshal(reader io.Reader, value any) error
• type DefaultSourceProvider
  • func (p *DefaultSourceProvider) GetSources(ctx context.Context) ([]Source, error)
• type File
  • func (f File) Path() string
  • func (f File) Reader() (io.Reader, error)
• type Format
  • func (f Format) SchemaEnum() any
• type Input
• type InputSource
  • func (s InputSource) GetValues(ctx context.Context) (map[string]any, error)
• type Property
  • func (p Property) Key() string
• type PropertySource
  • func (s PropertySource) GetValues(ctx context.Context) (map[string]any, error)
• type Reader
  • func (r Reader) Reader() (io.Reader, error)
• type Schema
  • func FromProvider[T any](ctx context.Context, provider SourceProvider) (*T, *Schema, error)
  • func GenerateSchema(value any) (*Schema, error)
  • func Get[T any](ctx context.Context, appName string) (*T, *Schema, error)
  • func (s *Schema) ApplyDefaults(source any) error
• type Source
• type SourceProvider

Variables

var Codecs = map[string]Codec{
	"json": JSON,
	"yaml": YAML,
	"yml":  YAML,
	"gob":  Gob,
}

var Gob = Codec{
	MarshalFn:   func(value any, writer io.Writer) error { return gob.NewEncoder(writer).Encode(value) },
	UnmarshalFn: func(reader io.Reader, value any) error { return gob.NewDecoder(reader).Decode(value) },
}

var JSON = Codec{
	MarshalFn: func(value any, writer io.Writer) error {
		encoder := json.NewEncoder(writer)
		encoder.SetIndent("", "  ")
		return encoder.Encode(value)
	},

	UnmarshalFn: func(reader io.Reader, value any) error { return json.NewDecoder(reader).Decode(value) },
}

var YAML = Codec{
	MarshalFn: func(value any, writer io.Writer) error {
		encoder := yaml.NewEncoder(writer)
		encoder.SetIndent(2)
		return encoder.Encode(value)
	},

	UnmarshalFn: func(reader io.Reader, value any) error { return yaml.NewDecoder(reader).Decode(value) },
}

Functions

func CloseQuietly

func CloseQuietly(value any)

func SpecifyType

func SpecifyType(source any) any

Types

type Codec

type Codec struct {
	MarshalFn   func(value any, writer io.Writer) error
	UnmarshalFn func(reader io.Reader, value any) error
}

func (Codec) Marshal

func (c Codec) Marshal(value any, writer io.Writer) error

func (Codec) Unmarshal

func (c Codec) Unmarshal(reader io.Reader, value any) error

type DefaultSourceProvider

type DefaultSourceProvider struct {
	EnvPrefix string
	Env       []string
	Args      []string
	Stdin     io.Reader
}

func (*DefaultSourceProvider) GetSources

func (p *DefaultSourceProvider) GetSources(ctx context.Context) ([]Source, error)

type File

type File string

func (File) Path

func (f File) Path() string

func (File) Reader

func (f File) Reader() (io.Reader, error)

type Format

type Format string

func (Format) SchemaEnum

func (f Format) SchemaEnum() any

type Input

type Input interface {
	Reader() (io.Reader, error)
}

type InputSource

type InputSource struct {
	Input  Input
	Format string
}

func (InputSource) GetValues

func (s InputSource) GetValues(ctx context.Context) (map[string]any, error)

type Property

type Property struct {
	Path  []string
	Value string
}

func (Property) Key

func (p Property) Key() string

type PropertySource

type PropertySource []Property

func (PropertySource) GetValues

func (s PropertySource) GetValues(ctx context.Context) (map[string]any, error)

type Reader

type Reader struct {
	R io.Reader
}

func (Reader) Reader

func (r Reader) Reader() (io.Reader, error)

type Schema

type Schema struct {
	Type                 string            `yaml:"type"`
	Items                *Schema           `yaml:"items,omitempty"`
	Properties           map[string]Schema `yaml:"properties,omitempty"`
	AdditionalProperties any               `yaml:"additionalProperties,omitempty"`
	Required             []string          `yaml:"required,omitempty"`

	// properties below are applied to primitive or inner types
	Enum             any     `yaml:"enum,omitempty" prop:"inner,array"`
	Examples         any     `yaml:"examples,omitempty" prop:"inner,array"`
	Pattern          string  `yaml:"pattern,omitempty" prop:"inner"`
	Format           string  `yaml:"format,omitempty" prop:"inner" alias:"fmt"`
	Minimum          any     `yaml:"minimum,omitempty" prop:"inner" alias:"min"`
	ExclusiveMinimum any     `yaml:"exclusiveMinimum,omitempty" prop:"inner" alias:"xmin"`
	Maximum          any     `yaml:"maximum,omitempty" prop:"inner" alias:"max"`
	ExclusiveMaximum any     `yaml:"exclusiveMaximum,omitempty" prop:"inner" alias:"xmax"`
	MultipleOf       any     `yaml:"multipleOf,omitempty" prop:"inner" alias:"mul"`
	MinLength        uint64  `yaml:"minLength,omitempty" prop:"inner" alias:"minlen"`
	MaxLength        *uint64 `yaml:"maxLength,omitempty" prop:"inner" alias:"maxlen"`

	// properties below are applied to primitive or outer types
	Description   string  `yaml:"description,omitempty" prop:"outer" alias:"desc,doc"`
	Default       any     `yaml:"default,omitempty" prop:"outer" alias:"def"`
	MinItems      uint64  `yaml:"minItems,omitempty" prop:"outer" alias:"minsize"`
	MaxItems      *uint64 `yaml:"maxItems,omitempty" prop:"outer" alias:"maxsize"`
	UniqueItems   bool    `yaml:"uniqueItems,omitempty" prop:"outer" alias:"unique"`
	MinProperties uint64  `yaml:"minProperties,omitempty" prop:"outer" alias:"minprops"`
	MaxProperties *uint64 `yaml:"maxProperties,omitempty" prop:"outer" alias:"maxprops"`
}

func FromProvider

func FromProvider[T any](ctx context.Context, provider SourceProvider) (*T, *Schema, error)

func GenerateSchema

func GenerateSchema(value any) (*Schema, error)

func Get

func Get[T any](ctx context.Context, appName string) (*T, *Schema, error)

func (*Schema) ApplyDefaults

func (s *Schema) ApplyDefaults(source any) error

type Source

type Source interface {
	GetValues(ctx context.Context) (map[string]any, error)
}

type SourceProvider

type SourceProvider interface {
	GetSources(ctx context.Context) ([]Source, error)
}