@volter/twin-tunnel 0.1.0

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

@@ -0,0 +1,10 @@
+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 declare function checkTunnelConformance(options?: {
+    root?: string;
+}): Promise<TunnelConformanceReport>;

package/dist/src/tunnel-conformance.js

@@ -0,0 +1,63 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createTunnelTwinServer } from "./tunnel-server.js";
+/** 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 = {}) {
+    const root = options.root ?? mkdtempSync(join(tmpdir(), 'tunnel-conformance-'));
+    const violations = [];
+    let probes = 0;
+    let socket;
+    let relay;
+    const require = (condition, label) => { 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();
+        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();
+        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();
+        require(missing.status === 404 && missingBody.error === 'not found', 'unknown route refusal');
+        socket = new WebSocket(`${relay.url.replace(/^http/, 'ws')}/ws`);
+        const registered = new Promise((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));
+                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((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/dist/src/tunnel-connector.d.ts

@@ -0,0 +1,21 @@
+import { type SyncResource } from '@volter/world-core';
+import { TunnelBudget, type TunnelBudgetOptions } from './tunnel-budget.js';
+export type TunnelExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, body?: unknown) => Promise<{
+    status: number;
+    body: any;
+}>;
+export declare function liveTunnelExecute(token: string, base?: string, opts?: {
+    fetchImpl?: typeof fetch;
+    budget?: TunnelBudget;
+    budgetOptions?: TunnelBudgetOptions;
+}): TunnelExecute;
+export declare function mapTunnelRelay(status: Record<string, unknown>): SyncResource;
+export declare function pullTunnelRelay(execute: TunnelExecute): Promise<SyncResource[]>;
+export declare function syncTunnelFromReal(execute: TunnelExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: any;
+    deltasAppended: any;
+}>;
+export declare function pushPendingTunnelActions(): Promise<never>;

package/dist/src/tunnel-connector.js

@@ -0,0 +1,68 @@
+import { assertBudgetGuardIntact, syncPull } from '@volter/world-core';
+import { TunnelBudget, TunnelBudgetError, tunnelCallWeight } from "./tunnel-budget.js";
+export function liveTunnelExecute(token, base = 'https://voltertest.xyz', opts = {}) {
+    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 = { authorization: `Bearer ${token}` };
+        const init = { 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 = {};
+        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 = {};
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { error: text };
+            }
+        }
+        return { status: response.status, body: parsed };
+    };
+}
+export function mapTunnelRelay(status) {
+    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) {
+    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, opts = {}) {
+    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() {
+    throw new Error('tunnel push is not implemented: publishing a local tunnel to a real edge needs an explicit operator-selected provider and credential');
+}

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

@@ -0,0 +1,109 @@
+import { persistTunnelRelayRegistration, type RelaySession } from './tunnel-twin.js';
+/**
+ * Socket state. ONE shape for both socket kinds because Bun's `serve` takes a single
+ * `WebSocketHandler` data type: a control socket is a registered relay client, a visitor
+ * socket is a browser that opened `wss://…/__twin/tunnels/<id>/<path>` and is being bridged
+ * to that client's local server. `kind` is the discriminator every handler branches on
+ * first — a visitor frame must never reach the control-frame reducer, and a control frame
+ * must never be mistaken for visitor payload.
+ */
+type VisitorState = {
+    connId: string;
+    tunnelId: string;
+    owner: Socket;
+    path: string;
+    headers: Record<string, string>;
+    /** The client has answered `ws-ready`; before that, visitor frames queue rather than vanish. */
+    ready: boolean;
+    queue: Array<{
+        data: Uint8Array;
+        binary: boolean;
+    }>;
+    queuedBytes: number;
+    /** A `ws-close`/`ws-error` already relayed for this connection — do not send a second. */
+    closeRelayed: boolean;
+};
+type ControlData = {
+    kind: 'control' | 'visitor';
+    socketId: string;
+    authoritativeId?: string;
+    session: RelaySession;
+    closed: boolean;
+    /** Where this relay is reached: what a registration hands its client as the tunnel's URL. */
+    publicBase?: string;
+    /** Set iff `kind === 'visitor'`. */
+    visitor?: VisitorState;
+};
+/** A relay socket as the handler uses it: Bun's `ServerWebSocket` locally, a `WebSocketPair` end on a
+ *  hosted World (createTunnelTwinFetch). */
+type Socket = {
+    data: ControlData;
+    send(message: string | Uint8Array): unknown;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+};
+/** Answer an upgrade with a socket carrying `data` (and `headers` on the 101); false when not one. */
+type Upgrade = (request: Request, init: {
+    data: ControlData;
+    headers?: Record<string, string>;
+}) => boolean;
+export declare function createTunnelTwinJwt(payload: {
+    sub?: string;
+    tid?: string;
+    exp?: number;
+    [key: string]: unknown;
+}, secret?: string): string;
+export declare function tunnelControlPathIsReserved(pathname: string): boolean;
+export declare function parseTunnelLoopbackOrigin(origin: string): URL;
+type TunnelTwinOptions = {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    requestTimeoutMs?: number;
+    jwtSecret?: string;
+    /** Match the owned relay's optional REQUIRE_TID=true mode. Default shared SSO accepts a valid
+     * token without tid; a present tid is always bound to its exact tunnel. */
+    requireTid?: boolean;
+    /** Deterministic capability seam for forcing registration-persistence overlap. */
+    persistRegistration?: typeof persistTunnelRelayRegistration;
+};
+/**
+ * THE RELAY, host-neutral: a fetch that may answer an upgrade, and the socket handlers. The loopback
+ * server below runs it under `Bun.serve`; a hosted World runs it with `WebSocketPair`
+ * (createTunnelTwinFetch), since a Worker answers WebSocket upgrades as it answers HTTP.
+ */
+export declare function createTunnelTwinHandler(options?: TunnelTwinOptions): {
+    fetch: (request: Request, bunServer: {
+        upgrade: Upgrade;
+    }) => Promise<Response | undefined>;
+    websocket: {
+        open: (ws: Socket) => void;
+        message: (ws: Socket, raw: string | Uint8Array) => Promise<void>;
+        close: (ws: Socket, code: number, reason?: string) => void;
+    };
+    /** Where the relay is reached when a request does not say (the loopback server's own origin). */
+    setBaseUrl(url: string): void;
+    readonly url: string;
+    registerQuickOrigin(id: string, origin: string): void;
+    quickUrl(id: string): string;
+    authUrl(tunnelId: string, token: string): string;
+    mintToken(tunnelId: string, payload?: Record<string, unknown>): string;
+    stop(): void;
+};
+/** The relay on loopback, under `Bun.serve`. */
+export declare function createTunnelTwinServer(options?: TunnelTwinOptions): {
+    port: number | undefined;
+    url: string;
+    registerQuickOrigin: (id: string, origin: string) => void;
+    quickUrl: (id: string) => string;
+    authUrl: (tunnelId: string, token: string) => string;
+    mintToken: (tunnelId: string, payload?: Record<string, unknown>) => string;
+    stop(): void;
+};
+/**
+ * The relay as a hosted World's twin wire: the same handler, its upgrades answered with a
+ * `WebSocketPair` (a Worker takes a WebSocket as it takes HTTP). Frames are handed to the handler in
+ * arrival order, as `Bun.serve` hands them.
+ */
+export declare function createTunnelTwinFetch(options?: TunnelTwinOptions): (request: Request) => Promise<Response>;
+export {};