💥 feat(sdk): failure converter + rich error types (#1226)

* initial plan

* Add ApplicationFailure and reshape ActivityError

* Move shared errors and split data_converters

* Implement erased failure classification

* Route workflow/activity failures through converter and update nexus async assertion

* fix: do not nest application failures

* doc: failure converter plan

* add activity error hint

* add child workflow decoding

* child workflow signal decode

* use outgoing error type

* differentiate workflow failures

* enumerate all current failure info options

* hook up query/update handlers

* richer failure error shapes

* activity errors tightening

* surface cancellation failure info

* enhance child workflow execution error

* child signal error type

* update docs

* flesh out activity failure

* prep for child wfl split

* split child start/execution error type

* refactor tests

* failure converter refactor

* add module doc comment

* remove arch docs

* collapse activity failure branches

* pr feedback

* switch from mod.rs to named module file

* serialize details to payload

* chore: add ergonomic constructors for cancellation details

* remove arch doc

* fix cause drops on conversion

* remove redundant test

* use payload converter from data converter

* simplify workflow_message_to_failure

* remove useless LA unit test

* include basic callout of failure conversion in readme

* fix lints

* fix formatting

* add identitiy to cancellation

* fix merge conflict

* special case ApplicationFailure during ActivityError construciton

Author: chris-olszewski

crates/common/Cargo.toml

@@ -107,5 +107,6 @@ workspace = true
 
 [dev-dependencies]
 futures-util = { version = "0.3", default-features = false }
+rstest = "0.26"
 tempfile = "3.21"
 tokio = { version = "1.47", features = ["macros", "rt"] }

crates/common/src/data_converters.rs

@@ -1,7 +1,14 @@
 //! Contains traits for and default implementations of data converters, codecs, and other
 //! serialization related functionality.
 
-use crate::protos::temporal::api::{common::v1::Payload, failure::v1::Failure};
+mod failure_converter;
+
+pub use failure_converter::{
+    ActivityExecutionDecodeHint, ChildWorkflowExecutionDecodeHint, ChildWorkflowSignalDecodeHint,
+    ChildWorkflowStartDecodeHint, DefaultFailureConverter, FailureConverter, FailureDecodeHint,
+};
+
+use crate::protos::temporal::api::common::v1::Payload;
 use futures::{FutureExt, future::BoxFuture};
 use std::{collections::HashMap, sync::Arc};
 
@@ -22,6 +29,7 @@ impl std::fmt::Debug for DataConverter {
             .finish_non_exhaustive()
     }
 }
