Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): performance, backend, consistency, advanced
Background
GuildPass SDK may need to retry temporary network failures such as 429 responses, transient 5xx responses, or short-lived connectivity issues. Retry behaviour should not be reimplemented independently by every API method.
This issue introduces a standalone retry policy primitive without connecting it to the SDK transport layer.
Problem
There is currently no reusable SDK abstraction for deciding whether a failed request should be retried or for calculating retry delays consistently.
Naive retries can retry permanent failures, exceed safe delay limits, or produce synchronized retry storms across clients.
Expected Outcome
Implement a deterministic retry policy module that classifies retryable outcomes and calculates bounded exponential backoff delays with optional jitter.
Suggested Implementation
Define configuration conceptually similar to:
interface RetryPolicyOptions {
maxAttempts: number;
initialDelayMs: number;
maxDelayMs: number;
multiplier: number;
jitterRatio?: number;
}The module should:
- calculate exponential backoff without executing requests;
- cap calculated delay at a configured maximum;
- support optional bounded jitter;
- allow deterministic jitter testing through an injectable random source;
- validate retry configuration;
- expose a typed decision for whether an HTTP status or error category should be retried;
- treat common transient statuses such as 429 and selected 5xx responses explicitly;
- treat most 4xx responses as non-retryable by default;
- support caller overrides for classification where practical;
- correctly interpret a supplied retry-after duration through a separate helper if included;
- avoid timers, fetch calls, or transport dependencies.
Acceptance Criteria
- Backoff delay increases according to the configured multiplier.
- Delay never exceeds the configured maximum.
- Invalid attempt numbers and invalid configuration are rejected.
- Optional jitter remains inside documented bounds.
- Jitter behaviour can be tested deterministically.
- Retryable and non-retryable HTTP status classifications are explicit and tested.
- 429 is classified according to documented retry semantics.
- Permanent client errors are not retried by default.
- Unit tests cover first attempt, later attempts, maximum delay, jitter, and status classification.
pnpm typecheck passes.pnpm build passes.pnpm test passes.- No actual HTTP retry loop is implemented in this issue.
Likely Affected Files/Directories
src/retry/ or equivalent focused module
src/types/
tests/
Independence Requirement
This issue must remain a pure retry-policy calculation task and must not depend on the transport or clock issues.
Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): performance, backend, consistency, advanced
Background
GuildPass SDK may need to retry temporary network failures such as 429 responses, transient 5xx responses, or short-lived connectivity issues. Retry behaviour should not be reimplemented independently by every API method.
This issue introduces a standalone retry policy primitive without connecting it to the SDK transport layer.
Problem
There is currently no reusable SDK abstraction for deciding whether a failed request should be retried or for calculating retry delays consistently.
Naive retries can retry permanent failures, exceed safe delay limits, or produce synchronized retry storms across clients.
Expected Outcome
Implement a deterministic retry policy module that classifies retryable outcomes and calculates bounded exponential backoff delays with optional jitter.
Suggested Implementation
Define configuration conceptually similar to:
The module should:
Acceptance Criteria
pnpm typecheckpasses.pnpm buildpasses.pnpm testpasses.Likely Affected Files/Directories
Independence Requirement
This issue must remain a pure retry-policy calculation task and must not depend on the transport or clock issues.