API Reference

Figgy.FigSource

Abstract type for all concrete config subtypes. The interface for FigSource includes: * T <: Figgy.FigSource: must subtype Figgy.FigSource * Figgy.load(::T) -> key-value iterator: return a key-value iterator for config source T Each "key-value" is an object x that can be indexed like: x[1] -> key and x[2] -> value Examples include Pair, Tuple{K, V}, Vector of length 2, etc. Keys should be String type, or will be converted to such via Figgy.load!. Values can be any type, though caution is advised as many config sources only support loading String => String key-value pairs. Figgy.load is called for each source when users call Figgy.load!(::Figgy.Store, sources...) to retrieve the key-value config items to load in the store.

Figgy.load(::Figgy.FigSource) -> key-value iterator

Required function of the Figgy.FigSource interface. See the docs for Figgy.FigSource for details.

Figgy.NamedSource(name)

A generic config source that has a name. Used when generic objects (Dict, Vector of Pairs) are passed to Figgy.load!, but a name can be provided for the specific set of configs.

Figgy.ObjectSource

A generic, unnamed config source where key-value pairs are provided directly from an object, with no additional information to identify the config source.

Figgy.Fig(key, values, sources)

Represents a unique config item key and its history of values from various sources. Used by Figgy.Store to track config items.

Figgy.Store()

A threadsafe config store. Tracks config item history as they are updated over time. Configs are loaded by calling Figgy.load!(::Figgy.Store, sources...), where sources is a list of Figgy.FigSource objects, including Figgy.ProgramArguments, Figgy.EnvironmentVariables, Figgy.IniFile, Figgy.JsonObject, Figgy.XmlObject, etc. Loading directly from Dict, NamedTuple, or Pair{String, String} is also allowed. See Figgy.load! for more details.

Figgy.load!(store::Store, sources...; name::String="", log::Bool=true)

Load config items from sources into store. With in a single call to load!, it is assumed that sources are ordered by priority, with the highest priority source first. That means that if a config item is found, it will be ignored from any subsequent sources. The sources arguments can be any official Figgy.FigSource object, like Figgy.ProgramArguments, Figgy.EnvironmentVariables, Figgy.IniFile, Figgy.JsonObject, Figgy.XmlObject, etc. or a generic key-value-producer object, like Dict, NamedTuple, or Pair. For these generic objects, a name can be provided to identify the config source via the name keyword argument.

Note: each call to Figgy.load! will gather all unique config items from sources and load them all, meaning config items already present in the store will be "updated" (though their history preserved).

By default, each config item loaded into the store is logged via an @info log message; to disable this logging, pass log=false.

Keys for sources are expected to be String and will be converted to such if not already. Key uniqueness is then determined by exact string comparison (==).

See Figgy.kmap and Figgy.select for helper functions to transform key names or filter out keys prior to loading.

Figgy.kmap(source, mappings; select::Bool=false)

Allows lazily transforming keys of a Figgy.FigSource object. Source is any official Figgy.FigSource object, or a generic key-value-producer object, like Dict, NamedTuple, or Pair. Mappings can be a one of the following:

• a Function that takes a key and returns a new key; applies to all keys in source
  • a Dict with keys of String and values of:
    • a String that is the new key
    • a Function that takes a key and returns a new key; only applies to the matched key in source

Common use-cases for Figgy.kmap include normalizing environment variable names like AWS_PROFILE and program arguments like --profile to a common config name like aws_profile.

The select keyword argument indicates that only provided key mappings should be "selected" from the config source, thus combining the functionaltiy of Figgy.select.

Figgy.select(source, keys)

Allows filtering keys of a Figgy.FigSource object. Source is any official Figgy.FigSource object, or a generic key-value-producer object, like Dict, NamedTuple, or Pair. keys can be a one of the following:

• a Function that takes a key and returns a Bool; applies to all keys in source
• a Set of String keys that are the only keys to be included in the result

Figgy.ProgramArguments(requiredArgs...)

A FigSource that parses command line arguments to a Julia program. Specifically, arguments of the following form are parsed:

• --key=value, long-form argument that is parsed as key => value
• -x, "flag" argument that is parsed as x => "true"
• -abc, multiple flag arguments that result in multiple key value pairs of the form a => "true", b => "true", c => "true"
• -x val, required argument that is parsed as x => val
• -xval, required argument that is parsed as x => "val" only when "x" is passed as a requiredArgs like ProgramArguments("x")

To transform program argument keys, see Figgy.kmap.

Figgy.EnvironmentVariables()

A FigSource that parses environment variables for config. Specifically, it takes the current contents of the ENV global variable for key-value pairs. Note that environment variable names will be preserved as-is; to transform/normalize the names, see Figgy.kmap.

Figgy.IniFile(file, section)

A FigSource that parses an INI file. The file argument can be a path to the INI file, or a String that is the contents of the INI file. The section argument is required and specifies the INI file section that will be parsed for key-value pairs.

Figgy.JsonObject(json, path="")

A FigSource for parsing simple json as key-value pairs. The json argument must be a String which is itself json data, or a Vector{UInt8}. The json is expected to be a json object where the key-values will be considered key-value config pairs. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs. So a json object like:

{
    "k": "v",
    "nested": {
        "level2": {
            "key1": "val1",
            "key2": "val2"
        },
        "key3": "val3"
    }
}

Where we wish to use the key-value pairs of nested.level2 for config, could be parsed like: Figgy.JsonObject(json, "nested.level2").

Figgy.XmlObject(xml, path="")

A FigSource for parsing simple xml as key-value pairs. The xml argument must be a String which is itself xml data, or a Vector{UInt8}. The xml is expected to be a xml object where the key-values will be considered key-value config pairs. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs. So a xml object like:

<root>
    <k>v</k>
    <nested>
        <level2>
            <key1>val1</key1>
            <key2>val2</key2>
        </level2>
        <key3>val3</key3>
    </nested>
</root>

Where we wish to use the key-value pairs of nested.level2 for config, could be parsed like: Figgy.XmlObject(xml, "nested.level2").

Figgy.TomlObject(file, path="")

A FigSource for loading config key-value pairs from .toml files. The file argument can be a path to a .toml file, or a String of which the contents is toml data directly. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs.

Figgy.encrypt(secret, plaintext; kwargs...)

Encrypt a string or byte vector with Figgy's OpenSSL-backed password-based config-value encryption. This is the public convenience wrapper for Figgy.Crypt.encrypt.

Figgy.decrypt(secret, encrypted; kwargs...)
Figgy.decrypt(keys::AbstractDict, encrypted; kwargs...)

Decrypt an encrypted config value and return UTF-8 text. This is the public convenience wrapper for Figgy.Crypt.decrypt.

Figgy.Crypt

OpenSSL-backed helpers for password-based config-value encryption.

New Figgy-managed values should use the default AES-256-GCM profile, which produces self-describing ENC[figgy-v1](...) envelopes. Interoperability profiles are available through configuration objects rather than separate encrypt/decrypt aliases.

Figgy.Crypt.CipherConfig(; kwargs...)

Password-based encryption configuration used by Figgy.Crypt.encrypt and Figgy.Crypt.decrypt.

The default config uses PBKDF2-HMAC-SHA256 and AES-256-GCM with a self-describing ENC[figgy-v1](...) envelope. CBC configs are supported for interoperability with existing ecosystems, but new Figgy-managed values should prefer the default authenticated encryption profile.

Figgy.Crypt.Envelope

Parsed encrypted-value wrapper returned by Figgy.Crypt.parse_envelope. format is :figgy_v1, :enc, or :bare; key_id is populated only for Figgy's versioned envelope when one was provided at encryption time.

Figgy.Crypt.DEFAULT_CONFIG

Default password-based encryption profile: PBKDF2-HMAC-SHA256 with 210,000 iterations, a 16-byte salt, AES-256-GCM, a 12-byte IV, and a 16-byte authentication tag in Figgy's self-describing v1 envelope.

Figgy.Crypt.jasypt_config(; iterations=50_000)

Return a CipherConfig compatible with Jasypt's PBEWITHHMACSHA512ANDAES_256 convention: PBKDF2-HMAC-SHA512, a 16-byte salt, a 16-byte random IV, AES-256-CBC with PKCS padding, and a base64(salt || iv || ciphertext) payload.

This profile exists for interoperability. Prefer the default AES-GCM config for new Figgy-managed secrets.

Figgy.Crypt.encrypt(secret, plaintext; config=Figgy.Crypt.DEFAULT_CONFIG, key_id=nothing, aad=UInt8[], rng=Random.default_rng(), salt=nothing, iv=nothing, wrap=nothing)

Encrypt a string or byte vector with a password/secret string or byte vector.

The default returns a self-describing ENC[figgy-v1](...) value. Passing key_id stores an explicit key identifier in the envelope so decryptors can route to the correct key without trying keys by exception.

Figgy.Crypt.encrypt_bytes(secret, plaintext; kwargs...)

Byte-vector variant of Figgy.Crypt.encrypt.

Figgy.Crypt.decrypt(secret, encrypted; config=nothing, aad=UInt8[])
Figgy.Crypt.decrypt(keys::AbstractDict, encrypted; config=nothing, aad=UInt8[])

Decrypt an encrypted string and return UTF-8 text. When a dictionary of keys is provided, the Figgy envelope must contain a key_id; the matching dictionary entry is selected before decrypting.

Figgy.Crypt.decrypt_bytes(secret, encrypted; config=nothing, aad=UInt8[])

Decrypt an encrypted string and return raw bytes.

Figgy.Crypt.derive_key(secret, salt; config=Figgy.Crypt.DEFAULT_CONFIG)

Derive an encryption key using OpenSSL's PKCS5_PBKDF2_HMAC.

Figgy.Crypt.parse_envelope(encrypted) -> Figgy.Crypt.Envelope

Parse ENC[figgy-v1](...), ENC[figgy-v1:key-id](...), ENC(...), or bare Base64 encrypted values. Bare values are returned with format == :bare.

Figgy.Crypt.is_encrypted(value) -> Bool

Return whether a string looks like an ENC(...) or ENC[...](...) value.