feat: add context binding parameter for execute handlers

Author: k13gomez

README.md

@@ -29,16 +29,22 @@ For detailed information on each policy's behavior and configuration options, se
 ```clj
 (require '[failsage.core :as fs])
 
-;; Create a retry policy
+;; Simplest form - no executor needed
+(fs/execute
+  (call-unreliable-service))
+
+;; With a retry policy
 (def retry-policy
   (fs/retry {:max-retries 3
              :delay-ms 100
              :backoff-delay-factor 2.0}))
 
-;; Create an executor with the policy
-(def executor (fs/executor retry-policy))
+;; Pass policy directly - no need to create executor
+(fs/execute retry-policy
+  (call-unreliable-service))
 
-;; Execute with automatic retry on failure
+;; Or create an executor explicitly
+(def executor (fs/executor retry-policy))
 (fs/execute executor
   (call-unreliable-service))
 ```
@@ -54,9 +60,8 @@ For detailed information on each policy's behavior and configuration options, se
              :backoff-max-delay-ms 5000
              :backoff-delay-factor 2.0}))
 
-(def executor (fs/executor retry-policy))
-
-(fs/execute executor
+;; Pass policy directly
+(fs/execute retry-policy
   (http/get "https://api.example.com/data"))
 ```
 
@@ -69,9 +74,8 @@ For detailed information on each policy's behavior and configuration options, se
                        :on-open-fn (fn [e] (log/warn "Circuit breaker opened!"))
                        :on-close-fn (fn [e] (log/info "Circuit breaker closed!"))}))
 
-(def executor (fs/executor circuit-breaker))
-
-(fs/execute executor
+;; Pass policy directly
+(fs/execute circuit-breaker
   (call-flaky-service))
 ```
 
@@ -82,10 +86,8 @@ For detailed information on each policy's behavior and configuration options, se
   (fs/fallback {:result {:status :degraded :data []}
                 :handle-exception Exception}))
 
-(def executor (fs/executor fallback-policy))
-
 ;; Returns fallback value on any exception
-(fs/execute executor
+(fs/execute fallback-policy
   (fetch-user-data user-id))
 ;; => {:status :degraded :data []}
 ```
@@ -97,9 +99,8 @@ For detailed information on each policy's behavior and configuration options, se
   (fs/timeout {:timeout-ms 5000          ;; 5 second timeout
                :interrupt true}))        ;; Interrupt thread on timeout
 
-(def executor (fs/executor timeout-policy))
-
-(fs/execute executor
+;; Pass policy directly
+(fs/execute timeout-policy
   (slow-database-query))
 ```
 
@@ -112,9 +113,8 @@ For detailed information on each policy's behavior and configuration options, se
                     :period-ms 1000
                     :burst true}))
 
