@volter/twin-planetscale 0.1.0

package/dist/src/planetscale-row.js

@@ -0,0 +1,39 @@
+// Shared row identity and SQL quoting for local execution, observation and deployment.
+import { PULLED_ROWID_BASE, tableKey } from "./planetscale-sql.js";
+export function pulledRowId(table, identity, ordinal = 0) {
+    // JSON tuple encoding distinguishes embedded separators and duplicate keyless rows.
+    let h = 0x811c9dc5;
+    const text = JSON.stringify([tableKey(table), identity, ordinal]);
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return PULLED_ROWID_BASE + h;
+}
+export function keyedRowIdentity(table, cells) {
+    const keys = Object.keys(cells);
+    const identity = table.primaryKey.map(k => k.toLowerCase()).sort().map(k => JSON.stringify([k, cells[keys.find(n => n.toLowerCase() === k) ?? k] ?? null]));
+    return identity;
+}
+export function quoteSqlLiteral(value) {
+    if (value === null)
+        return 'NULL';
+    const escaped = value.replace(/[\0\b\n\r\t\x1a\\"']/g, (c) => {
+        switch (c) {
+            case '"': return '\\"';
+            case "'": return "\\'";
+            case '\n': return '\\n';
+            case '\r': return '\\r';
+            case '\t': return '\\t';
+            case '\\': return '\\\\';
+            case '\0': return '\\0';
+            case '\b': return '\\b';
+            default: return '\\Z';
+        }
+    });
+    return `'${escaped}'`;
+}
+export const quoteIdent = (name) => `\`${name.replace(/`/g, '``')}\``;
+export function keyedRowId(table, cells) {
+    return pulledRowId(table.name, keyedRowIdentity(table, cells));
+}

package/dist/src/planetscale-server.d.ts

@@ -0,0 +1,42 @@
+import { DEFAULT_BRANCH, DEFAULT_DATABASE } from './planetscale-store.js';
+import { type DerivedFetch } from '@volter/world-core';
+export type PlanetscaleServerOptions = {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    /** The username the twin demands. Omit to accept any non-empty username. */
+    username?: string;
+    /** The password the twin demands. Omit to accept any non-empty password (still 401s a missing one). */
+    password?: string;
+    /** The schema name the twin presents. */
+    database?: string;
+    /** The branch name `CreateSession` reports. */
+    branch?: string;
+    /** The injected clock. Returns the ISO instant this request "happens at". */
+    now?: () => string;
+};
+/** Options every planetscale-twin HTTP surface needs, independent of who owns the socket. */
+export interface PlanetscaleTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    /** The username the twin demands. Omit to accept any non-empty username. */
+    username?: string;
+    /** The password the twin demands. Omit to accept any non-empty password (still 401s a missing one). */
+    password?: string;
+    /** The schema name the twin presents. */
+    database?: string;
+    /** The branch name `CreateSession` reports. */
+    branch?: string;
+    /** The injected clock. Returns the ISO instant this request "happens at". */
+    now?: () => string;
+}
+/** The pack's wire (docs/contributing/architecture.md, "Protocol 3"): the twin's doors in front, the management API and
+ *  app.planetscale.com's pages to the `api` lane, and the derived dispatch over psdb's proto: CreateSession, Execute,
+ *  CloseSession and Prepare reach their handlers (semantics/psdb.ts), and everything else is the gap (psdbGap). No
+ *  `around`: manifest.ts says why. */
+export declare function createPlanetscaleTwinFetch(options?: PlanetscaleTwinFetchOptions): DerivedFetch;
+export declare function createPlanetscaleTwinServer(options?: PlanetscaleServerOptions): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+export { DEFAULT_BRANCH, DEFAULT_DATABASE };

package/dist/src/planetscale-server.js

