Expose Retryability Metadata

Add retryability and expiration accessors to the core v2 session,
transport, replay, and response errors, then export the same
metadata through the existing UniFFI object wrappers.

This lets bindings distinguish expired sessions from transient
directory failures without parsing display strings or collapsing
everything into opaque transport errors.

Author: chavic

payjoin-ffi/python/test/test_payjoin_unit_test.py

@@ -230,5 +230,101 @@ def test_sender_builder_rejects_bad_psbt(self):
             payjoin.SenderBuilder("not-a-psbt", uri)
 
 
+class TestRetryMetadata(unittest.TestCase):
+    @staticmethod
+    def _ohttp_keys():
+        return payjoin.OhttpKeys.decode(
+            bytes.fromhex(
+                "01001604ba48c49c3d4a92a3ad00ecc63a024da10ced02180c73ec12d8a7ad2cc91bb483824fe2bee8d28bfe2eb2fc6453bc4d31cd851e8a6540e86c5382af588d370957000400010003"
+            )
+        )
+
+    def _receiver_builder(self, expiration=None):
+        builder = payjoin.ReceiverBuilder(
+            "2MuyMrZHkbHbfjudmKUy45dU4P17pjG2szK",
+            "https://example.com",
+            self._ohttp_keys(),
+        )
+        if expiration is not None:
+            builder = builder.with_expiration(expiration)
+        return builder
+
+    def test_sender_create_request_exposes_expiration_metadata(self):
+        recv_persister = InMemoryReceiverPersister(10)
+        receiver = self._receiver_builder(expiration=0).build().save(recv_persister)
+        uri = receiver.pj_uri()
+        sender = (
+            payjoin.SenderBuilder(payjoin.original_psbt(), uri)
+            .build_recommended(1000)
+            .save(InMemorySenderPersister(11))
+        )
+
+        with self.assertRaises(payjoin.CreateRequestError) as ctx:
+            sender.create_v2_post_request("https://example.com")
+
+        self.assertFalse(ctx.exception.is_retryable())
+        self.assertIsInstance(ctx.exception.expired_at_unix_seconds(), int)
+
+    def test_receiver_error_exposes_expiration_metadata(self):
+        receiver = (
+            self._receiver_builder(expiration=0)
+            .build()
+            .save(InMemoryReceiverPersister(12))
+        )
+
+        with self.assertRaises(payjoin.ReceiverError.Protocol) as ctx:
+            receiver.create_poll_request("https://example.com")
+
+        protocol_error = ctx.exception[0]
+        self.assertFalse(protocol_error.is_retryable())
+        self.assertIsInstance(protocol_error.expired_at_unix_seconds(), int)
+
+    def test_sender_persisted_error_keeps_retryable_transport_signal(self):
+        recv_persister = InMemoryReceiverPersister(13)
+        receiver = self._receiver_builder().build().save(recv_persister)
+        uri = receiver.pj_uri()
+        sender = (
+            payjoin.SenderBuilder(payjoin.original_psbt(), uri)
+            .build_recommended(1000)
+            .save(InMemorySenderPersister(14))
+        )
+        request = sender.create_v2_post_request("https://example.com")
+        transition = sender.process_response(b"", request.ohttp_ctx)
+
+        with self.assertRaises(payjoin.SenderPersistedError.EncapsulationError) as ctx:
+            transition.save(InMemorySenderPersister(15))
+
+        self.assertTrue(ctx.exception[0].is_retryable())
+
+    def test_replay_errors_expose_expiration_metadata(self):
+        recv_persister = InMemoryReceiverPersister(16)
+        self._receiver_builder(expiration=0).build().save(recv_persister)
+
+        with self.assertRaises(payjoin.ReceiverReplayError) as recv_ctx:
+            payjoin.replay_receiver_event_log(recv_persister)
+
+        self.assertFalse(recv_ctx.exception.is_retryable())
+        self.assertIsInstance(recv_ctx.exception.expired_at_unix_seconds(), int)
+
+        sender_persister = InMemorySenderPersister(17)
+        receiver = (
+            self._receiver_builder(expiration=0)
+            .build()
+            .save(InMemoryReceiverPersister(18))
+        )
+        uri = receiver.pj_uri()
+        (
+            payjoin.SenderBuilder(payjoin.original_psbt(), uri)
+            .build_recommended(1000)
+            .save(sender_persister)
+        )
+
+        with self.assertRaises(payjoin.SenderReplayError) as send_ctx:
+            payjoin.replay_sender_event_log(sender_persister)
+
+        self.assertFalse(send_ctx.exception.is_retryable())
+        self.assertIsInstance(send_ctx.exception.expired_at_unix_seconds(), int)
+
+
 if __name__ == "__main__":
     unittest.main()

payjoin-ffi/src/error.rs

@@ -17,6 +17,11 @@ impl From<ImplementationError> for payjoin::ImplementationError {
     fn from(value: ImplementationError) -> Self { value.0 }
 }
 
+#[uniffi::export]
+impl ImplementationError {
+    pub fn is_retryable(&self) -> bool { true }
+}
+
 #[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

