From e0f1c5ccd7a4cbe45e862730ef5925ddd21463fc Mon Sep 17 00:00:00 2001 From: Patrick Bennett <170563+pbennett@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:03:04 -0500 Subject: [PATCH] feat(client): retry a quote the router is too busy for after its retry-after The router's quote gate answers a quote it is too busy to compute with 503 and Retry-After: 1. request() now waits that out and retries once, so a burst of load costs the caller a second rather than an error. Only a 503 with a Retry-After of at most 5 seconds is retried; a 429, any other 503 and a second busy 503 are thrown as HTTPError as before. Aborting the request's signal ends the wait. --- .claude/CLAUDE.md | 1 + packages/haystack/README.md | 2 + packages/haystack/src/utils.ts | 105 ++++++++++++++++++++---- packages/haystack/tests/utils.test.ts | 114 ++++++++++++++++++++++++++ 4 files changed, 205 insertions(+), 17 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 5363e03..46def38 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -59,6 +59,7 @@ The public API is whatever `src/index.ts` re-exports: client, composer, constant - `Logger` is a static singleton. Each `RouterClient`/`SwapComposer` constructor overwrites the global level. Its `sanitize()` redacts `apiKey`, `algodToken`, signature values and `txnPayload`. Keep that redaction when you add log calls. - Asset and app IDs, and amounts, are `bigint` in `QuoteContext`/`SwapContext`/`SwapQuote`. The raw API response uses numbers and strings. - All HTTP goes through `utils.request()`, which throws `HTTPError`. Tests mock `../src/utils` or stub `algodClient.().do()`. No network calls in tests. +- `request()` retries once a `503` carrying a `Retry-After` of at most 5 s (the router's quote gate sheds a quote it's too busy for with `Retry-After: 1`). It waits that long and reads the first body to its end; aborting `options.signal` ends the wait. A `429`, a `503` without the header or with a longer or HTTP-date one, and a second busy `503` are thrown as `HTTPError`. Tests use fake timers for it. ## Commits and releases diff --git a/packages/haystack/README.md b/packages/haystack/README.md index 71ad7e0..019d00a 100644 --- a/packages/haystack/README.md +++ b/packages/haystack/README.md @@ -461,6 +461,8 @@ try { } ``` +API errors are thrown as `HTTPError`, with the response's `status` and its body in `data`. When the router is too busy to compute a quote, it answers `503` with `Retry-After: 1`. The SDK waits that second and retries once. If the router is still busy, it throws the `503` for you to retry later. A `429` (rate limit) is thrown at once: wait its `Retry-After` before retrying. + ## API Reference ### RouterClient diff --git a/packages/haystack/src/utils.ts b/packages/haystack/src/utils.ts index b8250fa..acd0972 100644 --- a/packages/haystack/src/utils.ts +++ b/packages/haystack/src/utils.ts @@ -12,14 +12,29 @@ export class HTTPError extends Error { } } +/** + * How many times a request answered `503` with a `Retry-After` is retried. + * The router answers a quote it is too busy to compute that way, with + * `Retry-After: 1`; the retry may reach a less busy server. + */ +const BUSY_RETRIES = 1 + +/** + * The longest `Retry-After` the SDK waits out. A longer one is thrown as the + * `HTTPError`, for the caller to decide. + */ +const MAX_RETRY_AFTER_MS = 5_000 + /** * Make an HTTP request and parse JSON response * - * Simple wrapper around native fetch for API calls. Throws HTTPError for - * non-2xx responses. + * Simple wrapper around native fetch for API calls. A `503` carrying a + * `Retry-After` of at most 5 seconds (the router too busy to quote) is + * retried once after that wait. Throws HTTPError for any other non-2xx + * response, and for a `503` still answered after its retry. * * @param url - The URL to request - * @param options - Fetch options + * @param options - Fetch options; aborting `options.signal` also ends the wait * @returns Parsed JSON response * @throws HTTPError if the response status is not ok */ @@ -27,27 +42,83 @@ export async function request( url: string, options?: RequestInit, ): Promise { - const response = await fetch(url, options) + for (let attempt = 0; ; attempt++) { + const response = await fetch(url, options) - if (!response.ok) { - let errorData: unknown + if (!response.ok) { + const wait = attempt < BUSY_RETRIES ? busyRetryDelay(response) : undefined + if (wait !== undefined) { + await discardBody(response) + await delay(wait, options?.signal) + continue + } + + let errorData: unknown - try { - errorData = await response.json() - } catch { try { - errorData = await response.text() + errorData = await response.json() } catch { - errorData = 'Failed to parse error response' + try { + errorData = await response.text() + } catch { + errorData = 'Failed to parse error response' + } } + + throw new HTTPError( + response.status, + response.statusText, + JSON.stringify(errorData), + ) } - throw new HTTPError( - response.status, - response.statusText, - JSON.stringify(errorData), - ) + return response.json() as Promise } +} - return response.json() as Promise +/** + * The wait in milliseconds before retrying a busy `503`: its `Retry-After` in + * seconds, when it is at most MAX_RETRY_AFTER_MS. Undefined for any other + * response, which isn't retried. + */ +function busyRetryDelay(response: Response): number | undefined { + if (response.status !== 503) { + return undefined + } + const header = response.headers?.get('Retry-After') + if (!header) { + return undefined + } + const ms = Number(header) * 1000 + return Number.isFinite(ms) && ms >= 0 && ms <= MAX_RETRY_AFTER_MS + ? ms + : undefined +} + +/** Reads a response's body to its end, so its connection can be reused. */ +async function discardBody(response: Response): Promise { + try { + await response.text() + } catch { + // nothing to free + } +} + +/** Resolves after ms, or rejects with the signal's reason once it aborts. */ +function delay(ms: number, signal?: AbortSignal | null): Promise { + return new Promise((resolve, reject) => { + if (signal?.aborted) { + reject(signal.reason) + return + } + const onAbort = () => { + clearTimeout(timer) + reject(signal?.reason) + } + const timer = setTimeout(() => { + signal?.removeEventListener('abort', onAbort) + resolve() + }, ms) + signal?.addEventListener('abort', onAbort, { once: true }) + }) } diff --git a/packages/haystack/tests/utils.test.ts b/packages/haystack/tests/utils.test.ts index a24c7e6..3b987c8 100644 --- a/packages/haystack/tests/utils.test.ts +++ b/packages/haystack/tests/utils.test.ts @@ -201,6 +201,120 @@ describe('request', () => { expect(result).toBeNull() }) + describe('busy retry', () => { + const busy = (retryAfter?: string) => ({ + ok: false, + status: 503, + statusText: 'Service Unavailable', + headers: new Headers( + retryAfter === undefined ? {} : { 'Retry-After': retryAfter }, + ), + json: async () => { + throw new Error('Invalid JSON') + }, + text: async () => 'quote not started: the router is busy\n', + }) + const ok = (data: unknown) => ({ ok: true, json: async () => data }) + + beforeEach(() => { + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + it('retries a 503 once after its Retry-After', async () => { + global.fetch = vi + .fn() + .mockResolvedValueOnce(busy('1')) + .mockResolvedValueOnce(ok({ quote: '1' })) + + const result = request('https://api.example.com/fetchQuote') + await vi.advanceTimersByTimeAsync(999) + expect(global.fetch).toHaveBeenCalledTimes(1) + await vi.advanceTimersByTimeAsync(1) + + await expect(result).resolves.toEqual({ quote: '1' }) + expect(global.fetch).toHaveBeenCalledTimes(2) + }) + + it('throws the 503 when the retry is busy too', async () => { + global.fetch = vi.fn().mockResolvedValue(busy('1')) + + const result = request('https://api.example.com/fetchQuote') + const caught = result.catch((error: unknown) => error) + await vi.advanceTimersByTimeAsync(1000) + + const error = await caught + expect(error).toBeInstanceOf(HTTPError) + expect((error as HTTPError).status).toBe(503) + expect((error as HTTPError).data).toBe( + JSON.stringify('quote not started: the router is busy\n'), + ) + expect(global.fetch).toHaveBeenCalledTimes(2) + }) + + it.each([ + ['no Retry-After', undefined], + ['a Retry-After over 5 s', '6'], + ['an HTTP-date Retry-After', 'Wed, 21 Oct 2026 07:28:00 GMT'], + ['a negative Retry-After', '-1'], + ])('throws a 503 with %s at once', async (_, retryAfter) => { + global.fetch = vi.fn().mockResolvedValue(busy(retryAfter)) + + await expect( + request('https://api.example.com/fetchQuote'), + ).rejects.toBeInstanceOf(HTTPError) + expect(global.fetch).toHaveBeenCalledTimes(1) + }) + + it('waits out a Retry-After of exactly 5 s', async () => { + global.fetch = vi + .fn() + .mockResolvedValueOnce(busy('5')) + .mockResolvedValueOnce(ok({ quote: '1' })) + + const result = request('https://api.example.com/fetchQuote') + await vi.advanceTimersByTimeAsync(5000) + + await expect(result).resolves.toEqual({ quote: '1' }) + expect(global.fetch).toHaveBeenCalledTimes(2) + }) + + it('does not retry a 429', async () => { + global.fetch = vi.fn().mockResolvedValue({ + ...busy('1'), + status: 429, + statusText: 'Too Many Requests', + }) + + await expect( + request('https://api.example.com/fetchQuote'), + ).rejects.toBeInstanceOf(HTTPError) + expect(global.fetch).toHaveBeenCalledTimes(1) + }) + + it('stops waiting when the signal aborts', async () => { + global.fetch = vi + .fn() + .mockResolvedValueOnce(busy('1')) + .mockResolvedValueOnce(ok({ quote: '1' })) + const controller = new AbortController() + + const result = request('https://api.example.com/fetchQuote', { + signal: controller.signal, + }) + const caught = result.catch((error: unknown) => error) + await vi.advanceTimersByTimeAsync(500) + controller.abort(new Error('cancelled')) + + expect(await caught).toEqual(new Error('cancelled')) + await vi.advanceTimersByTimeAsync(1000) + expect(global.fetch).toHaveBeenCalledTimes(1) + }) + }) + it('should handle array responses', async () => { const mockData = [{ id: 1 }, { id: 2 }, { id: 3 }]