@volter/twin-upstash 0.1.0

package/dist/src/upstash-server.d.ts

@@ -0,0 +1,29 @@
+import { upstashRedisOwners } from './upstash-store.js';
+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>;
+}
+/** The pack's fetch, with `owners()`: per id of Redis's command table, the command core (`handler`) or the gap. */
+export declare function createUpstashRedisTwinFetch(options?: UpstashRedisTwinFetchOptions): ((request: Request) => Promise<Response>) & {
+    owners: typeof upstashRedisOwners;
+};
+export declare function createUpstashRedisTwinServer(options?: UpstashRedisServerOptions): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/upstash-server.js

@@ -0,0 +1,81 @@
+// 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.js";
+import { upstashRedisOwners } from "./upstash-store.js";
+import { API_HOST, CONSOLE_HOST, createUpstashApiLaneFetch } from "../api/src/fetch.js";
+import { createQstashLaneFetch } from "../qstash/src/fetch.js";
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+/** 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 = {}) {
+    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) {
+        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 = {};
+        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() {
+    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 = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createUpstashRedisTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/upstash-store.d.ts

@@ -0,0 +1,114 @@
+export declare const SERVICE = "upstash";
+/**
+ * A Redis SIMPLE STATUS reply, kept distinct from a bulk string.
+ *
+ * This is not pedantry — it is required for `Upstash-Encoding: base64` fidelity. LIVE-PROBED rule:
+ * with that header on, Upstash base64-encodes every string in `result` at any array depth EXCEPT
+ * the simple-status reply `OK`, which is passed through raw. `PING`'s status `PONG` IS encoded
+ * (`UE9ORw==`), and so is a BULK STRING whose value happens to be `OK` (`GET okkey` → `T0s=`). So
+ * the exemption is scoped to the status reply `OK` specifically, and a twin that exempted any
+ * string equal to `"OK"` would send raw bytes for `GET okkey`. Hence this wrapper.
+ */
+export declare class RedisStatus {
+    readonly value: string;
+    constructor(value: string);
+}
+/** The JSON projection of a RESP reply — what Upstash puts in `{"result": …}`. */
+export type RedisValue = null | number | string | RedisStatus | RedisValue[];
+/** A command-level failure. `message` is the vendor's literal error string. Maps to HTTP 400. */
+export declare class RedisCommandError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a write is attempted against a read-only twin. Mapped to HTTP 405 by the handler. */
+export declare class ReadOnlyError extends Error {
+    constructor();
+}
+export declare const KEY_TYPES: readonly ["string", "list", "set", "hash", "zset", "stream"];
+export type KeyType = typeof KEY_TYPES[number];
+/** Everything a run needs. `root` scopes the kernel state; `occurredAt` IS the clock. */
+export type RedisContext = {
+    root?: string;
+    occurredAt: string;
+    /** When true, any write command raises `ReadOnlyError` (the handler answers 405). */
+    readOnly?: boolean;
+    /** The database a Developer API lane made (its `database_id`), whose keys and scripts are its own: subjects
+     *  `db:<id>:key:<name>` and `db:<id>:script:<sha1>`. Absent, the World's own database: `key:<name>`, `script:<sha1>`. */
+    database?: string;
+};
+/** Upstash's own unavailable-command message — NOT stock Redis's "unknown command". LIVE-PROBED. */
+export declare function unavailableCommand(name: string): string;
+/** Commands the REST layer refuses outright — LIVE-PROBED message, name upper-cased in quotes. */
+export declare function restRestricted(name: string): string;
+export declare function wrongArity(name: string): string;
+/**
+ * Commands the REST surface rejects even though Redis has them: connection/transaction/pub-sub
+ * control that has no meaning over stateless HTTP. LIVE-PROBED (`AUTH`, `MULTI`, `WATCH`,
+ * `SUBSCRIBE`, `CLIENT` all answered the `not allowed in REST` message).
+ */
+export declare const REST_RESTRICTED_COMMANDS: Set<string>;
+/**
+ * The commands this twin serves, each with the most arguments (after the name) its own parsing takes,
+ * `-1` for no bound: `[min, max]`, where `min` is the table's arity (checked equal for every entry) and
+ * `max` is what the command itself refuses past, with the same "wrong number of arguments". One table for
+ * both callers, `execOne` and `commandShapeError` (which lets `/multi-exec` reject a malformed batch at
+ * QUEUE time, as Redis's `EXECABORT` does). SCRIPT is a container: its subcommands are the table's ids.
+ */
+export declare const SERVED_COMMANDS: Record<string, [number, number]>;
+/**
+ * Does this command MUTATE? Takes the whole argv, not just the name, because two commands are
+ * only writes for some of their subcommands. A read-only twin and `EVAL_RO` both key off this,
+ * and getting it wrong in either direction is a bug: too broad refuses legitimate reads (§9 round
+ * 1), too narrow lets a write through a read-only twin.
+ */
+export declare function isWriteCommand(name: string, args?: readonly string[]): boolean;
+/**
+ * QUEUE-TIME validation: is this command well-formed enough for Redis to accept it into a MULTI?
+ * Returns the vendor's error string, or `null` when the command is fine. Only structural faults
+ * live here (unknown command, REST-restricted command, wrong arity) — a WRONGTYPE or a bad integer
+ * is a RUNTIME error, which (LIVE-PROBED) does NOT abort a transaction.
+ */
+export declare function commandShapeError(argv: unknown[]): string | null;
+/** The table id a command line names: a container's subcommand (`SCRIPT LOAD`) when the table has it. */
+export declare function commandId(argv: string[]): string | undefined;
+/** Per id of Redis's table, who answers it: the command core (`handler`) or the gap. */
+export declare function upstashRedisOwners(): Record<string, 'handler' | 'gap'>;
+/** One key as a backup holds it: its name, type, value, deadline and a stream's last id. */
+export type KeyImage = {
+    name: string;
+    kind: string;
+    v: unknown;
+    pexpireAt: number | null;
+    lastId?: string;
+};
+/** A database's live keys as they stand at `ctx.occurredAt`: what a backup of it holds (the Developer API lane's
+ *  backups, ../api/src/semantics/backups.ts). */
+export declare function keyspaceImage(ctx: RedisContext): KeyImage[];
+/** Replace a database's keys with a backup's: every live key is deleted, then the image's keys are written ("All
+ *  existing data in the target database will be deleted before the restore operation begins",
+ *  https://upstash.com/docs/redis/features/backup). */
+export declare function restoreKeyspace(image: readonly KeyImage[], ctx: RedisContext): Promise<void>;
+/** Redis glob-style key matching (`*`, `?`, `[abc]`, `[a-c]`, `[^a]`, `\` escape). */
+export declare function globMatch(pattern: string, subject: string): boolean;
+export type RunItem = {
+    result: RedisValue;
+} | {
+    error: string;
+};
+/**
+ * Execute a whole request's worth of commands against one root, then flush.
+ *
+ * Each element comes back as `{result}` or `{error}` — the exact per-command envelope Upstash's
+ * `/pipeline` and `/multi-exec` endpoints return and the SDK's `Pipeline.exec` destructures.
+ *
+ * RUNTIME ERRORS DO NOT ABORT — not in a pipeline and (LIVE-PROBED, contrary to the intuition that
+ * a "transaction" rolls back) NOT in `/multi-exec` either: Upstash's own docs say "all commands
+ * will be executed. Upstash Redis will not stop the processing of commands. This is to provide same
+ * semantics with Redis when there are errors inside a transaction." A probe of the real service
+ * confirmed a `SET` after a failing `INCR` in a `/multi-exec` batch is applied. Structural faults —
+ * an unavailable command or a bad arity — are QUEUE-time and DO discard the whole batch, but the
+ * caller (`upstash-twin.ts`) rejects those before this function is ever reached.
+ */
+export declare function execRedisRun(commands: string[][], ctx: RedisContext): Promise<{
+    items: RunItem[];
+    wrote: boolean;
+}>;