feat(core): integrate TAPI backoff v2 into upload flow (3/3)

[abueide]

Overview

This PR integrates the backoff infrastructure and error classification system into the SegmentDestination upload flow, completing the TAPI backoff v2 implementation.

Related PRs:

• Part 1: Infrastructure (feat(core): add TAPI backoff v2 infrastructure (1/3) #1149)
• Part 2: Error classification (feat(core): add error classification and default HTTP config (3/3) #1150)

SegmentDestination Changes

Upload Gate

Before processing any batches, the upload flow now checks if uploads are allowed based on the rate limit state:

if (this.backoffInitialized && this.uploadStateMachine) {
  const canUpload = await this.uploadStateMachine.canUpload();
  if (!canUpload) {
    return; // Defer upload until rate limit period expires
  }
}

Batch Metadata Lifecycle

Batch metadata is now created lazily to avoid unnecessary persistence overhead:

1. Before first upload attempt: No metadata exists
2. On first transient error: Metadata created with createBatch()
3. On subsequent errors: Metadata updated with handleRetry()
4. On success: Metadata removed with removeBatch()

Error Handling by Type

Rate Limit (429):
When a 429 response is received, the upload state machine is updated with the retry-after duration and the upload loop halts immediately to prevent wasted API calls.

Transient Errors (5xx, network failures):
Batch metadata is created or updated with exponential backoff timing. The upload loop continues to the next batch, allowing other batches to be attempted.

Permanent Errors (4xx):
The batch is immediately dropped and removed from the queue. No retry is attempted.

Retry Count Header

The implementation now sends an X-Retry-Count header with each upload request, using either the per-batch retry count or the global retry count:

const retryCount = batchRetryCount || globalRetryCount;
await uploadEvents({ writeKey, url, events: batch, retryCount });

Dynamic Module Import

The backoff module is loaded dynamically to avoid circular dependencies:

import('../backoff')
  .then(({ UploadStateMachine, BatchUploadManager }) => {
    // Initialize components
    this.backoffInitialized = true;
    this.settingsResolve();
  });

This approach ensures the settings promise only resolves after backoff components are initialized, preventing race conditions.

API Changes

keepalive Flag

The fetch request now includes the keepalive flag to ensure uploads can complete even if the app is backgrounded or closed:

fetch(url, {
  method: 'POST',
  keepalive: true,
  body: ...
});

X-Retry-Count Header

A new header is included in upload requests to help with debugging and monitoring:

headers: {
  'Content-Type': 'application/json; charset=utf-8',
  'Authorization': authHeader,
  'X-Retry-Count': retryCount.toString()
}

Logger Changes

The logger constructor now defaults to disabled in production environments:

constructor(isDisabled: boolean = process.env.NODE_ENV === 'production')

This prevents unexpected logging output in production builds while maintaining debug capability in development.

Code Quality Improvements

This PR includes several improvements from code review:

• Removed all debug console.log statements
• Added error logging to all catch blocks
• Used appropriate log levels (info for normal operations, error for failures)
• Simplified upload gate logic for better readability
• Simplified retry count logic using logical OR operator

Initialization Flow

1. SegmentDestination receives settings from Settings CDN
2. Backoff module is dynamically imported
3. Config validation is applied to rate limit and backoff configs
4. UploadStateMachine and BatchUploadManager are instantiated
5. backoffInitialized flag is set to true
6. Settings promise resolves, allowing uploads to proceed

If initialization fails at any step, uploads proceed without backoff (graceful degradation).

Testing

Manual testing has verified the following scenarios:

• Successful uploads do not create batch metadata
• 429 responses trigger rate limiting with proper wait times
• 5xx responses create batch metadata with exponential backoff
• App restart validates and drops corrupt metadata
• All error paths include appropriate logging

Dependencies

This PR depends on #1149 and #1150 being merged first, as it integrates the components added in those PRs.

[abueide]

Note: Integration tests for the upload flow will be added in a separate PR to keep the review focused on the implementation.

[abueide]

Closing this integration PR as we're keeping the implementation PRs separate for easier review. The integration will be done after all component PRs (#1153, #1152, #1150) have been reviewed and merged.