Fusebox Fault Tolerance Library

Fusebox is an extremely lightweight fault tolerance library designed for Clojure, ClojureScript, and Babashka. It focuses on simplicity and performance by providing modular resilience patterns without the complexity of heavyweight alternatives.

Key design principles include:

• Fast: Optimized for performance.
• Pure Functions: Prefers pure functions over complex configuration options.
• Modular: You only load the specific resilience patterns you need.
• Sequential Execution: Avoids callback-driven models in favor of sequential execution.
• Simple Configuration: Uses un-nested hashmaps with namespaced keys.
• Minimal Dependencies: Only depends on clojure/tools.logging.

Fusebox performance is measured against Resilience4J using JMH (Java Microbenchmark Harness). Benchmarks are designed to measure the overhead Fusebox adds to an application by comparing a 'Baseline' (a simple CPU-consuming task) against the same task wrapped in Fusebox utilities.

Key benchmarking characteristics:

• Test Case: Each test performs a single call to (org.openjdk.jmh.infra.Blackhole/consumeCPU 100) to prevent JIT optimization from removing the code.
• Concurrency: Tests include both 'serial' (1 thread) and 'parallel' (8 threads) runs to evaluate overhead in optimal throughput scenarios.
• Optimization: Benchmarks are often run with direct-linking enabled to minimize Clojure's wrapping overhead, providing a more accurate comparison of the core logic.

The init function returns a hashmap known as a spec. Specs are standard Clojure hashmaps and can be treated as such: they can be passed around, stored in definitions, registered, or merged with other specs to create complex resilience configurations.

When calling init, you can pass extra keys (like headers or metadata) and Fusebox will merge them without altering them.

;; Merging multiple specs into one configuration
(merge 
  (retry/init {::retry/retry? (fn [n ms ex] (< n 10))})
  (to/init {::to/timeout-ms 500})
  (fallback/init {::fallback/fallback (fn [ex] :default-val!}))
  (rl/init {::rl/bucket-size 10}))

Fusebox utilities are designed to be composable by accepting hashmaps that do not necessarily contain the required configuration keys. If a utility is called with a map that lacks its required keys (or with nil), it acts as a pass-through, executing the provided body as-is.

This pattern allows you to define a general-purpose function wrapped in multiple resilience layers and then selectively 'opt-in' to specific behaviors by merging configuration maps into the request.

(defn http [req]
  (retry/with-retry req
    (rl/with-rate-limit req
      (http/invoke req))))

;; Usage examples:
(http (merge req retry-spec))          ;; Only retry
(http (merge req rate-limit-spec))    ;; Only rate limit
(http (merge req retry-limit-spec rl-spec)) ;; Both

To achieve performance comparable to direct-linked environments (minimizing Clojure wrapping overhead), ensure the following JVM options are used:

• -Dclojure.compiler.direct-linking=true: Enables direct linking to reduce function call overhead.
• -Dfusebox.usePlatformThreads=false: Configures thread usage for Fusebox.
• -XX:-OmitStackTraceInFastThrow: Prevents the JVM from optimizing away stack traces, which is useful for consistent error measurement.

Example JVM options for a high-performance setup:

-XX:-OmitStackTraceInFastThrow -Dfusebox.usePlatformThreads=false -Dclojure.compiler.direct-linking=true

To use Fusebox in your Clojure or ClojureScript project, add the following dependency to your deps.edn file. Fusebox has only one dependency: clojure/tools.logging.

com.potetm/fusebox {:mvn/version "1.0.11"}

Every Fusebox namespace provides an init and shutdown function. Even for stateless utilities like Retry that are essentially maps of pure functions, these functions are provided to:

1. Provide validation on startup.
2. Maintain a uniform interface across all utilities.

You should always call init and shutdown to ensure proper lifecycle management and configuration validation.

A Rate Limiter limits the rate at which your application calls another application. Fusebox implements a Token Bucket algorithm.

To implement a Leaky Bucket, set ::rl/bucket-size to 1 and adjust ::rl/period-ms.

Configuration options:

• ::rl/bucket-size: Integer number of tokens per period.
• ::rl/period-ms: Milliseconds in each period.
• ::rl/wait-timeout-ms: Maximum milliseconds a thread waits for a token.

(require '[com.potetm.fusebox.rate-limit :as rl])

(def rate-limit
  (rl/init {::rl/bucket-size 10
            ::rl/period-ms 1000
            ::rl/wait-timeout-ms 5000}))

(rl/with-rate-limit rate-limit
  (run))