Preserve Persisted Error Classification

Expose persisted and replay error classification in core so the
FFI can preserve storage, transient, fatal, and fatal-with-state
semantics.

This keeps sender and receiver bindings from losing recovery
guidance at the persistence boundary, and it snapshots replay
failures with stable kind and detail accessors. The receiver save
helpers now retain replyable error state instead of flattening it
into implementation errors, which lets bindings continue the
protocol after fatal-with-state failures.

Author: chavic

payjoin-ffi/src/error.rs

@@ -17,6 +17,20 @@ impl From<ImplementationError> for payjoin::ImplementationError {
     fn from(value: ImplementationError) -> Self { value.0 }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)]
+pub enum ReplayErrorKind {
+    NoEvents,
+    InvalidEvent,
+    Expired,
+    PersistenceFailure,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)]
+pub enum ReplayInvalidEventKind {
+    InitialEvent,
+    SessionTransition,
+}
+
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error("Error de/serializing JSON object: {0}")]
 pub struct SerdeJsonError(#[from] serde_json::Error);

payjoin-ffi/src/receive/error.rs

@@ -1,8 +1,14 @@
 use std::sync::Arc;
 
+use payjoin::error::ReplayErrorVariant as CoreReplayErrorVariant;
+use payjoin::persist::PersistedErrorVariant;
 use payjoin::receive;
 
-use crate::error::{FfiValidationError, ImplementationError};
+use crate::error::{
+    FfiValidationError, ImplementationError, ReplayErrorKind as FfiReplayErrorKind,
+    ReplayInvalidEventKind as FfiReplayInvalidEventKind,
+};
+use crate::receive::HasReplyableError;
 use crate::uri::error::IntoUrlError;
 
 /// The top-level error type for the payjoin receiver
@@ -40,20 +46,36 @@ impl From<receive::Error> for ReceiverError {
 
 /// Error that may occur during state machine transitions
 #[derive(Debug, thiserror::Error, uniffi::Error)]
-#[error(transparent)]
 pub enum ReceiverPersistedError {
-    /// rust-payjoin receiver error
-    #[error(transparent)]
-    Receiver(ReceiverError),
-    /// Storage error that could occur at application storage layer
+    /// Storage failure while persisting session state.
     #[error(transparent)]
     Storage(Arc<ImplementationError>),
+    /// Retry the same receiver transition from the current session state.
+    #[error("Transient receiver error: {error}")]
+    Transient { error: ReceiverError },
+    /// The receiver session terminated and should not be resumed.
+    #[error("Fatal receiver error: {error}")]
+    Fatal { error: ReceiverError },
+    /// The receiver transitioned into a replyable error state.
+    ///
+    /// Continue the protocol with the returned `state` to reply to the sender.
+    #[error("Fatal receiver error with state: {error}")]
+    FatalWithState { error: ReceiverError, state: Arc<HasReplyableError> },
+    /// Unexpected error shape that should not occur for receiver transitions.
+    #[error("An unexpected error occurred")]
+    Unexpected,
 }
 
 impl From<ImplementationError> for ReceiverPersistedError {
     fn from(value: ImplementationError) -> Self { ReceiverPersistedError::Storage(Arc::new(value)) }
 }
 
+impl From<crate::error::ForeignError> for ReceiverPersistedError {
+    fn from(value: crate::error::ForeignError) -> Self {
+        ReceiverPersistedError::from(ImplementationError::new(value))
+    }
+}
+
 macro_rules! impl_persisted_error_from {
     (
         $api_error_ty:ty,
@@ -64,16 +86,16 @@ macro_rules! impl_persisted_error_from {
             S: std::error::Error + Send + Sync + 'static,
         {
             fn from(err: payjoin::persist::PersistedError<$api_error_ty, S>) -> Self {
-                if err.storage_error_ref().is_some() {
-                    if let Some(storage_err) = err.storage_error() {
-                        return ReceiverPersistedError::from(ImplementationError::new(storage_err));
-                    }
-                    return ReceiverPersistedError::Receiver(ReceiverError::Unexpected);
-                }
-                if let Some(api_err) = err.api_error() {
-                    return ReceiverPersistedError::Receiver($receiver_arm(api_err));
+                match err.into_variant() {
+                    PersistedErrorVariant::Storage(storage_err) =>
+                        ReceiverPersistedError::from(ImplementationError::new(storage_err)),
+                    PersistedErrorVariant::Transient(api_err) =>
+                        ReceiverPersistedError::Transient { error: $receiver_arm(api_err) },
+                    PersistedErrorVariant::Fatal(api_err) =>
+                        ReceiverPersistedError::Fatal { error: $receiver_arm(api_err) },
+                    PersistedErrorVariant::FatalWithState(_, _) =>
+                        ReceiverPersistedError::Unexpected,
                 }
-                ReceiverPersistedError::Receiver(ReceiverError::Unexpected)
             }
         }
     };
@@ -89,6 +111,47 @@ impl_persisted_error_from!(payjoin::IntoUrlError, |api_err: payjoin::IntoUrlErro
     ReceiverError::IntoUrl(Arc::new(api_err.into()))
 });
 
+impl_persisted_error_from!(
+    payjoin::ImplementationError,
+    |api_err: payjoin::ImplementationError| {
+        ReceiverError::Implementation(Arc::new(api_err.into()))
+    }
+);
+
+impl<S>
+    From<
+        payjoin::persist::PersistedError<
+            receive::Error,
+            S,
+            payjoin::receive::v2::Receiver<payjoin::receive::v2::HasReplyableError>,
+        >,
+    > for ReceiverPersistedError
+where
+    S: std::error::Error + Send + Sync + 'static,
+{
+    fn from(
+        err: payjoin::persist::PersistedError<
+            receive::Error,
+            S,
+            payjoin::receive::v2::Receiver<payjoin::receive::v2::HasReplyableError>,
+        >,
+    ) -> Self {
+        match err.into_variant() {
+            PersistedErrorVariant::Storage(storage_err) =>
+                ReceiverPersistedError::from(ImplementationError::new(storage_err)),
+            PersistedErrorVariant::Transient(api_err) =>
+                ReceiverPersistedError::Transient { error: api_err.into() },
+            PersistedErrorVariant::Fatal(api_err) =>
+                ReceiverPersistedError::Fatal { error: api_err.into() },
+            PersistedErrorVariant::FatalWithState(api_err, state) =>
+                ReceiverPersistedError::FatalWithState {
+                    error: api_err.into(),
+                    state: Arc::new(state.into()),
+                },
+        }
+    }
+}
+
 /// Error that may occur when building a receiver session.
 #[derive(Debug, thiserror::Error, uniffi::Error)]
 #[non_exhaustive]
@@ -231,9 +294,233 @@ impl From<FfiValidationError> for InputPairError {
     fn from(value: FfiValidationError) -> Self { InputPairError::FfiValidation(value) }
 }
 
-/// Error that may occur when a receiver event log is replayed
+/// Error that may occur when a receiver event log is replayed.
 #[derive(Debug, thiserror::Error, uniffi::Object)]
-#[error(transparent)]
-pub struct ReceiverReplayError(
-    #[from] payjoin::error::ReplayError<receive::v2::ReceiveSession, receive::v2::SessionEvent>,
-);
+#[error("{message}")]
+pub struct ReceiverReplayError {
+    kind: FfiReplayErrorKind,
+    message: String,
+    invalid_event_kind: Option<FfiReplayInvalidEventKind>,
+    expired_at_unix_seconds: Option<u32>,
+    persistence_failure: Option<Arc<ImplementationError>>,
+}
+
+impl From<payjoin::error::ReplayError<receive::v2::ReceiveSession, receive::v2::SessionEvent>>
+    for ReceiverReplayError
+{
+    fn from(
+        value: payjoin::error::ReplayError<receive::v2::ReceiveSession, receive::v2::SessionEvent>,
+    ) -> Self {
+        let message = value.to_string();
+        match value.into_variant() {
+            CoreReplayErrorVariant::NoEvents => Self {
+                kind: FfiReplayErrorKind::NoEvents,
+                message,
+                invalid_event_kind: None,
+                expired_at_unix_seconds: None,
+                persistence_failure: None,
+            },
+            CoreReplayErrorVariant::InvalidFirstEvent => Self {
+                kind: FfiReplayErrorKind::InvalidEvent,
+                message,
+                invalid_event_kind: Some(FfiReplayInvalidEventKind::InitialEvent),
+                expired_at_unix_seconds: None,
+                persistence_failure: None,
+            },
+            CoreReplayErrorVariant::InvalidEventForState => Self {
+                kind: FfiReplayErrorKind::InvalidEvent,
+                message,
+                invalid_event_kind: Some(FfiReplayInvalidEventKind::SessionTransition),
+                expired_at_unix_seconds: None,
+                persistence_failure: None,
+            },
+            CoreReplayErrorVariant::Expired { expired_at_unix_seconds } => Self {
+                kind: FfiReplayErrorKind::Expired,
+                message,
+                invalid_event_kind: None,
+                expired_at_unix_seconds: Some(expired_at_unix_seconds),
+                persistence_failure: None,
+            },
+            CoreReplayErrorVariant::PersistenceFailure(error) => Self {
+                kind: FfiReplayErrorKind::PersistenceFailure,
+                message,
+                invalid_event_kind: None,
+                expired_at_unix_seconds: None,
+                persistence_failure: Some(Arc::new(error.into())),
+            },
+        }
+    }
+}
+
+#[uniffi::export]
+impl ReceiverReplayError {
+    pub fn kind(&self) -> FfiReplayErrorKind { self.kind }
+
+    pub fn message(&self) -> String { self.message.clone() }
+
+    pub fn invalid_event_kind(&self) -> Option<FfiReplayInvalidEventKind> {
+        self.invalid_event_kind
+    }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.expired_at_unix_seconds }
+
+    pub fn persistence_failure(&self) -> Option<Arc<ImplementationError>> {
+        self.persistence_failure.clone()
+    }
+}
+
+#[cfg(all(test, feature = "_test-utils"))]
+mod tests {
+    use std::sync::{Arc, Mutex};
+    use std::time::Duration;
+
+    use payjoin_test_utils::TestServices;
+    use tokio::time::sleep;
+
+    use super::ReceiverPersistedError;
+    use crate::error::{ForeignError, ReplayErrorKind};
+    use crate::receive::{
+        InitializedTransitionOutcome, JsonReceiverSessionPersister, ReceiverBuilder,
+    };
+    use crate::send::{JsonSenderSessionPersister, SenderBuilder};
+
+    #[derive(Default)]
+    struct InMemoryReceiverPersister {
+        events: Mutex<Vec<String>>,
+    }
+
+    impl JsonReceiverSessionPersister for InMemoryReceiverPersister {
+        fn save(&self, event: String) -> Result<(), ForeignError> {
+            self.events.lock().expect("lock").push(event);
+            Ok(())
+        }
+
+        fn load(&self) -> Result<Vec<String>, ForeignError> {
+            Ok(self.events.lock().expect("lock").clone())
+        }
+
+        fn close(&self) -> Result<(), ForeignError> { Ok(()) }
+    }
+
+    #[derive(Default)]
+    struct InMemorySenderPersister {
+        events: Mutex<Vec<String>>,
+    }
+
+    impl JsonSenderSessionPersister for InMemorySenderPersister {
+        fn save(&self, event: String) -> Result<(), ForeignError> {
+            self.events.lock().expect("lock").push(event);
+            Ok(())
+        }
+
+        fn load(&self) -> Result<Vec<String>, ForeignError> {
+            Ok(self.events.lock().expect("lock").clone())
+        }
+
+        fn close(&self) -> Result<(), ForeignError> { Ok(()) }
+    }
+
+    #[derive(Default)]
+    struct EmptyReceiverPersister;
+
+    impl JsonReceiverSessionPersister for EmptyReceiverPersister {
+        fn save(&self, _: String) -> Result<(), ForeignError> { Ok(()) }
+
+        fn load(&self) -> Result<Vec<String>, ForeignError> { Ok(Vec::new()) }
+
+        fn close(&self) -> Result<(), ForeignError> { Ok(()) }
+    }
+
+    struct RejectBroadcast;
+
+    impl crate::receive::CanBroadcast for RejectBroadcast {
+        fn callback(&self, _: Vec<u8>) -> Result<bool, ForeignError> { Ok(false) }
+    }
+
+    async fn post_request(services: &TestServices, request: crate::Request) -> Vec<u8> {
+        let response = services
+            .http_agent()
+            .post(request.url)
+            .header("Content-Type", request.content_type)
+            .body(request.body)
+            .send()
+            .await
+            .expect("request should succeed");
+        response.bytes().await.expect("response bytes").to_vec()
+    }
+
+    #[tokio::test]
+    async fn test_receiver_persisted_error_preserves_fatal_with_state() {
+        let services = TestServices::initialize().await.expect("services initialize");
+        services.wait_for_services_ready().await.expect("services ready");
+
+        let receiver_persister = Arc::new(InMemoryReceiverPersister::default());
+        let initialized = ReceiverBuilder::new(
+            "2N47mmrWXsNBvQR6k78hWJoTji57zXwNcU7".to_string(),
+            services.directory_url(),
+            Arc::new(services.fetch_ohttp_keys().await.expect("fetch ohttp keys").into()),
+        )
+        .expect("receiver builder")
+        .build()
+        .save(receiver_persister.clone())
+        .expect("save initialized receiver");
+
+        let sender_persister = Arc::new(InMemorySenderPersister::default());
+        let with_reply_key =
+            SenderBuilder::new(crate::test_utils::original_psbt(), Arc::new(initialized.pj_uri()))
+                .expect("sender builder")
+                .build_recommended(1000)
+                .expect("build sender")
+                .save(sender_persister)
+                .expect("save sender");
+
+        let sender_request =
+            with_reply_key.create_v2_post_request(services.ohttp_relay_url()).unwrap();
+        let _ = post_request(&services, sender_request.request).await;
+
+        let mut initialized = initialized;
+        let unchecked = loop {
+            let poll = initialized.create_poll_request(services.ohttp_relay_url()).unwrap();
+            let response = post_request(&services, poll.request).await;
+            let outcome = initialized
+                .process_response(&response, poll.client_response.as_ref())
+                .save(receiver_persister.clone())
+                .expect("persist initialized transition");
+            match outcome {
+                InitializedTransitionOutcome::Progress { inner } => break inner,
+                InitializedTransitionOutcome::Stasis { inner } => {
+                    initialized = Arc::unwrap_or_clone(inner);
+                    sleep(Duration::from_millis(20)).await;
+                }
+            }
+        };
+
+        let error = unchecked
+            .check_broadcast_suitability(None, Arc::new(RejectBroadcast))
+            .expect("validation inputs")
+            .save(receiver_persister);
+        let error = match error {
+            Ok(_) => panic!("non-broadcastable original should produce replyable error state"),
+            Err(error) => error,
+        };
+
+        match error {
+            ReceiverPersistedError::FatalWithState { state, .. } => {
+                state.create_error_request(services.ohttp_relay_url()).expect("state preserved");
+            }
+            other => panic!("unexpected receiver persisted error: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_receiver_replay_error_exposes_no_events_kind() {
+        let error =
+            match crate::receive::replay_receiver_event_log(Arc::new(EmptyReceiverPersister)) {
+                Ok(_) => panic!("empty event log should fail"),
+                Err(error) => error,
+            };
+        assert_eq!(error.kind(), ReplayErrorKind::NoEvents);
+        assert!(error.persistence_failure().is_none());
+        assert!(error.expired_at_unix_seconds().is_none());
+    }
+}