mppx 0.17.0 → 0.17.3

package/dist/Store.js

@@ -52,6 +52,28 @@ function isReplayMarker(value) {
         'type' in value &&
         value.type === 'mppx:replay');
 }
+/**
+ * Runs `fn` on the stored value and commits its change with `swap`, a
+ * compare-and-swap. When another writer won, retries from the value `swap`
+ * returned (or a fresh read) after a jittered backoff.
+ */
+async function compareAndSwap(parameters) {
+    const { fn, key, label, maxAttempts, read, swap } = parameters;
+    let raw = await read();
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const change = fn(raw == null ? null : Json.parse(raw));
+        if (change.op === 'noop')
+            return change.result;
+        const swapped = await swap(raw, change.op === 'set' ? Json.stringify(change.value) : null);
+        if (swapped.applied)
+            return change.result;
+        if (attempt + 1 === maxAttempts)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.random() * Math.min(2 ** (attempt + 1), 200)));
+        raw = swapped.current !== undefined ? swapped.current : await read();
+    }
+    throw new Error(`${label} update of "${key}" conflicted ${maxAttempts} times.`);
+}
 const keyPrefixCache = new WeakMap();
 export function from(store, options) {
     return withKeyPrefix(store, options?.keyPrefix);
@@ -126,6 +148,342 @@ export function cloudflare(kv, options) {
         ...wrapJsonUpdate(kv.update),
     }, options);
 }
