Documentation
¶
Overview ¶
Package config provides utilities for configuration parsing and loading. It includes functionality for handling command-line flags and loading configuration from YAML files and environment variables, with additional support for setting default values and validation. Additionally, it provides a struct that defines common settings for a TLS client.
Index ¶
- Variables
- func FromEnv(v Validator, options EnvOptions) error
- func FromYAMLFile(name string, v Validator) error
- func Load(v Validator, options LoadOptions) error
- func LoadPasswordFile(password *string, passwordFile string) error
- func ParseFlags(v any) error
- type CrlChecker
- type EnvOptions
- type Flags
- type LoadOptions
- type ServerTLS
- type TLS
- type TLSCommon
- type TlsClientAuthType
- type Validator
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidArgument = stderrors.New("invalid argument")
ErrInvalidArgument is the error returned by any function that loads configuration if the parsing result cannot be stored in the value pointed to by the specified argument, which must be a non-nil struct pointer.
var ErrInvalidConfiguration = stderrors.New("invalid configuration")
ErrInvalidConfiguration is attached to errors returned by any function that loads configuration when the configuration is invalid, i.e. if the Validate method of the provided Validator interface returns an error, which is then propagated by these functions. Note that for such errors, errors.Is() will recognize both ErrInvalidConfiguration and the original errors returned from Validate.
Functions ¶
func FromEnv ¶ added in v0.4.0
func FromEnv(v Validator, options EnvOptions) error
FromEnv parses environment variables and stores the result in the value pointed to by v. If v is nil or not a struct pointer, FromEnv returns an ErrInvalidArgument error.
It is possible to define default values via the struct tag `default`.
The function also validates the configuration using the Validate method of the provided Validator interface. Any error returned from Validate is propagated with ErrInvalidConfiguration attached, allowing errors.Is() checks on the returned errors to recognize both ErrInvalidConfiguration and the original errors returned from Validate.
Example usage:
type Config struct {
ServerAddress string `env:"SERVER_ADDRESS" default:"localhost:8080"`
TLS config.TLS
}
func (c *Config) Validate() error {
if _, _, err := net.SplitHostPort(c.ServerAddress); err != nil {
return errors.Wrapf(err, "invalid server address: %s", c.ServerAddress)
}
if err := c.TLS.Validate(); err != nil {
return errors.WithStack(err)
}
return nil
}
func main() {
var cfg Config
if err := config.FromEnv(cfg, config.EnvOptions{}); err != nil {
log.Fatalf("error loading config: %v", err)
}
tlsCfg, err := cfg.TLS.MakeConfig("icinga.com")
if err != nil {
log.Fatalf("error creating TLS config: %v", err)
}
// ...
}
func FromYAMLFile ¶
FromYAMLFile parses the given YAML file and stores the result in the value pointed to by v. If v is nil or not a struct pointer, FromYAMLFile returns an ErrInvalidArgument error.
It is possible to define default values via the struct tag `default`.
The function also validates the configuration using the Validate method of the provided Validator interface. Any error returned from Validate is propagated with ErrInvalidConfiguration attached, allowing errors.Is() checks on the returned errors to recognize both ErrInvalidConfiguration and the original errors returned from Validate.
Example usage:
type Config struct {
ServerAddress string `yaml:"server_address" default:"localhost:8080"`
TLS config.TLS `yaml:",inline"`
}
func (c *Config) Validate() error {
if _, _, err := net.SplitHostPort(c.ServerAddress); err != nil {
return errors.Wrapf(err, "invalid server address: %s", c.ServerAddress)
}
if err := c.TLS.Validate(); err != nil {
return errors.WithStack(err)
}
return nil
}
func main() {
var cfg Config
if err := config.FromYAMLFile("config.yml", &cfg); err != nil {
log.Fatalf("error loading config: %v", err)
}
tlsCfg, err := cfg.TLS.MakeConfig("icinga.com")
if err != nil {
log.Fatalf("error creating TLS config: %v", err)
}
// ...
}
func Load ¶ added in v0.5.0
func Load(v Validator, options LoadOptions) error
Load loads configuration from both YAML files and environment variables and stores the result in the value pointed to by v. If v is nil or not a struct pointer, Load returns an ErrInvalidArgument error.
It is possible to define default values via the struct tag `default`.
The function also validates the configuration using the Validate method of the provided Validator interface. Any error returned from Validate is propagated with ErrInvalidConfiguration attached, allowing errors.Is() checks on the returned errors to recognize both ErrInvalidConfiguration and the original errors returned from Validate.
This function handles configuration loading in three scenarios:
- Load configuration exclusively from YAML files when no applicable environment variables are set.
- Combine YAML file and environment variable configurations, allowing environment variables to supplement or override possible incomplete YAML data.
- Load entirely from environment variables if the default YAML config file is missing and no specific config path is provided.
Example usage:
const DefaultConfigPath = "/path/to/config.yml"
type Flags struct {
Config string `short:"c" long:"config" description:"Path to config file"`
}
func (f Flags) GetConfigPath() string {
if f.Config == "" {
return DefaultConfigPath
}
return f.Config
}
func (f Flags) IsExplicitConfigPath() bool {
return f.Config != ""
}
type Config struct {
ServerAddress string `yaml:"server_address" env:"SERVER_ADDRESS" default:"localhost:8080"`
TLS config.TLS `yaml:",inline"`
}
func (c *Config) Validate() error {
if _, _, err := net.SplitHostPort(c.ServerAddress); err != nil {
return errors.Wrapf(err, "invalid server address: %s", c.ServerAddress)
}
if err := c.TLS.Validate(); err != nil {
return errors.WithStack(err)
}
return nil
}
func main() {
var flags Flags
if err := config.ParseFlags(&flags); err != nil {
log.Fatalf("error parsing flags: %v", err)
}
var cfg Config
if err := config.Load(&cfg, config.LoadOptions{Flags: flags, EnvOptions: config.EnvOptions{}}); err != nil {
log.Fatalf("error loading config: %v", err)
}
tlsCfg, err := cfg.TLS.MakeConfig("icinga.com")
if err != nil {
log.Fatalf("error creating TLS config: %v", err)
}
// ...
}
func LoadPasswordFile ¶ added in v0.9.0
LoadPasswordFile populates the password field from the content of a password file.
This is a helper function to be used in Validator.Validate implementations on types where both a password and a password file field are available. If both a password and a password file are given, an error is returned.
func ParseFlags ¶
ParseFlags parses CLI flags and stores the result in the value pointed to by v. If v is nil or not a struct pointer, ParseFlags returns an ErrInvalidArgument error.
ParseFlags adds a default Help Options group, which contains the options -h and --help. If either option is specified on the command line, ParseFlags prints the help message to os.Stdout and exits.
Note that errors are not printed automatically, so error handling is the sole responsibility of the caller.
Example usage:
type Flags struct {
Config string `short:"c" long:"config" description:"Path to config file" required:"true"`
}
func main() {
var flags Flags
if err := config.ParseFlags(&flags); err != nil {
log.Fatalf("error parsing flags: %v", err)
}
// ...
}
Types ¶
type CrlChecker ¶ added in v0.10.0
type CrlChecker struct {
// contains filtered or unexported fields
}
CrlChecker loads a Certificate Revocation List (CRL) from a file, verifies its signature against a trusted CA certificate, and exposes CrlChecker.IsRevoked for serial number lookups. The in-memory CRL is protected by a read/write mutex so that background reloads via CrlChecker.WatchAndReload are safe to run concurrently with ongoing checks.
func NewCRLChecker ¶ added in v0.10.0
func NewCRLChecker(path string, issuer *x509.Certificate) (*CrlChecker, error)
NewCRLChecker creates a CrlChecker by loading the CRL at path and verifying its signature against issuer. The file may be PEM- or DER-encoded. An error is returned if the file cannot be read, is not a valid CRL, or its signature does not match issuer.
func (*CrlChecker) IsRevoked ¶ added in v0.10.0
func (c *CrlChecker) IsRevoked(serial *big.Int) (bool, error)
IsRevoked reports whether serial appears in the CRL.
It returns an error if the CRL is outdated (NextUpdate in the past).
func (*CrlChecker) WatchAndReload ¶ added in v0.10.0
func (c *CrlChecker) WatchAndReload(ctx context.Context, logger *zap.SugaredLogger) error
WatchAndReload blocks, watching the CRL file for changes and reloading it whenever a Write, Create, or Rename event is received. It returns when ctx is canceled. Reload failures are logged as warnings and do not stop the watcher.
type EnvOptions ¶ added in v0.4.0
EnvOptions is a type alias for env.Options, so that only this package needs to import env.
type Flags ¶ added in v0.5.0
type Flags interface {
// GetConfigPath retrieves the path to the configuration file as specified by command line flags,
// or returns a default path if none was provided.
GetConfigPath() string
// IsExplicitConfigPath indicates whether the configuration file path was
// explicitly set through command line flags.
IsExplicitConfigPath() bool
}
Flags is an interface that provides methods related to access the configuration file path specified via command line flags. This interface is meant to be implemented by flag structs containing a switch for the configuration file path.
type LoadOptions ¶ added in v0.5.0
type LoadOptions struct {
// Flags provides access to specific command line flag values.
Flags Flags
// EnvOptions contains options for loading configuration from environment variables.
EnvOptions EnvOptions
}
LoadOptions contains options for loading configuration from both files and environment variables.
type ServerTLS ¶ added in v0.10.0
type ServerTLS struct {
TLSCommon `yaml:",inline"`
// ClientAuth specifies the policy the server will follow for TLS Client Authentication.
//
// If empty, the default is [tls.NoClientCert], meaning that the server will not request a certificate from
// clients and will not verify any certificates if they are sent. This is the most common mode for TLS servers,
// unless client authentication is explicitly required to restrict access to the server to specific clients.
//
// Valid values are all the [tls.ClientAuthType] options typed out as strings:
// "NoClientCert", "RequestClientCert", "RequireAnyClientCert", "VerifyClientCertIfGiven", and "RequireAndVerifyClientCert".
ClientAuth TlsClientAuthType `yaml:"client_auth" env:"CLIENT_AUTH" default:"NoClientCert"`
// CrlFile is the path to the Certificate Revocation List (CRL) file.
//
// If specified, the CRL is used to check for revoked certificates in TLS.
// The CRL must be signed by the CA specified in the Ca option. If the CRL file is not found or cannot be loaded,
// an error is returned during TLS configuration.
// This option is ignored if TLS is not enabled. If the Ca option is not set it returns an error.
//
// At the moment, only one CA certificate is supported.
//
// Note that populating this field alone does not enable CRL checking.
// [ServerTLS.InitRevocationChecking] must be called after assembling the [tls.Config]
// to wire up the actual revocation check.
CrlFile string `yaml:"crl_file" env:"CRL_FILE"`
}
ServerTLS represents all required TLS configuration options for a TLS server.
It embeds TLSCommon to include the common TLS settings, and adds the ClientAuth field to specify the TLS client authentication policy the server will follow for client authentication, with the default being tls.NoClientCert.
Use the ServerTLS.MakeConfig method to assemble a *tls.Config from the ServerTLS struct.
func (*ServerTLS) InitRevocationChecking ¶ added in v0.10.0
func (st *ServerTLS) InitRevocationChecking(tlsConfig *tls.Config) (*CrlChecker, error)
InitRevocationChecking wires CRL-based client certificate revocation checking into tlsConfig.
It loads the CA certificate from TLSCommon.Ca and the CRL from ServerTLS.CrlFile, verifies the CRL's signature against the CA, and installs a tls.Config.VerifyConnection hook that rejects any client certificate whose serial number appears in the CRL. If a VerifyConnection hook is already set on tlsConfig, the existing hook is called first and its error, if any, takes precedence.
The returned CrlChecker owns the loaded CRL and must be kept alive for the duration of the server's lifetime. Callers are responsible for calling CrlChecker.WatchAndReload to pick up CRL rotations at runtime.
InitRevocationChecking returns an error if tlsConfig, the CA certificate or CRL cannot be loaded or verified.
func (*ServerTLS) MakeConfig ¶ added in v0.10.0
MakeConfig assembles a *tls.Config from the ServerTLS struct.
It returns a configured *tls.Config or an error if there are issues with the provided TLS settings. If TLS is not enabled (st.Enable is false), it returns nil without an error.
type TLS ¶
type TLS struct {
TLSCommon `yaml:",inline"`
// Insecure indicates whether to skip verification of the server's certificate chain and host name.
// If true, any certificate presented by the server and any host name in that certificate is accepted.
// In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used.
Insecure bool `yaml:"insecure" env:"INSECURE"`
}
TLS represents configuration for a TLS client. It provides options to enable TLS, specify certificate and key files, CA certificate, and whether to skip verification of the server's certificate chain and host name. Use the TLS.MakeConfig method to assemble a *tls.Config from the TLS struct.
func (*TLS) MakeConfig ¶
MakeConfig assembles a *tls.Config from the TLS struct and the provided serverName. It returns a configured *tls.Config or an error if there are issues with the provided TLS settings. If TLS is not enabled (t.Enable is false), it returns nil without an error.
type TLSCommon ¶ added in v0.10.0
type TLSCommon struct {
// Enable indicates whether TLS is enabled.
//
// If false, the other TLS settings are ignored and no TLS configuration is created.
Enable bool `yaml:"tls" env:"TLS"`
// Cert is either the path to the client/server TLS certificate file or a raw PEM-encoded string.
//
// In TLS client mode, this certificate is sent to the server if requested, and may be used by
// the server to authenticate the client. In TLS server mode, this certificate is sent to clients
// during the TLS handshake and is used by clients to authenticate the server. Thus, in TLS server
// mode, this option is required if TLS is enabled. In either mode, if this option is set, the Key
// option must also be set to provide the corresponding private key.
Cert string `yaml:"cert" env:"CERT"`
// Key is either the path to the private key file corresponding to the TLS cert or a raw PEM-encoded string.
//
// If this option is set, the Cert option must also be set to provide the corresponding TLS certificate.
Key string `yaml:"key" env:"KEY,unset"`
// Ca is either the path to the CA certificate file or a raw PEM-encoded string representing it.
//
// If specified, the CA certificate is used to verify the server's certificate in TLS client mode,
// or to verify client certificates in TLS server mode. Otherwise, the system's root CA pool is used.
// This option is ignored if Insecure is true in TLS client mode.
Ca string `yaml:"ca" env:"CA"`
}
TLSCommon represents common TLS config options that are shared between TLS client and server settings.
type TlsClientAuthType ¶ added in v0.10.0
type TlsClientAuthType tls.ClientAuthType
TlsClientAuthType is a wrapper around tls.ClientAuthType that implements encoding.TextUnmarshaler and yaml.InterfaceUnmarshaler.
func (*TlsClientAuthType) UnmarshalText ¶ added in v0.10.0
func (o *TlsClientAuthType) UnmarshalText(text []byte) error
UnmarshalText implements encoding.TextUnmarshaler to allow parsing ClientAuth from environment variables.
This is required by the env library, which is used to parse environment variables into the configuration struct.
func (*TlsClientAuthType) UnmarshalYAML ¶ added in v0.10.0
func (o *TlsClientAuthType) UnmarshalYAML(unmarshal func(any) error) error
UnmarshalYAML implements yaml.InterfaceUnmarshaler to allow Options to be parsed go-yaml.
type Validator ¶
type Validator interface {
// Validate checks the configuration values and
// returns an error if any value is invalid or missing when required.
Validate() error
}
Validator is an interface that must be implemented by any struct into which configuration is intended to be loaded.
The Validate method checks the configuration values and returns an error if any value is invalid or missing when required.
For fields such as file paths, the responsibility of Validate is limited to verifying the presence and format of the value, not checking external conditions like file existence or readability. This principle applies generally to any field where external validation (e.g., network availability, resource accessibility) is beyond the scope of basic configuration validation.