@volter/twin-upstashvector 0.1.0

package/src/upstashvector-twin.ts

@@ -0,0 +1,347 @@
+// UPSTASH VECTOR REST TWIN — THE REQUEST HANDLER. Contract:
+//   handleUpstashVectorTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, token })
+//     -> { status, body, headers }
+//
+// This file is the TRANSPORT half; every vector semantic lives in `upstashvector-store.ts` and the
+// metadata-filter language in `upstashvector-filter.ts`. What is modeled here is Upstash Vector's
+// REST protocol itself:
+//
+//   POST /upsert            body: one vector object OR an array of them
+//   POST /upsert/{ns}       ... into a named namespace (namespaces are a PATH SUFFIX)
+//   POST /query             body: one query object → {result:[...]}
+//   POST /query             body: an ARRAY of query objects → queryMany (see below)
+//   POST /fetch  /range  /delete  /update     (+ their /{ns} forms)
+//   POST|DELETE /reset  /reset/{ns}  /reset?all
+//   GET|POST /info          GET|POST /list-namespaces
+//   POST|DELETE /delete-namespace/{ns}
+//
+// ── FOUR THINGS A NAIVE TWIN GETS WRONG ───────────────────────────────────────────────────────
+//
+// 1. EVERY SDK CALL IS A **POST**, whatever the docs say the method is. `@upstash/vector@1.2.3`'s
+//    `HttpClient.request` hardcodes `method: "POST"` (confirmed in the installed dist), so although
+//    the docs spell `/reset` and `/delete-namespace` as `-X DELETE`, the real SDK never sends
+//    DELETE at all. A twin that accepted only the documented method would 405 the actual client.
+//    Both are accepted here.
+//
+// 2. NAMESPACES ARE A PATH SUFFIX, NOT A BODY FIELD. `index.namespace("ns").query(...)` becomes
+//    `POST /query/ns` — the namespace never appears in the JSON. A twin reading `body.namespace`
+//    would silently serve every namespaced request out of the default namespace, so every tenant
+//    would see every other tenant's vectors.
+//
+// 3. `/query` IS OVERLOADED ON BODY SHAPE. An OBJECT body is one query and answers
+//    `{"result":[...]}`; an ARRAY body is `queryMany` and answers a nested `{"result":[[...],...]}`
+//    — EXCEPT for a single-element array, which the real API answers FLAT. That is not a guess:
+//    `QueryManyCommand.exec` in the installed SDK re-nests it and its own comment says "When a
+//    single query is sent via queryMany, the API returns a flat array of results instead of a
+//    nested array." A twin that always nested would hand `queryMany([q])` a doubly-nested result.
+//
+// 4. AN UNMODELED ENDPOINT MUST 404, NEVER 200. `/upsert-data`, `/query-data` and the
+//    resumable-query family are real vendor surface this twin does not serve; each fails with the
+//    vendor's `{error,status}` envelope naming what is missing, so a caller can never mistake
+//    silence for success.
+//
+// GROUNDED (2026-08-19) — see spec-sources.json and the store module's header. Upstash publishes
+// no literal text for most of its errors and this pack had no live index to probe, so the error
+// STRINGS below are twin-authored except the dimension mismatch, which is quoted from the vendor's
+// own upsert doc. What IS faithful and asserted: the `{result}` / `{error,status}` envelope, the
+// status codes, the routing table, and every response body shape.
+import {
+  DEFAULT_NAMESPACE,
+  IndexSpace,
+  ReadOnlyError,
+  VectorApiError,
+  UPSTASHVECTOR_RESOURCE_TYPES,
+  type SimilarityFunction,
+  type VectorContext,
+} from './upstashvector-store.ts';
+
+export type UpstashVectorRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /**
+   * The token this twin accepts. When set, the request's credential must match it EXACTLY.
+   * When omitted the twin accepts any NON-EMPTY credential and still 401s a missing/blank one —
+   * the honest default for a local twin whose whole point is that you hold no real secret.
+   */
+  token?: string;
+  /** The dimension this index was created with. Omit to let the first upsert lock one in. */
+  dimension?: number;
+  /** The metric this index was created with. Defaults to COSINE. */
+  similarityFunction?: SimilarityFunction;
+};
+
+export type UpstashVectorResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+/** Response headers. `content-type` is what the SDK's `res.json()` requires. */
+const BASE_HEADERS: Record<string, string> = {
+  'content-type': 'application/json; charset=utf-8',
+  'access-control-allow-credentials': 'true',
+};
+
+/**
+ * The 401 body — VERBATIM from upstash.com/docs/vector/api/get-started, whose error example is
+ * exactly `{"error": "Unauthorized: Invalid auth token", "status": 401}`.
+ *
+ * (§9 round 1 caught this pack UNDER-claiming: an earlier draft used its own wording and declared
+ * the vendor's text unpublished, when the get-started page publishes it. Note the capital `I` in
+ * "Invalid" — matching it exactly is the difference between a consumer's error assertion passing
+ * against this twin and only passing against the real service. This is now one of TWO strings in
+ * the pack quoted verbatim from the vendor, alongside the dimension-mismatch 422.)
+ */
+export const UPSTASH_VECTOR_UNAUTHORIZED_ERROR = 'Unauthorized: Invalid auth token';
+
+/** Every endpoint this twin routes, and the ones it deliberately refuses. */
+export type UpstashVectorCommand =
+  | 'upsert' | 'query' | 'fetch' | 'range' | 'delete' | 'update' | 'reset'
+  | 'info' | 'list-namespaces' | 'delete-namespace';
+
+/** Real vendor endpoints this twin does NOT serve, each with the manifest gap that tracks it. */
+const UNMODELED_ENDPOINTS: Record<string, string> = {
+  'upsert-data': 'upstashvector.embedding.upsert_data',
+  'query-data': 'upstashvector.embedding.query_data',
+  'resumable-query': 'upstashvector.resumable.start',
+  'resumable-query-data': 'upstashvector.resumable.start',
+  'resumable-query-next': 'upstashvector.resumable.next',
+  'resumable-query-end': 'upstashvector.resumable.stop',
+};
+
+const MODELED: ReadonlySet<string> = new Set<UpstashVectorCommand>([
+  'upsert', 'query', 'fetch', 'range', 'delete', 'update', 'reset', 'info', 'list-namespaces', 'delete-namespace',
+]);
+
+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;
+}
+
+/**
+ * Extract the caller's credential from `Authorization: Bearer <token>` (what the SDK sends) or a
+ * bare `Authorization: <token>`.
+ *
+ * The optional-group regex matters: `Authorization: Bearer ` — the scheme with an EMPTY token —
+ * trims to the bare word "Bearer". A `/^bearer\s+(.*)$/` pattern does not match it, so a naive
+ * implementation falls through and treats the literal string "Bearer" as the credential,
+ * authenticating a request that carries no token at all.
+ */
+export function extractUpstashVectorCredential(headers: Record<string, string> | undefined): string | null {
+  const raw = lowerHeaders(headers).authorization;
+  if (raw === undefined) return null;
+  const trimmed = raw.trim();
+  const bearer = /^bearer(?:\s+(.*))?$/i.exec(trimmed);
+  const token = bearer ? (bearer[1] ?? '').trim() : trimmed;
+  return token === '' ? null : token;
+}
+
+/** The parsed shape of a request path: which command, and which namespace. */
+export type UpstashVectorRoute = { command: string; namespace: string };
+
+/**
+ * Split `/query/my-ns` into `{command:'query', namespace:'my-ns'}`.
+ *
+ * Everything after the first segment is the namespace, percent-DECODED and re-joined — a namespace
+ * is an arbitrary string, so one containing a `/` must survive the round trip rather than being
+ * truncated at the first slash into a DIFFERENT namespace's data.
+ */
+export function routeUpstashVectorPath(path: string): UpstashVectorRoute {
+  const clean = (path.split('?')[0] ?? '/').replace(/^\/+/, '');
+  const segments = clean.split('/');
+  const command = decodeSegment(segments[0] ?? '').toLowerCase();
+  const namespace = segments.length > 1 ? segments.slice(1).map(decodeSegment).join('/') : DEFAULT_NAMESPACE;
+  return { command, namespace };
+}
+
+function decodeSegment(seg: string): string {
+  try {
+    return decodeURIComponent(seg);
+  } catch {
+    return seg; // a malformed escape is passed through rather than turned into a 500
+  }
+}
+
+export async function handleUpstashVectorTwinRequest(req: UpstashVectorRequest): Promise<UpstashVectorResponse> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery] = req.path.split('?');
+  const query = new URLSearchParams(rawQuery ?? '');
+  const headers = lowerHeaders(req.headers);
+  const occurredAt = req.occurredAt ?? new Date().toISOString();
+
+  // CORS preflight. Answered before auth — a browser preflight carries no Authorization header by
+  // definition, so 401ing it would make the twin unusable from any browser client.
+  if (method === 'OPTIONS') {
+    return {
+      status: 200,
+      body: null,
+      headers: {
+        'access-control-allow-origin': headers.origin ?? '*',
+        'access-control-allow-methods': 'GET,POST,PUT,DELETE,HEAD,OPTIONS',
+        'access-control-allow-headers': headers['access-control-request-headers'] ?? 'authorization,content-type',
+        'access-control-allow-credentials': 'true',
+      },
+    };
+  }
+
+  // upstash.com/docs/vector/api/get-started documents 405 for an unsupported method. DELETE is
+  // included because the docs spell `/reset` and `/delete-namespace` with `-X DELETE`.
+  if (!['GET', 'POST', 'PUT', 'HEAD', 'DELETE'].includes(method)) {
+    return fail(405, `Method Not Allowed: ${method}`);
+  }
+
+  // ── auth, before anything else ─────────────────────────────────────────────────────────────
+  const credential = extractUpstashVectorCredential(req.headers);
+  const authorized = req.token === undefined ? credential !== null : credential === req.token;
+  if (!authorized) return fail(401, UPSTASH_VECTOR_UNAUTHORIZED_ERROR);
+
+  const { command, namespace } = routeUpstashVectorPath(rawPath ?? '/');
+
+  if (command === '') return fail(404, 'Not Found: no endpoint at /');
+  if (!MODELED.has(command)) {
+    const gap = UNMODELED_ENDPOINTS[command];
+    // A REAL vendor endpoint this twin has not built fails 404 naming the filed gap; anything else
+    // is simply not an Upstash Vector endpoint. Neither can ever be mistaken for a success.
+    return fail(404, gap !== undefined
+      ? `upstashvector: /${command} is real Upstash Vector surface this twin does not model yet (${gap} is the filed gap)`
+      : `Not Found: /${command} is not an Upstash Vector endpoint`);
+  }
+
+  // GET AND HEAD ARE SAFE METHODS, so neither may mutate anything.
+  //
+  // §9 round 1 found the worst bug in this file: the HEAD check used to live AFTER `runCommand`
+  // and `flush()`, so `HEAD /reset` emptied the index and `HEAD /delete` removed vectors — then
+  // suppressed the body and answered a read-shaped, body-less 200. A destructive operation
+  // disguised as a read is the worst available failure mode. Forcing the request read-only means
+  // a HEAD to a write endpoint takes the ordinary 405 read-only path, while `HEAD /info` still
+  // answers 200 with no body.
+  //
+  // GET is included for the same reason (RFC 9110 defines both as safe): caches, prefetchers,
+  // crawlers and link-checkers issue GET freely, and no documented Upstash Vector client ever
+  // sends GET to a write endpoint — the SDK POSTs everything, and the docs use POST or DELETE. So
+  // the cost of refusing is zero for every real caller, while the cost of allowing it is an index
+  // destroyed by something that thought it was reading. What the REAL service does with
+  // `GET /reset` is UNVERIFIED (no live index to probe) and is filed as
+  // `upstashvector.protocol.get_on_a_write_endpoint`; this twin takes the safe side deliberately
+  // rather than guessing the destructive one.
+  const readOnly = (req.readOnly ?? false) || method === 'HEAD' || method === 'GET';
+
+  const ctx: VectorContext = {
+    occurredAt,
+    ...(req.root !== undefined ? { root: req.root } : {}),
+    ...(readOnly ? { readOnly: true } : {}),
+    ...(req.dimension !== undefined ? { dimension: req.dimension } : {}),
+    ...(req.similarityFunction !== undefined ? { similarityFunction: req.similarityFunction } : {}),
+  };
+
+  try {
+    const space = new IndexSpace(ctx);
+    const result = await runCommand(space, command as UpstashVectorCommand, namespace, req.body, query);
+    await space.flush();
+    // HEAD answers with no body at all.
+    if (method === 'HEAD') return { status: 200, body: null, headers: { ...BASE_HEADERS } };
+    return { status: 200, body: { result }, headers: { ...BASE_HEADERS } };
+  } catch (e) {
+    if (e instanceof ReadOnlyError) {
+      // Distinguish the two reasons a write can be refused. §9 round 2: a `HEAD /upsert` against a
+      // perfectly writable twin used to answer "this twin was started read-only", which is simply
+      // false and sends the reader hunting for a flag they never set.
+      return fail(405, readOnly && !(req.readOnly ?? false)
+        ? `upstashvector: ${method} is a safe method and cannot modify the index — use POST (or PUT/DELETE where the endpoint documents it)`
+        : e.message);
+    }
+    if (e instanceof VectorApiError) return fail(e.status, e.message);
+    // LAST-RESORT ENVELOPE. A twin's caller must always get a response it can reason about, and an
+    // internal fault must be VISIBLE rather than silent — an unhandled rejection would leave the
+    // request with no HTTP answer at all. Surfaced as a loud, twin-attributed 500.
+    return fail(500, `upstashvector: internal fault handling /${command} — ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+/** The vendor's error envelope: `{"error": "...", "status": N}` (upsert doc's own 422 example). */
+function fail(status: number, error: string): UpstashVectorResponse {
+  return { status, body: { error, status }, headers: { ...BASE_HEADERS } };
+}
+
+async function runCommand(
+  space: IndexSpace,
+  command: UpstashVectorCommand,
+  namespace: string,
+  rawBody: string | undefined,
+  query: URLSearchParams,
+): Promise<unknown> {
+  switch (command) {
+    case 'info':
+      return space.info();
+    case 'list-namespaces':
+      return space.listNamespaces();
+    case 'delete-namespace':
+      space.deleteNamespace(namespace);
+      return 'Success';
+    case 'reset':
+      // `?all` is a BARE query flag — `ResetCommand` builds the literal string `reset?all`, so the
+      // parameter has an empty value and `query.get('all')` is `''`, not `null`. Testing
+      // `.has('all')` is what makes the SDK's own spelling work.
+      return space.reset(query.has('all') ? { all: true } : { namespace });
+    case 'upsert': {
+      const body = parseJsonBody(rawBody);
+      // The vendor accepts a single object OR an array (its own doc shows both curl forms).
+      return space.upsert(namespace, Array.isArray(body) ? body : [body]);
+    }
+    case 'update':
+      return space.update(namespace, parseJsonBody(rawBody));
+    case 'fetch':
+      return space.fetch(namespace, parseJsonBody(rawBody));
+    case 'range':
+      return space.range(namespace, parseJsonBody(rawBody));
+    case 'delete':
+      return space.delete(namespace, parseJsonBody(rawBody));
+    case 'query': {
+      const body = parseJsonBody(rawBody);
+      if (!Array.isArray(body)) return space.query(namespace, body);
+      // queryMany. See the module header, point 3: a ONE-element batch answers FLAT, which is the
+      // shape the installed SDK's own normalization proves the real API returns.
+      if (body.length === 0) throw new VectorApiError('upstashvector: query batch must not be empty', 400);
+      const results = body.map((one) => space.query(namespace, one));
+      return body.length === 1 ? results[0]! : results;
+    }
+  }
+}
+
+/** Parse a JSON request body, refusing what the vendor refuses. */
+function parseJsonBody(raw: string | undefined): unknown {
+  if (raw === undefined || raw.trim() === '') throw new VectorApiError('upstashvector: request body is required', 400);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new VectorApiError('upstashvector: request body is not valid JSON', 400);
+  }
+}
+
+// ── the self-referential conformance snapshot ──────────────────────────────────────────────────
+
+export type UpstashVectorTwinSnapshot = {
+  resourceTypes: readonly string[];
+  implementedEndpoints: readonly string[];
+};
+
+export function upstashvectorTwinSnapshot(): UpstashVectorTwinSnapshot {
+  return {
+    resourceTypes: UPSTASHVECTOR_RESOURCE_TYPES,
+    implementedEndpoints: [
+      'POST /upsert[/{namespace}] (one vector object or an array of them)',
+      'POST /query[/{namespace}] (an object = one query; an array = queryMany)',
+      'POST /fetch[/{namespace}] (by ids — positionally aligned, null for a miss — or by prefix)',
+      'POST /range[/{namespace}] (offset cursor, nextCursor "" when exhausted)',
+      'POST /update[/{namespace}] ({updated:0|1}, metadataUpdateMode OVERWRITE|PATCH)',
+      'POST|DELETE /delete[/{namespace}] (by ids, prefix or metadata filter)',
+      'POST|DELETE /reset[/{namespace}] and /reset?all',
+      'GET|POST /info (counts + configuration + the per-namespace map)',
+      'GET|POST /list-namespaces',
+      'POST|DELETE /delete-namespace/{namespace}',
+      'OPTIONS (CORS preflight)',
+    ],
+  };
+}