@volter/twin-planetscale 0.1.0

package/src/index.ts

@@ -0,0 +1,267 @@
+// @volter/twin-planetscale — the PlanetScale psdb HTTP-API twin, built on the shared @volter/world-core
+// kernel. PlanetScale's serverless driver does not speak MySQL's binary protocol: it speaks
+// `psdb.v1alpha1.Database`, a Connect RPC service addressed with unary JSON POSTs
+// (`/psdb.v1alpha1.Database/CreateSession`, `/Execute`, `/CloseSession`) under HTTP Basic auth,
+// with results packed as protojson `QueryResult` — base64 row bytes plus per-column byte lengths,
+// `-1` for NULL, and every zero-valued field OMITTED.
+//
+// Behind that protocol is a REAL DATABASE: a stateful MySQL-subset engine with schemas
+// (CREATE/DROP/TRUNCATE TABLE, SHOW TABLES, DESCRIBE), DML (INSERT/SELECT/UPDATE/DELETE with WHERE,
+// ORDER BY, LIMIT/OFFSET, COUNT(*), ON DUPLICATE KEY UPDATE), MySQL's own errno/sqlstate errors
+// (1146 no-such-table, 1062 duplicate entry, 1048 not-null, 1064 parse error, 1054 unknown column),
+// AUTO_INCREMENT that survives deletes, NULL three-valued logic, and REAL TRANSACTIONS — so the
+// unmodified client's `conn.transaction(async (tx) => …)`, which is nothing but BEGIN/…/COMMIT over
+// the same session, genuinely commits or rolls back.
+//
+// THE HONEST CARVE-OUTS: a twin cannot make a wall clock pass or run a storage engine. `NOW()`
+// and the other clock functions read the World clock's instant for the statement;
+// `RAND()` and `UUID()` are REFUSED rather than frozen to a constant
+// (the serve path must be a pure function of (request, stored state)); real elapsed query `timing`
+// is never emitted; real Vitess sharding/resharding and MySQL's storage-engine physics are todos.
+// PlanetScale's branches are modelled: a password acts on its own branch, `main` is the World's one
+// image and every other branch a scope of its own (planetscale-store.ts, "BRANCH SCOPES"), and the
+// `api` lane deploys a branch's schema changes into its base (api/src/semantics/deploy-requests.ts).
+// The twin's limit: every database's `main` shares the one image. See README ## Coverage.
+//
+// State lives ENTIRELY in the kernel action log (no side-store): every table and every row is one
+// kernel subject, so a restart against the same root answers the same `SELECT`.
+export {
+  handlePlanetscaleTwinRequest,
+  planetscaleTwinSnapshot,
+  extractBasicCredential,
+  PSDB_SERVICE,
+  PSDB_METHODS,
+  PLANETSCALE_UNAUTHENTICATED,
+  PLANETSCALE_RESOURCE_TYPES,
+} from './planetscale-twin.ts';
+export type { PlanetscaleRequest, PlanetscaleResponse, PlanetscaleTwinSnapshot } from './planetscale-twin.ts';
+
+// The SQL core — exported so a caller (or a reviewer) can drive MySQL semantics in-process,
+// without HTTP. `runSql` over an image is the whole engine; nothing about the protocol is required
+// to exercise it.
+export {
+  runSql,
+  execStatement,
+  parseStatement,
+  tokenize,
+  evalExpr,
+  likeMatch,
+  emptyDatabase,
+  findTable,
+  tableRows,
+  tableKey,
+  nextRowId,
+  vitessTypeFor,
+  fieldForColumn,
+  isNumericVitessType,
+  unsupported,
+  parseError,
+  SqlError,
+  PLANETSCALE_LIMITS,
+  VITESS_TYPES,
+  BINARY_CHARSET,
+  UTF8MB4_CHARSET,
+  FLAG_NOT_NULL,
+  FLAG_PRI_KEY,
+  FLAG_UNIQUE_KEY,
+  FLAG_UNSIGNED,
+  FLAG_BINARY,
+  FLAG_AUTO_INCREMENT,
+} from './planetscale-sql.ts';
+export type { Cell, ColumnDef, Database, Expr, Field, QueryOutcome, RowRec, Statement, TableDef, VitessType, Write } from './planetscale-sql.ts';
+
+// The wire codec. Exported because faithful row packing is a headline claim of this pack and a
+// consumer (or a reviewer) must be able to decode a served response without the SDK.
+export {
+  packRow,
+  unpackRow,
+  packBytes,
+  encodeCell,
+  encodeField,
+  encodeQueryResult,
+  makeSession,
+  sessionIdOf,
+} from './planetscale-wire.ts';
+export type { WireField, WireRow, WireQueryResult, WireError, WireSession, WireExecuteResponse, WireCreateSessionResponse } from './planetscale-wire.ts';
+
+// The kernel binding — the projection and the session/transaction book.
+export {
+  SERVICE,
+  DEFAULT_BRANCH,
+  DEFAULT_DATABASE,
+  loadState,
+  readDatabase,
+  executeSql,
+  createSession,
+  closeSession,
+  mintSessionId,
+  applyWritesToImage,
+} from './planetscale-store.ts';
+export type { ExecuteContext, ExecuteResult, SessionState, PlanetscaleResourceType } from './planetscale-store.ts';
+
+export { createPlanetscaleTwinFetch, createPlanetscaleTwinServer } from './planetscale-server.ts';
+export { createPlanetscaleMysqlStream, createPlanetscaleTwinStream } from './planetscale-mysql.ts';
+export type { PlanetscaleServerOptions, PlanetscaleTwinFetchOptions } from './planetscale-server.ts';
+
+export {
+  mapTable,
+  mapRow,
+  mapDescribeRow,
+  encodeCellValue,
+  quoteSqlLiteral,
+  quoteIdent,
+  pollTimestamp,
+  pullPlanetscaleTables,
+  pullPlanetscaleDatabase,
+  pullPlanetscaleSnapshot,
+  type PlanetscalePullReport,
+  type PlanetscaleRefreshReport,
+  syncPlanetscaleFromReal,
+  syncPlanetscaleFromRemote,
+  performPlanetscaleAction,
+  pushPlanetscaleAction,
+  pushPlanetscaleActions,
+} from './planetscale-connector.ts';
+export type { PlanetscaleLikeClient, PlanetscaleRealTable, PlanetscaleExecutedQuery, PlanetscalePullOptions } from './planetscale-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 plus `guardPlanetscaleClient`, the choke point the connector entrypoints apply
+// unconditionally. There is deliberately no export that disables the guard.
+export {
+  PLANETSCALE_BUDGETED_METHODS,
+  PLANETSCALE_BUDGET_CEILING,
+  PLANETSCALE_BUDGET_MAX_RETRY_AFTER_S,
+  PLANETSCALE_BUDGET_WINDOW_MS,
+  PLANETSCALE_CALL_WEIGHTS,
+  PLANETSCALE_RATE_BUDGET,
+  PlanetscaleBudget,
+  PlanetscaleBudgetError,
+  planetscaleBudgetPath,
+  planetscaleCallWeight,
+  planetscaleClientBudget,
+  guardPlanetscaleClient,
+} from './planetscale-budget.ts';
+export type {
+  PlanetscaleBudgetErrorKind,
+  PlanetscaleBudgetOptions,
+  PlanetscaleBudgetReservation,
+  PlanetscaleBudgetSnapshot,
+  PlanetscaleBudgetedOptions,
+} from './planetscale-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performPlanetscaleAction, syncPlanetscaleFromRemote } from './planetscale-connector.ts';
+import { PLANETSCALE_RATE_BUDGET as RATE_BUDGET } from './planetscale-budget.ts';
+export const pack: TwinPack = {
+  protocol: '2',
+  stateSystem: { perform: performPlanetscaleAction, refresh: syncPlanetscaleFromRemote },
+  refresh: { onDemand: { atMost: '60s' } },
+  roundTrip: [
+    { method: 'POST', path: '/psdb.v1alpha1.Database/Execute', headers: { authorization: 'Basic dHdpbjp0d2lu' }, body: { query: 'CREATE TABLE IF NOT EXISTS round_trip (id BIGINT PRIMARY KEY AUTO_INCREMENT, body VARCHAR(255))' } },
+    { method: 'POST', path: '/psdb.v1alpha1.Database/Execute', headers: { authorization: 'Basic dHdpbjp0d2lu' }, body: { query: "INSERT INTO round_trip (body) VALUES ('round trip')" } },
+  ],
+  parityOrigin: 'http://twin',
+
+  // The SAME object planetscale-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: 'planetscale',
+  transport: 'rest',
+  nativeTransport: { protocol: 'mysql', flag: '--mysql', upstreamEnv: 'PLANETSCALE_TWIN_URL' },
+  endpointEnv: {
+    name: 'PLANETSCALE_TWIN_URL',
+    templates: { PLANETSCALE_DATABASE_URL: 'http://twin:twin@${host}:${port}' },
+    note: 'the @planetscale/database client reads PLANETSCALE_DATABASE_URL and honours http:; the injector also redirects *.psdb.cloud.',
+  },
+  // PRISMA — dub's `new PrismaClient({ omit })` names no adapter; on Prisma's client-engine
+  // build (the tab's, and the edge client's) that refuses to construct. The injector supplies
+  // this adapter, from the application's own `@prisma/adapter-planetscale`, over the endpoint
+  // template's PLANETSCALE_DATABASE_URL, which `@planetscale/database` honours as http:.
+  prismaAdapter: { adapter: '@prisma/adapter-planetscale', export: 'PrismaPlanetScale', urlEnv: 'PLANETSCALE_DATABASE_URL' },
+  archetype: 'crud',
+  bin: 'world-planetscale',
+  resources: ['table', 'row', '_session', '_backup'],
+  // ADOPTION — declared HERE, not in world-runtime's central SDK_TWINS / ENV_STEM_VENDORS tables
+  // (adding-a-twin.md §3; declaring a fact in both homes THROWS). `@planetscale/database` is the
+  // only official client of this API surface. `PLANETSCALE` is the credential-env stem: dub reads
+  // `PLANETSCALE_DATABASE_URL` (apps/web/lib/planetscale/connection.ts) — the exact var whose
+  // DATABASE_URL shape made `volter-world init` bin this vendor as generic infra and report the
+  // repo fully covered while a real call escaped (volter-ai/twin#255).
+  adoption: {
+    // No Python client for the psdb HTTP data API - `@planetscale/database` is JS-only, and Python
+    // callers reach PlanetScale over the MySQL wire protocol (a generic driver, not a vendor client).
+    pypi: [],
+    sdks: ['@planetscale/database'],
+    envStems: ['PLANETSCALE'],
+  },
+  // INTERCEPTION — the SDK addresses ONE host: whatever `config.host` resolves to from the
+  // connection URL (dist/index.js's constructor takes `url.hostname`, then `buildURL` rebuilds the
+  // request against it). PlanetScale's psdb data plane lives on per-region subdomains of
+  // `psdb.cloud` — `aws.connect.psdb.cloud`, `gcp.connect.psdb.cloud`, `<region>.connect.psdb.cloud`
+  // — so a SUFFIX matcher is required; an exact host would miss every region but one.
+  //
+  // `api.planetscale.com` is the MANAGEMENT API, the pack's `api` lane (api/src/, derived from PlanetScale's own
+  // Swagger document): the pack claims its /v1/organizations tree, where the lane serves databases, a branch's
+  // passwords and backups, and service tokens, and answers PlanetScale's 404 for every other operation; the host's
+  // other paths are unclaimed.
+  // app.planetscale.com's sign-in and service tokens page are screens the lane serves (api/src/screens/).
+  hosts: [{ suffix: '.psdb.cloud' }, { host: 'api.planetscale.com', pathPattern: '^/v1/organizations(/|$)' }, { host: 'app.planetscale.com', pathPattern: '^/(sign-in|[^/]+/settings/service-tokens)(/|$)' }],
+  // No endpoint env, and none INVENTED. `@planetscale/database` reads no environment variable of
+  // its own — `connect({url})` takes the URL from the application, which chooses the var name
+  // (dub's is PLANETSCALE_DATABASE_URL, Vercel's template uses DATABASE_URL). Interception here is
+  // the injector's, via the `hosts` suffix above, so an app-read endpoint var is not needed;
+  // emitting one anyway would let `covers` report coverage for an app that reads a different name.
+  pullPosture: 'on-demand',
+  pullPostureReason:
+    'PlanetScale meters ROWS READ rather than requests, so a scheduled full-table pull is unbounded in cost by '
+    + 'construction: one SELECT can read millions of billable rows. Pull it explicitly when someone asks, '
+    + 'through the guarded connector and its mandatory row limit.',
+  specSource:
+    'the installed @planetscale/database@1.20.1 package source (npm pack: dist/index.js, dist/cast.js, '
+    + 'dist/sanitization.js, dist/text.js, dist/index.d.ts) as the authoritative wire contract + its own test '
+    + 'fixtures for the error envelopes + github.com/mattrobenolt/ps-http-sim (the simulator upstream dub devs '
+    + 'run) and the psdb.v1alpha1 Connect service it implements + '
+    + 'planetscale.com/docs/reference/planetscale-system-limits for the published scalar limits; see '
+    + 'spec-sources.json.',
+  description:
+    "PlanetScale psdb HTTP-API twin — a real stateful MySQL-subset database (DDL, INSERT/SELECT/UPDATE/DELETE, "
+    + 'WHERE/ORDER BY/LIMIT, COUNT(*), ON DUPLICATE KEY UPDATE, AUTO_INCREMENT, NULL three-valued logic, real '
+    + "BEGIN/COMMIT/ROLLBACK transactions, MySQL errno/sqlstate errors) served over PlanetScale's Connect-JSON "
+    + 'wire protocol: POST /psdb.v1alpha1.Database/{CreateSession,Execute,CloseSession}, HTTP Basic auth, '
+    + 'protojson QueryResult with base64 row packing and -1 NULL lengths, query errors at HTTP 200 in the '
+    + '{error:{code,message}} envelope and auth failures at 401 in the same one. Non-deterministic SQL (NOW, '
+    + 'RAND, UUID) is refused, never frozen. Kernel-backed.',
+  browserRouting: { apiPathPrefix: '/psdb.v1alpha1.Database/', loaderHost: 'https://aws.connect.psdb.cloud' },
+};
+
+registerPack(pack);
+
+/**
+ * How a journey reads an answer of this pack (a step's `view`, scripts/behavior-journey.ts). `rows` decodes an Execute
+ * answer into what MySQL's client prints for it: `fields`, the result's column names in order; `rows`, each row as an
+ * array of its cells as text (MySQL's text protocol spelling: numbers as their digits, NULL as null), in the order the
+ * answer holds them; `rowsAffected` and `insertId` as numbers where psdb answers them (0 when it omits them, as its
+ * protojson does for a zero); and `error`, `{code, message}`, when the statement was refused. Cells are the packed bytes
+ * decoded as UTF-8.
+ */
+export const answerViews: Record<string, (body: unknown) => unknown> = {
+  rows: (body) => {
+    const b = (body ?? {}) as { result?: { fields?: Array<{ name?: string }>; rows?: Array<{ lengths?: string[]; values?: string }>; rowsAffected?: string; insertId?: string }; error?: { code?: string; message?: string } };
+    if (b.error) return { error: b.error };
+    const r = b.result ?? {};
+    const rows = (r.rows ?? []).map((row) => {
+      const bytes = Uint8Array.from(atob(row.values ?? ''), (c) => c.charCodeAt(0));
+      let at = 0;
+      return (row.lengths ?? []).map((size) => {
+        const width = Number(size);
+        if (width < 0) return null;
+        const cell = new TextDecoder().decode(bytes.subarray(at, at + width));
+        at += width;
+        return cell;
+      });
+    });
+    return { fields: (r.fields ?? []).map((f) => f.name ?? ''), rows, rowsAffected: Number(r.rowsAffected ?? 0), insertId: Number(r.insertId ?? 0) };
+  },
+};

