feat: Add smart retry system with rate limiting and exponential backoff

[didiergarcia]

Summary

Port of the smart retry system from analytics-kotlin to analytics-swift, adding HTTP 429 rate limiting and 5xx exponential backoff capabilities to the HTTPClient.

• Implements state machine pattern for retry decision logic
• Adds persistent state management using Codable and UserDefaults
• Provides configurable rate limit and backoff behavior via HttpConfig
• Maintains backward compatibility (legacy mode when httpConfig is nil)
• Includes comprehensive test coverage with time manipulation for deterministic chain tests

Key Components

• RetryTypes.swift: Core enums and structs (PipelineState, RetryBehavior, UploadDecision, ResponseInfo)
• RetryState.swift: Codable persistent state with per-batch metadata tracking
• HttpConfig.swift: Configuration with validation/clamping for rate limit and backoff settings
• TimeProvider.swift: Protocol for testable time (SystemTimeProvider, FakeTimeProvider)
• RetryStateMachine.swift: Decision engine handling 200, 429, and 5xx responses
• HTTPClient.swift: Integration with shouldUploadBatch/handleResponse
• Storage.swift: Persistence via PropertyListEncoder/Decoder

Test Coverage

• 21 tests passing across 6 test files
• Unit tests for all components
• Chain tests validating 429→429→200 and 500→500→200 sequences
• Integration test confirming end-to-end behavior
• Time manipulation using FakeTimeProvider for deterministic results

Configuration Example

let config = Configuration(writeKey: "key")
    .httpConfig(HttpConfig(
        rateLimitConfig: RateLimitConfig(
            enabled: true,
            maxRetries: 5,
            useRetryAfterHeader: true,
            defaultRetryAfterSeconds: 300
        ),
        backoffConfig: BackoffConfig(
            enabled: true,
            maxRetryCount: 3,
            initialDelaySeconds: 1.0,
            maxDelaySeconds: 300.0,
            multiplier: 2.0,
            jitterFactor: 0.1,
            maxTotalBackoffDuration: 3600
        )
    ))

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 89.62656% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.30%. Comparing base (110db3b) to head (2ed67f1).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...rces/Segment/Utilities/Networking/HTTPClient.swift	45.00%	22 Missing ⚠️
Sources/Segment/Utilities/Retry/TimeProvider.swift	81.81%	2 Missing ⚠️
...es/Segment/Utilities/Retry/RetryStateMachine.swift	99.07%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #426      +/-   ##
==========================================
+ Coverage   71.20%   72.30%   +1.09%     
==========================================
  Files          49       54       +5     
  Lines        3706     3943     +237     
==========================================
+ Hits         2639     2851     +212     
- Misses       1067     1092      +25     

Files with missing lines	Coverage Δ
Sources/Segment/Configuration.swift	77.89% <100.00%> (+0.97%)	⬆️
Sources/Segment/Utilities/Retry/HttpConfig.swift	100.00% <100.00%> (ø)
Sources/Segment/Utilities/Retry/RetryState.swift	100.00% <100.00%> (ø)
Sources/Segment/Utilities/Retry/RetryTypes.swift	100.00% <100.00%> (ø)
Sources/Segment/Utilities/Storage/Storage.swift	95.52% <100.00%> (+0.56%)	⬆️
...es/Segment/Utilities/Retry/RetryStateMachine.swift	99.07% <99.07%> (ø)
Sources/Segment/Utilities/Retry/TimeProvider.swift	81.81% <81.81%> (ø)
...rces/Segment/Utilities/Networking/HTTPClient.swift	50.00% <45.00%> (-4.00%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[didiergarcia]

Test Coverage Update

Expanded test coverage from 17 to 52 tests to match analytics-kotlin implementation.

Detailed Breakdown:

RetryStateMachine_Tests: 25 tests (+20)

• ✅ Status code overrides (408→RETRY, 501→DROP)
• ✅ 4xx/5xx default behaviors
• ✅ Unknown code handling
• ✅ Exponential backoff verification
• ✅ Rate limit edge cases (clamps, defaults, global retry count reset)
• ✅ shouldUploadBatch drops (max retries, max duration exceeded)
• ✅ getRetryCount all scenarios (new batch, per-batch, global, max)
• ✅ Legacy mode comprehensive tests (all features disabled)

HttpConfig_Tests: 13 tests (+10)

• ✅ Validation and clamping (min/max bounds)
• ✅ Status code override filtering (invalid codes removed)
• ✅ Negative value handling
• ✅ Automatic validation on init

Storage_RetryState_Tests: 7 tests (+5)

• ✅ Persistence edge cases (null fields, overwrites, multiple batches)

RetryChain_Tests: 2 tests

• ✅ 429→429→200 chain validation
• ✅ 500→500→200 chain validation

RetryState_Tests: 4 tests
RetryTypes_Tests: 1 test

All 52 tests passing ✅

[didiergarcia]

Persistence Validation Tests Added

Based on React Native RetryManager review (PR #1159), added 7 validation tests to guard against corrupted persisted state.

Tests Added:

RetryState_Tests (+5):

• ✅ Unreasonable waitUntilTime handling (infinite blocking risk)
• ✅ Clock skew on firstFailureTime (conservative behavior when clock goes backwards)
• ✅ Negative failureCount behavior (documents bypass of max retry check)
• ✅ Nil waitUntilTime protection
• ✅ Nil firstFailureTime protection

Storage_RetryState_Tests (+2):

• ✅ Corrupt PropertyList data returns safe defaults
• ✅ Extreme values (Int.max, far-future timestamps) load without error

Why These Tests Matter:

Clock Skew Scenarios:

• NTP time sync corrections
• User manual clock adjustment
• Daylight saving transitions
• Device replacing battery (clock reset)

Storage Corruption:

• Disk I/O errors
• App crash during write
• iOS storage cleanup
• Schema changes between app versions

Test Count: 52 → 59 tests

All 59 tests passing ✅

Commit: 2ed67f1