@volter/twin-upstash 0.1.0 → 0.1.1

package/README.md

@@ -30,7 +30,8 @@ silent no-op.
 
 ## `EVAL` runs a Lua interpreter
 
-`upstash-lua.ts` is a tokenizer, parser and evaluator for the Lua subset real Redis scripts use.
+The kernel's Redis library (`@volter/world-core/redis`, `lua.ts`; this pack's `upstash-lua.ts` names its command
+API `redis`) is a tokenizer, parser and evaluator for the Lua subset real Redis scripts use.
 It was a deliberate choice over the cheaper alternative — recognising known script SHA1s and
 dispatching to hand-written TypeScript — because recognition is a fake-success generator: it passes
 for the exact bytes it memorised and silently mis-answers anything one character different, and the

package/dist/qstash/src/doors.js

@@ -17,7 +17,7 @@ export async function door(ctx, request, report) {
             return Response.json({ error: 'to is required' }, { status: 400 });
         const deliveries = ctx.rowsRaw(DELIVERY).filter((d) => d.to === to)
             .sort((a, b) => String(a.at).localeCompare(String(b.at)) || Number(a.n) - Number(b.n))
-            .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, method: d.method, headers: d.headers, body: d.body, status: d.status }));
+            .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, ...(d.sent_at !== undefined ? { sentAt: d.sent_at } : {}), method: d.method, headers: d.headers, body: d.body, status: d.status }));
         return Response.json({ to, deliveries });
     }
     if (request.method === 'POST' && path === '/_twin/destinations') {

package/dist/qstash/src/doors.ts

@@ -5,7 +5,7 @@
 // `POST /_twin/recipients/:domain`).
 //
 // - GET /_twin/deliveries?to=<url> → {to, deliveries}: every request QStash made to that URL, oldest first, each as the
-//   endpoint received it (its method, headers and body) and the status it answered.
+//   endpoint received it (its method, headers and body), when it fell due (`at`) and was sent (`sentAt`), and the status it answered.
 // - POST /_twin/destinations {url, status, body?, headers?, when?} → 204: the World's word on how the endpoints under a URL
 //   answer, and, with `when` (header names and values), how they answer a delivery carrying those headers (a workflow's
 //   route answers its failure call, `Upstash-Workflow-Is-Failure: true`, apart from its steps). The statement that names
@@ -36,7 +36,7 @@ export async function door(ctx: SemanticsContext, request: Request, report: Catc
     if (!to) return Response.json({ error: 'to is required' }, { status: 400 });
     const deliveries = ctx.rowsRaw(DELIVERY).filter((d) => d.to === to)
       .sort((a, b) => String(a.at).localeCompare(String(b.at)) || Number(a.n) - Number(b.n))
-      .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, method: d.method, headers: d.headers, body: d.body, status: d.status }));
+      .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, ...(d.sent_at !== undefined ? { sentAt: d.sent_at } : {}), method: d.method, headers: d.headers, body: d.body, status: d.status }));
     return Response.json({ to, deliveries });
   }
   if (request.method === 'POST' && path === '/_twin/destinations') {

package/dist/qstash/src/fetch.js

@@ -2,7 +2,7 @@
 // World's doors and the lane's gate in front, and the catch-up before all of them. The upstash pack's fetch
 // (../../src/upstash-server.ts) sends it every request for a QStash host, every `/v2/` path (an application reaches QStash
 // at its QSTASH_URL, the pack's own address) and the lane's doors.
-import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext } from '@volter/world-core';
+import { bindSemantics, coreFor, worldNow, createDerivedFetch, crossCutting, semanticsContext } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest, spanning } from "./manifest.js";
 import { door, DOOR } from "./doors.js";
