@volter/twin-tunnel 0.1.37 → 1.0.1

package/src/semantics/shared.ts

@@ -0,0 +1,78 @@
+// What the relay shares: accounts and their tokens (each by its SHA-256), the tunnel ids they hold, the relay's domain,
+// and a tunnel's control session found among the World's open sockets.
+import type { HandlerContext, SocketSession } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+export type { HandlerContext };
+export const ACCOUNT = '_account';
+export const TUNNEL = '_tunnel';
+// source: spec:/x-reference/domain "voltertest.xyz"
+export const DOMAIN = 'voltertest.xyz';
+/** Labels of the domain that are not tunnels: the relay's own front (`www`, its RESERVED_HOSTS default) and the twins
+ *  cloud Volter serves there. */
+export const RESERVED = new Set(['www', 'twins']);
+
+export const sha256 = (ctx: Pick<HandlerContext, 'crypto'>, v: string): string => ctx.crypto.digest('sha256', v);
+export const tunnelUrl = (id: string): string => `https://${id}.${DOMAIN}`;
+
+
+
+/** The registered control session holding a tunnel, if a client holds it now. */
+export const holder = (ctx: Pick<HandlerContext, 'sockets'>, id: string): SocketSession | undefined =>
+  ctx.sockets('control').find((s) => s.state.registered === true && s.state.tunnelId === id);
+
+export const b64encode = (bytes: Uint8Array): string => btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+export const b64decode = (text: string): Uint8Array<ArrayBuffer> => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+
+// source: spec:/x-reference/auth "The relay answers preflight itself"
+export function cors(request: Request): Record<string, string> {
+  const origin = request.headers.get('origin');
+  return origin ? {
+    'access-control-allow-origin': origin,
+    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+    'access-control-allow-headers': request.headers.get('access-control-request-headers') || 'Content-Type, Authorization, X-Sandbox-Id',
+    'access-control-allow-credentials': 'true',
+  } : {};
+}
+
+/** Request metadata lasts only until the local client starts its reply, on that live connection. */
+export function requests(s: SocketSession): Map<string, Request> {
+  return (s.state.pendingRequests ??= new Map()) as Map<string, Request>;
+}
+
+// source: spec:/x-reference/auth "Build the downstream response headers: drop hop-by-hop + downstream CORS"
+export function responseHeaders(downstream: Headers, request: Request): Headers {
+  const headers = new Headers(downstream);
+  for (const key of ['transfer-encoding', 'connection', 'access-control-allow-origin', 'access-control-allow-methods', 'access-control-allow-headers', 'access-control-allow-credentials', 'x-frame-options']) headers.delete(key);
+  // source: spec:/x-reference/auth "strip CSP frame-ancestors / X-Frame-Options"
+  for (const key of ['content-security-policy', 'content-security-policy-report-only']) {
+    const value = headers.get(key);
+    if (value) {
+      const kept = value.split(';').filter((d) => !d.trim().startsWith('frame-ancestors')).join(';').trim();
+      if (kept) headers.set(key, kept); else headers.delete(key);
+    }
+  }
+  // source: spec:/x-reference/auth "only a downstream response that clearly says"
+  const cache = (headers.get('cache-control') ?? '').toLowerCase();
+  const publicCache = /(?:^|,)\s*public(?:\s|,|$)/.test(cache) && !/(?:^|,)\s*(?:private|no-store|no-cache)(?:\s|,|=|$)/.test(cache);
+  const path = new URL(request.url).pathname;
+  if (!publicCache || path === '/api' || path.startsWith('/api/')) {
+    headers.set('cache-control', 'private, no-store, max-age=0');
+    headers.set('cloudflare-cdn-cache-control', 'no-store');
+    headers.set('cdn-cache-control', 'no-store');
+    const vary = new Set((headers.get('vary') ?? '').split(',').map((v) => v.trim()).filter(Boolean));
+    vary.add('Cookie'); vary.add('Authorization'); headers.set('vary', [...vary].join(', '));
+  }
+  for (const [key, value] of Object.entries(cors(request))) headers.set(key, value);
+  return headers;
+}
+
+// source: spec:/x-reference/relay "Malformed tunnel response"
+export function bufferedBody(text: unknown): Uint8Array<ArrayBuffer> | null | undefined {
+  try { return text ? b64decode(String(text)) : null; } catch { return undefined; }
+}
+
+/** A provisional connection claim prevents two initial registrants passing the live-session decision. */
+export function claimant(ctx: Pick<HandlerContext, 'sockets'>, id: string): SocketSession | undefined {
+  return ctx.sockets('control').find((s) => s.state.superseded !== true && (s.state.registered === true || s.state.registering === true) && s.state.tunnelId === id);
+}