@@ -139,6 +139,13 @@ impl From<payjoin::bitcoin::address::ParseError> for AddressParseError {
 #[error(transparent)]
 pub struct ProtocolError(#[from] receive::ProtocolError);
 
+#[uniffi::export]
+impl ProtocolError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.0.expired_at_unix_seconds() }
+}
+
 /// The standard format for errors that can be replied as JSON.
 ///
 /// The JSON output includes the following fields:
@@ -168,6 +175,13 @@ impl From<ProtocolError> for JsonReply {
 #[error(transparent)]
 pub struct SessionError(#[from] receive::v2::SessionError);
 
+#[uniffi::export]
+impl SessionError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.0.expired_at_unix_seconds() }
+}
+
 /// Protocol error raised during output substitution.
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error(transparent)]
@@ -237,3 +251,10 @@ impl From<FfiValidationError> for InputPairError {
 pub struct ReceiverReplayError(
     #[from] payjoin::error::ReplayError<receive::v2::ReceiveSession, receive::v2::SessionEvent>,
 );
+
+#[uniffi::export]
+impl ReceiverReplayError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.0.expired_at_unix_seconds() }
+}

payjoin-ffi/src/send/error.rs

@@ -22,6 +22,11 @@ impl From<send::BuildSenderError> for BuildSenderError {
     fn from(value: send::BuildSenderError) -> Self { BuildSenderError { msg: value.to_string() } }
 }
 
