dryewo / squeeze

Library for config coercion

squeeze

A Clojure library for config coercion.

[squeeze "0.3.3"]

Rationale

The Twelve-Factor App recommends to only use environment variables to pass configuration to applications. That means, no files, no web-services that application calls to receive its config, only reading from the environment.

Process environment is platform-independent and immutable.

This brings several challenges:

1. Environment is a flat map (hash, dictionary) from string to string. Configuration values, on the other hand, can be not only strings, but also numbers, booleans, as well as lists and maps of primitive values.
2. Accessing the environment directly is error-prone: if some configuration value is used during program execution, it will only be discovered when it's first read from the environment and we try to convert it from string to something useful. This can be avoided by loading and validating all the configuration when the application starts up.

This library does not:

• Manage multiple sources of configuration, merge them together, track various application profiles etc. Only transformation from String->String to user-defined schema.
• Distribute parts of the application configuration to corresponding components. It does not rely on component, mount or any other state management library.

Examples

All examples assume the following imports:

(ns my-app.core
  (:require [squeeze.core :as squeeze]
            [environ.core :as env]
            [schema.core :as s]))

Simple example:

(def default-config
  {:http-port   8090
   :http-bind   "0.0.0.0"})

(s/defschema Config
  {(s/optional-key :http-port)   s/Int
   (s/optional-key :http-bind)   s/Str
   (s/optional-key :http-public) s/Bool}

(squeeze/coerce-config Config (merge default-config environ/env))

Given the following process environment:

LC_ALL=en_US.UTF-8
LANG=en_US.UTF-8
HTTP_PORT=4200
TERM=xterm-256color
SHELL=/bin/bash

The example would yield the following:

{:http-port 4200
 :http-bind "0.0.0.0"}

1. Unknown keys are removed.
2. Values are coerced to the schema, if possible.

Data structures

Environment variables are perfectly suited for passing big documents in them:

• they are not limited in size
• they can contain arbitrary text characters, including new lines

# whitelist.yaml
- 1.1.1.1
- 2.2.2.2
- 3.3.3.3

When run as:

HTTP_IP_WHITELIST=$(cat http.yaml) java -jar ...

Using schema:

(s/defschema HttpConfig
  {:http-ip-whitelist [s/Str]})
(squeeze/coerce-config HttpConfig environ/env)

Would yield:

{:http-ip-whitelist[squeeze "0.3.3"]}

Helper functions

If you need to get rid of the name prefix, like :http-, use remove-key-prefix:

(squeeze/remove-key-prefix :db- {:db-port 1234})
; => {:port 1234}

In order to remap some keys in a map and only keep the remapped ones, use remap-keys:

(squeeze/remap-keys {:whitelist :http-ip-whitelist} {:http-ip-whitelist[squeeze "0.3.3"] :http-port 8000})
; => {:whitelist[squeeze "0.3.3"]}

Dependencies

Squeeze relies on Prismatic Schema and clj-yaml.

License

Copyright © 2017 Dmitrii Balakhonskii

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

squeeze's Issues

Support literal keyword keys in YAML

;; Works:
(coerce-config {s/Keyword s/Int} "foo: 1") ;; => {:foo 1}
;; Does not work, but should:
(coerce-config {:foo s/Int} "foo: 1")      ;; => {:foo 1}

Coerce numbers into strings

(coerce-config s/Str 1)   ;; => "1"
(coerce-config s/Str 1.1) ;; => "1.1"