dsh-zen-remote 2.0.2 → 2.2.0

package/src/relay-client.ts

@@ -49,6 +49,7 @@ import { createHash } from 'node:crypto'
 
 import { compareFingerprints } from './fingerprint.js'
 import type { RelayCompatVerdict } from './fingerprint.js'
+import type { ServerPluginEntry } from './plugin-bridge.js'
 
 /** The one protocol version this client speaks; the handshake verifies it. */
 const RELAY_PROTOCOL = 1
@@ -60,6 +61,10 @@ const UNSHARE_PATH = '/_dsh/zen-remote/relay/v1/unshare'
 const EVENT_RESULT_PATH = '/_dsh/zen-remote/relay/v1/event-result'
 const HTTP_PATH = '/_dsh/zen-remote/relay/v1/http'
 const UPLOAD_PATH = '/_dsh/zen-remote/relay/v1/upload'
+const PLUGIN_PATH = '/_dsh/zen-remote/relay/v1/plugin'
+const PLUGIN_TUNNEL_OPEN_PATH = '/_dsh/zen-remote/relay/v1/plugin-tunnel/open'
+const PLUGIN_TUNNEL_SEND_PATH = '/_dsh/zen-remote/relay/v1/plugin-tunnel/send'
+const PLUGIN_TUNNEL_CLOSE_PATH = '/_dsh/zen-remote/relay/v1/plugin-tunnel/close'
 /** T59: a desktop-client device renaming ITSELF in the gateway's table. */
 const DEVICE_NAME_PATH = '/_dsh/zen-remote/relay/v1/device/name'
 
@@ -179,6 +184,15 @@ export interface RelayHandshake {
    * has and pushes nothing.
    */
   deviceName?: string
+  /**
+   * The server's per-plugin bridge table (PB-2), verbatim from the
+   * handshake. `undefined` from an OLDER server whose handshake carries no
+   * `plugins` field at all — and that distinction is load-bearing:
+   * {@link compareBridges} reads `undefined` as `server-too-old`, while an
+   * empty table means "this server speaks the field, nothing registered"
+   * (`not-on-server`). Never normalized into `{}` here.
+   */
+  plugins?: Record<string, ServerPluginEntry>
 }
 
 /**
@@ -197,14 +211,31 @@ export class RelayError extends Error {
   code: string
   status?: number
   reason?: string
+  /** The host error's sanitized `details` (invoke path): the UI maps
+   *  `details.reason` codes like `MODEL_DOES_NOT_SUPPORT_IMAGES` onto a
+   *  user-facing line — absent details stay undefined. */
+  details?: Record<string, unknown>
 
-  constructor(code: string, message?: string, httpStatus?: number, reason?: string) {
+  constructor(code: string, message?: string, httpStatus?: number, reason?: string, details?: Record<string, unknown>) {
     super(message === undefined ? code : message)
     this.name = 'RelayError'
     this.code = code
     if (httpStatus !== undefined) this.status = httpStatus
     if (reason !== undefined) this.reason = reason
+    if (details !== undefined) this.details = details
+  }
+}
+
+/** The error body's structured `details`, when it is a record of scalars —
+ *  the shape the server's own sanitizer emits. */
+function detailsOf(error: Record<string, unknown>): Record<string, unknown> | undefined {
+  const raw = error.details
+  if (!isRecord(raw)) return undefined
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) out[key] = value
   }
