@chipmobilesdk/rn-payment 0.4.0 → 0.5.0

package/src/core/retry.ts

@@ -1,133 +1,95 @@
-/**
- * Bounded backoff.
- *
- * "Bounded" is the whole point (FR-020, FR-045): an unbounded reconnect loop
- * against a billing service that is down drains battery and hammers a system
- * service, and an unbounded finalize loop hides a real failure behind noise.
- *
- * Delay computation is pure and separated from waiting so tests can assert the
- * schedule without burning real time.
- */
-
-import type { BackoffConfig } from '../config/types';
-
-/** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
-type TimerHandle = ReturnType<typeof setTimeout> | number;
-
-/**
- * Delay before `attempt` (1-based), capped and optionally jittered.
- *
- * Jitter is full jitter over [0, capped]: several devices that lost the billing
- * connection at the same moment should not retry in lockstep.
- */
-export function backoffDelayMs(
-	attempt: number,
-	config: Required<BackoffConfig>,
-	random: () => number = Math.random,
-): number {
-	const raw = config.initialDelayMs * Math.pow(config.factor, attempt - 1);
-	const capped = Math.min(raw, config.maxDelayMs);
-	return config.jitter ? Math.floor(capped * random()) : capped;
-}
-
-/** The full schedule, for asserting a retry policy without waiting for it. */
-export function backoffSchedule(config: Required<BackoffConfig>): number[] {
-	const delays: number[] = [];
-	for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
-		delays.push(backoffDelayMs(attempt, config, () => 1));
-	}
-	return delays;
-}
-
-export interface RetryHandle {
-	/** Cancels any pending attempt. Idempotent, so cleanup can call it freely (FR-082). */
-	cancel(): void;
-	/** Attempts consumed so far, so a retry storm is observable rather than inferred. */
-	attempts(): number;
-	/** True once the per-session budget is spent. */
-	exhausted(): boolean;
-}
-
-export interface RetryRunnerOptions {
-	config: Required<BackoffConfig>;
-	/** Return true when the attempt succeeded and retrying should stop. */
-	attempt: (attemptNumber: number) => Promise<boolean>;
-	/** Called once the per-session budget is spent without success. */
-	onExhausted?: (attempts: number) => void;
-	/**
-	 * Injected so a test can run the whole schedule synchronously instead of
-	 * waiting minutes of real backoff. The handle is opaque, because a Node
-	 * `Timeout` and a browser numeric id are both valid here.
-	 */
-	setTimeoutFn?: (fn: () => void, ms: number) => TimerHandle;
-	clearTimeoutFn?: (handle: TimerHandle) => void;
-	random?: () => number;
-}
-
-/**
- * Runs `attempt` under the bounded schedule.
- *
- * Exhaustion is reported rather than thrown: for finalization, a spent session
- * budget is not a failure but a handoff to the next launch, and the caller is
- * the only one that knows which of the two it is.
- */
-export function runWithRetry(options: RetryRunnerOptions): RetryHandle {
-	const {
-		config,
-		attempt,
-		onExhausted,
-		setTimeoutFn = setTimeout,
-		clearTimeoutFn = clearTimeout,
-		random = Math.random,
-	} = options;
-
-	let attemptCount = 0;
-	let cancelled = false;
-	let pending: TimerHandle | undefined;
-
-	const schedule = (delayMs: number): void => {
-		pending = setTimeoutFn(() => {
-			pending = undefined;
-			run().catch(() => undefined);
-		}, delayMs);
-	};
-
-	const run = async (): Promise<void> => {
-		if (cancelled) {
-			return;
-		}
-		attemptCount += 1;
-		let succeeded = false;
-		try {
-			succeeded = await attempt(attemptCount);
-		} catch {
-			// A throwing attempt is a failed attempt, nothing more. Letting it escape
-			// would abandon the schedule and, for finalization, silently drop a paid
-			// transaction.
-			succeeded = false;
-		}
-		if (cancelled || succeeded) {
-			return;
-		}
-		if (attemptCount >= config.maxAttempts) {
-			onExhausted?.(attemptCount);
-			return;
-		}
-		schedule(backoffDelayMs(attemptCount + 1, config, random));
-	};
-
-	// Fire the first attempt immediately; the schedule owns everything after it.
-	run().catch(() => undefined);
-
-	return {
-		cancel(): void {
-			cancelled = true;
-			if (pending !== undefined) {
-				clearTimeoutFn(pending);
-				pending = undefined;
-			}
-		},
-		attempts: () => attemptCount,
-		exhausted: () => attemptCount >= config.maxAttempts,
-	};
-}
+/**
+ * Bounded backoff.
+ *
+ * "Bounded" is the whole point (FR-020, FR-045): an unbounded reconnect loop
+ * against a billing service that is down drains battery and hammers a system
+ * service, and an unbounded finalize loop hides a real failure behind noise.
+ *
+ * Delay computation is pure and separated from waiting so tests can assert the
+ * schedule without burning real time.
+ */
+
+import {
+	computeBackoff,
+	runWithRetry as runCoreRetry,
+	type RetryHandle,
+} from '@chipmobilesdk/rn-core';
+
+import type { BackoffConfig } from '../config/types';
+
+/** Opaque timer handle: a Node Timeout and a browser numeric id are both valid. */
+type TimerHandle = ReturnType<typeof setTimeout> | number;
+
+/**
+ * Delay before `attempt` (1-based), capped and optionally jittered.
+ *
+ * Jitter is full jitter over [0, capped]: several devices that lost the billing
+ * connection at the same moment should not retry in lockstep.
+ */
+export function backoffDelayMs(
+	attempt: number,
+	config: Required<BackoffConfig>,
+	random: () => number = Math.random,
+): number {
+	return computeBackoff(attempt, toSpec(config), random);
+}
+
+function toSpec(config: Required<BackoffConfig>) {
+	return {
+		initialDelayMs: config.initialDelayMs,
+		maxDelayMs: config.maxDelayMs,
+		factor: config.factor,
+		jitter: config.jitter ? ('full' as const) : ('none' as const),
+		maxAttempts: config.maxAttempts,
+	};
+}
+
+/** The full schedule, for asserting a retry policy without waiting for it. */
+export function backoffSchedule(config: Required<BackoffConfig>): number[] {
+	const delays: number[] = [];
+	for (let attempt = 1; attempt <= config.maxAttempts; attempt += 1) {
+		delays.push(backoffDelayMs(attempt, config, () => 1));
+	}
+	return delays;
+}
+
+export type { RetryHandle } from '@chipmobilesdk/rn-core';
+
+export interface RetryRunnerOptions {
+	config: Required<BackoffConfig>;
+	/** Return true when the attempt succeeded and retrying should stop. */
+	attempt: (attemptNumber: number) => Promise<boolean>;
+	/** Called once the per-session budget is spent without success. */
+	onExhausted?: (attempts: number) => void;
+	/**
+	 * Injected so a test can run the whole schedule synchronously instead of
+	 * waiting minutes of real backoff. The handle is opaque, because a Node
+	 * `Timeout` and a browser numeric id are both valid here.
+	 */
+	setTimeoutFn?: (fn: () => void, ms: number) => TimerHandle;
+	clearTimeoutFn?: (handle: TimerHandle) => void;
+	random?: () => number;
+}
+
+/**
+ * Runs `attempt` under the bounded schedule (rn-core's runner).
+ *
+ * Exhaustion is reported rather than thrown: for finalization, a spent session
+ * budget is not a failure but a handoff to the next launch, and the caller is
+ * the only one that knows which of the two it is. A throwing attempt is a failed
+ * attempt, nothing more: letting it escape would silently drop a paid transaction.
+ */
+export function runWithRetry(options: RetryRunnerOptions): RetryHandle {
+	const setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+	return runCoreRetry({
+		spec: toSpec(options.config),
+		attempt: options.attempt,
+		onExhausted: options.onExhausted,
+		random: options.random,
+		scheduler: {
+			setTimeout: (callback, ms) => setTimeoutFn(callback, ms),
+			clearTimeout: handle => clearTimeoutFn(handle as TimerHandle),
+		},
+	});
+}