@xxgxiaoyu/dsh-session-sync 0.0.0-stage → 0.8.3

package/lib/lan.js

@@ -0,0 +1,213 @@
+/**
+ * The LAN-facing HTTP sync endpoint.
+ *
+ * This is deliberately a separate listener from the GUI web server: the GUI
+ * binds one loopback literal (the app keeps it off the network), while syncing
+ * must be reachable from other machines. It therefore binds 0.0.0.0 on its own
+ * port and only answers requests that present the sync header (and the shared
+ * token when one is configured).
+ *
+ *   GET  /v1/health            liveness probe
+ *   GET  /v1/info              identity + session count
+ *   GET  /v1/sessions          session index (metadata only)
+ *   GET  /v1/sessions/:id      one session: header + replay-validated events
+ *   POST /v1/sessions          import a session from another device
+ */
+import http from 'node:http'
+import { SessionSyncError, sessionSignature } from './sessions.js'
+
+const MAX_BODY_BYTES = 256 * 1024 * 1024
+const SYNC_HEADER = 'x-dsh-session-sync'
+
+function sendJson(res, status, value) {
+  if (res.headersSent) return
+  const body = JSON.stringify(value)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new SessionSyncError('too-large', '会话数据超过 256MB 上限', 413))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (size === 0) {
+        resolve({})
+        return
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch {
+        reject(new SessionSyncError('bad-json', '请求体不是合法 JSON', 400))
+      }
+    })
+    req.on('error', (error) => reject(error))
+  })
+}
+
+export class LanServer {
+  /**
+   * @param {object} options
+   * @param {number} options.port - preferred port; next free ports are tried.
+   * @param {string} [options.token] - optional shared secret.
+   * @param {import('./sessions.js').SessionBridge} options.bridge
+   * @param {() => object} options.info - identity fields for /v1/info.
+   * @param {(message: string) => void} [options.log]
+   */
+  constructor({ port, token, bridge, info, duplicateOf, log }) {
+    this.preferredPort = port
+    this.port = null
+    this.token = token ?? null
+    this.bridge = bridge
+    this.info = info
+    this.duplicateOf = duplicateOf
+    this.log = log ?? (() => {})
+    this.server = null
+  }
+
+  async start() {
+    if (this.server !== null) return this.port
+    const server = http.createServer((req, res) => {
+      this._handle(req, res).catch((error) => {
+        const status = error instanceof SessionSyncError ? error.status : 500
+        const code = error instanceof SessionSyncError ? error.code : 'internal'
+        if (!(error instanceof SessionSyncError)) {
+          this.log(`同步请求失败: ${error?.stack ?? error}`)
+        }
+        sendJson(res, status, { ok: false, error: { code, message: String(error?.message ?? error) } })
+      })
+    })
+    server.on('clientError', (_error, socket) => {
+      try {
+        socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+      } catch {
+        /* ignore */
+      }
+    })
+    this.server = server
+    const base = Number.isInteger(this.preferredPort) && this.preferredPort >= 0 ? this.preferredPort : 47802
+    if (base === 0) {
+      // Explicit ephemeral port (tests, or a NAT'd host that forwards).
+      await listen(server, 0)
+      this.port = server.address().port
+      this.log(`局域网同步服务已监听 0.0.0.0:${this.port}`)
+      return this.port
+    }
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+      const candidate = base + attempt
+      if (candidate > 65535) break
+      try {
+        await listen(server, candidate)
+        this.port = candidate
+        this.log(`局域网同步服务已监听 0.0.0.0:${candidate}`)
+        return candidate
+      } catch (error) {
+        if (error?.code !== 'EADDRINUSE') throw error
+      }
+    }
+    throw new Error(`端口 ${base} 起连续 16 个端口都被占用，无法启动局域网同步服务`)
+  }
+
+  async _handle(req, res) {
+    const url = new URL(req.url ?? '/', 'http://dsh-session-sync.internal')
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'access-control-allow-origin': '*',
+        'access-control-allow-headers': `${SYNC_HEADER}, content-type, x-dsh-session-sync-token`,
+        'access-control-allow-methods': 'GET, POST, OPTIONS',
+      })
+      res.end()
+      return
+    }
+    if (url.pathname === '/v1/health') {
+      sendJson(res, 200, { ok: true, service: 'dsh-session-sync', proto: 1 })
+      return
+    }
+    if (req.headers[SYNC_HEADER] === undefined) {
+      throw new SessionSyncError('unauthorized', '缺少同步请求头', 401)
+    }
+    if (this.token !== null && req.headers['x-dsh-session-sync-token'] !== this.token) {
+      throw new SessionSyncError('unauthorized', '同步口令不匹配', 401)
+    }
+    if (url.pathname === '/v1/info') {
+      sendJson(res, 200, { ok: true, ...this.info() })
+      return
+    }
+    if (url.pathname === '/v1/sessions' && req.method === 'GET') {
+      const limit = Number(url.searchParams.get('limit') ?? '200')
+      const sessions = await this.bridge.list({ limit: Number.isFinite(limit) ? Math.min(Math.max(limit, 1), 500) : 200 })
+      sendJson(res, 200, { ok: true, sessions })
+      return
+    }
+    if (url.pathname.startsWith('/v1/sessions/') && req.method === 'GET') {
+      const id = decodeURIComponent(url.pathname.slice('/v1/sessions/'.length))
+      if (id.length === 0 || id.includes('/')) throw new SessionSyncError('bad-id', '会话 id 无效', 400)
+      const payload = await this.bridge.exportSession(id)
+      sendJson(res, 200, { ok: true, ...payload })
+      return
+    }
+    if (url.pathname === '/v1/sessions' && req.method === 'POST') {
+      const body = await readJsonBody(req)
+      // Dedupe before writing: the same conversation pushed twice (or pushed
+      // back after being pulled) must not become a second local copy. Callers
+      // that really want a copy ask for it explicitly with `?force=1`.
+      const force = url.searchParams.get('force') === '1'
+      if (!force && Array.isArray(body?.events)) {
+        const signature = sessionSignature(body.session, body.events)
+        const duplicate = this.duplicateOf?.(signature) ?? null
+        if (duplicate !== null && duplicate !== undefined) {
+          sendJson(res, 200, { ok: true, skipped: true, id: duplicate, signature })
+          return
+        }
+      }
+      const imported = await this.bridge.importSession(body)
+      this.log(`已接收来自 ${req.socket.remoteAddress} 的会话 → ${imported.id}`)
+      sendJson(res, 200, { ok: true, ...imported })
+      return
+    }
+    throw new SessionSyncError('not-found', `未知接口: ${req.method} ${url.pathname}`, 404)
+  }
+
+  close() {
+    const server = this.server
+    this.server = null
+    this.port = null
+    if (server !== null) {
+      try {
+        server.close()
+        server.closeAllConnections?.()
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+function listen(server, port) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      server.off('error', onError)
+      resolve()
+    }
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(port, '0.0.0.0')
+  })
+}

