From 53ba658aae60d70ba245bfb7b3145121f783b3d2 Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Fri, 6 Nov 2026 08:58:18 -0500 Subject: [PATCH] Serve every read through a caching gateway in the worker New routes under /xrpc and /git answer repo reads, blobs, identity, backlinks, record-by-URI, and git fetches. Each validates its params, resolves the repo to its PDS or knot through cached identity, and fetches with a timeout, a size cap, and redirects checked hop by hop. The cache keeps blobs, CID-pinned records, and pure-want git fetches for a year, current records and listings for 15 s with a 60 s stale window, identity for 5 minutes, and backlinks for 15 s. TTLs only, since the Cache API is per data center. x-nib-fresh: 1 skips the read and stores the result. Pushes are refused. --- packages/api/src/gateway/cache.ts | 107 ++++++++ packages/api/src/gateway/context.ts | 22 ++ packages/api/src/gateway/git.ts | 158 ++++++++++++ packages/api/src/gateway/identity.ts | 158 ++++++++++++ packages/api/src/gateway/index.ts | 31 +++ packages/api/src/gateway/proxy.ts | 129 ++++++++++ packages/api/src/gateway/xrpc.ts | 216 ++++++++++++++++ packages/api/src/identity.ts | 17 +- packages/api/src/router.ts | 18 ++ packages/api/src/worker.ts | 10 +- packages/api/tests/gateway.test.ts | 348 ++++++++++++++++++++++++++ packages/api/tests/router.test.ts | 4 + packages/api/tests/user-agent.test.ts | 45 +++- packages/api/wrangler.jsonc | 3 +- 14 files changed, 1258 insertions(+), 8 deletions(-) create mode 100644 packages/api/src/gateway/cache.ts create mode 100644 packages/api/src/gateway/context.ts create mode 100644 packages/api/src/gateway/git.ts create mode 100644 packages/api/src/gateway/identity.ts create mode 100644 packages/api/src/gateway/index.ts create mode 100644 packages/api/src/gateway/proxy.ts create mode 100644 packages/api/src/gateway/xrpc.ts create mode 100644 packages/api/tests/gateway.test.ts diff --git a/packages/api/src/gateway/cache.ts b/packages/api/src/gateway/cache.ts new file mode 100644 index 0000000..c45c3ce --- /dev/null +++ b/packages/api/src/gateway/cache.ts @@ -0,0 +1,107 @@ +/** The slice of the Workers Cache API the gateway uses. The worker passes `caches.default`; tests pass + * `memoryCache()`. The Cache API is per data center and purges do not reach the others, so nothing + * here purges: every entry ages out on its TTL. */ +export interface ResponseCache { + match(key: string): Promise; + put(key: string, response: Response): Promise; +} + +/** How long an answer is served from cache (`fresh`), then served while a background refresh runs + * (`stale`), in seconds, and the Cache-Control a client gets with it. */ +export interface CachePolicy { + fresh: number; + stale: number; + client: string; +} + +export const POLICY = { + /** A blob, or a record pinned by CID: the bytes can never change. */ + immutable: { fresh: 31_536_000, stale: 0, client: 'public, max-age=31536000, immutable' }, + /** The current version of a record or a listing. Clients revalidate so a save shows up on reload. */ + repo: { fresh: 15, stale: 60, client: 'no-cache' }, + identity: { fresh: 300, stale: 0, client: 'public, max-age=300' }, + backlinks: { fresh: 15, stale: 0, client: 'public, max-age=15' }, +} as const satisfies Record; + +export type CacheStatus = 'hit' | 'stale' | 'miss' | 'bypass'; + +export interface CacheContext { + cache: ResponseCache; + waitUntil(promise: Promise): void; + now(): number; +} + +const STORED_AT = 'x-nib-stored-at'; +/** Set by a loader on a 200 that must not be kept, and stripped before the client sees it. */ +export const NO_STORE = 'x-nib-no-store'; + +/** The copy that goes into the cache: the body, its type, when it was stored, and a max-age that + * covers the stale window so the Cache API keeps it that long. */ +function forStorage(response: Response, body: ReadableStream | null, policy: CachePolicy, now: number): Response { + const headers = new Headers(response.headers); + headers.set(STORED_AT, String(now)); + headers.set('cache-control', `public, max-age=${policy.fresh + policy.stale}`); + return new Response(body, { status: response.status, headers }); +} + +function forClient(response: Response, body: ReadableStream | null, policy: CachePolicy, status: CacheStatus): Response { + const headers = new Headers(response.headers); + headers.delete(STORED_AT); + const keep = !headers.has(NO_STORE); + headers.delete(NO_STORE); + headers.set('cache-control', keep ? policy.client : 'no-store'); + headers.set('x-nib-cache', status); + return new Response(body, { status: response.status, headers }); +} + +/** Stores a 200 in the background and hands back a response the client can read at the same time. + * Anything else (an error, a record that is not there) passes through unstored. */ +function store(ctx: CacheContext, key: string, response: Response, policy: CachePolicy, status: CacheStatus): Response { + if (response.status !== 200 || response.headers.has(NO_STORE) || !response.body) return forClient(response, response.body, policy, status); + const [client, copy] = response.body.tee(); + ctx.waitUntil(ctx.cache.put(key, forStorage(response, copy, policy, ctx.now())).catch(() => undefined)); + return forClient(response, client, policy, status); +} + +/** + * Serves `key` from the cache under `policy`, loading it with `load` on a miss. `bypass` (the request's + * `x-nib-fresh: 1`) skips the read but still stores what it loads, so the next reader sees the write. + * Stale-while-revalidate is done here because the Cache API ignores that directive. + */ +export async function cached(ctx: CacheContext, key: string, policy: CachePolicy, bypass: boolean, load: () => Promise): Promise { + if (bypass) return store(ctx, key, await load(), policy, 'bypass'); + const hit = await ctx.cache.match(key).catch(() => undefined); + const storedAt = Number(hit?.headers.get(STORED_AT)); + if (hit && Number.isFinite(storedAt)) { + const age = ctx.now() - storedAt; + if (age < policy.fresh * 1000) return forClient(hit, hit.body, policy, 'hit'); + if (age < (policy.fresh + policy.stale) * 1000) { + ctx.waitUntil( + load() + .then((fresh) => (fresh.status === 200 && !fresh.headers.has(NO_STORE) ? ctx.cache.put(key, forStorage(fresh, fresh.body, policy, ctx.now())) : fresh.body?.cancel())) + .catch(() => undefined), + ); + return forClient(hit, hit.body, policy, 'stale'); + } + } + await hit?.body?.cancel(); + return store(ctx, key, await load(), policy, 'miss'); +} + +/** An in-memory `ResponseCache` that honors each entry's `max-age` against `now`, as the Cache API does. */ +export function memoryCache(now: () => number): ResponseCache & { keys(): string[] } { + const entries = new Map(); + return { + async match(key) { + const entry = entries.get(key); + if (!entry || entry.expires <= now()) return undefined; + return new Response(entry.bytes.slice(), { status: entry.status, headers: entry.headers }); + }, + async put(key, response) { + const maxAge = Number(/max-age=(\d+)/.exec(response.headers.get('cache-control') ?? '')?.[1] ?? 0); + const bytes = new Uint8Array(await response.arrayBuffer()); + entries.set(key, { bytes, status: response.status, headers: [...response.headers], expires: now() + maxAge * 1000 }); + }, + keys: () => [...entries.keys()], + }; +} diff --git a/packages/api/src/gateway/context.ts b/packages/api/src/gateway/context.ts new file mode 100644 index 0000000..7a3205c --- /dev/null +++ b/packages/api/src/gateway/context.ts @@ -0,0 +1,22 @@ +import type { Upstream } from '../upstream.ts'; +import type { CacheContext } from './cache.ts'; + +/** Everything a gateway route reads from: the network through `Upstream`, the cache, and the two + * microcosm services it passes through to. */ +export interface Gateway extends CacheContext { + fetch: Upstream; + /** This worker's origin. Cache keys live under it. */ + origin: string; + slingshot: string; + constellation: string; +} + +/** A cache key: a URL under this worker's origin, with the params in a fixed order so equivalent + * requests share one entry. */ +export function cacheKey(g: Gateway, path: string, params: Record): string { + const url = new URL(path, g.origin); + for (const [name, value] of Object.entries(params).sort(([a], [b]) => a.localeCompare(b))) { + if (value !== undefined) url.searchParams.set(name, value); + } + return url.toString(); +} diff --git a/packages/api/src/gateway/git.ts b/packages/api/src/gateway/git.ts new file mode 100644 index 0000000..a40f6f5 --- /dev/null +++ b/packages/api/src/gateway/git.ts @@ -0,0 +1,158 @@ +import { isDid } from '@atcute/lexicons/syntax'; +import { serviceEndpoint } from '../identity.ts'; +import { cached, NO_STORE, POLICY } from './cache.ts'; +import type { Gateway } from './context.ts'; +import { didDocument } from './identity.ts'; +import { CORS, failureResponse, fetchUpstream, limitStream, readLimited, UpstreamError, xrpcError } from './proxy.ts'; + +/** A clone streams for longer than an XRPC call may take. */ +const GIT_TIMEOUT_MS = 60_000; +/** The SDK's own import cap. */ +const MAX_PACK_BYTES = 100_000_000; +/** An upload-pack request is wants and haves; a megabyte is thousands of them. */ +const MAX_REQUEST_BYTES = 1_000_000; + +const ROUTE = /^\/git\/([^/]+)\/(info\/refs|git-upload-pack|git-receive-pack)$/; + +const FORWARDED = ['content-type', 'accept', 'git-protocol']; + +/** The knot a repo DID's document names as `#tangled_knot`. The gateway proxies only there. */ +async function knotFor(g: Gateway, did: string): Promise { + try { + const doc = await didDocument(g, did); + if (!doc.found) return xrpcError('RepoNotFound', doc.message, 404); + const knot = serviceEndpoint(doc.value, did, { id: '#tangled_knot' }); + return knot ? new URL(knot).origin : xrpcError('RepoNotFound', `${did} names no public https #tangled_knot`, 404); + } catch (error) { + return failureResponse(error); + } +} + +const latin1 = new TextDecoder('latin1'); + +/** + * Whether an upload-pack request is a pure fetch of named commits: `want ` lines, an optional + * `deepen `, flushes, and `done`, with no `have` or `shallow` lines. The answer to such a request + * depends only on the request bytes and the commits, which never change, so it can be cached by body. + */ +export function isPureWant(body: Uint8Array): boolean { + let at = 0; + let wants = 0; + let done = false; + while (at < body.length) { + const length = Number.parseInt(latin1.decode(body.subarray(at, at + 4)), 16); + if (!/^[0-9a-f]{4}$/.test(latin1.decode(body.subarray(at, at + 4))) || Number.isNaN(length)) return false; + if (length === 0) { + at += 4; + continue; + } + if (length < 5 || at + length > body.length) return false; + const line = latin1.decode(body.subarray(at + 4, at + length)).replace(/\n$/, ''); + at += length; + if (/^want [0-9a-f]{40}(?: .*)?$/.test(line)) wants++; + else if (line === 'done') done = true; + else if (!/^deepen [1-9]\d*$/.test(line)) return false; + } + return wants > 0 && done; +} + +async function sha256Hex(bytes: Uint8Array): Promise { + const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)); + return Array.from(digest, (b) => b.toString(16).padStart(2, '0')).join(''); +} + +/** A knot that cannot serve a want answers 200 with an `ERR` pkt-line. That answer is passed on but + * never cached: the commit may be pushed later. Reads the first chunk to tell. */ +async function markErrors(res: Response): Promise { + if (res.status !== 200 || !res.body) return res; + const reader = res.body.getReader(); + const first = await reader.read(); + const body = new ReadableStream({ + start(controller) { + if (!first.done) controller.enqueue(first.value); + }, + async pull(controller) { + const next = await reader.read(); + if (next.done) controller.close(); + else controller.enqueue(next.value); + }, + cancel: (reason) => reader.cancel(reason), + }); + const headers = new Headers(res.headers); + if (!first.done && /^[0-9a-f]{4}ERR /.test(latin1.decode(first.value.subarray(0, 12)))) headers.set(NO_STORE, '1'); + return new Response(body, { status: res.status, headers }); +} + +async function forward(g: Gateway, url: string, init: RequestInit): Promise { + try { + const res = await fetchUpstream(g.fetch, url, { ...init, timeoutMs: GIT_TIMEOUT_MS }); + if (res.status >= 500) { + await res.body?.cancel(); + return xrpcError('UpstreamFailure', `${new URL(url).host} answered ${res.status}`, 502); + } + if (res.status !== 200) { + const bytes = await readLimited(res, 64_000); + return new Response(bytes, { status: res.status, headers: { ...CORS, 'content-type': res.headers.get('content-type') ?? 'text/plain' } }); + } + const headers = { ...CORS, 'content-type': res.headers.get('content-type') ?? 'application/octet-stream' }; + return new Response(res.body && limitStream(res.body, MAX_PACK_BYTES), { headers }); + } catch (error) { + return failureResponse(error); + } +} + +function forwardedHeaders(request: Request): Headers { + const headers = new Headers(); + for (const name of FORWARDED) { + const value = request.headers.get(name); + if (value) headers.set(name, value); + } + return headers; +} + +/** + * Smart-HTTP reads for a tangled repo, by repo DID: `/git//info/refs?service=git-upload-pack` and + * `POST /git//git-upload-pack`. Pushes are refused: a push token is single-use and bound to the + * knot, so it goes from the browser to the knot directly. + */ +export async function handleGit(g: Gateway, request: Request, bypass: boolean): Promise { + const url = new URL(request.url); + const match = ROUTE.exec(url.pathname); + if (!match) return undefined; + const [, did, endpoint] = match as unknown as [string, string, string]; + if (endpoint === 'git-receive-pack' || url.searchParams.get('service') === 'git-receive-pack') { + return xrpcError('MethodNotAllowed', 'push straight to the knot; the gateway only reads', 403); + } + if (!isDid(did)) return xrpcError('InvalidRequest', `${did} is not a DID`, 400); + + if (endpoint === 'info/refs') { + if (request.method !== 'GET') return xrpcError('MethodNotAllowed', 'info/refs is GET', 405); + if (url.searchParams.get('service') !== 'git-upload-pack') return xrpcError('InvalidRequest', 'service must be git-upload-pack', 400); + const knot = await knotFor(g, did); + if (knot instanceof Response) return knot; + const res = await forward(g, `${knot}/${did}/info/refs?service=git-upload-pack`, { headers: forwardedHeaders(request) }); + res.headers.set('cache-control', 'no-store'); + return res; + } + + if (request.method !== 'POST') return xrpcError('MethodNotAllowed', 'git-upload-pack is POST', 405); + let body: Uint8Array; + try { + body = await readLimited(new Response(request.body, { headers: request.headers }), MAX_REQUEST_BYTES); + } catch (error) { + if (error instanceof UpstreamError && error.reason === 'too-large') return xrpcError('PayloadTooLarge', error.message, 413); + throw error; + } + const knot = await knotFor(g, did); + if (knot instanceof Response) return knot; + const load = () => forward(g, `${knot}/${did}/git-upload-pack`, { method: 'POST', headers: forwardedHeaders(request), body }); + + const cacheable = isPureWant(body) && !request.headers.get('git-protocol') && !request.headers.get('content-encoding'); + if (!cacheable) { + const res = await load(); + res.headers.set('cache-control', 'no-store'); + return res; + } + const key = new URL(`/git/${did}/git-upload-pack?body=${await sha256Hex(body)}`, g.origin).toString(); + return cached(g, key, POLICY.immutable, bypass, async () => markErrors(await load())); +} diff --git a/packages/api/src/gateway/identity.ts b/packages/api/src/gateway/identity.ts new file mode 100644 index 0000000..6a4b20b --- /dev/null +++ b/packages/api/src/gateway/identity.ts @@ -0,0 +1,158 @@ +import { isDid, isHandle } from '@atcute/lexicons/syntax'; +import { didDocumentUrl, serviceEndpoint } from '../identity.ts'; +import { isPublicHttpsUrl } from '../net.ts'; +import { cached, POLICY } from './cache.ts'; +import { cacheKey, type Gateway } from './context.ts'; +import { CORS, failureResponse, fetchUpstream, MAX_JSON_BYTES, readLimited, UpstreamError, xrpcError } from './proxy.ts'; + +/** `blue.microcosm.identity.resolveMiniDoc`'s answer. `handle` is `handle.invalid` when it does not + * resolve back to the DID. */ +export interface MiniDoc { + did: string; + handle: string; + pds: string; +} + +type Found = { found: true; value: T } | { found: false; message: string }; + +const json = (body: unknown) => Response.json(body, { headers: CORS }); + +async function readJson(res: Response): Promise { + return JSON.parse(new TextDecoder().decode(await readLimited(res, MAX_JSON_BYTES))); +} + +/** `com.atproto.identity.resolveDid`, cached for 5 minutes. Straight from PLC or the did:web host. */ +export function resolveDid(g: Gateway, did: string, bypass = false): Promise { + return cached(g, cacheKey(g, '/xrpc/com.atproto.identity.resolveDid', { did }), POLICY.identity, bypass, async () => { + const url = didDocumentUrl(did); + if (!url) return xrpcError('DidNotFound', `${did} is not a did:plc or a public did:web`, 400); + try { + const res = await fetchUpstream(g.fetch, url, { headers: { accept: 'application/json' } }); + if (res.status === 404 || res.status === 410) { + await res.body?.cancel(); + return xrpcError('DidNotFound', `no DID document for ${did}`, 400); + } + if (!res.ok) { + await res.body?.cancel(); + throw new UpstreamError('unreachable', `${new URL(url).host} answered ${res.status} for ${did}`); + } + const doc = await readJson(res); + if ((doc as { id?: unknown } | null)?.id !== did) return xrpcError('DidNotFound', `the document at ${url} is not ${did}'s`, 400); + return json({ didDoc: doc }); + } catch (error) { + return error instanceof SyntaxError ? xrpcError('UpstreamFailure', `${did}'s document is not JSON`, 502) : failureResponse(error); + } + }); +} + +/** A DID document through `resolveDid`'s cache. Throws `UpstreamError` when that is an outage. */ +export async function didDocument(g: Gateway, did: string): Promise> { + const res = await resolveDid(g, did); + if (res.status >= 500) { + await res.body?.cancel(); + throw new UpstreamError('unreachable', `could not read ${did}'s DID document`); + } + const body = (await res.json()) as { didDoc?: unknown; message?: string }; + return res.ok ? { found: true, value: body.didDoc } : { found: false, message: body.message ?? `no DID document for ${did}` }; +} + +/** `_atproto.` over DNS-over-HTTPS, then `https:///.well-known/atproto-did`. */ +async function resolveHandle(g: Gateway, handle: string): Promise { + try { + const res = await fetchUpstream(g.fetch, `https://cloudflare-dns.com/dns-query?name=_atproto.${handle}&type=TXT`, { + headers: { accept: 'application/dns-json' }, + }); + if (res.ok) { + const answers = ((await readJson(res)) as { Answer?: { data?: unknown }[] }).Answer ?? []; + const dids = answers.flatMap((a) => { + const match = typeof a.data === 'string' ? /^"?did=([^"\s]+)"?$/.exec(a.data) : null; + return match && isDid(match[1]) ? [match[1]] : []; + }); + if (dids.length === 1) return dids[0]; + } else { + await res.body?.cancel(); + } + } catch { + // DNS unanswered: try the well-known file. + } + const wellKnown = `https://${handle}/.well-known/atproto-did`; + if (!isPublicHttpsUrl(wellKnown)) return undefined; + try { + const res = await fetchUpstream(g.fetch, wellKnown); + if (!res.ok) { + await res.body?.cancel(); + return undefined; + } + const did = new TextDecoder().decode(await readLimited(res, 2048)).trim(); + return isDid(did) ? did : undefined; + } catch { + return undefined; + } +} + +function handleClaim(doc: unknown): string | undefined { + const aka = (doc as { alsoKnownAs?: unknown } | null)?.alsoKnownAs; + const first = Array.isArray(aka) ? aka.find((v): v is string => typeof v === 'string' && v.startsWith('at://')) : undefined; + const handle = first?.slice('at://'.length).toLowerCase(); + return handle && isHandle(handle) ? handle : undefined; +} + +async function viaSlingshot(g: Gateway, identifier: string): Promise { + try { + const url = new URL('/xrpc/blue.microcosm.identity.resolveMiniDoc', g.slingshot); + url.searchParams.set('identifier', identifier); + const res = await fetchUpstream(g.fetch, url.toString(), { headers: { accept: 'application/json' } }); + if (!res.ok) { + await res.body?.cancel(); + return undefined; + } + const body = (await readJson(res)) as Partial; + if (typeof body.did !== 'string' || typeof body.handle !== 'string' || typeof body.pds !== 'string') return undefined; + if (isDid(identifier) ? body.did !== identifier : body.handle.toLowerCase() !== identifier) return undefined; + if (!isPublicHttpsUrl(body.pds)) return undefined; + return { did: body.did, handle: body.handle, pds: body.pds }; + } catch { + return undefined; + } +} + +/** The same answer built from PLC or did:web and DNS, checking the handle both ways. */ +async function viaDocument(g: Gateway, identifier: string): Promise> { + const did = isDid(identifier) ? identifier : await resolveHandle(g, identifier); + if (!did) return { found: false, message: `${identifier} does not resolve to a DID` }; + const doc = await didDocument(g, did); + if (!doc.found) return doc; + const pds = serviceEndpoint(doc.value, did, { id: '#atproto_pds' }); + if (!pds) return { found: false, message: `${did} names no public https PDS` }; + const claimed = handleClaim(doc.value); + const verified = isDid(identifier) + ? claimed !== undefined && (await resolveHandle(g, claimed)) === did + : claimed === identifier; + return { found: true, value: { did, handle: verified ? claimed! : 'handle.invalid', pds } }; +} + +/** `blue.microcosm.identity.resolveMiniDoc`, cached for 5 minutes: Slingshot first, then PLC or + * did:web and DNS directly. `identifier` is already a parsed DID or lowercase handle. */ +export function resolveMiniDoc(g: Gateway, identifier: string, bypass = false): Promise { + return cached(g, cacheKey(g, '/xrpc/blue.microcosm.identity.resolveMiniDoc', { identifier }), POLICY.identity, bypass, async () => { + const slingshot = await viaSlingshot(g, identifier); + if (slingshot) return json(slingshot); + try { + const direct = await viaDocument(g, identifier); + return direct.found ? json(direct.value) : xrpcError('NotFound', direct.message, 400); + } catch (error) { + return failureResponse(error); + } + }); +} + +/** Who `identifier` is and where their repo lives, through `resolveMiniDoc`'s cache. */ +export async function miniDoc(g: Gateway, identifier: string): Promise> { + const res = await resolveMiniDoc(g, identifier); + if (res.status >= 500) { + await res.body?.cancel(); + throw new UpstreamError('unreachable', `could not resolve ${identifier}`); + } + const body = (await res.json()) as MiniDoc & { message?: string }; + return res.ok ? { found: true, value: body } : { found: false, message: body.message ?? `could not resolve ${identifier}` }; +} diff --git a/packages/api/src/gateway/index.ts b/packages/api/src/gateway/index.ts new file mode 100644 index 0000000..16004db --- /dev/null +++ b/packages/api/src/gateway/index.ts @@ -0,0 +1,31 @@ +import type { Gateway } from './context.ts'; +import { handleGit } from './git.ts'; +import { handleXrpc } from './xrpc.ts'; + +export type { Gateway } from './context.ts'; +export { memoryCache, type ResponseCache } from './cache.ts'; + +/** Request headers a cross-origin caller may send: XRPC reads, git's, and the cache bypass. */ +const PREFLIGHT = { + 'access-control-allow-origin': '*', + 'access-control-allow-methods': 'GET, POST, OPTIONS', + 'access-control-allow-headers': 'content-type, git-protocol, x-nib-fresh', + 'access-control-max-age': '86400', +}; + +export function preflight(): Response { + return new Response(null, { status: 204, headers: PREFLIGHT }); +} + +/** + * The read gateway (D22): repo reads, identity, backlinks, and git fetches, each answered from a + * per-data-center cache or from upstream. Undefined when the path is not one of its routes. + * `x-nib-fresh: 1` skips the cache read, so a writer sees their own write. + */ +export async function handleGateway(request: Request, g: Gateway): Promise { + const url = new URL(request.url); + const bypass = request.headers.get('x-nib-fresh') === '1'; + if (url.pathname.startsWith('/git/')) return handleGit(g, request, bypass); + if (request.method !== 'GET' || !url.pathname.startsWith('/xrpc/')) return undefined; + return handleXrpc(g, url.pathname.slice('/xrpc/'.length), url.searchParams, bypass); +} diff --git a/packages/api/src/gateway/proxy.ts b/packages/api/src/gateway/proxy.ts new file mode 100644 index 0000000..775ff73 --- /dev/null +++ b/packages/api/src/gateway/proxy.ts @@ -0,0 +1,129 @@ +import { FETCH_TIMEOUT_MS, isPublicHttpsUrl } from '../net.ts'; +import type { Upstream } from '../upstream.ts'; + +/** The most a JSON answer or a blob may be. 5 MB is also the lexicon's per-blob cap. */ +export const MAX_JSON_BYTES = 5_000_000; +export const MAX_BLOB_BYTES = 5_000_000; +const MAX_REDIRECTS = 3; + +export type UpstreamFailure = 'timeout' | 'too-large' | 'unreachable' | 'unsafe'; + +/** Why a call to a PDS, PLC, a knot, or microcosm failed. The gateway answers each with a 5xx, so the + * SDK falls back to reading direct. */ +export class UpstreamError extends Error { + readonly reason: UpstreamFailure; + constructor(reason: UpstreamFailure, message: string) { + super(message); + this.reason = reason; + } +} + +export const CORS = { + 'access-control-allow-origin': '*', + 'access-control-expose-headers': 'x-nib-cache', +}; + +export function xrpcError(error: string, message: string, status: number): Response { + return Response.json({ error, message }, { status, headers: { ...CORS, 'cache-control': 'no-store' } }); +} + +export function failureResponse(error: unknown): Response { + if (!(error instanceof UpstreamError)) throw error; + if (error.reason === 'timeout') return xrpcError('UpstreamTimeout', error.message, 504); + return xrpcError('UpstreamFailure', error.message, 502); +} + +/** + * One request to an untrusted host. Redirects are followed by hand, at most 3, and each hop must be a + * public `https:` URL like the first (`isPublicHttpsUrl`), so a PDS cannot bounce the worker inward. + * `timeoutMs` covers the headers and the body. + */ +export async function fetchUpstream(fetchFn: Upstream, url: string, init: RequestInit & { timeoutMs?: number } = {}): Promise { + const { timeoutMs = FETCH_TIMEOUT_MS, ...rest } = init; + const signal = AbortSignal.timeout(timeoutMs); + let target = url; + for (let hop = 0; hop <= MAX_REDIRECTS; hop++) { + if (!isPublicHttpsUrl(target)) throw new UpstreamError('unsafe', `refusing to fetch ${target}`); + let res: Response; + try { + res = await fetchFn(target, { ...rest, signal, redirect: 'manual' }); + } catch (error) { + if (signal.aborted) throw new UpstreamError('timeout', `${new URL(target).host} did not answer in ${timeoutMs} ms`); + throw new UpstreamError('unreachable', `${new URL(target).host}: ${(error as Error).message}`); + } + const location = res.headers.get('location'); + if (res.status < 300 || res.status >= 400 || !location) return res; + await res.body?.cancel(); + target = new URL(location, target).toString(); + } + throw new UpstreamError('unsafe', `${url} redirected more than ${MAX_REDIRECTS} times`); +} + +/** The whole body, failing once it passes `limit` bytes, whatever Content-Length claimed. */ +export async function readLimited(res: Response, limit: number): Promise { + if (Number(res.headers.get('content-length') ?? 0) > limit) { + await res.body?.cancel(); + throw new UpstreamError('too-large', `the answer is over ${limit} bytes`); + } + if (!res.body) return new Uint8Array(); + const reader = res.body.getReader(); + const chunks: Uint8Array[] = []; + let size = 0; + try { + for (let next = await reader.read(); !next.done; next = await reader.read()) { + size += next.value.byteLength; + if (size > limit) { + await reader.cancel(); + throw new UpstreamError('too-large', `the answer is over ${limit} bytes`); + } + chunks.push(next.value); + } + } catch (error) { + if (error instanceof UpstreamError) throw error; + throw new UpstreamError('unreachable', `the answer broke off: ${(error as Error).message}`); + } + const bytes = new Uint8Array(size); + let at = 0; + for (const chunk of chunks) { + bytes.set(chunk, at); + at += chunk.byteLength; + } + return bytes; +} + +/** `body` passed through, erroring once more than `limit` bytes have gone by. */ +export function limitStream(body: ReadableStream, limit: number): ReadableStream { + let size = 0; + return body.pipeThrough( + new TransformStream({ + transform(chunk, controller) { + size += chunk.byteLength; + if (size > limit) controller.error(new UpstreamError('too-large', `the answer is over ${limit} bytes`)); + else controller.enqueue(chunk); + }, + }), + ); +} + +/** + * An XRPC JSON query to `url`, answered as the upstream answered it: a 2xx or 4xx body that is JSON + * and at most 5 MB. A 5xx, a non-JSON body, or a failure becomes a 502 or 504. + */ +export async function proxyJson(fetchFn: Upstream, url: string): Promise { + try { + const res = await fetchUpstream(fetchFn, url, { headers: { accept: 'application/json' } }); + if (res.status >= 500) { + await res.body?.cancel(); + return xrpcError('UpstreamFailure', `${new URL(url).host} answered ${res.status}`, 502); + } + const bytes = await readLimited(res, MAX_JSON_BYTES); + try { + JSON.parse(new TextDecoder().decode(bytes)); + } catch { + return xrpcError('UpstreamFailure', `${new URL(url).host} answered with something other than JSON`, 502); + } + return new Response(bytes, { status: res.status, headers: { ...CORS, 'content-type': 'application/json' } }); + } catch (error) { + return failureResponse(error); + } +} diff --git a/packages/api/src/gateway/xrpc.ts b/packages/api/src/gateway/xrpc.ts new file mode 100644 index 0000000..560e00b --- /dev/null +++ b/packages/api/src/gateway/xrpc.ts @@ -0,0 +1,216 @@ +import { isCid, isDid, isNsid, isRecordKey, isResourceUri } from '@atcute/lexicons/syntax'; +import { parseActorIdentifier } from '@nibling/sdk/identifier'; +import { cached, POLICY, type CachePolicy } from './cache.ts'; +import { cacheKey, type Gateway } from './context.ts'; +import { miniDoc, resolveDid, resolveMiniDoc } from './identity.ts'; +import { + CORS, + failureResponse, + fetchUpstream, + MAX_BLOB_BYTES, + MAX_JSON_BYTES, + proxyJson, + readLimited, + xrpcError, +} from './proxy.ts'; + +type Params = Record; + +/** What a valid request turns into: where it is cached, for how long, and how to load it. */ +interface Plan { + key: string; + policy: CachePolicy; + load(): Promise; +} + +type Parsed = { ok: true; params: Params } | { ok: false; message: string }; + +/** One query param's rule: `required` or not, and a check on its value. */ +type Rule = { required: boolean; check(value: string): boolean; what: string }; + +const required = (check: Rule['check'], what: string): Rule => ({ required: true, check, what }); +const optional = (check: Rule['check'], what: string): Rule => ({ required: false, check, what }); + +const actor = (v: string) => parseActorIdentifier(v) !== undefined; +const limit = (v: string) => /^\d{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= 100; +const cursor = (v: string) => v.length > 0 && v.length <= 1024; +const bool = (v: string) => v === 'true' || v === 'false'; +const subject = (v: string) => v.length > 0 && v.length <= 2048; +const source = (v: string) => /^[a-zA-Z0-9.-]+:[a-zA-Z0-9_.[\]-]+$/.test(v) && v.length <= 512; + +/** Parses the params a route takes. Anything else in the query string is dropped, so it can neither + * reach the upstream nor split the cache. */ +function parse(query: URLSearchParams, rules: Record): Parsed { + const params: Params = {}; + for (const [name, rule] of Object.entries(rules)) { + const values = query.getAll(name); + if (values.length > 1) return { ok: false, message: `${name} may be given once` }; + const value = values[0]; + if (value === undefined || value === '') { + if (rule.required) return { ok: false, message: `${name} is required` }; + continue; + } + if (!rule.check(value)) return { ok: false, message: `${name} must be ${rule.what}` }; + params[name] = value; + } + return { ok: true, params }; +} + +function upstreamUrl(base: string, nsid: string, params: Params): string { + const url = new URL(`/xrpc/${nsid}`, base); + for (const [name, value] of Object.entries(params)) if (value !== undefined) url.searchParams.set(name, value); + return url.toString(); +} + +/** Resolves `repo` to its DID and PDS, so a handle and its DID share one cache entry. */ +async function withPds(g: Gateway, identifier: string, plan: (did: string, pds: string) => Plan): Promise { + try { + const found = await miniDoc(g, parseActorIdentifier(identifier)!); + if (!found.found) return xrpcError('RepoNotFound', found.message, 400); + return plan(found.value.did, found.value.pds); + } catch (error) { + return failureResponse(error); + } +} + +/** A record pinned by CID never changes, but a PDS asked for a CID it no longer holds answers with the + * current version on some implementations. Only an answer that carries the asked-for CID is kept. */ +async function pinnedRecord(g: Gateway, url: string, cid: string): Promise { + const res = await proxyJson(g.fetch, url); + if (res.status !== 200) return res; + const body = (await res.clone().json()) as { cid?: unknown }; + return body.cid === cid ? res : xrpcError('RecordNotFound', `no version ${cid} of that record`, 400); +} + +async function blob(g: Gateway, url: string): Promise { + try { + const res = await fetchUpstream(g.fetch, url); + if (res.status >= 500) { + await res.body?.cancel(); + return xrpcError('UpstreamFailure', `${new URL(url).host} answered ${res.status}`, 502); + } + if (res.status !== 200) return proxyJsonBody(res); + const bytes = await readLimited(res, MAX_BLOB_BYTES); + return new Response(bytes, { + headers: { + ...CORS, + 'content-type': res.headers.get('content-type') ?? 'application/octet-stream', + // A blob is whatever its uploader said it is. Served from our origin it must never run. + 'content-security-policy': "default-src 'none'; sandbox", + 'x-content-type-options': 'nosniff', + }, + }); + } catch (error) { + return failureResponse(error); + } +} + +async function proxyJsonBody(res: Response): Promise { + const bytes = await readLimited(res, MAX_JSON_BYTES); + return new Response(bytes, { status: res.status, headers: { ...CORS, 'content-type': 'application/json' } }); +} + +type Route = { rules: Record; plan(g: Gateway, params: Params): Plan | Response | Promise }; + +/** Every read the gateway answers, by NSID. Each validates its params, then names a cache policy. */ +const ROUTES: Record = { + 'com.atproto.repo.getRecord': { + rules: { + repo: required(actor, 'a handle or DID'), + collection: required(isNsid, 'an NSID'), + rkey: required(isRecordKey, 'a record key'), + cid: optional(isCid, 'a CID'), + }, + plan: (g, p) => + withPds(g, p.repo!, (did, pds) => { + const params = { ...p, repo: did }; + const url = upstreamUrl(pds, 'com.atproto.repo.getRecord', params); + return p.cid + ? { key: cacheKey(g, '/xrpc/com.atproto.repo.getRecord', params), policy: POLICY.immutable, load: () => pinnedRecord(g, url, p.cid!) } + : { key: cacheKey(g, '/xrpc/com.atproto.repo.getRecord', params), policy: POLICY.repo, load: () => proxyJson(g.fetch, url) }; + }), + }, + 'com.atproto.repo.listRecords': { + rules: { + repo: required(actor, 'a handle or DID'), + collection: required(isNsid, 'an NSID'), + limit: optional(limit, 'an integer from 1 to 100'), + cursor: optional(cursor, 'at most 1024 characters'), + reverse: optional(bool, 'true or false'), + }, + plan: (g, p) => + withPds(g, p.repo!, (did, pds) => { + const params = { ...p, repo: did }; + return { key: cacheKey(g, '/xrpc/com.atproto.repo.listRecords', params), policy: POLICY.repo, load: () => proxyJson(g.fetch, upstreamUrl(pds, 'com.atproto.repo.listRecords', params)) }; + }), + }, + 'com.atproto.repo.describeRepo': { + rules: { repo: required(actor, 'a handle or DID') }, + plan: (g, p) => + withPds(g, p.repo!, (did, pds) => { + const params = { repo: did }; + return { key: cacheKey(g, '/xrpc/com.atproto.repo.describeRepo', params), policy: POLICY.repo, load: () => proxyJson(g.fetch, upstreamUrl(pds, 'com.atproto.repo.describeRepo', params)) }; + }), + }, + 'com.atproto.sync.getBlob': { + rules: { did: required(isDid, 'a DID'), cid: required(isCid, 'a CID') }, + plan: (g, p) => + withPds(g, p.did!, (did, pds) => ({ + key: cacheKey(g, '/xrpc/com.atproto.sync.getBlob', p), + policy: POLICY.immutable, + load: () => blob(g, upstreamUrl(pds, 'com.atproto.sync.getBlob', { did, cid: p.cid })), + })), + }, + 'com.atproto.identity.resolveDid': { + rules: { did: required(isDid, 'a DID') }, + // Cached inside, where the gateway's own lookups share the entry. + plan: (g, p) => resolveDid(g, p.did!), + }, + 'blue.microcosm.identity.resolveMiniDoc': { + rules: { identifier: required(actor, 'a handle or DID') }, + plan: (g, p) => resolveMiniDoc(g, parseActorIdentifier(p.identifier!)!), + }, + 'blue.microcosm.links.getBacklinks': { + rules: { + subject: required(subject, 'at most 2048 characters'), + source: required(source, 'a : source'), + limit: optional(limit, 'an integer from 1 to 100'), + cursor: optional(cursor, 'at most 1024 characters'), + }, + plan: (g, p) => ({ + key: cacheKey(g, '/xrpc/blue.microcosm.links.getBacklinks', p), + policy: POLICY.backlinks, + load: () => proxyJson(g.fetch, upstreamUrl(g.constellation, 'blue.microcosm.links.getBacklinks', p)), + }), + }, + 'blue.microcosm.links.getBacklinksCount': { + rules: { subject: required(subject, 'at most 2048 characters'), source: required(source, 'a : source') }, + plan: (g, p) => ({ + key: cacheKey(g, '/xrpc/blue.microcosm.links.getBacklinksCount', p), + policy: POLICY.backlinks, + load: () => proxyJson(g.fetch, upstreamUrl(g.constellation, 'blue.microcosm.links.getBacklinksCount', p)), + }), + }, + 'blue.microcosm.repo.getRecordByUri': { + rules: { at_uri: required(isResourceUri, 'an AT-URI'), cid: optional(isCid, 'a CID') }, + plan: (g, p) => ({ + key: cacheKey(g, '/xrpc/blue.microcosm.repo.getRecordByUri', p), + policy: p.cid ? POLICY.immutable : POLICY.repo, + load: () => { + const url = upstreamUrl(g.slingshot, 'blue.microcosm.repo.getRecordByUri', p); + return p.cid ? pinnedRecord(g, url, p.cid) : proxyJson(g.fetch, url); + }, + }), + }, +}; + +/** Answers `/xrpc/` when the gateway serves that NSID, else undefined. */ +export async function handleXrpc(g: Gateway, nsid: string, query: URLSearchParams, bypass: boolean): Promise { + const route = ROUTES[nsid]; + if (!route) return undefined; + const parsed = parse(query, route.rules); + if (!parsed.ok) return xrpcError('InvalidRequest', parsed.message, 400); + const plan = await route.plan(g, parsed.params); + if (plan instanceof Response) return plan; + return cached(g, plan.key, plan.policy, bypass, plan.load); +} diff --git a/packages/api/src/identity.ts b/packages/api/src/identity.ts index c088c63..3352d7d 100644 --- a/packages/api/src/identity.ts +++ b/packages/api/src/identity.ts @@ -22,9 +22,18 @@ export async function resolveDidPds(did: string, fetchFn: Upstream, timeoutMs = if (!docUrl) throw new Error(`cannot resolve ${did}`); const res = await fetchFn(docUrl, { signal: AbortSignal.timeout(timeoutMs) }); if (!res.ok) throw new Error(`DID document for ${did}: HTTP ${res.status}`); - const doc = (await res.json()) as { service?: unknown }; - const services = Array.isArray(doc.service) ? (doc.service as { type?: unknown; serviceEndpoint?: unknown }[]) : []; - const pds = services.find((s) => s?.type === 'AtprotoPersonalDataServer')?.serviceEndpoint; - if (typeof pds !== 'string' || !isPublicHttpsUrl(pds)) throw new Error(`no usable PDS in DID document for ${did}`); + const pds = serviceEndpoint(await res.json(), did, { type: 'AtprotoPersonalDataServer' }); + if (!pds) throw new Error(`no usable PDS in DID document for ${did}`); return pds; } + +/** The endpoint of the first service in `doc` with this `id` (`#atproto_pds`, `#tangled_knot`) or + * `type`, when it is a public `https:` URL. A DID document is untrusted input. */ +export function serviceEndpoint(doc: unknown, did: string, match: { id?: `#${string}`; type?: string }): string | undefined { + const raw = (doc as { service?: unknown } | null)?.service; + const services = Array.isArray(raw) ? (raw as { id?: unknown; type?: unknown; serviceEndpoint?: unknown }[]) : []; + const found = services.find((s) => + match.id ? s?.id === match.id || s?.id === `${did}${match.id}` : s?.type === match.type, + )?.serviceEndpoint; + return typeof found === 'string' && isPublicHttpsUrl(found) ? found : undefined; +} diff --git a/packages/api/src/router.ts b/packages/api/src/router.ts index 73a477c..a4d6e79 100644 --- a/packages/api/src/router.ts +++ b/packages/api/src/router.ts @@ -4,6 +4,7 @@ import { parseActorIdentifier } from '@nibling/sdk/identifier'; import { clientMetadata } from '@nibling/sdk/metadata'; import { FETCH_TIMEOUT_MS, isPublicHttpsUrl } from './net.ts'; import type { Upstream } from './upstream.ts'; +import { handleGateway, preflight, type ResponseCache } from './gateway/index.ts'; /** What the router needs from the Index DO, kept to just the RPC surface it calls. Isolating * this (rather than importing `cloudflare:workers` types here) is what lets this file run under @@ -18,8 +19,14 @@ export interface RouterEnv { INDEX: { getByName(name: string): IndexStub }; APP_ORIGIN: string; SLINGSHOT_URL: string; + CONSTELLATION_URL: string; /** Every outbound request goes through this. */ fetch: Upstream; + /** `caches.default` in the worker. */ + cache: ResponseCache; + /** Keeps a background cache write or refresh alive after the response is sent. */ + waitUntil(promise: Promise): void; + now?: () => number; } const XRPC_HEADERS = { @@ -108,6 +115,17 @@ function matchProjectPath(pathname: string): { actor: string; rkey: string } | u export async function handleRequest(request: Request, env: RouterEnv): Promise { const url = new URL(request.url); + if (request.method === 'OPTIONS') return preflight(); + const gateway = await handleGateway(request, { + fetch: env.fetch, + cache: env.cache, + waitUntil: env.waitUntil, + now: env.now ?? Date.now, + origin: url.origin, + slingshot: env.SLINGSHOT_URL, + constellation: env.CONSTELLATION_URL, + }); + if (gateway) return gateway; const stub = env.INDEX.getByName('global'); if (url.pathname === '/xrpc/run.nibling.feed.getRecent') { diff --git a/packages/api/src/worker.ts b/packages/api/src/worker.ts index 1e1369d..66d911a 100644 --- a/packages/api/src/worker.ts +++ b/packages/api/src/worker.ts @@ -11,12 +11,18 @@ export interface Env { JETSTREAM_URL: string; RELAY_URL: string; SLINGSHOT_URL: string; + CONSTELLATION_URL: string; CONTACT_URL?: string; } export default { - fetch(request: Request, env: Env): Promise { - return handleRequest(request, { ...env, fetch: outbound(env) }); + fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { + return handleRequest(request, { + ...env, + fetch: outbound(env), + cache: { match: (key) => caches.default.match(key), put: (key, response) => caches.default.put(key, response) }, + waitUntil: (promise) => ctx.waitUntil(promise), + }); }, }; diff --git a/packages/api/tests/gateway.test.ts b/packages/api/tests/gateway.test.ts new file mode 100644 index 0000000..86a9fb0 --- /dev/null +++ b/packages/api/tests/gateway.test.ts @@ -0,0 +1,348 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { isPureWant } from '../src/gateway/git.ts'; +import { memoryCache } from '../src/gateway/index.ts'; +import { handleRequest, type RouterEnv } from '../src/router.ts'; +import { upstream } from '../src/upstream.ts'; + +const ALICE = 'did:plc:aaaaaaaaaaaaaaaaaaaaaaaa'; +const REPO = 'did:plc:rrrrrrrrrrrrrrrrrrrrrrrr'; +const CID1 = 'bafyreie5737gdxlw5i64vzichcalba3z2v5n6icifvx5xytvske7mr3hpm'; +const CID2 = 'bafyreib2rxk3rybk3aobmv5cjuql3bm2twh4jo5uxgf5x5hhvugd5rj2sq'; +const BLOB = 'bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku'; +const SHA = 'a'.repeat(40); + +/** The network the gateway sees: a PDS, PLC, Slingshot, Constellation, DNS, and a knot, each a + * function tests can swap, with every request logged as `host path?query`. */ +function world() { + const calls: string[] = []; + let record: { cid: string; value: unknown } = { cid: CID1, value: { text: 'first' } }; + const services: Record Response | Promise> = { + 'slingshot.test': (url) => { + if (url.pathname === '/xrpc/blue.microcosm.identity.resolveMiniDoc') { + const id = url.searchParams.get('identifier'); + return id === ALICE || id === 'alice.test' + ? Response.json({ did: ALICE, handle: 'alice.test', pds: 'https://pds.test' }) + : Response.json({ error: 'NotFound' }, { status: 400 }); + } + if (url.pathname === '/xrpc/blue.microcosm.repo.getRecordByUri') { + return Response.json({ uri: url.searchParams.get('at_uri'), cid: record.cid, value: record.value }); + } + return new Response('{}', { status: 404 }); + }, + 'pds.test': (url) => { + switch (url.pathname) { + case '/xrpc/com.atproto.repo.getRecord': { + const uri = `at://${url.searchParams.get('repo')}/${url.searchParams.get('collection')}/${url.searchParams.get('rkey')}`; + // Like some PDSes, this one ignores `cid` and answers with the current version. + return Response.json({ uri, cid: record.cid, value: record.value }); + } + case '/xrpc/com.atproto.repo.listRecords': + return Response.json({ records: [{ uri: `at://${ALICE}/run.nibling.project/3la1`, cid: record.cid, value: record.value }] }); + case '/xrpc/com.atproto.repo.describeRepo': + return Response.json({ did: ALICE, handle: 'alice.test', collections: ['run.nibling.project'] }); + case '/xrpc/com.atproto.sync.getBlob': + return new Response(new TextEncoder().encode(''), { headers: { 'content-type': 'text/html' } }); + default: + return new Response('{}', { status: 404 }); + } + }, + 'plc.directory': (url) => { + const did = url.pathname.slice(1); + if (did === ALICE) { + return Response.json({ + id: ALICE, + alsoKnownAs: ['at://alice.test'], + service: [{ id: '#atproto_pds', type: 'AtprotoPersonalDataServer', serviceEndpoint: 'https://pds.test' }], + }); + } + if (did === REPO) { + return Response.json({ + id: REPO, + service: [{ id: '#tangled_knot', type: 'TangledKnot', serviceEndpoint: 'https://knot.test' }], + }); + } + return new Response('not found', { status: 404 }); + }, + 'cloudflare-dns.com': (url) => + url.searchParams.get('name') === '_atproto.alice.test' + ? Response.json({ Answer: [{ data: `"did=${ALICE}"` }] }) + : Response.json({ Answer: [] }), + 'constellation.test': (url) => + url.pathname.endsWith('getBacklinksCount') ? Response.json({ total: 3 }) : Response.json({ total: 1, records: [{ did: ALICE, collection: 'run.nibling.feed.like', rkey: '3l' }] }), + 'knot.test': async (url, init) => { + if (url.pathname === `/${REPO}/info/refs`) { + return new Response('001e# service=git-upload-pack\n0000', { headers: { 'content-type': 'application/x-git-upload-pack-advertisement' } }); + } + if (url.pathname === `/${REPO}/git-upload-pack`) { + const body = new TextDecoder().decode(init.body as Uint8Array); + if (body.includes('b'.repeat(40))) return new Response('0019ERR not our ref bbbb\n', { headers: { 'content-type': 'application/x-git-upload-pack-result' } }); + return new Response('0008NAK\nPACK', { headers: { 'content-type': 'application/x-git-upload-pack-result' } }); + } + return new Response('nope', { status: 404 }); + }, + }; + const fetch = upstream(async (input: string | URL | Request, init?: RequestInit) => { + const url = new URL(input instanceof Request ? input.url : input.toString()); + calls.push(`${url.host} ${url.pathname}${decodeURIComponent(url.search)}`); + const service = services[url.host]; + if (!service) throw new TypeError(`fetch failed: ${url.host}`); + return service(url, init ?? {}); + }); + return { + calls, + services, + setRecord: (next: typeof record) => (record = next), + fetch, + }; +} + +function gateway() { + const net = world(); + let clock = Date.parse('2026-11-06T00:00:00.000Z'); + const pending: Promise[] = []; + const env: RouterEnv = { + INDEX: { getByName: () => ({ getRecent: async () => ({ projects: [] }), getTrending: async () => ({ projects: [] }), getKnown: async () => [] }) }, + APP_ORIGIN: 'https://nibling.run', + SLINGSHOT_URL: 'https://slingshot.test', + CONSTELLATION_URL: 'https://constellation.test', + fetch: net.fetch, + cache: memoryCache(() => clock), + waitUntil: (promise) => void pending.push(promise), + now: () => clock, + }; + return { + net, + tick: (ms: number) => (clock += ms), + /** Runs a request, then waits for the cache writes and refreshes it started. */ + async get(path: string, init?: RequestInit) { + const res = await handleRequest(new Request(`https://api.nibling.run${path}`, init), env); + const body = new Uint8Array(await res.arrayBuffer()); + await Promise.all(pending.splice(0)); + return { status: res.status, headers: res.headers, text: new TextDecoder().decode(body), json: () => JSON.parse(new TextDecoder().decode(body)) }; + }, + }; +} + +const GET_RECORD = `/xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=run.nibling.project&rkey=3la1`; + +test('getRecord is answered from the PDS once, then from the cache', async () => { + const g = gateway(); + const first = await g.get(GET_RECORD); + const second = await g.get(GET_RECORD); + assert.deepEqual([first.status, first.headers.get('x-nib-cache'), second.headers.get('x-nib-cache')], [200, 'miss', 'hit']); + assert.deepEqual(second.json(), { uri: `at://${ALICE}/run.nibling.project/3la1`, cid: CID1, value: { text: 'first' } }); + assert.equal(second.headers.get('access-control-allow-origin'), '*'); + assert.equal(second.headers.get('cache-control'), 'no-cache'); + assert.deepEqual(g.net.calls, [ + `slingshot.test /xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=${ALICE}`, + `pds.test /xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=run.nibling.project&rkey=3la1`, + ]); +}); + +test('a handle repo is resolved and forwarded as its DID, sharing the DID entry', async () => { + const g = gateway(); + await g.get(GET_RECORD); + const byHandle = await g.get('/xrpc/com.atproto.repo.getRecord?repo=alice.test&collection=run.nibling.project&rkey=3la1'); + assert.equal(byHandle.headers.get('x-nib-cache'), 'hit'); + assert.deepEqual(g.net.calls.slice(2), ['slingshot.test /xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=alice.test']); +}); + +test('after 15 s the current version is served stale while it refreshes, then the refresh is a hit', async () => { + const g = gateway(); + await g.get(GET_RECORD); + g.net.setRecord({ cid: CID2, value: { text: 'second' } }); + g.tick(16_000); + const stale = await g.get(GET_RECORD); + assert.deepEqual([stale.headers.get('x-nib-cache'), stale.json().value], ['stale', { text: 'first' }]); + const fresh = await g.get(GET_RECORD); + assert.deepEqual([fresh.headers.get('x-nib-cache'), fresh.json().value], ['hit', { text: 'second' }]); + g.tick(15_000 + 60_000 + 1); + const expired = await g.get(GET_RECORD); + assert.equal(expired.headers.get('x-nib-cache'), 'miss'); +}); + +test('x-nib-fresh: 1 skips the cached answer and stores the new one for everyone', async () => { + const g = gateway(); + await g.get(GET_RECORD); + g.net.setRecord({ cid: CID2, value: { text: 'saved' } }); + const own = await g.get(GET_RECORD, { headers: { 'x-nib-fresh': '1' } }); + assert.deepEqual([own.headers.get('x-nib-cache'), own.json().value], ['bypass', { text: 'saved' }]); + const other = await g.get(GET_RECORD); + assert.deepEqual([other.headers.get('x-nib-cache'), other.json().value], ['hit', { text: 'saved' }]); +}); + +test('getRecord with a cid is cached for a year, and only when the PDS answers with that cid', async () => { + const g = gateway(); + const pinned = await g.get(`${GET_RECORD}&cid=${CID1}`); + assert.deepEqual([pinned.status, pinned.headers.get('cache-control')], [200, 'public, max-age=31536000, immutable']); + g.tick(30 * 24 * 3600 * 1000); + assert.equal((await g.get(`${GET_RECORD}&cid=${CID1}`)).headers.get('x-nib-cache'), 'hit'); + const gone = await g.get(`${GET_RECORD}&cid=${CID2}`); + assert.deepEqual([gone.status, gone.json().error], [400, 'RecordNotFound']); + assert.equal((await g.get(`${GET_RECORD}&cid=${CID2}`)).headers.get('x-nib-cache'), 'miss'); +}); + +test('params are validated at the boundary, and unknown params never reach the PDS', async () => { + const g = gateway(); + const cases = [ + ['/xrpc/com.atproto.repo.getRecord?repo=nope&collection=run.nibling.project&rkey=3la1', 'repo must be a handle or DID'], + [`/xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=not_an_nsid&rkey=3la1`, 'collection must be an NSID'], + [`/xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=run.nibling.project&rkey=..`, 'rkey must be a record key'], + [`/xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=run.nibling.project`, 'rkey is required'], + [`/xrpc/com.atproto.repo.listRecords?repo=${ALICE}&collection=run.nibling.project&limit=500`, 'limit must be an integer from 1 to 100'], + [`/xrpc/com.atproto.sync.getBlob?did=alice.test&cid=${BLOB}`, 'did must be a DID'], + [`/xrpc/com.atproto.sync.getBlob?did=${ALICE}&cid=nope`, 'cid must be a CID'], + ]; + for (const [path, message] of cases) { + const res = await g.get(path!); + assert.deepEqual([res.status, res.json()], [400, { error: 'InvalidRequest', message }], path); + } + assert.deepEqual(g.net.calls, []); + await g.get(`/xrpc/com.atproto.repo.listRecords?repo=${ALICE}&collection=run.nibling.project&limit=10&evil=1`); + assert.equal(g.net.calls.at(-1), `pds.test /xrpc/com.atproto.repo.listRecords?repo=${ALICE}&collection=run.nibling.project&limit=10`); +}); + +test('getBlob serves the bytes sandboxed and immutable', async () => { + const g = gateway(); + const res = await g.get(`/xrpc/com.atproto.sync.getBlob?did=${ALICE}&cid=${BLOB}`); + assert.deepEqual( + [res.status, res.text, res.headers.get('content-type'), res.headers.get('content-security-policy'), res.headers.get('x-content-type-options'), res.headers.get('cache-control')], + [200, '', 'text/html', "default-src 'none'; sandbox", 'nosniff', 'public, max-age=31536000, immutable'], + ); +}); + +test('a blob or a JSON answer over 5 MB is refused with a 502', async () => { + const g = gateway(); + const big = new Uint8Array(5_000_001); + g.net.services['pds.test'] = () => new Response(big); + const blob = await g.get(`/xrpc/com.atproto.sync.getBlob?did=${ALICE}&cid=${BLOB}`); + const record = await g.get(GET_RECORD); + assert.deepEqual([blob.status, blob.json().error, record.status, record.json().error], [502, 'UpstreamFailure', 502, 'UpstreamFailure']); +}); + +test('a failing upstream becomes a 5xx so the SDK falls back, and is not cached', async () => { + const g = gateway(); + g.net.services['pds.test'] = () => new Response('oops', { status: 503 }); + const res = await g.get(GET_RECORD); + assert.deepEqual([res.status, res.json()], [502, { error: 'UpstreamFailure', message: 'pds.test answered 503' }]); + delete g.net.services['pds.test']; + const down = await g.get(GET_RECORD); + assert.deepEqual([down.status, down.json().error], [502, 'UpstreamFailure']); +}); + +test('a PDS that redirects inward is not followed', async () => { + const g = gateway(); + g.net.services['pds.test'] = () => new Response(null, { status: 302, headers: { location: 'http://169.254.169.254/latest' } }); + const res = await g.get(GET_RECORD); + assert.deepEqual([res.status, res.json().message], [502, 'refusing to fetch http://169.254.169.254/latest']); + assert.ok(!g.net.calls.some((call) => call.startsWith('169.254.169.254'))); +}); + +test('a DID that names a private PDS is never fetched', async () => { + const g = gateway(); + g.net.services['slingshot.test'] = () => Response.json({ did: ALICE, handle: 'alice.test', pds: 'http://10.0.0.1' }); + g.net.services['plc.directory'] = () => + Response.json({ id: ALICE, service: [{ id: '#atproto_pds', type: 'AtprotoPersonalDataServer', serviceEndpoint: 'http://10.0.0.1' }] }); + const res = await g.get(`/xrpc/com.atproto.repo.describeRepo?repo=${ALICE}`); + assert.deepEqual([res.status, res.json()], [400, { error: 'RepoNotFound', message: `${ALICE} names no public https PDS` }]); + assert.ok(!g.net.calls.some((call) => call.startsWith('10.0.0.1'))); +}); + +test('resolveMiniDoc falls back from Slingshot to PLC and DNS, checks the handle, and caches for 5 minutes', async () => { + const g = gateway(); + g.net.services['slingshot.test'] = () => new Response('down', { status: 500 }); + const res = await g.get('/xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=@Alice.Test'); + assert.deepEqual([res.status, res.json()], [200, { did: ALICE, handle: 'alice.test', pds: 'https://pds.test' }]); + assert.deepEqual(g.net.calls, [ + 'slingshot.test /xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=alice.test', + 'cloudflare-dns.com /dns-query?name=_atproto.alice.test&type=TXT', + `plc.directory /${ALICE}`, + ]); + g.tick(299_000); + assert.equal((await g.get('/xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=alice.test')).headers.get('x-nib-cache'), 'hit'); + g.tick(2_000); + assert.equal((await g.get('/xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=alice.test')).headers.get('x-nib-cache'), 'miss'); +}); + +test('a DID whose handle does not point back is reported as handle.invalid', async () => { + const g = gateway(); + g.net.services['slingshot.test'] = () => new Response('down', { status: 500 }); + g.net.services['cloudflare-dns.com'] = () => Response.json({ Answer: [] }); + const res = await g.get(`/xrpc/blue.microcosm.identity.resolveMiniDoc?identifier=${ALICE}`); + assert.deepEqual(res.json(), { did: ALICE, handle: 'handle.invalid', pds: 'https://pds.test' }); +}); + +test('resolveDid serves the DID document', async () => { + const g = gateway(); + const res = await g.get(`/xrpc/com.atproto.identity.resolveDid?did=${REPO}`); + assert.deepEqual(res.json(), { didDoc: { id: REPO, service: [{ id: '#tangled_knot', type: 'TangledKnot', serviceEndpoint: 'https://knot.test' }] } }); + const missing = await g.get('/xrpc/com.atproto.identity.resolveDid?did=did:plc:zzzzzzzzzzzzzzzzzzzzzzzz'); + assert.deepEqual([missing.status, missing.json().error], [400, 'DidNotFound']); +}); + +test('backlinks, counts, and record-by-URI pass through to microcosm and cache for 15 s', async () => { + const g = gateway(); + const subject = encodeURIComponent(`at://${ALICE}/run.nibling.project/3la1`); + const count = await g.get(`/xrpc/blue.microcosm.links.getBacklinksCount?subject=${subject}&source=run.nibling.feed.like:subject.uri`); + const links = await g.get(`/xrpc/blue.microcosm.links.getBacklinks?subject=${subject}&source=run.nibling.feed.like:subject.uri&limit=100`); + const byUri = await g.get(`/xrpc/blue.microcosm.repo.getRecordByUri?at_uri=${subject}`); + assert.deepEqual([count.json(), links.json().total, byUri.json().cid], [{ total: 3 }, 1, CID1]); + assert.equal(count.headers.get('cache-control'), 'public, max-age=15'); + g.tick(14_000); + assert.equal((await g.get(`/xrpc/blue.microcosm.links.getBacklinksCount?subject=${subject}&source=run.nibling.feed.like:subject.uri`)).headers.get('x-nib-cache'), 'hit'); + g.tick(2_000); + assert.equal((await g.get(`/xrpc/blue.microcosm.links.getBacklinksCount?subject=${subject}&source=run.nibling.feed.like:subject.uri`)).headers.get('x-nib-cache'), 'miss'); + assert.deepEqual(g.net.calls.filter((c) => c.startsWith('constellation')).length, 3); +}); + +const pkt = (line: string) => (line.length + 4).toString(16).padStart(4, '0') + line; +const wantBody = (sha: string, extra = '') => `${pkt(`want ${sha} side-band-64k agent=test\n`)}${pkt('deepen 1\n')}0000${extra}${pkt('done\n')}`; + +test('isPureWant accepts wants, deepen, and done, and nothing that depends on what the client has', () => { + assert.equal(isPureWant(new TextEncoder().encode(wantBody(SHA))), true); + assert.equal(isPureWant(new TextEncoder().encode(wantBody(SHA, pkt(`have ${'c'.repeat(40)}\n`)))), false); + assert.equal(isPureWant(new TextEncoder().encode(`${pkt(`want ${SHA}\n`)}${pkt(`shallow ${SHA}\n`)}0000${pkt('done\n')}`)), false); + assert.equal(isPureWant(new TextEncoder().encode(`${pkt(`want ${SHA}\n`)}0000`)), false); + assert.equal(isPureWant(new TextEncoder().encode('zzzz')), false); +}); + +test('git reads go only to the knot the repo DID names; pushes are refused', async () => { + const g = gateway(); + const refs = await g.get(`/git/${REPO}/info/refs?service=git-upload-pack`); + assert.deepEqual( + [refs.status, refs.text, refs.headers.get('cache-control'), refs.headers.get('access-control-allow-origin')], + [200, '001e# service=git-upload-pack\n0000', 'no-store', '*'], + ); + const push = await g.get(`/git/${REPO}/info/refs?service=git-receive-pack`); + const pushPost = await g.get(`/git/${REPO}/git-receive-pack`, { method: 'POST', body: '0000' }); + assert.deepEqual([push.status, pushPost.status], [403, 403]); + const noKnot = await g.get(`/git/${ALICE}/info/refs?service=git-upload-pack`); + assert.deepEqual([noKnot.status, noKnot.json().message], [404, `${ALICE} names no public https #tangled_knot`]); + assert.deepEqual(g.net.calls, [`plc.directory /${REPO}`, `knot.test /${REPO}/info/refs?service=git-upload-pack`, `plc.directory /${ALICE}`]); +}); + +test('a pure-want upload-pack is cached by its body; one with haves, or an ERR answer, is not', async () => { + const g = gateway(); + const post = (body: string) => g.get(`/git/${REPO}/git-upload-pack`, { method: 'POST', body, headers: { 'content-type': 'application/x-git-upload-pack-request' } }); + const first = await post(wantBody(SHA)); + const second = await post(wantBody(SHA)); + assert.deepEqual([first.text, first.headers.get('x-nib-cache'), second.text, second.headers.get('x-nib-cache')], ['0008NAK\nPACK', 'miss', '0008NAK\nPACK', 'hit']); + const withHave = wantBody(SHA, pkt(`have ${'c'.repeat(40)}\n`)); + await post(withHave); + const again = await post(withHave); + assert.deepEqual([again.headers.get('x-nib-cache'), again.headers.get('cache-control')], [null, 'no-store']); + const missing = await post(wantBody('b'.repeat(40))); + const missingAgain = await post(wantBody('b'.repeat(40))); + assert.deepEqual([missing.text, missingAgain.headers.get('x-nib-cache')], ['0019ERR not our ref bbbb\n', 'miss']); + assert.equal(g.net.calls.filter((c) => c.endsWith('git-upload-pack')).length, 5); +}); + +test('a preflight allows the cache bypass and git headers from any origin', async () => { + const g = gateway(); + const res = await g.get(GET_RECORD, { method: 'OPTIONS' }); + assert.deepEqual( + [res.status, res.headers.get('access-control-allow-origin'), res.headers.get('access-control-allow-headers')], + [204, '*', 'content-type, git-protocol, x-nib-fresh'], + ); +}); diff --git a/packages/api/tests/router.test.ts b/packages/api/tests/router.test.ts index acf0dec..8650899 100644 --- a/packages/api/tests/router.test.ts +++ b/packages/api/tests/router.test.ts @@ -2,6 +2,7 @@ import assert from 'node:assert/strict'; import { test } from 'node:test'; import { handleRequest, type IndexStub, type RouterEnv } from '../src/router.ts'; import { upstream, type Upstream } from '../src/upstream.ts'; +import { memoryCache } from '../src/gateway/index.ts'; function fakeEnv(stub: Partial = {}): RouterEnv { const index: IndexStub = { @@ -14,7 +15,10 @@ function fakeEnv(stub: Partial = {}): RouterEnv { INDEX: { getByName: () => index }, APP_ORIGIN: 'https://nibling.run', SLINGSHOT_URL: 'https://slingshot.microcosm.blue', + CONSTELLATION_URL: 'https://constellation.microcosm.blue', fetch: upstream(async () => new Response('{}', { status: 404 })), + cache: memoryCache(Date.now), + waitUntil: () => {}, }; } diff --git a/packages/api/tests/user-agent.test.ts b/packages/api/tests/user-agent.test.ts index 0a48246..769edf0 100644 --- a/packages/api/tests/user-agent.test.ts +++ b/packages/api/tests/user-agent.test.ts @@ -4,13 +4,16 @@ import { join } from 'node:path'; import { test } from 'node:test'; import { ingest } from '../src/index/ingest.ts'; import { IndexModel } from '../src/index/model.ts'; +import { memoryCache } from '../src/gateway/index.ts'; import { handleRequest, type RouterEnv } from '../src/router.ts'; import { ingestDeps, outbound } from '../src/services.ts'; import { sqliteSql } from './sqlite-sql.ts'; const UA = 'nibling.run/0.0.1 (+https://ops.example/contact)'; const ALICE = 'did:plc:aaaaaaaaaaaaaaaaaaaaaaaa'; +const REPO = 'did:plc:rrrrrrrrrrrrrrrrrrrrrrrr'; const PROJECT = `at://${ALICE}/run.nibling.project/3la1`; +const BLOB = 'bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku'; interface Seen { url: string; @@ -30,8 +33,19 @@ function world(request: Request): Response { return Response.json({ repos: [{ did: ALICE }] }); case `plc.directory/${ALICE}`: return Response.json({ id: ALICE, service: [{ id: '#atproto_pds', type: 'AtprotoPersonalDataServer', serviceEndpoint: 'https://pds.test' }] }); + case `plc.directory/${REPO}`: + return Response.json({ id: REPO, service: [{ id: '#tangled_knot', type: 'TangledKnot', serviceEndpoint: 'https://knot.test' }] }); case 'pds.test/xrpc/com.atproto.repo.listRecords': return Response.json({ records: [] }); + case 'pds.test/xrpc/com.atproto.repo.getRecord': + return Response.json({ uri: PROJECT, cid: 'bafy1', value: {} }); + case 'pds.test/xrpc/com.atproto.sync.getBlob': + return new Response('blob'); + case 'constellation.test/xrpc/blue.microcosm.links.getBacklinksCount': + return Response.json({ total: 1 }); + case `knot.test/${REPO}/info/refs`: + case `knot.test/${REPO}/git-upload-pack`: + return new Response('0000'); case 'jetstream.test/xrpc/network.bsky.jetstream.subscribeEvents': { const listeners: Record void)[]> = {}; const webSocket = { @@ -71,6 +85,7 @@ async function recording(run: () => Promise): Promise { const env = { APP_ORIGIN: 'https://nibling.run', SLINGSHOT_URL: 'https://slingshot.test', + CONSTELLATION_URL: 'https://constellation.test', JETSTREAM_URL: 'wss://jetstream.test', RELAY_URL: 'https://relay.test', CONTACT_URL: 'https://ops.example/contact', @@ -78,7 +93,7 @@ const env = { function routerEnv(): RouterEnv { const index = { getRecent: async () => ({ projects: [] }), getTrending: async () => ({ projects: [] }), getKnown: async () => [] }; - return { ...env, INDEX: { getByName: () => index }, fetch: outbound(env) }; + return { ...env, INDEX: { getByName: () => index }, fetch: outbound(env), cache: memoryCache(Date.now), waitUntil: () => {} }; } test('link cards, backfill, and the Jetstream upgrade all send exactly the nibling User-Agent', async () => { @@ -100,6 +115,34 @@ test('link cards, backfill, and the Jetstream upgrade all send exactly the nibli ]); }); +test('every gateway read sends exactly the nibling User-Agent', async () => { + let env: RouterEnv; + const get = async (path: string, init?: RequestInit) => { + const res = await handleRequest(new Request(`https://api.nibling.run${path}`, init), env); + assert.equal(res.status, 200, path); + await res.arrayBuffer(); + }; + const seen = await recording(async () => { + env = routerEnv(); + await get(`/xrpc/com.atproto.repo.getRecord?repo=${ALICE}&collection=run.nibling.project&rkey=3la1`); + await get(`/xrpc/com.atproto.sync.getBlob?did=${ALICE}&cid=${BLOB}`); + await get(`/xrpc/blue.microcosm.links.getBacklinksCount?subject=${encodeURIComponent(PROJECT)}&source=run.nibling.feed.like:subject.uri`); + await get(`/xrpc/blue.microcosm.repo.getRecordByUri?at_uri=${encodeURIComponent(PROJECT)}`); + await get(`/git/${REPO}/info/refs?service=git-upload-pack`); + await get(`/git/${REPO}/git-upload-pack`, { method: 'POST', body: '0000' }); + }); + assert.deepEqual(seen, [ + { url: 'slingshot.test/xrpc/blue.microcosm.identity.resolveMiniDoc', userAgent: UA }, + { url: 'pds.test/xrpc/com.atproto.repo.getRecord', userAgent: UA }, + { url: 'pds.test/xrpc/com.atproto.sync.getBlob', userAgent: UA }, + { url: 'constellation.test/xrpc/blue.microcosm.links.getBacklinksCount', userAgent: UA }, + { url: 'slingshot.test/xrpc/blue.microcosm.repo.getRecordByUri', userAgent: UA }, + { url: `plc.directory/${REPO}`, userAgent: UA }, + { url: `knot.test/${REPO}/info/refs`, userAgent: UA }, + { url: `knot.test/${REPO}/git-upload-pack`, userAgent: UA }, + ]); +}); + const src = new URL('../src/', import.meta.url).pathname; const sources = (dir: string): string[] => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => diff --git a/packages/api/wrangler.jsonc b/packages/api/wrangler.jsonc index 45650c1..12693ff 100644 --- a/packages/api/wrangler.jsonc +++ b/packages/api/wrangler.jsonc @@ -15,6 +15,7 @@ "APP_ORIGIN": "http://127.0.0.1:5173", "JETSTREAM_URL": "wss://jetstream.us-east.bsky.network", "RELAY_URL": "https://relay1.us-east.bsky.network", - "SLINGSHOT_URL": "https://slingshot.microcosm.blue" + "SLINGSHOT_URL": "https://slingshot.microcosm.blue", + "CONSTELLATION_URL": "https://constellation.microcosm.blue" } } -- knotmirror 0.0.1