@volter/twin-upstash 0.1.0

package/src/upstash-server.ts

@@ -0,0 +1,103 @@
+// upstash twin HTTP server — serve the Upstash Redis REST twin over HTTP so the real
+// `@upstash/redis` SDK (pointed at it with nothing but its own public `url` option) works
+// UNMODIFIED, and so `@upstash/ratelimit` on top of that SDK enforces a real limit.
+//
+// ── THE INJECTED CLOCK ────────────────────────────────────────────────────────────────────────
+// `now` is the twin's whole notion of time: it produces the `occurredAt` the kernel stamps each
+// action with AND the instant every TTL is measured against. It defaults to the wall clock (a
+// server has to), but a test passes its own so that TTL expiry, `EXPIRE`/`TTL` arithmetic and
+// stream ids become data it controls rather than a race it hopes to win. This is the seam the
+// repo's no-wall-clock discipline requires — see the store module's header.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createUpstashRedisTwinFetch` and
+// the SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): replies carry ONLY the handler's own headers (the REST envelope
+// declares its own content type; a 405 carries none at all), and the clock is an injectable seam.
+import { serveHttp } from '@volter/world-core';
+import { handleUpstashRedisTwinRequest } from './upstash-twin.ts';
+import { upstashRedisOwners } from './upstash-store.ts';
+import { API_HOST, CONSOLE_HOST, createUpstashApiLaneFetch } from '../api/src/fetch.ts';
+import { createQstashLaneFetch } from '../qstash/src/fetch.ts';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+
+export type UpstashRedisServerOptions = {
+  root?: string;
+  port?: number;
+  readOnly?: boolean;
+  /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+  token?: string;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+};
+
+/** Options every Upstash Redis-twin HTTP surface needs, independent of who owns the socket. */
+export interface UpstashRedisTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** The token the twin demands. Omit to accept any non-empty credential (still 401s a missing one). */
+  token?: string;
+  /** The injected clock. Returns the ISO instant this request "happens at". */
+  now?: () => string;
+  /** the QStash lane's fetch (../qstash/src/fetch.ts), when the caller has one already */
+  qstash?: (request: Request) => Promise<Response>;
+}
+
+/** QStash's hosts: qstash.upstash.io and qstash-<region>.upstash.io (both documents' `servers`). */
+const QSTASH_HOST = /^qstash(-[a-z0-9-]+)?\.upstash\.io$/;
+/** The QStash lane's requests at the pack's own address: its API (an application's QSTASH_URL is the pack's address, and
+ *  every QStash path begins `/v2/`, which no Redis command is) and the World's doors for it. */
+const QSTASH_PATH = /^\/(v2\/|_twin\/(deliveries|destinations)(\/|$))/;
+
+/** The pack's fetch, with `owners()`: per id of Redis's command table, the command core (`handler`) or the gap. */
+export function createUpstashRedisTwinFetch(options: UpstashRedisTwinFetchOptions = {}): ((request: Request) => Promise<Response>) & { owners: typeof upstashRedisOwners } {
+  const readOnly = options.readOnly ?? false;
+  const now = options.now ?? (() => worldNow());
+  // api.upstash.com's Developer API and console.upstash.com's pages are the pack's `api` lane (../api/src/fetch.ts)
+  const api = createUpstashApiLaneFetch({ ...(options.root !== undefined ? { root: options.root } : {}), readOnly, clock: now });
+  const qstash = options.qstash ?? createQstashLaneFetch({ ...(options.root !== undefined ? { root: options.root } : {}), readOnly, clock: now });
+  const fetch = async function upstashRedisTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // the vendor host a redirected request names in x-volter-twin-original-host (the injector's fetch path, a hosted
+    // World), else its Host, else its URL's (vercel-server.ts's precedent): the lane's two hosts go to the lane
+    const host = (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host).split(':')[0]!.toLowerCase();
+    const vendorHost = host === API_HOST || host === CONSOLE_HOST ? host : url.hostname === API_HOST || url.hostname === CONSOLE_HOST ? url.hostname : undefined;
+    if (vendorHost !== undefined) return api(request, vendorHost);
+    if (QSTASH_HOST.test(host) || QSTASH_HOST.test(url.hostname) || QSTASH_PATH.test(url.pathname)) return qstash(request);
+    // GET /twin — the discovery manifest (education inside the twin).
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') return discovery();
+    // a daily backup due before this request is made first, so it holds the keys as they were (../api/src/semantics/time.ts)
+    await api.catchUp(request);
+    const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : '';
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+    const { status, body: out, headers: outHeaders } = await handleUpstashRedisTwinRequest({
+      method: request.method,
+      path: url.pathname + (url.search || ''),
+      body,
+      headers,
+      readOnly,
+      occurredAt: now(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+      ...(options.token !== undefined ? { token: options.token } : {}),
+    });
+    // A null body means "no body at all" (405 on a disallowed method, HEAD, CORS preflight) —
+    // the real service answers those with zero bytes and, for 405, no content-type either.
+    if (out === null) return new Response(null, { status, headers: { ...(outHeaders ?? {}) } });
+    return new Response(JSON.stringify(out), { status, headers: { ...(outHeaders ?? {}) } });
+  };
+  return Object.assign(fetch, { owners: upstashRedisOwners });
+}
+
+/** `GET /twin`, the discovery manifest. */
+function discovery(): Response {
+  return Response.json(statefulTwinManifest({ vendor: 'upstash', twinOf: 'Upstash Redis (REST protocol)', stores: "a real Redis keyspace served over Upstash's REST envelope" }));
+}
+
+export async function createUpstashRedisTwinServer(options: UpstashRedisServerOptions = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createUpstashRedisTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}