configsource

Documentation

Overview

Package configsource is an internal package that implements methods for injecting, watching, and updating data from ConfigSource into configuration.

Index

• type Manager
  • func NewManager(_ *configparser.Parser) (*Manager, error)
  • func (m *Manager) Close(ctx context.Context) error
  • func (m *Manager) Resolve(ctx context.Context, parser *configparser.Parser) (*configparser.Parser, error)
  • func (m *Manager) WaitForWatcher()
  • func (m *Manager) WatchForUpdate() error

Types

type Manager

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

Manager is used to inject data from config sources into a configuration and also to monitor for updates on the items injected into the configuration. All methods of a Manager must be called only once and have an expected sequence:

1. NewManager to create a new instance; 2. Resolve to inject the data from config sources into a configuration; 3. WatchForUpdate in a goroutine to wait for configuration updates; 4. WaitForWatcher to wait until the watchers are in place; 5. Close to close the instance;

The current syntax to reference a config source in a YAML is provisional. Currently single-line:

param_to_be_retrieved: $<cfgSrcName>:<selector>[?<params_url_query_format>]

bracketed single-line:

param_to_be_retrieved: ${<cfgSrcName>:<selector>[?<params_url_query_format>]}

and multi-line are supported:

param_to_be_retrieved: |
  $<cfgSrcName>: <selector>
  [<params_multi_line_YAML>]

The <cfgSrcName> is a name string used to identify the config source instance to be used to retrieve the value.

The <selector> is the mandatory parameter required when retrieving data from a config source.

Not all config sources need the optional parameters, they are used to provide extra control when retrieving and preparing the data to be injected into the configuration.

For single-line format <params_url_query_format> uses the same syntax as URL query parameters. Hypothetical example in a YAML file:

component:

config_field: $file:/etc/secret.bin?binary=true

For multi-line format <params_multi_line_YAML> uses syntax as a YAML inside YAML. Possible usage example in a YAML file:

component:

config_field: |
  $yamltemplate: /etc/log_template.yaml
  logs_path: /var/logs/
  timeout: 10s

Not all config sources need these optional parameters, they are used to provide extra control when retrieving and data to be injected into the configuration.

Assuming a config source named "env" that retrieve environment variables and one named "file" that retrieves contents from individual files, here are some examples:

component:
  # Retrieves the value of the environment variable LOGS_DIR.
  logs_dir: $env:LOGS_DIR

  # Retrieves the value from the file /etc/secret.bin and injects its contents as a []byte.
  bytes_from_file: $file:/etc/secret.bin?binary=true

  # Retrieves the value from the file /etc/text.txt and injects its contents as a string.
  # Hypothetically the "file" config source by default tries to inject the file contents
  # as a string if params doesn't specify that "binary" is true.
  text_from_file: $file:/etc/text.txt

Bracketed single-line should be used when concatenating a suffix to the value retrieved by the config source. Example:

component:
  # Retrieves the value of the environment variable LOGS_DIR and appends /component.log to it.
  log_file_fullname: ${env:LOGS_DIR}/component.log

Environment variables are expanded before passed to the config source when used in the selector or the optional parameters. Example:

component:
  # Retrieves the value from the file text.txt located on the path specified by the environment
  # variable DATA_PATH. The name of the environment variable is the string after the delimiter
  # until the first character different than '_' and non-alpha-numeric.
  text_from_file: $file:$DATA_PATH/text.txt

Since environment variables and config sources both use the '$', with or without brackets, as a prefix for their expansion it is necessary to have a way to distinguish between them. For the non-bracketed syntax the code will peek at the first character other than alpha-numeric and '_' after the '$'. If that character is a ':' it will treat it as a config source and as environment variable otherwise. For example:

component:
  field_0: $PATH:/etc/logs # Injects the data from a config sourced named "PATH" using the selector "/etc/logs".
  field_1: $PATH/etc/logs  # Expands the environment variable "PATH" and adds the suffix "/etc/logs" to it.

So if you need to include an environment followed by ':' the bracketed syntax must be used instead:

component:
  field_0: ${PATH}:/etc/logs # Expands the environment variable "PATH" and adds the suffix ":/etc/logs" to it.

For the bracketed syntax the presence of ':' inside the brackets indicates that code will treat the bracketed contents as a config source. For example:

component:
  field_0: ${file:/var/secret.txt} # Injects the data from a config sourced named "file" using the selector "/var/secret.txt".
  field_1: ${file}:/var/secret.txt # Expands the environment variable "file" and adds the suffix ":/var/secret.txt" to it.

If the character following the '$' is in the set {'*', '#', '$', '@', '!', '?', '-', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9'} the code will consider it to be the name of an environment variable to expand, or config source if followed by ':'. Do not use any of these characters as the first char on the name of a config source or an environment variable (even if allowed by the system) to avoid unexpected results.

func NewManager

func NewManager(_ *configparser.Parser) (*Manager, error)

NewManager creates a new instance of a Manager to be used to inject data from ConfigSource objects into a configuration and watch for updates on the injected data.

func (*Manager) Close

func (m *Manager) Close(ctx context.Context) error

Close terminates the WatchForUpdate function and closes all Session objects used in the configuration. It should be called

func (*Manager) Resolve

func (m *Manager) Resolve(ctx context.Context, parser *configparser.Parser) (*configparser.Parser, error)

Resolve inspects the given config.Parser and resolves all config sources referenced in the configuration, returning a config.Parser fully resolved. This must be called only once per lifetime of a Manager object.

func (*Manager) WaitForWatcher

func (m *Manager) WaitForWatcher()

WaitForWatcher blocks until the watchers used by WatchForUpdate are all ready. This is used to ensure that the watchers are in place before proceeding.

func (*Manager) WatchForUpdate

func (m *Manager) WatchForUpdate() error

WatchForUpdate must watch for updates on any of the values retrieved from config sources and injected into the configuration. Typically this method is launched in a goroutine, the method WaitForWatcher blocks until the WatchForUpdate goroutine is running and ready.