package/src/manifest.ts

@@ -0,0 +1,60 @@
+// PlanetScale's psdb manifest: the vendor facts its published proto does not carry (docs/contributing/architecture.md,
+// "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec/proto by scripts/derive-pack.ts):
+// the Connect service psdb.v1alpha1.Database, five RPCs, all `action`. The psdb wire has no REST resources: tables and
+// rows are world-store subjects owned by planetscale-store.ts, and every MySQL semantic lives in planetscale-sql.ts.
+//
+// WHY NO `auth` AND NO `crossCutting`. psdb answers in two envelopes. A transport error (an unknown method, a malformed
+// body) is Connect's flat `{code, message}` with a lowercase code, declared as `error` below. A query error is HTTP 200
+// `{session, error:{code, message}}`, and an auth failure is HTTP 401 in that same `{session, error}` envelope (the
+// literal fixture of @planetscale/database's own suite; planetscale-twin.ts's header). Read-only is decided per
+// statement: a write on a read-only twin is MySQL's errno 1290 inside a 200 `{session, error}`, while a SELECT is
+// answered. The kernel's `crossCutting` refuses auth through the manifest's one error template and read-only per
+// operation, so it cannot state either rule; the psdb handlers (semantics/psdb.ts) keep auth, the per-statement
+// read-only rule and the malformed-body check, in today's order and with today's bodies, and the pack's fetch is served
+// without `around`. `auth` is not declared, since nothing would enforce it: psdb reads `Authorization: Basic
+// base64(username:password)`, any branch password (planetscale-twin.ts, `extractBasicCredential`).
+import type { DerivedManifest, StateField } from '@volter/world-core';
+
+// ps-http-sim, the simulator PlanetScale's driver authors publish for local development: its CloseSession handler
+// closes the session's connection when the request names one (`closeConn(mysqlConnKey{…})`) and answers the session
+// reset, whatever the connection's state.
+const PS_HTTP_SIM = 'https://github.com/mattrobenolt/ps-http-sim/blob/main/main.go';
+
+/** A session's `closed`. CreateSession opens one (the initial state); CloseSession closes an open one, discarding any
+ *  uncommitted transaction as a dropped connection does. Closing one already closed moves nothing and answers 200, as
+ *  ps-http-sim answers every close. Not moves of a session, and the twin's decisions where nothing shows the vendor's:
+ *  a CloseSession naming a session the twin never issued answers 200 and writes nothing; an Execute naming a closed
+ *  session runs in a new session the twin opens for it (planetscale-store.ts, `executeSqlUnlocked`), as an Execute
+ *  naming none does (ps-http-sim: "if !clientSession { sess = session.New(…) }"). */
+const sessionClosed: StateField = {
+  initial: false,
+  transitions: [
+    { operation: 'CloseSession', from: ['false'], to: 'true', source: PS_HTTP_SIM },
+    { operation: 'CloseSession', from: ['true'], source: PS_HTTP_SIM },
+  ],
+};
+
+export const manifest: DerivedManifest = {
+  vendor: 'planetscale',
+  service: 'planetscale',
+  // the driver always sends JSON (`Content-Type: application/json`, @planetscale/database dist/index.js `postJSON`)
+  body: { json: 'always' },
+  // the store mints a session `tws-<n>-<the World instant in ms>` (planetscale-store.ts, `mintSessionId`), stored as
+  // subject `session:<id>`; the core mints none (it owns no operation), so the template names the counted part only
+  ids: { template: '{prefix}-{n}' },
+  time: 'iso',
+  // Connect's transport-level error body: a lowercase code and a message, no wrapper
+  error: { code: '{code}', message: '{message}' },
+  // a whole-operation refusal of a write to a read-only twin; the psdb handlers refuse per statement (errno 1290 in a
+  // 200 `{session, error}`) and never reach this
+  readOnly: { status: 403, code: 'permission_denied', message: 'twin is read-only; omit readOnly to accept writes' },
+  malformedBody: { status: 400, code: 'invalid_argument', message: 'malformed JSON request body' },
+  // Connect's not_found; psdb addresses nothing by id in a path, so no operation answers it
+  notFound: { status: 404, code: 'not_found', message: 'not found' },
+  // psdb has no list operation: an Execute's rows are its QueryResult. Required by the type; nothing reads it.
+  list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  deleted: {},
+  resources: {
+    Session: { storedAs: '_session', idPrefix: 'tws', state: { closed: sessionClosed } },
+  },
+};