@volter/twin-turbopuffer 0.1.0

package/src/manifest.ts

@@ -0,0 +1,63 @@
+// Turbopuffer's manifest: the vendor facts its published spec does not carry (docs/contributing/architecture.md,
+// "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec by scripts/derive-pack.ts): the
+// OpenAPI document @turbopuffer/turbopuffer@2.8.0 was generated from, with its three generator pseudo-paths folded
+// into the operations turbopuffer documents (../spec/patches.json). The spec has no operationIds, so an operation's id
+// is the reader's `method_path` slug (`post_v2_namespaces_namespace` is the write).
+//
+// THE HANDLERS. Every operation the twin serves is a semantics handler (semantics/namespaces.ts) over the pack's
+// request handler (turbopuffer-twin.ts), whose store and filter/BM25 code (turbopuffer-store.ts, -filter.ts,
+// -text.ts) are the vendor's behaviour. The spec names one resource (`NamespaceSummary`, what the list answers);
+// every other answer is a computed or non-resource body (a write's result, a query's rows, a schema), so the derived
+// core owns no operation and none is declared here. An operation no handler serves answers the gap (../src/turbopuffer-server.ts).
+//
+// WHY NO `auth`. Turbopuffer reads `Authorization: Bearer <API key>` (https://turbopuffer.com/docs/auth). The request
+// handler refuses a request with no key; the key gate (../key-gate.ts) refuses a key the dashboard expired or never made,
+// and a key without the list or admin permission asking to list namespaces. A served twin may also be started demanding
+// one key (`--token`), which the kernel's `auth` (keys the twin refuses, never the one it accepts) cannot state.
+//
+// THE STATUSES THE KEY GATE ANSWERS: the twin's reading. turbopuffer's pages print the error body and a 429, and no
+// status for a bad key or a missing permission; 401 and 403 are the statuses its own client maps to AuthenticationError
+// and PermissionDeniedError (https://raw.githubusercontent.com/turbopuffer/turbopuffer-typescript/v2.8.0/src/core/error.ts).
+//
+// THE KEYS' PERMISSIONS: where the evidence stops. turbopuffer names read/write permissions (changelog, March 2024), a
+// list permission (May 2026) and admin, and says which one an endpoint needs only for listing namespaces
+// (https://turbopuffer.com/docs/namespaces). The twin enforces that one; every other operation admits any live key, the
+// twin's reading, since no page says whether a read key may write, warm a cache or delete a namespace.
+//
+// THE ERROR BODY. `{"status": "error", "error": "<message>"}`, as https://turbopuffer.com/docs/auth prints it and the
+// spec's ErrorResponse types it. The messages are the twin's; where the documentation stops, no page prints the text
+// of a particular refusal.
+//
+// THE STATE. One `namespace` subject per namespace (its schema, distance metric, vector dimensions and times) and one
+// `document` subject per document, keyed `<namespace>/<n|s>:<id>` (turbopuffer-store.ts). A write request is one
+// kernel action: the namespace's fields and a projection of the documents it touched.
+import type { DerivedManifest } from '@volter/world-core';
+
+export const manifest: DerivedManifest = {
+  vendor: 'turbopuffer',
+  service: 'turbopuffer',
+  body: {},
+  // the core mints no id (it owns no operation); a document's id is the caller's
+  ids: { template: '{prefix}_{n}' },
+  time: 'iso',
+  error: { status: 'error', error: '{message}' },
+  readOnly: { status: 405, message: 'read_only: this twin was started read-only; writes are refused' },
+  malformedBody: { status: 400, message: 'invalid request: body is not valid JSON' },
+  notFound: { status: 404, message: 'not found' },
+  // GET /v1/namespaces answers `{namespaces, next_cursor}`, paged by `cursor` and `page_size`
+  // (https://turbopuffer.com/docs/namespaces); the handler answers it. Required by the type; the core lists nothing.
+  list: { style: 'envelope', envelope: { namespaces: '{data}' }, limit: { param: 'page_size', default: 100, max: 1000 } },
+  deleted: {},
+  // turbopuffer's dashboard (https://turbopuffer.com/docs/auth: "You can create and expire tokens in the dashboard"):
+  // its sign-in, and the page where an organization's API keys are made and expired (screens/dashboard.tsx)
+  screens: [{
+    id: 'login', kind: 'flow', host: 'turbopuffer.com', path: '/login',
+    demand: 'every dashboard page asks who is signed in', status: 'done',
+    controls: ['Email', 'Password', 'Continue'], source: 'https://turbopuffer.com/docs/auth',
+  }, {
+    id: 'api-keys', kind: 'workspace', host: 'turbopuffer.com', path: '/dashboard/api-keys',
+    demand: 'every API key a customer uses is made here, and expired here when it is rotated or the customer leaves', status: 'done',
+    controls: ['Name', 'Read', 'Write', 'List', 'Admin', 'Create API key', 'Expire'], source: 'https://turbopuffer.com/docs/auth',
+  }],
+  resources: {},
+};

