temporalio 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c61a784d88682c42f1dae18ee88ce556f6f705914abccf793f7a37ae4877bb83
-  data.tar.gz: 72a8f479f63d3acad8944eee20f4eb53f2db84e6304c930d29d2180e4181100f
+  metadata.gz: 657f0a3bde04af32d78ce4f6b58103ba1eb5e16b6b023aea02fdd8889fe7594c
+  data.tar.gz: 7b51a09196eb6dde92b54e31b1abad8cf7ce3a41f2c719de73d8341e83d5d95e
 SHA512:
-  metadata.gz: c6d6e559f5f71e48d823acef13e32576fc61d589882f35c6ba5b2bbd5addd83bfbab0cf76480de6895e9afa005c2fa9a8fa2dd973048443fd152d5057ea9724f
-  data.tar.gz: 1cab9eb98faaa44e715f046870bcc83a64a979720da6ef28c1ff5dd0a600041cd7f32a4bdc44afcc9b4576171d07b36fe80c7eb7815c5a5c83f52c51f96cb16e
+  metadata.gz: 768d7983132b8a4bc3bd359be90a621463f9abd0e3a6de51dbd13256c86e9f60f916142b3301d22082e7ffacba156b5a97666b4f189299e976bc890c224fe2bb
+  data.tar.gz: 7602428c63547f9de4da9dcbd4180d58617eae04fb5478a58fbfc16c2d7f27fda8894134ab1a7d37dfe3c79f0c67d97eabf5f2f7f50e0112f19dbcc12f32d1d3

data/README.md

@@ -23,12 +23,17 @@ At this point the SDK only supports the **Temporal Client** capabilities:
 - gRPC access to Temporal Server
 - Temporal Cloud is not yet supported due to the lack of TLS support, but it's coming soon
 
+As well as **Activity Worker** capabilities:
+
+- Definiting activities
+- Activity heartbeats/cancellations
+- Running activity workers
 
 ## Quick Start
 
 ### Installation
 
