Initial release

Signed-off-by: Greg Haskins <[email protected]>

Author: ghaskins

.gitignore

@@ -0,0 +1,13 @@
+/target
+/classes
+/checkouts
+profiles.clj
+pom.xml
+pom.xml.asc
+*.jar
+*.class
+/.lein-*
+/.nrepl-port
+/.prepl-port
+.hgignore
+.hg/

LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

README.md

@@ -1,2 +1,47 @@
-# temporal-clojure-sdk
-A Temporal SDK for Clojure
+# Temporal Clojure SDK 
+
+[Temporal](https://github.com/temporalio/temporal) is a Workflow-as-Code platform for building and operating
+resilient applications using developer-friendly primitives, instead of constantly fighting your infrastructure.
+
+This Clojure SDK is a framework for authoring Workflows and Activities in Clojure. (For other languages, see [Temporal SDKs](https://docs.temporal.io/application-development).)
+
+- [Temporal docs](https://docs.temporal.io/)
+- [Install Temporal Server](https://docs.temporal.io/docs/server/quick-install)
+- [Temporal CLI](https://docs.temporal.io/docs/devtools/tctl/)
+
+## Requirements
+
+- JDK 1.8+
+
+## macOS Users
+
+Due to issues with default hostname resolution
+(see [this StackOverflow question](https://stackoverflow.com/questions/33289695/inetaddress-getlocalhost-slow-to-run-30-seconds) for more details),
+macOS Users may see gRPC `DEADLINE_EXCEEDED` errors and other slowdowns when running the SDK.
+
+To solve the problem add the following entries to your `/etc/hosts` file (where my-macbook is your hostname):
+
+```conf
+127.0.0.1   my-macbook
+::1         my-macbook
+```
+
+## Contributing
+
+Pull requests welcome.  Please be sure to include a [DCO](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) in any commit messages.
+
+## License
+
+Copyright (C) 2022 Manetu, Inc. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this material except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

dev-resources/user.clj

@@ -0,0 +1,5 @@
+;; Copyright © 2022 Manetu, Inc.  All rights reserved
+
+(ns user
+  (:require [clojure.tools.namespace.repl :refer [refresh]]))
+

doc/intro.md

@@ -0,0 +1,10 @@
+# Introduction
+
+[Temporal](https://github.com/temporalio/temporal) is a Workflow-as-Code platform for building and operating
+resilient applications using developer-friendly primitives, instead of constantly fighting your infrastructure.
+
+The Clojure SDK is the framework for authoring Workflows and Activities in Clojure. (For other languages, see [Temporal SDKs](https://docs.temporal.io/application-development).)
+
+- [Temporal docs](https://docs.temporal.io/)
+- [Install Temporal Server](https://docs.temporal.io/docs/server/quick-install)
+- [Temporal CLI](https://docs.temporal.io/docs/devtools/tctl/)

project.clj

@@ -0,0 +1,31 @@
+(defproject io.github.manetu/temporal-sdk "0.1.0-SNAPSHOT"
+  :description "A Temporal SDK for Clojure"
+  :url "https://github.com/manetu/temporal-clojure-sdk"
+  :license {:name "Apache License 2.0"
+            :url "https://www.apache.org/licenses/LICENSE-2.0"
+            :year 2022
+            :key "apache-2.0"}
+  :plugins [[lein-cljfmt "0.8.2"]
+            [lein-kibit "0.1.8"]
+            [lein-bikeshed "0.5.2"]
+            [lein-cloverage "1.2.4"]
+            [jonase/eastwood "1.2.4"]
+            [lein-codox "0.10.8"]]
+  :dependencies [[org.clojure/clojure "1.11.1"]
+                 [io.temporal/temporal-sdk "1.16.0"]
+                 [io.temporal/temporal-testing "1.16.0"]
+                 [com.taoensso/timbre "5.2.1"]
+                 [funcool/promesa "8.0.450"]]
+  :repl-options {:init-ns user}
+  :aot [temporal.internal.dispatcher]
+
+  :eastwood {:add-linters [:unused-namespaces]}
+  :codox {:metadata {:doc/format :markdown}}
+
+  :profiles {:dev {:dependencies   [[org.clojure/tools.namespace "1.3.0"]
+                                    [eftest "0.5.9"]]}}
+  :cloverage {:runner :eftest
+              :runner-opts {:multithread? false
+                            :fail-fast? true}
+              :fail-threshold 92
+              :ns-exclude-regex [#"temporal.client.worker"]})

src/temporal/activity.clj

@@ -0,0 +1,66 @@
+;; Copyright © 2022 Manetu, Inc.  All rights reserved
+
+(ns temporal.activity
+  "Methods for defining and invoking activity tasks"
+  (:require [clojure.edn :as edn]
+            [taoensso.timbre :as log]
+            [promesa.core :as p]
+            [temporal.internal.activity :as a]
+            [temporal.internal.utils :refer [->promise] :as u])
+  (:import [io.temporal.workflow Workflow]
+           [io.temporal.activity ActivityOptions ActivityOptions$Builder]
+           [java.time Duration]))
+
+(def ^:no-doc invoke-option-spec
+  {:start-to-close-timeout #(.setStartToCloseTimeout ^ActivityOptions$Builder %1  %2)})
+
+(defn- invoke-options->
+  ^ActivityOptions [params]
+  (u/build (ActivityOptions/newBuilder) invoke-option-spec params))
+
+(def ^:no-doc default-invoke-options {:start-to-close-timeout (Duration/ofSeconds 3)})
+
+(defn invoke
+  "
+Invokes 'activity' with 'params' from within a workflow context.  Returns a promise that when derefed will resolve to
+the evaluation of the defactivity once the activity concludes.
+
+```clojure
+(defactivity my-activity
+   [ctx {:keys [foo] :as args}]
+   ...)
+
+(invoke my-activity {:foo \"bar\"} {:start-to-close-timeout (Duration/ofSeconds 3))
+```
+"
+  ([activity params] (invoke activity params default-invoke-options))
+  ([activity params options]
+   (let [act-name (a/get-annotation activity)
+         stub (Workflow/newUntypedActivityStub (invoke-options-> options))]
+     (-> (->promise
+          (.executeAsync stub act-name String (u/->objarray params)))
+         (p/then edn/read-string)))))
+
+(defmacro defactivity
+  "
+Defines a new activity, similar to defn, expecting a 2-arity parameter list and body.  Should evaluate to something
+serializable with [prn-str](https://clojuredocs.org/clojure.core/prn-str), which will be available to the [[invoke]] caller.
+
+Arguments:
+
+- `ctx`: Context passed through from [[temporal.client.worker/start]]
+- `args`: Passed from 'params' of [[invoke]]
+
+```clojure
+(defactivity greet-activity
+    [ctx {:keys [name] :as args}]
+    (str \"Hi, \" name))
+```
+"
+  [name params* & body]
+  (let [class-name (u/get-classname name)]
+    `(def ~name ^{::a/def ~class-name}
+       (fn [ctx# args#]
+         (log/trace (str ~class-name ": ") args#)
+         (let [f# (fn ~params* (do ~@body))]
+           (f# ctx# args#))))))

src/temporal/client/core.clj

@@ -0,0 +1,113 @@
+;; Copyright © 2022 Manetu, Inc.  All rights reserved
+
+(ns temporal.client.core
+  "Methods for client interaction with Temporal"
+  (:require [clojure.edn :as edn]
+            [promesa.core :as p]
+            [temporal.internal.workflow :as w]
+            [temporal.internal.utils :as u])
+  (:import [io.temporal.client WorkflowClient WorkflowStub WorkflowOptions WorkflowOptions$Builder]
+           [io.temporal.serviceclient WorkflowServiceStubs]))
+
+(defn create-client
+  "
+Creates a new client instance suitable for implementing Temporal workers (See [[temporal.client.worker/start]]) or
+workflow clients (See [[create-workflow]]).
+"
+  []
+  (let [service (WorkflowServiceStubs/newLocalServiceStubs)]
+    (WorkflowClient/newInstance service)))
+
+(def ^:no-doc wf-option-spec
+  {:task-queue #(.setTaskQueue ^WorkflowOptions$Builder %1 (u/namify %2))
+   :workflow-id #(.setWorkflowId ^WorkflowOptions$Builder %1 %2)})
+
+(defn- wf-options->
+  ^WorkflowOptions [params]
+  (u/build (WorkflowOptions/newBuilder) wf-option-spec params))
+
+(defn create-workflow
+  "
+Create a new workflow-stub instance, suitable for managing and interacting with a workflow through it's lifecycle.
+
+*N.B.: The workflow will remain in an uninitialized and idle state until explicitly started with either ([[start]]) or
+([[signal-with-start]]).*
+
+```clojure
+(defworkflow my-workflow
+  [ctx args]
+  ...)
+
+(let [w (create client my-workflow {:task-queue ::my-task-queue})]
+  ;; do something with the instance 'w')
+```
+"
+  [^WorkflowClient client workflow options]
+  (let [wf-name (w/get-annotation workflow)
+        stub    (.newUntypedWorkflowStub client wf-name (wf-options-> options))]
+    {:client client :stub stub}))
+
+(defn start
+  "
+Starts 'worklow' with 'params'"
+  [{:keys [^WorkflowStub stub] :as workflow} params]
+  (.start stub (u/->objarray params)))
+
+(defn signal-with-start
+  "
+Signals 'workflow' with 'signal-params' on signal 'signal-name', starting it if not already running.  'wf-params' are
+used as workflow start arguments if the workflow needs to be started"
+  [{:keys [^WorkflowStub stub] :as workflow} signal-name signal-params wf-params]
+  (.signalWithStart stub (u/namify signal-name) (u/->objarray signal-params) (u/->objarray wf-params)))
+
+(defn >!
+  "
+Sends 'params' as a signal 'signal-name' to 'workflow'
+
+```clojure
+(>! workflow ::my-signal {:msg \"Hi\"})
+```
+"
+  [{:keys [^WorkflowStub stub] :as workflow} signal-name params]
+  (.signal stub (u/namify signal-name) (u/->objarray params)))
+
+(defn get-result
+  "
+Retrieves the final result of 'workflow'.  Returns a promise that when derefed will resolve to the evaluation of the
+defworkflow once the workflow concludes.
+
+```clojure
+(defworkflow my-workflow
+  [ctx args]
+  ...)
+
+(let [w (create ...)]
+   (start w ...)
+   @(get-result w))
+```
+"
+  [{:keys [^WorkflowStub stub] :as workflow}]
+  (-> (.getResultAsync stub String)
+      (p/then edn/read-string)))
+
+(defn cancel
+  "
+Gracefully cancels 'workflow'
+
+```clojure
+(cancel workflow)
+```
+"
+  [{:keys [^WorkflowStub stub] :as workflow}]
+  (.cancel stub))
+
+(defn terminate
+  "
+Forcefully terminates 'workflow'
+
+```clojure
+(terminate workflow \"unresponsive\", {})
+```
+"
+  [{:keys [^WorkflowStub stub] :as workflow} reason params]
+  (.terminate stub reason (u/->objarray params)))

src/temporal/client/worker.clj

@@ -0,0 +1,58 @@
+;; Copyright © 2022 Manetu, Inc.  All rights reserved
+
+(ns temporal.client.worker
+  "Methods for managing a Temporal worker instance"
+  (:require [temporal.internal.activity :as a]
+            [temporal.internal.utils :as u])
+  (:import [io.temporal.worker Worker WorkerFactory]
+           [temporal.internal.dispatcher WorkflowImpl]))
+
+(defn ^:no-doc  init
+  "
+Initializes a worker instance, suitable for real connections or unit-testing with temporal.testing.env
+"
+  [^Worker worker ctx]
+  (.addWorkflowImplementationFactory worker WorkflowImpl (u/->Func (fn [] (new WorkflowImpl ctx))))
+  (.registerActivitiesImplementations worker (to-array [(a/dispatcher ctx)])))
+
+(defn start
+  "
+Starts a worker processing loop.
+
+Arguments:
+
+- `client`:     WorkflowClient instance returned from [[temporal.client.core/create-client]]
+- `queue-name`: The name of the task-queue for this worker instance to listen on.  Accepts a string or fully-qualified
+                keyword.
+- `ctx`:        (optional) an opaque handle that is passed as the first argument of [[temporal.workflow/defworkflow]]
+                and [[temporal.activity/defactivity]].  Useful for passing state such as database or network
+                connections.  Not interpreted in any manner.
+
+```clojure
+(start ::my-queue {:some \"context\"})
+```
+"
+  ([client queue-name] (start client queue-name nil))
+  ([client queue-name ctx]
+   (let [factory (WorkerFactory/newInstance client)
+         worker  (.newWorker factory (u/namify queue-name))]
+     (init worker ctx)
+     (.start factory)
+     {:factory factory :worker worker})))
+
+(defn stop
+  "
+Stops a running worker.
+
+Arguments:
+
+- `instance`: Result returned from original call to ([[start]])
+
+```clojure
+(let [instance (start ::my-queue)]
+   ...
+   (stop instance))
+```
+"
+  [{:keys [^WorkerFactory factory] :as instance}]
+  (.shutdown factory))

src/temporal/core.clj

@@ -0,0 +1,13 @@
+;; Copyright © 2022 Manetu, Inc.  All rights reserved
+
+(ns temporal.core
+  (:import [io.temporal.workflow Workflow]
+           [java.util.function Supplier]))
+
+(defn await
+  "Efficiently parks the workflow until 'pred' evaluates to true.  Re-evaluates on each state transition"
+  [pred]
+  (Workflow/await
+   (reify Supplier
+     (get [_]
+       (pred)))))