config

README

Minimalist Go Config Library

The config package contains types useful for validating, parsing, and loading values of some useful types in config files. The config types generally embed a corresponding standard library type, and provide Unmarshaler and Marshaler support for loading configs from and saving configs to JSON and YAML formats.

The types in this package also implement flag.Value for use in command line arguments.

Types include:

• net/url.URL
• time.Duration
• net.{UDP,TCP,Unix}Addr
• crypto/tls.Config

All of these Unmarshal from and Marshal to their natural string representations, with the exception of tls.Config, which is represented in the configuration as a dictionary of filenames and other settings.

An additional utility String type holds a string value which can optionally be read from the environment or from a named file.

Example

import (
        "encoding/json"
        "github.com/farsightsec/go-config"
)

type Config struct {
        Server   config.URL
        Timeout  config.Duration
        Username config.String
        Key      config.String
}

// cfg.Server.URL = net/url.URL of Server.
// cfg.Timeout.Duration = time.Duration of Timeout.
var cfg Config

var serverURL config.URL

func init() {
        configText := `
        {
                "Server": "https://example.com:8080/api/",
                "Timeout": "90s",
                "Username": "$USER",
                "Key": "/etc/app/apikey"
        }`
        if err := json.Unmarshal([]byte(configText)); err != nil {
                panic(err)
        }

        flag.Var(&serverURL, "server", "URL for server")
}

Documentation

Overview

Package config provides convenience wrappers for useful standard library types easing their use in JSON and YAML config files and as flag Values for command line tools.

This allows you to Unmarshal JSON or YAML into:

type myConfig struct {
        Server    config.URL
        TLS       config.TLS
}

and have a net/url url.URL value available as cfg.Server.URL, and a TLS configuration as cfg.TLS.Config, with the config package taking care of parsing and validation.

Index

• func LoadJSON(i interface{}, filename string, required bool) error
• func LoadYAML(i interface{}, filename string, required bool) error
• type Addr
  • func (a Addr) MarshalJSON() ([]byte, error)
  • func (a Addr) MarshalYAML() (interface{}, error)
  • func (a *Addr) Set(s string) error
  • func (a *Addr) UnmarshalJSON(b []byte) error
  • func (a *Addr) UnmarshalYAML(u func(interface{}) error) error
• type Duration
  • func (d Duration) MarshalJSON() ([]byte, error)
  • func (d Duration) MarshalYAML() (interface{}, error)
  • func (d *Duration) Set(s string) (err error)
  • func (d *Duration) UnmarshalJSON(b []byte) error
  • func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error
• type String
  • func (s *String) MarshalJSON() ([]byte, error)
  • func (s *String) MarshalYAML() (interface{}, error)
  • func (s *String) Set(v string) (err error)
  • func (s *String) String() string
  • func (s *String) UnmarshalJSON(b []byte) error
  • func (s *String) UnmarshalYAML(u func(interface{}) error) error
• type TCPAddr
  • func (t TCPAddr) MarshalJSON() ([]byte, error)
  • func (t TCPAddr) MarshalYAML() (interface{}, error)
  • func (t *TCPAddr) Set(s string) (err error)
  • func (t *TCPAddr) UnmarshalJSON(b []byte) error
  • func (t *TCPAddr) UnmarshalYAML(u func(interface{}) error) error
• type TLS
  • func (t TLS) MarshalJSON() ([]byte, error)
  • func (t TLS) MarshalYAML() (interface{}, error)
  • func (t *TLS) UnmarshalJSON(b []byte) (err error)
  • func (t *TLS) UnmarshalYAML(u func(interface{}) error) (err error)
• type TLSClientAuth
  • func (auth TLSClientAuth) MarshalJSON() ([]byte, error)
  • func (auth TLSClientAuth) MarshalYAML() (interface{}, error)
  • func (auth *TLSClientAuth) Set(s string) error
  • func (auth *TLSClientAuth) String() string
  • func (auth *TLSClientAuth) UnmarshalJSON(b []byte) error
  • func (auth *TLSClientAuth) UnmarshalYAML(u func(interface{}) error) error
• type TLSConfig
• type UDPAddr
  • func (u UDPAddr) MarshalJSON() ([]byte, error)
  • func (u UDPAddr) MarshalYAML() (interface{}, error)
  • func (u *UDPAddr) Set(s string) (err error)
  • func (u *UDPAddr) UnmarshalJSON(b []byte) error
  • func (u *UDPAddr) UnmarshalYAML(unmarshal func(interface{}) error) error