-(def executor (fs/executor rate-limiter))
-
-(fs/execute executor
+;; Pass policy directly
+(fs/execute rate-limiter
   (process-request request))
 ```
 
@@ -126,9 +126,8 @@ For detailed information on each policy's behavior and configuration options, se
   (fs/bulkhead {:max-concurrency 10
                 :max-wait-time-ms 1000}))   ;; Wait up to 1 second for permit
 
-(def executor (fs/executor bulkhead-policy))
-
-(fs/execute executor
+;; Pass policy directly
+(fs/execute bulkhead-policy
   (process-task task))
 ```
 
@@ -183,16 +182,54 @@ Failsage integrates with [futurama](https://github.com/k13labs/futurama) for asy
 (require '[failsage.core :as fs])
 (require '[futurama.core :as f])
 
+;; Simplest form - uses default thread pool
+(fs/execute-async
+  (f/async
+    (let [result (f/<!< (async-http-call))]
+      (process-result result))))
+
+;; With a policy
 (def retry-policy (fs/retry {:max-retries 3}))
-(def executor (fs/executor :io retry-policy))  ;; Use :io thread pool
+(fs/execute-async retry-policy
+  (f/async
+    (let [result (f/<!< (async-http-call))]
+      (process-result result))))
 
-;; Returns immediately, executes asynchronously
+;; With explicit executor and thread pool
+(def executor (fs/executor :io retry-policy))  ;; Use :io thread pool
 (fs/execute-async executor
   (f/async
     (let [result (f/<!< (async-http-call))]
       (process-result result))))
 ```
 
+## Accessing Execution Context
+
+You can access execution context information (like attempt count, start time, etc.) by providing a context binding:
+
+```clj
+;; Synchronous execution with context
+(def retry-policy (fs/retry {:max-retries 3}))
+
+(fs/execute retry-policy ctx
+  (let [attempt (.getAttemptCount ctx)
+        start-time (.getStartTime ctx)]
+    (log/info "Attempt" attempt "started at" start-time)
+    (call-service)))
+
+;; Asynchronous execution with context
+(fs/execute-async retry-policy ctx
+  (f/async
+    (log/info "Async attempt" (.getAttemptCount ctx))
+    (f/<!< (async-call-service))))
+```
+
+The context object provides access to:
+- `.getAttemptCount` - Current attempt number (0-indexed)
+- `.getStartTime` - When execution started
+- `.getElapsedTime` - Time elapsed since execution started
+- And more - see [ExecutionContext](https://failsafe.dev/javadoc/core/dev/failsafe/ExecutionContext.html) / [AsyncExecution](https://failsafe.dev/javadoc/core/dev/failsafe/AsyncExecution.html) docs
+
 ## Event Callbacks
 
 All policies support event callbacks for observability:

resources/clj-kondo.exports/failsage/failsage/config.edn

@@ -1 +1,5 @@
-{}
+{:hooks {:analyze-call {failsage.core/execute
+                        hooks.failsage/analyze-execute-macro
+
+                        failsage.core/execute-async
+                        hooks.failsage/analyze-execute-macro}}}

resources/clj-kondo.exports/failsage/failsage/hooks/failsage.clj_kondo

@@ -0,0 +1,17 @@
+(ns hooks.failsage
+  (:require [clj-kondo.hooks-api :as api]))
+
+(defn analyze-execute-macro
+  "analyze execute macro to support optional context binding"
+  [{:keys [:node]}]
+  (let [execute-args (rest (:children node))
+        [executor-or-policy context-binding body] (when (= 3 (count execute-args))
+                                                    execute-args)]
+    (if context-binding
+      {:node (api/list-node
+              (list
+               (api/token-node 'let)
+               (api/vector-node
+                (vector context-binding executor-or-policy))
+               body))}
+      {:node node})))

src/failsage/core.clj

@@ -1,12 +1,14 @@
 (ns failsage.core
   "Defines failsafe policies for handling failures, retries, etc."
   (:require
-   [failsage.impl :as impl])
+   [failsage.impl :as impl]
+   [futurama.core :refer [!<! async]])
   (:import
    [dev.failsafe
+    AsyncExecution
     Bulkhead
     CircuitBreaker
-    Failsafe
+    ExecutionContext
     FailsafeExecutor
     Fallback
     RateLimiter
@@ -499,7 +501,7 @@
       builder)))
 
 (defn executor
-  "Creates a Failsafe instance with the provided policies.
+  "Creates a FailsafeExecutor instance with the provided policies.
 
   Docs: https://failsafe.dev/javadoc/core/dev/failsafe/FailsafeExecutor.html
 
@@ -508,41 +510,53 @@
   If not provided, it will use the currently bound `futurama.core/*thread-pool*` or `:io` pool.
   - `:policies`, `:policy-args` (optional): The policy or policies to use with the FailsafeExecutor.
   If not provided, the executor will treat any exceptions as a failure without any additional error handling."
-  ([]
-   (executor nil nil))
-  ([policies]
-   (executor nil policies))
+  (^FailsafeExecutor []
+   (impl/->executor nil nil))
+  (^FailsafeExecutor [policies]
+   (impl/->executor nil policies))
   (^FailsafeExecutor [pool policies]
-   (let [pool (impl/get-pool pool)
-         policies (impl/get-policy-list policies)]
-     (if (empty? policies)
-       (.with (Failsafe/none) pool)
-       (.with (Failsafe/with policies) pool)))))
+   (impl/->executor pool policies)))
 
 (defmacro execute
-  "Executes the given function with the provided Failsafe executor.
+  "Executes the given function with the provided Failsafe executor or policy.
 
   Docs: https://failsafe.dev/javadoc/core/dev/failsafe/FailsafeExecutor.html
 
   Parameters:
-  - `executor`: The FailsafeExecutor to use for execution.
+  - `executor-or-policy`: The FailsafeExecutor or Policies to use for execution.
+  - `context-binding`: the binding to use for the ExecutionContext context.
   - `body`: the body of code to execute.
 
   Returns the result or throws an exception."
-  [executor & body]
-  `(impl/execute-get ~executor (bound-fn []
-                                 ~@body)))
+  ([body]
+   `(execute [] context# ~body))
+  ([executor-or-policy body]
+   `(execute ~executor-or-policy context# ~body))
+  ([executor-or-policy context-binding body]
+   `(impl/execute-get ~executor-or-policy
+                      (bound-fn [~(vary-meta context-binding assoc :tag ExecutionContext)]
+                        ~body))))
 
 (defmacro execute-async
-  "Executes the given async function with the provided Failsafe executor.
+  "Executes the given async function with the provided Failsafe executor or policy.
 
   Docs: https://failsafe.dev/javadoc/core/dev/failsafe/FailsafeExecutor.html
 
   Parameters:
-  - `executor`: The FailsafeExecutor to use for execution.
+  - `executor-or-policy`: The FailsafeExecutor or Policies to use for async execution.
+  - `context-binding`: the binding to use for the AsyncExecution context.
   - `body`: the body of code to execute.
 
   Returns a future representing the result or exception."
-  [executor & body]
-  `(impl/execute-get-async ~executor (bound-fn []
-                                       ~@body)))
+  ([body]
+   `(execute-async [] context# ~body))
+  ([executor-or-policy body]
+   `(execute-async ~executor-or-policy context# ~body))
+  ([executor-or-policy context-binding body]
+   `(impl/execute-get-async ~executor-or-policy
+                            (bound-fn [~context-binding]
+                              (async
+                               (try
+                                 (impl/record-async-success ~context-binding (!<! ~body))
+                                 (catch Throwable ~'t
+                                   (impl/record-async-failure ~context-binding ~'t))))))))

src/failsage/impl.clj

@@ -1,11 +1,12 @@
 (ns failsage.impl
   (:require
-   [futurama.core :refer [async !<!] :as f])
+   [futurama.core :as f])
   (:import
    [dev.failsafe
     AsyncExecution
     BulkheadBuilder
     CircuitBreakerBuilder
+    Failsafe
     FailsafeExecutor
     FallbackBuilder
     Policy
@@ -17,7 +18,7 @@
     AsyncRunnable
     CheckedFunction
     CheckedPredicate
-    CheckedSupplier]
+    ContextualSupplier]
    [java.util List]
    [java.util.concurrent ExecutorService]))
 
@@ -63,16 +64,6 @@
   ^EventListener [f]
   (FailsafeEventListener. f))
 
-(deftype FailsafeCheckedSupplier [f]
-  CheckedSupplier
-  (get [_]
-    (f)))
-
-(defn ->checked-supplier
-  "Converts a Clojure function to a Failsafe CheckedSupplier."
-  ^CheckedSupplier [f]
-  (FailsafeCheckedSupplier. f))
-
 (deftype FailsafeCheckedFunction [f]
   CheckedFunction
   (apply [_ args]
@@ -103,6 +94,16 @@
   ^AsyncRunnable [f]
   (FailsafeAsyncRunnable. f))
 
+(deftype FailsafeContextualSupplier [f]
+  ContextualSupplier
+  (get [_ context]
+    (f context)))
+
+(defn ->contextual-supplier
+  "Converts a Clojure function to a Failsafe ContextualSupplier."
+  ^ContextualSupplier [f]
+  (FailsafeContextualSupplier. f))
+
 (defn get-pool
   "Returns a Failsafe-compatible thread pool. If `pool` is a keyword, looks up the pool using `futurama.core/get-pool`.
   Otherwise, returns the provided pool, a default thread pool, or falls back to `futurama.core/get-pool :io`."
@@ -127,20 +128,41 @@
            :else (throw (ex-info "Invalid policy type" {:policy policy}))))
        vec))
 
+(defn record-async-success
+  "Records the result of an execution in the given ExecutionContext."
+  [^AsyncExecution context ^Object result]
+  (.recordResult context result))
+
+(defn record-async-failure
+  "Records the error of an execution in the given ExecutionContext."
+  [^AsyncExecution context ^Throwable error]
+  (.recordException context error))
+
+(defn ->executor
+  "Creates a FailsafeExecutor with the given thread pool and policies.
+  If no policies are provided, uses Failsafe.none()
+  If no pool is provided, uses a default thread pool."
+  (^FailsafeExecutor []
+   (->executor nil nil))
+  (^FailsafeExecutor [executor-or-policies]
+   (->executor nil executor-or-policies))
+  (^FailsafeExecutor [pool executor-or-policies]
+   (let [pool (get-pool pool)]
+     (if (instance? FailsafeExecutor executor-or-policies)
+       (.with ^FailsafeExecutor executor-or-policies pool)
+       (let [policies (get-policy-list executor-or-policies)]
+         (if (empty? policies)
+           (.with (Failsafe/none) pool)
+           (.with (Failsafe/with policies) pool)))))))
+
 (defn execute-get
   "Executes the given CheckedSupplier using the Failsafe executor."
-  [^FailsafeExecutor executor execute-fn]
-  (.get executor (->checked-supplier execute-fn)))
+  [executor-or-policies execute-fn]
+  (.get (->executor executor-or-policies)
+        (->contextual-supplier execute-fn)))
 
 (defn execute-get-async
   "Executes the given CheckedSupplier using the Failsafe executor."
-  [^FailsafeExecutor executor execute-fn]
-  (.getAsyncExecution executor
-                      (->async-runnable
-                       (fn [^AsyncExecution execution]
-                         (async
-                          (try
-                            (let [result (!<! (execute-fn))]
-                              (.recordResult execution result))
-                            (catch Throwable t
-                              (.recordException execution t))))))))
+  [executor-or-policies execute-fn]
+  (.getAsyncExecution (->executor executor-or-policies)
+                      (->async-runnable execute-fn)))