repository·master·Indexed 41 days ago
https://github.com/grammarly/omniconfA Clojure library that separates configuration blueprints (schemas) from values to provide unified, early-validated access to configuration. It supports multiple sources including CLI arguments, environment variables, Java properties, EDN files, and AWS Systems Manager (SSM) Parameter Store. Features include nested options, custom parsers, verifiers, and dynamic reconfiguration via SSM polling.
You can remove an existing Omniconf parameter by setting its corresponding SSM key to the special string value __SSM__UNSET__.
Behavior Notes:
dissoc on the key in the current config map.Omniconf operates on a core distinction between the blueprint and the values:
By separating these, Omniconf can unify disparate sources into a single, verified Clojure data structure. This ensures that all configuration is validated upfront before your application logic executes.
You can inspect all available configuration options and command-line flags for the example project by running the application with the --help flag.
clojure -M -m example.core --helpAdd Omniconf to your Clojure project dependencies via Clojars to begin using it for unified configuration management.
<!-- Add to your deps.edn or project.clj using the latest version from Clojars -->
https://clojars.org/com.grammarly/omniconfTo see Omniconf in action, navigate to the example directory and run the example core module using Clojure. You can pass configuration via environment variables (e.g., OPTION_FROM_SET) and specify required options using the --required-option flag.
OPTION_FROM_SET=foo clojure -M -m example.core --required-option quxOmniconf can use EDN files as a configuration source. The file must contain a map of options to their values. Values can be provided in their native format (e.g., numbers, keywords) or as strings, in which case the Omniconf parser will be called on them.
To handle dynamic filenames, a common pattern is to first call populate-from-cmd to extract a filename from CLI arguments, and then call populate-from-file. Note that populate-from-file will have priority over CLI arguments. If your CLI arguments are idempotent (i.e., they do not use special operations like ^:concat), you can call populate-from-cmd again after the file is loaded to restore CLI priority.
If your EDN files use library-specific reader macros, you can provide data-readers via the *data-readers* binding during the populate-from-file call.
(cfg/populate-from-cmd args) ;; args is a command-line arguments list
(when-let [conf (cfg/get :conf)]
(binding [cfg/*data-readers* {'ig/ref ig/ref 'ig/refset ig/refset}] ; e.g. reader macros used by integrant
(cfg/populate-from-file conf)))Omniconf supports Amazon SSM Parameter Store as a configuration source, which is ideal for managing secrets.
Setup:
You must add the omniconf.ssm dependency to your project.
Usage:
Use omniconf.core/populate-from-ssm with a path argument. This path acts as the root for nested parameters. For example, providing path /prod/myapp/ will map an SSM parameter /prod/myapp/db/password to the Omniconf key [:db :password].
Mapping Strategies:
:ssm-name key in your configuration definition to map a specific Omniconf key to an absolute SSM path. These absolute paths ignore the path argument provided to populate-from-ssm../ prefix in an :ssm-name to indicate the path is relative to the root path provided to populate-from-ssm.;; Implicit mapping
(cfg/define
{:db {:nested {:password {:type :string
:secret true}}}})
(cfg/populate-from-ssm "/prod/myapp/")
;; Explicit absolute mapping
(cfg/define
{:github-token {:type :string
:secret true
:ssm-name "/myteam/github/oauth-token"}})
(cfg/populate-from-ssm "/prod/myapp/")
;; Relative mapping
(cfg/define
{:db {:nested {:password {:type :string
:secret true
:ssm-name "./db-pass"}}}})
(cfg/populate-from-ssm "/prod/myapp/")When setting values from any source (like CLI arguments), you can use special operations to append or merge data instead of overwriting it. These are attached to maps or lists using the ^:concat or ^:merge metadata.
^:concat: Appends the new collection to the existing one.^:merge: Merges the new map into the existing one.$ my-app --emails '^:concat ["user1@corp.org"]' --roles '^:merge {"user1@corp.org" :user}'By default, Omniconf prints errors and the final configuration map to standard output. To redirect this output to a specific logging framework, use cfg/set-logging-fn and provide a function that accepts a vararg of arguments.
(require '[taoensso.timbre :as log])
(cfg/set-logging-fn (fn [& args] (log/info (str/join " " args))))To react to changes in AWS SSM Parameter Store without restarting your application, use populate-from-ssm-continually.
This function polls SSM at a specified interval (in seconds). Omniconf will only report resetting the values that have actually changed.
Warning: The :verifier step is not re-run after fetching updated values from SSM, so ensure your configuration invariants are not broken by dynamic updates.
;; Poll values under /prod/myapp/ prefix every 10 seconds.
(cfg/populate-from-ssm-continually "/prod/myapp/" 10)Call cfg/verify to mark the boundary where configuration is guaranteed to be complete and correct.
verify throws an exception. In non-REPL environments, stacktraces are stripped to show only a clean, human-readable error message.verify pretty-prints the entire configuration map to stdout. Use (cfg/verify :silent true) to suppress this output.(cfg/verify)Use cfg/get to extract values from the verified configuration. You can access nested values using a vector or as varargs.
(cfg/get :hostname) ; Single level
(cfg/get :database :ip) ; Nested via varargs
(cfg/get [:database :ip]) ; Nested via vector(cfg/get :hostname)