• type URL
  • func (u URL) MarshalJSON() ([]byte, error)
  • func (u URL) MarshalYAML() (interface{}, error)
  • func (u *URL) Set(s string) (err error)
  • func (u *URL) UnmarshalJSON(b []byte) error
  • func (u *URL) UnmarshalYAML(unmarshal func(interface{}) error) error
• type UnixAddr
  • func (u UnixAddr) MarshalJSON() ([]byte, error)
  • func (u UnixAddr) MarshalYAML() (interface{}, error)
  • func (u *UnixAddr) Set(s string) (err error)
  • func (u *UnixAddr) UnmarshalJSON(b []byte) error
  • func (u *UnixAddr) UnmarshalYAML(unmarshal func(interface{}) error) error

Functions

func LoadJSON

func LoadJSON(i interface{}, filename string, required bool) error

LoadJSON populates the configuration from the JSON-formatted contents of the file `filename`. If `required` is false, LoadJSON returns a nil error if the file does not exist.

func LoadYAML

func LoadYAML(i interface{}, filename string, required bool) error

LoadYAML populates the configuration from the YAML-formatted contents of the file `filename`. If `required` is false, LoadYAML returns a nil error if the file does not exist.

Types

type Addr

type Addr struct{ net.Addr }

Addr is a generic network address with JSON and YAML Marshaler and Unmarshaler methods.

func (Addr) MarshalJSON

func (a Addr) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (Addr) MarshalYAML

func (a Addr) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*Addr) Set

func (a *Addr) Set(s string) error

Set satisfies flag.Value for use with command line flags.

func (*Addr) UnmarshalJSON

func (a *Addr) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*Addr) UnmarshalYAML

func (a *Addr) UnmarshalYAML(u func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type Duration

type Duration struct{ time.Duration }

Duration provides JSON Marshaling and Unmarshaling for time.Duration values. The JSON string format is that supported by the Parse() and String() methods of time.Duration, e.g., "1m30s", "100ms", etc.

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON satisfies json.Marshaler

func (Duration) MarshalYAML

func (d Duration) MarshalYAML() (interface{}, error)

MarshalYAML satisfies yaml.Marshaler

func (*Duration) Set

func (d *Duration) Set(s string) (err error)

Set satisfies the flag.Value interface for use as a command line flag.

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies json.Unmarshaler

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML satisfies yaml.Unmarshaler

type String

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

String is a string value which can optionally be read from an environment variable or file.

A string value beginning with "$" is replaced by the value of the environment variable named by the rest of the string. If the value starts with "/", "./", or "../", it is replaced by the contents of the file named by the path. Otherwise, the string value is used as is.

Marshaling a String marshals the original form (environment variable or file, if applicable) in all cases.

func (*String) MarshalJSON

func (s *String) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (*String) MarshalYAML

func (s *String) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*String) Set

func (s *String) Set(v string) (err error)

Set sets the String to the value v, expanding v if it is an environment variable or file.

func (*String) String

func (s *String) String() string

String() returns the string value of the string.

func (*String) UnmarshalJSON

func (s *String) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*String) UnmarshalYAML

func (s *String) UnmarshalYAML(u func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type TCPAddr

type TCPAddr struct{ *net.TCPAddr }

TCPAddr is an address restricted to be in the "tcp", "tcp4", or "tcp6" networks.

func (TCPAddr) MarshalJSON

func (t TCPAddr) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (TCPAddr) MarshalYAML

func (t TCPAddr) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*TCPAddr) Set

func (t *TCPAddr) Set(s string) (err error)

Set satisfies flag.Value for use in command line arguments

func (*TCPAddr) UnmarshalJSON

func (t *TCPAddr) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*TCPAddr) UnmarshalYAML

func (t *TCPAddr) UnmarshalYAML(u func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type TLS

type TLS struct {
	TLSConfig
	*tls.Config
}

TLS provides JSON and YAML Marshalers and Unmarshalers for loading values into tls.Config.

The JSON and YAML configuration format is provided by the embedded type TLSConfig.

func (TLS) MarshalJSON

func (t TLS) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (TLS) MarshalYAML

func (t TLS) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*TLS) UnmarshalJSON

