temporalio 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c61a784d88682c42f1dae18ee88ce556f6f705914abccf793f7a37ae4877bb83
-  data.tar.gz: 72a8f479f63d3acad8944eee20f4eb53f2db84e6304c930d29d2180e4181100f
+  metadata.gz: f08577afe5170dc9e21a1fca6cf6c392fe4a15d2bcb699a452aa21ec3a7dee16
+  data.tar.gz: 8f36176626b07d8fd2a49e214d55c1e8f4727ad5dfbc15555d620ce88452ed93
 SHA512:
-  metadata.gz: c6d6e559f5f71e48d823acef13e32576fc61d589882f35c6ba5b2bbd5addd83bfbab0cf76480de6895e9afa005c2fa9a8fa2dd973048443fd152d5057ea9724f
-  data.tar.gz: 1cab9eb98faaa44e715f046870bcc83a64a979720da6ef28c1ff5dd0a600041cd7f32a4bdc44afcc9b4576171d07b36fe80c7eb7815c5a5c83f52c51f96cb16e
+  metadata.gz: 072a450775661734eb6fdc176a09e64ada9616d17769ce723e12182e59603e08df6cdd58e095f92673ec09b041bb9e9e508b0f079ec4d83b6acdc31f460bb667
+  data.tar.gz: e4e8c7b38410a2ba9f2eb8256d26dbb5f02fd936e650e3cd75c4fdc36c09d2f172aa3b06b819bac41ea11bf6e2e9d8eec3cb29873643ca149759ed58c8c40a71

data/README.md

@@ -21,14 +21,18 @@ At this point the SDK only supports the **Temporal Client** capabilities:
 - Interacting with a workflow (cancelling, querying, signalling, etc)
 - Interceptor and Data Conversion support
 - 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'
@@ -38,7 +42,6 @@ The SDK is now ready for use. To build from source, see [Dev Setup](#dev-setup).
 
 **NOTE: This README is for the current branch and not necessarily what's released on RubyGems.**
 
-
 ## Usage
 
 ### Client
@@ -47,10 +50,16 @@ 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')
+
+# To enable TLS, simply add the `tls:` argument:
+#     Temporalio::Connection.new(
+#       'localhost:7233',
+#       tls: Temporalio::Connection::TlsOptions.new(client_cert, client_private_key)
+#     )
 
 # 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')
@@ -63,7 +72,6 @@ puts "Result: #{result}"
 Some things to note about the above code:
 
 - A `Client` does not have an explicit "close"
-- TLS is not yet supported
 - All positional arguments after the workflow name are treated as workflow arguments
 - The `handle` represents the workflow that was started and can be used for more than just getting
   the result
@@ -82,12 +90,177 @@ 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 'temporalio'
+
+# Establish a gRPC connection to the server
+connection = Temporalio::Connection.new('localhost:7233')
+
+# Initialize a new worker with your activities
+worker = Temporalio::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 = Temporalio::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 `Temporalio::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 `Temporalio::Worker.run` method:
+
+```ruby
+# Initialize workers
+worker_1 = Temporalio::Worker.new(connection, 'my-namespace-1', 'my-task-queue-1', activities: [MyActivity1, MyActivity2])
+worker_2 = Temporalio::Worker.new(connection, 'my-namespace-2', 'my-task-queue-1', activities: [MyActivity3])
+worker_3 = Temporalio::Worker.new(connection, 'my-namespace-1', 'my-task-queue-2', activities: [MyActivity4])
+
+Temporalio::Worker.run(worker_1, worker_2, worker_3)
+```
+
+Please note that similar to `Temporalio::Worker#run`, `Temporalio::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
+Temporalio::Worker.run(worker_1, worker_2, worker_3, shutdown_signals: %w[INT TERM])
+```
+
+#### Worker Shutdown
+
+The `Temporalio::Worker#run` (as well as `Temporalio::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 `Temporalio::Activity` class:
+
+```ruby
+class SayHelloActivity < Temporalio::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 `Temporalio::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
+`Temporalio::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 < Temporalio::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 < Temporalio::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