Skip to content

feat(core): add error classification and default HTTP config (3/3)#1150

Draft
abueide wants to merge 5 commits intomasterfrom
feature/tapi-errors
Draft

feat(core): add error classification and default HTTP config (3/3)#1150
abueide wants to merge 5 commits intomasterfrom
feature/tapi-errors

Conversation

@abueide
Copy link
Contributor

@abueide abueide commented Mar 6, 2026

Summary

  • Adds classifyError() for SDD-compliant HTTP error classification
  • Adds parseRetryAfter() supporting seconds and HTTP-date formats
  • Adds ErrorClassification type to types.ts
  • Adds defaultHttpConfig to constants.ts with SDD defaults
  • Preserves maxPendingEvents (used by analytics.ts)

Merge order

Depends on #1152. Rebase onto master after #1152 lands.

  1. feat(core): add UploadStateMachine for rate limiting (1/3) #1153 — UploadStateMachine + rate limit types
  2. feat(core): add BackoffManager for transient error backoff (2/3) #1152 — BackoffManager + backoff types
  3. feat(core): add error classification and default HTTP config (3/3) #1150 (this) — Error classification + defaultHttpConfig

Components

classifyError() (35 lines)

Classifies HTTP status codes per the SDD error handling tables.

Precedence: statusCodeOverrides -> 429 special handling -> default4xx/5xxBehavior -> permanent fallback

Returns: { isRetryable, errorType: 'rate_limit' | 'transient' | 'permanent' }

parseRetryAfter() (18 lines)

Parses Retry-After header values.

  • Supports seconds format: "60" -> 60
  • Supports HTTP-date format: "Fri, 31 Dec 2026 23:59:59 GMT" -> calculated delay
  • Clamped to maxRetryInterval (default 300s)

defaultHttpConfig (27 lines)

Production-ready defaults per the SDD:

  • Rate limiting: enabled, 100 retries, 300s max interval, 12h max duration
  • Backoff: enabled, 100 retries, 0.5s base, 300s max, 12h max duration, 10% jitter
  • Status code overrides: 408/410/429/460 retry, 501/505 drop

Test plan

  • Existing test suites pass (no broken imports)
  • maxPendingEvents still exported and importable
  • No unrelated diffs

@abueide
Copy link
Contributor Author

abueide commented Mar 6, 2026

Note: Unit tests for error classification will be added in a separate PR to keep the review focused on the implementation.

@abueide abueide marked this pull request as draft March 6, 2026 20:22
@abueide abueide marked this pull request as draft March 6, 2026 20:22
@abueide abueide self-assigned this Mar 6, 2026
@abueide abueide force-pushed the feature/tapi-errors branch from e40db0b to 54acb5d Compare March 6, 2026 20:44
abueide added a commit that referenced this pull request Mar 6, 2026
Adds comprehensive extended test suites for edge cases and implementation
details that supplement the core tests in the feature PRs:

- UploadStateMachine.extended.test.ts: disabled config, multiple retries,
  getter tests, persistence tests
- BatchUploadManager.extended.test.ts: unique IDs, disabled config, getter
  tests, detailed exponential backoff algorithm tests, persistence tests
- SegmentDestination.extended.test.ts: state reset after success, legacy
  behavior, Retry-After header parsing

These tests provide thorough coverage of edge cases, backwards compatibility,
and implementation details without adding bulk to the core feature PRs.

Related to PRs: #1150, #1151, #1152, #1153

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
abueide and others added 3 commits March 6, 2026 16:13
Add the UploadStateMachine component for managing global rate limiting
state for 429 responses, along with supporting types and config validation.

Components:
- RateLimitConfig, UploadStateData, HttpConfig types
- validateRateLimitConfig with SDD-specified bounds
- UploadStateMachine with canUpload/handle429/reset/getGlobalRetryCount
- Core test suite (10 tests) and test helpers
- backoff/index.ts barrel export

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add global transient error backoff manager that replaces the per-batch
BatchUploadManager. Uses same exponential backoff formula from the SDD
but tracks state globally rather than per-batch, which aligns with the
RN SDK's queue model where batch identities are ephemeral.

Components:
- BackoffConfig, BackoffStateData types
- Expanded HttpConfig to include backoffConfig
- validateBackoffConfig with SDD-specified bounds
- BackoffManager with canRetry/handleTransientError/reset/getRetryCount
- Core test suite (12 tests)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add classifyError and parseRetryAfter functions for TAPI error handling,
plus production-ready default HTTP configuration per the SDD.

Components:
- ErrorClassification type
- classifyError() with SDD precedence: overrides -> 429 special -> defaults -> permanent
- parseRetryAfter() supporting seconds and HTTP-date formats
- defaultHttpConfig with SDD defaults (rate limit + backoff configs)
- maxPendingEvents preserved (used by analytics.ts)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@abueide abueide force-pushed the feature/tapi-errors branch from 9111eb7 to 0b64eba Compare March 6, 2026 22:19
@abueide abueide changed the title feat(core): add flexible error classification for backoff (2/3) feat(core): add error classification and default HTTP config (3/3) Mar 6, 2026
abueide and others added 2 commits March 6, 2026 17:09
…tion

Improvements:
- Add comprehensive JSDoc comments for classifyError and parseRetryAfter
- Create comprehensive test suite (33 tests) covering all edge cases
- Test SDD-specified error code behavior (408, 410, 429, 460, 501, 505)
- Test override precedence and default behaviors
- Test Retry-After parsing (seconds and HTTP-date formats)
- Test edge cases (negative codes, invalid inputs, past dates)

All 33 tests pass. Ready for review.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add validation to reject negative seconds in parseRetryAfter()
- Update test to verify negative values are handled correctly
- Negative strings fall through to date parsing (acceptable behavior)

All 33 tests pass. Ready for review.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant