@c3exchange/simple-config

Simple-Config

A simple application configuration library.

Installation and usage

Installation

Run the following command in your NodeJS project's directory.

npm i @c3exchange/simple-config

Sample code

1. First define the configuration variables you expect. You can specify the type of variable and some constraints. For example:

const variableDefs: Variable[] = [
	StringVar.define('DATABASE_HOST').minLength(1).maxLength(256).validator((value: string, name: string): string => {
		if (ipV4AddressRegex.test(value) || hostnameRegex.test(value)) {
			return value;
		}
		throw new Error('Variable "' + name + '" is not an IPv4 address nor a host name.');
	}),
	NumberVar.define('DATABASE_PORT').min(1).max(65535),
	BooleanVar.define('DATABASE_USE_SSL'),
	EnumVar.define('DATABASE_TYPE').allowed(['mysql', 'postgresql', 'mongodb'])
];

2. At program startup, try to load them from process environment variables and/or Hashicorp Vault secrets store.

try {
	const settings = await load({
		vars: variableDefs
	});
	// ....
}
catch (err: any) {
	// ....
}

Variable types

StringVar

Define a string variable using StringVar.define("{variable-name}").

The available constraints and options are:

Name	Description
minLength	Specifies the minimum length.
maxLength	Specifies the maximum length.
validator	Specifies a custom validator callback. After performing your desired checks, the validator function can return a modified value.

NumberVar

Define a numeric variable using NumberVar.define("{variable-name}").

The available constraints and options are:

Name	Description
min	Specifies the minimum value.
max	Specifies the maximum value.
musBeInt	Indicates if the number must be an integer value or can be float.
validator	Specifies a custom validator callback. After performing your desired checks, the validator function can return a modified value.

EnumVar

Define a string variable that only allows one of a set of values using EnumVar.define("{variable-name}").

The available constraint is:

Name	Description
allowed	An array of allowed values, case insensitive. The value is transformed to uppercase when processed.

BooleanVar

Define a boolean variable using BooleanVar.define("{variable-name}").

The case-insensitive values 1, Y, yes, on, t and true resolves to true and the values 0, N, no, off, f and false resolves to false.

Additional common options

Name	Description
required	Raises an exception if the variable is not found unless a `default`` value is assigned.
default	Sets a default value if the variable is not defined.

Loader options

The load function accepts some configuration options that established the load behavior. By default, the library will attempt to load and merge variables in the following order:

1. From Vault, if access is allowed and a the environment variable containing the url is present.
2. From the process environment.

Name	Description
vars	An array of `Variable`` objects that defines the configuration settings to parse.
envVarsOverride	Specifies if the values readed from Vault can be overriden with values stored in the process environment.
modifyEnvVars	The load function returns an object with the parsed values. By enabling this setting, it will also set/overwrite the process' environment variables with stringified versions of the those values. Defaults to true.
vaultOpts	Customizes Vault access behavior. See below for details.

Vault options:

Name	Description
disable	Skip the attempt to load variables from Vault.
envVar	Sets what environment variable name may contain the Vault URL. Defaults to VAULT_URL.
caCertEnvVar (1)	Sets what environment variable name may contain the filename of the certificate autority file. Defaults to VAULT_SSL_CACERT.
certEnvVar (1) (2)	Sets what environment variable name may contain the filename of the client certificate file. Defaults to VAULT_SSL_CLIENT_CERT.
keyEnvVar (1) (2)	Sets what environment variable name may contain the filename of the client private key file. Defaults to VAULT_SSL_CLIENT_KEY.

1. Used only when accesing Vault with HTTPS.
2. Define both variables or none. You cannot define just one of them.

Hashicorp Vault setup and URL format

The document folder contains instructions on how to configure Hashicorp Vault for different authentication methods like AppRole, AWS using IAM roles and Kubernetes.

The URL must have the following format: {protocol}://{vault-host:vault-port}?{query-parameters}

Where protocol can be http or https. vault-host and, optionally, vault-port indicates the location of Vault server. At last, query-parameters are:

Parameter	Description
method	Can be iam, approle or k8s. The loader tries to auto-detect the authorization method if not specified.
mountPath	Sets the authentication mount path. Defaults to aws, approle or kubernetes.
path	A full path where secrets are stored. For example: /secret/data/my-app. See notes below.
roleName	Specifies the role name to use. Only valid for iam and k8s authentication methods.
roleId & secretId	Specifies the role and secret ids. Only valid for the approle authentication method.
timeout	Establishes a query timeout. Defaults to 10 seconds.
allowUntrusted	If set to true, invalid or expired HTTPS server certificates are ignored.

Remember to do escape encoding when specifying query parameters.

NOTES for the path parameter

• If multiple path query parameters are specified, they are read in order. If duplicated settings are found in more than one location, the lastest will be used.
• The path route may vary depending on the secrets engine you are accessing. Check Vault documentation.

License

MIT