package/src/semantics/sockets.ts

@@ -0,0 +1,127 @@
+// The relay's control channel (the manifest's socket `control`, the kernel's sockets.ts): a client registers a tunnel id
+// with its token and is told the tunnel's URL; then the relay sends it each public request (./../semantics/around.ts)
+// and the client answers with a whole `response` or a stream (`response-start`, `response-chunk`s, `response-end`),
+// which settle the request waiting on it by its `reqId`. Frames as volter-tunnel's protocol.ts defines them.
+import type { HandlerContext, SocketEngine, SocketSession } from '@volter/world-core';
+import { ACCOUNT, b64decode, bufferedBody, claimant, requests, responseHeaders, type Row, sha256, TUNNEL, tunnelUrl } from './shared.ts';
+
+type Streams = Map<string, ReadableStreamDefaultController<Uint8Array>>;
+const obj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+const streams = (s: SocketSession): Streams => (s.state.streams ??= new Map()) as Streams;
+const headersOf = (v: unknown): Headers => { const h = new Headers(); for (const [k, x] of Object.entries(obj(v))) h.set(k, String(x)); return h; };
+
+/** A rejected registration: the error frame, then the close (protocol.ts `ErrorMsg`; tunnel-do's rejection). */
+function reject(s: SocketSession, message: string, code: number, reason: string): void {
+  s.send({ type: 'error', message });
+  s.close(code, reason);
+}
+
+async function register(s: SocketSession, msg: Row, ctx: HandlerContext): Promise<void> {
+  const token = typeof msg.secret === 'string' ? msg.secret : '';
+  const account = token ? ctx.rowsRaw(ACCOUNT).find((a) => a.deleted !== true && a.token_sha256 === sha256(ctx, token)) : undefined;
+  // source: spec:/x-reference/relay "Invalid tunnel secret"
+  if (!account) return reject(s, 'Invalid tunnel secret', 4003, 'Invalid tunnel secret');
+  // the control URL's ?id= names the tunnel (the routing relay's authority), else the register frame's, else one minted
+  // This id names a stored reservation: mint it, then record the reservation with its owner below. ctx.issue is for
+  // issued ids whose subjects the vendor does not store; its empty row would look like another account's reservation.
+  // source: spec:/x-reference/relay "Prefer the ?id= captured at accept (authoritative"
+  const id = String(s.state.tunnelId || msg.tunnelId || ctx.mint(TUNNEL));
+  const held = ctx.row(TUNNEL, id);
+  // source: spec:/x-reference/relay "Tunnel ID reserved"
+  if (held && held._owner !== account.id) return reject(s, `Tunnel ID '${id}' is reserved by another account.`, 4002, 'Tunnel ID reserved');
+  const live = claimant(ctx, id);
+  if (live && live !== s) {
+    // source: spec:/x-reference/relay "Pass { replace: true } to take over."
+    if (msg.replace !== true) return reject(s, `Tunnel ID '${id}' is already in use by another client. Pass { replace: true } to take over.`, 4002, 'Tunnel ID already in use');
+    // source: spec:/x-reference/relay "Tunnel replaced"
+    live.state.superseded = true;
+    live.state.disconnectReason = 'Tunnel replaced';
+    live.state.registered = false;
+    // source: spec:/x-reference/relay "Replaced by new client"
+    live.close(4001, 'Replaced by new client');
+  }
+  Object.assign(s.state, { registering: true, tunnelId: id, account: account.id });
+  try { if (!held) await ctx.record(TUNNEL, { _owner: account.id, reservedAt: ctx.occurredAt }, id); }
+  finally { s.state.registering = false; }
+  if (s.state.superseded === true || !ctx.sockets('control').includes(s)) return;
+  Object.assign(s.state, { registered: true, tunnelId: id, account: account.id, authRequired: msg.authRequired !== false });
+  // source: spec:/x-reference/protocol "Acknowledges a successful registration; carries the public URL + usage."
+  s.send({ type: 'registered', tunnelId: id, url: tunnelUrl(id) });
+}
+
+export const control: SocketEngine<HandlerContext> = {
+  open(s, ctx) {
+    s.state.tunnelId = new URL(ctx.call.request.url).searchParams.get('id') ?? '';
+  },
+  async message(s, data, ctx) {
+    let msg: Row;
+    try { msg = obj(JSON.parse(data)); } catch { return; }
+    if (msg.type === 'register') return register(s, msg, ctx);
+    if (s.state.registered !== true) return;
+    const reqId = String(msg.reqId ?? '');
+    const request = requests(s).get(reqId);
+    // source: spec:/x-reference/protocol "A complete (buffered) response"
+    if (msg.type === 'response') {
+      if (!request) return;
+      const headers = responseHeaders(headersOf(msg.headers), request);
+      const body = bufferedBody(msg.body);
+      // source: spec:/x-reference/relay "Malformed tunnel response"
+      if (body === undefined) s.fulfil(reqId, new Response('Malformed tunnel response', { status: 502, headers }));
+      else s.fulfil(reqId, new Response(request.method === 'HEAD' ? null : body, { status: Number(msg.status || 200), headers }));
+    // source: spec:/x-reference/protocol "Start of a streamed response"
+    } else if (msg.type === 'response-start') {
+      if (!request) return;
+      const status = Number(msg.status || 200);
+      const headers = responseHeaders(headersOf(msg.headers), request);
+      // source: spec:/x-reference/relay "HEAD is bodyless by contract too."
+      if (request.method === 'HEAD' || status === 204 || status === 205 || status === 304) {
+        s.fulfil(reqId, new Response(null, { status, headers }));
+      } else {
+        const body = new ReadableStream<Uint8Array>({ start: (c) => { streams(s).set(reqId, c); }, cancel: () => cancelStream(s, reqId) });
+        armStreamIdle(s, reqId, ctx);
+        s.fulfil(reqId, new Response(body, { status, headers }));
+      }
+    // source: spec:/x-reference/protocol "One streamed response body chunk."
+    } else if (msg.type === 'response-chunk') {
+      const stream = streams(s).get(reqId);
+      if (stream) {
+        try { stream.enqueue(b64decode(String(msg.data ?? ''))); s.fulfil(`idle:${reqId}`, null); armStreamIdle(s, reqId, ctx); }
+        catch { streams(s).delete(reqId); s.fulfil(`idle:${reqId}`, null); }
+      }
+    // source: spec:/x-reference/protocol "End of a streamed response."
+    } else if (msg.type === 'response-end') {
+      const stream = streams(s).get(reqId);
+      streams(s).delete(reqId);
+      s.fulfil(`idle:${reqId}`, null);
+      if (stream) { try { stream.close(); } catch { /* already closed */ } }
+    }
+  },
+  close(s) {
+    s.state.registered = false;
+    s.state.closed = true;
+    for (const c of streams(s).values()) { try { c.error(new Error('Tunnel closed')); } catch { /* already ended */ } }
+    streams(s).clear();
+  },
+};
+
+// source: spec:/x-reference/relay "Idle watchdog for a streaming response"
+function armStreamIdle(s: SocketSession, reqId: string, ctx: HandlerContext): void {
+  // source: spec:/x-reference/relay "120000"
+  void s.expect(`idle:${reqId}`, 120_000).catch(() => { if (ctx.sockets('control').includes(s)) expireStream(s, reqId); });
+}
+
+// source: spec:/x-reference/relay "stream idle timeout"
+function expireStream(s: SocketSession, reqId: string): void {
+  const stream = streams(s).get(reqId);
+  if (!stream) return;
+  streams(s).delete(reqId);
+  try { stream.error(new Error('stream idle timeout')); } catch { /* already closed */ }
+  s.send({ type: 'request-abort', reqId });
+}
+
+// source: spec:/x-reference/protocol "The relay asks the client to abort an in-flight request."
+function cancelStream(s: SocketSession, reqId: string): void {
+  streams(s).delete(reqId);
+  s.fulfil(`idle:${reqId}`, null);
+  s.send({ type: 'request-abort', reqId });
+}

