@volter/twin-upstash 0.1.0

package/src/index.ts

@@ -0,0 +1,203 @@
+// @volter/twin-upstash — the Upstash Redis REST API twin, built on the shared @volter/world-core
+// kernel. Per-database host transport (`https://<slug>.upstash.io`), five request forms
+// (`POST /`, path-style `GET|POST /CMD/args`, raw-body `POST /set/k`, `POST /pipeline`,
+// `POST /multi-exec`), Bearer-token auth with the vendor's literal `WRONGPASS` 401, the
+// `{result}`/`{error}` envelope, and `Upstash-Encoding: base64`.
+//
+// Behind that protocol is a REAL Redis: a stateful keyspace (strings, counters, hashes, sets,
+// sorted sets, lists, streams) with real type errors (`WRONGTYPE`), real integer semantics
+// (`ERR value is not an integer or out of range`), real lazy TTL expiry — and a Lua-subset
+// INTERPRETER behind `EVAL`/`EVALSHA`, which is what lets `@upstash/ratelimit` run its own
+// unmodified fixed-window / sliding-window / token-bucket scripts against this twin and actually
+// enforce a limit. Nothing about those scripts is special-cased: they run because the interpreter
+// runs Lua, and their SHA1s are only ever used the way real Redis uses them (the script cache and
+// the `NOSCRIPT` fallback contract).
+//
+// TIME IS INJECTED: TTL expiry, rate-limit windows and stream ids are all measured against an
+// INJECTED clock — the request's own `occurredAt`, or `createUpstashRedisTwinServer({ now })` — so
+// every time-dependent behaviour is reproducible rather than raced. See README ## Coverage.
+//
+// State lives ENTIRELY in the kernel action log (no side-store): every Redis key is one kernel
+// subject, so a restart against the same root answers the same `GET`.
+export {
+  handleUpstashRedisTwinRequest,
+  routeUpstashRedisSurface,
+  upstashTwinSnapshot,
+  extractUpstashCredential,
+  encodeResult,
+  nextSyncToken,
+  UPSTASH_RESOURCE_TYPES,
+  UPSTASH_UNAUTHORIZED_ERROR,
+} from './upstash-twin.ts';
+export type {
+  UpstashRedisRequest,
+  UpstashRedisResponse,
+  UpstashRedisResourceType,
+  UpstashRedisSurface,
+  UpstashRedisTwinSnapshot,
+} from './upstash-twin.ts';
+
+// The command core — exported so a caller can drive Redis semantics in-process, without HTTP.
+export {
+  execRedisRun,
+  commandShapeError,
+  globMatch,
+  isWriteCommand,
+  unavailableCommand,
+  restRestricted,
+  wrongArity,
+  RedisCommandError,
+  RedisStatus,
+  ReadOnlyError,
+  SERVED_COMMANDS,
+  commandId,
+  upstashRedisOwners,
+  KEY_TYPES,
+  REST_RESTRICTED_COMMANDS,
+  SERVICE,
+} from './upstash-store.ts';
+export type { RedisContext, RedisValue, RunItem, KeyType } from './upstash-store.ts';
+
+// The Lua-subset interpreter. Exported because `EVAL` fidelity is a headline claim of this pack and
+// a consumer (or a reviewer) must be able to run a script against it directly.
+export { runLua, parseLua, tokenize, luaScriptSha1, luaTruthy, luaTypeName, luaToNumber, luaEquals, numberToLuaString, LuaError, LuaTable } from './upstash-lua.ts';
+export type { LuaHost, LuaValue, LuaFunction } from './upstash-lua.ts';
+
+export { createUpstashRedisTwinFetch, createUpstashRedisTwinServer } from './upstash-server.ts';
+export type { UpstashRedisServerOptions, UpstashRedisTwinFetchOptions } from './upstash-server.ts';
+
+export {
+  mapKey,
+  pullUpstashRedisKeys,
+  pullUpstashRedisScan,
+  syncUpstashRedisFromReal,
+} from './upstash-connector.ts';
+export type {
+  UpstashRedisLikeClient,
+  UpstashRedisKeyHandle,
+  UpstashRedisRealKey,
+  UpstashRedisBudgetedOptions,
+} from './upstash-connector.ts';
+
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardUpstashRedisClient`, the choke point
+// the connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `UpstashRedisBudgetError` by type; there is deliberately no
+// export that disables the guard.
+export {
+  UPSTASH_BUDGETED_METHODS,
+  UPSTASH_BUDGET_CEILING,
+  UPSTASH_BUDGET_MAX_RETRY_AFTER_S,
+  UPSTASH_BUDGET_WINDOW_MS,
+  UPSTASH_CALL_WEIGHTS,
+  UPSTASH_RATE_BUDGET,
+  UpstashRedisBudget,
+  UpstashRedisBudgetError,
+  upstashBudgetPath,
+  upstashCallWeight,
+  upstashClientBudget,
+  guardUpstashRedisClient,
+} from './upstash-budget.ts';
+export type {
+  UpstashRedisBudgetErrorKind,
+  UpstashRedisBudgetOptions,
+  UpstashRedisBudgetReservation,
+  UpstashRedisBudgetSnapshot,
+} from './upstash-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performUpstashRedisAction, syncUpstashRedisFromRemote } from './upstash-connector.ts';
+import { UPSTASH_RATE_BUDGET as RATE_BUDGET } from './upstash-budget.ts';
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system. Moved 2026-09-08.
+  protocol: '2',
+  // A cache moves constantly and a full SCAN of a real keyspace is expensive, so the poll is coarse
+  // and the on-demand path is what a world uses when it needs to know now.
+  refresh: { every: '15m', webhook: false, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performUpstashRedisAction, refresh: syncUpstashRedisFromRemote },
+  // The round trip is a SET — Redis's own write, idempotent by nature, so a second send on a branch
+  // sets the key again rather than being refused.
+  roundTrip: { method: 'POST', path: '/', body: ['SET', 'round-trip', 'round-trip'], headers: { authorization: 'Bearer round-trip' } },
+  parityOrigin: 'http://twin',
+  shapeParity: 'held',
+
+  // The SAME object upstash-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  vendor: 'upstash',
+  // INTERCEPTION — this pack's hosts as DATA (packRegistry HostRule), moved from the injector's
+  // hand table with its reasoning verbatim:
+  // (TOMBSTONE) `azureformrecognizer` used to live here as a bare
+  // `h.endsWith('.cognitiveservices.azure.com')` suffix matcher, with a note that a second Azure
+  // AI twin on that shared domain would need path-prefix disambiguation. That second twin is here
+  // — the `azure` pack's service area 2 serves Azure OpenAI on `/openai/*` — so BOTH claims moved
+  // onto their pack descriptors WITH `pathPattern`s and this hand entry was deleted in the same
+  // change (one home per fact; keeping it would throw at require time). See
+  // packages/twin/azureformrecognizer/src/index.ts and packages/twin/azure/src/index.ts.
+  // Upstash Redis. Every database gets its OWN host under one shared apex —
+  // https://<slug>.upstash.io, where the slug is per-database (both naming generations exist in
+  // the wild: the legacy regional `us1-merry-cat-32748` form and the current
+  // `striking-osprey-20681` form) — so there is no fixed host to match and this needs a SUFFIX
+  // matcher, exactly like azureformrecognizer's per-resource Azure hosts above. Confirmed against
+  // the pack's own connector/README and the vendor's REST docs; global databases use ONE hostname
+  // and Upstash routes internally, so there is no region-suffixed variant to add.
+  //
+  // QStash and Upstash Workflow share the apex too (qstash.upstash.io, qstash-<region>.upstash.io): they are this pack's
+  // `qstash` lane (../qstash/src/), so the suffix takes their hosts and the pack's fetch sends them to the lane. The one
+  // exclusion is Upstash VECTOR (`*-vector.upstash.io`, packages/twin/upstashvector), claimed by that pack's own entry: a
+  // bare suffix would swallow it into this twin. Upstash Search (`*-search.upstash.io`) also lives here and has no twin
+  // yet; when one lands it needs the same treatment, and this comment is the note that says so.
+  hosts: [
+    { suffix: '.upstash.io' },
+    { suffix: '-vector.upstash.io', exclude: true },
+    // the Developer API and the console's pages, the pack's `api` lane (../api/src/index.ts)
+    { host: 'api.upstash.com', pathPattern: '^/v2/(redis|team|teams)(/|$)' },
+    { host: 'console.upstash.com', pathPattern: '^/(login|account/(api|teams)|qstash|invite)(/|$)' },
+  ],
+  // QStash's clients read their base URL from QSTASH_URL (@upstash/qstash's documented override; @upstash/workflow's
+  // Client is a QStash client and reads the same), so the World points it at this twin as well as redirecting the hosts.
+  endpointEnv: {
+    name: 'UPSTASH_TWIN_URL',
+    templates: { QSTASH_URL: '${url}' },
+    note: '@upstash/qstash and @upstash/workflow read QSTASH_URL; the injector also redirects *.upstash.io (Redis databases, QStash) to this twin.',
+  },
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-upstash',
+  resources: ['key'],
+  specSource:
+    'upstash.com/docs/redis/features/restapi + the installed @upstash/redis@1.35.7 compiled source + LIVE PROBES of a real ephemeral Upstash database (every error string, HTTP status and base64 rule); see spec-sources.json.',
+  description:
+    'Upstash Redis REST twin — a real stateful Redis keyspace (strings/counters/TTL/hashes/sets/sorted-sets/lists/streams, WRONGTYPE and integer errors, lazy expiry) served over Upstash\'s REST protocol: POST /, path-style GET /get/key, POST /pipeline, POST /multi-exec, Bearer auth with the vendor\'s WRONGPASS 401, and Upstash-Encoding: base64. EVAL/EVALSHA run a Lua-subset INTERPRETER over that same command core, so @upstash/ratelimit\'s own unmodified scripts execute and a limiter genuinely enforces. Clock is injected (no wall-clock reads). Kernel-backed. Its lanes: the Developer API and console (api.upstash.com, console.upstash.com: sign-in, API keys, the QStash page), and QStash with Upstash Workflow (qstash.upstash.io and QSTASH_URL: publish, enqueue, batch, schedules, queues, the DLQs, signing keys, and workflow runs delivered step by step to the app, with waits, notify, cancel and resume).',
+  // Adoption, all in the pack's one home. The `scopes` entries are exact PACKAGE names, not an apex: the `@upstash/` scope
+  // spans several Upstash products, and Vector has its own pack, so it is claimed package by package: the Redis client and
+  // the ratelimiter built on it, and QStash's and Workflow's clients (the qstash lane). Stems: UPSTASH_REDIS_* and KV_REST_*
+  // (the env names Vercel KV, this vendor's Redis under another label, writes into a project), and QSTASH_*.
+  adoption: {
+    pypi: ['upstash-redis', 'upstash-ratelimit', 'qstash', 'upstash-workflow'],
+    sdks: ['@upstash/redis', '@upstash/ratelimit', '@upstash/qstash', '@upstash/workflow'],
+    scopes: ['@upstash/redis', '@upstash/ratelimit', '@upstash/qstash', '@upstash/workflow'],
+    envStems: ['UPSTASHREDIS', 'KVREST', 'QSTASH'],
+  },
+  browserRouting: { apiPathPrefix: '/', loaderHost: 'https://twin.upstash.io' },
+};
+
+registerPack(pack);
+
+/** A string of a `Upstash-Encoding: base64` answer as @upstash/redis decodes it: base64 to UTF-8, the bare status `OK`
+ *  excepted, which Upstash leaves raw (upstash-twin.ts, `encodeResult`). */
+const decodeResult = (v: unknown): unknown =>
+  typeof v === 'string' ? (v === 'OK' ? v : Buffer.from(v, 'base64').toString('utf8')) : Array.isArray(v) ? v.map(decodeResult) : v;
+
+/** The pack's views of its answers, for a journey step's `view` (scripts/journey-kit.ts). `decoded`: an answer to a
+ *  request sent with `Upstash-Encoding: base64`, as @upstash/redis reads it: each `result` decoded, each `error` as it is,
+ *  for a single command's `{result}` or `{error}` and for a pipeline's or transaction's list of them. */
+export const answerViews: Record<string, (body: unknown) => unknown> = {
+  decoded: (body) => {
+    const one = (item: unknown): unknown => (item !== null && typeof item === 'object' && 'result' in item ? { ...item, result: decodeResult((item as { result: unknown }).result) } : item);
+    return Array.isArray(body) ? body.map(one) : one(body);
+  },
+};