+/**
+ * Atomic store backed by Cloudflare Durable Objects.
+ *
+ * Each key lives in its own Durable Object instance (`idFromName(key)`), so
+ * reads and writes of one key are linearizable across every Worker isolate and
+ * location, while different keys (such as different payment channels) scale
+ * out across instances. {@link AtomicStore.update} runs `fn` in the Worker and
+ * commits with a compare-and-swap in the object. When another writer changed
+ * the key in between, the swap returns the stored value and the update retries
+ * from it after a jittered backoff; {@link AtomicStore.tryClaim} runs in a single
+ * object call.
+ *
+ * Bind {@link DurableObjectStore} as a SQLite-backed Durable Object and pass
+ * its namespace.
+ *
+ * @example
+ * ```ts
+ * import { Store } from 'mppx/server'
+ *
+ * export class MppxStore extends Store.DurableObjectStore {}
+ *
+ * export default {
+ *   fetch(request: Request, env: Env) {
+ *     const store = Store.durableObject(env.MPPX_STORE)
+ *     // ...
+ *   },
+ * }
+ * ```
+ */
+export function durableObject(namespace, options) {
+    const maxAttempts = options?.maxAttempts ?? 32;
+    async function call(key, body) {
+        const stub = namespace.get(namespace.idFromName(key));
+        const response = await stub.fetch('https://mppx-store/', {
+            body: JSON.stringify(body),
+            headers: { 'content-type': 'application/json' },
+            method: 'POST',
+        });
+        if (!response.ok)
+            throw new Error(`Durable Object store request failed (${response.status}): ${await response.text()}`);
+        return (await response.json());
+    }
+    return from({
+        async get(key) {
+            const raw = await call(key, { op: 'get', key });
+            if (raw == null)
+                return null;
+            return Json.parse(raw);
+        },
+        async put(key, value) {
+            await call(key, { op: 'put', key, value: Json.stringify(value) });
+        },
+        async delete(key) {
+            await call(key, { op: 'delete', key });
+        },
+        update(key, fn) {
+            return compareAndSwap({
+                fn,
+                key,
+                label: 'Durable Object store',
+                maxAttempts,
+                read: () => call(key, { op: 'get', key }),
+                swap: (expected, value) => call(key, { op: 'swap', key, expected, value }),
+            });
+        },
+        async tryClaim(key, expires) {
+            if (!Number.isFinite(expires) || expires <= Date.now())
+                return false;
+            return call(key, { op: 'claim', key, expires });
+        },
+    }, options);
+}
+/**
+ * Durable Object class that holds the values of {@link durableObject}.
+ *
+ * Export a subclass of it from your Worker and bind it in
+ * `wrangler.jsonc` with a `new_sqlite_classes` migration. It needs no
+ * `cloudflare:workers` import, so it bundles anywhere.
+ *
+ * @example
+ * ```jsonc
+ * {
+ *   "durable_objects": { "bindings": [{ "name": "MPPX_STORE", "class_name": "MppxStore" }] },
+ *   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MppxStore"] }]
+ * }
+ * ```
+ */
+export class DurableObjectStore {
+    #storage;
+    constructor(state, _env) {
+        this.#storage = state.storage;
+    }
+    /** Handles one store operation. Each runs without awaiting other I/O between its read and write, so the object's input gate makes it atomic. */
+    async fetch(request) {
+        if (request.method !== 'POST')
+            return new Response('Method not allowed', { status: 405 });
+        const body = (await request.json());
+        const storage = this.#storage;
+        const read = async () => (await storage.get(body.key)) ?? null;
+        const write = async (value) => {
+            if (value === null)
+                await storage.delete(body.key);
+            else
+                await storage.put(body.key, value);
+        };
+        switch (body.op) {
+            case 'get':
+                return Response.json(await read());
+            case 'put':
+                await write(body.value);
+                return Response.json(true);
+            case 'delete':
+                await write(null);
+                return Response.json(true);
+            case 'swap': {
+                const current = await read();
+                if (current !== body.expected)
+                    return Response.json({ applied: false, current });
+                await write(body.value);
+                return Response.json({ applied: true });
+            }
+            case 'claim': {
+                const { expires } = body;
+                if (!Number.isFinite(expires) || expires <= Date.now())
+                    return Response.json(false);
+                const raw = await read();
+                const current = raw == null ? null : Json.parse(raw);
+                if (current !== null && (!isReplayMarker(current) || current.expires > Date.now()))
+                    return Response.json(false);
+                await write(Json.stringify({ expires, type: 'mppx:replay' }));
+                return Response.json(true);
+            }
+            default:
+                return new Response('Unknown operation', { status: 400 });
+        }
+    }
+}
+/**
+ * Atomic store backed by a SQL database: Postgres, SQLite or Cloudflare D1.
+ *
+ * Values live as JSON text in one table (`mppx_store` by default, created on
+ * first use). Every write is a single statement, and {@link AtomicStore.update}
+ * commits with a compare-and-swap on the stored value
+ * (`UPDATE … WHERE key = ? AND value = ? RETURNING`, or
+ * `INSERT … ON CONFLICT DO NOTHING RETURNING` for a new key), retrying from the
+ * current value after a jittered backoff when another writer won. It needs no
+ * interactive transactions, so it works over HTTP drivers and D1, and only
+ * `ON CONFLICT` and `RETURNING` (Postgres, SQLite 3.35+, D1, libSQL).
+ *
+ * Use {@link postgres}, {@link sqlite} or {@link d1} for common drivers, or pass
+ * any driver as a `query` function.
+ *
+ * @example
+ * ```ts
+ * import postgres from 'postgres'
+ * import { Store } from 'mppx/server'
+ *
+ * const db = postgres(process.env.DATABASE_URL!)
+ * const store = Store.sql({ dialect: 'postgres', query: (text, params) => db.unsafe(text, params) })
+ * ```
+ */
+export function sql(driver, options) {
+    const table = options?.table ?? 'mppx_store';
+    if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(table))
+        throw new Error(`Invalid SQL store table name: "${table}".`);
+    const maxAttempts = options?.maxAttempts ?? 32;
+    // Statements are written with `?`; Postgres numbers its placeholders.
+    const prepare = (text) => {
+        if (driver.dialect !== 'postgres')
+            return text;
+        let index = 0;
+        return text.replace(/\?/g, () => `$${++index}`);
+    };
+    let ready;
+    const ensureTable = () => {
+        if (options?.createTable === false)
+            return;
+        ready ??= Promise.resolve(driver.query(
+        // `expires` mirrors a replay marker's expiry, so a claim needs no JSON in SQL.
+        `CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires DOUBLE PRECISION)`, [])).then(() => { }, async (error) => {
+            // Concurrent `CREATE TABLE IF NOT EXISTS` from other processes can fail on
+            // Postgres (duplicate catalog row) although the table now exists: probe it.
+            const exists = await Promise.resolve(driver.query(`SELECT 1 FROM ${table} WHERE 1 = 0`, [])).then(() => true, () => false);
+            if (exists)
+                return;
+            ready = undefined;
+            throw error;
+        });
+        return ready;
+    };
+    async function query(text, params) {
+        await ensureTable();
+        return driver.query(prepare(text), params);
+    }
+    async function read(key) {
+        const [row] = await query(`SELECT value FROM ${table} WHERE key = ?`, [key]);
+        return row ? row.value : null;
+    }
+    /** The `expires` column for a serialized value: the expiry of a replay marker, else null. */
+    const expiresOf = (raw) => {
+        const value = Json.parse(raw);
+        return isReplayMarker(value) ? value.expires : null;
+    };
+    /** Writes `value` (or deletes, for `null`) only if the key still holds `expected`. */
+    async function swap(key, expected, value) {
+        let rows;
+        if (expected === null) {
+            if (value === null)
+                return { applied: true };
+            rows = await query(`INSERT INTO ${table} (key, value, expires) VALUES (?, ?, ?) ON CONFLICT (key) DO NOTHING RETURNING key`, [key, value, expiresOf(value)]);
+        }
+        else if (value === null)
+            rows = await query(`DELETE FROM ${table} WHERE key = ? AND value = ? RETURNING key`, [
+                key,
+                expected,
+            ]);
+        else
+            rows = await query(`UPDATE ${table} SET value = ?, expires = ? WHERE key = ? AND value = ? RETURNING key`, [value, expiresOf(value), key, expected]);
+        return { applied: rows.length > 0 };
+    }
+    return from({
+        async get(key) {
+            const raw = await read(key);
+            if (raw == null)
+                return null;
+            return Json.parse(raw);
+        },
+        async put(key, value) {
+            const raw = Json.stringify(value);
+            await query(`INSERT INTO ${table} (key, value, expires) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires = excluded.expires`, [key, raw, expiresOf(raw)]);
+        },
+        async delete(key) {
+            await query(`DELETE FROM ${table} WHERE key = ?`, [key]);
+        },
+        update(key, fn) {
+            return compareAndSwap({
+                fn,
+                key,
+                label: 'SQL store',
+                maxAttempts,
+                read: () => read(key),
+                swap: (expected, value) => swap(key, expected, value),
+            });
+        },
+        // One statement: insert the marker, or replace one whose expiry has passed.
+        async tryClaim(key, expires) {
+            if (!Number.isFinite(expires) || expires <= Date.now())
+                return false;
+            const rows = await query(`INSERT INTO ${table} AS existing (key, value, expires) VALUES (?, ?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires = excluded.expires WHERE existing.expires IS NOT NULL AND existing.expires <= ? RETURNING key`, [
+                key,
+                Json.stringify({ expires, type: 'mppx:replay' }),
+                expires,
+                Date.now(),
+            ]);
+            // The claim's own expiry may have passed while the statement ran.
+            return rows.length > 0 && expires > Date.now();
+        },
+    }, options);
+}
+/**
+ * Atomic SQL store on a Postgres client: `pg` (`Pool` or `Client`),
+ * `@neondatabase/serverless` (`Pool` or `neon()`), `@vercel/postgres`,
+ * Supabase's Postgres connection or PGlite. See {@link sql}.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg'
+ * import { Store } from 'mppx/server'
+ *
+ * const store = Store.postgres(new Pool({ connectionString: process.env.DATABASE_URL }))
+ * ```
+ */
+export function postgres(client, options) {
+    return sql({
+        dialect: 'postgres',
+        async query(text, params) {
+            const result = await client.query(text, params);
+            return Array.isArray(result) ? result : result.rows;
+        },
+    }, options);
+}
+/**
+ * Atomic SQL store on a SQLite database: `node:sqlite` (`DatabaseSync`),
+ * `better-sqlite3` or `bun:sqlite`. See {@link sql}. For libSQL or Turso, use
+ * {@link sql} with dialect `sqlite` and return the result set's rows:
+ * `Store.sql({ dialect: 'sqlite', query: async (sql, args) => (await client.execute({ sql, args: args as InArgs })).rows })`.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseSync } from 'node:sqlite'
+ * import { Store } from 'mppx/server'
+ *
+ * const store = Store.sqlite(new DatabaseSync('mppx.db'))
+ * ```
+ */
+export function sqlite(database, options) {
+    return sql({
+        dialect: 'sqlite',
+        async query(text, params) {
+            const statement = database.prepare(text);
+            // better-sqlite3 allows all() only on statements that return rows.
+            if (statement.reader === false && statement.run) {
+                await statement.run(...params);
+                return [];
+            }
+            return (await statement.all(...params));
+        },
+    }, options);
+}
+/**
+ * Atomic SQL store on a Cloudflare D1 database binding. See {@link sql}.
+ *
+ * @example
+ * ```ts
+ * import { Store } from 'mppx/server'
+ *
+ * export default {
+ *   fetch(request: Request, env: { DB: D1Database }) {
+ *     const store = Store.d1(env.DB)
+ *     // ...
+ *   },
+ * }
+ * ```
+ */
+export function d1(database, options) {
+    return sql({
+        dialect: 'sqlite',
+        async query(text, params) {
+            const { results } = await database
+                .prepare(text)
+                .bind(...params)
+                .all();
+            return results;
+        },
+    }, options);
+}
 /** In-memory store backed by a `Map`. JSON-roundtrips values to match production behavior. */
 export function memory(options) {
     const store = new Map();