COW-1013: orderbook 429/backoff resilience + non-root container

[jeffersonBastos]

Closes COW-1013.

Two production-hardening items surfaced in the COW-1012 QA review (PR #97), each with tests.

1. Orderbook API resilience (429 / 5xx)

Problem. orderbookClient.ts treated every non-OK response identically: log("warn", ...) then break/continue, returning a partial/empty result. That empty result is indistinguishable downstream from "order genuinely absent" (blockHandler.ts: if (!orderbookEntry) continue; // not on API yet). So a 429/5xx caused candidate orders to silently never promote, with only warn logs — looks healthy from the status enums.

Change.

• New fetchOrderbook() wrapping fetchWithTimeout with bounded retry/backoff: honors Retry-After (delta-seconds and HTTP-date, capped at ORDERBOOK_RETRY_MAX_DELAY_MS) on 429, exponential backoff on 5xx. Stops at ORDERBOOK_MAX_RETRIES or when the next sleep would exceed ORDERBOOK_RETRY_BUDGET_MS, then throws — never holds a block-handler DB transaction open past the budget (the key constraint per withTimeout.ts).
• New OrderbookUnavailableError + distinct log codes:
  • ob:unavailable (level error, carries status) — API refused to answer. Alarm on this.
  • ob:retry (level warn) — a retry is happening.
  • A genuinely absent order (empty 2xx) stays the benign missing-UID path — no new alarm.
• Wired into fetchAccountOrders and fetchOrdersByUids. Caller control flow and return shapes are unchanged — promotion still safely defers on unavailability (retries on the next poll ~ORDERBOOK_POLL_INTERVAL blocks later), it's just now observable.

Constants (src/constants.ts): ORDERBOOK_MAX_RETRIES=2, ORDERBOOK_RETRY_BASE_MS=250, ORDERBOOK_RETRY_MAX_DELAY_MS=2000, ORDERBOOK_RETRY_BUDGET_MS=4000.

Tests (tests/helpers/orderbookClient.test.ts): two focused cases — 429-then-success (Retry-After honored) and persistent-429 → ob:unavailable after bounded retries. 5xx is already exercised by the pre-existing 500 tests (they now route through the retry/classify path), and empty-200 by the existing empty-array test.

2. Run the container as non-root

Dockerfile never set USER (ran as uid 0). Now chown -R node:node /usr/src/app /pnpm after install, then USER node before HEALTHCHECK/CMD (node:22-alpine ships node, uid 1000).

Verified: image builds; docker run → uid=1000(node); workdir owned by node and writable (Ponder cache). Full docker compose --profile deploy up end-to-end was not run here (needs RPC secrets/network) — worth a sanity check in deploy.

Live-probe finding — rate limiting may surface as 403, not 429

A controlled probe against the real api.cow.fi (826 requests to a live mainnet order, bursts up to 300 concurrent) returned all 200s, no 429 — the endpoint is CDN/WAF-fronted and absorbs single-IP bursts. Separately, restricted endpoints returned 403 from the edge nginx. Implication: real-world throttling may arrive as a WAF 403 rather than an app-level 429. Our code handles this correctly — a non-429/non-5xx response is a non-retryable OrderbookUnavailableError → logged ob:unavailable (so it is never mistaken for "order absent"), with no retry (a 403 is not transient). No Retry-After is sent on success; the retry path is defensive (honor it if present, else backoff).

Scope decisions (per discussion)

• Skipped the optional client-side token-bucket throttle — avoiding over-engineering; the bounded retry already absorbs transient 429s.
• Out of scope (noted): the cancel-cascade preflight (blockHandler.ts) falls back to writing cancelled for orphans the API doesn't return — so an unavailable API (429/5xx, or a timeout) can mislabel a filled order as cancelled. Pre-existing behavior (already happens on timeout); the retry here reduces its likelihood. Could be a follow-up: skip the cancelled write specifically on OrderbookUnavailableError.

Checks

• pnpm test → 108 passed · pnpm lint clean · tsc --noEmit clean

[linear-code]

COW-1013