@worker-protocol/cloudflare 0.0.0-stage → 0.7.0

package/dist/schema.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Migrations for the tables a piece keeps in a Durable Object, applied object by object.
+ *
+ * **Why `CREATE TABLE IF NOT EXISTS` was not enough.** It creates a table and never changes one: a
+ * column or an index added in a later release would reach the objects created after it and none of
+ * the thousands created before. A Worker with an object per vehicle has every one of those to bring
+ * forward, each on its own, the first time it is reached after a deploy.
+ *
+ * **One journal, `wp_schema`, a row per piece.** Each piece names itself and lists every step its
+ * schema has ever taken, in order; the journal records how many an object has applied, and
+ * `migrate` applies the rest. Pieces are independent because the mixins are: an object that carries
+ * only an outbox migrates only the outbox. A domain may keep its own tables in the same journal
+ * under names of its own, so one object has one record of what shape it is in.
+ *
+ * **A step, once published, is never edited** — an object that already applied it will not apply it
+ * again — and a change is a new step at the end. The first step of each piece in this package
+ * creates its tables `IF NOT EXISTS`, so that an object created before the journal existed adopts
+ * the tables it already has.
+ *
+ * This is not an ORM and does not want to be one. The tables are a few, the queries are plain, and a
+ * query builder imposed by a library would be a version every Worker that installs it has to agree
+ * with — a Worker that wants Drizzle or Kysely for its own tables uses them, beside these.
+ */
+/** One piece's schema: its name in the journal, and every step it has taken, oldest first. */
+export type Schema = {
+    /** Unique within an object. This package's pieces are `worker-protocol.<piece>`. */
+    piece: string;
+    /** Each step is the statements that take the schema one version forward. */
+    steps: string[][];
+};
+/**
+ * Brings this object's tables for `schema` up to its latest step, and answers the `sql` to use.
+ *
+ * Called at the start of every method rather than once in a constructor, because an object that
+ * empties itself with `deleteAll()` keeps running in the same instance, and a table created only at
+ * construction would be missing on the next call. An object already at the latest step costs one
+ * read of the journal.
+ *
+ * The steps still owed are applied in one transaction with the journal's new version, so a step that
+ * fails leaves the object exactly where it was. An object ahead of `schema` — written by a later
+ * release than the one now running — is refused rather than read: running older code over a newer
+ * shape is a rollback, and a rollback is not a migration.
+ */
+export declare function migrate(storage: DurableObjectStorage, schema: Schema): SqlStorage;

package/dist/schema.js

@@ -0,0 +1,64 @@
+/**
+ * Migrations for the tables a piece keeps in a Durable Object, applied object by object.
+ *
+ * **Why `CREATE TABLE IF NOT EXISTS` was not enough.** It creates a table and never changes one: a
+ * column or an index added in a later release would reach the objects created after it and none of
+ * the thousands created before. A Worker with an object per vehicle has every one of those to bring
+ * forward, each on its own, the first time it is reached after a deploy.
+ *
+ * **One journal, `wp_schema`, a row per piece.** Each piece names itself and lists every step its
+ * schema has ever taken, in order; the journal records how many an object has applied, and
+ * `migrate` applies the rest. Pieces are independent because the mixins are: an object that carries
+ * only an outbox migrates only the outbox. A domain may keep its own tables in the same journal
+ * under names of its own, so one object has one record of what shape it is in.
+ *
+ * **A step, once published, is never edited** — an object that already applied it will not apply it
+ * again — and a change is a new step at the end. The first step of each piece in this package
+ * creates its tables `IF NOT EXISTS`, so that an object created before the journal existed adopts
+ * the tables it already has.
+ *
+ * This is not an ORM and does not want to be one. The tables are a few, the queries are plain, and a
+ * query builder imposed by a library would be a version every Worker that installs it has to agree
+ * with — a Worker that wants Drizzle or Kysely for its own tables uses them, beside these.
+ */
+const JOURNAL = `CREATE TABLE IF NOT EXISTS wp_schema (
+  piece TEXT PRIMARY KEY,
+  version INTEGER NOT NULL
+)`;
+/**
+ * Brings this object's tables for `schema` up to its latest step, and answers the `sql` to use.
+ *
+ * Called at the start of every method rather than once in a constructor, because an object that
+ * empties itself with `deleteAll()` keeps running in the same instance, and a table created only at
+ * construction would be missing on the next call. An object already at the latest step costs one
+ * read of the journal.
+ *
+ * The steps still owed are applied in one transaction with the journal's new version, so a step that
+ * fails leaves the object exactly where it was. An object ahead of `schema` — written by a later
+ * release than the one now running — is refused rather than read: running older code over a newer
+ * shape is a rollback, and a rollback is not a migration.
+ */
+export function migrate(storage, schema) {
+    const sql = storage.sql;
+    sql.exec(JOURNAL);
+    const held = sql
+        .exec("SELECT version FROM wp_schema WHERE piece = ?", schema.piece)
+        .toArray()[0];
+    const at = held?.version ?? 0;
+    const latest = schema.steps.length;
+    if (at === latest)
+        return sql;
+    if (at > latest) {
+        throw new Error(`${schema.piece} is at version ${at} in this object, and this code knows ${latest}: ` +
+            "the object was written by a later release.");
+    }
+    storage.transactionSync(() => {
+        for (const step of schema.steps.slice(at)) {
+            for (const statement of step)
+                sql.exec(statement);
+        }
+        sql.exec(`INSERT INTO wp_schema (piece, version) VALUES (?, ?)
+         ON CONFLICT (piece) DO UPDATE SET version = excluded.version`, schema.piece, latest);
+    });
+    return sql;
+}