+  return Object.keys(out).length > 0 ? out : undefined
 }
 
 export interface CreateRelayClientOptions {
@@ -333,6 +364,68 @@ export interface RelayClient {
    * `Content-Length`, when it had one) and a timeout there never moves the
    * connection state — the invoke route's rules (T31-fix). */
   upload(options: RelayUploadOptions, signal?: AbortSignal): Promise<RelayHttpResult>
+  /** One bridged-plugin round-trip (PB-4): the coordinates travel in the
+   * x-zr-* headers (PB-3's protocol), no body. Resolves with the UNREAD
+   * fetch Response the moment the headers arrive — the caller streams the
+   * body itself — and EVERY HTTP status is carried verbatim (a refusal's
+   * `x-zen-remote-error` header is the caller's classifier, never an
+   * exception here). The header wait gets the plain request timeout; the
+   * BODY carries no deadline of our own (a stream takes as long as it
+   * takes) — the caller's signal aborts it. Transport deaths judge the
+   * link like every exchange (offline); `requireCredentials` throws the
+   * usual RelayError when nothing is configured. */
+  pluginRequest(request: RelayPluginRequest, signal?: AbortSignal): Promise<Response>
+  /** Open one WebSocket byte tunnel (PB-10): the coordinates travel like a
+   * pluginRequest's, plus the browser handshake's `sec-websocket-*` headers
+   * and any early head bytes (base64). Resolves once the NDJSON stream's
+   * FIRST line named the tunnel id; `frames` then yields the upstream's
+   * raw bytes (each `data` line decoded) and ENDS when the server writes
+   * the `end` line (upstream closed or errored). A refusal (any non-200 or
+   * a missing open line) throws RelayError with the wire's
+   * `x-zen-remote-error` code. */
+  pluginTunnelOpen(
+    request: RelayPluginRequest & {
+      wsHeaders: { 'sec-websocket-key': string; 'sec-websocket-version': string; 'sec-websocket-protocol'?: string; 'sec-websocket-extensions'?: string }
+      head?: string
+    },
+    signal?: AbortSignal,
+  ): Promise<{ tunnel: string; frames: AsyncIterable<Uint8Array> }>
+  /** One ordered upstream chunk (PB-10): `seq` must count from 0 without
+   * gaps — the server answers 409 `tunnel-out-of-order` and closes the
+   * tunnel otherwise. Resolves after the server took the bytes (drain
+   * included). */
+  pluginTunnelSend(tunnel: string, seq: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void>
+  /** Idempotent teardown (PB-10). */
+  pluginTunnelClose(tunnel: string, signal?: AbortSignal): Promise<void>
+}
+
+/** The inputs of one {@link RelayClient.pluginRequest} round-trip (PB-4) —
+ * the PB-3 wire protocol's coordinates, already validated and virtual-id-
+ * restored by the caller. */
+export interface RelayPluginRequest {
+  plugin: string
+  version: string
+  digest: string
+  /** The declared route path, verbatim (never decoded). */
+  path: string
+  /** The re-serialized query string, session id already restored to its
+   * ORIGINAL form. */
+  query: string
+  /** The request method (PB-9); defaults to GET. Must be one the route
+   * declared — the server answers 405 `method-undeclared` otherwise. */
+  method?: string
+  /** The request BODY (PB-9), forwarded verbatim as a stream. `null` means
+   * no body. A streaming body rides chunked (undici forbids hand-set length
+   * headers), so the server's streaming byte count is the size gate. */
+  body?: ReadableStream<Uint8Array> | null
+  /** The body's content type, passed through to the plugin when set. */
+  contentType?: string
+  /** The declared body size, when the local request carried one — sizes the
+   * header-wait budget and nothing else (a streaming body goes chunked). */
+  contentLength?: number
+  /** The one request header passed through to the plugin beside `range`. */
+  accept?: string
+  range?: string
 }
 
 /** The inputs of one {@link RelayClient.upload} round-trip. */
@@ -782,6 +875,25 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     void pushDeviceName(trimmed)
   }
 