@@ -0,0 +1,137 @@
+// planetscale twin HTTP server — serve the psdb wire twin over HTTP so the real
+// `@planetscale/database` client, pointed at it with nothing but its own public `url`/`host`
+// option, works UNMODIFIED.
+//
+// ── THE ONE THING AN INTEGRATOR MUST KNOW ─────────────────────────────────────────────────────
+// The client forces `https:` for every scheme except a literal `http:` (dist/index.js `protocol`),
+// so a local twin is reachable by passing `url: 'http://user:pass@127.0.0.1:PORT'` — that is
+// CONFIGURATION through the client's own public option, not a modification. `PLANETSCALE_DATABASE_URL`
+// (what dub reads) takes exactly that shape.
+//
+// ── THE INJECTED CLOCK ────────────────────────────────────────────────────────────────────────
+// `now` produces the `occurredAt` the kernel stamps each action with. It defaults to the wall clock
+// (a server has to), but a test passes its own so a run is reproducible. Nothing in a SERVED
+// response is derived from it except the kernel's own action ordinals — the response body is a pure
+// function of (request, stored state), which is why `timing` is never emitted.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createPlanetscaleTwinFetch` and
+// the SERVER is one line of `serveHttp` around it. The fetch is the derived dispatch over psdb's
+// proto (`createDerivedFetch`), with the pack's earlier fetch as its `legacy`: psdb replies carry
+// ONLY the handler's own headers (no default `content-type` is added), and the clock is injectable
+// per instance.
+import { serveHttp } from '@volter/world-core';
+import { createPlanetscaleApiLaneFetch } from "../api/src/fetch.js";
+import { PSDB_METHODS, PSDB_SERVICE } from "./planetscale-twin.js";
+import { psdbHandlers, psdbInternal } from "./semantics/psdb.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { DEFAULT_BRANCH, DEFAULT_DATABASE, STORE_NAMES, planetscaleStore } from "./planetscale-store.js";
+import { createDerivedFetch, worldNow, statefulTwinManifest } from '@volter/world-core';
+/** The twin's own doors, in front of the vendor's dispatch (docs/contributing/architecture.md, "Doors, screens and the
+ *  gap"): `GET /twin`, the discovery manifest, and `GET /twin/store/<tables|rows>`, the store door. Undefined for any
+ *  other request. */
+function twinDoors(request, options) {
+    if (request.method !== 'GET')
+        return undefined;
+    const cleanPath = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+    if (cleanPath === '/twin')
+        return discovery();
+    // THE STORE DOOR: `GET /twin/store/<tables|rows>` — this pack's own named, read-only,
+    // deterministic projection over stored state. The psdb wire is Connect-JSON and unary
+    // Connect is POST-ONLY, so even `Execute` (the vendor's read) is a POST. Nothing in the vendor
+    // surface can observe stored state with a GET, which is what this door is for — and it is what
+    // makes the pack's determinism checkable at the resource level (R9). Twin surface, not vendor
+    // surface: keyless.
+    if (cleanPath.startsWith('/twin/store/'))
+        return storeDoor(cleanPath.slice('/twin/store/'.length), options);
+    return undefined;
+}
+/** `GET /twin`. The manifest EDUCATES: it names the store door beside the others, so a caller who only ever sees
+ *  `GET /twin` can find the one GET read this POST-only protocol has. */
+function discovery() {
+    const manifest = statefulTwinManifest({
+        vendor: 'planetscale',
+        twinOf: 'PlanetScale (psdb.v1alpha1.Database HTTP wire protocol)',
+        stores: 'a real MySQL-subset schema and its rows, served over the psdb Connect-JSON envelope',
+    });
+    return Response.json({
+        ...manifest,
+        stores: STORE_NAMES,
+        doors: { ...manifest.doors, store: 'GET /twin/store/<name>' },
+    });
+}
+/** `GET /twin/store/<tables|rows>`, the store door. */
+function storeDoor(name, options) {
+    if (!STORE_NAMES.includes(name)) {
+        return Response.json({ error: 'unknown store', store: name, stores: STORE_NAMES }, { status: 404 });
+    }
+    return Response.json(planetscaleStore(name, options.root, options.database ?? DEFAULT_DATABASE));
+}
+/**
+ * The gap: Connect's own answer for a request psdb does not serve. A path outside the service is `not_found` naming the
+ * service it asked for; a method the twin does not model is `unimplemented`, as Connect answers a method a service lacks;
+ * a psdb method asked with a verb other than POST is refused, since unary Connect is POST-only. StreamExecute is the gap:
+ * @planetscale/database never calls it (its dist/index.js sends only CreateSession and Execute) though ps-http-sim, the
+ * simulator PlanetScale's driver authors publish, serves it as a server stream of ExecuteResponse.
+ */
+function psdbGap(request) {
+    const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+    const prefix = `/${PSDB_SERVICE}/`;
+    const json = (status, code, message) => Response.json({ code, message }, { status });
+    if (!path.startsWith(prefix))
+        return json(404, 'not_found', `unknown service: ${path.replace(/^\//, '').split('/')[0] ?? ''}`);
+    const method = path.slice(prefix.length);
+    if (request.method.toUpperCase() !== 'POST' && PSDB_METHODS.includes(method)) {
+        return json(405, 'unimplemented', `HTTP ${request.method.toUpperCase()} is not supported by this protocol`);
+    }
+    return json(404, 'unimplemented', `${PSDB_SERVICE}/${method} is not implemented`);
+}
+/** app.planetscale.com's pages the `api` lane serves (its sign-in, the service tokens settings and a deploy request's
+ *  page), and the World's door
+ *  that gives a person their PlanetScale password. */
+const SETTINGS_PAGE = /^\/(?:sign-in|_twin\/users\/[^/]+\/password|[^/]+\/settings\/service-tokens(?:\/.*)?|[^/]+\/[^/]+\/deploy-requests\/\d+(?:\/review)?)$/;
+/** The pack's wire (docs/contributing/architecture.md, "Protocol 3"): the twin's doors in front, the management API and
+ *  app.planetscale.com's pages to the `api` lane, and the derived dispatch over psdb's proto: CreateSession, Execute,
+ *  CloseSession and Prepare reach their handlers (semantics/psdb.ts), and everything else is the gap (psdbGap). No
+ *  `around`: manifest.ts says why. */
+export function createPlanetscaleTwinFetch(options = {}) {
+    const now = options.now ?? (() => worldNow());
+    const psdb = createDerivedFetch({
+        surface: surface,
+        handlers: psdbHandlers(options, now),
+        gap: (request) => psdbGap(request),
+    });
+    // api.planetscale.com's management API is the pack's `api` lane (../api/src/fetch.ts)
+    const api = createPlanetscaleApiLaneFetch({ ...(options.root !== undefined ? { root: options.root } : {}), readOnly: options.readOnly ?? false, clock: now });
+    return Object.assign(async (request) => {
+        const door = twinDoors(request, options);
+        if (door)
+            return door;
+        const path = new URL(request.url).pathname;
+        if (path === '/v1/organizations' || path.startsWith('/v1/organizations/') || SETTINGS_PAGE.test(path)) {
+            try {
+                return await api(request);
+            }
+            catch (error) {
+                return psdbInternal(error);
+            }
+        }
+        // a move the World clock makes happens when any request next arrives (a deploy finishing changes the branch psdb
+        // reads), so the management lane catches up before psdb answers
+        try {
+            await api.catchUp(request);
+        }
+        catch (error) {
+            return psdbInternal(error);
+        }
+        return psdb(request);
+    }, { owners: () => psdb.owners() });
+}
+export async function createPlanetscaleTwinServer(options = {}) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createPlanetscaleTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+export { DEFAULT_BRANCH, DEFAULT_DATABASE };