package/src/screens/dashboard.tsx

@@ -0,0 +1,214 @@
+// TURBOPUFFER'S DASHBOARD — the pages an organization's person signs in to and makes its API keys on
+// (docs/contributing/architecture.md, "Screens" and "Who is on a screen"). No API operation makes or expires a key: "All
+// API calls require authenticating with your API key. You can create and expire tokens in the dashboard"
+// (https://turbopuffer.com/docs/auth), so every key a customer uses comes from here. Built from @volter/world-ui's
+// sign-in and settings pieces under turbopuffer's skin; nothing of turbopuffer's page is copied.
+//
+// - turbopuffer.com/login: the sign-in (turbopuffer's page asks for an Email and has Continue). A dashboard page asked for
+//   by nobody signed in sends its visitor here, and the sign-in returns them there.
+// - turbopuffer.com/dashboard/api-keys: the organization's API keys. Create API key with its Name and its permissions,
+//   shown once in the page's notice; each live key's Expire. The permissions are the ones turbopuffer's pages name:
+//   "API Key read/write permissions" (https://turbopuffer.com/docs/roadmap, March 2024), "New API key permission to
+//   `list` namespaces" (the same, May 2026), and admin ("available to API keys with list or admin permissions",
+//   https://turbopuffer.com/docs/namespaces). A key is named ("Named API Keys", the same changelog) and marked expired
+//   (the audit log's `api-key-marked-as-expired`, https://turbopuffer.com/docs/audit-logs).
+// - POST /_twin/users/:email/password {password, organization, plan}: stands in for turbopuffer's sign-up
+//   (turbopuffer.com/join: Email, a plan, Continue), as upstash's and planetscale's doors of the same path do. The World
+//   keeps the password's hash, never the password.
+//
+// Where turbopuffer's documentation stops and the twin decides: a person signs in with an email and the password the
+// World gave them (turbopuffer's own sign-in continues by email or GitHub or Google, which the twin does not model); the
+// session cookie is named `tpuf_session`; the keys page is at /dashboard/api-keys; a key's permissions are four
+// checkboxes (Read, Write, List, Admin; turbopuffer does not document the control) and a key needs at least one; a key
+// is `tpuf_` and 32 letters and digits (the length is the twin's; the prefix is the docs' own placeholder for a key,
+// `"source_api_key": "tpuf_A1..."` in https://turbopuffer.com/docs/write's copy example); a refused sign-in shows the form again with
+// "Incorrect email or password." (200); a name already used by a live key, or none, answers the page with a notice (422).
+import { createHash } from 'node:crypto';
+import { cookieOf, flowPage, Portal, PORTAL_CSS, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+
+export const DASHBOARD_HOST = 'turbopuffer.com';
+const COOKIE = 'tpuf_session';
+const KEYS = '/dashboard/api-keys';
+export const GRANTS = ['read', 'write', 'list', 'admin'] as const;
+export type Grant = (typeof GRANTS)[number];
+const LABEL: Record<Grant, string> = { read: 'Read', write: 'Write', list: 'List', admin: 'Admin' };
+
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email: string, password: string): string => hex(`password:${email.toLowerCase()}:${password}`);
+const ALNUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+// turbopuffer's skin: its warm off-white page and near-black ink and buttons
+const SKIN = `
+body { background: #faf8f5; color: #111111; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.sign-in-mark { background: #111111; }
+.sign-in-box { background: #ffffff; border-color: #e5e1da; }
+.sign-in-error { background: #fff4f2; border-color: #f3c7bf; color: #111111; }
+.sign-in-submit { background: #111111; border-color: #111111; color: #ffffff; }
+.portal-side { background: #f3f0ea; border-right: 1px solid #e5e1da; }
+.portal-section h2 { border-color: #e5e1da; color: #57534e; }
+.portal-notice { background: #f3f0ea; border: 1px solid #e5e1da; word-break: break-all; }
+.portal-button { background: #ffffff; border: 1px solid #d6d1c8; border-radius: 4px; padding: 6px 12px; }
+.portal-primary { background: #111111; border-color: #111111; color: #ffffff; }
+`;
+
+type Row = Record<string, unknown>;
+
+/** A return_to the dashboard follows: a path on turbopuffer.com, never another site. */
+const returnTo = (raw: string | null | undefined): string => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : KEYS);
+
+function signInPage(back: string, email?: string, error?: string): Response {
+  return flowPage({
+    title: 'Log in · turbopuffer',
+    css: [SIGN_IN_CSS, SKIN],
+    body: (
+      <SignIn
+        heading="Log in"
+        action="/login"
+        fields={{ return_to: back }}
+        account={{ name: 'email', label: 'Email', ...(email ? { value: email } : {}) }}
+        password={{ name: 'password', label: 'Password' }}
+        submit="Continue"
+        {...(error ? { error } : {})}
+      />
+    ),
+  });
+}
+
+/** The person the request's session cookie names, with their organization, or undefined. */
+function signedIn(ctx: SemanticsContext, request: Request): Row | undefined {
+  const token = cookieOf(request, COOKIE);
+  const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+  return session ? ctx.rowsRaw('_person').find((p) => p.email === session.email) : undefined;
+}
+
+/** The organization's live and expired keys, oldest first. */
+export function keysOf(ctx: SemanticsContext, organization: string): Row[] {
+  return ctx.rowsRaw('_api_key').filter((k) => k.organization === organization);
+}
+
+function keysPage(ctx: SemanticsContext, person: Row, notice?: string, status = 200): Response {
+  const organization = String(person.organization);
+  const keys = keysOf(ctx, organization);
+  const grantsOf = (k: Row): string => (Array.isArray(k.grants) ? (k.grants as Grant[]).map((g) => LABEL[g]).join(', ') : '');
+  return flowPage({
+    title: 'API keys · turbopuffer',
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant={`${organization} · ${String(person.email)}`}
+        back={{ href: '/dashboard', label: 'Dashboard' }}
+        {...(notice ? { notice } : {})}
+        sections={[{
+          heading: 'API keys',
+          empty: 'No API keys yet.',
+          items: keys.map((k) => ({
+            title: String(k.name),
+            detail: grantsOf(k),
+            note: k.expired_at ? `Expired ${String(k.expired_at).slice(0, 10)}` : `Created ${String(k.created_at).slice(0, 10)} · ends ${String(k.suffix)}`,
+            ...(k.expired_at ? { badge: 'Expired' } : { actions: [{ label: 'Expire', action: `${KEYS}/expire`, tone: 'danger' as const, fields: { name: String(k.name) } }] }),
+          })),
+        }]}
+        forms={[{
+          heading: 'Create API key',
+          action: KEYS,
+          fields: [
+            { id: 'name', label: 'Name' },
+            ...GRANTS.map((g) => ({ id: g, label: LABEL[g], type: 'checkbox' })),
+          ],
+          submit: { label: 'Create API key' },
+        }]}
+      />
+    ),
+  });
+}
+
+/** A key's value: `tpuf_` and 32 letters and digits, derived from the organization, the name and the moment. */
+function keyValue(organization: string, name: string, at: string, n: number): string {
+  const digest = createHash('sha256').update(`apikey:${organization}:${name}:${at}:${n}`).digest();
+  return `tpuf_${Array.from(digest.subarray(0, 32), (b) => ALNUM[b % ALNUM.length]).join('')}`;
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+async function createKey(ctx: SemanticsContext, person: Row, form: Record<string, string>): Promise<Response> {
+  const organization = String(person.organization);
+  const name = (form.name ?? '').trim();
+  const grants = GRANTS.filter((g) => form[g] !== undefined);
+  if (!name) return keysPage(ctx, person, 'An API key needs a name.', 422);
+  if (keysOf(ctx, organization).some((k) => k.name === name && !k.expired_at)) return keysPage(ctx, person, `There is already an API key named ${name}.`, 422);
+  if (!grants.length) return keysPage(ctx, person, 'Choose at least one permission.', 422);
+  const n = ctx.rowsRaw('_api_key').length + 1;
+  const key = keyValue(organization, name, ctx.occurredAt, n);
+  await ctx.record('_api_key', {
+    organization, name, grants, created_at: ctx.occurredAt, created_by: person.email, expired_at: null,
+    suffix: key.slice(-4), key_sha256: hex(key),
+  }, `apikey:${organization}:${n}`);
+  return keysPage(ctx, person, `API key ${name} created: ${key} — copy it now, it will not be shown again.`);
+}
+
+/** Expire: the key stops working at once (key-gate.ts admits no expired key). */
+async function expireKey(ctx: SemanticsContext, person: Row, name: string): Promise<Response> {
+  const organization = String(person.organization);
+  const key = keysOf(ctx, organization).find((k) => k.name === name && !k.expired_at);
+  if (!key) return keysPage(ctx, person, `There is no live API key named ${name}.`, 422);
+  await ctx.record('_api_key', { ...ctx.own(key), expired_at: ctx.occurredAt, expired_by: person.email }, String(key.id));
+  return keysPage(ctx, person, `API key ${name} expired.`);
+}
+
+/** turbopuffer.com's pages and the World's sign-up door, or undefined for any other path. `contextFor` gives the
+ *  pack's semantics context for a request. */
+export async function dashboard(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '') || '/';
+  const ctx = await contextFor(new Request(request.url));
+  if (path === '/login' && request.method === 'GET') return signInPage(returnTo(url.searchParams.get('return_to')));
+  if (path === '/login' && request.method === 'POST') {
+    const f = await formOf(request);
+    const email = (f.email ?? '').trim().toLowerCase();
+    const back = returnTo(f.return_to);
+    const person = ctx.rowsRaw('_person').find((p) => p.email === email);
+    if (!email || !person || person.hash !== passwordHash(email, f.password ?? '')) return signInPage(back, email, 'Incorrect email or password.');
+    const token = hex(`session:${email}:${ctx.occurredAt}:${ctx.rowsRaw('_web_session').length + 1}`).slice(0, 48);
+    await ctx.record('_web_session', { token, email, created_at: ctx.occurredAt }, `websession:${token}`);
+    const headers = new Headers({ location: back });
+    headers.append('set-cookie', `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`);
+    return new Response(null, { status: 302, headers });
+  }
+  const door = /^\/_twin\/users\/([^/]+)\/password$/.exec(path);
+  if (door && request.method === 'POST') return signUpDoor(ctx, decodeURIComponent(door[1]!).toLowerCase(), request);
+  // a path the host's pages do not have is the caller's (its 404)
+  return path === '/dashboard' || path === KEYS || path === `${KEYS}/expire` ? keysPages(ctx, request, url, path) : undefined;
+}
+
+/** /dashboard (to the keys page), the keys page, its Create API key and its Expire, for the person signed in. */
+async function keysPages(ctx: SemanticsContext, request: Request, url: URL, path: string): Promise<Response | undefined> {
+  const person = signedIn(ctx, request);
+  if (!person) return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(url.pathname + url.search)}` } });
+  if (request.method === 'GET') return path === '/dashboard' ? new Response(null, { status: 302, headers: { location: KEYS } }) : keysPage(ctx, person);
+  if (request.method !== 'POST' || path === '/dashboard') return undefined;
+  const form = await formOf(request);
+  return path === KEYS ? createKey(ctx, person, form) : expireKey(ctx, person, (form.name ?? '').trim());
+}
+
+/** The sign-up door's refusal of a call missing what it needs. */
+function badSignUp(): Response {
+  return Response.json({ status: 'error', error: 'an email, a password of at least 8 characters, an organization and a plan (launch or scale) are required' }, { status: 400 });
+}
+
+/** POST /_twin/users/:email/password {password, organization, plan}: the person, their organization and its plan, as
+ *  turbopuffer's sign-up makes them (turbopuffer.com/join: "Select plan launch ($16/mo minimum) … scale ($256/mo
+ *  minimum)"); 204. */
+async function signUpDoor(ctx: SemanticsContext, email: string, request: Request): Promise<Response> {
+  let body: Record<string, unknown> = {};
+  try { body = JSON.parse(await request.text()) as Record<string, unknown>; } catch { /* refused below */ }
+  const password = typeof body.password === 'string' ? body.password : '';
+  const organization = typeof body.organization === 'string' ? body.organization.trim() : '';
+  const plan = body.plan === undefined ? 'launch' : body.plan;
+  if (!/^[^@\s]+@[^@\s]+$/.test(email) || password.length < 8 || !organization || (plan !== 'launch' && plan !== 'scale')) return badSignUp();
+  await ctx.record('_person', { email, hash: passwordHash(email, password), organization, plan, set_at: ctx.occurredAt }, `person:${email}`);
+  return new Response(null, { status: 204 });
+}

package/src/semantics/namespaces.ts

@@ -0,0 +1,30 @@
+// Turbopuffer's handlers, by operationId (docs/contributing/architecture.md, "The semantics layer"): every operation of
+// the spec's surface (../generated/surface.gen.json) the twin serves. Each delegates to the pack's request handler
+// (../turbopuffer-twin.ts), which keeps turbopuffer's order and answers: the API key, then the namespace name, then
+// the operation over the store (../turbopuffer-store.ts: writes, schema, queries, BM25 and filters), in the
+// `{status: "error", error}` body. An operation of the surface not named here is the gap: namespace pinning
+// (PATCH /v1/namespaces/{namespace}/metadata), query plans (explain_query) and recall evaluation (_debug/recall).
+//
+// These are dispatch handlers, not `bindSemantics` ones: a write request is one kernel action over the namespace and
+// every document it touches (a projection), which a semantics context's single-subject write cannot make, as
+// tinybird's handlers are for its row-per-event appends.
+import type { DerivedCall, DerivedHandler } from '@volter/world-core';
+
+/** The operations served here, every one the twin serves. */
+export const HANDLED = [
+  // namespaces
+  'get_v1_namespaces', 'get_v2_namespaces_namespace_metadata', 'get_v1_namespaces_namespace_metadata', 'get_v1_namespaces_namespace_hint_cache_warm',
+  'delete_v2_namespaces_namespace',
+  // an asynchronous copy's operation, polled (the API overview's Asynchronous requests)
+  'get_v1_namespaces_namespace_operations_token',
+  // a namespace's schema
+  'get_v1_namespaces_namespace_schema', 'post_v1_namespaces_namespace_schema',
+  // documents: the write (upserts, patches and deletes, by id or by filter) and the query (one query, or several)
+  'post_v2_namespaces_namespace', 'post_v2_namespaces_namespace_query',
+] as const;
+
+/** A handler per operation above, answering through `answer` (the pack's request handler as a fetch). */
+export function turbopufferHandlers(answer: (request: Request) => Promise<Response>): Record<string, DerivedHandler> {
+  const serve: DerivedHandler = ({ request }: DerivedCall) => answer(request);
+  return Object.fromEntries(HANDLED.map((id) => [id, serve]));
+}