Guardrails

The configuration can be changed to help the signal to noise ratio on failures. If you have heavily instrumented your code with Guardrails, then turning on these two config options will likely give you a clearer picture on failures:

Try the above settings as shown. You can always see the full stack by calling last-failure (which is printed with any failures for convenience). The result is way less noisy, and often sufficient to find the problem. When it’s not, the full stack trace is just a copy/paste away.

There is a a noop namespace that can be used in your build settings to attempt to eliminate all traces of guardrails and dependent code. This will not remove spec dependencies unless you only use spec for guardrails, so do similar tricks for your inclusions of spec namespaces.

See noop.cljc.

Write the function as normal, and put a gspec after the argument list:

arg-specs for variadic arguments are defined as one would expect from standard fspec:

To add an additional condition add | after either the argument specs (just before =>) or return value spec and supply a lambda that uses the symbol names from the argument list (and % for return value).

The ? macro can be used as a shorthand for s/nilable:

Nested gspecs are defined using the exact same syntax:

In the rare cases when a nilable gspec is needed ? is put in a vector rather than a list:

Credit: The above documentation was largely taken from Ghostwheel’s documentation.

Clojure Spec forces you to use a shared global registry, and carefully ensure that your keywords are qualified and do not collide with others.

Malli does have a default registry, but it is not mutable. This lets you to pick registries at will, and allows for more lenient use of "poor" naming because the threat of collision is reduced; however, it makes the writing of function schemas a lot more tedious:

Fortunately, Malli supports mutable registries, so we can provide the convenience of a global registry and dramatically reduce the boilerplate.

The mutable Guardrails registry is initiated with the exact content of the default Malli registry, and is held in the com.fulcrologic.guardrails.malli.registry namespace, which also includes functions that you can use to directly add your own schema to it. You’ll need to do this for any qualified keywords you want to use in `>defn`s that leverage Malli. For example you can merge in some other schema maps with:

The com.fulcrologic.guardrails.malli.core namespace also has a convenient >def that is like the Clojure Spec def, in that it will register a schema under a qualified keyword for you:

Guardrails is disabled by default, emitting exactly what a plain defn would until you explicitly turn it on, which is done via a JVM option. We chose this path because it is highly effective at preventing its accidental enabling in production, which could cause huge performance impacts.

The JVM option -Dguardrails.enabled=true should be used to turn on guardrails. When not defined >defn will emit exactly what defn would.

You may also enable it in cljs in your shadow-cljs config (see Configuration…​adding even an empty config map will enable it).

The default config goes in the root of the project as guardrails.edn:

You can override the config file name using JVM option -Dguardrails.config=filename. In your shadow-cljs config file you can override settings via the [:compiler-options :external-config :guardrails] config path of a build:

In version 1.2.0 and above you can tune Guardrails to limit the number of times a function is checked per second. This can have a huge performance benefit for functions that are called in loops and possibly involve complex and expensive checks.

The limit can be applied globally, to a namespace, or even to a function (recommended), by setting :guardrails/mcps to an integer. Like most other options, you can place it in the global guardrails.edn, the compiler config, the metadata of a namespace, or in the attribute map of a >defn. For example:

The performance boost from this setting can be dramatic. The Fulcrologic Statecharts library uses Guardrails extensively for internal function checks, and without an MCPS limit some state changes can take human-perceptible amounts of time (like seconds). With it applied the performance impact returns to a virtually unnoticeable level. Measurements on this particular library indicate that each check takes around 20 microseconds, but the overhead of the max-calls-per-second is only 20 or so nanoseconds (on an M1 Max Mac Studio). So, when a calculation ends up causing 100k+ checks (remember there is a check for each arg, and one for the return value) enabling MCPS makes things run literally 1000x faster.

Here’s that same set of 8 tests we showed earlier, but with MCPS set to 100 the Guardrails overhead is reduced to only a few milliseconds! In other words, the non-exhaustive checking makes it appear as if guardrails isn’t even there. Since it is very common to have just a handful of heavily called functions, dropping each of their check counts to 100 means that you’re more likely to only run a few thousand checks in total.

Of course, the downside is that you are no longer getting rigorous data flow checking, but for functions that are called heavily this is an acceptable trade-off, since the probability of detecting some kind of problem can be tuned as you see fit.

The throttling always checks the "leading edge" first; from there it tracks a counter, and uses the high resolution timer to calculate the current number of checks per second that have been done. If that exceeds the set limit, the check is skipped (and the time will change, but not the check count), so after enough time has elapsed, more checks will happen. This has the tendency to "spread out" the checks over time, but of course even high resolution timers are going to give you a lot of jitter at a high call frequency.

Version 1.2.0 also includes the ability to turn checks completely on or off, including at runtime, on a wide or granular level, such as for a namespace or even a function, both in CLJ and CLJS. The functions for controlling this are in com.fulcrologic.guardrails.config:

Most libraries have a main surface API, and then a bunch of internal functions. It is useful to instrument all of these with Guardrails in order to get the benefits of documentation, validation during development, and verification while testing.

Unfortunately, this can have a huge performance impact on downstream consumers of your library that also use Guardrails. It makes sense that a library author should indicate which functions comprise the public API (and should be checked by downstream users), and which are considered more internal and should only be checked when the author is working on the library itself.

Library authors (and application authors as well) can include a file at the top level of their classpath (e.g. src or resources folder, usually) with the special name guardrails-export.edn which contains a config map that can exclude a set of namespaces from ALL checks. To get the checking config at runtime, the >defn functions in those namespaces will only run a simple check on a volatile, so setting these exclusions returns things to pretty much full performance (~= no Guardrails used at all).

For example, src/main/guardrails-export.edn in the Fulcrologic statecharts library looks something like this:

Remember, this goes in a specially-named file, not in the primary guardrails configuration file, since these are meant to be seen by downstream consumers (like data_readers.clj).

A quick implementation note: In order to make this work in Clojurescript a macro must run that can read the JVM classpath, and compile all the exclusions found in on-disk (and in JAR files) into a runtime set. The same happens in Clojure (though in CLJ you can read the fs again at any time).

The set of exclusions found in export files at load time is what reset-exclusions! will restore if you have dynamically changed the exclusions at runtime. Basically this load-time set is kept in a var for exactly this reason since CLJS cannot re-trigger a classpath scan.