@volter/twin-upstash 0.1.0 → 0.1.2

package/dist/src/upstash-server.js

@@ -13,7 +13,7 @@
 // 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 { isReadOnlyRequest, serveHttp, withRequestScopes } 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";
@@ -26,12 +26,16 @@ const QSTASH_HOST = /^qstash(-[a-z0-9-]+)?\.upstash\.io$/;
 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)
+    // the lanes' own read-only twin; a read-only REQUEST is refused by the kernel's scope around them (withRequestScopes)
+    const readOnly = options.readOnly ?? false;
     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) {
+    // a read-only request (x-volter-read-only) is a request to a read-only twin: a command that writes
+    // (by GET too: Upstash runs any command from the path) is refused, and the kernel refuses any that slip
+    const fetch = withRequestScopes(async function upstashRedisTwinFetch(request) {
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(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
@@ -64,7 +68,7 @@ export function createUpstashRedisTwinFetch(options = {}) {
         if (out === null)
             return new Response(null, { status, headers: { ...(outHeaders ?? {}) } });
         return new Response(JSON.stringify(out), { status, headers: { ...(outHeaders ?? {}) } });
-    };
+    }, { refuse: () => Response.json({ error: 'NOPERM this request is read-only' }, { status: 403 }) });
     return Object.assign(fetch, { owners: upstashRedisOwners });
 }
 /** `GET /twin`, the discovery manifest. */

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

@@ -1,66 +1,21 @@
+import { type KeyImage, type RedisContext as CoreContext, type RedisDialect, type RunItem } from '@volter/world-core/redis';
+export { globMatch, KEY_TYPES, ReadOnlyError, RedisCommandError, RedisStatus, wrongArity, } from '@volter/world-core/redis';
+export type { KeyImage, KeyType, RedisValue, RunItem } from '@volter/world-core/redis';
 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;
-};
+/** A run's context as this pack's callers give it: the service and the dialect are Upstash's. */
+export type RedisContext = Omit<CoreContext, 'service' | 'dialect'>;
 /** 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.
- */
+/** The commands this twin serves: the core's, and SELECT, which Upstash answers for its one database. */
 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
@@ -72,43 +27,16 @@ export declare function commandShapeError(argv: unknown[]): string | null;
 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.
- */
+/** Upstash's REST API as a dialect of the core: its refusals, its one database, its scripts rolled back on error. */
+export declare const UPSTASH_DIALECT: RedisDialect;
+/** Run a request's commands on the core, as Upstash answers them (the kernel's `execRedisRun`). */
 export declare function execRedisRun(commands: string[][], ctx: RedisContext): Promise<{
     items: RunItem[];
     wrote: boolean;
 }>;
+/** Does this command MUTATE, as the REST API's read-only token decides it. */
+export declare function isWriteCommand(name: string, args?: readonly string[]): boolean;
+/** A database's live keys as they stand at `ctx.occurredAt`: what a backup of it holds. */
+export declare function keyspaceImage(ctx: RedisContext): KeyImage[];
+/** Replace a database's keys with a backup's. */
+export declare function restoreKeyspace(image: readonly KeyImage[], ctx: RedisContext): Promise<void>;