+
 impl DataConverter {
     /// Create a new DataConverter with the given payload converter, failure converter, and codec.
     pub fn new(
@@ -105,6 +113,34 @@ impl DataConverter {
         &self.payload_converter
     }
 
+    /// Returns the failure converter component of this data converter.
+    pub fn failure_converter(&self) -> &(dyn FailureConverter + Send + Sync) {
+        self.failure_converter.as_ref()
+    }
+
+    /// Decode a Temporal failure into a caller-facing Rust error surface.
+    pub fn to_error<H: FailureDecodeHint>(
+        &self,
+        context: &SerializationContextData,
+        failure: crate::protos::temporal::api::failure::v1::Failure,
+        hint: H,
+    ) -> Result<H::Output, PayloadConversionError> {
+        let normalized =
+            self.failure_converter
+                .to_error(failure, &self.payload_converter, context)?;
+        Ok(hint.adapt(normalized))
+    }
+
+    /// Encode a typed Rust error surface into a Temporal failure.
+    pub fn to_failure(
+        &self,
+        context: &SerializationContextData,
+        error: crate::error::OutgoingError,
+    ) -> crate::protos::temporal::api::failure::v1::Failure {
+        self.failure_converter
+            .to_failure(error, &self.payload_converter, context)
+    }
+
     /// Returns the codec component of this data converter.
     pub fn codec(&self) -> &(dyn PayloadCodec + Send + Sync) {
         self.codec.as_ref()
@@ -196,26 +232,6 @@ impl std::error::Error for PayloadConversionError {
     }
 }
 
-/// Converts between Rust errors and Temporal [`Failure`] protobufs.
-pub trait FailureConverter {
-    /// Convert an error into a Temporal failure protobuf.
-    fn to_failure(
-        &self,
-        error: Box<dyn std::error::Error>,
-        payload_converter: &PayloadConverter,
-        context: &SerializationContextData,
-    ) -> Result<Failure, PayloadConversionError>;
-
-    /// Convert a Temporal failure protobuf back into a Rust error.
-    fn to_error(
-        &self,
-        failure: Failure,
-        payload_converter: &PayloadConverter,
-        context: &SerializationContextData,
-    ) -> Result<Box<dyn std::error::Error>, PayloadConversionError>;
-}
-/// Default (currently unimplemented) failure converter.
-pub struct DefaultFailureConverter;
 /// Encodes and decodes payloads, enabling encryption or compression.
 pub trait PayloadCodec {
     /// Encode payloads before they are sent to the server.
@@ -307,6 +323,53 @@ pub trait TemporalDeserializable: Sized {
     }
 }
 
+/// A codec-decoded set of payloads that can be deserialized later with to a user provided type.
+#[derive(Clone, Debug)]
+pub struct DecodablePayloads {
+    payloads: Vec<Payload>,
+    payload_converter: PayloadConverter,
+    context: SerializationContextData,
+}
+
+impl DecodablePayloads {
+    /// Create a new decodable payload set from raw payloads and the converter context needed to
+    /// deserialize them later.
+    pub fn new(
+        payloads: Vec<Payload>,
+        payload_converter: PayloadConverter,
+        context: SerializationContextData,
+    ) -> Self {
+        Self {
+            payloads,
+            payload_converter,
+            context,
+        }
+    }
+
+    /// Deserialize these payloads into a typed value using the stored payload converter.
+    pub fn deserialize<T: TemporalDeserializable + 'static>(
+        &self,
+    ) -> Result<T, PayloadConversionError> {
+        self.payload_converter.from_payloads(
+            &SerializationContext {
+                data: &self.context,
+                converter: &self.payload_converter,
+            },
+            self.payloads.clone(),
+        )
+    }
+
+    /// Returns the underlying payloads.
+    pub fn raw(&self) -> &[Payload] {
+        &self.payloads
+    }
+
+    /// Consume this value and return the underlying payloads as a [`RawValue`].
+    pub fn into_raw(self) -> RawValue {
+        RawValue::new(self.payloads)
+    }
+}
+
 /// An unconverted set of payloads, used when the caller wants to defer deserialization.
 #[derive(Clone, Debug, Default)]
 pub struct RawValue {
@@ -672,24 +735,6 @@ impl Default for DataConverter {
         )
     }
 }
-impl FailureConverter for DefaultFailureConverter {
-    fn to_failure(
-        &self,
-        _: Box<dyn std::error::Error>,
-        _: &PayloadConverter,
-        _: &SerializationContextData,
-    ) -> Result<Failure, PayloadConversionError> {
-        todo!()
-    }
-    fn to_error(
-        &self,
-        _: Failure,
-        _: &PayloadConverter,
-        _: &SerializationContextData,
-    ) -> Result<Box<dyn std::error::Error>, PayloadConversionError> {
-        todo!()
-    }
-}
 impl PayloadCodec for DefaultPayloadCodec {
     fn encode(
         &self,
@@ -866,4 +911,53 @@ mod tests {
         let args: MultiArgs2<String, i32> = ("hello".to_string(), 42i32).into();
         assert_eq!(args, MultiArgs2("hello".to_string(), 42));
     }
+
+    fn decodable_from_value<T: TemporalSerializable + 'static>(value: &T) -> DecodablePayloads {
+        let converter = PayloadConverter::default();
+        let payloads = converter
+            .to_payloads(
+                &SerializationContext {
+                    data: &SerializationContextData::Workflow,
+                    converter: &converter,
+                },
+                value,
+            )
+            .unwrap();
+        DecodablePayloads::new(payloads, converter, SerializationContextData::Workflow)
+    }
+    #[test]
+    fn decodable_payloads_roundtrip_string() {
+        let payloads = decodable_from_value(&"hello".to_string());
+
+        let result: String = payloads.deserialize().unwrap();
+
+        assert_eq!(result, "hello");
+    }
+
+    #[test]
+    fn decodable_payloads_roundtrip_option_string() {
+        let payloads = decodable_from_value(&Some("hello".to_string()));
+
+        let result: Option<String> = payloads.deserialize().unwrap();
+
+        assert_eq!(result, Some("hello".to_string()));
+    }
+
+    #[test]
+    fn decodable_payloads_roundtrip_unit() {
+        let payloads = decodable_from_value(&());
+
+        let result: () = payloads.deserialize().unwrap();
+
+        assert_eq!(result, ());
+    }
+
+    #[test]
+    fn decodable_payloads_roundtrip_vec_string() {
+        let payloads = decodable_from_value(&vec!["hello".to_string(), "world".to_string()]);
+
+        let result: Vec<String> = payloads.deserialize().unwrap();
+
+        assert_eq!(result, vec!["hello".to_string(), "world".to_string()]);
+    }
 }