package/lib/logfile.js

@@ -0,0 +1,80 @@
+/**
+ * Offline helpers for the JSONL session logs DSH keeps in `$DSH_HOME/sessions`.
+ *
+ * `zlib.zstdDecompressSync` only decodes the *first* Zstandard frame of a file,
+ * and DSH appends one frame per write batch, so reading a stored log needs a
+ * frame walker first. Writing back emits a single frame, which every decoder
+ * (including DSH's streaming reader) accepts.
+ */
+import { zstdCompressSync, zstdDecompressSync } from 'node:zlib'
+
+const MAGIC = 0xfd2fb528
+
+/**
+ * Split a buffer into its concatenated Zstandard frames.
+ *
+ * @param {Buffer} buffer - raw `*.jsonl.zstd` content.
+ * @returns {Buffer[]} one slice per frame, in file order.
+ */
+export function splitZstdFrames(buffer) {
+  const frames = []
+  let offset = 0
+  while (offset + 4 <= buffer.length) {
+    const start = offset
+    if (buffer.readUInt32LE(offset) !== MAGIC) {
+      // A torn tail (crash mid-write) is the only legitimate reason to stop;
+      // keep what was decoded so far instead of refusing the whole log.
+      break
+    }
+    offset += 4
+    const descriptor = buffer.readUInt8(offset)
+    offset += 1
+    const fcsFlag = descriptor >> 6
+    const singleSegment = (descriptor & 0x20) !== 0
+    const checksum = (descriptor & 0x04) !== 0
+    const dictFlag = descriptor & 0x03
+    const dictSize = dictFlag === 0 ? 0 : dictFlag === 1 ? 1 : dictFlag === 2 ? 2 : 4
+    if (singleSegment === false) offset += 1
+    offset += dictSize
+    offset += fcsFlag === 0 ? (singleSegment ? 1 : 0) : fcsFlag === 1 ? 2 : fcsFlag === 2 ? 4 : 8
+    for (;;) {
+      if (offset + 3 > buffer.length) return frames
+      const header = buffer.readUIntLE(offset, 3)
+      offset += 3
+      const last = (header & 0x01) !== 0
+      const type = (header >> 1) & 0x03
+      const size = header >> 3
+      if (type === 0) offset += size
+      else if (type === 1) offset += 1
+      else if (type === 2) offset += size
+      else throw new Error('zstd frame uses a reserved block type')
+      if (offset > buffer.length) return frames
+      if (last) break
+    }
+    if (checksum) offset += 4
+    frames.push(buffer.subarray(start, Math.min(offset, buffer.length)))
+    if (offset >= buffer.length) break
+  }
+  return frames
+}
+
+/**
+ * Decode a whole stored log (all frames) into its JSONL text.
+ *
+ * @param {Buffer} buffer - raw `*.jsonl.zstd` content.
+ * @returns {string} newline-delimited JSON text without a trailing newline requirement.
+ */
+export function decodeStoredLog(buffer) {
+  const parts = splitZstdFrames(buffer).map((frame) => zstdDecompressSync(frame))
+  return Buffer.concat(parts).toString('utf8')
+}
+
+/**
+ * Encode JSONL text as a single Zstandard frame.
+ *
+ * @param {string} text - newline-delimited JSON.
+ * @returns {Buffer} compressed bytes ready to write as `session.v4.jsonl.zstd`.
+ */
+export function encodeStoredLog(text) {
+  return zstdCompressSync(Buffer.from(text, 'utf8'))
+}

