@volter/twin-tunnel 0.1.0

package/src/tunnel-conformance.ts

@@ -0,0 +1,62 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createTunnelTwinServer } from './tunnel-server.ts';
+
+export type TunnelConformanceReport = { ok: boolean; probes: number; violations: string[] };
+
+/** Literal control-plane probes through the same Bun HTTP/WebSocket adapter callers use. Payload
+ * transport is covered separately, including an unmodified @volter/tunnel SDK integration test. */
+export async function checkTunnelConformance(options: { root?: string } = {}): Promise<TunnelConformanceReport> {
+  const root = options.root ?? mkdtempSync(join(tmpdir(), 'tunnel-conformance-'));
+  const violations: string[] = [];
+  let probes = 0;
+  let socket: WebSocket | undefined;
+  let relay: ReturnType<typeof createTunnelTwinServer> | undefined;
+  const require = (condition: boolean, label: string) => { probes++; if (!condition) violations.push(label); };
+  try {
+    relay = createTunnelTwinServer({ root });
+    const allocated = await fetch(`${relay.url}/tunnel`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}',
+    });
+    if (!allocated.ok) throw new Error(`POST /tunnel transport returned HTTP ${allocated.status}`);
+    const allocationBody = await allocated.json() as Record<string, any>;
+    require(allocated.status === 200 && allocated.headers.get('content-type')?.startsWith('application/json') === true
+      && allocationBody.success === true && typeof allocationBody.result?.hostname === 'string', 'POST /tunnel response');
+
+    const status = await fetch(`${relay.url}/api/status`);
+    const statusBody = await status.json() as Record<string, unknown>;
+    require(status.status === 200 && status.headers.get('content-type')?.startsWith('application/json') === true
+      && statusBody.relay === 'twin-local' && statusBody.tunnels === 0, 'GET /api/status response');
+
+    const missing = await fetch(`${relay.url}/accounts`);
+    const missingBody = await missing.json() as Record<string, unknown>;
+    require(missing.status === 404 && missingBody.error === 'not found', 'unknown route refusal');
+
+    socket = new WebSocket(`${relay.url.replace(/^http/, 'ws')}/ws`);
+    const registered = new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('relay register transport timed out')), 3_000);
+      socket!.addEventListener('message', (event) => {
+        const message = JSON.parse(String(event.data)) as Record<string, unknown>;
+        if (message.type !== 'registered' && message.type !== 'error') return;
+        clearTimeout(timer); resolve(message);
+      });
+      socket!.addEventListener('error', () => { clearTimeout(timer); reject(new Error('relay register transport failed')); }, { once: true });
+    });
+    await new Promise<void>((resolve, reject) => {
+      socket!.addEventListener('open', () => resolve(), { once: true });
+      socket!.addEventListener('error', () => reject(new Error('relay websocket did not open')), { once: true });
+    });
+    socket.send(JSON.stringify({ type: 'register', tunnelId: 'conformance', secret: 'vt_fake_local', authRequired: false }));
+    const registration = await registered;
+    require(registration.type === 'registered' && registration.tunnelId === 'conformance'
+      && registration.url === `${relay.url}/__twin/tunnels/conformance`, 'relay register frame');
+  } catch (error) {
+    violations.push(`conformance probe threw: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    socket?.close();
+    relay?.stop();
+    if (!options.root) rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: violations.length === 0, probes, violations };
+}

package/src/tunnel-connector.ts

@@ -0,0 +1,64 @@
+import { assertBudgetGuardIntact, syncPull, type SyncResource } from '@volter/world-core';
+import { TunnelBudget, TunnelBudgetError, tunnelCallWeight, type TunnelBudgetOptions } from './tunnel-budget.ts';
+
+export type TunnelExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, body?: unknown) => Promise<{ status: number; body: any }>;
+
+export function liveTunnelExecute(token: string, base = 'https://voltertest.xyz', opts: {
+  fetchImpl?: typeof fetch; budget?: TunnelBudget; budgetOptions?: TunnelBudgetOptions;
+} = {}): TunnelExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, TunnelBudget, 'liveTunnelExecute')
+    : new TunnelBudget({ token, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    const headers: Record<string, string> = { authorization: `Bearer ${token}` };
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) { headers['content-type'] = 'application/json'; init.body = JSON.stringify(body); }
+    const weight = tunnelCallWeight(method, path.split('?')[0] ?? path);
+    const reservation = budget.checkBudget(weight);
+    const response = await doFetch(`${base.replace(/\/$/, '')}${path}`, init);
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((v, k) => { responseHeaders[k.toLowerCase()] = v; });
+    const text = await response.text();
+    // An answer the relay ACCEPTED is kept even if recordCall then throws (a back-off beyond the
+    // cap, cooldown already armed): a write that landed is never recorded as failed and redone.
+    try {
+      budget.recordCall(weight, responseHeaders, { status: response.status, reservation });
+    } catch (error) {
+      if (!(error instanceof TunnelBudgetError) || !response.ok) throw error;
+    }
+    let parsed: unknown = {};
+    if (text) { try { parsed = JSON.parse(text); } catch { parsed = { error: text }; } }
+    return { status: response.status, body: parsed };
+  };
+}
+
+export function mapTunnelRelay(status: Record<string, unknown>): SyncResource {
+  return {
+    type: 'relay', id: 'relay:default',
+    // The owned public endpoint is exactly { ok: true, relay: 'cloudflare-do' }. Live socket
+    // counts are a useful twin-local diagnostic, not a real field and therefore never folded.
+    fields: { ok: status.ok === true, relay: String(status.relay ?? 'unknown') },
+  };
+}
+
+export async function pullTunnelRelay(execute: TunnelExecute): Promise<SyncResource[]> {
+  const response = await execute('GET', '/api/status');
+  if (response.status < 200 || response.status >= 300) throw new Error(`tunnel pull status refused: HTTP ${response.status}`);
+  if (!response.body || typeof response.body !== 'object' || Array.isArray(response.body)
+    || response.body.ok !== true || response.body.relay !== 'cloudflare-do'
+    || Object.keys(response.body).length !== 2) {
+    throw new Error('tunnel pull status returned no healthy relay — refusing to fold an empty observation');
+  }
+  return [mapTunnelRelay(response.body)];
+}
+
+export async function syncTunnelFromReal(execute: TunnelExecute, opts: { root?: string; occurredAt?: string } = {}) {
+  const resources = await pullTunnelRelay(execute);
+  const result = syncPull({ service: 'tunnel', resources, occurredAt: opts.occurredAt ?? new Date().toISOString(), ...(opts.root ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+export async function pushPendingTunnelActions(): Promise<never> {
+  throw new Error('tunnel push is not implemented: publishing a local tunnel to a real edge needs an explicit operator-selected provider and credential');
+}