package/src/manifest.ts

@@ -0,0 +1,26 @@
+// Upstash Redis's manifest: the vendor facts Redis's command table does not carry (docs/contributing/architecture.md,
+// "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec/commands by scripts/derive-pack.ts):
+// Redis's command table, one entry per command id with its arity, dispatched by upstash-store.ts. The wire is
+// Upstash's REST envelope (upstash.com/docs/redis/features/restapi), served by the pack's own fetch
+// (upstash-server.ts over upstash-twin.ts), each form it serves cited to that page there.
+//
+// WHY NO `auth` AND NO ERROR TEMPLATE. The envelope's answers are Upstash's own: `{result}` or `{error}` with the Redis
+// error text, a 401 `{error: "WRONGPASS …"}` for a missing or wrong token, a 405 with no body for a method it does not
+// take. The pack's fetch keeps them in that order (upstash-twin.ts, `handleUpstashRedisTwinRequest`); nothing in the
+// kernel would enforce a declared `auth`, so none is declared, as psdb's manifest declares none.
+//
+// THE STATE. Keys and their values are the World's state: each key one world-store subject `key:<name>` (its kind,
+// value, deadline and a write ordinal), each cached script one subject `script:<sha1>` (upstash-store.ts, the
+// KeySpace). No command moves a declared state: a key's TTL is a deadline its reads compare with the World clock, and a
+// key's kind is fixed by the command that creates it (a command against another kind answers WRONGTYPE). So no state
+// machine is declared.
+import type { DerivedManifest } from '@volter/world-core';
+
+export const manifest = {
+  vendor: 'upstash',
+  service: 'upstash',
+  resources: {
+    Key: { storedAs: 'key', idPrefix: 'key' },
+    Script: { storedAs: 'script', idPrefix: 'script' },
+  },
+} satisfies Pick<DerivedManifest, 'vendor' | 'service' | 'resources'>;