@sparkelf/dsh-plugin-mobile-gateway 0.9.0 → 0.9.2

package/bin/protocol-harness.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Mobile gateway protocol harness.
+ *
+ * Drives a full pairing and Session load the way the App does, so a change can be checked without
+ * a phone in hand. It speaks the wire protocol directly: the App is a shipped binary and the point
+ * is to reproduce its behaviour, not the gateway's own tests.
+ *
+ * Usage:
+ *   protocol-harness.mjs --host 127.0.0.1 --port 7091 --code <pairingCode> [--json]
+ *                        [--expect-history] [--timeout 30000]
+ *
+ * Exit codes: 0 the flow completed, 1 a protocol failure, 2 the flow timed out.
+ */
+import net from 'node:net'
+import { randomBytes } from 'node:crypto'
+
+const argv = process.argv.slice(2)
+let host = '127.0.0.1'
+let port = 7091
+let code = ''
+let json = false
+let expectHistory = false
+let sessionId = ''
+let timeoutMs = 30000
+let path = '/ws/mobile'
+for (let index = 0; index < argv.length; index += 1) {
+  const arg = argv[index]
+  if (arg === '--host') { host = argv[++index]; continue }
+  if (arg === '--port') { port = Number(argv[++index]); continue }
+  if (arg === '--code') { code = argv[++index]; continue }
+  if (arg === '--path') { path = argv[++index]; continue }
+  if (arg === '--timeout') { timeoutMs = Number(argv[++index]); continue }
+  if (arg === '--json') { json = true; continue }
+  if (arg === '--expect-history') { expectHistory = true; continue }
+  if (arg === '--session') { sessionId = argv[++index]; continue }
+  if (arg === '--help' || arg === '-h') {
+    console.log('usage: protocol-harness.mjs --code <pairingCode> [--host 127.0.0.1] [--port 7091] [--path /ws/mobile] [--json] [--expect-history] [--timeout 30000]')
+    process.exit(0)
+  }
+  throw new Error('unknown option: ' + arg)
+}
+
+const report = { steps: [], frames: [], errors: [], ok: false }
+
+function note(step) { report.steps.push(step); if (!json) console.log('  ' + step) }
+function fail(message) { report.errors.push(message); if (!json) console.log('  FAIL ' + message) }
+
+/** One masked client text frame, per RFC 6455 — an unmasked frame is rejected as EXPECTED_MASK. */
+function encodeClientText(text) {
+  const payload = Buffer.from(text, 'utf8')
+  const mask = randomBytes(4)
+  const length = payload.length
+  let header
+  if (length < 126) {
+    header = Buffer.alloc(2)
+    header[1] = 0x80 | length
+  } else if (length < 65536) {
+    header = Buffer.alloc(4)
+    header[1] = 0x80 | 126
+    header.writeUInt16BE(length, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[1] = 0x80 | 127
+    header.writeBigUInt64BE(BigInt(length), 2)
+  }
+  header[0] = 0x81
+  const masked = Buffer.from(payload)
+  for (let index = 0; index < masked.length; index += 1) masked[index] ^= mask[index % 4]
+  return Buffer.concat([header, mask, masked])
+}
+
+const socket = net.connect(port, host)
+let carry = Buffer.alloc(0)
+let handshakeDone = false
+let finished = false
+const sentHistory = new Set()
+
+function finish(ok, why) {
+  if (finished) return
+  finished = true
+  report.ok = ok
+  if (why !== undefined) fail(why)
+  if (json) console.log(JSON.stringify(report, null, 2))
+  else {
+    console.log()
+    console.log('  帧序列: ' + report.frames.map((frame) => frame.kind).join(' -> '))
+    console.log('  结果: ' + (ok ? 'PASS' : 'FAIL'))
+    if (report.errors.length > 0) for (const error of report.errors) console.log('    - ' + error)
+  }
+  try { socket.destroy() } catch {}
+  process.exit(ok ? 0 : 1)
+}
+
+/** Decode server frames; the server never masks, so the payload follows the header directly. */
+function readFrames() {
+  for (;;) {
+    if (carry.length < 2) return
+    const opcode = carry[0] & 0x0f
+    const masked = (carry[1] & 0x80) !== 0
+    let length = carry[1] & 0x7f
+    let offset = 2
+    if (length === 126) { if (carry.length < 4) return; length = carry.readUInt16BE(2); offset = 4 }
+    else if (length === 127) { if (carry.length < 10) return; length = Number(carry.readBigUInt64BE(2)); offset = 10 }
+    const maskLength = masked ? 4 : 0
+    if (carry.length < offset + maskLength + length) return
+    let payload = carry.subarray(offset + maskLength, offset + maskLength + length)
+    if (masked) {
+      const mask = carry.subarray(offset, offset + 4)
+      payload = Buffer.from(payload)
+      for (let index = 0; index < payload.length; index += 1) payload[index] ^= mask[index % 4]
+    }
+    carry = carry.subarray(offset + maskLength + length)
+    if (opcode === 0x8) { note('server closed the connection'); finish(false, 'the server closed before the flow completed'); return }
+    if (opcode === 0x9) { socket.write(Buffer.concat([Buffer.from([0x8a, 0x80]), randomBytes(4)])); continue }
+    if (opcode !== 0x1) continue
+    onFrame(payload.toString('utf8'))
+  }
+}
+
+function onFrame(text) {
+  let frame
+  try { frame = JSON.parse(text) } catch { fail('the server sent a frame that is not JSON'); return }
+  report.frames.push({ kind: frame.kind, bytes: text.length })
+  if (!json) console.log('  <- ' + frame.kind + (frame.kind === 'history' ? ' events=' + String(frame.events?.length ?? 0) + ' cursor=' + String(frame.cursor) + ' bytes=' + String(frame.bytes) : ''))
+  if (frame.kind === 'error') { fail('server error frame: ' + JSON.stringify(frame).slice(0, 160)); return }
+  if (frame.kind === 'paired') { note('paired'); socket.write(encodeClientText(JSON.stringify({ type: 'sessions' }))); return }
+  if (frame.kind === 'sessions') {
+    note('sessions: ' + String(frame.sessions?.length ?? 0))
+    // A named Session lets a caller exercise a Session known to hold events, which the default
+    // first-two choice cannot guarantee.
+    const ids = sessionId !== '' ? [sessionId] : (frame.sessions ?? []).map((session) => session.sessionId).slice(0, 2)
+    for (const id of ids) { sentHistory.add(id); socket.write(encodeClientText(JSON.stringify({ type: 'history', sessionId: id, view: 'conversation' }))) }
+    if (ids.length === 0) { note('no Sessions to request'); finish(true) }
+    return
+  }
+  if (frame.kind === 'history') {
+    note('history for ' + String(frame.sessionId).slice(0, 24) + ': ' + String(frame.events?.length ?? 0) + ' events'
+      + ' cursor=' + String(frame.cursor) + ' hasMore=' + String(frame.hasMore)
+      + ' bytes=' + String(frame.bytes) + ' formatVersion=' + String(frame.historyFormatVersion)
+      + ' view=' + String(frame.view))
+    if ((frame.events?.length ?? 0) > 0) {
+      const sequenced = frame.events.every((event) => typeof event.seq === 'number')
+      if (!sequenced) fail('history carried an event without a seq')
+    }
+    const done = [...sentHistory].every((id) => report.frames.some((seen) => seen.kind === 'history'))
+    if (done) finish(report.errors.length === 0)
+  }
+}
+
+socket.on('connect', () => {
+  const key = randomBytes(16).toString('base64')
+  const protocols = code === '' ? 'dsh-mobile-v1' : 'dsh-mobile-v1, dsh-pair.' + code
+  socket.write(
+    'GET ' + path + ' HTTP/1.1\r\n'
+    + 'Host: ' + host + ':' + String(port) + '\r\n'
+    + 'Upgrade: websocket\r\n'
+    + 'Connection: Upgrade\r\n'
+    + 'Sec-WebSocket-Version: 13\r\n'
+    + 'Sec-WebSocket-Key: ' + key + '\r\n'
+    + 'Sec-WebSocket-Protocol: ' + protocols + '\r\n'
+    + 'X-DSH-Device-ID: harness-' + randomBytes(8).toString('hex') + '\r\n'
+    + '\r\n',
+  )
+})
+
+socket.on('data', (chunk) => {
+  if (!handshakeDone) {
+    carry = Buffer.concat([carry, chunk])
+    const end = carry.indexOf('\r\n\r\n')
+    if (end < 0) return
+    const head = carry.subarray(0, end).toString('utf8')
+    const status = head.split('\r\n')[0]
+    report.handshake = status
+    if (!json) console.log('  handshake: ' + status)
+    if (!head.startsWith('HTTP/1.1 101')) { finish(false, 'handshake refused: ' + status); return }
+    handshakeDone = true
+    note('upgraded')
+    carry = carry.subarray(end + 4)
+  } else {
+    carry = Buffer.concat([carry, chunk])
+  }
+  readFrames()
+})
+
+socket.on('error', (error) => finish(false, 'socket error: ' + error.message))
+setTimeout(() => finish(false, 'timed out after ' + String(timeoutMs) + 'ms'), timeoutMs)

package/bin/session-cache-proxy.mjs

@@ -19,7 +19,7 @@
  *   session-cache-proxy.mjs [--port 7091] [--root /var/lib/dsh-mobile-cache]
  *                           [--upstream http://127.0.0.1:3080] [--ws-path /ws/mobile]
  */
-import { createHash } from 'node:crypto'
+import { createHash, randomBytes } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { createServer, request as httpRequest } from 'node:http'
@@ -34,6 +34,9 @@ let upstream = process.env.DSH_UPSTREAM ?? 'http://127.0.0.1:3080'
 let upstreamHost = process.env.DSH_UPSTREAM_HOST ?? ''
 let wsPath = process.env.DSH_WS_PATH ?? '/ws/mobile'
 let tokensFile = process.env.DSH_CACHE_TOKENS ?? ''
+// When set, every frame's kind and size is logged. Used to see what a client actually asked for and
+// what it was given, which is the only way to tell a client that is waiting from one that is retrying.
+const trace = process.env.DSH_PROXY_TRACE === '1'
 for (let index = 0; index < argv.length; index += 1) {
   const arg = argv[index]
   if (arg === '--port') { port = Number(argv[++index]); continue }
@@ -59,7 +62,64 @@ function tokenHashes() {
   } catch { return new Set() }
 }
 
+/**
+ * Write to a socket that may already be gone.
+ *
+ * `destroyed` is checked before the write but the peer can disappear between the check and the
+ * write, and a write to a closed socket emits an 'error' that, unhandled, ends the process — one
+ * phone hanging up took this proxy down (EPIPE from FrameReader.onFrame). Every write on a
+ * connection the peer controls goes through here.
+ *
+ * @param socket - the stream to write to; may be destroyed or undefined.
+ * @param payload - bytes or text to send.
+ * @returns whether the write was attempted.
+ */
+function safeWrite(socket, payload) {
+  if (socket === undefined || socket === null || socket.destroyed === true || socket.writable === false) return false
+  try {
+    socket.write(payload)
+    return true
+  } catch {
+    try { socket.destroy() } catch {}
+    return false
+  }
+}
+
 const frame = {
+  /**
+   * Wrap an already-serialized payload in one masked text frame.
+   *
+   * The upstream socket from an 'upgrade' event is a raw TCP stream, not a WebSocket object, so
+   * anything written to it must already be framed. Bare JSON corrupts the header instead: the first
+   * payload byte reads as the frame header, and '{' is 0x7B = FIN 0, RSV1 1, RSV2 1, RSV3 1,
+   * opcode 0xB, which the receiver rejects as "RSV2 and RSV3 must be clear".
+   *
+   * It must also be *masked*. In this direction the proxy is the client, and RFC 6455 requires
+   * client-to-server frames to carry a mask — a server rejects an unmasked one with
+   * WS_ERR_EXPECTED_MASK and closes the connection, which the phone sees as a failed login.
+   */
+  encodeClientText(text) {
+    const payload = Buffer.from(text, 'utf8')
+    const mask = randomBytes(4)
+    const length = payload.length
+    let header
+    if (length < 126) {
+      header = Buffer.alloc(2)
+      header[1] = 0x80 | length
+    } else if (length < 65536) {
+      header = Buffer.alloc(4)
+      header[1] = 0x80 | 126
+      header.writeUInt16BE(length, 2)
+    } else {
+      header = Buffer.alloc(10)
+      header[1] = 0x80 | 127
+      header.writeBigUInt64BE(BigInt(length), 2)
+    }
+    header[0] = 0x81
+    const masked = Buffer.from(payload)
+    for (let index = 0; index < masked.length; index += 1) masked[index] ^= mask[index % 4]
+    return Buffer.concat([header, mask, masked])
+  },
   /** Encode one server frame. Payloads are text by construction. */
   encode(value) {
     const payload = Buffer.from(JSON.stringify(value), 'utf8')
@@ -146,6 +206,11 @@ function cachedEvents(sessionId) {
 
 // --- history shaping, mirroring the gateway so a phone cannot tell the difference ---
 //
+// The gateway announces its Session format in the hello frame and the client checks the history
+// answer against it. This must match that announcement, not the newest format the cache happens to
+// hold: the cache stores whatever the desktop wrote, while the handshake is what the client trusts.
+const GATEWAY_HISTORY_FORMAT_VERSION = 3
+//
 // The gateway caps a page at 256 KB on its opening read because every byte travels the desktop's
 // upstream. Here the bytes are already local and the wire is the VPS's own 8.3 MB/s downstream, so
 // the cap only costs round trips: a 10866-event Session would take 118 pages, and at 173 ms RTT
@@ -225,7 +290,11 @@ function historyFrame(message, cached) {
     ...(message.view === 'conversation' ? { view: 'conversation' } : {}),
     ...(capped.hasMore && oldest !== undefined ? { nextBeforeSeq: oldest } : {}),
     cursor: lastSeq,
-    historyFormatVersion: 4,
+    // Must equal what the gateway announced in its own hello frame, which is its
+    // SESSION_FORMAT_VERSION. The client validates the version on the history answer against the one
+    // it was told, so announcing 4 while the gateway says 3 makes it reject every page and stay on
+    // "loading history". The wire can carry either; the handshake is what must agree.
+    historyFormatVersion: GATEWAY_HISTORY_FORMAT_VERSION,
   }
 }
 
@@ -269,7 +338,7 @@ server.on('upgrade', (request, socket, head) => {
     // asked for dsh-mobile-v1 must see it echoed or it will not treat the socket as established.
     const accept = response2.headers['sec-websocket-accept']
     const protocol = response2.headers['sec-websocket-protocol']
-    socket.write(
+    safeWrite(socket,
       'HTTP/1.1 101 Switching Protocols\r\n'
       + 'Upgrade: websocket\r\n'
       + 'Connection: Upgrade\r\n'
@@ -277,11 +346,15 @@ server.on('upgrade', (request, socket, head) => {
       + (protocol === undefined ? '' : 'Sec-WebSocket-Protocol: ' + String(protocol) + '\r\n')
       + '\r\n',
     )
-    if (head.length > 0) liveSocket.write(head)
-    if (liveHead.length > 0) socket.write(liveHead)
+    // `head` holds leftover bytes the client sent after its handshake, already framed.
+    if (head.length > 0) safeWrite(liveSocket, head)
+    if (liveHead.length > 0) safeWrite(socket, liveHead)
 
     const liveReader = new FrameReader((text) => {
-      if (!socket.destroyed) socket.write(frame.encode(JSON.parse(text)))
+      if (trace) console.log('trace upstream->client ' + text.slice(0, 200))
+      let parsed
+      try { parsed = JSON.parse(text) } catch { return }
+      safeWrite(socket, frame.encode(parsed))
     }, () => {})
     liveSocket.on('data', (chunk) => liveReader.push(chunk))
     liveSocket.on('close', () => { if (!socket.destroyed) socket.destroy() })
@@ -290,17 +363,20 @@ server.on('upgrade', (request, socket, head) => {
     // The client's frames are examined: a history request for a cached Session is answered from
     // local storage, and every other frame is forwarded unchanged.
     const clientReader = new FrameReader((text) => {
+      if (trace) console.log('trace client->upstream ' + text.slice(0, 200))
       let message
-      try { message = JSON.parse(text) } catch { liveSocket.write(text); return }
+      try { message = JSON.parse(text) } catch { safeWrite(liveSocket, frame.encodeClientText(text)); return }
       if (message?.type === 'history' && typeof message.sessionId === 'string') {
         let cached
         try { cached = cachedEvents(message.sessionId) } catch { cached = undefined }
         if (cached !== undefined && cached.events.length > 0) {
-          socket.write(frame.encode(historyFrame(message, cached)))
+          const answer = historyFrame(message, cached)
+          if (trace) console.log('trace cache->client history sessionId=' + message.sessionId + ' events=' + String(answer.events.length) + ' bytes=' + String(answer.bytes))
+          safeWrite(socket, frame.encode(answer))
           return
         }
       }
-      liveSocket.write(text)
+      safeWrite(liveSocket, frame.encodeClientText(text))
     }, (kind) => { if (kind === 'close') liveSocket.destroy() })
     socket.on('data', (chunk) => clientReader.push(chunk))
   })
@@ -313,20 +389,17 @@ server.on('upgrade', (request, socket, head) => {
     response2.on('end', () => {
       if (socket.destroyed) return
       const body = Buffer.concat(chunks)
-      socket.write('HTTP/1.1 ' + String(response2.statusCode ?? 502) + ' ' + String(response2.statusMessage ?? 'Bad Gateway') + '\r\nContent-Length: ' + String(body.length) + '\r\nConnection: close\r\n\r\n')
-      socket.end(body)
+      if (safeWrite(socket, 'HTTP/1.1 ' + String(response2.statusCode ?? 502) + ' ' + String(response2.statusMessage ?? 'Bad Gateway') + '\r\nContent-Length: ' + String(body.length) + '\r\nConnection: close\r\n\r\n')) socket.end(body)
     })
   })
   live.on('error', () => {
     if (socket.destroyed) return
-    socket.write('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n')
-    socket.end()
+    if (safeWrite(socket, 'HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n')) socket.end()
   })
   live.setTimeout(20000, () => {
     live.destroy()
     if (!socket.destroyed) {
-      socket.write('HTTP/1.1 504 Gateway Timeout\r\nConnection: close\r\n\r\n')
-      socket.end()
+      if (safeWrite(socket, 'HTTP/1.1 504 Gateway Timeout\r\nConnection: close\r\n\r\n')) socket.end()
     }
   })
   live.end()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-plugin-mobile-gateway",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Mobile gateway for DSH 0.1.7 (Session format 4) with an entry-VPS Session cache. Reads DSH 0.1.7 Session format 4 and lifts retired v3 message shapes on read; a companion cache service plus gateway proxy let a phone fetch history from the entry host at 109 MB/s instead of through the desktop's 0.9 MB/s upstream. Per-session Agent preset selection, live preset updates, and the upstream LAN/pairing protocol are unchanged.",
   "main": "lib/index.mjs",
   "files": [