samconf¶

This library has the following main tasks:

Manage program configurations through a centralized configuration API.
Merge arbitrary sources for configuration like Json and/or Xml, program parameters, environment and compile/buildin configurations.
Transparently verify signed configurations

General Structure¶

The configuration is held in a tree structure. Each tree node is of type samconfConfig_t. A node can hold a value of a certain type defined by its type attribute or in case of type object and type array it can hold children. For a detailed type description have a look at the class diagram.

configuration class diagram

This structure allows a hierarchical ordering of configuration options. The following diagram shows an example configuration.

Example configuration tree

Each node can be addressed by a xpath like notation. The option SyslogPath of the Syslog-Scanner is for example /elos/scanner/syslog/SyslogPath.

From Configuration Source to Configuration¶

The samconf library shall support different types of sources for configuration options and provided a unified interface to access them. The following diagram shows the life cycle of a configuration source.

configuration source life cycle

A configuration is created by defining a location as file path, the type is determined form the file.
A configuration is loaded by a dedicated backend implementation.
A configuration backend can tell if a source pointed to by given path is valid
A configuration can never change after initialization
A configuration can not change the underling source of information.

The data format for a configuration source type is limited by the following requirements:

a single options must be transferable into a key value based structure
provide hierarchical structure information for each key value pair to construct a path

This means it must be possible to implement a dedicated loader that is capable of transforming the plain data a configuration source is pointing to into a samconfConfig_t tree.

The process of loading a configuration from and building a configuration tree from an arbitrary configuration source shall be done by the ConfigurationFactory component.

The Configuration Factory¶

The Configuration Factory shall provide an interface to abstract the details of creating a samconfConfig_t configuration tree, therefore it shall fullfill the following requirements:

Easy extensibility for new source types (Open/Close principle)
Validation of sources
Statically linked backends
Compile time switches for backends (-DSAMCONF_ENABLE_CONFIG_BACKEND_)

The process to create a configuration source is as follows:

create a Configuration Tree

As the Configuration Factory shall provide the developer with the mechanisms to load, merge and release a configuration tree from various sources, the public API does only define the following three functions.

samconfConfigStatusE_t samconfLoad(const char *location, bool enforceSignature, samconfConfig_t **conf);
samconfConfigStatusE_t samconfMerge(samconfConfig_t **new, samconfConfig_t *conf1, samconfConfig_t *conf2);
samconfConfigStatusE_t samconfClear(samconfConfig_t *conf);

To provide implementations for different configuration sources the interface samconfConfigBackend_t shall be implemented as follows:

#define samconfConfigBackendForEach(source, key, value) \
  for (...)

typedef struct samconfConfigBackendOps {
  // List of function pointers
  samconfConfigStatusE_t (*supports)(const char *location, bool *isSupported);
  samconfConfigStatusE_t (*open)(const char *location, samconfConfigBackend_t *backend);
  samconfConfigStatusE_t (*load)(samconfConfigBackend_t *backend, bool isSigned, samconfConfig_t **config);
  samconfConfigStatusE_t (*close)(samconfConfigBackend_t *backend);
} samconfConfigBackendOps_t;

typedef struct samconfConfigBackend {
  void *originalHandle; // eg. File descriptor
  void *backendHandle; // internal json object
  samconfConfigBackendOps_t *ops; // Config operations
} samconfConfigBackend_t;

An implementation for a specific configuration source shall implement the above functions, which can then be used by the Configuration Factory to parse a configuration.

Types of Configuration Sources¶

The following sources for configuration options shall be provided:

Parameter list
Environment variables
JSON file
Compiled in configuration

Parameter Source¶

A configuration option shall be passed to a program as parameter. The parsing and the format of such parameter shall be follow the format accepted by getopt libc function. The general processing rule shall be as follows:

if a parameter is invalid or unknown return an error
if parameter is valid insert it into a configuration tree

To integrate parameter as configuration options into a samconfConfig_t tree, it requires a mapping or strategy on how to place the parameter in the config tree. There two possible solutions:

A) the parameter name must be structured like a full qualified name --app.categoryA.itemA.subItem "the value of a configuration option" B) a set of parameter is mapped statically in the code to a full qualified name by the ParameterConfigLoader for example.

$> app -p 42 --ItemB

this will results in two options (key value pairs):

root.categoryA.itemA = 42
root.categoryB.itemB = true

In either case the following rules shall be applied to set the different types of values:

Boolean¶

if a parameter is specified the corresponding option value shall be true otherwise false
if a parameter is set explicitly to true or false the corresponding value shall be used for the corresponding option

-/--itemB  => /root/categoryB/itemB = true
-/--itemB=false  => root/categoryB/itemB = false

Integer¶

If a parameter provides an integer value it shall be converted to the configuration option type and used.

-/--itemA=42  => /root/categoryA/itemA = 42
-/--itemA 42  => /root/categoryA/itemA = 42

Real¶

If a parameter provides a real value it shall be converted to the configuration option type and used.

-/--itemA=42.3  => /root/categoryA/itemA = 42.3
-/--itemA 42.3  => /root/categoryA/itemA = 42.3

String¶

If a parameter provides a string value it shall be used.

-/--subItem="the value of a configuration option"  => /root/categoryA/itemA/subItem = "the value of a configuration option"
-/--subItem "the value of a configuration option"  => /root/categoryA/itemA/subItem = "the value of a configuration option"

Environment Source¶

To load a configuration from an environment into a samconfConfig_t tree, the Option path must be encoded in the environment variable name. Given a config path like /myApp/network/port would translate to myApp_network_port.

An example environment config could then look like:

myApp_network_port = 33333
myApp_network_interface = "0.0.0.0"
myApp_network_enable = true

Environment variables can have the following types:

Boolean¶

If a environment parameter contains the string true or false the corresponding value of SAMCONF_CONFIG_VALUE_BOOLEAN shall be used. The strings true or false are accepted and mapped case insensitive. Surrounding white spaces shall be stripped.