Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<method>().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

Expand Down
2 changes: 2 additions & 0 deletions packages/haystack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
105 changes: 88 additions & 17 deletions packages/haystack/src/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,42 +12,113 @@ 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
*/
export async function request<T>(
url: string,
options?: RequestInit,
): Promise<T> {
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<T>
}
}

return response.json() as Promise<T>
/**
* 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<void> {
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<void> {
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 })
})
}
114 changes: 114 additions & 0 deletions packages/haystack/tests/utils.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }]

Expand Down
Loading