func (t *TLS) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*TLS) UnmarshalYAML

func (t *TLS) UnmarshalYAML(u func(interface{}) error) (err error)

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type TLSClientAuth

type TLSClientAuth struct{ tls.ClientAuthType }

TLSClientAuth provides a convenience wrapper for tls.ClientAuthType and conversion to and from string format.

Supported string values are:

"none":           tls.NoClientCert  (default)
"request":        tls.RequestClientCert
"require":        tls.RequireAnyClientCert
"verify":         tls.VerifyClientCertIfGiven
"require+verify": tls.RequireAndVerifyClientCert

func (TLSClientAuth) MarshalJSON

func (auth TLSClientAuth) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (TLSClientAuth) MarshalYAML

func (auth TLSClientAuth) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*TLSClientAuth) Set

func (auth *TLSClientAuth) Set(s string) error

Set satisfies the flag.Value interface.

func (*TLSClientAuth) String

func (auth *TLSClientAuth) String() string

String satisfies the flag.Value interface

func (*TLSClientAuth) UnmarshalJSON

func (auth *TLSClientAuth) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*TLSClientAuth) UnmarshalYAML

func (auth *TLSClientAuth) UnmarshalYAML(u func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type TLSConfig

type TLSConfig struct {
	RootCAFiles   []string      `json:"rootCAFiles,omitempty" yaml:"rootCAFiles,omitempty"`
	ClientCAFiles []string      `json:"clientCAFiles,omitempty" yaml:"clientCAFiles,omitempty"`
	ClientAuth    TLSClientAuth `json:"clientAuth,omitempty" yaml:"clientAuth,omitempty"`
	Certificates  []struct {
		CertFile string `json:"certFile" yaml:"certFile"`
		KeyFile  string `json:"keyFile" yaml:"keyFile"`
	} `json:"certificates,omitempty" yaml:"certificates,omitempty"`
}

TLSConfig contains the configuration for TLS as it appears on the JSON or YAML config. Values parsed from the config are translated and loaded into corresponding fields in tls.Config.

type UDPAddr

type UDPAddr struct{ *net.UDPAddr }

UDPAddr is an address restricted to be in the network "udp", "udp4", or "udp6". Other networks are considered an error.

func (UDPAddr) MarshalJSON

func (u UDPAddr) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (UDPAddr) MarshalYAML

func (u UDPAddr) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*UDPAddr) Set

func (u *UDPAddr) Set(s string) (err error)

Set satisfies flag.Value for use in command line arguments

func (*UDPAddr) UnmarshalJSON

func (u *UDPAddr) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*UDPAddr) UnmarshalYAML

func (u *UDPAddr) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface

type URL

type URL struct{ *url.URL }

URL provides JSON Marshaling and Unmarshaling of URLs, internally representing them as *url.URL from net/url.

func (URL) MarshalJSON

func (u URL) MarshalJSON() ([]byte, error)

MarshalJSON satisfies json.Marshaler

func (URL) MarshalYAML

func (u URL) MarshalYAML() (interface{}, error)

MarshalYAML satisfies yaml.Marshaler

func (*URL) Set

func (u *URL) Set(s string) (err error)

Set satisfies the flag.Value interface along with the net.URL String() method.

func (*URL) UnmarshalJSON

func (u *URL) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies json.Unmarshaler

func (*URL) UnmarshalYAML

func (u *URL) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML satisfies yaml.Unmarshaler

type UnixAddr

type UnixAddr struct{ *net.UnixAddr }

UnixAddr is a unix-domain socket address in the "unix", "unixpacket", or "unixgram" network

func (UnixAddr) MarshalJSON

func (u UnixAddr) MarshalJSON() ([]byte, error)

MarshalJSON satisfies the json.Marshaler interface

func (UnixAddr) MarshalYAML

func (u UnixAddr) MarshalYAML() (interface{}, error)

MarshalYAML satisfies the yaml.Marshaler interface

func (*UnixAddr) Set

func (u *UnixAddr) Set(s string) (err error)

Set satisfies flag.Value for use in command line arguments

func (*UnixAddr) UnmarshalJSON

func (u *UnixAddr) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies the json.Unmarshaler interface

func (*UnixAddr) UnmarshalYAML

func (u *UnixAddr) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML satisfies the yaml.Unmarshaler interface