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 93.81188% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.19%. Comparing base (110db3b) to head (90a62da).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
...rces/Segment/Utilities/Networking/HTTPClient.swift	73.77%	16 Missing ⚠️
...es/Segment/Utilities/Retry/RetryStateMachine.swift	96.87%	4 Missing ⚠️
Sources/Segment/Plugins/SegmentDestination.swift	95.45%	3 Missing ⚠️
.../Segment/Utilities/Storage/Types/MemoryStore.swift	60.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #426      +/-   ##
==========================================
+ Coverage   71.20%   73.19%   +1.98%     
==========================================
  Files          49       54       +5     
  Lines        3706     4063     +357     
==========================================
+ Hits         2639     2974     +335     
- Misses       1067     1089      +22     

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/Retry/TimeProvider.swift	100.00% <100.00%> (ø)
Sources/Segment/Utilities/Storage/DataStore.swift	100.00% <ø> (ø)
Sources/Segment/Utilities/Storage/Storage.swift	95.52% <100.00%> (+0.56%)	⬆️
...ources/Segment/Utilities/Storage/TransientDB.swift	100.00% <100.00%> (ø)
...gment/Utilities/Storage/Types/DirectoryStore.swift	85.36% <100.00%> (ø)
.../Segment/Utilities/Storage/Types/MemoryStore.swift	96.92% <60.00%> (-3.08%)	⬇️
... and 3 more

... and 2 files with indirect coverage changes

🚀 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