package/lib/probe.js

@@ -0,0 +1,100 @@
+/**
+ * Quiet HTTP fallback for networks where UDP broadcast (and even unicast UDP)
+ * cannot cross a router or a firewall.
+ *
+ * Only *explicit* targets are probed — a bare IP from the "cross-subnet" box or
+ * a `host:port` from the manual list — never a whole CIDR: 254 hosts times a
+ * port range would be a port scan, not a discovery handshake.
+ *
+ * The probe is a normal `GET /v1/info` against the same API every peer already
+ * exposes on the LAN; the reply carries the device id, so the rest of the
+ * plugin can treat an HTTP-discovered device exactly like a broadcast one.
+ */
+
+/** Sync port the plugin starts on, plus the ports it falls back to (16 tries). */
+export const SYNC_PORT_BASE = 47802
+export const SYNC_PORT_TRIES = 16
+
+export const DEFAULT_SYNC_PORTS = Array.from({ length: SYNC_PORT_TRIES }, (_, index) => SYNC_PORT_BASE + index)
+
+/**
+ * Split `192.168.1.20:47802` into host and port. IPv6 literals in brackets are
+ * rejected on purpose: the LAN API is IPv4-only (the discovery socket is udp4).
+ *
+ * @param {string} spec
+ * @returns {{host: string, port: number|null} | null}
+ */
+export function parseTarget(spec) {
+  const text = String(spec ?? '').trim()
+  if (text.length === 0) return null
+  const match = /^(\d{1,3}(?:\.\d{1,3}){3})(?::(\d{1,5}))?$/.exec(text)
+  if (match === null) return null
+  const host = match[1]
+  const parts = host.split('.').map(Number)
+  if (parts.some((part) => part < 0 || part > 255)) return null
+  if (match[2] === undefined) return { host, port: null }
+  const port = Number(match[2])
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null
+  return { host, port }
+}
+
+/**
+ * Try the candidate ports of one host and return the first `/v1/info` answer.
+ *
+ * @param {string} host
+ * @param {number[]} ports
+ * @param {{token?: string|null, timeoutMs?: number, header?: string}} options
+ * @returns {Promise<{host: string, port: number, info: object} | null>}
+ */
+export async function probeHost(host, ports, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 450
+  const headers = { 'x-dsh-session-sync': '1' }
+  if (typeof options.token === 'string' && options.token.length > 0) headers['x-dsh-session-sync-token'] = options.token
+  // Ports are tried concurrently: a filtered port stalls the full timeout, so
+  // sequential probing of 16 ports would take 7s on a quiet host.
+  const attempt = async (port) => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    timer.unref?.()
+    try {
+      const response = await fetch(`http://${host}:${port}/v1/info`, { headers, signal: controller.signal })
+      if (!response.ok) return null
+      const info = await response.json()
+      if (info !== null && typeof info === 'object' && typeof info.id === 'string' && info.id.length > 0) {
+        return { host, port, info }
+      }
+      return null
+    } catch {
+      return null
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+  const settled = await Promise.allSettled(ports.map((port) => attempt(port)))
+  for (const entry of settled) {
+    if (entry.status === 'fulfilled' && entry.value !== null) return entry.value
+  }
+  return null
+}
+
+/**
+ * Probe a list of explicit targets, stopping at the first answer per host.
+ * Sequential on purpose: a handful of addresses, and we do not want a burst.
+ *
+ * @param {Array<{host: string, port: number|null}>} targets
+ * @param {{token?: string|null, timeoutMs?: number, ports?: number[]}} options
+ * @returns {Promise<Array<{host: string, port: number, info: object}>>}
+ */
+export async function probeTargets(targets, options = {}) {
+  const ports = options.ports ?? DEFAULT_SYNC_PORTS
+  const found = []
+  const seen = new Set()
+  for (const target of targets) {
+    if (target === null || typeof target.host !== 'string') continue
+    if (seen.has(target.host)) continue
+    seen.add(target.host)
+    const result = await probeHost(target.host, target.port === null ? ports : [target.port], options)
+    if (result !== null) found.push(result)
+  }
+  return found
+}

package/lib/repair.js

@@ -0,0 +1,150 @@
+/**
+ * Repair session logs that an older plugin build imported incorrectly.
+ *
+ * Those copies carried the source's inherited `session/end-seed` marker into an
+ * unseeded header, so DSH rejects them with
+ * "released v2 unseeded Session contains an inherited end-seed marker".
+ * Dropping the inherited prefix (the source's own conversation is kept) and
+ * renumbering `seq` makes the log valid again.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { decodeStoredLog, encodeStoredLog } from './logfile.js'
+
+/** @typedef {{ dropped: number, events: number }} RepairReport */
+
+/**
+ * Remove an inherited prefix from decoded JSONL text.
+ *
+ * @param {string} text - decoded log including its header line.
+ * @returns {{ text: string, report: RepairReport } | null} null when nothing needs repair.
+ */
+export function repairLogText(text) {
+  const lines = text.split('\n').filter((line) => line.length > 0)
+  if (lines.length < 2) return null
+  let header
+  try {
+    header = JSON.parse(lines[0])
+  } catch {
+    return null
+  }
+  if (header?.type !== 'session' || header.version !== 4) return null
+  if (header.isSeeded === true) return null
+
+  let cut = -1
+  for (const [index, line] of lines.slice(1).entries()) {
+    let event
+    try {
+      event = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (event?.type === 'session/end-seed' && event.data?.inherited === true) cut = index
+  }
+  if (cut < 0) return null
+
+  const kept = lines.slice(cut + 2).map((line, index) => {
+    const event = JSON.parse(line)
+    return JSON.stringify({ ...event, seq: index })
+  })
+  return {
+    text: [JSON.stringify(header), ...kept].join('\n') + '\n',
+    report: { dropped: cut + 1, events: kept.length },
+  }
+}
+
+/**
+ * Every `session*.jsonl.zstd` under a sessions root, with its lock state.
+ *
+ * @param {string} root - `$DSH_HOME/sessions`.
+ * @returns {{ file: string, dir: string, locked: boolean }[]}
+ */
+export function listStoredLogs(root) {
+  const found = []
+  let slugs = []
+  try {
+    slugs = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return found
+  }
+  for (const slug of slugs) {
+    if (!slug.isDirectory()) continue
+    const slugDir = path.join(root, slug.name)
+    let sessions = []
+    try {
+      sessions = fs.readdirSync(slugDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const session of sessions) {
+      if (!session.isDirectory()) continue
+      const dir = path.join(slugDir, session.name)
+      let files = []
+      try {
+        files = fs.readdirSync(dir)
+      } catch {
+        continue
+      }
+      const file = files.find((name) => name.endsWith('.jsonl.zstd'))
+      if (file === undefined) continue
+      found.push({ file: path.join(dir, file), dir, locked: files.includes('session.lock') })
+    }
+  }
+  return found
+}
+
+/**
+ * Repair one stored log in place, keeping a `*.bak` next to it.
+ *
+ * @param {string} file - path to `session.v4.jsonl.zstd`.
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {RepairReport | null} null when the log needed no repair.
+ */
+export function repairStoredLog(file, options = {}) {
+  const raw = fs.readFileSync(file)
+  let text
+  try {
+    text = decodeStoredLog(raw)
+  } catch {
+    return null
+  }
+  const repaired = repairLogText(text)
+  if (repaired === null) return null
+  if (options.dryRun === true) return repaired.report
+  fs.writeFileSync(`${file}.bak`, raw)
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, encodeStoredLog(repaired.text))
+  fs.renameSync(tmp, file)
+  return repaired.report
+}
+
+/**
+ * Repair every unlocked stored log under a sessions root.
+ *
+ * @param {string} root - `$DSH_HOME/sessions`.
+ * @param {{ dryRun?: boolean, log?: (message: string) => void }} [options]
+ * @returns {{ scanned: number, repaired: number, locked: number }}
+ */
+export function repairStoredSessions(root, options = {}) {
+  const log = options.log ?? (() => {})
+  const summary = { scanned: 0, repaired: 0, locked: 0 }
+  for (const entry of listStoredLogs(root)) {
+    summary.scanned += 1
+    if (entry.locked) summary.locked += 1
+    // `session.lock` is an empty marker DSH leaves behind, not a reliable
+    // "someone is writing" signal — and a corrupt log cannot be open anyway,
+    // because opening it fails validation. Repair it and keep the backup.
+    let report = null
+    try {
+      report = repairStoredLog(entry.file, { dryRun: options.dryRun })
+    } catch (error) {
+      log(`修复失败 ${entry.file}: ${error?.message ?? error}`)
+      continue
+    }
+    if (report === null) continue
+    summary.repaired += 1
+    log(`已修复 ${path.basename(entry.dir)}：丢弃继承前缀 ${report.dropped} 条，保留 ${report.events} 条`)
+  }
+  return summary
+}