Skip to content

Latest commit

 

History

History
98 lines (69 loc) · 3.32 KB

README.md

File metadata and controls

98 lines (69 loc) · 3.32 KB
Raw

ConfigSmuggler

-Build Status -Docs -Hex.pm Version

ConfigSmuggler is a library for converting Elixir-style configuration statements to and from string-encoded key/value pairs.

Elixir (and Erlang)'s configuration system is somewhat richer than naïve environment variables, i.e., System.get_env/1-style key/value configs alone can capture.

Configs in Elixir are namespaced by app, can be arbitrarily nested, and contain Elixir-native data types like atoms, keyword lists, etc.

ConfigSmuggler provides a bridge between Elixir applications and key/value configuration stores, especially those available at runtime. It makes it dead-simple to use platform-agnostic configuration systems with Elixir services.

WARNING!

The functions in ConfigSmuggler are not suitable for use on untrusted inputs! Code is evaled, atoms are created, etc.

Configs are considered privileged inputs, so don't worry about using ConfigSmuggler for its intended purpose. But please, never let user input anywhere near this module. You've been warned.

Example

iex> encoded_configs = %{
...>   # imagine you fetch this every 60 seconds at runtime
...>   "elixir-logger-level" => ":debug",
...>   "elixir-my_api-MyApi.Endpoint-url-port" => "8888",
...> }
iex> ConfigSmuggler.apply(encoded_configs)
iex> Application.get_env(:logger, :level)
:debug
iex> ConfigSmuggler.encode([my_api: Application.get_all_env(:my_api)])
{:ok, %{"elixir-my_api-MyApi.Endpoint-url-port" => "8888"}}

Installation

Add :config_smuggler to your list of deps in mix.exs:

def deps do
  [
    {:config_smuggler, "~> 0.6.0"}
  ]
end

Documentation

Full documentation and usage examples can be found on hexdocs.pm.

Overview

  • apply/1 applies encoded or decoded configs to the current environment.

  • decode/1 converts an encoded config map into Elixir-native decoded configs, also returning a list of zero or more encoded key/value pairs that could not be decoded.

  • encode/1 converts Elixir-native decoded configs (i.e., a keyword list with app name as key and keyword list of configs as value) into an encoded config map.

  • encode_file/1 converts an entire config.exs-style file (along with all files included with Mix.Config.import_config/1) into an encoded config map.

  • encode_statement/1 converts a single config statement from a config.exs-style file into an encoded config map.

Encoding Scheme

The encoded key begins with elixir and is a hyphen-separated "path" of atoms and modules leading to the config value we wish to set.

The value is any valid Elixir term, encoded using normal Elixir syntax.

Encoding is performed by Kernel.inspect/2. Decoding is performed by Code.eval_string/1 and String.to_atom/1.

Authorship and License

Copyright 2019-2021, Appcues, Inc.

ConfigSmuggler is released under the MIT License.