npm - @query-farm/vgi-rpc - Versions diffs - 0.6.4 → 0.7.0 - Mend

@query-farm/vgi-rpc 0.6.4 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (160) hide show

package/dist/access-log.d.ts +50 -0
package/dist/access-log.d.ts.map +1 -0
package/dist/arrow/impl-arrowjs/index.d.ts +96 -0
package/dist/arrow/impl-arrowjs/index.d.ts.map +1 -0
package/dist/arrow/impl-flechette/index.d.ts +102 -0
package/dist/arrow/impl-flechette/index.d.ts.map +1 -0
package/dist/arrow/impl-flechette/message-meta.d.ts +11 -0
package/dist/arrow/impl-flechette/message-meta.d.ts.map +1 -0
package/dist/arrow/index.d.ts +4 -0
package/dist/arrow/index.d.ts.map +1 -0
package/dist/arrow/predicates.d.ts +44 -0
package/dist/arrow/predicates.d.ts.map +1 -0
package/dist/arrow/types.d.ts +62 -0
package/dist/arrow/types.d.ts.map +1 -0
package/dist/client/capabilities.d.ts +25 -0
package/dist/client/capabilities.d.ts.map +1 -0
package/dist/client/connect.d.ts.map +1 -1
package/dist/client/introspect.d.ts +7 -0
package/dist/client/introspect.d.ts.map +1 -1
package/dist/client/ipc.d.ts +8 -2
package/dist/client/ipc.d.ts.map +1 -1
package/dist/client/pipe.d.ts.map +1 -1
package/dist/client/stream.d.ts +11 -2
package/dist/client/stream.d.ts.map +1 -1
package/dist/client/uploadUrl.d.ts +25 -0
package/dist/client/uploadUrl.d.ts.map +1 -0
package/dist/constants.d.ts +15 -1
package/dist/constants.d.ts.map +1 -1
package/dist/crypto.d.ts +22 -0
package/dist/crypto.d.ts.map +1 -0
package/dist/dispatch/describe.d.ts +10 -6
package/dist/dispatch/describe.d.ts.map +1 -1
package/dist/dispatch/stream.d.ts +2 -2
package/dist/dispatch/stream.d.ts.map +1 -1
package/dist/dispatch/unary.d.ts +2 -2
package/dist/dispatch/unary.d.ts.map +1 -1
package/dist/errors.d.ts +46 -0
package/dist/errors.d.ts.map +1 -1
package/dist/external.d.ts +25 -5
package/dist/external.d.ts.map +1 -1
package/dist/http/bearer.d.ts.map +1 -1
package/dist/http/common.d.ts +42 -7
package/dist/http/common.d.ts.map +1 -1
package/dist/http/dispatch.d.ts +20 -2
package/dist/http/dispatch.d.ts.map +1 -1
package/dist/http/handler.d.ts.map +1 -1
package/dist/http/index.d.ts +1 -0
package/dist/http/index.d.ts.map +1 -1
package/dist/http/mtls.d.ts +2 -1
package/dist/http/mtls.d.ts.map +1 -1
package/dist/http/oauth-pkce.d.ts +141 -0
package/dist/http/oauth-pkce.d.ts.map +1 -0
package/dist/http/pages.d.ts +3 -0
package/dist/http/pages.d.ts.map +1 -1
package/dist/http/sticky.d.ts +124 -0
package/dist/http/sticky.d.ts.map +1 -0
package/dist/http/token.d.ts +38 -12
package/dist/http/token.d.ts.map +1 -1
package/dist/http/types.d.ts +66 -5
package/dist/http/types.d.ts.map +1 -1
package/dist/index.d.ts +6 -4
package/dist/index.d.ts.map +1 -1
package/dist/index.js +1275 -3511
package/dist/index.js.map +19 -37
package/dist/launcher/hash.d.ts +22 -0
package/dist/launcher/hash.d.ts.map +1 -0
package/dist/launcher/index.d.ts +23 -0
package/dist/launcher/index.d.ts.map +1 -0
package/dist/launcher/launch.d.ts +27 -0
package/dist/launcher/launch.d.ts.map +1 -0
package/dist/launcher/lock.d.ts +19 -0
package/dist/launcher/lock.d.ts.map +1 -0
package/dist/launcher/serve-unix.d.ts +54 -0
package/dist/launcher/serve-unix.d.ts.map +1 -0
package/dist/launcher/state.d.ts +59 -0
package/dist/launcher/state.d.ts.map +1 -0
package/dist/otel.d.ts.map +1 -1
package/dist/protocol.d.ts +16 -2
package/dist/protocol.d.ts.map +1 -1
package/dist/schema.d.ts +45 -18
package/dist/schema.d.ts.map +1 -1
package/dist/server.d.ts +23 -2
package/dist/server.d.ts.map +1 -1
package/dist/types.d.ts +216 -12
package/dist/types.d.ts.map +1 -1
package/dist/util/gzip.d.ts +10 -0
package/dist/util/gzip.d.ts.map +1 -0
package/dist/util/schema.d.ts +3 -15
package/dist/util/schema.d.ts.map +1 -1
package/dist/util/web-crypto.d.ts +22 -0
package/dist/util/web-crypto.d.ts.map +1 -0
package/dist/util/zstd.d.ts +26 -3
package/dist/util/zstd.d.ts.map +1 -1
package/dist/wire/opaque.d.ts +11 -0
package/dist/wire/opaque.d.ts.map +1 -0
package/dist/wire/reader.d.ts +5 -5
package/dist/wire/reader.d.ts.map +1 -1
package/dist/wire/request.d.ts +11 -3
package/dist/wire/request.d.ts.map +1 -1
package/dist/wire/response.d.ts +6 -6
package/dist/wire/response.d.ts.map +1 -1
package/dist/wire/writer.d.ts +49 -39
package/dist/wire/writer.d.ts.map +1 -1
package/package.json +24 -10
package/src/access-log.ts +195 -0
package/src/arrow/impl-arrowjs/index.ts +433 -0
package/src/arrow/impl-flechette/index.ts +414 -0
package/src/arrow/impl-flechette/message-meta.ts +174 -0
package/src/arrow/index.ts +89 -0
package/src/arrow/predicates.ts +56 -0
package/src/arrow/types.ts +73 -0
package/src/client/capabilities.ts +84 -0
package/src/client/connect.ts +103 -26
package/src/client/introspect.ts +60 -38
package/src/client/ipc.ts +37 -27
package/src/client/pipe.ts +12 -9
package/src/client/stream.ts +34 -19
package/src/client/uploadUrl.ts +169 -0
package/src/constants.ts +18 -1
package/src/crypto.ts +95 -0
package/src/dispatch/describe.ts +146 -107
package/src/dispatch/stream.ts +53 -24
package/src/dispatch/unary.ts +5 -4
package/src/errors.ts +76 -0
package/src/external.ts +43 -29
package/src/http/bearer.ts +2 -5
package/src/http/common.ts +90 -23
package/src/http/dispatch.ts +373 -46
package/src/http/handler.ts +790 -68
package/src/http/index.ts +1 -0
package/src/http/mtls.ts +18 -3
package/src/http/oauth-pkce.ts +1035 -0
package/src/http/pages.ts +30 -15
package/src/http/sticky.ts +429 -0
package/src/http/token.ts +165 -75
package/src/http/types.ts +67 -5
package/src/index.ts +40 -1
package/src/launcher/hash.ts +104 -0
package/src/launcher/index.ts +35 -0
package/src/launcher/launch.ts +284 -0
package/src/launcher/lock.ts +171 -0
package/src/launcher/serve-unix.ts +385 -0
package/src/launcher/state.ts +245 -0
package/src/otel.ts +39 -33
package/src/protocol.ts +27 -3
package/src/schema.ts +107 -56
package/src/server.ts +196 -20
package/src/types.ts +322 -18
package/src/util/gzip.ts +63 -0
package/src/util/schema.ts +4 -22
package/src/util/web-crypto.ts +98 -0
package/src/util/zstd.ts +133 -14
package/src/wire/opaque.ts +37 -0
package/src/wire/reader.ts +5 -4
package/src/wire/request.ts +67 -8
package/src/wire/response.ts +51 -85
package/src/wire/writer.ts +165 -69
package/dist/util/conform.d.ts +0 -18
package/dist/util/conform.d.ts.map +0 -1
package/src/util/conform.ts +0 -94