@@ -33,7 +33,7 @@ export function createQstashLaneFetch(options = {}) {
         if (!options.readOnly && !catchingUp.has(key)) {
             catchingUp.add(key);
             try {
-                report = await catchUp(ctx);
+                report = await catchUp(ctx, () => Date.parse((options.clock ?? worldNow)()));
             }
             finally {
                 catchingUp.delete(key);

package/dist/qstash/src/fetch.ts

@@ -2,7 +2,7 @@
 // World's doors and the lane's gate in front, and the catch-up before all of them. The upstash pack's fetch
 // (../../src/upstash-server.ts) sends it every request for a QStash host, every `/v2/` path (an application reaches QStash
 // at its QSTASH_URL, the pack's own address) and the lane's doors.
-import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
+import { bindSemantics, coreFor, worldNow, createDerivedFetch, crossCutting, semanticsContext, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest, spanning } from './manifest.ts';
 import { door, DOOR } from './doors.ts';
@@ -36,7 +36,7 @@ export function createQstashLaneFetch(options: QstashLaneOptions = {}): DerivedF
     let report: CatchUpReport = { delivered: [], retried: [], failed: [] };
     if (!options.readOnly && !catchingUp.has(key)) {
       catchingUp.add(key);
-      try { report = await catchUp(ctx); } finally { catchingUp.delete(key); }
+      try { report = await catchUp(ctx, () => Date.parse((options.clock ?? worldNow)())); } finally { catchingUp.delete(key); }
     }
     const own = await door(ctx, request, report);
     if (own) return own;

package/dist/qstash/src/semantics/delivery.d.ts

@@ -14,4 +14,4 @@ export type CatchUpReport = {
     failed: Row[];
 };
 /** Run everything due by the World's instant, in order, each at its own moment. */
-export declare function catchUp(ctx: SemanticsContext): Promise<CatchUpReport>;
+export declare function catchUp(ctx: SemanticsContext, live?: () => number): Promise<CatchUpReport>;

package/dist/qstash/src/semantics/delivery.js

@@ -119,7 +119,7 @@ function eligible(ctx, m, all) {
     }
     return true;
 }
-function nextDue(ctx, until) {
+function nextDue(ctx, until, live) {
     const due = [];
     for (const s of ctx.rowsRaw('Schedule')) {
         if (typeof s.nextScheduleTime === 'number' && s.nextScheduleTime <= until)
@@ -138,7 +138,7 @@ function nextDue(ctx, until) {
         if (m.state === 'CANCEL_REQUESTED')
             due.push({ when, order: 2 + Number(m._ordinal) / 1e9, act: (at) => cancelled(at, m) });
         else if (eligible(ctx, m, all))
-            due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report) });
+            due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report, live) });
     }
     for (const resource of ['DLQMessage', 'WorkflowDLQMessage']) {
         for (const e of ctx.rowsRaw(resource)) {
@@ -150,14 +150,14 @@ function nextDue(ctx, until) {
     return due.sort((a, b) => a.when - b.when || a.order - b.order)[0];
 }
 /** Run everything due by the World's instant, in order, each at its own moment. */
-export async function catchUp(ctx) {
+export async function catchUp(ctx, live = () => nowMs(ctx)) {
     const until = nowMs(ctx);
     const report = { delivered: [], retried: [], failed: [] };
     // a message held behind another (the one before it in its queue or its run) goes once that one has left, so the World
     // clock never runs back: each move happens at its own due time or at the last move's, whichever is later
     let last = 0;
     for (let n = 0; n < 5000; n += 1) {
-        const next = nextDue(ctx, until);
+        const next = nextDue(ctx, until, live);
         if (!next)
             break;
         last = Math.max(last, next.when);
@@ -198,9 +198,14 @@ async function move(ctx, m, to, actor, fields) {
     await ctx.write('Message', String(m.id), { ...fields, state: to }, `message.${to.toLowerCase()}`);
     m.state = to;
 }
-/** One delivery attempt of a message, at the moment it is due. */
-async function attempt(ctx, m, report) {
+/** One delivery attempt of a message, at the moment it is due. Its signature is issued when it is sent — the World
+ *  clock as the post leaves (`live`), never before the due time: QStash signs a request when it sends it, and a
+ *  delivery the World makes late (its clock moved past the due time) reaches an application already living at that
+ *  instant, which refuses a token that expired while it waited (dub walk 4: every workflow step after a clock shift
+ *  answered "signature verification failed"). A long catch-up on a running clock signs each post at its own instant. */
+async function attempt(ctx, m, report, live) {
     const when = nowMs(ctx);
+    const sentAt = Math.max(when, live());
     const tried = Number(m._attempts ?? 0);
     await move(ctx, m, 'ACTIVE', 'time', { _attempts: tried });
     const published = (m._published ?? {});
@@ -214,11 +219,11 @@ async function attempt(ctx, m, report) {
     const key = accountOf(ctx, String(m._owner ?? 'world')).current;
     const headers = {
         ...base, 'upstash-message-id': String(m.messageId), 'upstash-retried': String(tried),
-        'upstash-signature': sign(body, url, Math.floor(when / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
+        'upstash-signature': sign(body, url, Math.floor(sentAt / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
     };
     const method = String(m.method ?? 'POST');
     const outcome = stated(ctx, url, headers) ?? await post(url, method, headers, body);
-    await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
+    await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, sent_at: iso(sentAt), n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
     const n = tried + 1;
     const response = { _response_status: outcome.status, _response_body: outcome.body, _response_headers: outcome.headers };
     if (outcome.status >= 200 && outcome.status < 300) {

package/dist/qstash/src/semantics/delivery.ts

@@ -125,7 +125,7 @@ export type CatchUpReport = { delivered: Row[]; retried: Row[]; failed: Row[] };
 
 type Due = { when: number; order: number; act: (at: SemanticsContext, report: CatchUpReport) => Promise<void> };
 
-function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
+function nextDue(ctx: SemanticsContext, until: number, live: () => number): Due | undefined {
   const due: Due[] = [];
   for (const s of ctx.rowsRaw('Schedule')) {
     if (typeof s.nextScheduleTime === 'number' && s.nextScheduleTime <= until) due.push({ when: s.nextScheduleTime, order: 0, act: (at) => fire(at, s) });
@@ -139,7 +139,7 @@ function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
     const when = Number(m._due);
     if (when > until) continue;
     if (m.state === 'CANCEL_REQUESTED') due.push({ when, order: 2 + Number(m._ordinal) / 1e9, act: (at) => cancelled(at, m) });
-    else if (eligible(ctx, m, all)) due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report) });
+    else if (eligible(ctx, m, all)) due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report, live) });
   }
   for (const resource of ['DLQMessage', 'WorkflowDLQMessage']) {
     for (const e of ctx.rowsRaw(resource)) {
@@ -151,14 +151,14 @@ function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
 }
 
 /** Run everything due by the World's instant, in order, each at its own moment. */
-export async function catchUp(ctx: SemanticsContext): Promise<CatchUpReport> {
+export async function catchUp(ctx: SemanticsContext, live: () => number = () => nowMs(ctx)): Promise<CatchUpReport> {
   const until = nowMs(ctx);
   const report: CatchUpReport = { delivered: [], retried: [], failed: [] };
   // a message held behind another (the one before it in its queue or its run) goes once that one has left, so the World
   // clock never runs back: each move happens at its own due time or at the last move's, whichever is later
   let last = 0;
   for (let n = 0; n < 5000; n += 1) {
-    const next = nextDue(ctx, until);
+    const next = nextDue(ctx, until, live);
     if (!next) break;
     last = Math.max(last, next.when);
     await next.act(await ctx.at(iso(last)), report);
@@ -197,9 +197,14 @@ async function move(ctx: SemanticsContext, m: Row, to: string, actor: 'time' | '
   m.state = to;
 }
 
-/** One delivery attempt of a message, at the moment it is due. */
-async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport): Promise<void> {
+/** One delivery attempt of a message, at the moment it is due. Its signature is issued when it is sent — the World
+ *  clock as the post leaves (`live`), never before the due time: QStash signs a request when it sends it, and a
+ *  delivery the World makes late (its clock moved past the due time) reaches an application already living at that
+ *  instant, which refuses a token that expired while it waited (dub walk 4: every workflow step after a clock shift
+ *  answered "signature verification failed"). A long catch-up on a running clock signs each post at its own instant. */
+async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport, live: () => number): Promise<void> {
   const when = nowMs(ctx);
+  const sentAt = Math.max(when, live());
   const tried = Number(m._attempts ?? 0);
   await move(ctx, m, 'ACTIVE', 'time', { _attempts: tried });
   const published = (m._published ?? {}) as Record<string, string>;
@@ -213,11 +218,11 @@ async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport): Pr
   const key = accountOf(ctx, String(m._owner ?? 'world')).current;
   const headers: Record<string, string> = {
     ...base, 'upstash-message-id': String(m.messageId), 'upstash-retried': String(tried),
-    'upstash-signature': sign(body, url, Math.floor(when / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
+    'upstash-signature': sign(body, url, Math.floor(sentAt / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
   };
   const method = String(m.method ?? 'POST');
   const outcome = stated(ctx, url, headers) ?? await post(url, method, headers, body);
-  await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
+  await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, sent_at: iso(sentAt), n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
   const n = tried + 1;
   const response = { _response_status: outcome.status, _response_body: outcome.body, _response_headers: outcome.headers };
   if (outcome.status >= 200 && outcome.status < 300) {

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

@@ -1,140 +1,8 @@
-/** A Lua runtime/parse error. Surfaces to the caller as a Redis script error, never as a result. */
-export declare class LuaError extends Error {
-    constructor(message: string);
-}
-/** A Lua table. Array part + hash part, exactly like the real thing (1-based array indices). */
-export declare class LuaTable {
-    readonly map: Map<string | number | boolean, LuaValue>;
-    get(k: LuaValue): LuaValue;
-    set(k: LuaValue, v: LuaValue): void;
-    /** A non-nil value at a non-nil key. */
-    private store;
-    /** `#t` — the border of the array part: the largest n where t[1..n] are all non-nil. */
-    get length(): number;
-    static fromArray(values: LuaValue[]): LuaTable;
-    toArray(): LuaValue[];
-}
-export type LuaFunction = (args: LuaValue[]) => LuaValue[];
-/** `null` stands for Lua `nil` (JS `undefined` is never used as a value in this interpreter). */
-export type LuaValue = null | boolean | number | string | LuaTable | LuaFunction;
-type TokKind = 'name' | 'number' | 'string' | 'op' | 'keyword' | 'eof';
-type Token = {
-    kind: TokKind;
-    value: string;
-    line: number;
-};
-export declare function tokenize(src: string): Token[];
-type Expr = {
-    t: 'nil';
-} | {
-    t: 'true';
-} | {
-    t: 'false';
-} | {
-    t: 'num';
-    v: number;
-} | {
-    t: 'str';
-    v: string;
-} | {
-    t: 'name';
-    v: string;
-} | {
-    t: 'index';
-    obj: Expr;
-    key: Expr;
-} | {
-    t: 'call';
-    fn: Expr;
-    args: Expr[];
-    line?: number;
-} | {
-    t: 'bin';
-    op: string;
-    l: Expr;
-    r: Expr;
-} | {
-    t: 'un';
-    op: string;
-    e: Expr;
-} | {
-    t: 'table';
-    array: Expr[];
-    pairs: Array<{
-        k: Expr;
-        v: Expr;
-    }>;
-} | {
-    t: 'func';
-    params: string[];
-    body: Stat[];
-};
-type Stat = {
-    t: 'local';
-    names: string[];
-    exprs: Expr[];
-} | {
-    t: 'assign';
-    targets: Expr[];
-    exprs: Expr[];
-} | {
-    t: 'callstat';
-    call: Expr;
-} | {
-    t: 'if';
-    branches: Array<{
-        cond: Expr;
-        body: Stat[];
-    }>;
-    orelse: Stat[] | null;
-} | {
-    t: 'while';
-    cond: Expr;
-    body: Stat[];
-} | {
-    t: 'repeat';
-    body: Stat[];
-    cond: Expr;
-} | {
-    t: 'fornum';
-    name: string;
-    from: Expr;
-    to: Expr;
-    step: Expr | null;
-    body: Stat[];
-} | {
-    t: 'forin';
-    names: string[];
-    exprs: Expr[];
-    body: Stat[];
-} | {
-    t: 'do';
-    body: Stat[];
-} | {
-    t: 'return';
-    exprs: Expr[];
-} | {
-    t: 'break';
-};
-/** Parse Lua source into a chunk. Exported so a test can prove a bad script fails at PARSE time. */
-export declare function parseLua(src: string): Stat[];
-export declare function luaTruthy(v: LuaValue): boolean;
-export declare function luaTypeName(v: LuaValue): string;
-/** Lua 5.1's `%.14g` number formatting — `3` prints as "3", not "3.0". */
-export declare function numberToLuaString(n: number): string;
-/** `tonumber`, exactly: a number passes through, a numeric string converts, anything else is nil. */
-export declare function luaToNumber(v: LuaValue, base?: number): LuaValue;
-/** What the host must supply: a synchronous `redis.call`, plus KEYS/ARGV. */
-export type LuaHost = {
-    /** Run one Redis command, called from the script's line `line`. MUST throw to abort the script the way `redis.call` does. */
-    call: (args: string[], line: number) => LuaValue;
-    keys: string[];
-    argv: string[];
-};
-/** Lua `==`: same type required (no string/number coercion); tables compare by identity. */
-export declare function luaEquals(l: LuaValue, r: LuaValue): boolean;
-/** Parse + run a script. Returns the Lua value the chunk returned (or `nil`). */
-export declare function runLua(script: string, host: LuaHost): LuaValue;
-/** The SHA1 real Redis keys the script cache by — the same hex digest `SCRIPT LOAD` returns. */
-export declare function luaScriptSha1(script: string): string;
-export {};
+import { type LuaHost, type LuaValue } from '@volter/world-core/redis';
+export { LuaError, LuaTable, luaEquals, luaScriptSha1, luaToNumber, luaTruthy, luaTypeName, numberToLuaString, parseLua, tokenize, } from '@volter/world-core/redis';
+export type { LuaFunction, LuaHost, LuaValue } from '@volter/world-core/redis';
+type Globals = Parameters<NonNullable<LuaHost['extend']>>[0];
+/** The command API under the names Redis's scripts call it by. */
+export declare function nameCommandApi(g: Globals): void;
+/** Parse + run a script with the command API named: the kernel's `runLua`. */
+export declare function runLua(script: string, host: Omit<LuaHost, 'numberArg'> & Partial<Pick<LuaHost, 'numberArg'>>): LuaValue;