@temporalio/core-bridge 1.14.2-canary-release-testing.0 → 1.16.0

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>;

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

@@ -0,0 +1,294 @@
+//! Contains errors that can be returned by clients.
+
+use http::uri::InvalidUri;
+use temporalio_common::{
+    data_converters::PayloadConversionError,
+    protos::temporal::api::{common::v1::Payload, failure::v1::Failure, query::v1::QueryRejected},
+};
+use tonic::Code;
+
+/// Errors thrown while attempting to establish a connection to the server
+#[derive(thiserror::Error, Debug)]
+#[non_exhaustive]
+pub enum ClientConnectError {
+    /// Invalid URI. Configuration error, fatal.
+    #[error("Invalid URI: {0:?}")]
+    InvalidUri(#[from] InvalidUri),
+    /// Invalid gRPC metadata headers. Configuration error.
+    #[error("Invalid headers: {0}")]
+    InvalidHeaders(#[from] InvalidHeaderError),
+    /// Server connection error. Crashing and restarting the worker is likely best.
+    #[error("Server connection error: {0:?}")]
+    TonicTransportError(#[from] tonic::transport::Error),
+    /// We couldn't successfully make the `get_system_info` call at connection time to establish
+    /// server capabilities / verify server is responding.
+    #[error("`get_system_info` call error after connection: {0:?}")]
+    SystemInfoCallError(tonic::Status),
+}
+
+/// Errors thrown when a gRPC metadata header is invalid.
+#[derive(thiserror::Error, Debug)]
+#[non_exhaustive]
+pub enum InvalidHeaderError {
+    /// A binary header key was invalid
+    #[error("Invalid binary header key '{key}': {source}")]
+    InvalidBinaryHeaderKey {
+        /// The invalid key
+        key: String,
+        /// The source error from tonic
+        source: tonic::metadata::errors::InvalidMetadataKey,
+    },
+    /// An ASCII header key was invalid
+    #[error("Invalid ASCII header key '{key}': {source}")]
+    InvalidAsciiHeaderKey {
+        /// The invalid key
+        key: String,
+        /// The source error from tonic
+        source: tonic::metadata::errors::InvalidMetadataKey,
+    },
+    /// An ASCII header value was invalid
+    #[error("Invalid ASCII header value for key '{key}': {source}")]
+    InvalidAsciiHeaderValue {
+        /// The key
+        key: String,
+        /// The invalid value
+        value: String,
+        /// The source error from tonic
+        source: tonic::metadata::errors::InvalidMetadataValue,
+    },
+}
+
+/// Errors that can occur when starting a workflow.
+#[derive(thiserror::Error, Debug)]
+#[non_exhaustive]
+pub enum WorkflowStartError {
+    /// The workflow already exists.
+    #[error("Workflow already started with run ID: {run_id:?}")]
+    AlreadyStarted {
+        /// Run ID of the already-started workflow if this was raised by the client.
+        run_id: Option<String>,
+        /// The original gRPC status from the server.
+        #[source]
+        source: tonic::Status,
+    },
+    /// Error converting the input to a payload.
+    #[error("Failed to serialize workflow input: {0}")]
+    PayloadConversion(#[from] PayloadConversionError),
+    /// An uncategorized rpc error from the server.
+    #[error("Server error: {0}")]
+    Rpc(#[from] tonic::Status),
+}
+
+/// Errors returned by query operations on [crate::WorkflowHandle].
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum WorkflowQueryError {
+    /// The workflow was not found.
+    #[error("Workflow not found")]
+    NotFound(#[source] tonic::Status),
+
+    /// The query was rejected based on the rejection condition.
+    #[error("Query rejected: workflow status {:?}", .0.status)]
+    Rejected(QueryRejected),
+
+    /// Error serializing input or deserializing output.
+    #[error("Payload conversion error: {0}")]
+    PayloadConversion(#[from] PayloadConversionError),
+
+    /// An uncategorized RPC error from the server.
+    #[error("Server error: {0}")]
+    Rpc(tonic::Status),
+
+    /// Other errors.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
+}
+
+impl WorkflowQueryError {
+    pub(crate) fn from_status(status: tonic::Status) -> Self {
+        if status.code() == Code::NotFound {
+            Self::NotFound(status)
+        } else {
+            Self::Rpc(status)
+        }
+    }
+}
+
+/// Errors returned by update operations on [crate::WorkflowHandle].
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum WorkflowUpdateError {
+    /// The workflow was not found.
+    #[error("Workflow not found")]
+    NotFound(#[source] tonic::Status),
+
+    /// The update failed with an application-level failure.
+    #[error("Update failed: {0:?}")]
+    Failed(Box<Failure>),
+
+    /// Error serializing input or deserializing output.
+    #[error("Payload conversion error: {0}")]
+    PayloadConversion(#[from] PayloadConversionError),
+
+    /// An uncategorized RPC error from the server.
+    #[error("Server error: {0}")]
+    Rpc(tonic::Status),
+
+    /// Other errors.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
+}
+
+impl WorkflowUpdateError {
+    pub(crate) fn from_status(status: tonic::Status) -> Self {
+        if status.code() == Code::NotFound {
+            Self::NotFound(status)
+        } else {
+            Self::Rpc(status)
+        }
+    }
+}
+
+/// Errors returned by workflow get_result operations.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum WorkflowGetResultError {
+    /// The workflow finished in failure.
+    #[error("Workflow failed: {0:?}")]
+    Failed(Box<Failure>),
+
+    /// The workflow was cancelled.
+    #[error("Workflow cancelled")]
+    Cancelled {
+        /// Details provided at cancellation time.
+        details: Vec<Payload>,
+    },
+
+    /// The workflow was terminated.
+    #[error("Workflow terminated")]
+    Terminated {
+        /// Details provided at termination time.
+        details: Vec<Payload>,
+    },
+
+    /// The workflow timed out.
+    #[error("Workflow timed out")]
+    TimedOut,
+
+    /// The workflow continued as new.
+    #[error("Workflow continued as new")]
+    ContinuedAsNew,
+
+    /// The workflow was not found.
+    #[error("Workflow not found")]
+    NotFound(#[source] tonic::Status),
+
+    /// Error serializing input or deserializing output.
+    #[error("Payload conversion error: {0}")]
+    PayloadConversion(#[from] PayloadConversionError),
+
+    /// An uncategorized RPC error from the server.
+    #[error("Server error: {0}")]
+    Rpc(tonic::Status),
+
+    /// Other errors.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
+}
+
+impl From<WorkflowInteractionError> for WorkflowGetResultError {
+    fn from(err: WorkflowInteractionError) -> Self {
+        match err {
+            WorkflowInteractionError::NotFound(s) => Self::NotFound(s),
+            WorkflowInteractionError::PayloadConversion(e) => Self::PayloadConversion(e),
+            WorkflowInteractionError::Rpc(s) => Self::Rpc(s),
+            WorkflowInteractionError::Other(e) => Self::Other(e),
+        }
+    }
+}
+
+impl WorkflowGetResultError {
+    /// Returns `true` if this error represents a workflow-level non-success outcome
+    /// (Failed, Cancelled, Terminated, TimedOut, or ContinuedAsNew) rather than an
+    /// infrastructure/RPC error.
+    pub fn is_workflow_outcome(&self) -> bool {
+        matches!(
+            self,
+            Self::Failed(_)
+                | Self::Cancelled { .. }
+                | Self::Terminated { .. }
+                | Self::TimedOut
+                | Self::ContinuedAsNew
+        )
+    }
+}
+
+/// Errors returned by client methods that don't need more specific error types.
+#[derive(thiserror::Error, Debug)]
+#[non_exhaustive]
+pub enum ClientError {
+    /// An uncategorized rpc error from the server.
+    #[error("Server error: {0}")]
+    Rpc(#[from] tonic::Status),
+}
+
+/// Errors returned by methods on [crate::WorkflowHandle] for general operations
+/// like signal, cancel, terminate, describe, fetch_history, and get_result.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum WorkflowInteractionError {
+    /// The workflow was not found.
+    #[error("Workflow not found")]
+    NotFound(#[source] tonic::Status),
+
+    /// Error serializing input or deserializing output.
+    #[error("Payload conversion error: {0}")]
+    PayloadConversion(#[from] PayloadConversionError),
+
+    /// An uncategorized RPC error from the server.
+    #[error("Server error: {0}")]
+    Rpc(tonic::Status),
+
+    /// Other errors.
+    #[error(transparent)]
+    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
+}
+
+impl WorkflowInteractionError {
+    pub(crate) fn from_status(status: tonic::Status) -> Self {
+        if status.code() == Code::NotFound {
+            Self::NotFound(status)
+        } else {
+            Self::Rpc(status)
+        }
+    }
+}
+
+/// Errors that can occur when completing an activity asynchronously.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum AsyncActivityError {
+    /// The activity was not found (e.g., already completed, cancelled, or never existed).
+    #[error("Activity not found")]
+    NotFound(#[source] tonic::Status),
+    /// An uncategorized rpc error from the server.
+    #[error("Server error: {0}")]
+    Rpc(#[from] tonic::Status),
+}
+
+impl AsyncActivityError {
+    pub(crate) fn from_status(status: tonic::Status) -> Self {
+        if status.code() == Code::NotFound {
+            Self::NotFound(status)
+        } else {
+            Self::Rpc(status)
+        }
+    }
+}
+
+/// Errors that can occur when constructing a [`crate::Client`].
+///
+/// Currently has no variants, but may be extended in the future.
+#[derive(Debug, thiserror::Error)]
+#[non_exhaustive]
+pub enum ClientNewError {}