@temporalio/core-bridge 0.19.2 → 0.20.2

package/sdk-core/sdk/src/lib.rs

@@ -1,41 +1,67 @@
 #![warn(missing_docs)] // error if there are missing docs
 
-//! This crate is a rough prototype Rust SDK. It can be used to create closures that look sort of
-//! like normal workflow code. It should only depend on things in the core crate that are already
-//! publicly exposed.
+//! This crate defines an alpha-stage Temporal Rust SDK.
 //!
-//! Needs lots of love to be production ready but the basis is there
+//! Currently defining activities and running an activity-only worker is the most stable code.
+//! Workflow definitions exist and running a workflow worker works, but the API is still very
+//! unstable.
+//!
+//! An example of running an activity worker:
+//! ```no_run
+//! use std::{sync::Arc, str::FromStr};
+//! use temporal_sdk::{sdk_client_options, Worker};
+//! use temporal_sdk_core::{init_worker, Url};
+//! use temporal_sdk_core_api::worker::{WorkerConfig, WorkerConfigBuilder};
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let server_options = sdk_client_options(Url::from_str("http://localhost:7233")?).build()?;
+//!     let client = server_options.connect("my_namespace", None).await?;
+//!     let worker_config = WorkerConfigBuilder::default().build()?;
+//!     let core_worker = init_worker(worker_config, client);
+//!
+//!     let mut worker = Worker::new_from_core(Arc::new(core_worker), "task_queue");
+//!     worker.register_activity(
+//!         "echo_activity",
+//!         |echo_me: String| async move { Ok(echo_me) },
+//!     );
+//!     worker.run().await?;
+//!     Ok(())
+//! }
+//! ```
 
 #[macro_use]
 extern crate tracing;
 
 mod conversions;
+pub mod interceptors;
 mod payload_converter;
 mod workflow_context;
 mod workflow_future;
 
 pub use workflow_context::{
     ActivityOptions, CancellableFuture, ChildWorkflow, ChildWorkflowOptions, LocalActivityOptions,
-    WfContext,
+    Signal, SignalData, SignalWorkflowOptions, WfContext,
 };
 
-use crate::workflow_context::{ChildWfCommon, PendingChildWorkflow};
+use crate::{
+    interceptors::WorkerInterceptor,
+    workflow_context::{ChildWfCommon, PendingChildWorkflow},
+};
 use anyhow::{anyhow, bail};
 use futures::{future::BoxFuture, stream::FuturesUnordered, FutureExt, StreamExt};
+use once_cell::sync::OnceCell;
 use std::{
     collections::HashMap,
     fmt::{Debug, Display, Formatter},
     future::Future,
-    ops::{Deref, DerefMut},
-    sync::{
-        atomic::{AtomicUsize, Ordering},
-        Arc,
-    },
-    time::Duration,
+    sync::Arc,
 };