+  /**
+   * Canonical JSON for CHANGE DETECTION (PB-2-fix): every object's keys are
+   * sorted, recursively, so two tables that differ only in key order — the
+   * server's map insertion order AND each entry's field order — compare
+   * equal. Anything else (values, entry sets) differs, and JSON.stringify
+   * answers scalars verbatim.
+   */
+  function canonicalJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+    if (value !== null && typeof value === 'object') {
+      const record = value as Record<string, unknown>
+      return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(',')}}`
+    }
+    return JSON.stringify(value)
+  }
+
   /**
    * One QUIET handshake re-run (T59): refreshes the two names while online —
    * no state announcement, no ladder movement, failures silent (the next
@@ -822,7 +934,12 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     if (!isRecord(payload) || payload.ok !== true || payload.relayProtocol !== RELAY_PROTOCOL) return
     // T59-fix: NAMES ONLY. serverId / dshVersion / fingerprints belong to the
     // real handshake (the compat verdict is computed there, on both maps
-    // fresh); a quiet refresh never disturbs them.
+    // fresh); a quiet refresh never disturbs them. PB-2 is the one addition:
+    // the plugin bridge table rides along, because a consent change on the
+    // server must reach an otherwise-idle client without a reconnect — and
+    // unlike the compat verdict it is never cached as a conclusion, the
+    // comparison runs live off this map. A refresh answer WITHOUT the field
+    // keeps whatever the real handshake stored.
     const previous = handshakeInfo
     if (previous === undefined) return
     const serverName = typeof payload.serverName === 'string' ? payload.serverName : previous.serverName
@@ -834,10 +951,27 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     const pushedDuringRefresh = deviceNamePushSeq !== pushSeqAtStart || deviceNamePushBusy || pendingDeviceName !== undefined
     const deviceName = pushedDuringRefresh ? undefined : serverDeviceName
     if (deviceName !== undefined) deviceNameAuthoritative = false
+    // PB-2-fix: compare the incoming table by CONTENT, not by reference — the
+    // payload was parsed fresh, so an unchanged table would otherwise read as
+    // changed on every tick and wake every subscriber (the interceptor's
+    // catalog listener re-pulls on each wake) for nothing. An unchanged table
+    // keeps the PREVIOUS object: identity is the "nothing moved" proof the
+    // changed flag reads.
+    let plugins = previous.plugins
+    if (isRecord(payload.plugins)) {
+      const incoming = payload.plugins as Record<string, ServerPluginEntry>
+      if (canonicalJson(incoming) !== canonicalJson(previous.plugins ?? {})) plugins = incoming
+    }
     let changed = previous.serverName !== serverName
     if (deviceName !== undefined && deviceName !== previous.deviceName) changed = true
+    if (plugins !== previous.plugins) changed = true
     if (!changed) return
-    handshakeInfo = { ...previous, serverName, ...(deviceName !== undefined ? { deviceName } : {}) }
+    handshakeInfo = {
+      ...previous,
+      serverName,
+      ...(deviceName !== undefined ? { deviceName } : {}),
+      ...(plugins !== previous.plugins ? { plugins } : {}),
+    }
     notify()
   }
 
@@ -948,7 +1082,7 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     // 200 {ok:false} envelopes, 400/404/429 answers and anything else
     // unheard-of: the body's error code is the answer, the state is not
     // touched.
-    if (code !== undefined) return new RelayError(code, message, status)
+    if (code !== undefined) return new RelayError(code, message, status, undefined, detailsOf(error))
     // The bad-gateway band carries no relay body of its own — it is what a
     // reverse proxy answers when the gateway behind it is down (nginx: an
     // HTML 502). That IS the offline case, and the e2e contract expects it.
@@ -1131,6 +1265,10 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
         // speaks the field at all (an older server omits it and the client
         // keeps whatever it had).
         ...(infoString(payload.deviceName) !== undefined ? { deviceName: infoString(payload.deviceName) } : {}),
+        // PB-2: the plugin bridge table, kept VERBATIM — an absent or
+        // malformed field stays `undefined` so the comparison reads
+        // server-too-old, never a silently empty table.
+        ...(isRecord(payload.plugins) ? { plugins: payload.plugins as Record<string, ServerPluginEntry> } : {}),
       }
       // Interface compatibility (T42): compare the handshake's group map
       // against this side's own, right here where both are fresh. A compute
@@ -1306,6 +1444,273 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     }
   }
 
+  /**
+   * The bridged-plugin forward (PB-4): headers in, an UNREAD Response out.
+   * Deliberately NOT the shared exchange (it buffers the body): the fetch
+   * resolves on headers, the plain request timeout guards exactly that
+   * wait, and the body streams under the CALLER's signal alone. The
+   * caller's abort listener survives past the header arrival (registered
+   * `once` on the caller's own request-scoped signal, so it dies with that
+   * request) — a browser hang-up mid-stream must tear the relay round-trip
+   * down, and the server's own route then aborts its loopback in turn.
+   */
+  async function pluginRequest(request: RelayPluginRequest, signal?: AbortSignal): Promise<Response> {
+    const creds = requireCredentials()
+    const controller = new AbortController()
+    const onExternalAbort = (): void => {
+      controller.abort()
+    }
+    if (signal !== undefined) {
+      if (signal.aborted) controller.abort()
+      else signal.addEventListener('abort', onExternalAbort, { once: true })
+    }
+    // The header wait gets the plain request timeout for a bodyless call;
+    // with a BODY (PB-9) the budget scales with its declared size like the
+    // upload's (a slow body is a slow call, never a dead link), and the
+    // timeout never moves the connection state.
+    const hasBody = request.body !== undefined && request.body !== null
+    const headerTimeoutMs = hasBody
+      ? sizeBackedTimeoutMs(requestTimeoutMs, request.contentLength)
+      : requestTimeoutMs
+    const timer = setTimeout(() => controller.abort(), headerTimeoutMs)
+    if (typeof timer.unref === 'function') timer.unref()
+    try {
+      let response: Response
+      const init: RequestInit = {
+        // The WIRE method is always POST — the relay route is a POST endpoint
+        // whatever the bridged call is; the bridged method travels in
+        // `x-zr-method` (the server never reads this request line's verb).
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${creds.token}`,
+          // No accept of our own unless the caller carries one: this
+          // header FORWARDS to the plugin (PB-3's protocol), and the
+          // default below exists only so a revoked-token wall still
+          // answers JSON instead of the pairing HTML page.
+          accept: request.accept ?? 'application/json',
+          ...(request.range !== undefined ? { range: request.range } : {}),
+          // PB-9: the body's content type is the OTHER passthrough header.
+          ...(hasBody && request.contentType !== undefined ? { 'content-type': request.contentType } : {}),
+          'x-zr-plugin': request.plugin,
+          'x-zr-plugin-version': request.version,
+          'x-zr-plugin-digest': request.digest,
+          'x-zr-path': request.path,
+          'x-zr-query': request.query,
+          // PB-9: the method travels in the HEADER (the wire protocol's
+          // coordinate), not just the request line — the server reads it
+          // from here, and an omitted header means GET there no matter what
+          // this request line says.
+          'x-zr-method': request.method ?? 'GET',
+        },
+        ...(hasBody ? { body: request.body } : {}),
+        // A wrong server must not walk the pairing token through a redirect.
+        redirect: 'manual',
+        signal: controller.signal,
+      }
+      if (hasBody) {
+        // `duplex: 'half'` is mandatory for a streaming request body; the
+        // resolved RequestInit type hides the field (the DOM-vs-undici
+        // conditional in @types/node), so the assignment carries its own cast.
+        ;(init as { duplex?: string }).duplex = 'half'
+      }
+      try {
+        response = await fetchImpl(`${creds.url}${PLUGIN_PATH}`, init)
+      } catch (error) {
+        // A caller abort is NOT a transport death (PB-9-fix): the caller
+        // aborts exactly when its own request-body gate tripped or the
+        // browser hung up — both are this call's verdicts to answer, never
+        // the link's. Same discipline as the invoke/upload timeouts
+        // (T31-fix/T51-fix): no offline, no failure recorded on the link.
+        if (signal?.aborted) throw abortedError()
+        // A body-bearing call keeps the upload route's rule (T51-fix): the
+        // timeout judges THIS call, not the link — but a real transport
+        // death still reads offline (the reconnect ladder hangs off it).
+        if (hasBody && controller.signal.aborted && !signal?.aborted) {
+          noteFailure('request-timeout')
+          throw new RelayError('request-timeout', `no response within ${headerTimeoutMs} ms`)
+        }
+        noteFailure('offline')
+        setState('offline')
+        throw new RelayError('offline', messageOf(error))
+      }
+      // Headers are here: every status — bridged answer or x-zen-remote-error
+      // refusal — travels to the caller verbatim, body untouched.
+      return response
+    } finally {
+      // The header wait is over (or never started): no deadline on the body.
+      clearTimeout(timer)
+    }
+  }
+
+  /**
+   * The WebSocket byte tunnel's open half (PB-10). The wire: one POST whose
+   * answer is an NDJSON river — first line names the tunnel, `data` lines
+   * carry base64 chunks of the upstream socket's bytes, `ping` lines keep
+   * proxies warm, an `end` line closes the river. Everything after the
+   * headers is line-framed HERE: the caller gets an async iterable of
+   * decoded byte chunks and never sees the framing.
+   */
+  async function pluginTunnelOpen(
+    request: RelayPluginRequest & {
+      wsHeaders: { 'sec-websocket-key': string; 'sec-websocket-version': string; 'sec-websocket-protocol'?: string; 'sec-websocket-extensions'?: string }
+      head?: string
+    },
+    signal?: AbortSignal,
+  ): Promise<{ tunnel: string; frames: AsyncIterable<Uint8Array> }> {
+    const creds = requireCredentials()
+    const payload = {
+      headers: request.wsHeaders,
+      ...(request.head !== undefined && request.head !== '' ? { head: request.head } : {}),
+    }
+    const response = await fetch(`${creds.url}${PLUGIN_TUNNEL_OPEN_PATH}`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${creds.token}`,
+        accept: 'application/x-ndjson',
+        'content-type': 'application/json',
+        'x-zr-plugin': request.plugin,
+        'x-zr-plugin-version': request.version,
+        'x-zr-plugin-digest': request.digest,
+        'x-zr-path': request.path,
+        'x-zr-query': request.query,
+      },
+      body: JSON.stringify(payload),
+      redirect: 'manual',
+      signal,
+    }).catch((error: unknown) => {
+      noteFailure('offline')
+      setState('offline')
+      throw new RelayError('offline', messageOf(error))
+    })
+    if (response.status < 200 || response.status >= 300 || response.body === null) {
+      // The refusal carries its code in the marker header (every
+      // plugin-bridge wall does) — surface it verbatim.
+      const code = response.headers.get('x-zen-remote-error') ?? `http-${response.status}`
+      const bodyText = await response.text().catch(() => '')
+      throw new RelayError(code, bodyText === '' ? code : bodyText, response.status)
+    }
+    let tunnelId: string | undefined
+    let upstreamClosed = false
+    let pendingError: RelayError | undefined
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let lineBuffer = ''
+    const nextLine = async (): Promise<string | null> => {
+      while (true) {
+        const idx = lineBuffer.indexOf('\n')
+        if (idx >= 0) {
+          const line = lineBuffer.slice(0, idx)
+          lineBuffer = lineBuffer.slice(idx + 1)
+          return line
+        }
+        const { done, value } = await reader.read()
+        if (done) {
+          const tail = lineBuffer
+          lineBuffer = ''
+          return tail === '' ? null : tail
+        }
+        lineBuffer += decoder.decode(value, { stream: true })
+      }
+    }
+    // The FIRST line must name the tunnel; anything else up front is a
+    // protocol violation the caller sees as a refused open.
+    const first = await nextLine()
+    if (first !== null) {
+      try {
+        const parsed: unknown = JSON.parse(first)
+        if (typeof parsed === 'object' && parsed !== null && (parsed as { type?: unknown }).type === 'open' &&
+            typeof (parsed as { tunnel?: unknown }).tunnel === 'string') {
+          tunnelId = (parsed as { tunnel: string }).tunnel
+        }
+      } catch {
+        // Falls through to the refusal below.
+      }
+    }
+    if (tunnelId === undefined) {
+      const code = response.headers.get('x-zen-remote-error') ?? 'internal'
+      throw new RelayError(code, `the tunnel open stream never named a tunnel`, response.status)
+    }
+    const frames: AsyncIterable<Uint8Array> = {
+      [Symbol.asyncIterator]() {
+        return {
+          async next(): Promise<IteratorResult<Uint8Array>> {
+            if (upstreamClosed) return { done: true, value: undefined }
+            while (true) {
+              const line = await nextLine()
+              if (line === null) {
+                upstreamClosed = true
+                return { done: true, value: undefined }
+              }
+              let parsed: unknown
+              try {
+                parsed = JSON.parse(line)
+              } catch {
+                continue // a damaged line is skipped, like every NDJSON reader here
+              }
+              if (parsed === null || typeof parsed !== 'object') continue
+              const frame = parsed as { type?: unknown; b64?: unknown; reason?: unknown }
+              if (frame.type === 'data' && typeof frame.b64 === 'string' && frame.b64 !== '') {
+                return { done: false, value: new Uint8Array(Buffer.from(frame.b64, 'base64')) }
+              }
+              if (frame.type === 'end') {
+                upstreamClosed = true
+                if (typeof frame.reason === 'string' && frame.reason === 'upstream-error') {
+                  pendingError = new RelayError('internal', 'the upstream tunnel socket failed')
+                }
+                return { done: true, value: undefined }
+              }
+              // ping and anything unrecognized: skipped.
+            }
+          },
+        }
+      },
+    }
+    void pendingError
+    return { tunnel: tunnelId, frames }
+  }
+
+  async function pluginTunnelSend(tunnel: string, seq: number, bytes: Uint8Array, signal?: AbortSignal): Promise<void> {
+    const creds = requireCredentials()
+    // The body IS the payload — raw bytes, not JSON. The requestInit shape
+    // lives in exchangeRequest's url+init contract: headers hand-built here.
+    await exchangeRequest(
+      `${creds.url}${PLUGIN_TUNNEL_SEND_PATH}`,
+      {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${creds.token}`,
+          accept: 'application/json',
+          'content-type': 'application/octet-stream',
+          'x-zr-tunnel': tunnel,
+          'x-zr-seq': String(seq),
+        },
+        // undici's BodyInit types reject ArrayBufferView here (the DOM face
+        // wins in @types/node) — the cast carries the wire reality.
+        body: new Uint8Array(bytes) as unknown as BodyInit,
+        redirect: 'manual',
+      },
+      signal,
+      true,
+      { timeoutMs: sizeBackedTimeoutMs(requestTimeoutMs, bytes.byteLength), timeoutSetsOffline: false },
+    )
+  }
+
+  async function pluginTunnelClose(tunnel: string, signal?: AbortSignal): Promise<void> {
+    const creds = requireCredentials()
+    await fetch(`${creds.url}${PLUGIN_TUNNEL_CLOSE_PATH}`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${creds.token}`,
+        accept: 'application/json',
+        'x-zr-tunnel': tunnel,
+      },
+      redirect: 'manual',
+      signal,
+    }).catch((error: unknown) => {
+      throw new RelayError('offline', messageOf(error))
+    })
+  }
+
   function openStream(namespace: string, method: string, args: unknown, signal?: AbortSignal): AsyncIterable<unknown> {
     // Eager, not generator-lazy: an unconfigured client fails at CALL time,
     // exactly like connect/invoke, instead of hiding the error inside the
@@ -1510,5 +1915,9 @@ export function createRelayClient(options: CreateRelayClientOptions): RelayClien
     openStream,
     http,
     upload,
+    pluginRequest,
+    pluginTunnelOpen,
+    pluginTunnelSend,
+    pluginTunnelClose,
   }
 }