package/src/http/pages.ts CHANGED Viewed

@@ -8,17 +8,38 @@
 import type { MethodDefinition } from "../types.js";
-const LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
+export const LOGO_URL = "https://vgi-rpc-python.query.farm/assets/logo-hero.png";
-const FONTS = `<link rel="preconnect" href="https://fonts.googleapis.com">
+export const FONTS = `<link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">`;
+export const ERROR_PAGE_STYLE = `<style>
+body { font-family: 'Inter', system-ui, -apple-system, sans-serif; max-width: 600px;
+       margin: 0 auto; padding: 60px 20px 0; color: #2c2c1e; text-align: center;
+       background: #faf8f0; }
+.logo { margin-bottom: 24px; }
+.logo img { width: 120px; height: 120px; border-radius: 50%;
+             box-shadow: 0 4px 24px rgba(0,0,0,0.12); }
+h1 { color: #2d5016; margin-bottom: 8px; font-weight: 700; }
+code { font-family: 'JetBrains Mono', monospace; background: #f0ece0;
+        padding: 2px 6px; border-radius: 3px; font-size: 0.9em; color: #2c2c1e; }
+a { color: #2d5016; text-decoration: none; }
+a:hover { color: #4a7c23; }
+p { line-height: 1.7; color: #6b6b5a; }
+.detail { margin-top: 12px; padding: 12px 16px; background: #f0ece0;
+           border-radius: 6px; font-size: 0.9em; color: #6b6b5a; }
+footer { margin-top: 48px; padding: 20px 0; border-top: 1px solid #f0ece0;
+          color: #6b6b5a; font-size: 0.85em; line-height: 1.8; }
+footer a { color: #2d5016; font-weight: 600; }
+footer a:hover { color: #4a7c23; }
+</style>`;
 function escapeHtml(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function arrowTypeToString(type: import("@query-farm/apache-arrow").DataType): string {
+function arrowTypeToString(type: import("../arrow/index.js").VgiDataType): string {
   const id = type.typeId;
   // Match the human-friendly type names used by the Python reference implementation
   if (id === 5) return "str"; // Utf8
@@ -114,17 +135,9 @@ export function buildNotFoundPage(prefix: string, protocolName: string): string
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>404 \u2014 vgi-rpc endpoint</title>
-<style>
-body { font-family: system-ui, -apple-system, sans-serif; max-width: 600px;
-       margin: 60px auto; padding: 0 20px; color: #333; text-align: center; }
-.logo { margin-bottom: 24px; }
-.logo img { width: 120px; height: 120px; }
-h1 { color: #555; }
-code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; font-size: 0.95em; }
-a { color: #0066cc; }
-p { line-height: 1.6; }
-</style>
+<title>404 \u2014 vgi-rpc</title>
+${FONTS}
+${ERROR_PAGE_STYLE}
 </head>
 <body>
 <div class="logo">
@@ -133,7 +146,9 @@ p { line-height: 1.6; }
 <h1>404 \u2014 Not Found</h1>
 <p>This is a <code>vgi-rpc</code> service endpoint${nameFragment}.</p>
 <p>RPC methods are available under <code>${escapeHtml(prefixDisplay)}/&lt;method&gt;</code>.</p>
-<p>Learn more at <a href="https://vgi-rpc.query.farm">vgi-rpc.query.farm</a>.</p>
+<footer>
+  Powered by <a href="https://vgi-rpc.query.farm"><code>vgi-rpc</code></a>
+</footer>
 </body>
 </html>`;
 }

package/src/http/sticky.ts ADDED Viewed

@@ -0,0 +1,429 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sticky-session machinery for the HTTP transport.
+ *
+ * Sticky sessions let an RPC method bind a state object (a DB cursor, a
+ * loaded model, an open file handle) to the worker process that opened it,
+ * keyed by a short-lived AEAD-sealed token. Subsequent requests carrying
+ * the same `VGI-Session` header restore the object as `ctx.session`;
+ * requests that miss (wrong worker, expired, evicted) surface as a typed
+ * {@link SessionLostError}.
+ *
+ * HTTP-only and opt-in: the non-sticky wire path is byte-identical to the
+ * pre-sticky framework.
+ *
+ * Mirrors Python's `vgi_rpc/http/server/_sticky.py`.
+ */
+import { openBytes, SealError, sealBytes } from "../crypto.js";
+import { ServerDrainingError, SessionLostError } from "../errors.js";
+import { randomBytes } from "../util/web-crypto.js";
+const _UTF8 = new TextEncoder();
+const _UTF8DEC = new TextDecoder("utf-8", { fatal: false });
+const TOKEN_VERSION = 1;
+const SESSION_ID_LEN = 12; // bytes — matches Python's `_SESSION_ID_LEN`
+// Plaintext frame layout (little-endian):
+//   [u64 created_at]
+//   [u8  server_id_len]
+//   [server_id_len bytes ASCII server_id]
+//   [12B session_id]
+//   [u64 expires_at]
+const PREFIX_LEN = 8 + 1; // created_at + server_id_len
+const SUFFIX_LEN = 8; // expires_at
+// ---------------------------------------------------------------------------
+// base64url helpers (no padding) — `VGI-Session` is header-safe
+// ---------------------------------------------------------------------------
+function base64UrlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(s: string): Uint8Array {
+  let b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  // Re-pad to multiple of 4 for `atob`.
+  const pad = b64.length % 4;
+  if (pad === 2) b64 += "==";
+  else if (pad === 3) b64 += "=";
+  else if (pad === 1) throw new Error("invalid base64url length");
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+// ---------------------------------------------------------------------------
+// Token sealing
+// ---------------------------------------------------------------------------
+/** Seal a sticky-session token. Returns the base64url-encoded value for the
+ *  `VGI-Session` header. */
+export function sealSessionToken(
+  serverId: string,
+  sessionId: Uint8Array,
+  expiresAt: number,
+  tokenKey: Uint8Array,
+  aad: Uint8Array,
+  now?: number,
+): string {
+  if (sessionId.length !== SESSION_ID_LEN) {
+    throw new Error(`session_id must be ${SESSION_ID_LEN} bytes, got ${sessionId.length}`);
+  }
+  const serverIdBytes = _UTF8.encode(serverId);
+  if (serverIdBytes.length > 255) {
+    throw new Error(`server_id too long (${serverIdBytes.length} bytes); max 255`);
+  }
+  const plaintext = new Uint8Array(PREFIX_LEN + serverIdBytes.length + SESSION_ID_LEN + SUFFIX_LEN);
+  const view = new DataView(plaintext.buffer);
+  let offset = 0;
+  view.setBigUint64(offset, BigInt(now ?? Math.floor(Date.now() / 1000)), true);
+  offset += 8;
+  plaintext[offset] = serverIdBytes.length;
+  offset += 1;
+  plaintext.set(serverIdBytes, offset);
+  offset += serverIdBytes.length;
+  plaintext.set(sessionId, offset);
+  offset += SESSION_ID_LEN;
+  view.setBigUint64(offset, BigInt(expiresAt), true);
+  const sealed = sealBytes(plaintext, tokenKey, { aad, version: TOKEN_VERSION });
+  return base64UrlEncode(sealed);
+}
+export interface OpenedSessionToken {
+  serverId: string;
+  sessionId: Uint8Array;
+  expiresAt: number;
+}
+/** Open a sticky-session token. Raises {@link SessionLostError} on any failure
+ *  — wrong AAD (cross-principal replay) is indistinguishable from garbage. */
+export function openSessionToken(token: string, tokenKey: Uint8Array, aad: Uint8Array): OpenedSessionToken {
+  let raw: Uint8Array;
+  try {
+    raw = base64UrlDecode(token);
+  } catch {
+    throw new SessionLostError("malformed session token");
+  }
+  let plaintext: Uint8Array;
+  try {
+    plaintext = openBytes(raw, tokenKey, { aad, version: TOKEN_VERSION });
+  } catch (err) {
+    if (err instanceof SealError) {
+      throw new SessionLostError("session token verification failed");
+    }
+    throw err;
+  }
+  if (plaintext.length < PREFIX_LEN) {
+    throw new SessionLostError("malformed session token");
+  }
+  const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
+  const serverIdLen = plaintext[8];
+  const sidPos = PREFIX_LEN + serverIdLen;
+  const endPos = sidPos + SESSION_ID_LEN + SUFFIX_LEN;
+  if (plaintext.length !== endPos) {
+    throw new SessionLostError("malformed session token");
+  }
+  const serverId = _UTF8DEC.decode(plaintext.subarray(PREFIX_LEN, sidPos));
+  // Copy session_id into a fresh buffer so callers can hold it without
+  // pinning the larger plaintext buffer.
+  const sessionId = new Uint8Array(SESSION_ID_LEN);
+  sessionId.set(plaintext.subarray(sidPos, sidPos + SESSION_ID_LEN));
+  const expiresAt = Number(view.getBigUint64(sidPos + SESSION_ID_LEN, true));
+  return { serverId, sessionId, expiresAt };
+}
+// ---------------------------------------------------------------------------
+// Async mutex — serializes same-session calls
+// ---------------------------------------------------------------------------
+/** Minimal promise-based mutex. The HTTP handler awaits `acquire()` before
+ *  dispatching on a resumed session and calls the returned release in a
+ *  `finally` so concurrent calls on the same session run sequentially. */
+class AsyncMutex {
+  private locked = false;
+  private waiters: Array<() => void> = [];
+  async acquire(): Promise<() => void> {
+    if (!this.locked) {
+      this.locked = true;
+      return () => this.release();
+    }
+    await new Promise<void>((resolve) => this.waiters.push(resolve));
+    this.locked = true;
+    return () => this.release();
+  }
+  private release(): void {
+    const next = this.waiters.shift();
+    if (next) {
+      // Hand the lock straight to the next waiter (still `locked = true`).
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+}
+// ---------------------------------------------------------------------------
+// Session registry
+// ---------------------------------------------------------------------------
+/** A live session in the per-worker registry. */
+export interface SessionEntry {
+  state: unknown;
+  expiresAt: number; // seconds since epoch
+  principalKey: string;
+  lock: AsyncMutex;
+}
+/**
+ * Derive the registry partition key for a request principal.
+ *
+ * Both the dispatch path and the `DELETE /__session__` teardown path MUST
+ * compute this identically — otherwise a session opened on one path can't
+ * be looked up on the other. The NUL separator (rather than a space)
+ * keeps `{domain:"a", principal:"b "}` from colliding with
+ * `{domain:"a ", principal:"b"}`. Anonymous requests collapse to a
+ * single sentinel.
+ *
+ * `domain` / `principal` are the authenticated identity fields, or
+ * null/undefined for anonymous.
+ */
+export function sessionPrincipalKey(
+  authenticated: boolean,
+  domain: string | null | undefined,
+  principal: string | null | undefined,
+): string {
+  if (!authenticated) return "\u0000anonymous";
+  return `${domain ?? ""}\u0000${principal ?? ""}`;
+}
+/** Hex-encode a session_id Uint8Array (24-char lowercase hex). */
+export function sessionIdHex(sessionId: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < sessionId.length; i++) s += sessionId[i].toString(16).padStart(2, "0");
+  return s;
+}
+/** Compare two byte arrays for equality. */
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+/** Per-worker in-process map of live sticky sessions. */
+export class SessionRegistry {
+  // Use a Map keyed by hex id (Uint8Array isn't a valid Map key for equality).
+  private entries = new Map<string, { id: Uint8Array; entry: SessionEntry }>();
+  private _draining = false;
+  constructor(public readonly defaultTtl: number) {}
+  get draining(): boolean {
+    return this._draining;
+  }
+  setDraining(value: boolean): void {
+    this._draining = value;
+  }
+  /** Register a session. Throws {@link ServerDrainingError} when draining. */
+  open(state: unknown, ttl: number | undefined, principalKey: string): { sessionId: Uint8Array; expiresAt: number } {
+    if (this._draining) {
+      throw new ServerDrainingError("server is draining — new sessions are rejected");
+    }
+    const effective = ttl ?? this.defaultTtl;
+    const expiresAt = Math.floor(Date.now() / 1000) + effective;
+    const sessionId = randomBytes(SESSION_ID_LEN);
+    const key = sessionIdHex(sessionId);
+    this.entries.set(key, {
+      id: sessionId,
+      entry: { state, expiresAt, principalKey, lock: new AsyncMutex() },
+    });
+    return { sessionId, expiresAt };
+  }
+  /** Look up a session. Returns null on miss, expiry, or principal mismatch.
+   *  Expired entries are evicted in-line (and `state.close?.()` invoked). */
+  get(sessionId: Uint8Array, principalKey: string): SessionEntry | null {
+    const key = sessionIdHex(sessionId);
+    const slot = this.entries.get(key);
+    if (!slot) return null;
+    if (!bytesEqual(slot.id, sessionId)) return null;
+    const now = Math.floor(Date.now() / 1000);
+    if (slot.entry.expiresAt < now) {
+      this.entries.delete(key);
+      closeStateSuppressed(slot.entry.state);
+      return null;
+    }
+    if (slot.entry.principalKey !== principalKey) return null;
+    return slot.entry;
+  }
+  /** Remove a session and invoke `state.close?.()`. Returns true on hit. */
+  close(sessionId: Uint8Array): boolean {
+    const key = sessionIdHex(sessionId);
+    const slot = this.entries.get(key);
+    if (!slot || !bytesEqual(slot.id, sessionId)) return false;
+    this.entries.delete(key);
+    closeStateSuppressed(slot.entry.state);
+    return true;
+  }
+  /** Evict every entry past its TTL. Returns the eviction count. */
+  drainExpired(now?: number): number {
+    const cutoff = now ?? Math.floor(Date.now() / 1000);
+    let count = 0;
+    for (const [key, slot] of this.entries) {
+      if (slot.entry.expiresAt < cutoff) {
+        this.entries.delete(key);
+        closeStateSuppressed(slot.entry.state);
+        count++;
+      }
+    }
+    return count;
+  }
+  /** Invoke `state.close?.()` on every live session and clear the registry. */
+  shutdown(): void {
+    const slots = Array.from(this.entries.values());
+    this.entries.clear();
+    for (const slot of slots) closeStateSuppressed(slot.entry.state);
+  }
+  get size(): number {
+    return this.entries.size;
+  }
+}
+function closeStateSuppressed(state: unknown): void {
+  const closer = (state as { close?: unknown })?.close;
+  if (typeof closer !== "function") return;
+  try {
+    (closer as () => unknown).call(state);
+  } catch {
+    // Suppress — eviction must not crash the reaper.
+  }
+}
+// ---------------------------------------------------------------------------
+// Reaper
+// ---------------------------------------------------------------------------
+/** Start a periodic reaper that evicts expired sessions. Returns a stop fn.
+ *  Uses `setInterval().unref()` where available so the reaper does not keep
+ *  the process alive. */
+export function startSessionReaper(registry: SessionRegistry, tickMs = 1000): () => void {
+  const handle = setInterval(() => {
+    try {
+      registry.drainExpired();
+    } catch {
+      // never crash the reaper
+    }
+  }, tickMs);
+  (handle as { unref?: () => void }).unref?.();
+  return () => clearInterval(handle);
+}
+// ---------------------------------------------------------------------------
+// Per-request sticky sink — bridges CallContext to the handler
+// ---------------------------------------------------------------------------
+/** Per-request handle that the HTTP handler installs on the OutputCollector.
+ *  `CallContext.openSession` / `closeSession` / `session` read and mutate
+ *  this object; the handler then emits the resulting headers on the
+ *  response. */
+export interface StickySink {
+  /** True iff the request carried `VGI-Session-Accept: true`. */
+  acceptOpens: boolean;
+  /** Live session state (resumed or just-opened). Null until `openSession`
+   *  or a successful resume populates it. */
+  state: unknown | null;
+  /** Hex session_id for the access log. Populated on resume + open;
+   *  preserved across `closeSession` so close records still carry the id. */
+  sessionId: string | null;
+  /** Set by `openSession` so `process_response` emits `VGI-Session: <token>`. */
+  mintToken: string | null;
+  /** Set by `closeSession` so `process_response` emits `VGI-Session-Close: true`. */
+  closed: boolean;
+  /** Sticky-session lifecycle action observed during dispatch — one of
+   *  "none" / "resume" / "open" / "close". Surfaced on the access log. */
+  action: "none" | "resume" | "open" | "close";
+  /** Bound by the handler: registers `state` in the registry, mints the
+   *  AEAD-sealed token, and stamps `mintToken` + `sessionId`. */
+  _open(state: unknown, ttl: number | undefined): void;
+  /** Bound by the handler: removes the registry entry + invokes
+   *  `state.close?.()`. Idempotent. */
+  _close(): void;
+}
+/** Build a `StickySink` for a request without sticky support — `_open` /
+ *  `_close` throw the same RuntimeError shape as Python's implementation so
+ *  call sites get a clear message. */
+export function unavailableStickySink(): StickySink {
+  return {
+    acceptOpens: false,
+    state: null,
+    sessionId: null,
+    mintToken: null,
+    closed: false,
+    action: "none",
+    _open() {
+      throw new Error("sticky sessions not available on this transport");
+    },
+    _close() {
+      throw new Error("sticky sessions not available on this transport");
+    },
+  };
+}
+// ---------------------------------------------------------------------------
+// Drain handle — operator-facing API for graceful shutdown
+// ---------------------------------------------------------------------------
+/** Operator-facing handle returned by `createHttpHandler` (when sticky is
+ *  enabled) so SIGTERM hooks / worker-exit hooks can drain in-flight
+ *  sessions cleanly. Mirrors Python's `DrainHandle`. */
+export interface DrainHandle {
+  /** Flip the registry's drain flag — subsequent `ctx.openSession` raises
+   *  {@link ServerDrainingError}. Existing sessions continue. */
+  drain(): void;
+  /** Invoke `state.close?.()` on every live session and clear the registry. */
+  shutdown(): void;
+  /** Return whether `drain()` has been invoked. */
+  isDraining(): boolean;
+  /** Test-only / advanced: flip the drain flag back. Production deployments
+   *  only ever drain in one direction; conformance tests use this to clean
+   *  up the fixture between tests. */
+  setDraining(value: boolean): void;
+}
+/** Build a {@link DrainHandle} for *registry*. `stopReaper`, when supplied,
+ *  is invoked by `shutdown()` so the periodic reaper interval is cleared and
+ *  the handle fully releases its resources. */
+export function makeDrainHandle(registry: SessionRegistry, stopReaper?: () => void): DrainHandle {
+  return {
+    drain: () => registry.setDraining(true),
+    shutdown: () => {
+      stopReaper?.();
+      registry.shutdown();
+    },
+    isDraining: () => registry.draining,
+    setDraining: (v) => registry.setDraining(v),
+  };
+}
+// AAD: sticky tokens reuse the existing `computeAad` from `./token.ts` so the
+// principal binding is identical for state and session tokens. The envelope
+// version byte (`TOKEN_VERSION = 1` here vs. `TOKEN_VERSION = 4` for state
+// tokens) keeps the two formats discriminated under the same key.