+#[uniffi::export]
+impl BuildSenderError {
+    pub fn is_retryable(&self) -> bool { false }
+}
+
 /// FFI-visible PSBT parsing error surfaced at the sender boundary.
 #[derive(Debug, thiserror::Error, uniffi::Error)]
 pub enum PsbtParseError {
@@ -58,16 +63,33 @@ impl From<FfiValidationError> for SenderInputError {
 #[error(transparent)]
 pub struct CreateRequestError(#[from] send::v2::CreateRequestError);
 
+#[uniffi::export]
+impl CreateRequestError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.0.expired_at_unix_seconds() }
+}
+
 /// Error returned for v2-specific payload encapsulation errors.
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error(transparent)]
 pub struct EncapsulationError(#[from] send::v2::EncapsulationError);
 
+#[uniffi::export]
+impl EncapsulationError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+}
+
 /// Error that may occur when the response from receiver is malformed.
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error(transparent)]
 pub struct ValidationError(#[from] send::ValidationError);
 
+#[uniffi::export]
+impl ValidationError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+}
+
 /// Represent an error returned by Payjoin receiver.
 #[derive(Debug, thiserror::Error, uniffi::Error)]
 pub enum ResponseError {
@@ -109,13 +131,25 @@ impl From<send::ResponseError> for ResponseError {
 #[error(transparent)]
 pub struct WellKnownError(#[from] send::WellKnownError);
 
+#[uniffi::export]
+impl WellKnownError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+}
+
 /// Error that may occur when the sender session event log is replayed
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error(transparent)]
 pub struct SenderReplayError(
     #[from] payjoin::error::ReplayError<send::v2::SendSession, send::v2::SessionEvent>,
 );
 
+#[uniffi::export]
+impl SenderReplayError {
+    pub fn is_retryable(&self) -> bool { self.0.is_retryable() }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> { self.0.expired_at_unix_seconds() }
+}
+
 /// Error that may occur during state machine transitions
 #[derive(Debug, thiserror::Error, uniffi::Error)]
 #[error(transparent)]

payjoin-ffi/src/uri/error.rs

@@ -28,6 +28,11 @@ pub struct UrlParseError(#[from] url::ParseError);
 #[error(transparent)]
 pub struct IntoUrlError(#[from] payjoin::IntoUrlError);
 
+#[uniffi::export]
+impl IntoUrlError {
+    pub fn is_retryable(&self) -> bool { false }
+}
+
 #[derive(Debug, thiserror::Error, uniffi::Object)]
 #[error("{msg}")]
 pub struct FeeRateError {

payjoin/src/core/error.rs

@@ -69,6 +69,20 @@ impl<SessionState: Debug, SessionEvent: Debug> From<InternalReplayError<SessionS
     fn from(e: InternalReplayError<SessionState, SessionEvent>) -> Self { ReplayError(e) }
 }
 
+#[cfg(feature = "v2")]
+impl<SessionState: Debug, SessionEvent: Debug> ReplayError<SessionState, SessionEvent> {
+    pub fn is_retryable(&self) -> bool {
+        matches!(self.0, InternalReplayError::PersistenceFailure(_))
+    }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> {
+        match &self.0 {
+            InternalReplayError::Expired(expiration) => Some(expiration.to_unix_seconds()),
+            _ => None,
+        }
+    }
+}
+
 #[cfg(feature = "v2")]
 #[derive(Debug)]
 pub(crate) enum InternalReplayError<SessionState, SessionEvent> {
@@ -81,3 +95,24 @@ pub(crate) enum InternalReplayError<SessionState, SessionEvent> {
     /// Application storage error
     PersistenceFailure(ImplementationError),
 }
+
+#[cfg(all(test, feature = "v2"))]
+mod tests {
+    use std::time::{Duration, SystemTime};
+
+    use super::*;
+
+    #[test]
+    fn test_replay_error_retryability_and_expiration_metadata() {
+        let expiration =
+            crate::time::Time::try_from(SystemTime::now() - Duration::from_secs(1)).unwrap();
+        let expired: ReplayError<(), ()> = InternalReplayError::Expired(expiration).into();
+        assert!(!expired.is_retryable());
+        assert_eq!(expired.expired_at_unix_seconds(), Some(expiration.to_unix_seconds()));
+
+        let persistence_failure: ReplayError<(), ()> =
+            InternalReplayError::PersistenceFailure(ImplementationError::from("storage")).into();
+        assert!(persistence_failure.is_retryable());
+        assert_eq!(persistence_failure.expired_at_unix_seconds(), None);
+    }
+}

payjoin/src/core/ohttp.rs

@@ -70,6 +70,8 @@ impl DirectoryResponseError {
             UnexpectedStatusCode(status_code) => status_code.is_client_error(),
         }
     }
+
+    pub(crate) fn is_retryable(&self) -> bool { !self.is_fatal() }
 }
 
 impl fmt::Display for DirectoryResponseError {

payjoin/src/core/receive/error.rs

@@ -158,6 +158,26 @@ impl error::Error for ProtocolError {
     }
 }
 
+impl ProtocolError {
+    pub fn is_retryable(&self) -> bool {
+        match self {
+            Self::OriginalPayload(_) => false,
+            #[cfg(feature = "v1")]
+            Self::V1(_) => false,
+            #[cfg(feature = "v2")]
+            Self::V2(error) => error.is_retryable(),
+        }
+    }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> {
+        match self {
+            #[cfg(feature = "v2")]
+            Self::V2(error) => error.expired_at_unix_seconds(),
+            _ => None,
+        }
+    }
+}
+
 impl From<InternalPayloadError> for Error {
     fn from(e: InternalPayloadError) -> Self {
         Error::Protocol(ProtocolError::OriginalPayload(e.into()))
@@ -433,6 +453,8 @@ impl From<InternalInputContributionError> for InputContributionError {
 
 #[cfg(test)]
 mod tests {
+    use std::time::{Duration, SystemTime};
+
     use super::*;
     use crate::ImplementationError;
 
@@ -504,4 +526,24 @@ mod tests {
         assert_eq!(json["errorCode"], "original-psbt-rejected");
         assert_eq!(json["message"], "Missing payment.");
     }
+
+    #[cfg(feature = "v2")]
+    #[test]
+    fn test_protocol_error_exposes_retryability_and_expiration() {
+        let expiration =
+            crate::time::Time::try_from(SystemTime::now() - Duration::from_secs(1)).unwrap();
+        let expired = ProtocolError::V2(crate::receive::v2::SessionError::from(
+            crate::receive::v2::InternalSessionError::Expired(expiration),
+        ));
+        assert!(!expired.is_retryable());
+        assert_eq!(expired.expired_at_unix_seconds(), Some(expiration.to_unix_seconds()));
+
+        let retryable = ProtocolError::V2(crate::receive::v2::SessionError::from(
+            crate::receive::v2::InternalSessionError::DirectoryResponse(
+                crate::ohttp::DirectoryResponseError::InvalidSize(1),
+            ),
+        ));
+        assert!(retryable.is_retryable());
+        assert_eq!(retryable.expired_at_unix_seconds(), None);
+    }
 }

payjoin/src/core/receive/v2/error.rs

@@ -73,3 +73,43 @@ impl error::Error for SessionError {
         }
     }
 }
+
+impl SessionError {
+    pub fn is_retryable(&self) -> bool {
+        match &self.0 {
+            InternalSessionError::ParseUrl(_)
+            | InternalSessionError::Expired(_)
+            | InternalSessionError::OhttpEncapsulation(_)
+            | InternalSessionError::Hpke(_) => false,
+            InternalSessionError::DirectoryResponse(error) => error.is_retryable(),
+        }
+    }
+
+    pub fn expired_at_unix_seconds(&self) -> Option<u32> {
+        match &self.0 {
+            InternalSessionError::Expired(expiration) => Some(expiration.to_unix_seconds()),
+            _ => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{Duration, SystemTime};
+
+    use super::*;
+
+    #[test]
+    fn test_session_error_exposes_retryability_and_expiration() {
+        let expiration =
+            Time::try_from(SystemTime::now() - Duration::from_secs(1)).expect("valid timestamp");
+        let expired: SessionError = InternalSessionError::Expired(expiration).into();
+        assert!(!expired.is_retryable());
+        assert_eq!(expired.expired_at_unix_seconds(), Some(expiration.to_unix_seconds()));
+
+        let retryable: SessionError =
+            InternalSessionError::DirectoryResponse(DirectoryResponseError::InvalidSize(1)).into();
+        assert!(retryable.is_retryable());
+        assert_eq!(retryable.expired_at_unix_seconds(), None);
+    }
+}