feat(core): implement TAPI backoff and retry handling

[abueide]

Summary

Implements TAPI error handling specification for the React Native SDK. Adds proper retry logic for rate limits (429), transient errors (5xx), and handling of permanent errors (4xx).

Background

Currently the SDK has minimal error handling - failed events stay in the queue and retry indefinitely. This causes several issues:

• No backoff for transient errors
• No handling of 429 rate limits
• Permanent errors (400, 404) never get dropped and block the queue
• No retry limits

Solution

Added a RetryManager that handles retry logic for both rate limits and transient errors.

RetryManager - Manages retry state for uploads

• Handles 429 rate limit responses using server-provided Retry-After wait time
• Handles transient errors (5xx, network failures) using exponential backoff
• Three states: READY, RATE_LIMITED, BACKING_OFF
• Blocks all uploads when in RATE_LIMITED or BACKING_OFF state
• Tracks retry count and enforces max retry limits
• State persisted across app restarts

How it works with flush policies

Flush policies (TimerFlushPolicy, CountFlushPolicy) trigger flushes based on their criteria (time interval, event count). The RetryManager acts as a gate in sendEvents():

async sendEvents(events) {
  // Check if blocked by rate limit or backoff
  if (!await retryManager.canRetry()) return;

  // Upload batches in parallel
  const batches = chunk(events, 100, 500KB);
  const results = await Promise.all(batches.map(batch => uploadBatch(batch)));
  
  // Aggregate errors from all batches
  const aggregation = aggregateErrors(results);

  // Update retry manager based on errors
  if (aggregation.has429) {
    await retryManager.handle429(aggregation.longestRetryAfter);
  }
  if (aggregation.hasTransientError) {
    await retryManager.handleTransientError();
  }

  // Remove successful and permanently failed events
  if (aggregation.successfulMessageIds.length > 0) {
    await queuePlugin.dequeueByMessageIds(aggregation.successfulMessageIds);
    await retryManager.reset();
  }
  if (aggregation.permanentErrorMessageIds.length > 0) {
    await queuePlugin.dequeueByMessageIds(aggregation.permanentErrorMessageIds);
  }
}

When uploads are blocked:

• Flush policies continue triggering at their normal interval
• sendEvents() checks retryManager.canRetry() and returns early if blocked
• Next flush attempt occurs on the next policy trigger
• Once the backoff/rate limit expires, the flush succeeds

Error classification

Status Code	Classification	Action
200	Success	Dequeue events, reset retry count
429	Rate limit	Keep in queue, increment retry count, wait for Retry-After
5xx, 408, 410, 460	Transient	Keep in queue, increment retry count, exponential backoff
400, 401, 403, 404	Permanent	Drop events immediately
Network error	Transient	Keep in queue, increment retry count, exponential backoff

Implementation details

Error aggregation - When multiple batches are uploaded in parallel and multiple fail:

• Retry count increments by 1 (not by the number of failed batches)
• For multiple 429s, uses the longest Retry-After value
• Successful events are dequeued even if some batches failed

MessageId-based dequeue - Events are removed from the queue by messageId instead of object reference, stable across re-chunking.

Flush serialization - Concurrent flush calls are serialized to prevent uploading the same events multiple times.

Thread safety - State machine updates use atomic dispatch to prevent race conditions from async interleaving.

Configuration

The feature is opt-in via the httpConfig parameter:

const client = createClient({
  writeKey: 'YOUR_WRITE_KEY',
  httpConfig: {
    rateLimitConfig: {
      enabled: true,
      maxRetryCount: 10,
      maxRetryInterval: 1800,      // max 30min retry-after
      maxRateLimitDuration: 86400, // give up after 24 hours
    },
    backoffConfig: {
      enabled: true,
      maxRetryCount: 10,
      baseBackoffInterval: 0.5,
      maxBackoffInterval: 30,
      maxTotalBackoffDuration: 86400,
      jitterPercent: 25,
      default4xxBehavior: 'drop',
      default5xxBehavior: 'retry',
      statusCodeOverrides: {},
    },
  },
});

If httpConfig is not provided, behavior is unchanged from current implementation.

Testing

All tests pass (69 test suites, 422 tests). Added comprehensive tests for retry manager state transitions, backoff calculation, and error aggregation logic.