ref(transport): Measure rate-limit backoff on a monotonic clock (JAVA-574) (#6030)

* ref(transport): Measure rate-limit backoff on a monotonic clock (JAVA-574)

Retry-after limits were java.util.Date values derived from
System.currentTimeMillis(). A wall clock is the wrong instrument for a
backoff window: it steps when the device syncs time, so an NTP
correction could lift a 60 second rate limit early or extend it by
however far the clock jumped. The limits now live on the monotonic
clock, which counts forward at a steady rate and keeps counting while
the device sleeps, which is what a server-dictated wait means.

Storing Deadline rather than a timestamp also removes the duplicated
parameter on applyRetryAfterOnlyIfLonger, which took both an absolute
deadline and the delay needed to reach it, and lets three JdkObsolete
and JavaUtilDate suppressions go with the Dates.

RateLimiter also took the whole SentryOptions while reading exactly
three methods from it. It now depends on RateLimiterConfig, declared
next to its consumer, so what a rate limiter touches is three lines to
read rather than three hundred. SentryOptions implements it with no new
methods, so every existing caller compiles unchanged.

Both existing constructors stay, so the .api diff is additions only. The
ICurrentDateProvider one is deprecated and adapts the injected provider
rather than ignoring it, since a custom ITransportFactory may be passing
one.

One boundary moves by a nanosecond: a limit used to be active while
`now <= deadline` and is now active while `now < deadline`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Add changelog entries for JAVA-574

* ref(transport): Create RateLimiter through a factory (JAVA-574)

The RateLimiterConfig constructor is now private behind
RateLimiter.create, and both SentryOptions constructors are deprecated.
Handing over the whole options object hides which three of its methods a
rate limiter reads, which is the very thing the config interface exists
to name, so both transport factories call the factory method instead.

RateLimiterTest supplies its own RateLimiterConfig rather than a
SentryOptions carrying a @testonly executor setter and a reflective
client-report-recorder injection. A DeferredExecutorService replaces the
real executor, so the lifted-limit notification runs when the test says
so instead of a real second later, leaving the deadline's virtual clock
as the only clock in the test.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(transport): Tolerate a negative retry-after delay (JAVA-574)

A server-supplied `Retry-After: -1`, or a negative delay in
`X-Sentry-Rate-Limits`, reached `Deadline.after` unvalidated and threw
`IllegalArgumentException` out of response handling. Clamp a negative
amount to an already-passed deadline, restoring the behavior the
wall-clock implementation had, and keeping the tick arithmetic away from
wrapping on a large negative value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* ref(transport): Keep RateLimiter(SentryOptions) as public API (JAVA-574)

RateLimiter is public because ITransport.getRateLimiter returns it and a
custom transport has to build one. Deprecating the options constructor
pointed those callers at RateLimiter.create, whose two parameter types
are both @ApiStatus.Internal, so following the deprecation meant reaching
into internal API.

Un-deprecate the options constructor and mark the factory internal
instead, which is what it already was in practice. Both transport
factories call the constructor, dropping the getMonotonicTicker/options
double-pass and, in the apache module, an internal call from another
module.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* ref(transport): Note why RateLimiter(SentryOptions) stays non-deprecated (JAVA-574)

Both transport factories go back to RateLimiter.create, which names the
collaborators a rate limiter reads instead of handing over the whole
options object. The constructor stays as the one path a caller outside
the SDK can take, and now says so: it is only non-deprecated because
create takes the internal MonotonicTicker, and should be deprecated once
that type is public API.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: runningcode

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 8.56.0
 
+### Behavioral Changes
+
+- Measure HTTP rate-limit backoff on a monotonic clock instead of the wall clock, so that a device time change no longer lifts or extends an active rate limit ([#6030](https://github.com/getsentry/sentry-java/pull/6030))
+
 ### Fixes
 
 - Update `SentryTraced` so that it now honors `options.setIgnoredSpanOrigins` ([#6058](https://github.com/getsentry/sentry-java/pull/6058))
@@ -19,6 +23,7 @@
 
 - Add an internal `MonotonicTicker` abstraction with `Deadline` and `Stopwatch` primitives ([#6028](https://github.com/getsentry/sentry-java/pull/6028))
 - Add internal `Timestamp`, `EpochClock` and `AnchoredClock`, so related instants project from one wall-clock reading instead of each reading the clock ([#6045](https://github.com/getsentry/sentry-java/pull/6045))
+- Deprecate `RateLimiter(ICurrentDateProvider, SentryOptions)` in favor of `RateLimiter(SentryOptions)`, whose backoff is measured on a monotonic ticker ([#6030](https://github.com/getsentry/sentry-java/pull/6030))
 
 ### Dependencies
 

sentry-apache-http-client-5/src/main/java/io/sentry/transport/apache/ApacheHttpClientTransportFactory.java

@@ -62,7 +62,7 @@ public ApacheHttpClientTransportFactory(final @NotNull TimeValue connectionTimeT
                     .setResponseTimeout(options.getReadTimeoutMillis(), TimeUnit.MILLISECONDS)
                     .build())
             .build();
-    final RateLimiter rateLimiter = new RateLimiter(options);
+    final RateLimiter rateLimiter = RateLimiter.create(options.getMonotonicTicker(), options);
 
     return new ApacheHttpClientTransport(options, requestDetails, httpclient, rateLimiter);
   }

sentry/api/sentry.api

@@ -3654,7 +3654,7 @@ public final class io/sentry/SentryOpenTelemetryMode : java/lang/Enum {
 	public static fun values ()[Lio/sentry/SentryOpenTelemetryMode;
 }
 
-public class io/sentry/SentryOptions {
+public class io/sentry/SentryOptions : io/sentry/transport/RateLimiterConfig {
 	public static final field DEFAULT_PROPAGATION_TARGETS Ljava/lang/String;
 	public static final field MAX_EVENT_SIZE_BYTES J
 	protected final field lock Lio/sentry/util/AutoClosableReentrantLock;
@@ -7706,6 +7706,7 @@ public final class io/sentry/transport/RateLimiter : java/io/Closeable {
 	public fun <init> (Lio/sentry/transport/ICurrentDateProvider;Lio/sentry/SentryOptions;)V
 	public fun addRateLimitObserver (Lio/sentry/transport/RateLimiter$IRateLimitObserver;)V
 	public fun close ()V
+	public static fun create (Lio/sentry/time/MonotonicTicker;Lio/sentry/transport/RateLimiterConfig;)Lio/sentry/transport/RateLimiter;
 	public fun filter (Lio/sentry/SentryEnvelope;Lio/sentry/Hint;)Lio/sentry/SentryEnvelope;
 	public fun isActiveForCategory (Lio/sentry/DataCategory;)Z
 	public fun isAnyRateLimitActive ()Z
@@ -7717,6 +7718,12 @@ public abstract interface class io/sentry/transport/RateLimiter$IRateLimitObserv
 	public abstract fun onRateLimitChanged (Lio/sentry/transport/RateLimiter;)V
 }
 
+public abstract interface class io/sentry/transport/RateLimiterConfig {
+	public abstract fun getClientReportRecorder ()Lio/sentry/clientreport/IClientReportRecorder;
+	public abstract fun getLogger ()Lio/sentry/ILogger;
+	public abstract fun getTimerExecutorService ()Lio/sentry/ISentryExecutorService;
+}
+
 public final class io/sentry/transport/ReusableCountLatch {
 	public fun <init> ()V
 	public fun <init> (I)V

sentry/src/main/java/io/sentry/AsyncHttpTransportFactory.java

@@ -18,6 +18,9 @@ public final class AsyncHttpTransportFactory implements ITransportFactory {
     Objects.requireNonNull(requestDetails, "requestDetails is required");
 
     return new AsyncHttpTransport(
-        options, new RateLimiter(options), options.getTransportGate(), requestDetails);
+        options,
+        RateLimiter.create(options.getMonotonicTicker(), options),
+        options.getTransportGate(),
+        requestDetails);
   }
 }

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -29,6 +29,7 @@
 import io.sentry.transport.ITransportGate;
 import io.sentry.transport.NoOpEnvelopeCache;
 import io.sentry.transport.NoOpTransportGate;
+import io.sentry.transport.RateLimiterConfig;
 import io.sentry.util.AutoClosableReentrantLock;
 import io.sentry.util.LazyEvaluator;
 import io.sentry.util.LoadClass;
@@ -58,7 +59,7 @@
 
 /** Sentry SDK options */
 @Open
-public class SentryOptions {
+public class SentryOptions implements RateLimiterConfig {
 
   @ApiStatus.Internal public static final @NotNull String DEFAULT_PROPAGATION_TARGETS = ".*";
 
@@ -847,6 +848,7 @@ public void setDebug(final boolean debug) {
    *
    * @return the logger
    */
+  @Override
   public @NotNull ILogger getLogger() {
     return logger;
   }
@@ -1610,6 +1612,7 @@ public void setExecutorService(final @NotNull ISentryExecutorService executorSer
    * @return the timer executor service
    */
   @ApiStatus.Internal
+  @Override
   @NotNull
   public ISentryExecutorService getTimerExecutorService() {
     return timerExecutorService;
@@ -2601,6 +2604,7 @@ public void setInstrumenter(final @NotNull Instrumenter instrumenter) {
    * @return a client report recorder or NoOp
    */
   @ApiStatus.Internal
+  @Override
   public @NotNull IClientReportRecorder getClientReportRecorder() {
     return clientReportRecorder;
   }

sentry/src/main/java/io/sentry/time/Deadline.java

@@ -24,15 +24,18 @@ private Deadline(final @NotNull MonotonicTicker ticker, final long deadlineNanos
   }
 
   /**
-   * A deadline {@code amount} of {@code unit} from now.
+   * A deadline {@code amount} of {@code unit} from now, or one that has already {@link #passed} if
+   * {@code amount} is negative.
    *
-   * @throws IllegalArgumentException if {@code amount} is negative. A deadline that starts out in
-   *     the past is a sign error at the call site; {@link #passed} says it deliberately.
+   * <p>Negative amounts are tolerated because callers pass durations parsed from server headers,
+   * where a bogus value must degrade to "no wait" rather than throw out of response handling.
+   * Clamping rather than adding a negative offset also keeps the tick arithmetic away from
+   * wrapping.
    */
   public static @NotNull Deadline after(
       final @NotNull MonotonicTicker ticker, final long amount, final @NotNull TimeUnit unit) {
     if (amount < 0) {
-      throw new IllegalArgumentException("Deadline amount must not be negative, but was " + amount);
+      return passed(ticker);
     }
     return new Deadline(ticker, ticker.tickNanos() + unit.toNanos(amount));
   }