package/dist/subscriptions.d.ts

@@ -0,0 +1,23 @@
+import type { SubscriptionStore } from "@worker-protocol/hono";
+import { type DurableObjectClass, type Mixed, type Rpc } from "./durable.ts";
+/** What `withSubscriptions` adds to a Durable Object. Every subscription crosses as JSON. */
+export interface SubscriptionMethods {
+    findSubscription(key: string): string | null;
+    ensureSubscription(key: string, candidate: string): {
+        record: string;
+        created: boolean;
+    };
+    getSubscription(id: string): string | null;
+    subscriptionsOf(caller: string | null): string[];
+    subscriptionsFor(type: string): string[];
+    updateSubscription(id: string, change: {
+        set: string;
+        clear: string[];
+    }): void;
+    removeSubscription(id: string): void;
+}
+export declare function withSubscriptions<B extends DurableObjectClass>(Base: B): Mixed<B, SubscriptionMethods>;
+/** What `durableSubscriptions` needs of a stub: the methods `withSubscriptions` adds, over RPC. */
+export type SubscriptionsRpc = Rpc<SubscriptionMethods>;
+/** `subscriptions.store` for `mount()` and `eventHub()`, over the object with `withSubscriptions`. */
+export declare const durableSubscriptions: (stub: SubscriptionsRpc) => SubscriptionStore;

package/dist/subscriptions.js

