feat: fall back to GCS mirror when GitHub source is unavailable

[pkieltyka]

Summary

Adds https://storage.googleapis.com/token-directory-index/index as a fallback source for index.json and token lists. The primary GitHub raw URL remains the logical identity (TokenList.TokenListURL and cache keys stay the GitHub URL even when bytes come from the mirror); the GCS bucket is purely a transport fallback.

How it works

• fetchFromURLs tries URLs in order and returns the first 200 OK. It falls back on 429/5xx, network errors, and stalled sources — an error is returned only if all URLs fail, via errors.Join so no failure is lost.
• Per-attempt timeout (sourceAttemptTimeout, 10s): each source gets its own budget, so a stalled primary can't consume the caller's whole deadline and still leaves room for the mirror. The single-URL fetch is extracted into fetchOnce so the body is fully read before the attempt context is canceled (structural, not a comment).
• Bounded default client: NewTokenDirectory now defaults to a client with a 30s timeout instead of http.DefaultClient (no timeout), so callers using context.Background() can't hang forever. Invariant documented: client timeout must exceed len(urls) × sourceAttemptTimeout.
• ErrSourceTimeout sentinel: when an attempt times out but the caller's context is still alive, the error is remapped so errors.Is(err, context.DeadlineExceeded) no longer masquerades as the caller's own deadline — retry logic can distinguish "source was slow" (safe to retry) from "my budget is spent".
• fallbackURLFor uses strings.CutPrefix so only a true prefix is rewritten (an embedded occurrence in a query string is left alone).

Tests

tokendirectory_test.go (new) — 15 tests, all passing under CI flags (-p 1 -race):

• fetchFromURLs: primary 200 (fallback untouched), 500→fallback, 429→fallback, network-error→fallback, stalled primary→fallback (blocks on <-r.Context().Done(), exercises the real timeout path), canceled context makes zero requests, all-fail reports both URLs, no-URLs guard
• stalled sources report ErrSourceTimeout and not context.DeadlineExceeded
• request-path assertions: the mirror is hit at the correct paths (/index.json, /mainnet/erc20.json), not just any path
• URL-rewrite prefix semantics, including the embedded-URL case
• default client has a non-zero timeout

Verified against the live mirror

• index.json and mainnet/erc20.json return 200 from the bucket
• index.json is byte-identical to GitHub (same sha256)
• Live run with the primary pointed at a dead server: FetchIndex transparently pulled the full index from GCS