Add support for a retry later duration in rate limit challenge responses

marc-signal · web-flow · commit 0a58e80bbc31 · 2026-03-26T17:08:19.000-07:00
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,5 +1,7 @@
 v0.90.0
 
+- Add support for a retry later duration in rate limit responses
+
 - keytrans: Simplify the top-level API
 
 - Use CDSI enclave 3a1ac5e5 in staging.
diff --git a/java/client/src/main/java/org/signal/libsignal/net/RateLimitChallengeException.kt b/java/client/src/main/java/org/signal/libsignal/net/RateLimitChallengeException.kt
@@ -6,6 +6,7 @@
 package org.signal.libsignal.net
 
 import org.signal.libsignal.internal.CalledFromNative
+import java.time.Duration
 import java.util.EnumSet
 
 /**
@@ -17,10 +18,30 @@ import java.util.EnumSet
 public class RateLimitChallengeException : ChatServiceException {
   public val token: String
   public val options: Set<ChallengeOption>
+  public val retryLater: Duration?
 
-  @CalledFromNative
-  public constructor(message: String, token: String, options: Array<ChallengeOption>) : super(message) {
+  public constructor(
+    message: String,
+    token: String,
+    options: Array<ChallengeOption>,
+    retryLater: Duration?,
+  ) : super(message) {
     this.token = token
     this.options = EnumSet.copyOf(options.asList())
+    this.retryLater = retryLater
+  }
+
+  @CalledFromNative
+  internal constructor(
+    message: String,
+    token: String,
+    options: Array<ChallengeOption>,
+    retryLater: Long,
+  ) : this(
+    message,
+    token,
+    options,
+    if (retryLater < 0) null else Duration.ofSeconds(retryLater),
+  ) {
   }
 }
diff --git a/java/client/src/test/java/org/signal/libsignal/net/RegistrationServiceTest.java b/java/client/src/test/java/org/signal/libsignal/net/RegistrationServiceTest.java
@@ -266,11 +266,18 @@ private static void assertIsServerSideError(ThrowingConsumer<String> throwError)
   }
 
   private static void assertIsPushChallengeError(ThrowingConsumer<String> throwError) {
-    RateLimitChallengeException e =
+    final RateLimitChallengeException e =
         assertRegistrationSessionErrorIs(
             "PushChallenge", RateLimitChallengeException.class, throwError);
     assertEquals(e.getToken(), "token");
     assertEquals(e.getOptions(), EnumSet.of(ChallengeOption.PUSH_CHALLENGE));
+    assertEquals(e.getRetryLater(), null);
+    final RateLimitChallengeException e2 =
+        assertRegistrationSessionErrorIs(
+            "PushChallengeRetryAfter42Seconds", RateLimitChallengeException.class, throwError);
+    assertEquals(e2.getToken(), "token42");
+    assertEquals(e2.getOptions(), EnumSet.of(ChallengeOption.PUSH_CHALLENGE));
+    assertEquals(e2.getRetryLater(), Duration.ofSeconds(42));
   }
 
   @Test
diff --git a/node/ts/Errors.ts b/node/ts/Errors.ts
@@ -307,6 +307,7 @@ export type RateLimitChallengeError = LibSignalErrorBase & {
   code: ErrorCode.RateLimitChallengeError;
   readonly token: string;
   readonly options: Set<'pushChallenge' | 'captcha'>;
+  readonly retryAfterSecs: number | null;
 };
 
 export type ChatServiceInactive = LibSignalErrorBase & {
diff --git a/node/ts/test/RegistrationTest.ts b/node/ts/test/RegistrationTest.ts
@@ -133,6 +133,16 @@ describe('Registration types', () => {
         code: ErrorCode.RateLimitChallengeError,
         token: 'token',
         options: new Set(['pushChallenge']),
+        retryAfterSecs: null,
+      },
+    ];
+    const rateLimitRetryChallengeCase: [string, object] = [
+      'PushChallengeRetryAfter42Seconds',
+      {
+        code: ErrorCode.RateLimitChallengeError,
+        token: 'token42',
+        options: new Set(['pushChallenge']),
+        retryAfterSecs: 42,
       },
     ];
     const cases: Array<{
@@ -150,6 +160,7 @@ describe('Registration types', () => {
           timeoutCase,
           serverSideErrorCase,
           rateLimitChallengeCase,
+          rateLimitRetryChallengeCase,
         ],
       },
       {
@@ -162,6 +173,7 @@ describe('Registration types', () => {
           timeoutCase,
           serverSideErrorCase,
           rateLimitChallengeCase,
+          rateLimitRetryChallengeCase,
         ],
       },
       {
diff --git a/rust/bridge/ffi/src/error.rs b/rust/bridge/ffi/src/error.rs
@@ -12,6 +12,7 @@ use libsignal_bridge::ffi::{
 use libsignal_bridge::{IllegalArgumentError, ffi_arg_type, ffi_result_type};
 use libsignal_bridge_macros::bridge_fn;
 use libsignal_core::ProtocolAddress;
+use libsignal_net::infra::errors::RetryLater;
 use libsignal_net_chat::api::ChallengeOption;
 use libsignal_net_chat::api::messages::MismatchedDeviceError;
 use uuid::Uuid;
@@ -146,17 +147,28 @@ fn Error_GetTriesRemaining(err: &SignalFfiError) -> Result<u32, IllegalArgumentE
     })
 }
 
+#[allow(clippy::type_complexity)]
 #[bridge_fn(jni = false, node = false)]
 fn Error_GetRateLimitChallenge(
     err: &SignalFfiError,
-) -> Result<(String, Box<[ChallengeOption]>), IllegalArgumentError> {
-    let libsignal_net_chat::api::RateLimitChallenge { token, options } =
-        err.provide_rate_limit_challenge().map_err(|_| {
-            IllegalArgumentError::new(format!(
-                "cannot get rate limit challenge error from error ({err})"
-            ))
-        })?;
-    Ok((token.clone(), options[..].into()))
+) -> Result<((String, Box<[ChallengeOption]>), i64), IllegalArgumentError> {
+    let libsignal_net_chat::api::RateLimitChallenge {
+        token,
+        options,
+        retry_later,
+    } = err.provide_rate_limit_challenge().map_err(|_| {
+        IllegalArgumentError::new(format!(
+            "cannot get rate limit challenge error from error ({err})"
+        ))
+    })?;
+    let retry_later = retry_later
+        .map(
+            |RetryLater {
+                 retry_after_seconds,
+             }| i64::from(retry_after_seconds),
+        )
+        .unwrap_or(-1);
+    Ok(((token.clone(), options[..].into()), retry_later))
 }
 
 #[bridge_fn(jni = false, node = false)]
diff --git a/rust/bridge/shared/testing/src/net/registration.rs b/rust/bridge/shared/testing/src/net/registration.rs
@@ -189,6 +189,12 @@ impl<TestE: for<'a> TryFrom<&'a str, Error = strum::ParseError>> TryFrom<String>
             "PushChallenge" => RequestError::Challenge(RateLimitChallenge {
                 token: "token".to_owned(),
                 options: vec![ChallengeOption::PushChallenge],
+                retry_later: None,
+            }),
+            "PushChallengeRetryAfter42Seconds" => RequestError::Challenge(RateLimitChallenge {
+                token: "token42".to_owned(),
+                options: vec![ChallengeOption::PushChallenge],
+                retry_later: Some(RETRY_AFTER_42_SECONDS),
             }),
             "ServerSideError" => RequestError::ServerSideError,
             _ => TestE::try_from(&value)
diff --git a/rust/bridge/shared/types/src/ffi/convert.rs b/rust/bridge/shared/types/src/ffi/convert.rs
@@ -1381,6 +1381,7 @@ trivial!(u8);
 trivial!(u16);
 trivial!(u32);
 trivial!(u64);
+trivial!(i64);
 trivial!(usize);
 trivial!(bool);
 
@@ -1493,6 +1494,7 @@ macro_rules! ffi_result_type {
     (u32) => (u32);
     (Option<u32>) => (u32);
     (u64) => (u64);
+    (i64) => (i64);
     (Option<u64>) => (u64);
     (bool) => (bool);
     (&str) => (*const std::ffi::c_char);
diff --git a/rust/bridge/shared/types/src/jni/mod.rs b/rust/bridge/shared/types/src/jni/mod.rs
@@ -1031,18 +1031,32 @@ impl JniError for RateLimitChallenge {
         &self,
         env: &mut JNIEnv<'a>,
     ) -> Result<JThrowable<'a>, BridgeLayerError> {
-        let Self { token, options } = self;
+        let Self {
+            token,
+            options,
+            retry_later,
+        } = self;
         let (message, token) =
             try_scoped(|| Ok((env.new_string(self.to_string())?, env.new_string(token)?)))
                 .check_exceptions(env, "RateLimitChallenge")?;
         let options = options.as_slice().convert_into(env)?;
+        let retry_later = retry_later
+            .as_ref()
+            .map(
+                |RetryLater {
+                     retry_after_seconds,
+                 }| i64::from(*retry_after_seconds),
+            )
+            .unwrap_or(-1);
         new_instance(
             env,
             ClassName("org.signal.libsignal.net.RateLimitChallengeException"),
             jni_args!((
                 message => java.lang.String,
                 token => java.lang.String,
-                options => [org.signal.libsignal.net.ChallengeOption]) -> void),
+                options => [org.signal.libsignal.net.ChallengeOption],
+                retry_later => long,
+            ) -> void),
         )
         .map(Into::into)
     }
diff --git a/rust/bridge/shared/types/src/node/error.rs b/rust/bridge/shared/types/src/node/error.rs
@@ -6,7 +6,7 @@
 use std::borrow::Cow;
 use std::fmt;
 
-use libsignal_net::infra::errors::TransportConnectError;
+use libsignal_net::infra::errors::{RetryLater, TransportConnectError};
 use libsignal_net::infra::ws::WebSocketConnectError;
 use libsignal_net_chat::api::keys::GetPreKeysFailure;
 use neon::thread::LocalKey;
@@ -521,15 +521,28 @@ impl SignalNodeError for libsignal_net_chat::api::RateLimitChallenge {
         operation_name: &str,
     ) -> Handle<'a, JsError> {
         let message = self.to_string();
-        let Self { token, options } = self;
+        let Self {
+            token,
+            options,
+            retry_later,
+        } = self;
         let properties = move |cx: &mut C| {
             let token = cx.string(token);
             let options = options.into_boxed_slice().convert_into(cx)?.upcast();
             let set_constructor: Handle<'_, JsFunction> = cx.global("Set")?;
             let options = set_constructor.construct(cx, [options])?;
             let props = cx.empty_object();
+            let retry_later = retry_later
+                .map(
+                    |RetryLater {
+                         retry_after_seconds,
+                     }| cx.number(retry_after_seconds),
+                )
+                .map(|x| x.as_value(cx))
+                .unwrap_or_else(|| cx.null().as_value(cx));
             props.set(cx, "token", token)?;
             props.set(cx, "options", options)?;
+            props.set(cx, "retryAfterSecs", retry_later)?;
             Ok(props.upcast())
         };
         new_js_error(
diff --git a/rust/net/chat/src/api.rs b/rust/net/chat/src/api.rs
@@ -7,8 +7,9 @@
 //! chat-server".
 
 use std::convert::Infallible;
+use std::fmt::Formatter;
 
-use libsignal_net::infra::errors::LogSafeDisplay;
+use libsignal_net::infra::errors::{LogSafeDisplay, RetryLater};
 use ref_cast::RefCast as _;
 
 pub mod backups;
@@ -142,12 +143,25 @@ impl<E> From<DisconnectedError> for RequestError<E> {
     }
 }
 
-#[derive(Debug, thiserror::Error, displaydoc::Display)]
+#[derive(Debug, thiserror::Error)]
 #[cfg_attr(test, derive(Clone))]
-/// retry after completing a rate limit challenge {options:?}
 pub struct RateLimitChallenge {
     pub token: String,
     pub options: Vec<ChallengeOption>,
+    pub retry_later: Option<RetryLater>,
+}
+impl std::fmt::Display for RateLimitChallenge {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "retry after completing a rate limit challenge {:?}",
+            self.options
+        )?;
+        if let Some(retry_later) = &self.retry_later {
+            write!(f, " (or {retry_later})")?;
+        }
+        Ok(())
+    }
 }
 impl LogSafeDisplay for RateLimitChallenge {}
 
diff --git a/rust/net/chat/src/ws.rs b/rust/net/chat/src/ws.rs
@@ -293,7 +293,11 @@ impl ResponseError {
                         if let Ok(ChallengeBody { token, options }) =
                             parse_json_from_body(&response)
                         {
-                            return RequestError::Challenge(RateLimitChallenge { token, options });
+                            return RequestError::Challenge(RateLimitChallenge {
+                                token,
+                                options,
+                                retry_later: extract_retry_later(headers),
+                            });
                         }
                     }
                     if status.as_u16() == 422 {
@@ -452,6 +456,18 @@ mod testutil {
         }
     }
 
+    pub(crate) fn with_headers(
+        headers: &[(http::HeaderName, &'static str)],
+        mut response: chat::Response,
+    ) -> chat::Response {
+        response.headers.extend(
+            headers
+                .iter()
+                .map(|(k, v)| (k.clone(), http::HeaderValue::from_static(v))),
+        );
+        response
+    }
+
     pub(crate) struct RequestValidator {
         pub expected: chat::Request,
         pub response: chat::Response,
@@ -556,7 +572,12 @@ mod test {
     #[test_case(json(428, "{}") => matches Err(RequestError::Unexpected { log_safe: m }) if m.contains("428"))]
     #[test_case(json(
         428, r#"{"token": "zzz", "options": ["captcha"]}"#
-    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
+    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options, retry_later: None })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
+    #[test_case(with_headers(&[(http::header::RETRY_AFTER, "42")], json(
+        428, r#"{"token": "zzz", "options": ["captcha"]}"#
+    )) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options, retry_later: Some(
+        RetryLater { retry_after_seconds: 42 }
+    ) })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
     #[test_case(empty(422) => matches Err(RequestError::Unexpected { log_safe: m }) if m.contains("server validation"))]
     #[test_case(empty(419) => matches Err(RequestError::Unexpected { log_safe: m }) if m.contains("419"))]
     fn try_parse_empty(
diff --git a/rust/net/chat/src/ws/messages.rs b/rust/net/chat/src/ws/messages.rs
@@ -550,6 +550,7 @@ mod test {
 
     use futures_util::FutureExt;
     use libsignal_core::{Aci, Pni};
+    use libsignal_net::infra::errors::RetryLater;
     use libsignal_protocol::{CiphertextMessage, PlaintextContent, Timestamp};
     use serde_json::json;
     use test_case::test_case;
@@ -562,7 +563,7 @@ mod test {
     };
     use crate::api::{ChallengeOption, RateLimitChallenge, UserBasedAuthorization};
     use crate::ws::ACCESS_KEY_HEADER_NAME;
-    use crate::ws::testutil::{JsonRequestValidator, RequestValidator, empty, json};
+    use crate::ws::testutil::{JsonRequestValidator, RequestValidator, empty, json, with_headers};
 
     const ACI_UUID: &str = "9d0652a3-dcc3-4d11-975f-74d61598733f";
     const PNI_UUID: &str = "796abedb-ca4e-4f18-8803-1fde5b921f9f";
@@ -858,7 +859,12 @@ mod test {
     #[test_case(json(428, "{}") => matches Err(RequestError::Unexpected { log_safe: m }) if m.contains("428"))]
     #[test_case(json(
         428, r#"{"token": "zzz", "options": ["captcha"]}"#
-    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
+    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options, retry_later: None })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
+    #[test_case(with_headers(&[(http::header::RETRY_AFTER, "42")], json(
+        428, r#"{"token": "zzz", "options": ["captcha"]}"#
+    )) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options, retry_later: Some(
+        RetryLater { retry_after_seconds: 42 }
+    ) })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
     fn test_unsealed_send(response: Response) -> Result<(), RequestError<UnsealedSendFailure>> {
         let validator = JsonRequestValidator {
             expected: Request {
@@ -953,7 +959,7 @@ mod test {
     )]
     #[test_case(json(
         428, r#"{"token": "zzz", "options": ["captcha"]}"#
-    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
+    ) => matches Err(RequestError::Challenge(RateLimitChallenge { token, options, retry_later: None })) if token == "zzz" && options == vec![ChallengeOption::Captcha])]
     fn test_sync_send(response: Response) -> Result<(), RequestError<MismatchedDeviceError>> {
         let validator = JsonRequestValidator {
             expected: Request {
diff --git a/swift/Sources/LibSignalClient/Error.swift b/swift/Sources/LibSignalClient/Error.swift
diff --git a/swift/Sources/SignalFfi/signal_ffi.h b/swift/Sources/SignalFfi/signal_ffi.h
diff --git a/swift/Tests/LibSignalClientTests/RegistrationServiceTests.swift b/swift/Tests/LibSignalClientTests/RegistrationServiceTests.swift