@@ -0,0 +1,121 @@
+import { first } from "./durable.js";
+import { migrate } from "./schema.js";
+/**
+ * SUB-7's store, in the one Durable Object that holds a Worker's subscriptions.
+ *
+ * **One object, never one per shard.** SUB-7 has two requests for the same thing find one
+ * subscription, which only a single consistent store can promise — so a Worker that keeps an object
+ * per vehicle keeps its subscriptions in the one object it has for the whole fleet, and puts this
+ * mixin there and nowhere else.
+ *
+ * SQL, because every publish asks for the live subscriptions naming a type (SUB-13) and every list
+ * for one caller's (SUB-8), and both are filters. Each method is synchronous between its first
+ * statement and its last, so nothing interleaves inside one — which is what `ensureSubscription`
+ * needs, as `beginOutcome` does.
+ *
+ * **A subscription crosses the RPC boundary as JSON.** Its filters nest by definition, and a stub's
+ * types are a conditional mapping that exceeds the compiler's instantiation depth on a recursive
+ * type. `durableSubscriptions` does the parsing, so a Worker never sees the strings.
+ */
+/** `migrate` applies these; a new step goes at the end, and a published one is never edited. */
+const SCHEMA = {
+    piece: "worker-protocol.subscriptions",
+    steps: [
+        // 1. The tables as first released, `IF NOT EXISTS` so an object that already has them adopts them.
+        [
+            // The subscription itself is `record`. `key`, `caller` and `ended` are copied out of it only
+            // because a query filters on them; nothing reads them back.
+            `CREATE TABLE IF NOT EXISTS wp_subscription (
+        id TEXT PRIMARY KEY,
+        key TEXT NOT NULL,
+        caller TEXT,
+        ended INTEGER NOT NULL,
+        record TEXT NOT NULL
+      )`,
+            "CREATE INDEX IF NOT EXISTS wp_subscription_key ON wp_subscription (key)",
+        ],
+    ],
+};
+export function withSubscriptions(Base) {
+    class WithSubscriptions extends Base {
+        findSubscription(key) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            const row = first(sql.exec("SELECT record FROM wp_subscription WHERE key = ? AND ended = 0 LIMIT 1", key));
+            return row?.record ?? null;
+        }
+        /** SUB-7, SUB-15: the live one under `key`, or the candidate. An ended one stays, listed. */
+        ensureSubscription(key, candidate) {
+            const held = this.findSubscription(key);
+            if (held !== null)
+                return { record: held, created: false };
+            const one = JSON.parse(candidate);
+            migrate(this.ctx.storage, SCHEMA).exec("INSERT INTO wp_subscription (id, key, caller, ended, record) VALUES (?, ?, ?, 0, ?)", one.id, key, one.caller, candidate);
+            return { record: candidate, created: true };
+        }
+        getSubscription(id) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            const row = first(sql.exec("SELECT record FROM wp_subscription WHERE id = ?", id));
+            return row?.record ?? null;
+        }
+        /** SUB-8: one caller's, ended ones included. `IS` because a caller may be `null`. */
+        subscriptionsOf(caller) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            return sql
+                .exec("SELECT record FROM wp_subscription WHERE caller IS ?", caller)
+                .toArray()
+                .map((row) => row.record);
+        }
+        /** SUB-13: the live ones naming this type. The filters are the hub's to apply. */
+        subscriptionsFor(type) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            return sql
+                .exec(`SELECT record FROM wp_subscription
+            WHERE ended = 0
+              AND EXISTS (SELECT 1 FROM json_each(record, '$.types') WHERE value = ?)`, type)
+                .toArray()
+                .map((row) => row.record);
+        }
+        /**
+         * A patch, as two lists because JSON cannot say *cleared*: `JSON.stringify` drops a member
+         * whose value is `undefined`, which is exactly how `SubscriptionStore.update` names one to
+         * clear.
+         */
+        updateSubscription(id, change) {
+            const held = this.getSubscription(id);
+            if (held === null)
+                return;
+            const next = { ...JSON.parse(held), ...JSON.parse(change.set) };
+            for (const name of change.clear)
+                delete next[name];
+            migrate(this.ctx.storage, SCHEMA).exec("UPDATE wp_subscription SET ended = ?, record = ? WHERE id = ?", next.endedAt === undefined ? 0 : 1, JSON.stringify(next), id);
+        }
+        removeSubscription(id) {
+            const sql = migrate(this.ctx.storage, SCHEMA);
+            sql.exec("DELETE FROM wp_subscription WHERE id = ?", id);
+        }
+    }
+    return WithSubscriptions;
+}
+const parse = (record) => JSON.parse(record);
+/** `subscriptions.store` for `mount()` and `eventHub()`, over the object with `withSubscriptions`. */
+export const durableSubscriptions = (stub) => {
+    const read = (record) => (record === null ? undefined : parse(record));
+    return {
+        find: async (key) => read(await stub.findSubscription(key)),
+        ensure: async (key, candidate) => {
+            const { record, created } = await stub.ensureSubscription(key, JSON.stringify(candidate));
+            return { subscription: parse(record), created };
+        },
+        get: async (id) => read(await stub.getSubscription(id)),
+        list: async (caller) => (await stub.subscriptionsOf(caller)).map(parse),
+        forType: async (type) => (await stub.subscriptionsFor(type)).map(parse),
+        // `undefined` names a member to clear, and JSON drops it — so the cleared ones go by name.
+        update: (id, patch) => stub.updateSubscription(id, {
+            set: JSON.stringify(patch),
+            clear: Object.entries(patch)
+                .filter(([, value]) => value === undefined)
+                .map(([name]) => name),
+        }),
+        remove: (id) => stub.removeSubscription(id),
+    };
+};

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@worker-protocol/cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "workerProtocolEdition": "0.5",
+  "description": "The protocol's stores in Durable Objects, and the Queues between an outbox and a sink: mixins for ENDP-16, SUB-7, LOG-2 and an outbox, for Workers on Cloudflare",
+  "keywords": [
+    "worker-protocol",
+    "worker",
+    "cloudflare",
+    "durable-objects",
+    "queues",
+    "cloudevents",
+    "rowing-tech"
+  ],
+  "license": "Apache-2.0",
+  "author": "Rowing Tech, S.A. (https://rowing.tech)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowing-tech/worker-protocol.git",
+    "directory": "packages/cloudflare"
+  },
+  "homepage": "https://github.com/rowing-tech/worker-protocol/tree/main/packages/cloudflare#readme",
+  "bugs": "https://github.com/rowing-tech/worker-protocol/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@worker-protocol/hono": "0.7.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.7",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.22.0",
+    "@types/node": "26.5.1",
+    "hono": "4.13.7",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11",
+    "wrangler": "4.131.1",
+    "zod": "4.5.4"
+  },
+  "scripts": {
+    "typecheck": "wrangler types && tsc -p tsconfig.json",
+    "build": "wrangler types --include-env=false runtime.d.ts && tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
 }