package/src/semantics/states.ts

@@ -0,0 +1,3 @@
+// The relay's state rulings (architecture, "State"): a tunnel id is held by the account that registered it first; a
+// session's registration is the connection's, never World state.
+export const states = {};

package/src/server.ts

@@ -0,0 +1,10 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp, type PackFetchOptions } from '@volter/world-core';
+import { createTunnelFetch } from './fetch.ts';
+
+export async function createTunnelTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const fetch = createTunnelFetch(options);
+  // the vendor's sockets, when its manifest declares any (the kernel's sockets.ts)
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch, ...(fetch.upgrade ? { upgrade: fetch.upgrade } : {}) });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/tunnel-budget.d.ts

@@ -1,21 +0,0 @@
-import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions } from '@volter/world-core';
-export declare const TUNNEL_BUDGET_WINDOW_MS = 60000;
-export declare const TUNNEL_BUDGET_CEILING = 60;
-export declare const TUNNEL_CALL_WEIGHTS: {
-    readonly create: 3;
-    readonly other: 2;
-};
-/** Cloudflare documents a 200 concurrent in-flight request cap for Quick Tunnels, but no scalar
- * create-control-API rate. Volter's relay publishes data-plane and signup rates, not a status-read
- * rate. The connector ledger is account-wide, so it uses the kernel's conservative fallback. */
-export declare const TUNNEL_RATE_BUDGET: RateBudgetDeclaration;
-export declare const tunnelCallWeight: (method: string, path: string) => number;
-export declare const tunnelBudgetPath: (opts?: {
-    root?: string;
-    token?: string;
-} | string) => string;
-export type TunnelBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
-export declare class TunnelBudget extends RateBudget {
-    constructor(opts?: TunnelBudgetOptions);
-}
-export { RateBudgetError as TunnelBudgetError } from '@volter/world-core';

