Liking cljdoc? Tell your friends :D

Envoy

CircleCI envoy cljdoc

A Clojure library compatible with environ which adds tracking of which environment variables are referenced, whitelisting, descriptions, and more!

Installation

Library releases are published on Clojars. To use the latest version with Leiningen, add the following to your project dependencies:

Clojars Project

Usage

A quick overview of envoy usage:

=> (require '[envoy.core :as env :refer [defenv env]])

=> (defenv :http-port
     "TCP port to run the HTTP server on."
     :type :integer)

; Look up the declared variable, get an int back:
=> (env :http-port)
8080

; Envoy records variable access:
=> @env/accesses
{:http-port 1}

; Try an undeclared environment variable:
=> (env :user)
; WARNING: Access to undeclared env variable :user
"pjfry"

; The warning was logged because of the behavior setting:
=> (envoy.check/behaviors :undeclared-access)
:warn

; We can also set it to be stricter:
=> (envoy.check/set-behavior! :undeclared-access :abort)

=> (:foo env)
; ExceptionInfo Access to undeclared env variable :foo  clojure.core/ex-info

; Overrides have a behavior setting too:
=> (envoy.check/behaviors :undeclared-override)
:warn

=> (assoc env :foo "bar")
; WARNING: Overriding undeclared env variable :foo
{:foo "bar", :http-port ...}

; Variables can have :missing behavior for situations where the var must not
; resolve to nil:
=> (defenv :secret-key
     "Essential for accessing the data!"
     :missing :warn)

; Calling without a default value triggers:
=> (env :secret-key)
; WARNING: Access to env variable :secret-key which has no value
nil

; Providing a default is okay though:
=> (env :secret-key "53CR37")
"53CR37"

; Still watching all those accesses!
=> @env/accesses
{:http-port 1
 :user 1
 :foo 1
 :secret-key 2}

; Need to change a value from the REPL, but don't want to restart?
=> (env/set-env! :http-port "8085")
=> (env :http-port)
8085

Linting

If you're using lein-env or boot-env to pass environment configuration from your build tool to the process, you can use the -main function in envoy.tools to check that you're not providing values for any undeclared variables. To run the lint task, use:

lein run -m envoy.tools lint [namespace ...]

Any namespaces provided will be loaded before the check runs, in case you need to pull in variable definitions. Typically, you should provide the top-level namespace with the -main entry point into the code.

Reporting

Similarly, you can use the tools namespace to print out a report of the variable definitions known to envoy.

lein run -m envoy.tools report [namespace ...]

This will give you a table like the following:

| Name                 | Type    | Declaration             | Description                         |
|--------------------- | ------- | ------------------------| ------------------------------------|
| :secret-key          | string  | example.data.crypto:187 | Essential for accessing the data!   |
| :http-port           | integer | example.http.server:22  | TCP port to run the HTTP server on. |

The table is in Github-compatible Markdown to make it easy to paste into documentation.

Configuration

Variable Definitions

Variables can be declared using the defenv macro or its helper function declare-env-var!. Definitions can have the following attributes:

AttributeDefinition
:nsNamespace the variable was defined in.
:lineLine number of the definition in the source file.
:descriptionHuman-readable description of the variable.
:typeValue type to parse the variable as. See below.
:defaultDefault value, cannot be set with :missing and must match :type.
:missingBehavior if the variable is accessed with no configured value.

The first three are added automatically as part of the defenv macro.

Value Types

By default, all variables are treated like :string types, which directly reads the value from the environment. Other types apply parsing functions to the values:

TypeDefinition
:stringNormal string variable.
:keywordParse the value as a keyword (without the leading colon).
:booleanConverts 'bool-esque' values such as "" "0", "f", "no", and so on to false and everything else to true.
:integerParse the value as an integer.
:decimalParse the value as a floating point number.
:listTreats the value as a comma-separated list of strings.

Behaviors

Envoy supports behavior settings which control what happens in various situations. There are a few different behaviors:

BehaviorTypeTrigger
undeclared-accessglobalAn undeclared variable is looked up in the environment map.
undeclared-overrideglobalAn undeclared variable is associated into the environment map.
undeclared-configglobalAn environment file provides a value for an undeclared variable.
missing-accessvariableA variable is accessed without a default and is not present in the environment.

All behavior options support the following values:

SettingDescription
nilNo behavior.
:warnLog a warning.
:abortThrow an exception.

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for rights and restrictions.

Can you improve this documentation? These fine people already did:
Greg Look & Colin Lappala
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close