-Add the [`temporalio` gem](https://rubygems.org/gems/temporalio) to your Gemfile:
+Add the [temporalio gem](https://rubygems.org/gems/temporalio) to your Gemfile:
 
 ```ruby
 gem 'temporalio'
@@ -47,10 +52,10 @@ A client can be created and used to start a workflow like so:
 
 ```ruby
 # Establish a gRPC connection to the server
-connection = Temporal::Connection.new('localhost:7233')
+connection = Temporalio::Connection.new('localhost:7233')
 
 # Initialize a Client with a namespace
-client = Temporal::Client.new(connection, 'my-namespace')
+client = Temporalio::Client.new(connection, 'my-namespace')
 
 # Start a workflow
 handle = client.start_workflow('MyWorkflow', 'some input', id: 'my-id', task_queue: 'my-task-queue')
@@ -82,12 +87,178 @@ The default data converter supports converting multiple types including:
 
 - `nil`
 - bytes (`String` with `Encoding::ASCII_8BIT`)
-- Anything that [`JSON.generate`](https://ruby-doc.org/stdlib-3.0.0/libdoc/json/rdoc/JSON.html#method-i-generate)
+- Anything that [JSON.generate](https://ruby-doc.org/stdlib-3.0.0/libdoc/json/rdoc/JSON.html#method-i-generate)
   supports
 
 This notably doesn't include any `Date`, `Time`, or `DateTime` objects as they may not work across
 different SDKs. A custom payload converter can be implemented to support these.
 
+### Workers
+
+Workers host workflows (coming soon) and/or activities. Here's how to run a worker:
+
+```ruby
+require 'temporal'
+
+# Establish a gRPC connection to the server
+connection = Temporal::Connection.new('localhost:7233')
+
+# Initialize a new worker with your activities
+worker = Temporal::Worker.new(connection, 'my-namespace', 'my-task-queue', activities: [MyActivity])
+
+# Occupy the thread by running the worker
+worker.run
+```
+
+Some things to note about the above code:
+
+- This creates/uses the same connection that is used for initializing a client
+- Workers can have many more options not shown here (e.g. data converters and interceptors)
+
+In order to have more control over running of a worker you can provide a block of code by the end of
+which the worker will shut itself down:
+
+```ruby
+# Initialize worker_1, worker_2 and worker_3 as in the example above
+
+# Run the worker for 5 seconds, then shut down
+worker_1.run { sleep 5 }
+
+# Or shut the worker down when a workflow completes (very useful for running specs):
+client = Temporal::Client.new(connection, 'my-namespace')
+handle = client.start_workflow('MyWorkflow', 'some input', id: 'my-id', task_queue: 'my-task-queue')
+worker_2.run { handle.result }
+
+# Or wait for some external signal to stop the worker
+stop_queue = Queue.new
+Signal.trap('USR1') { stop_queue.close }
+worker_3.run { stop_queue.pop }
+```
+
+You can also shut down a running worker by calling `Temporal::Worker#shutdown` from a separate
+thread at any time.
+
+#### Running multiple workers
+
+In order to run multiple workers in the same thread you can use the `Temporal::Worker.run` method:
+
+```ruby
+# Initialize workers
+worker_1 = Temporal::Worker.new(connection, 'my-namespace-1', 'my-task-queue-1', activities: [MyActivity1, MyActivity2])
+worker_2 = Temporal::Worker.new(connection, 'my-namespace-2', 'my-task-queue-1', activities: [MyActivity3])
+worker_3 = Temporal::Worker.new(connection, 'my-namespace-1', 'my-task-queue-2', activities: [MyActivity4])
+
+Temporal::Worker.run(worker_1, worker_2, worker_3)
+```
+
+Please note that similar to `Temporal::Worker#run`, `Temporal::Worker.run` accepts a block that
+behaves the same way — the workers will be shut down when the block finishes.
+
+You can also configure your worker to listen on process signals to initiate a shutdown:
+
+```ruby
+Temporal::Worker.run(worker_1, worker_2, worker_3, shutdown_signals: %w[INT TERM])
+```
+
+#### Worker Shutdown
+
+The `Temporal::Worker#run` (as well as `Temporal::Worker#shutdown`) invocation will wait on all
+activities to complete, so if a long-running activity does not at least respect cancellation, the
+shutdown may never complete.
+
+If a worker was initialized with a `graceful_shutdown_timeout` option then a cancellation will be
+issued for every running activity after the set timeout. The bahaviour is mostly identical to a
+server requested cancellation and should be handled accordingly. More on this in [Heartbeating and
+Cancellation](#heartbeating-and-cancellation).
+
+### Activities
+
+#### Definition
+
+Activities are defined by subclassing `Temporal::Activity` class:
+
+```ruby
+class SayHelloActivity < Temporal::Activity
+  # Optionally specify a custom activity name:
+  #   (The class name `SayHelloActivity` will be used by default)
+  activity_name 'say-hello'
+
+  def execute(name)
+    return "Hello, #{name}!"
+  end
+end
+```
+
+Some things to note about activity definitions:
+
+- Long running activities should regularly heartbeat and handle cancellation
+- Activities can only have positional arguments. Best practice is to only take a single argument
+  that is an object/dataclass of fields that can be added to as needed.
+
+#### Activity Context
+
+Activity classes have access to `Temporal::Activity::Context` via the `activity` method. Which
+itself provides access to useful methods, specifically:
+
+- `info` - Returns the immutable info of the currently running activity
+- `heartbeat(*details)` - Record a heartbeat
+- `cancelled?` - Whether a cancellation has been requested on this activity
+- `shield` - Prevent cancel exception from being thrown during the provided block of code
+
+##### Heartbeating and Cancellation
+
+In order for a non-local activity to be notified of cancellation requests, it must call
+`activity.heartbeat`. It is strongly recommended that all but the fastest executing activities call
+this method regularly.
+
+In addition to obtaining cancellation information, heartbeats also support detail data that is
+persisted on the server for retrieval during activity retry. If an activity calls
+`activity.heartbeat(123, 456)` and then fails and is retried, `activity.info.heartbeat_details` will
+return an array containing `123` and `456` on the next run.
+
+A cancellation is implemented using the `Thread#raise` method, which will raise a
+`Temporal::Error::ActivityCancelled` during the execution of an activity. This means that your code
+might get interrupted at any point and never complete. In order to protect critical parts of your
+activities wrap them in `activity.shield`:
+
+```ruby
+class ActivityWithCriticalLogic < Temporal::Activity
+  def execute
+    activity.shield do
+      run_business_critical_logic_1
+    end
+
+    run_non_critical_logic
+
+    activity.shield do
+      run_business_critical_logic_2
+    end
+  end
+end
+```
+
+This will ensure that a cancellation request received while inside the `activity.shield` block will
+not raise an exception until that block finishes.
+
+In case the entire activity is considered critical, you can mark it as `shielded!` and ignore
+cancellation requests altogether:
+
+```ruby
+class CriticalActivity < Temporal::Activity
+  shielded!
+
+  def execute
+    ...
+  end
+end
+```
+
+For any long-running activity using this approach it is recommended to periodically check
+`activity.cancelled?` flag and respond accordingly.
+
+Please note that your activities can also get cancelled during a worker shutdown process ([if
+configured accordingly](#worker-shutdown)).
+
 
 ## Dev Setup
 

data/bridge/Cargo.lock

@@ -163,6 +163,12 @@ version = "0.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9e1b586273c5702936fe7b7d6896644d8be71e6314cfe09d3167c95f712589e8"
 
+[[package]]
+name = "base64"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ea22880d78093b0cbe17c89f64a7d457941e65759157ec6cb31a31d652b05e5"
+
 [[package]]
 name = "base64ct"
 version = "1.5.3"
@@ -197,6 +203,7 @@ dependencies = [
  "temporal-sdk-core-protos",
  "thiserror",
  "tokio",
+ "tokio-util",
  "tonic",
  "url",
 ]
@@ -369,7 +376,7 @@ dependencies = [
  "autocfg",
  "cfg-if",
  "crossbeam-utils",
- "memoffset",
+ "memoffset 0.6.5",
  "scopeguard",
 ]
 
@@ -452,18 +459,18 @@ dependencies = [
 
 [[package]]
 name = "derive_builder"
-version = "0.11.2"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d07adf7be193b71cc36b193d0f5fe60b918a3a9db4dad0449f57bcfd519704a3"
+checksum = "8d67778784b508018359cbc8696edb3db78160bab2c2a28ba7f56ef6932997f8"
 dependencies = [
  "derive_builder_macro",
 ]
 
 [[package]]
 name = "derive_builder_core"
-version = "0.11.2"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f91d4cfa921f1c05904dc3c57b4a32c38aed3340cce209f3a6fd1478babafc4"
+checksum = "c11bdc11a0c47bc7d37d582b5285da6849c96681023680b906673c5707af7b0f"
 dependencies = [
  "darling",
  "proc-macro2",
@@ -473,9 +480,9 @@ dependencies = [
 
 [[package]]
 name = "derive_builder_macro"
-version = "0.11.2"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f0314b72bed045f3a68671b3c86328386762c93f82d98c65c3cb5e5f573dd68"
+checksum = "ebcda35c7a396850a55ffeac740804b40ffec779b98fffbb1738f4033f0ee79e"
 dependencies = [
  "derive_builder_core",
  "syn",
@@ -1056,6 +1063,15 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "memoffset"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5de893c32cde5f383baa4c04c5d6dbdd735cfd4a794b0debdb2bb1b421da5ff4"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "mime"
 version = "0.3.16"
@@ -1118,16 +1134,16 @@ checksum = "e5ce46fe64a9d73be07dcbe690a38ce1b293be448fd8ce1e6c1b8062c9f72c6a"
 
 [[package]]
 name = "nix"
-version = "0.25.0"
+version = "0.26.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e322c04a9e3440c327fca7b6c8a63e6890a32fa2ad689db972425f07e0d22abb"
+checksum = "46a58d1d356c6597d08cde02c2f09d785b09e28711837b1ed667dc652c08a694"
 dependencies = [
- "autocfg",
  "bitflags",
  "cfg-if",
  "libc",
- "memoffset",
+ "memoffset 0.7.1",
  "pin-utils",
+ "static_assertions",
 ]
 
 [[package]]
@@ -1637,7 +1653,7 @@ version = "0.11.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "431949c384f4e2ae07605ccaa56d1d9d2ecdb5cadd4f9577ccfab29f2e5149fc"
 dependencies = [
- "base64",
+ "base64 0.13.1",
  "bytes",
  "encoding_rs",
  "futures-core",
@@ -1688,11 +1704,11 @@ dependencies = [
 
 [[package]]
 name = "ringbuf"
-version = "0.2.8"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f65af18d50f789e74aaf23bbb3f65dcd22a3cb6e029b5bced149f6bd57c5c2a2"
+checksum = "89e68dd9c1d8f7bb0c664e1556b1521809bc6fa62d92bb3b813adf8611caa0eb"
 dependencies = [
- "cache-padded",
+ "crossbeam-utils",
 ]
 
 [[package]]
@@ -1757,7 +1773,7 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0864aeff53f8c05aa08d86e5ef839d3dfcf07aeba2db32f12db0ef716e87bd55"
 dependencies = [
- "base64",
+ "base64 0.13.1",
 ]
 
 [[package]]
@@ -1960,6 +1976,12 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e63cff320ae2c57904679ba7cb63280a3dc4613885beafb148ee7bf9aa9042d"
 
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
 [[package]]
 name = "strsim"
 version = "0.10.0"
@@ -2048,7 +2070,7 @@ dependencies = [
  "arc-swap",
  "async-channel",
  "async-trait",
- "base64",
+ "base64 0.20.0",
  "crossbeam",
  "dashmap",
  "derive_builder",
@@ -2105,16 +2127,17 @@ dependencies = [
 name = "temporal-sdk-core-api"
 version = "0.1.0"
 dependencies = [
- "anyhow",
  "async-trait",
  "derive_builder",
- "log",
  "opentelemetry",
  "prost-types",
+ "serde_json",
  "temporal-client",
  "temporal-sdk-core-protos",
  "thiserror",
  "tonic",
+ "tracing-core",
+ "url",
 ]
 
 [[package]]
@@ -2122,7 +2145,7 @@ name = "temporal-sdk-core-protos"
 version = "0.1.0"
 dependencies = [
  "anyhow",
- "base64",
+ "base64 0.20.0",
  "derive_more",
  "prost",
  "prost-types",
@@ -2298,7 +2321,7 @@ dependencies = [
  "async-stream",
  "async-trait",
  "axum",
- "base64",
+ "base64 0.13.1",
  "bytes",
  "futures-core",
  "futures-util",

data/bridge/Cargo.toml

@@ -15,6 +15,7 @@ temporal-sdk-core-api = { version = "0.1.0", path = "./sdk-core/core-api" }
 temporal-sdk-core-protos = { version = "0.1.0", path = "./sdk-core/sdk-core-protos" }
 thiserror = "1.0.31"
 tokio = "1.15"
+tokio-util = "0.7.4"
 tonic = "0.8"
 url = "2.2"
 

data/bridge/sdk-core/Cargo.toml

@@ -1,2 +1,2 @@
 [workspace]
-members = ["bridge-ffi", "core", "client", "core-api", "fsm", "test-utils", "sdk-core-protos", "sdk"]
+members = ["core", "client", "core-api", "fsm", "test-utils", "sdk-core-protos", "sdk"]

data/bridge/sdk-core/README.md

@@ -17,7 +17,6 @@ This repo is composed of multiple crates:
 * temporal-sdk-core-api `./core-api` - Defines the API surface exposed by Core
 * temporal-sdk-core `./core` - The Core implementation
 * temporal-sdk `./sdk` - A (currently prototype) Rust SDK built on top of Core. Used for testing.
-* temporal-sdk-core-bridge-ffi `./bridge-ffi` - C API wrapper for Core
 * rustfsm `./fsm` - Implements a procedural macro used by core for defining state machines
     (contains subcrates). It is temporal agnostic.
 
@@ -52,9 +51,7 @@ it for a test, insert the below snippet at the start of the test. By default, tr
 to stdout in a (reasonably) pretty manner.
 
 ```rust
-crate::telemetry::telemetry_init(Default::default());
-let s = info_span!("Test start");
-let _enter = s.enter();
+crate::telemetry::test_telem_console();
 ```
 
 The passed in options to initialization can be customized to export to an OTel collector, etc.

data/bridge/sdk-core/client/Cargo.toml

@@ -14,7 +14,7 @@ categories = ["development-tools"]
 anyhow = "1.0"
 async-trait = "0.1"
 backoff = "0.4"
-derive_builder = "0.11"
+derive_builder = "0.12"
 derive_more = "0.99"
 futures = "0.3"
 futures-retry = "0.6.0"

data/bridge/sdk-core/client/src/lib.rs

@@ -46,13 +46,12 @@ use temporal_sdk_core_protos::{
     coresdk::{workflow_commands::QueryResult, IntoPayloadsExt},
     grpc::health::v1::health_client::HealthClient,
     temporal::api::{
-        command::v1::Command,
         common::v1::{Header, Payload, Payloads, WorkflowExecution, WorkflowType},
         enums::v1::{TaskQueueKind, WorkflowIdReusePolicy, WorkflowTaskFailedCause},
         failure::v1::Failure,
         operatorservice::v1::operator_service_client::OperatorServiceClient,
         query::v1::WorkflowQuery,
-        taskqueue::v1::{StickyExecutionAttributes, TaskQueue},
+        taskqueue::v1::TaskQueue,
         testservice::v1::test_service_client::TestServiceClient,
         workflowservice::v1::{workflow_service_client::WorkflowServiceClient, *},
     },
@@ -181,6 +180,17 @@ impl RetryConfig {
         }
     }
 
+    pub(crate) const fn throttle_retry_policy() -> Self {
+        Self {
+            initial_interval: Duration::from_secs(1),
+            randomization_factor: 0.2,
+            multiplier: 2.0,
+            max_interval: Duration::from_secs(10),
+            max_elapsed_time: None,
+            max_retries: 0,
+        }
+    }
+
     pub(crate) fn into_exp_backoff<C>(self, clock: C) -> exponential::ExponentialBackoff<C> {
         exponential::ExponentialBackoff {
             current_interval: self.initial_interval,
@@ -362,24 +372,6 @@ impl ClientOptions {
     }
 }
 
-/// A version of [RespondWorkflowTaskCompletedRequest] that will finish being filled out by the
-/// server client
-#[derive(Debug, Clone, PartialEq)]
-pub struct WorkflowTaskCompletion {
-    /// The task token that would've been received from polling for a workflow activation
-    pub task_token: TaskToken,
-    /// A list of new commands to send to the server, such as starting a timer.
-    pub commands: Vec<Command>,
-    /// If set, indicate that next task should be queued on sticky queue with given attributes.
-    pub sticky_attributes: Option<StickyExecutionAttributes>,
-    /// Responses to queries in the `queries` field of the workflow task.
-    pub query_responses: Vec<QueryResult>,
-    /// Indicate that the task completion should return a new WFT if one is available
-    pub return_new_workflow_task: bool,
-    /// Force a new WFT to be created after this completion
-    pub force_create_new_workflow_task: bool,
-}
-
 /// Interceptor which attaches common metadata (like "client-name") to every outgoing call
 #[derive(Clone)]
 pub struct ServiceCallInterceptor {

data/bridge/sdk-core/client/src/raw.rs

@@ -542,6 +542,15 @@ proxier! {
             r.extensions_mut().insert(labels);
         }
     );
+    (
+        delete_workflow_execution,
+        DeleteWorkflowExecutionRequest,
+        DeleteWorkflowExecutionResponse,
+        |r| {
+            let labels = AttachMetricLabels::namespace(r.get_ref().namespace.clone());
+            r.extensions_mut().insert(labels);
+        }
+    );
     (
         list_open_workflow_executions,
         ListOpenWorkflowExecutionsRequest,
@@ -808,17 +817,9 @@ proxier! {
             r.extensions_mut().insert(labels);
         }
     );
-    (delete_workflow_execution, DeleteWorkflowExecutionRequest, DeleteWorkflowExecutionResponse,
-        |r| {
-            let labels = AttachMetricLabels::namespace(r.get_ref().namespace.clone());
-            r.extensions_mut().insert(labels);
-        }
-    );
     (add_or_update_remote_cluster, AddOrUpdateRemoteClusterRequest, AddOrUpdateRemoteClusterResponse);
     (remove_remote_cluster, RemoveRemoteClusterRequest, RemoveRemoteClusterResponse);
-    (describe_cluster, DescribeClusterRequest, DescribeClusterResponse);
     (list_clusters, ListClustersRequest, ListClustersResponse);
-    (list_cluster_members, ListClusterMembersRequest, ListClusterMembersResponse);
 }
 
 proxier! {