dsh-mini-remote 0.1.0

package/lib/server.js

@@ -0,0 +1,590 @@
+/**
+ * 插件自带的轻量 HTTP 服务。
+ *
+ * 为什么不挂在 ctx.webServer 上：DSH 主服务的 host 只能是 127.0.0.1 或
+ * 0.0.0.0（见 dsh-host-webserver 的 Config 声明），没法只绑 Tailscale 虚拟 IP。
+ * 而把主 GUI 暴露到 0.0.0.0 是不可接受的。所以这里自己起一个 node:http，
+ * 绑定地址完全由插件配置决定。
+ *
+ * 传输用 SSE 而不是 WebSocket：
+ *   - 零依赖（不用 ws）
+ *   - EventSource 自带断线重连，移动端切后台回来能自愈
+ *   - 只需要服务端→手机单向推送；手机发指令用普通 POST 即可
+ */
+import { createServer } from 'node:http'
+import { timingSafeEqual } from 'node:crypto'
+import { renderPage, readArt } from './page.js'
+
+const COOKIE = 'dsh_mini_token'
+
+/**
+ * 配置的端口被占时，往后最多再试几个。
+ *
+ * 5 是个折中：够躲开「某个程序占了 3090」这种最常见的冲突，又不会在端口段整个
+ * 被防火墙或别的服务吃掉时，在这里白白等一圈。
+ */
+const PORT_TRIES = 5
+
+/**
+ * 手机上传的单个文件上限。
+ *
+ * DSH 那边**不设**文件大小上限（图片才有），所以这个数是我们的取舍：手机上常见的
+ * 是照片、截图、PDF，几十兆足够覆盖；再大就是视频了，而这条路上没有进度条，传一个
+ * 几百兆的文件会让用户对着一个转圈的界面干等，还不知道要等多久。宁可早一点、
+ * 明确地拒绝，也不要让它悬着。
+ */
+const MAX_UPLOAD = 50 * 1024 * 1024
+
+/** 把字节数说成人话。 */
+function mb(bytes) {
+  return `${Math.round(bytes / 1024 / 1024)} MB`
+}
+const MAX_BODY = 64 * 1024
+const HEARTBEAT_MS = 25_000
+
+/**
+ * 密码试错的限速。
+ *
+ * 默认放开到内网之后，同一个 Wi-Fi 下的任何设备都能连到这个端口。token 是
+ * 128 位随机值，猜不出来；但万一它从别处漏了（比如二维码截图被转发），
+ * 限速是最后一道闸。同一来源一分钟内错 5 次，就挡一分钟。
+ */
+const RATE_WINDOW_MS = 60_000
+const RATE_MAX_FAILURES = 5
+
+/** 定长比较，避免 token 被逐字节试探。 */
+function tokenEquals(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false
+  const ba = Buffer.from(a)
+  const bb = Buffer.from(b)
+  if (ba.length !== bb.length) return false
+  return timingSafeEqual(ba, bb)
+}
+
+/**
+ * 限速分桶用的键。
+ *
+ * 走隧道进来的请求，源地址全是 127.0.0.1（cloudflared 在本机回环上回连我们）。
+ * 要是按源地址分桶，随便谁在公网上错 5 次密码，就能把你自己手机也一起锁在
+ * 外面一分钟；反复触发就是一条拒绝服务的路子。所以隧道流量改按 cloudflared
+ * 填进来的真实客户端地址分桶。
+ *
+ * 隧道流量靠 Host 头识别——cloudflared 会把 Host 设成公网域名。Host 是可以
+ * 伪造的，但伪造它最多只能绕开限速；限速本来就是 128 位 token 之外的第二道
+ * 保险，绕开它照样猜不出 token。
+ */
+export function clientKey(req, tunnelHost) {
+  const host = String(req.headers?.host ?? '').toLowerCase()
+  if (tunnelHost && host && (host === tunnelHost || host.startsWith(`${tunnelHost}:`))) {
+    const forwarded = forwardedClient(req)
+    if (forwarded) return `fwd:${forwarded}`
+  }
+  return `src:${req.socket?.remoteAddress ?? 'unknown'}`
+}
+
+function forwardedClient(req) {
+  const cf = req.headers['cf-connecting-ip']
+  if (typeof cf === 'string' && cf.trim()) return cf.trim()
+  const xff = req.headers['x-forwarded-for']
+  if (typeof xff === 'string' && xff.trim()) return xff.split(',')[0].trim()
+  return null
+}
+
+function parseCookies(header) {
+  const out = {}
+  if (!header) return out
+  for (const part of header.split(';')) {
+    const i = part.indexOf('=')
+    if (i < 0) continue
+    out[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim())
+  }
+  return out
+}
+
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY) {
+        reject(new Error('请求体过大'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8')
+      if (!raw) return resolve({})
+      try {
+        resolve(JSON.parse(raw))
+      } catch {
+        reject(new Error('请求体不是合法 JSON'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+export function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload)
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(body),
+    'Cache-Control': 'no-store',
+  })
+  res.end(body)
+}
+
+/**
+ * @param {object} opts
+ * @param {import('./store.js').createStore extends (...a:any)=>infer R ? R : never} opts.store
+ * @param {{port:number, defaultMode:string}} opts.config
+ * @param {string[]} opts.bindAddresses 要监听的地址；第一个应是 127.0.0.1
+ * @param {string} opts.token
+ * @param {() => string | null} [opts.tunnelHost] 当前公网域名（没开隧道时返回 null），只用于限速分桶
+ * @param {(text:string)=>Promise<{ok:boolean, error?:string, sessionId?:string}>} opts.onInstruction
+ * @param {()=>Promise<{ok:boolean, error?:string, sessionId?:string}>|{ok:boolean, error?:string, sessionId?:string}} opts.onStop
+ * @param {(id:string)=>{ok:boolean, error?:string, sessionId?:string}} opts.onUnqueue
+ * @returns {Promise<{port:number, addresses:string[], failed:{address:string,message:string}[], close:()=>Promise<void>, broadcast:(event:string, data:unknown)=>void}>}
+ */
+export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onStop, onUnqueue, onUpload, log, tree, build }) {
+  /** @type {Set<import('node:http').ServerResponse>} */
+  const clients = new Set()
+
+  // 没传 tree（测试里就是这样，headless 组合里也拿不到那两个服务）时给个空壳，
+  // 导航栏显示「取不到」，遥控本身照常。
+  const nav = tree ?? { listWorkspaces: async () => [], listSessionsOf: async () => null }
+
+  function broadcast(event, data) {
+    const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+    for (const res of clients) {
+      try {
+        res.write(frame)
+      } catch {
+        clients.delete(res)
+      }
+    }
+  }
+
+  function isAuthorized(req, url) {
+    const fromQuery = url.searchParams.get('token')
+    const fromCookie = parseCookies(req.headers.cookie)[COOKIE]
+    const fromHeader = req.headers['x-mini-token']
+    return tokenEquals(fromQuery, token)
+      || tokenEquals(fromCookie, token)
+      || tokenEquals(fromHeader, token)
+  }
+
+  /** 这次请求到底有没有带凭据。没带只是没登录，不算试错。 */
+  function hasCredential(req, url) {
+    return Boolean(
+      url.searchParams.get('token')
+      || parseCookies(req.headers.cookie)[COOKIE]
+      || req.headers['x-mini-token'],
+    )
+  }
+
+  /** 来源 -> { firstAt, count, blockedUntil } */
+  const attempts = new Map()
+
+  function isBlocked(req) {
+    const rec = attempts.get(clientKey(req, tunnelHost?.()))
+    return Boolean(rec && rec.blockedUntil > Date.now())
+  }
+
+  function noteFailure(req) {
+    const key = clientKey(req, tunnelHost?.())
+    const now = Date.now()
+    let rec = attempts.get(key)
+    if (!rec || now - rec.firstAt > RATE_WINDOW_MS) {
+      rec = { firstAt: now, count: 0, blockedUntil: 0 }
+      attempts.set(key, rec)
+    }
+    rec.count += 1
+    if (rec.count >= RATE_MAX_FAILURES) rec.blockedUntil = now + RATE_WINDOW_MS
+    // 别让这张表无限长大；正常情况下它只有个位数条目
+    if (attempts.size >= 512) {
+      for (const [k, v] of attempts) {
+        if (now - v.firstAt > RATE_WINDOW_MS && v.blockedUntil <= now) attempts.delete(k)
+      }
+    }
+  }
+
+  function noteSuccess(req) {
+    attempts.delete(clientKey(req, tunnelHost?.()))
+  }
+
+  async function handle(req, res) {
+    const url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`)
+    const path = url.pathname
+
+    // 试错太多的来源一律挡住，页面和接口都一样——否则可以拿页面接口
+    // 当测密码的探针。
+    if (isBlocked(req)) {
+      sendJson(res, 429, { error: '密码错误次数太多，等一分钟再试。' })
+      return
+    }
+
+    // ---- 页面本身 -------------------------------------------------------
+    // 允许用 ?token=xxx 直接进（二维码扫的就是这个地址），
+    // 校验通过后写 cookie，后续请求就不必再带参数。
+    if (req.method === 'GET' && (path === '/' || path === '/mini' || path === '/mini/')) {
+      const provided = url.searchParams.get('token')
+      if (provided && tokenEquals(provided, token)) {
+        noteSuccess(req)
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Set-Cookie': `${COOKIE}=${encodeURIComponent(token)}; Path=/; Max-Age=31536000; SameSite=Lax`,
+        })
+        res.end(renderPage({ defaultMode: config.defaultMode, build, maxUpload: MAX_UPLOAD }))
+        return
+      }
+      if (isAuthorized(req, url)) {
+        noteSuccess(req)
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+        })
+        res.end(renderPage({ defaultMode: config.defaultMode, build, maxUpload: MAX_UPLOAD }))
+        return
+      }
+      // 带了密码但不对，记一次失败；压根没带不算——那只是打开页面而已
+      if (hasCredential(req, url)) noteFailure(req)
+      // 没带 token：给一个只用于输入 token 的极简页面。
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+      })
+      res.end(renderPage({ defaultMode: config.defaultMode, needsToken: true, build, maxUpload: MAX_UPLOAD }))
+      return
+    }
+
+    // ---- 立绘 -----------------------------------------------------------
+    // 静态资源，但同样要鉴权：它只服务于这个页面，没必要对没登录的人开放。
+    // 页面给 <img> 拼的是 /mini/art/x.webp?token=...&v=<指纹>，所以走 query 就够，
+    // 不依赖 cookie（从门禁页手输 token 进来时是没有 cookie 的）。
+    if (req.method === 'GET' && path.startsWith('/mini/art/')) {
+      if (!isAuthorized(req, url)) {
+        if (hasCredential(req, url)) noteFailure(req)
+        sendJson(res, 401, { error: '未授权：token 不正确' })
+        return
+      }
+      noteSuccess(req)
+      const buf = readArt(path.slice('/mini/art/'.length))
+      if (!buf) {
+        sendJson(res, 404, { error: 'not found' })
+        return
+      }
+      res.writeHead(200, {
+        'Content-Type': 'image/webp',
+        'Content-Length': buf.length,
+        // 地址里带着构建指纹，内容不会在同一个地址下变化，可以放心长缓存。
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      })
+      res.end(buf)
+      return
+    }
+
+    // ---- 其余一律要鉴权 -------------------------------------------------
+    if (!path.startsWith('/mini/api/')) {
+      sendJson(res, 404, { error: 'not found' })
+      return
+    }
+    if (!isAuthorized(req, url)) {
+      // 只有「带了密码但不对」才算试错；压根没带只是没登录。
+      if (hasCredential(req, url)) noteFailure(req)
+      sendJson(res, 401, { error: '未授权：token 不正确' })
+      return
+    }
+    noteSuccess(req)
+
+    // ---- SSE 推送流 ----------------------------------------------------
+    if (req.method === 'GET' && path === '/mini/api/stream') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      })
+      res.write(': connected\n\n')
+      clients.add(res)
+
+      const beat = setInterval(() => {
+        try {
+          res.write(': ping\n\n')
+        } catch {
+          clearInterval(beat)
+          clients.delete(res)
+        }
+      }, HEARTBEAT_MS)
+      if (beat.unref) beat.unref()
+
+      // 连上就先补一次全量状态，手机刷新后不用再单独拉一次。
+      res.write(`event: state\ndata: ${JSON.stringify(store.snapshot())}\n\n`)
+
+      const cleanup = () => {
+        clearInterval(beat)
+        clients.delete(res)
+      }
+      req.on('close', cleanup)
+      res.on('close', cleanup)
+      return
+    }
+
+    if (req.method === 'GET' && path === '/mini/api/state') {
+      sendJson(res, 200, store.snapshot())
+      return
+    }
+
+    // 构建指纹。重启期间旧进程还在应答，这个接口用来确认「跑的是不是新代码」。
+    if (req.method === 'GET' && path === '/mini/api/version') {
+      sendJson(res, 200, { ok: true, build: build ?? 'unknown' })
+      return
+    }
+
+    // latest / history 都取**当前绑定会话**的那一份，不取全局的。
+    if (req.method === 'GET' && path === '/mini/api/latest') {
+      const snap = store.snapshot()
+      sendJson(res, 200, { latest: snap.latest, sessionId: snap.boundSessionId })
+      return
+    }
+
+    if (req.method === 'GET' && path === '/mini/api/history') {
+      sendJson(res, 200, { history: store.snapshot().history })
+      return
+    }
+
+    // 左侧导航栏：先列工作区（便宜），展开某个再取它的会话（要读日志折标题，贵）。
+    // `refresh=1` 是导航栏那个 ⟳ 按钮用的：绕过服务端缓存，真去读一遍。
+    if (req.method === 'GET' && path === '/mini/api/workspaces') {
+      const runningIds = new Set(
+        (store.snapshot().sessions ?? []).filter((s) => s.running).map((s) => s.id),
+      )
+      const workspaces = await nav.listWorkspaces(runningIds, url.searchParams.get('refresh') === '1')
+      sendJson(res, 200, { ok: true, workspaces })
+      return
+    }
+
+    const wsSessions = /^\/mini\/api\/workspaces\/([^/]+)\/sessions$/.exec(path)
+    if (req.method === 'GET' && wsSessions) {
+      const asked = Number(url.searchParams.get('limit'))
+      const limit = Number.isFinite(asked) && asked > 0 ? Math.min(asked, 100) : undefined
+      const result = await nav.listSessionsOf(
+        decodeURIComponent(wsSessions[1]),
+        limit,
+        url.searchParams.get('refresh') === '1',
+      )
+      if (!result) {
+        sendJson(res, 404, { ok: false, error: '没有这个工作区。' })
+        return
+      }
+      sendJson(res, 200, { ok: true, ...result })
+      return
+    }
+
+    // ---- 上传文件 -------------------------------------------------------
+    // 这一段**必须排在下面那个 readBody 前面**：readBody 既只认 JSON，又把请求体
+    // 限死在 64 KB（MAX_BODY）。手机拍一张照片就有好几兆，走它必然失败，而且失败得
+    // 很难看——先是「请求体过大」，用户完全不知道该怎么办。这里直接把请求流喂给
+    // 插件的保存回调，DSH 那边边收边落盘，不在内存里攒整份。
+    if (req.method === 'POST' && path === '/mini/api/upload') {
+      if (!onUpload) {
+        sendJson(res, 503, { error: '这台电脑上的 DSH 没装附件服务，传不了文件。' })
+        return
+      }
+      const name = url.searchParams.get('name') ?? undefined
+      // 客户端声明的长度只能当提示：够长就早点拒绝，省得白白传上来再失败。
+      // 但它不算依据——真正的闸门在下面那道数着字节的闸门上。
+      const declared = Number(url.searchParams.get('size') ?? '')
+      if (Number.isFinite(declared) && declared > MAX_UPLOAD) {
+        sendJson(res, 413, { error: `文件太大了（${mb(declared)}），最多 ${mb(MAX_UPLOAD)}。` })
+        return
+      }
+      let seen = 0
+      async function* capped() {
+        for await (const chunk of req) {
+          seen += chunk.length
+          if (seen > MAX_UPLOAD) throw new Error(`超过 ${mb(MAX_UPLOAD)}`)
+          yield chunk
+        }
+      }
+      try {
+        const result = await onUpload({ data: capped(), name })
+        sendJson(res, 200, { ok: true, ...result })
+      } catch (err) {
+        // 手机中途断了、或者文件太大，都会走到这里。这不是「服务坏了」，
+        // 如实把原因说出来就行。
+        sendJson(res, 400, { error: `文件没存下：${err?.message ?? err}` })
+      }
+      return
+    }
+
+    if (req.method === 'POST') {
+      let body
+      try {
+        body = await readBody(req)
+      } catch (err) {
+        sendJson(res, 400, { error: err.message })
+        return
+      }
+
+      if (path === '/mini/api/send') {
+        const text = typeof body.text === 'string' ? body.text.trim() : ''
+        const uploadIds = Array.isArray(body.uploadIds) ? body.uploadIds : []
+        // 只传文件不写字也是合法的——「这份文件你看一下」本来就是常见用法。
+        // 两样都没有才算空。
+        if (!text && !uploadIds.length) {
+          sendJson(res, 400, { error: '指令为空' })
+          return
+        }
+        const result = await onInstruction(text, uploadIds)
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
+      if (path === '/mini/api/stop') {
+        // 停的是「手机正在遥控的那个会话」，和 send 同一套口径——
+        // 手机上按的停止，不该停掉你在电脑上另开的那个任务。
+        const result = await onStop()
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
+      if (path === '/mini/api/unqueue') {
+        // 撤掉一条还在排队的指令。撤的是「手机正在遥控的那个会话」队列里的那一条，
+        // 和 send / stop 同一套口径。
+        const id = typeof body.id === 'string' ? body.id : ''
+        if (!id) {
+          sendJson(res, 400, { error: 'id 为空' })
+          return
+        }
+        const result = onUnqueue(id)
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
+      if (path === '/mini/api/bind') {
+        const sessionId = typeof body.sessionId === 'string' ? body.sessionId : ''
+        if (!sessionId) {
+          sendJson(res, 400, { error: 'sessionId 为空' })
+          return
+        }
+        store.bind(sessionId)
+        const snap = store.snapshot()
+        broadcast('state', snap)
+        // 顺手把快照放回响应里。手机拿到就能立刻渲染，不用等 SSE 那一趟；
+        // 万一那一刻连接正好断了，切换也还是自足的。
+        sendJson(res, 200, { ok: true, boundSessionId: sessionId, state: snap })
+        return
+      }
+
+      if (path === '/mini/api/presence') {
+        store.markSeen(body.state === 'background' ? 'background' : 'foreground')
+        sendJson(res, 200, { ok: true })
+        return
+      }
+
+      if (path === '/mini/api/heartbeat') {
+        store.markSeen()
+        sendJson(res, 200, { ok: true })
+        return
+      }
+    }
+
+    sendJson(res, 404, { error: 'not found' })
+  }
+
+  const onRequest = (req, res) => {
+    handle(req, res).catch((err) => {
+      log?.warn?.(`dsh-mini-remote: 请求处理失败 ${req.url} — ${err?.message ?? err}`)
+      if (!res.headersSent) {
+        sendJson(res, 500, { error: '内部错误' })
+      } else {
+        res.destroy()
+      }
+    })
+  }
+
+  // 一个地址一个监听。127.0.0.1 排在第一个，配置成 0 端口时由它把真实端口
+  // 定下来，其余地址复用同一个端口。
+  const wanted = Array.isArray(bindAddresses) && bindAddresses.length
+    ? bindAddresses
+    : ['127.0.0.1']
+
+  /**
+   * 在某个端口上把地址逐个绑一遍。
+   *
+   * 逐个绑是刻意的：某个地址绑不上（比如 DHCP 换过 IP、Tailscale 退出了）不该
+   * 拖垮整个服务——其余的照常工作，只是这个地址用不了。
+   */
+  async function bindOn(startPort) {
+    const listeners = []
+    const failed = []
+    let port = startPort
+    for (const address of wanted) {
+      const server = createServer(onRequest)
+      try {
+        await new Promise((resolve, reject) => {
+          server.once('error', reject)
+          server.listen(port, address, resolve)
+        })
+        port = server.address().port
+        listeners.push({ address, server })
+      } catch (err) {
+        failed.push({ address, message: err?.message ?? String(err) })
+        server.close()
+      }
+    }
+    return { listeners, failed, port }
+  }
+
+  // 端口被占就往后挪一个再试。
+  //
+  // 一个非技术用户撞上「3090 被别的程序占了」时，自己是没有办法的：设置界面里
+  // 没有改端口的地方，日志他也不会去看，而端口号对他毫无意义。所以这里自己让开，
+  // 别让他去配。只往后试 PORT_TRIES 个——万一整个端口段都被占，不能在这儿转圈。
+  let listeners = []
+  let failed = []
+  let port = config.port
+  for (let i = 0; i < PORT_TRIES; i += 1) {
+    const attempt = await bindOn(config.port + i)
+    listeners = attempt.listeners
+    failed = attempt.failed
+    port = attempt.port
+    if (listeners.length) {
+      if (i > 0) log?.info?.(`端口 ${config.port} 被占用，改用 ${port}。`)
+      break
+    }
+  }
+
+  if (!listeners.length) {
+    // 分清两种成因：端口被占（用户改个端口就行）和地址都不可用（网络的事）。
+    // 这两件事的下一步动作完全不同，合成一句等于什么都没说。
+    const busy = failed.length > 0 && failed.every((f) => /EADDRINUSE/.test(f.message))
+    throw new Error(busy
+      ? `端口 ${config.port} 往后连续 ${PORT_TRIES} 个都被占用了。`
+      : `没有任何地址能监听：${failed.map((f) => `${f.address}（${f.message}）`).join('、')}`)
+  }
+
+  return {
+    port,
+    /** 真正绑定成功的地址。 */
+    addresses: listeners.map((l) => l.address),
+    /** 想绑但失败的地址，交给调用方决定怎么提示。 */
+    failed,
+    broadcast,
+    close: async () => {
+      for (const res of clients) {
+        try { res.end() } catch { /* 已经断了 */ }
+      }
+      clients.clear()
+      await Promise.all(listeners.map(({ server }) => new Promise((resolve) => {
+        server.close(() => resolve())
+        server.closeAllConnections?.()
+      })))
+    },
+  }
+}