Aero

(aero isednreally,ok?)

A small library for explicit, intentful configuration.

Installation

Add the following dependency to yourproject.cljfile

Getting started

Create a file calledconfig.edncontaining the following

{:greeting"World!"}

In your code, read the configuration like this

(require'[aero.core:refer[read-config]])
(read-config"config.edn")

or to read from the classpath, like this

(read-config(clojure.java.io/resource"config.edn"))

Keep in mind that even though(read-config "config.edn" )will work in your Repl and when running tests, it's very likely to catastrophically fail if you run your application from the generated.jarfile.

So to avoid surprises it's better to always useio/resourcewhich works in all scenarios.

Design goals

Explicit and intentional

Configuration should be explicit, intentful, obvious, but not clever. It should be easy to understand what the config is, and where it is declared.

Determining config in stressful situations, for example, while diagnosing the cause of a production issue, should not be a wild goose chase.

Avoid duplication...

Config files are often duplicated on a per-environment basis, attracting all the problems associated with duplication.

... but allow for difference

When looking at a config file, a reader will usually ask: "Does the value differ from the default, and if so how?". It's clearly better to answer that question in-place.

Allow config to be stored in the source code repository...

When config is left out of source code control it festers and diverges from the code base. Better to keep a single config file in source code control.

... while hiding passwords

While it is good to keep config in source code control, it is important to ensure passwords and other sensitive information remain hidden.

Config should be data

While it can be very flexible to have 'clever' configuration 'programs', it can beunsafe,lead to exploits and compromise security. Configuration is a key input to a program. Always use data for configuration andavoid turing-completelanguages!

Use environment variables sparingly

We suggest using environment variables judiciously and sparingly, the way Unix intends, and notgo mad.After all, we want to keep configuration explicit and intentional.

Also, see these argumentsagainst.

Use edn

Fortunately for Clojure developers like us, most of the tech to read configuration in a safe, secure and extensible way already exists in the Clojure core library (EDN).

Tag literals

Aero provides a small library of tag literals.

env

Use#envto reference an environment variable.

{:database-uri#env DATABASE_URI}

It is considered bad practice to use environment variables for passwords and other confidential information. This is because it is very easy to leak a process's environment (e.g. viaps e -for to your application monitoring tool). Instead you should use#include- seehere.

envf

Use#envfto insert environment variables into a formatted string.

{:database#envf ["protocol://%s:%s"DATABASE_HOST DATABASE_NAME]}

or

Use#orwhen you want to provide a list of possibilities, perhaps with a default at the end.

{:port#or [#env PORT8080]}

join

#joinis used as a string builder, useful in a variety of situations such as building up connection strings.

{:url#join ["jdbc:postgresql://psq-prod/prod?user="
#env PROD_USER
"&password="
#env PROD_PASSWD]}

profile

Use profile as a kind of reader conditional.

#profileexpects a map, from which it extracts the entry corresponding to theprofile.

{:webserver
{:port#profile {:default8000
:dev8001
:test8002}}}

You can specify the value ofprofilewhen you read the config.

(read-config"config.edn"{:profile:dev})

which will return

{:webserver
{:port8001}}

(#profilereplaces the now deprecated#cond,found in previous versions of Aero)

hostname

Use when config has to differ from host to host, using the hostname. You can specify multiple hostnames in a set.

{:webserver
{:port#hostname {"stone"8080
#{"emerald""diamond"}8081
:default8082}}}

long, double, keyword, boolean

Use to parse aStringvalue into aLong,Double,keyword or boolean.

{:debug#boolean #or [#env DEBUG"true"]
:webserver
{:port#long #or [#env PORT8080]
:factor#double #env FACTOR
:mode#keyword #env MODE}}

user

#useris like#hostname,but switches on the user.

include

Use to include another config file. This allows you to split your config files to prevent them from getting too large.

{:webserver#include"webserver.edn"
:analytics#include"analytics.edn"}

NOTE: By default#includewill attempt to resolve the file to be includedrelativeto the config file it's being included from. (this won't work for jars)

You can provide your own custom resolver to replace the default behaviour or use one that aero provides (resource-resolver,root-resolver). For example

(require'[aero.core:refer(read-configresource-resolver)])
(read-config"config.edn"{:resolverresource-resolver})

You can also provide a map as a resolver. For example

(read-config"config.edn"{:resolver{"webserver.edn""resources/webserver/config.edn"}})

merge

Merge multiple maps together

#merge [{:foo:bar} {:foo:zip}]

ref

To avoid duplication you can refer to other parts of your configuration file using the#reftag.

The#refvalue should be a vector resolveable byget-in.Take the following config map for example:

{:db-connection"datomic:dynamo://dynamodb"
:webserver
{:db#ref [:db-connection]}
:analytics
{:db#ref [:db-connection]}}

Both:analyticsand:webserverwill have their:dbkeys resolved to"datomic:dynamo://dynamodb"

References are recursive. They can be used in#includefiles.

Define your own

Aero supports user-defined tag literals. Just extend thereadermultimethod.

(defmethodreader'mytag
[{:keys[profile]:asopts} tag value]
(if(=value:favorite)
:chocolate
:vanilla))

Recommended usage patterns, tips and advice

Hide passwords in local private files

Passwords and other confidential information should not be stored in version control, nor be specified in environment variables. One alternative option is to create a private file in the HOME directory that contains only the information that must be kept outside version control (it is good advice that everything else be subject to configuration management via version control).

Here is how this can be achieved:

{:secrets#include #join [#env HOME"/.secrets.edn"]

:aws-secret-access-key
#profile {:test#ref [:secrets:aws-test-key]
:prod#ref [:secrets:aws-prod-key]}}

Use functions to wrap access to your configuration.

Here's some good advice on using Aero in your own programs.

Define a dedicated namespace for config that reads the config and provides functions to access it.

(nsmyproj.config
(:require[aero.core:asaero]))

(defnconfig[profile]
(aero/read-config"dev/config.edn"{:profileprofile}))

(defnwebserver-port[config]
(get-inconfig [:webserver:port]))

This way, you build a simple layer of indirection to insulate the parts of your program that access configuration from the evolving structure of the configuration file. If your configuration structure changes, you only have to change the wrappers, rather than locate and update all the places in your code where configuration is accessed.

Your program should call theconfigfunction, usually with an argument specifying the configuration profile. It then returned value passes the returned value through functions or via lexical scope (possibly components).

Using Aero with Plumatic schema

Aero has frictionless integration withPlumatic Schema.If you wish, specify your configuration schemas and runcheckorvalidateagainst the data returned fromread-config.

Using Aero with components

If you are using Stuart Sierra's componentlibrary, here's how you might integrate Aero.

(nsmyproj.server
(:require[myproj.config:asconfig]))

(defrecordMyServer[config]
Lifecycle
(start[component]
(assoccomponent:server(start-server:port(config/webserver-portconfig))))
(stop[component]
(when-let[server (:servercomponent)] (stop-serverserver))))

(defnnew-server[config]
(->MyServerconfig))

(nsmyproj.system
[com.stuartsierra ponent:ascomponent]
[myproj.server:refer[new-server]])

(defnnew-production-system[]
(let[config (config/config:prod)]
(system-using
(component/system-map:server(new-serverconfig))
{})))

However, another useful pattern you might consider is to keep your system map and configuration map aligned.

For example, imagine you have a config file:

{:listener{:port8080}
:database{:uri"datomic:mem://myapp/dev"}}

Here we create a system as normal but with the key difference that we configure the system map after we have created usingmerge-with merge.This avoids all the boilerplate required in passing config around the various component constructors.

(defrecordListener[database port]
Lifecycle…)

(defnnew-listener[]
(using(map->Listener{}) [:database])

(defrecordDatabase[uri]
Lifecycle…)

(defnnew-database[]
(map->Database{}))

(defnnew-system-map
"Create a configuration-free system"
[]
(system-map
:listener(new-listener)
:database(new-database)))

(defnconfigure[system profile]
(let[config (aero/read-config"config.edn"{:profileprofile})]
(merge-withmerge system config)))

(defnnew-dependency-map[] {})

(defnnew-system
"Create the production system"
[profile]
(->(new-system-map)
(configureprofile)
(system-using(new-dependency-map))))

Also, if you follow the pattern describedhereyou can also ensure accurate configuration is given to each component without having to maintain explicit schemas. This way, you only verify the config that you are actually using.

Feature toggles

Aero is a great way to implementfeature toggles.

Use a single configuration file

If at all possible, try to avoid having lots of configuration files and stick with a single file. That way, you're encouraged to keep configuration down to a minimum. Having a single file is also useful because it can be more easily edited, published, emailed,watchedfor changes. It is generally better to surface complexity than hide it away.

(Alpha) Define macro tag literals

aero. Alpha.coredefines a new experimental API for tagged literals. This API allows you to define tagged literal "macros" similar to macros in Clojure. It is intended for use in creating your own conditional constructs like#profileand#or.

case-like tag literal

The easiest kind of tagged literal to create is a case-like one. A case-like tagged literal is one which takes a map of possible paths to take. An example of this in Aero is#profile.

Here's how you can define your own version of#profile:

(nsmyns
(:require[aero. Alpha.core:asaero. Alpha ]))

(defmethodaero. Alpha/eval-tagged-literal'profile
[tagged-literal opts env ks]
(aero. Alpha /expand-case(:profileopts) tagged-literal opts env ks))

eval-tagged-literalallows you to define macro tagged literals. expand-caseis a function which forms the common behaviour beneath#user,#profile,etc.

Other conditional constructs

#oris very different from#profilein implementation, and doesn't have a convenience function. The source for#orinaero.coreis a good example of doing custom partial expansion from a tagged literal.

The primitives you will need to understand are:aero. Alpha.core/expand,aero. Alpha.core/expand-coll,aero. Alpha.core/expand-scalar. And helpers:aero. Alpha.core/expand-scalar-repeatedly. These vars have docstrings which explain their specific purpose.

All expand-* functions take parametersopts,env,andks. optsare the sameoptsthat are passed toaero.core/read-config. envis a map ofksto their resolved values in the config, being absent from this map means the value is not yet resolved. ksis a vector representing the current key path into the location of this tagged literal.

Your implementation of eval-tagged-literal mustassoctheksintoenvif it is successfully resolved.

References

Aero is built on Clojure'sedn.

Aero is influenced bynomad,but purposely avoids instance, environment and private config.

Acknowledgments

Thanks to the following people for inspiration, contributions, feedback and suggestions.

• Gardner Vickers

Copyright & License

The MIT License (MIT)

Copyright © 2015 JUXT LTD.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software" ), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.