package/dist/src/tunnel-budget.js

@@ -1,26 +0,0 @@
-import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
-const VENDOR = 'tunnel';
-export const TUNNEL_BUDGET_WINDOW_MS = 60_000;
-export const TUNNEL_BUDGET_CEILING = 60;
-export const TUNNEL_CALL_WEIGHTS = { create: 3, other: 2 };
-/** Cloudflare documents a 200 concurrent in-flight request cap for Quick Tunnels, but no scalar
- * create-control-API rate. Volter's relay publishes data-plane and signup rates, not a status-read
- * rate. The connector ledger is account-wide, so it uses the kernel's conservative fallback. */
-export const TUNNEL_RATE_BUDGET = {
-    windowMs: TUNNEL_BUDGET_WINDOW_MS,
-    ceiling: TUNNEL_BUDGET_CEILING,
-    defaultWeight: TUNNEL_CALL_WEIGHTS.other,
-    maxRetryAfterSeconds: 300,
-    rules: [{ match: '^POST /tunnel$', weight: TUNNEL_CALL_WEIGHTS.create }],
-    reason: 'Cloudflare Quick Tunnels documentation (developers.cloudflare.com, fetched 2026-08-20) publishes a 200 concurrent in-flight data-plane cap but no scalar quick-control creation rate; the first-party cloudflared source POSTs /tunnel once per quick session. The owned volter-tunnel relay (a5abc628, 2026-08-20) publishes data-plane and signup limits, not a status-read rate. This account-wide connector therefore uses the kernel fallback: 60 weighted units/60s, reads weight 2 (30/min) and tunnel allocation weight 3 (20/min), never more permissive than an undeclared vendor.',
-};
-declareRateBudget(VENDOR, TUNNEL_RATE_BUDGET);
-export const tunnelCallWeight = (method, path) => rateBudgetWeight(VENDOR, `${method.toUpperCase()} ${path}`);
-export const tunnelBudgetPath = (opts = {}) => {
-    const value = typeof opts === 'string' ? { root: opts } : opts;
-    return rateBudgetPath({ ...value, vendor: VENDOR });
-};
-export class TunnelBudget extends RateBudget {
-    constructor(opts = {}) { super({ ...opts, vendor: VENDOR }); }
-}
-export { RateBudgetError as TunnelBudgetError } from '@volter/world-core';

package/dist/src/tunnel-capabilities.d.ts

@@ -1,4 +0,0 @@
-import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
-export declare const TUNNEL_CAPABILITIES: CapabilitySpec[];
-export declare const TUNNEL_AREAS: readonly ["cloudflare_quick", "cloudflare_managed", "volter_control", "volter_http", "volter_websocket", "volter_auth", "volter_reservations", "volter_accounts", "volter_usage", "volter_signup", "volter_inspector", "volter_management", "connector"];
-export declare function tunnelCapabilities(): Promise<CapabilityReport>;