@volter/twin-planetscale 0.1.0

package/src/planetscale-twin.ts

@@ -0,0 +1,338 @@
+// PLANETSCALE psdb TWIN — THE REQUEST HANDLER. Contract:
+//   handlePlanetscaleTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, ... })
+//     -> { status, body, headers }
+//
+// This file is the TRANSPORT half. Every MySQL semantic lives in `planetscale-sql.ts`, every kernel
+// interaction in `planetscale-store.ts`, and every byte-level encoding rule in
+// `planetscale-wire.ts`.
+//
+// ── THE PROTOCOL, AND WHY IT LOOKS LIKE THIS ──────────────────────────────────────────────────
+// PlanetScale's HTTP driver does not speak MySQL's binary protocol and it is not REST. It is a
+// Connect RPC service — `psdb.v1alpha1.Database` — addressed with unary JSON POSTs:
+//
+//   POST /psdb.v1alpha1.Database/CreateSession   {}                     -> {branch, user, session}
+//   POST /psdb.v1alpha1.Database/Execute         {query, session}       -> {session, result|error}
+//   POST /psdb.v1alpha1.Database/CloseSession    {session}              -> {session}
+//   POST /psdb.v1alpha1.Database/Prepare         …                      -> unimplemented (real!)
+//
+// with `Authorization: Basic base64(username:password)` and `User-Agent: database-js/<version>`.
+// GROUNDED in the installed `@planetscale/database@1.20.1` source (dist/index.js builds exactly
+// these two URLs and this header set) and in `github.com/mattrobenolt/ps-http-sim`, the simulator
+// upstream integrators run, whose handler implements CreateSession/Execute/StreamExecute/
+// CloseSession and answers Prepare with Connect's `unimplemented`.
+//
+// ── TWO ERROR CHANNELS, AND CONFUSING THEM BREAKS EVERY CONSUMER ──────────────────────────────
+// 1. A QUERY error (unknown table, duplicate key, parse error) is HTTP **200** carrying
+//    `{session, error:{code, message}}`. The client's `execute` sees `error` on an OK response and
+//    throws `DatabaseError(message, 400, error)` — note the **400 it synthesizes itself**, which is
+//    why serving an actual HTTP 400 here would change the status every consumer's tests assert on.
+// 2. An AUTH failure is HTTP **401** with the SAME `{session, error:{code, message}}` envelope —
+//    the client's `postJSON` looks for `parsed?.error` on a non-ok response and throws
+//    `DatabaseError` with the REAL status. This shape is not a guess: it is the literal fixture in
+//    the client's own test suite (`__tests__/index.test.ts`,
+//    `{ code: 'unauthenticated', message: 'invalid auth credentials' }` replied at 401).
+// Anything else — an unknown method, a wrong HTTP verb — takes Connect's own transport-level error
+// body `{code, message}` with a LOWERCASE code, which the client reports as `UnknownError`
+// ("Expected JSON response from database API, got HTTP …"). That is the vendor's behaviour too, and
+// it is deliberately NOT dressed up in the `{error}` envelope to look like a query failure.
+import {
+  closeSession as storeCloseSession,
+  createSession as storeCreateSession,
+  executeSql,
+  scopeOf,
+  sessionState,
+  DEFAULT_BRANCH,
+  DEFAULT_DATABASE,
+  PLANETSCALE_RESOURCE_TYPES,
+  SERVICE,
+  type ExecuteContext,
+} from './planetscale-store.ts';
+import { createHash } from 'node:crypto';
+import { parseStatement, SqlError, type Statement } from './planetscale-sql.ts';
+import { directDdlDisabled, isDdl, roleRefusal, type PasswordRole } from './planetscale-roles.ts';
+import { ownFields, transitionFor, twinResourcesOfType } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import {
+  encodeQueryResult,
+  makeSession,
+  sessionIdOf,
+  sessionVarsOf,
+  type WireCreateSessionResponse,
+  type WireExecuteResponse,
+} from './planetscale-wire.ts';
+
+export type PlanetscaleRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The password this twin demands. Omit to accept any non-empty credential (still 401s a missing
+   *  one) — the honest default for a local twin that holds no real secret. */
+  password?: string;
+  /** The username this twin demands. Omit to accept any non-empty username. */
+  username?: string;
+  /** The schema name the twin presents (`Field.database`, errno 1146). */
+  database?: string;
+  /** The branch name `CreateSession` reports. */
+  branch?: string;
+};
+
+export type PlanetscaleResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+/** The Connect service this twin serves. The path is `/<fully-qualified service>/<Method>`. */
+export const PSDB_SERVICE = 'psdb.v1alpha1.Database';
+
+/** Every method the real service declares, so an unknown one is distinguishable from a known-but-
+ *  unmodeled one — the difference between Connect's `unimplemented` and its `not_found`. */
+export const PSDB_METHODS = ['CreateSession', 'Execute', 'StreamExecute', 'CloseSession', 'Prepare'] as const;
+
+/** The literal 401 body the client's own suite fixtures. Identical for a missing, blank or wrong
+ *  credential: the vendor draws no distinction between them, so neither does this twin. */
+export const PLANETSCALE_UNAUTHENTICATED = { code: 'unauthenticated', message: 'invalid auth credentials' } as const;
+
+const JSON_HEADERS: Record<string, string> = { 'content-type': 'application/json' };
+
+/** The endpoint inventory `planetscale-conformance.ts` probes. */
+export type PlanetscaleTwinSnapshot = {
+  service: string;
+  implementedEndpoints: string[];
+  resourceTypes: readonly string[];
+};
+
+export function planetscaleTwinSnapshot(): PlanetscaleTwinSnapshot {
+  return {
+    service: PSDB_SERVICE,
+    implementedEndpoints: [
+      'POST /psdb.v1alpha1.Database/CreateSession',
+      'POST /psdb.v1alpha1.Database/Execute',
+      'POST /psdb.v1alpha1.Database/CloseSession',
+      'POST /psdb.v1alpha1.Database/Prepare (vendor-faithful unimplemented)',
+      'POST /psdb.v1alpha1.Database/StreamExecute (the gap: Connect unimplemented)',
+    ],
+    resourceTypes: PLANETSCALE_RESOURCE_TYPES,
+  };
+}
+
+function lowerHeaders(h: Record<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) out[k.toLowerCase()] = v;
+  return out;
+}
+
+/**
+ * Decode `Authorization: Basic base64(user:pass)` — the ONLY scheme this wire uses
+ * (dist/index.js `postJSON` builds it with `btoa(`${username}:${password}`)`).
+ *
+ * The password may itself contain `:` (PlanetScale passwords are `pscale_pw_…`, but a
+ * connection-URL password is arbitrary), so the split is on the FIRST colon only. Anything that is
+ * not a well-formed Basic header resolves to null and gets the vendor's 401 — a malformed header
+ * must never fall through and be treated as a bare credential.
+ */
+/** What `atob` decodes (forgiving-base64): base64 characters whose length is not 1 mod 4, with at most the padding that completes a quad. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;
+
+/** A Basic credential that is not base64: the vendor's 401, as for any malformed header. */
+function notBase64(): null {
+  return null;
+}
+
+export function extractBasicCredential(headers: Record<string, string> | undefined): { username: string; password: string } | null {
+  const raw = lowerHeaders(headers).authorization;
+  if (raw === undefined) return null;
+  const m = /^basic\s+(\S+)\s*$/i.exec(raw.trim());
+  if (m === null) return null;
+  const decoded = BASE64.test(m[1]!) ? atob(m[1]!) : notBase64();
+  if (decoded === null) return null;
+  const colon = decoded.indexOf(':');
+  if (colon < 0) return null;
+  const username = decoded.slice(0, colon);
+  const password = decoded.slice(colon + 1);
+  if (username === '' || password === '') return null;
+  return { username, password };
+}
+
+/** Connect's transport-level error body: a lowercase code and a message, with no `error` wrapper. */
+const connectError = (status: number, code: string, message: string): PlanetscaleResponse =>
+  ({ status, body: { code, message }, headers: JSON_HEADERS });
+
+const unauthenticated = (session: unknown): PlanetscaleResponse =>
+  ({ status: 401, body: { ...(session !== undefined ? { session } : {}), error: PLANETSCALE_UNAUTHENTICATED }, headers: JSON_HEADERS });
+
+export async function handlePlanetscaleTwinRequest(req: PlanetscaleRequest): Promise<PlanetscaleResponse> {
+  const path = req.path.split('?')[0]!.replace(/\/+$/, '') || '/';
+  const prefix = `/${PSDB_SERVICE}/`;
+
+  if (!path.startsWith(prefix)) return unknownService(path);
+  const method = path.slice(prefix.length);
+  if (!(PSDB_METHODS as readonly string[]).includes(method)) return unknownMethod(method);
+  // Connect unary RPCs are POST-only; a GET is refused before authentication, as Connect does.
+  if (req.method.toUpperCase() !== 'POST') return postOnly();
+
+  const credential = extractBasicCredential(req.headers);
+  if (credential === null) return unauthenticated(undefined);
+  if (req.username !== undefined && credential.username !== req.username) return unauthenticated(undefined);
+  if (req.password !== undefined && credential.password !== req.password) return unauthenticated(undefined);
+  // a password the management lane issued authenticates by its secret and acts in its role; a deleted one (or one of a
+  // deleted database) is refused like any bad credential (planetscale-roles.ts)
+  const issued = issuedPassword(req.root, credential, req.occurredAt);
+  if (issued === 'refused') return unauthenticated(undefined);
+
+  const payload = req.body === undefined || req.body.trim() === '' ? {} : payloadOf(req.body);
+  if (payload === undefined) return malformedBody();
+
+  const ctx: ExecuteContext = {
+    ...(req.root !== undefined ? { root: req.root } : {}),
+    occurredAt: req.occurredAt ?? '1970-01-01T00:00:00.000Z',
+    ...(req.readOnly !== undefined ? { readOnly: req.readOnly } : {}),
+    database: req.database ?? DEFAULT_DATABASE,
+    // a password acts on the branch it was made on (M5: "Create new credentials to access a branch's data",
+    // planetscale.com/docs/cli/password); the World's own credential acts on the branch the server was given
+    branch: issued?.branch ?? req.branch ?? DEFAULT_BRANCH,
+    ...(issued?.scope ? { scope: issued.scope } : {}),
+  };
+  const branch = ctx.branch ?? DEFAULT_BRANCH;
+
+  if (method === 'CreateSession') return createSession(ctx, credential.username, branch);
+  if (method === 'CloseSession') return closeSession(req, ctx, payload, branch);
+  if (method === 'Prepare') return prepareUnimplemented();
+  if (method === 'StreamExecute') return streamExecuteUnmodelled();
+
+  // ── Execute ────────────────────────────────────────────────────────────────────────────────
+  const query = payload.query;
+  const incoming = sessionIdOf(payload.session);
+  // the session's user variables and SQL mode ride the session the client echoes (vtgate.proto Session
+  // user_defined_variables, system_variables), as Vitess keeps them
+  const vars = sessionVarsOf(payload.session);
+  ctx.vars = vars;
+  if (typeof query !== 'string') return queryNotString();
+  try {
+    if (issued !== undefined) {
+      let stmt: Statement | undefined;
+      try { stmt = parseStatement(query); } catch { stmt = undefined; } // a statement that does not parse is refused by executeSql
+      const refused = stmt === undefined ? undefined : roleRefusal(issued.role, stmt);
+      if (refused) throw refused;
+      if (stmt !== undefined && issued.safeMigrations && isDdl(stmt)) throw directDdlDisabled();
+    }
+    const { outcome, session } = await executeSql(ctx, query, incoming);
+    const body: WireExecuteResponse = {
+      session: makeSession(session.id, { branch, inTransaction: session.inTransaction, vars: outcome.vars ?? vars }),
+      result: encodeQueryResult(outcome),
+    };
+    // `timing` is DELIBERATELY omitted: it is an elapsed-wall-clock measurement, and this repo's
+    // serve-path determinism rule forbids one. The client's own `timing ?? 0` handles its absence,
+    // so `ExecutedQuery.time` reads 0 — honestly "not measured" rather than an invented duration.
+    return { status: 200, body, headers: JSON_HEADERS };
+  } catch (error) {
+    if (!(error instanceof SqlError)) return internalFault(error);
+    // HTTP 200 — see the header. The client turns this into `DatabaseError(message, 400, error)`.
+    //
+    // The echoed session must report the transaction's REAL state. §9 round one, finding 10: this
+    // used to answer a flat `inTransaction: false`, so a statement that failed INSIDE an open
+    // transaction told the caller the transaction had ended — while the server still held the
+    // buffer and a later COMMIT still landed everything. MySQL does not end a transaction on a
+    // failed statement, and neither does this twin, so the wire must not say otherwise.
+    const open = incoming === null ? undefined : sessionState(req.root, incoming, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+    const body: WireExecuteResponse = {
+      session: makeSession(incoming ?? '', { branch, inTransaction: open?.inTransaction === true, vars }),
+      error: { code: error.code, message: error.message },
+    };
+    return { status: 200, body, headers: JSON_HEADERS };
+  }
+}
+
+const unknownService = (path: string): PlanetscaleResponse =>
+  connectError(404, 'not_found', `unknown service: ${path.replace(/^\//, '').split('/')[0] ?? ''}`);
+
+const unknownMethod = (method: string): PlanetscaleResponse =>
+  connectError(404, 'unimplemented', `${PSDB_SERVICE}/${method} is not implemented`);
+
+const postOnly = (): PlanetscaleResponse =>
+  connectError(405, 'unimplemented', 'HTTP GET is not supported by this protocol');
+
+const malformedBody = (): PlanetscaleResponse =>
+  connectError(400, 'invalid_argument', 'malformed JSON request body');
+
+const queryNotString = (): PlanetscaleResponse =>
+  connectError(400, 'invalid_argument', 'query must be a string');
+
+/** A request body as a JSON object; undefined when it is not one. */
+function payloadOf(text: string): Record<string, unknown> | undefined {
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { return undefined; }
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+}
+
+/**
+ * A fault inside the twin that is not a `SqlError`, answered as Connect's `internal` transport error. The wire must never
+ * be the crash surface (a deeply nested expression's RangeError once escaped as an HTTP 500 and the client's
+ * `UnknownError`), so the boundary that owns the protocol answers it.
+ */
+const internalFault = (error: unknown): PlanetscaleResponse =>
+  connectError(500, 'internal', `internal twin error: ${error instanceof Error ? error.message : String(error)}`);
+
+/** VENDOR-FAITHFUL: ps-http-sim answers Prepare with Connect's Unimplemented, and the client never calls it. */
+const prepareUnimplemented = (): PlanetscaleResponse =>
+  connectError(501, 'unimplemented', 'psdb.v1alpha1.Database/Prepare is not implemented');
+
+/**
+ * A TWIN GAP, stated as one: the real service implements StreamExecute; this twin does not model Connect's
+ * server-streaming envelope framing, and a unary body here would be a fabricated success.
+ */
+const streamExecuteUnmodelled = (): PlanetscaleResponse =>
+  connectError(501, 'unimplemented', 'psdb.v1alpha1.Database/StreamExecute is not modeled by this twin');
+
+/** CreateSession: a fresh session on the branch, and the user the credential names. */
+async function createSession(ctx: ExecuteContext, username: string, branch: string): Promise<PlanetscaleResponse> {
+  const state = await storeCreateSession(ctx);
+  const body: WireCreateSessionResponse = {
+    branch,
+    user: { username, psid: username },
+    session: makeSession(state.id, { branch, inTransaction: false }),
+  };
+  return { status: 200, body, headers: JSON_HEADERS };
+}
+
+/**
+ * CloseSession: a session the twin issued moves by the declared machine (manifest.ts): open → closed, or stays closed.
+ * Connect's CloseSessionResponse carries the (now closed) session; a session the twin never issued is NOT an error, as
+ * the real service tolerates it.
+ */
+async function closeSession(req: PlanetscaleRequest, ctx: ExecuteContext, payload: Record<string, unknown>, branch: string): Promise<PlanetscaleResponse> {
+  const id = sessionIdOf(payload.session);
+  const held = id === null ? undefined : sessionState(req.root, id, ctx.database ?? DEFAULT_DATABASE, ctx.scope);
+  if (held !== undefined) {
+    const { move } = transitionFor('closed', manifest.resources.Session!.state!.closed!, 'CloseSession', held.closed, undefined, id!);
+    if (move === undefined) throw new Error(`CloseSession moves a session from closed=${String(held.closed)}, which the machine does not declare`);
+  }
+  if (id !== null) await storeCloseSession(ctx, id);
+  return { status: 200, body: { session: makeSession(id ?? '', { branch, inTransaction: false }) }, headers: JSON_HEADERS };
+}
+
+/**
+ * The password a Basic credential names, when the management lane issued one with its username: its role when the secret
+ * matches and it is not deleted, `refused` otherwise. A credential no issued password names is the World's own, as every
+ * credential was before passwords were issued, and acts as admin: an application pointed at the World (Dub) carries
+ * whatever credential its own configuration holds. That rule is the twin's decision.
+ */
+function issuedPassword(root: string | undefined, credential: { username: string; password: string }, occurredAt?: string): { role: PasswordRole; branch: string; scope?: string; safeMigrations: boolean } | 'refused' | undefined {
+  const row = twinResourcesOfType(SERVICE, '_password', root).map((r) => ownFields(r) as Record<string, unknown>)
+    .find((p) => p.username === credential.username);
+  if (row === undefined) return undefined;
+  if (row.deleted_at !== null && row.deleted_at !== undefined) return 'refused';
+  if (row._secret_sha256 !== createHash('sha256').update(credential.password).digest('hex')) return 'refused';
+  // a password whose ttl has passed "will be invalid" (the spec's create_password), refused like any bad credential
+  if (typeof row.expires_at === 'string' && occurredAt !== undefined && Date.parse(row.expires_at) <= Date.parse(occurredAt)) return 'refused';
+  // the branch the password was made on (its `database_branch`), and that branch's scope in the store
+  const branch = String((row.database_branch as { name?: unknown } | undefined)?.name ?? DEFAULT_BRANCH);
+  const scope = scopeOf(String(row._database || DEFAULT_DATABASE), branch);
+  // the branch's safe migrations, as the management lane keeps them on its branch record
+  const database = String(row._database ?? '');
+  const record = twinResourcesOfType(SERVICE, '_branch', root).find((r) => (ownFields(r) as Record<string, unknown>)._database === database && (ownFields(r) as Record<string, unknown>).name === branch && (ownFields(r) as Record<string, unknown>).deleted_at === null);
+  const safeMigrations = record !== undefined && (ownFields(record) as Record<string, unknown>).safe_migrations === true;
+  return { role: row.role as PasswordRole, branch, ...(scope ? { scope } : {}), safeMigrations };
+}
+
+export { PLANETSCALE_RESOURCE_TYPES };