Clojure SDK

The Clojure SDK ships as two namespaces in the io.orrery/orrery-sdk library:

Namespace	Purpose
`orrery.client`	Low-level HTTP client — fetch-and-lock, complete, fail, extend lock
`orrery.worker`	Worker abstraction — polling loop, heartbeat, auto-complete

Installation


;; deps.edn
{:deps {io.orrery/orrery-sdk {:git/url "https://github.com/orrery-io/orrery"
                               :git/tag "latest"}}}

orrery.client

Creating a client


(require '[orrery.client :as oc])
 
(def c (oc/client))
;; base-url defaults to $ORRERY_URL env var or "http://localhost:3000"
 
(def c (oc/client {:base-url "http://localhost:3000"}))

Functions


;; Fetch and lock tasks
(oc/fetch-and-lock c
  {:worker-id   "my-worker"
   :subscriptions [{:topic "validatePayment"}
                   {:topic "chargeCard" :process-definition-ids ["order-process"]}]
   :max-tasks          4      ; default: 1
   :lock-duration-ms   30000  ; default: 30 000
   :request-timeout-ms 20000  ; default: 20 000
   })
 
;; Complete a task
(oc/complete-task c task-id worker-id {:approved true})
 
;; Fail a task
(oc/fail-task c task-id worker-id "payment declined"
  :retries 2 :retry-timeout-ms 5000)
;; :retries default 0, :retry-timeout-ms default 0
 
;; Extend the lock (heartbeat)
(oc/extend-lock c task-id worker-id 30000)

Errors are thrown as ExceptionInfo with message "HTTP {status}" and :body containing the response body.

Task map shape


{:id                  "task-abc123"
 :topic               "validatePayment"
 :process-instance-id "inst-xyz"
 :process-definition-id "order-process"
 :variables           {:order-id "42" :amount 99.0}
 :worker-id           "my-worker"
 :locked-until        "2024-01-01T00:00:30Z"
 :retry-count         0
 :max-retries         3
 :created-at          "2024-01-01T00:00:00Z"}

orrery.worker

worker + subscribe + run wrap the polling loop. The worker automatically extends locks (heartbeat at 50% of :lock-duration-ms), completes tasks on success, and fails them on error.

Minimal example


(require '[orrery.worker :as ow])
 
(def w (ow/worker {:base-url "http://localhost:3000"}))
 
(ow/subscribe w
  {:topic "validatePayment"}
  (fn [task]
    (let [amount (get-in task [:variables :amount] 0)]
      {:valid (pos? amount)})))
 
(ow/run w) ; blocks until JVM shutdown

run blocks until the JVM shuts down. A shutdown hook stops the worker gracefully, waiting up to 30 seconds for in-flight tasks to complete.

Worker options


(ow/worker
  {:worker-id          "payment-worker-1"  ; default: "worker-{timestamp}"
   :base-url           "http://localhost:3000"
   :lock-duration-ms   60000               ; default: 30 000
   :request-timeout-ms 20000               ; default: 20 000
   :concurrency        8                   ; default: 4
   })

If :base-url is omitted, the worker reads $ORRERY_URL from the environment and falls back to http://localhost:3000.

Multiple topics


(ow/subscribe w {:topic "validatePayment"}
  (fn [task] {:valid true}))
 
(ow/subscribe w {:topic "chargeCard" :process-definition-ids ["order-process"]}
  (fn [task] {:charge-id "ch_abc123"}))
 
(ow/subscribe w {:topic "sendReceipt"}
  (fn [task] {}))

:process-definition-ids filters tasks to only those definitions. Omit it (or pass an empty vector) to receive tasks from any definition.

Error handling

Throw any exception to fail the task. The exception message is stored and the task is retried according to its retry configuration.


(ow/subscribe w {:topic "chargeCard"}
  (fn [task]
    (let [amount (get-in task [:variables :amount])]
      (when-not amount
        (throw (ex-info "missing amount variable" {})))
      (when (> amount 10000)
        (throw (ex-info "amount exceeds limit" {})))
      {:charged true :amount amount})))

Task context


(ow/subscribe w {:topic "processOrder"}
  (fn [task]
    (println "task:      " (:id task))
    (println "topic:     " (:topic task))
    (println "instance:  " (:process-instance-id task))
    (println "definition:" (:process-definition-id task))
    (println "retry:     " (:retry-count task) "/" (:max-retries task))
 
    (let [amount (get-in task [:variables :amount] 0)]
      {:total amount})))

Source: sdks/clojure/ in the main repository.