|
| 1 | +import { createStore } from '@segment/sovran-react-native'; |
| 2 | +import type { Store, Persistor } from '@segment/sovran-react-native'; |
| 3 | +import type { LoggerType, RateLimitConfig, BackoffConfig } from '../types'; |
| 4 | + |
| 5 | +type RetryStateData = { |
| 6 | + state: 'READY' | 'RATE_LIMITED' | 'BACKING_OFF'; |
| 7 | + waitUntilTime: number; |
| 8 | + retryCount: number; |
| 9 | + firstFailureTime: number | null; |
| 10 | +}; |
| 11 | + |
| 12 | +const INITIAL_STATE: RetryStateData = { |
| 13 | + state: 'READY', |
| 14 | + waitUntilTime: 0, |
| 15 | + retryCount: 0, |
| 16 | + firstFailureTime: null, |
| 17 | +}; |
| 18 | + |
| 19 | +/** |
| 20 | + * Unified retry manager for both rate limiting (429) and transient errors (5xx). |
| 21 | + * Handles wait times from server (429 Retry-After) or calculated exponential backoff (5xx). |
| 22 | + */ |
| 23 | +export class RetryManager { |
| 24 | + private store: Store<RetryStateData>; |
| 25 | + private rateLimitConfig?: RateLimitConfig; |
| 26 | + private backoffConfig?: BackoffConfig; |
| 27 | + private logger?: LoggerType; |
| 28 | + |
| 29 | + /** |
| 30 | + * Creates a RetryManager instance. |
| 31 | + * |
| 32 | + * @param storeId - Unique identifier for the store (typically writeKey) |
| 33 | + * @param persistor - Optional persistor for state persistence |
| 34 | + * @param rateLimitConfig - Optional rate limit configuration (for 429 handling) |
| 35 | + * @param backoffConfig - Optional backoff configuration (for transient errors) |
| 36 | + * @param logger - Optional logger for debugging |
| 37 | + */ |
| 38 | + constructor( |
| 39 | + storeId: string, |
| 40 | + persistor: Persistor | undefined, |
| 41 | + rateLimitConfig?: RateLimitConfig, |
| 42 | + backoffConfig?: BackoffConfig, |
| 43 | + logger?: LoggerType |
| 44 | + ) { |
| 45 | + this.rateLimitConfig = rateLimitConfig; |
| 46 | + this.backoffConfig = backoffConfig; |
| 47 | + this.logger = logger; |
| 48 | + |
| 49 | + try { |
| 50 | + this.store = createStore<RetryStateData>( |
| 51 | + INITIAL_STATE, |
| 52 | + persistor |
| 53 | + ? { |
| 54 | + persist: { |
| 55 | + storeId: `${storeId}-retryState`, |
| 56 | + persistor, |
| 57 | + }, |
| 58 | + } |
| 59 | + : undefined |
| 60 | + ); |
| 61 | + } catch (e) { |
| 62 | + const errorMessage = e instanceof Error ? e.message : String(e); |
| 63 | + this.logger?.error( |
| 64 | + `[RetryManager] Persistence failed, using in-memory store: ${errorMessage}` |
| 65 | + ); |
| 66 | + |
| 67 | + try { |
| 68 | + this.store = createStore<RetryStateData>(INITIAL_STATE); |
| 69 | + } catch (fallbackError) { |
| 70 | + const fallbackMessage = |
| 71 | + fallbackError instanceof Error |
| 72 | + ? fallbackError.message |
| 73 | + : String(fallbackError); |
| 74 | + this.logger?.error( |
| 75 | + `[RetryManager] CRITICAL: In-memory store creation failed: ${fallbackMessage}` |
| 76 | + ); |
| 77 | + throw fallbackError; |
| 78 | + } |
| 79 | + } |
| 80 | + } |
| 81 | + |
| 82 | + /** |
| 83 | + * Check if retries can proceed based on current state. |
| 84 | + * Automatically transitions to READY when wait time has passed. |
| 85 | + * |
| 86 | + * @returns true if operations should proceed, false if blocked |
| 87 | + */ |
| 88 | + async canRetry(): Promise<boolean> { |
| 89 | + const state = await this.store.getState(); |
| 90 | + const now = Date.now(); |
| 91 | + |
| 92 | + if (state.state === 'READY') { |
| 93 | + return true; |
| 94 | + } |
| 95 | + |
| 96 | + if (now >= state.waitUntilTime) { |
| 97 | + await this.transitionToReady(); |
| 98 | + return true; |
| 99 | + } |
| 100 | + |
| 101 | + const waitSeconds = Math.ceil((state.waitUntilTime - now) / 1000); |
| 102 | + const stateType = state.state === 'RATE_LIMITED' ? 'rate limited' : 'backing off'; |
| 103 | + this.logger?.info( |
| 104 | + `Upload blocked: ${stateType}, retry in ${waitSeconds}s (retry ${state.retryCount})` |
| 105 | + ); |
| 106 | + return false; |
| 107 | + } |
| 108 | + |
| 109 | + /** |
| 110 | + * Handle a 429 rate limit response. |
| 111 | + * Uses server-specified wait time from Retry-After header. |
| 112 | + * |
| 113 | + * @param retryAfterSeconds - Delay in seconds from Retry-After header (validated and clamped) |
| 114 | + */ |
| 115 | + async handle429(retryAfterSeconds: number): Promise<void> { |
| 116 | + if (!this.rateLimitConfig?.enabled) { |
| 117 | + return; |
| 118 | + } |
| 119 | + |
| 120 | + // Validate and clamp input |
| 121 | + if (retryAfterSeconds < 0) { |
| 122 | + this.logger?.warn( |
| 123 | + `Invalid retryAfterSeconds ${retryAfterSeconds}, using 0` |
| 124 | + ); |
| 125 | + retryAfterSeconds = 0; |
| 126 | + } |
| 127 | + if (retryAfterSeconds > this.rateLimitConfig.maxRetryInterval) { |
| 128 | + this.logger?.warn( |
| 129 | + `retryAfterSeconds ${retryAfterSeconds}s exceeds maxRetryInterval, clamping to ${this.rateLimitConfig.maxRetryInterval}s` |
| 130 | + ); |
| 131 | + retryAfterSeconds = this.rateLimitConfig.maxRetryInterval; |
| 132 | + } |
| 133 | + |
| 134 | + const now = Date.now(); |
| 135 | + const waitUntilTime = now + retryAfterSeconds * 1000; |
| 136 | + |
| 137 | + await this.handleError( |
| 138 | + 'RATE_LIMITED', |
| 139 | + waitUntilTime, |
| 140 | + this.rateLimitConfig.maxRetryCount, |
| 141 | + this.rateLimitConfig.maxRateLimitDuration, |
| 142 | + now |
| 143 | + ); |
| 144 | + } |
| 145 | + |
| 146 | + /** |
| 147 | + * Handle a transient error (5xx, network failure). |
| 148 | + * Uses exponential backoff to calculate wait time. |
| 149 | + */ |
| 150 | + async handleTransientError(): Promise<void> { |
| 151 | + if (!this.backoffConfig?.enabled) { |
| 152 | + return; |
| 153 | + } |
| 154 | + |
| 155 | + const now = Date.now(); |
| 156 | + const state = await this.store.getState(); |
| 157 | + |
| 158 | + // Calculate exponential backoff |
| 159 | + const backoffSeconds = this.calculateBackoff(state.retryCount); |
| 160 | + const waitUntilTime = now + backoffSeconds * 1000; |
| 161 | + |
| 162 | + await this.handleError( |
| 163 | + 'BACKING_OFF', |
| 164 | + waitUntilTime, |
| 165 | + this.backoffConfig.maxRetryCount, |
| 166 | + this.backoffConfig.maxTotalBackoffDuration, |
| 167 | + now |
| 168 | + ); |
| 169 | + } |
| 170 | + |
| 171 | + /** |
| 172 | + * Reset the state machine to READY with retry count 0. |
| 173 | + * Called on successful upload (2xx response). |
| 174 | + */ |
| 175 | + async reset(): Promise<void> { |
| 176 | + await this.store.dispatch(() => INITIAL_STATE); |
| 177 | + } |
| 178 | + |
| 179 | + /** |
| 180 | + * Get the current retry count for X-Retry-Count header. |
| 181 | + * |
| 182 | + * @returns Current retry count |
| 183 | + */ |
| 184 | + async getRetryCount(): Promise<number> { |
| 185 | + const state = await this.store.getState(); |
| 186 | + return state.retryCount; |
| 187 | + } |
| 188 | + |
| 189 | + /** |
| 190 | + * Core error handling logic - atomic dispatch for thread safety |
| 191 | + */ |
| 192 | + private async handleError( |
| 193 | + newState: 'RATE_LIMITED' | 'BACKING_OFF', |
| 194 | + waitUntilTime: number, |
| 195 | + maxRetryCount: number, |
| 196 | + maxRetryDuration: number, |
| 197 | + now: number |
| 198 | + ): Promise<void> { |
| 199 | + // Atomic dispatch prevents async interleaving when multiple batches fail |
| 200 | + await this.store.dispatch((state: RetryStateData) => { |
| 201 | + const newRetryCount = state.retryCount + 1; |
| 202 | + const firstFailureTime = state.firstFailureTime ?? now; |
| 203 | + const totalDuration = (now - firstFailureTime) / 1000; |
| 204 | + |
| 205 | + // Max retry count check |
| 206 | + if (newRetryCount > maxRetryCount) { |
| 207 | + this.logger?.warn( |
| 208 | + `Max retry count exceeded (${maxRetryCount}), resetting retry manager` |
| 209 | + ); |
| 210 | + return INITIAL_STATE; |
| 211 | + } |
| 212 | + |
| 213 | + // Max duration check |
| 214 | + if (totalDuration > maxRetryDuration) { |
| 215 | + this.logger?.warn( |
| 216 | + `Max retry duration exceeded (${maxRetryDuration}s), resetting retry manager` |
| 217 | + ); |
| 218 | + return INITIAL_STATE; |
| 219 | + } |
| 220 | + |
| 221 | + // If already blocked, take the longest wait time (most conservative) |
| 222 | + const finalWaitUntilTime = |
| 223 | + state.state !== 'READY' |
| 224 | + ? Math.max(state.waitUntilTime, waitUntilTime) |
| 225 | + : waitUntilTime; |
| 226 | + |
| 227 | + const stateType = newState === 'RATE_LIMITED' ? 'Rate limited (429)' : 'Transient error'; |
| 228 | + this.logger?.info( |
| 229 | + `${stateType}: waiting ${Math.ceil((finalWaitUntilTime - now) / 1000)}s before retry ${newRetryCount}` |
| 230 | + ); |
| 231 | + |
| 232 | + return { |
| 233 | + state: newState, |
| 234 | + waitUntilTime: finalWaitUntilTime, |
| 235 | + retryCount: newRetryCount, |
| 236 | + firstFailureTime, |
| 237 | + }; |
| 238 | + }); |
| 239 | + } |
| 240 | + |
| 241 | + /** |
| 242 | + * Calculate exponential backoff with jitter |
| 243 | + */ |
| 244 | + private calculateBackoff(retryCount: number): number { |
| 245 | + if (!this.backoffConfig) { |
| 246 | + return 0; |
| 247 | + } |
| 248 | + |
| 249 | + const { baseBackoffInterval, maxBackoffInterval, jitterPercent } = this.backoffConfig; |
| 250 | + |
| 251 | + // Base exponential backoff: base * 2^retryCount |
| 252 | + const exponentialBackoff = baseBackoffInterval * Math.pow(2, retryCount); |
| 253 | + |
| 254 | + // Clamp to max |
| 255 | + const clampedBackoff = Math.min(exponentialBackoff, maxBackoffInterval); |
| 256 | + |
| 257 | + // Add jitter: ±jitterPercent |
| 258 | + const jitterRange = clampedBackoff * (jitterPercent / 100); |
| 259 | + const jitter = (Math.random() * 2 - 1) * jitterRange; |
| 260 | + |
| 261 | + return Math.max(0, clampedBackoff + jitter); |
| 262 | + } |
| 263 | + |
| 264 | + private async transitionToReady(): Promise<void> { |
| 265 | + const state = await this.store.getState(); |
| 266 | + const stateType = state.state === 'RATE_LIMITED' ? 'Rate limit' : 'Backoff'; |
| 267 | + this.logger?.info(`${stateType} period expired, resuming uploads`); |
| 268 | + |
| 269 | + await this.store.dispatch((state: RetryStateData) => ({ |
| 270 | + ...state, |
| 271 | + state: 'READY' as const, |
| 272 | + })); |
| 273 | + } |
| 274 | +} |
0 commit comments