@volter/twin-tunnel 1.0.0 → 1.0.1

package/src/semantics/sockets.ts

@@ -3,7 +3,7 @@
 // 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, holder, type Row, sha256, TUNNEL, tunnelUrl, validId } from './shared.ts';
+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 : {});
@@ -19,24 +19,33 @@ function reject(s: SocketSession, message: string, code: number, reason: string)
 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;
-  if (!account) return reject(s, 'Tunnel rejected: credential is invalid or revoked. On an owner-authenticated device, run "volter-tunnel tokens" and restore this host token, or sign in again on the host.', 4003, 'badToken');
+  // 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));
-  if (!validId(id)) return reject(s, `Tunnel rejected: invalid tunnel id ${id}`, 4029, 'invalidId');
   const held = ctx.row(TUNNEL, id);
-  // Where the documentation stops: a tunnel id another account holds is refused, as the relay's reservation refuses it
-  if (held && held._owner !== account.id) return reject(s, `Tunnel rejected: ${id} is reserved by another account`, 4029, 'reserved');
-  const live = holder(ctx, 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) {
-    // Where the documentation stops: a live registration of the id is refused unless this one replaces it
-    if (msg.replace !== true) return reject(s, `Tunnel rejected: ${id} is already connected`, 4029, 'inUse');
+    // 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');
   }
-  if (!held) await ctx.record(TUNNEL, { _owner: account.id, reservedAt: ctx.occurredAt }, id);
+  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) });
 }
 
@@ -50,20 +59,69 @@ export const control: SocketEngine<HandlerContext> = {
     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') {
-      s.fulfil(reqId, new Response(msg.body ? b64decode(String(msg.body)) as Uint8Array<ArrayBuffer> : null, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+      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') {
-      const body = new ReadableStream<Uint8Array>({ start: (c) => { streams(s).set(reqId, c); } });
-      s.fulfil(reqId, new Response(body, { status: Number(msg.status ?? 502), headers: headersOf(msg.headers) }));
+      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') {
-      streams(s).get(reqId)?.enqueue(b64decode(String(msg.data ?? '')));
+      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') {
-      streams(s).get(reqId)?.close();
+      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 });
+}