@temporalio/core-bridge 1.15.0 → 1.16.1

package/sdk-core/README.md

@@ -7,6 +7,20 @@ Core SDK that can be used as a base for other Temporal SDKs. It is currently use
 - [.NET SDK](https://github.com/temporalio/sdk-dotnet/)
 - [Ruby SDK](https://github.com/temporalio/sdk-ruby/)
 
+# Temporal Rust SDK
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-sdk.svg)](https://crates.io/crates/temporalio-sdk)
+[![docs.rs](https://docs.rs/temporalio-sdk/badge.svg)](https://docs.rs/temporalio-sdk)
+
+Currently prerelease, see more in the [SDK README.md](crates/sdk/README.md)
+
+# Temporal Rust Client
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-sdk.svg)](https://crates.io/crates/temporalio-client)
+[![docs.rs](https://docs.rs/temporalio-sdk/badge.svg)](https://docs.rs/temporalio-client)
+
+Currently prerelease, see more in the [client README.md](crates/client/README.md)
+
 # Documentation
 
 Core SDK documentation can be generated with `cargo doc`, output will be placed in the
@@ -90,7 +104,7 @@ equivalent.
 This repo uses a subtree for upstream protobuf files. The path `crates/common/protos/api_upstream`
 is a subtree. To update it, use:
 
-`git pull --squash --rebase=false -s subtree -Xsubtree=crates/common/protos/api_upstream ssh://git@github.com/temporalio/api.git master --allow-unrelated-histories`
+`git pull --squash --rebase=false -s subtree -X subtree=crates/common/protos/api_upstream ssh://git@github.com/temporalio/api.git master --allow-unrelated-histories`
 
 Do not question why this git command is the way it is. It is not our place to interpret git's ways.
 This same approach can be taken for updating `crates/common/protos/api_cloud_upstream` from the
@@ -127,11 +141,3 @@ Any error which is returned from a public interface should be well-typed, and we
 
 Errors returned from things only used in testing are free to use
 [anyhow](https://github.com/dtolnay/anyhow) for less verbosity.
-
-# The Rust "SDK"
-
-This repo contains a *prototype* Rust sdk in the `sdk/` directory. This SDK should be considered
-pre-alpha in terms of its API surface. Since it's still using Core underneath, it is generally
-functional. We do not currently have any firm plans to productionize this SDK. If you want to write
-workflows and activities in Rust, feel free to use it - but be aware that the API may change at any
-time without warning and we do not provide any support guarantees.

package/sdk-core/crates/client/Cargo.toml

@@ -9,9 +9,11 @@ homepage = "https://temporal.io/"
 repository = "https://github.com/temporalio/sdk-core"
 keywords = ["temporal", "workflow"]
 categories = ["development-tools"]
+readme = "README.md"
 
 [features]
 telemetry = ["dep:opentelemetry"]
+core-based-sdk = []
 
 [dependencies]
 anyhow = "1.0"
@@ -42,10 +44,12 @@ rand = "0.9.2"
 
 [dependencies.temporalio-common]
 path = "../common"
+version = "0.1"
 
 [dev-dependencies]
 assert_matches = "1"
 mockall = "0.13"
+prost = "0.14"
 rstest = "0.26"
 
 [lints]

package/sdk-core/crates/client/README.md

@@ -0,0 +1,139 @@
+# Temporal Rust Client
+
+[![crates.io](https://img.shields.io/crates/v/temporalio-client.svg)](https://crates.io/crates/temporalio-client)
+[![docs.rs](https://docs.rs/temporalio-client/badge.svg)](https://docs.rs/temporalio-client)
+
+This crate provides a Rust client for interacting with the Temporal service. It can be used
+standalone to start and manage workflows, or together with the
+[`temporalio-sdk`](https://crates.io/crates/temporalio-sdk) crate to run workers.
+
+⚠️ **This crate is under active development and should be considered prerelease.** The API can and
+will continue to evolve.
+
+## Quick Start
+
+### Connecting and Starting Workflows
+
+```rust
+use temporalio_client::{
+    Client, ClientOptions, Connection, ConnectionOptions,
+    WorkflowOptions, GetWorkflowResultOptions,
+};
+use temporalio_sdk_core::{Url, CoreRuntime, RuntimeOptions};
+use std::str::FromStr;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let connection = Connection::connect(
+        ConnectionOptions::new(Url::from_str("http://localhost:7233")?)
+            .identity("my-client".to_string())
+            .build()
+    ).await?;
+
+    // "default" is your namespace
+    let client = Client::new(connection, ClientOptions::new("default").build());
+
+    // Start a workflow
+    let handle = client.start_workflow(
+        GreetingWorkflow::run,
+        "World".to_string(),
+        WorkflowOptions::new("my-task-queue", "greeting-workflow-1").build()
+    ).await?;
+
+    // Wait for the result
+    let result = handle.get_result(GetWorkflowResultOptions::default()).await?;
+
+    Ok(())
+}
+```
+
+### Signals, Queries, and Updates
+
+Once you have a workflow handle, you can interact with the running workflow:
+
+```rust
+use temporalio_client::{
+    SignalOptions, QueryOptions, UpdateOptions,
+    StartUpdateOptions, WorkflowUpdateWaitStage,
+    UntypedSignal,
+};
+use temporalio_common::data_converters::{PayloadConverter, RawValue};
+
+// Get a handle to an existing workflow (or use one from start_workflow)
+let handle = client.get_workflow_handle::<MyWorkflow>("workflow-id");
+
+// --- Signals (fire-and-forget messages) ---
+handle.signal(MyWorkflow::push_value, 42, SignalOptions::default()).await?;
+
+// --- Queries (read workflow state) ---
+let values = handle
+    .query(MyWorkflow::get_values, (), QueryOptions::default())
+    .await?;
+
+// --- Updates (modify state and get a result) ---
+let values = handle
+    .execute_update(MyWorkflow::add_wait_return, 100, UpdateOptions::default())
+    .await?;
+
+// Start an update and wait for acceptance only
+let update_handle = handle
+    .start_update(
+        MyWorkflow::add_wait_return,
+        50,
+        StartUpdateOptions::builder()
+            .wait_for_stage(WorkflowUpdateWaitStage::Accepted)
+            .build()
+    )
+    .await?;
+update_handle.get_result().await?;
+
+// --- Untyped interactions (when types aren't known at compile time) ---
+let pc = PayloadConverter::serde_json();
+handle
+    .signal(
+        UntypedSignal::new("increment"),
+        RawValue::from_value(&25i32, &pc),
+        SignalOptions::default(),
+    )
+    .await?;
+// UntypedQuery and UntypedUpdate work similarly
+```
+
+### Cancelling and Terminating Workflows
+
+```rust
+use temporalio_client::{CancelWorkflowOptions, TerminateWorkflowOptions};
+
+// Request cancellation (workflow can handle this gracefully)
+handle.cancel(CancelWorkflowOptions::builder().reason("No longer needed").build()).await?;
+
+// Terminate immediately (workflow cannot intercept this)
+handle.terminate(TerminateWorkflowOptions::builder().reason("Emergency shutdown").build()).await?;
+```
+
+### Listing Workflows
+
+```rust
+use temporalio_client::ListWorkflowsOptions;
+use futures_util::StreamExt;
+
+let mut stream = client.list_workflows(
+    "WorkflowType = 'GreetingWorkflow'",
+    ListWorkflowsOptions::builder().limit(10).build()
+);
+
+while let Some(result) = stream.next().await {
+    let execution = result?;
+    println!("Workflow: {} ({})", execution.id(), execution.workflow_type());
+}
+```
+
+## Raw gRPC Access
+
+For operations not covered by the high-level API, access the underlying gRPC service clients
+directly:
+
+```rust
+let mut workflowf_service = client.connection().workflow_service();
+let mut operator_service = client.connection().operator_service();
+```

package/sdk-core/crates/client/src/async_activity_handle.rs

@@ -0,0 +1,297 @@
+//! Handle for completing activities asynchronously via a client.
+
+use crate::{NamespacedClient, errors::AsyncActivityError, grpc::WorkflowService};
+use temporalio_common::protos::{
+    TaskToken,
+    temporal::api::{
+        common::v1::Payloads,
+        failure::v1::Failure,
+        workflowservice::v1::{
+            RecordActivityTaskHeartbeatByIdRequest, RecordActivityTaskHeartbeatByIdResponse,
+            RecordActivityTaskHeartbeatRequest, RecordActivityTaskHeartbeatResponse,
+            RespondActivityTaskCanceledByIdRequest, RespondActivityTaskCanceledRequest,
+            RespondActivityTaskCompletedByIdRequest, RespondActivityTaskCompletedRequest,
+            RespondActivityTaskFailedByIdRequest, RespondActivityTaskFailedRequest,
+        },
+    },
+};
+use tonic::IntoRequest;
+
+/// Identifies an async activity for completion outside a worker.
+#[derive(Debug, Clone)]
+pub enum ActivityIdentifier {
+    /// Identify activity by its task token
+    TaskToken(TaskToken),
+    /// Identify activity by workflow and activity IDs.
+    ById {
+        /// ID of the workflow that scheduled this activity.
+        workflow_id: String,
+        /// Run ID of the workflow (optional - if not provided, targets the latest run).
+        run_id: String,
+        /// ID of the activity to complete.
+        activity_id: String,
+    },
+}
+
+impl ActivityIdentifier {
+    /// Create an identifier from a task token.
+    pub fn from_task_token(token: TaskToken) -> Self {
+        Self::TaskToken(token)
+    }
+
+    /// Create an identifier from workflow and activity IDs. Use an empty run id to target the
+    /// latest workflow execution.
+    pub fn by_id(
+        workflow_id: impl Into<String>,
+        run_id: impl Into<String>,
+        activity_id: impl Into<String>,
+    ) -> Self {
+        Self::ById {
+            workflow_id: workflow_id.into(),
+            run_id: run_id.into(),
+            activity_id: activity_id.into(),
+        }
+    }
+}
+
+/// Handle for completing activities asynchronously (outside the worker).
+pub struct AsyncActivityHandle<CT> {
+    client: CT,
+    identifier: ActivityIdentifier,
+}
+
+impl<CT> AsyncActivityHandle<CT> {
+    /// Create a new async activity handle.
+    pub fn new(client: CT, identifier: ActivityIdentifier) -> Self {
+        Self { client, identifier }
+    }
+
+    /// Get the identifier for this activity.
+    pub fn identifier(&self) -> &ActivityIdentifier {
+        &self.identifier
+    }
+
+    /// Get a reference to the underlying client.
+    pub fn client(&self) -> &CT {
+        &self.client
+    }
+}
+
+impl<CT: WorkflowService + NamespacedClient + Clone> AsyncActivityHandle<CT> {
+    /// Complete the activity with a successful result.
+    pub async fn complete(&self, result: Option<Payloads>) -> Result<(), AsyncActivityError> {
+        match &self.identifier {
+            ActivityIdentifier::TaskToken(token) => {
+                WorkflowService::respond_activity_task_completed(
+                    &mut self.client.clone(),
+                    RespondActivityTaskCompletedRequest {
+                        task_token: token.0.clone(),
+                        result,
+                        identity: self.client.identity(),
+                        namespace: self.client.namespace(),
+                        ..Default::default()
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+            ActivityIdentifier::ById {
+                workflow_id,
+                run_id,
+                activity_id,
+            } => {
+                WorkflowService::respond_activity_task_completed_by_id(
+                    &mut self.client.clone(),
+                    RespondActivityTaskCompletedByIdRequest {
+                        namespace: self.client.namespace(),
+                        workflow_id: workflow_id.clone(),
+                        run_id: run_id.clone(),
+                        activity_id: activity_id.clone(),
+                        result,
+                        identity: self.client.identity(),
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Fail the activity with a failure.
+    pub async fn fail(
+        &self,
+        failure: Failure,
+        last_heartbeat_details: Option<Payloads>,
+    ) -> Result<(), AsyncActivityError> {
+        match &self.identifier {
+            ActivityIdentifier::TaskToken(token) => {
+                WorkflowService::respond_activity_task_failed(
+                    &mut self.client.clone(),
+                    RespondActivityTaskFailedRequest {
+                        task_token: token.0.clone(),
+                        failure: Some(failure),
+                        identity: self.client.identity(),
+                        namespace: self.client.namespace(),
+                        last_heartbeat_details,
+                        ..Default::default()
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+            ActivityIdentifier::ById {
+                workflow_id,
+                run_id,
+                activity_id,
+            } => {
+                WorkflowService::respond_activity_task_failed_by_id(
+                    &mut self.client.clone(),
+                    RespondActivityTaskFailedByIdRequest {
+                        namespace: self.client.namespace(),
+                        workflow_id: workflow_id.clone(),
+                        run_id: run_id.clone(),
+                        activity_id: activity_id.clone(),
+                        failure: Some(failure),
+                        identity: self.client.identity(),
+                        last_heartbeat_details,
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Reports the activity as canceled.
+    pub async fn report_cancelation(
+        &self,
+        details: Option<Payloads>,
+    ) -> Result<(), AsyncActivityError> {
+        match &self.identifier {
+            ActivityIdentifier::TaskToken(token) => {
+                WorkflowService::respond_activity_task_canceled(
+                    &mut self.client.clone(),
+                    RespondActivityTaskCanceledRequest {
+                        task_token: token.0.clone(),
+                        details,
+                        identity: self.client.identity(),
+                        namespace: self.client.namespace(),
+                        ..Default::default()
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+            ActivityIdentifier::ById {
+                workflow_id,
+                run_id,
+                activity_id,
+            } => {
+                WorkflowService::respond_activity_task_canceled_by_id(
+                    &mut self.client.clone(),
+                    RespondActivityTaskCanceledByIdRequest {
+                        namespace: self.client.namespace(),
+                        workflow_id: workflow_id.clone(),
+                        run_id: run_id.clone(),
+                        activity_id: activity_id.clone(),
+                        details,
+                        identity: self.client.identity(),
+                        ..Default::default()
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?;
+            }
+        }
+        Ok(())
+    }
+
+    /// Record a heartbeat for the activity.
+    ///
+    /// Heartbeats let the server know the activity is still running and can carry
+    /// progress information. The response indicates if cancellation has been requested.
+    pub async fn heartbeat(
+        &self,
+        details: Option<Payloads>,
+    ) -> Result<ActivityHeartbeatResponse, AsyncActivityError> {
+        match &self.identifier {
+            ActivityIdentifier::TaskToken(token) => {
+                let resp = WorkflowService::record_activity_task_heartbeat(
+                    &mut self.client.clone(),
+                    RecordActivityTaskHeartbeatRequest {
+                        task_token: token.0.clone(),
+                        details,
+                        identity: self.client.identity(),
+                        namespace: self.client.namespace(),
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?
+                .into_inner();
+                Ok(ActivityHeartbeatResponse::from(resp))
+            }
+            ActivityIdentifier::ById {
+                workflow_id,
+                run_id,
+                activity_id,
+            } => {
+                let resp = WorkflowService::record_activity_task_heartbeat_by_id(
+                    &mut self.client.clone(),
+                    RecordActivityTaskHeartbeatByIdRequest {
+                        namespace: self.client.namespace(),
+                        workflow_id: workflow_id.clone(),
+                        run_id: run_id.clone(),
+                        activity_id: activity_id.clone(),
+                        details,
+                        identity: self.client.identity(),
+                    }
+                    .into_request(),
+                )
+                .await
+                .map_err(AsyncActivityError::from_status)?
+                .into_inner();
+                Ok(ActivityHeartbeatResponse::from(resp))
+            }
+        }
+    }
+}
+
+/// Response from a heartbeat call.
+#[derive(Debug, Clone)]
+pub struct ActivityHeartbeatResponse {
+    /// True if the activity has been asked to cancel itself.
+    pub cancel_requested: bool,
+    /// True if the activity is paused.
+    pub activity_paused: bool,
+    /// True if the activity was reset.
+    pub activity_reset: bool,
+}
+
+impl From<RecordActivityTaskHeartbeatResponse> for ActivityHeartbeatResponse {
+    fn from(resp: RecordActivityTaskHeartbeatResponse) -> Self {
+        Self {
+            cancel_requested: resp.cancel_requested,
+            activity_paused: resp.activity_paused,
+            activity_reset: resp.activity_reset,
+        }
+    }
+}
+
+impl From<RecordActivityTaskHeartbeatByIdResponse> for ActivityHeartbeatResponse {
+    fn from(resp: RecordActivityTaskHeartbeatByIdResponse) -> Self {
+        Self {
+            cancel_requested: resp.cancel_requested,
+            activity_paused: resp.activity_paused,
+            activity_reset: resp.activity_reset,
+        }
+    }
+}

package/sdk-core/crates/client/src/callback_based.rs

@@ -15,6 +15,7 @@ use tonic::{Status, metadata::GRPC_CONTENT_TYPE};
 use tower::Service;
 
 /// gRPC request for use by a callback.
+#[derive(Debug)]
 pub struct GrpcRequest {
     /// Fully qualified gRPC service name.
     pub service: String,
@@ -27,6 +28,7 @@ pub struct GrpcRequest {
 }
 
 /// Successful gRPC response returned by a callback.
+#[derive(Debug)]
 pub struct GrpcSuccessResponse {
     /// Response headers.
     pub headers: HeaderMap,
@@ -46,6 +48,11 @@ pub struct CallbackBasedGrpcService {
             + Sync,
     >,
 }
+impl std::fmt::Debug for CallbackBasedGrpcService {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("CallbackBasedGrpcService").finish()
+    }
+}
 
 impl Service<Request<tonic::body::Body>> for CallbackBasedGrpcService {
     type Response = http::Response<tonic::body::Body>;