+use temporal_client::ClientOptionsBuilder;
+use temporal_sdk_core::Url;
 use temporal_sdk_core_api::{
     errors::{PollActivityError, PollWfError},
-    Core,
+    Worker as CoreWorker,
 };
 use temporal_sdk_core_protos::{
     coresdk::{
@@ -64,22 +90,40 @@ use tokio::{
 };
 use tokio_util::sync::CancellationToken;
 
-/// A worker that can poll for and respond to workflow tasks by using [WorkflowFunction]s
-pub struct TestRustWorker {
-    core: Arc<dyn Core>,
-    task_queue: String,
-    task_timeout: Option<Duration>,
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Returns a [ClientOptionsBuilder] with required fields set to appropriate values
+/// for the Rust SDK.
+pub fn sdk_client_options(url: impl Into<Url>) -> ClientOptionsBuilder {
+    let mut builder = ClientOptionsBuilder::default();
+    builder
+        .target_url(url)
+        .client_name("rust-sdk".to_string())
+        .client_version(VERSION.to_string())
+        .worker_binary_id(binary_id().to_string());
+
+    builder
+}
+
+/// A worker that can poll for and respond to workflow tasks by using [WorkflowFunction]s,
+/// and activity tasks by using [ActivityFunction]s
+pub struct Worker {
+    common: CommonWorker,
     workflow_half: WorkflowHalf,
     activity_half: ActivityHalf,
 }
 
+struct CommonWorker {
+    worker: Arc<dyn CoreWorker>,
+    task_queue: String,
+    worker_interceptor: Option<Box<dyn WorkerInterceptor>>,
+}
+
 struct WorkflowHalf {
     /// Maps run id to the driver
     workflows: HashMap<String, UnboundedSender<WorkflowActivation>>,
     /// Maps workflow type to the function for executing workflow runs with that ID
     workflow_fns: HashMap<String, WorkflowFunction>,
-    /// Number of live workflows
-    incomplete_workflows: Arc<AtomicUsize>,
     /// Handles for each spawned workflow run are inserted here to be cleaned up when all runs
     /// are finished
     join_handles: FuturesUnordered<BoxFuture<'static, Result<WorkflowResult<()>, JoinError>>>,
@@ -91,17 +135,21 @@ struct ActivityHalf {
     task_tokens_to_cancels: HashMap<TaskToken, CancellationToken>,
 }
 
-impl TestRustWorker {
-    /// Create a new rust worker
-    pub fn new(core: Arc<dyn Core>, task_queue: String, task_timeout: Option<Duration>) -> Self {
+impl Worker {
+    // pub fn new(cfg: WorkerConfig) -> Self {}
+
+    #[doc(hidden)]
+    /// Create a new rust worker from a core worker
+    pub fn new_from_core(worker: Arc<dyn CoreWorker>, task_queue: impl Into<String>) -> Self {
         Self {
-            core,
-            task_queue,
-            task_timeout,
+            common: CommonWorker {
+                worker,
+                task_queue: task_queue.into(),
+                worker_interceptor: None,
+            },
             workflow_half: WorkflowHalf {
                 workflows: Default::default(),
                 workflow_fns: Default::default(),
-                incomplete_workflows: Arc::new(AtomicUsize::new(0)),
                 join_handles: FuturesUnordered::new(),
             },
             activity_half: ActivityHalf {
@@ -113,35 +161,14 @@ impl TestRustWorker {
 
     /// Returns the task queue name this worker polls on
     pub fn task_queue(&self) -> &str {
-        &self.task_queue
+        &self.common.task_queue
     }
 
-    /// Create a workflow, asking the server to start it with the provided workflow ID and using the
-    /// provided workflow function.
-    ///
-    /// Increments the expected Workflow run count.
-    ///
-    /// Returns the run id of the started workflow
-    pub async fn submit_wf(
-        &self,
-        workflow_id: impl Into<String>,
-        workflow_type: impl Into<String>,
-        input: Vec<Payload>,
-    ) -> Result<String, tonic::Status> {
-        let res = self
-            .core
-            .server_gateway()
-            .start_workflow(
-                input,
-                self.task_queue.clone(),
-                workflow_id.into(),
-                workflow_type.into(),
-                self.task_timeout,
-            )
-            .await?;
-
-        self.incr_expected_run_count(1);
-        Ok(res.run_id)
+    /// Return a handle that can be used to initiate shutdown.
+    /// TODO: Doc better after shutdown changes
+    pub fn shutdown_handle(&self) -> impl Fn() {
+        let w = self.common.worker.clone();
+        move || w.initiate_shutdown()
     }
 
     /// Register a Workflow function to invoke when the Worker is asked to run a workflow of
@@ -171,34 +198,19 @@ impl TestRustWorker {
         );
     }
 
-    // TODO: Should be removed before making this worker prod ready. There can be a test worker
-    //   which wraps this one and implements the workflow counting / run_until_done concepts.
-    //   This worker can expose an interceptor for completions that could be used to assist with
-    //   workflow tracking
-    /// Increment the expected Workflow run count on this Worker. The Worker tracks the run count
-    /// and will resolve `run_until_done` when it goes down to 0.
-    /// You do not have to increment if scheduled a Workflow with `submit_wf`.
-    pub fn incr_expected_run_count(&self, count: usize) {
-        self.workflow_half
-            .incomplete_workflows
-            .fetch_add(count, Ordering::SeqCst);
-    }
-
-    /// See [Self::run_until_done], except calls the provided callback just before performing core
-    /// shutdown.
-    pub async fn run_until_done_shutdown_hook(
-        &mut self,
-        before_shutdown: impl FnOnce(),
-    ) -> Result<(), anyhow::Error> {
+    /// Runs the worker. Eventually resolves after the worker has been explicitly shut down,
+    /// or may return early with an error in the event of some unresolvable problem.
+    pub async fn run(&mut self) -> Result<(), anyhow::Error> {
         let (shutdown_tx, shutdown_rx) = watch::channel(false);
         let pollers = async move {
-            let (core, task_q, wf_half, act_half) = self.split_apart();
+            let (common, wf_half, act_half) = self.split_apart();
             let (completions_tx, mut completions_rx) = unbounded_channel();
             let (wf_poll_res, act_poll_res) = tokio::join!(
                 // Workflow polling loop
                 async {
                     loop {
-                        let activation = match core.poll_workflow_activation(task_q).await {
+                        info!("Polling");
+                        let activation = match common.worker.poll_workflow_activation().await {
                             Err(PollWfError::ShutDown) => {
                                 break Result::<_, anyhow::Error>::Ok(());
                             }
@@ -206,20 +218,13 @@ impl TestRustWorker {
                         };
                         wf_half
                             .workflow_activation_handler(
-                                core.as_ref(),
-                                task_q,
+                                common,
                                 &shutdown_rx,
                                 &completions_tx,
                                 &mut completions_rx,
                                 activation,
                             )
                             .await?;
-                        if wf_half.incomplete_workflows.load(Ordering::SeqCst) == 0 {
-                            // Die rebel scum - evict all workflows (which are complete now),
-                            // and turn off activity polling.
-                            let _ = shutdown_tx.send(true);
-                            break Result::<_, anyhow::Error>::Ok(());
-                        }
                     }
                 },
                 // Only poll on the activity queue if activity functions have been registered. This
@@ -229,11 +234,11 @@ impl TestRustWorker {
                     if !act_half.activity_fns.is_empty() {
                         loop {
                             tokio::select! {
-                                activity = core.poll_activity_task(task_q) => {
+                                activity = common.worker.poll_activity_task() => {
                                     if matches!(activity, Err(PollActivityError::ShutDown)) {
                                         break;
                                     }
-                                    act_half.activity_task_handler(core.clone(), task_q,
+                                    act_half.activity_task_handler(common.worker.clone(),
                                                                    activity?)?;
                                 },
                                 _ = shutdown_rx.changed() => { break }
@@ -250,36 +255,31 @@ impl TestRustWorker {
         };
 
         let myself = pollers.await?;
+        info!("Polling loop exited");
+        let _ = shutdown_tx.send(true);
         while let Some(h) = myself.workflow_half.join_handles.next().await {
             h??;
         }
-        before_shutdown();
-        myself.core.shutdown().await;
+        myself.common.worker.shutdown().await;
         myself.workflow_half.workflows.clear();
         Ok(())
     }
 
-    /// Drives all workflows & activities until they have all finished, repeatedly polls server to
-    /// fetch work for them.
-    pub async fn run_until_done(&mut self) -> Result<(), anyhow::Error> {
-        self.run_until_done_shutdown_hook(|| {}).await
+    /// Set a [WorkerInterceptor]
+    pub fn set_worker_interceptor(&mut self, interceptor: Box<dyn WorkerInterceptor>) {
+        self.common.worker_interceptor = Some(interceptor);
     }
 
-    /// Temporarily swap the core implementation used by this worker. When the returned value is
-    /// dropped, the old core implementation will be restored. This can be used to run against
-    /// mocked-out core instances.
-    pub fn swap_core(&mut self, other_core: Arc<dyn Core>) -> impl DerefMut<Target = Self> + '_ {
-        let old_core = std::mem::replace(&mut self.core, other_core);
-        RustWorkerSwappedCore {
-            old_core: Some(old_core),
-            worker: self,
-        }
+    /// Turns this rust worker into a new worker with all the same workflows and activities
+    /// registered, but with a new underlying core worker. Can be used to swap the worker for
+    /// a replay worker, change task queues, etc.
+    pub fn with_new_core_worker(&mut self, new_core_worker: Arc<dyn CoreWorker>) {
+        self.common.worker = new_core_worker;
     }
 
-    fn split_apart(&mut self) -> (Arc<dyn Core>, &str, &mut WorkflowHalf, &mut ActivityHalf) {
+    fn split_apart(&mut self) -> (&mut CommonWorker, &mut WorkflowHalf, &mut ActivityHalf) {
         (
-            self.core.clone(),
-            &self.task_queue,
+            &mut self.common,
             &mut self.workflow_half,
             &mut self.activity_half,
         )
@@ -289,8 +289,7 @@ impl TestRustWorker {
 impl WorkflowHalf {
     async fn workflow_activation_handler(
         &mut self,
-        core: &dyn Core,
-        task_queue: &str,
+        common: &CommonWorker,
         shutdown_rx: &Receiver<bool>,
         completions_tx: &UnboundedSender<WorkflowActivationCompletion>,
         completions_rx: &mut UnboundedReceiver<WorkflowActivationCompletion>,
@@ -302,14 +301,15 @@ impl WorkflowHalf {
             variant: Some(Variant::StartWorkflow(sw)),
         }) = activation.jobs.get(0)
         {
+            let workflow_type = &sw.workflow_type;
             let wf_function = self
                 .workflow_fns
-                .get(&sw.workflow_type)
-                .ok_or_else(|| anyhow!("Workflow type not found"))?;
+                .get(workflow_type)
+                .ok_or_else(|| anyhow!("Workflow type {workflow_type} not found"))?;
 
             let (wff, activations) = wf_function.start_workflow(
-                core.server_gateway().get_options().namespace.clone(),
-                task_queue.to_string(),
+                common.worker.get_config().namespace.clone(),
+                common.task_queue.clone(),
                 // NOTE: Don't clone args if this gets ported to be a non-test rust worker
                 sw.arguments.clone(),
                 completions_tx.clone(),
@@ -336,11 +336,13 @@ impl WorkflowHalf {
         };
 
         let completion = completions_rx.recv().await.expect("No workflows left?");
-        if completion.has_execution_ending() {
-            debug!("Workflow {} says it's finishing", &completion.run_id);
-            self.incomplete_workflows.fetch_sub(1, Ordering::SeqCst);
+        if let Some(ref i) = common.worker_interceptor {
+            i.on_workflow_activation_completion(&completion);
         }
-        core.complete_workflow_activation(completion).await?;
+        common
+            .worker
+            .complete_workflow_activation(completion)
+            .await?;
         Ok(())
     }
 }
@@ -365,13 +367,11 @@ impl ActivityHalf {
     /// Spawns off a task to handle the provided activity task
     fn activity_task_handler(
         &mut self,
-        core: Arc<dyn Core>,
-        task_queue: &str,
+        worker: Arc<dyn CoreWorker>,
         activity: ActivityTask,
     ) -> Result<(), anyhow::Error> {
         match activity.variant {
             Some(activity_task::Variant::Start(start)) => {
-                let task_queue = task_queue.to_string();
                 let act_fn = self
                     .activity_fns
                     .get(&start.activity_type)
@@ -389,7 +389,7 @@ impl ActivityHalf {
                 tokio::spawn(ACT_CANCEL_TOK.scope(ct, async move {
                     let mut inputs = start.input;
                     let arg = inputs.pop().unwrap_or_default();
-                    let output = (&act_fn.act_func)(arg).await;
+                    let output = (act_fn.act_func)(arg).await;
                     let result = match output {
                         Ok(res) => ActivityExecutionResult::ok(res),
                         Err(err) => match err.downcast::<ActivityCancelledError>() {
@@ -397,12 +397,12 @@ impl ActivityHalf {
                             Err(other_err) => ActivityExecutionResult::fail(other_err.into()),
                         },
                     };
-                    core.complete_activity_task(ActivityTaskCompletion {
-                        task_token: activity.task_token,
-                        task_queue,
-                        result: Some(result),
-                    })
-                    .await?;
+                    worker
+                        .complete_activity_task(ActivityTaskCompletion {
+                            task_token: activity.task_token,
+                            result: Some(result),
+                        })
+                        .await?;
                     Result::<_, anyhow::Error>::Ok(())
                 }));
             }
@@ -553,7 +553,7 @@ enum RustWfCmd {
     NewCmd(CommandCreateRequest),
     NewNonblockingCmd(workflow_command::Variant),
     SubscribeChildWorkflowCompletion(CommandSubscribeChildWorkflowCompletion),
-    SubscribeSignal(String, UnboundedSender<Vec<Payload>>),
+    SubscribeSignal(String, UnboundedSender<SignalData>),
 }
 
 struct CommandCreateRequest {
@@ -669,31 +669,19 @@ where
     }
 }
 
-/// Allows the worker to swap back to an original core instance upon Drop
-struct RustWorkerSwappedCore<'a> {
-    old_core: Option<Arc<dyn Core>>,
-    worker: &'a mut TestRustWorker,
-}
-
-impl<'a> Deref for RustWorkerSwappedCore<'a> {
-    type Target = TestRustWorker;
-
-    fn deref(&self) -> &Self::Target {
-        self.worker
-    }
-}
-
-impl<'a> DerefMut for RustWorkerSwappedCore<'a> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        self.worker
-    }
-}
-
-impl<'a> Drop for RustWorkerSwappedCore<'a> {
-    fn drop(&mut self) {
-        let _ = std::mem::replace(
-            &mut self.worker.core,
-            self.old_core.take().expect("Old core always exists"),
-        );
-    }
+/// Reads own binary, hashes it, and returns b64 str version of that hash
+fn binary_id() -> &'static str {
+    use sha2::{Digest, Sha256};
+    use std::{env, fs, io};
+
+    static INSTANCE: OnceCell<String> = OnceCell::new();
+    INSTANCE.get_or_init(|| {
+        let exe_path = env::current_exe().expect("Cannot read own binary to determine binary id");
+        let mut exe_file =
+            fs::File::open(exe_path).expect("Cannot read own binary to determine binary id");
+        let mut hasher = Sha256::new();
+        io::copy(&mut exe_file, &mut hasher).expect("Copying data into binary hasher works");
+        let hash = hasher.finalize();
+        base64::encode(hash)
+    })
 }

package/sdk-core/sdk/src/workflow_context/options.rs

@@ -1,4 +1,4 @@
-use std::time::Duration;
+use std::{collections::HashMap, time::Duration};
 use temporal_sdk_core_protos::coresdk::{
     child_workflow::ChildWorkflowCancellationType,
     common::{Payload, RetryPolicy},
@@ -178,3 +178,88 @@ impl IntoWorkflowCommand for ChildWorkflowOptions {
         }
     }
 }
+
+/// Options for sending a signal to an external workflow
+pub struct SignalWorkflowOptions {
+    /// The workflow's id
+    pub workflow_id: String,
+    /// The particular run to target, or latest if `None`
+    pub run_id: Option<String>,
+    /// The details of the signal to send
+    pub signal: Signal,
+}
+
+impl SignalWorkflowOptions {
+    /// Create options for sending a signal to another workflow
+    pub fn new(
+        workflow_id: impl Into<String>,
+        run_id: impl Into<String>,
+        name: impl Into<String>,
+        input: impl IntoIterator<Item = impl Into<Payload>>,
+    ) -> Self {
+        Self {
+            workflow_id: workflow_id.into(),
+            run_id: Some(run_id.into()),
+            signal: Signal::new(name, input),
+        }
+    }
+
+    /// Set a header k/v pair attached to the signal
+    pub fn with_header(
+        &mut self,
+        key: impl Into<String>,
+        payload: impl Into<Payload>,
+    ) -> &mut Self {
+        self.signal.data.with_header(key.into(), payload.into());
+        self
+    }
+}
+
+/// Information needed to send a specific signal
+pub struct Signal {
+    /// The signal name
+    pub signal_name: String,
+    /// The data the signal carries
+    pub data: SignalData,
+}
+
+impl Signal {
+    /// Create a new signal
+    pub fn new(
+        name: impl Into<String>,
+        input: impl IntoIterator<Item = impl Into<Payload>>,
+    ) -> Self {
+        Self {
+            signal_name: name.into(),
+            data: SignalData::new(input),
+        }
+    }
+}
+
+/// Data contained within a signal
+pub struct SignalData {
+    /// The arguments the signal will receive
+    pub input: Vec<Payload>,
+    /// Metadata attached to the signal
+    pub headers: HashMap<String, Payload>,
+}
+
+impl SignalData {
+    /// Create data for a signal
+    pub fn new(input: impl IntoIterator<Item = impl Into<Payload>>) -> Self {
+        Self {
+            input: input.into_iter().map(Into::into).collect(),
+            headers: HashMap::new(),
+        }
+    }
+
+    /// Set a header k/v pair attached to the signal
+    pub fn with_header(
+        &mut self,
+        key: impl Into<String>,
+        payload: impl Into<Payload>,
+    ) -> &mut Self {
+        self.headers.insert(key.into(), payload.into());
+        self
+    }
+}