@mrrisega/dsh-remote 0.3.0

package/clients/dsh-remote/test/bridge-gzip.test.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * bridge 响应 gzip 压缩契约测试(防回归):
+ *   maybeCompressResponse 各分支单测 + 经 handleHttpFrame/doHttp 的本地上游全链路集成。
+ *
+ * 注意:dsh-bridge.mjs 顶层会读 DSH_BRIDGE_* 环境变量并写 .dsh-config.json,
+ * 因此必须先设好 env(设备 id + 临时配置 + 本地上游地址)再动态 import。
+ *
+ * 用法: node --test test/bridge-gzip.test.mjs
+ */
+import assert from "node:assert/strict";
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import test, { after } from "node:test";
+import { gunzipSync } from "node:zlib";
+
+// ---------- 本地假上游(doHttp 全链路用;端口先占再 import,UPSTREAM 在模块加载时固定) ----------
+
+const BIG_JSON = JSON.stringify({
+  ok: true,
+  items: Array.from({ length: 5000 }, (_, i) => ({ id: i, name: `item-${i}`, desc: "x".repeat(20) }))
+});
+const TINY_TEXT = "tiny";
+
+const upstream = http.createServer((req, res) => {
+  if (req.url === "/big-json") {
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    res.end(BIG_JSON);
+    return;
+  }
+  if (req.url === "/tiny") {
+    res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+    res.end(TINY_TEXT);
+    return;
+  }
+  if (req.url === "/no-content") {
+    res.writeHead(204, { "content-type": "text/plain" });
+    res.end();
+    return;
+  }
+  res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+  res.end("hello-upstream");
+});
+
+const tmpDir = mkdtempSync(path.join(os.tmpdir(), "dsh-bridge-gzip-"));
+process.env.DSH_BRIDGE_DEVICE_ID = "dev-gziptest0001";
+process.env.DSH_BRIDGE_CONFIG = path.join(tmpDir, "config.json");
+
+const { maybeCompressResponse, handleHttpFrame } = await new Promise((resolve, reject) => {
+  upstream.listen(0, "127.0.0.1", () => {
+    process.env.DSH_BRIDGE_UPSTREAM = `http://127.0.0.1:${upstream.address().port}`;
+    import("../dsh-bridge.mjs").then(resolve, reject);
+  });
+});
+
+after(() => {
+  try { upstream.close(); } catch {}
+  try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+});
+
+// ---------- maybeCompressResponse 单测 ----------
+
+const BIG = Buffer.from(BIG_JSON, "utf8"); // ≈250KB,可压缩
+const GZIP_ACCEPT = "gzip, deflate, br, zstd";
+
+test("压缩 js/json/css/svg/xml/text:返回 gzip buf + content-encoding 头,解压后与原内容一致", async () => {
+  for (const contentType of [
+    "application/javascript",
+    "application/json; charset=utf-8",
+    "text/css",
+    "image/svg+xml",
+    "application/xml",
+    "text/html; charset=utf-8"
+  ]) {
+    const r = await maybeCompressResponse({
+      buf: BIG, contentType, contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+    });
+    assert.ok(r, `应压缩 ${contentType}`);
+    assert.deepEqual(r.headers, { "content-encoding": "gzip" });
+    assert.ok(r.buf.length < BIG.length, `${contentType}: gzip 后应更小 (${r.buf.length} < ${BIG.length})`);
+    assert.deepEqual(gunzipSync(r.buf), BIG, `${contentType}: 解压后应与原文一致`);
+  }
+});
+
+test("<1KB 不压缩", async () => {
+  const small = Buffer.from("a".repeat(512));
+  const r = await maybeCompressResponse({
+    buf: small, contentType: "text/plain", contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+  });
+  assert.equal(r, null);
+});
+
+test("上游已编码(content-encoding 非空)不叠压缩", async () => {
+  const r = await maybeCompressResponse({
+    buf: BIG, contentType: "application/json", contentEncoding: "gzip", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+  });
+  assert.equal(r, null);
+});
+
+test("text/event-stream 不压缩(SSE 需流式逐条推)", async () => {
+  const r = await maybeCompressResponse({
+    buf: BIG, contentType: "text/event-stream", contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+  });
+  assert.equal(r, null);
+});
+
+test("请求未带 gzip Accept-Encoding 不压缩(保守:手机可能不会解压)", async () => {
+  for (const acceptEncoding of ["", "br", "deflate, br", "identity"]) {
+    const r = await maybeCompressResponse({
+      buf: BIG, contentType: "application/json", contentEncoding: "", acceptEncoding, status: 200, method: "GET"
+    });
+    assert.equal(r, null, `accept-encoding=${JSON.stringify(acceptEncoding)}`);
+  }
+});
+
+test("gzip 后不比原 buf 小就不采用(不可压数据)", async () => {
+  const incompressible = randomBytes(4096); // 随机字节 gzip 只会更大
+  const r = await maybeCompressResponse({
+    buf: incompressible, contentType: "application/json", contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+  });
+  assert.equal(r, null);
+});
+
+test("HEAD / 204 / 304 不压缩(无响应体语义)", async () => {
+  const cases = [
+    { method: "HEAD", status: 200 },
+    { method: "GET", status: 204 },
+    { method: "GET", status: 304 }
+  ];
+  for (const c of cases) {
+    const r = await maybeCompressResponse({
+      buf: BIG, contentType: "application/json", contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: c.status, method: c.method
+    });
+    assert.equal(r, null, JSON.stringify(c));
+  }
+});
+
+test("content-type 缺失/不可压缩类型不压缩", async () => {
+  for (const contentType of ["", "application/octet-stream", "image/png"]) {
+    const r = await maybeCompressResponse({
+      buf: BIG, contentType, contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+    });
+    assert.equal(r, null, `content-type=${JSON.stringify(contentType)}`);
+  }
+});
+
+test("非 Buffer 输入不压缩", async () => {
+  const r = await maybeCompressResponse({
+    buf: "not-a-buffer-".repeat(200), contentType: "text/plain", contentEncoding: "", acceptEncoding: GZIP_ACCEPT, status: 200, method: "GET"
+  });
+  assert.equal(r, null);
+});
+
+// ---------- doHttp 全链路集成(handleHttpFrame → 本地上游) ----------
+
+/** 发一帧并取回 reply。 */
+async function request(frame) {
+  let reply;
+  const sender = (obj) => { reply = obj; return true; };
+  await handleHttpFrame(sender, { type: "http", ...frame });
+  return reply;
+}
+
+test("集成:大 JSON 响应带 gzip 压缩回传(content-encoding: gzip + 可解压)", async () => {
+  const reply = await request({
+    id: "g1",
+    method: "GET",
+    path: "/big-json",
+    headers: { "accept-encoding": GZIP_ACCEPT, "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(reply.headers["content-encoding"], "gzip", "回包 headers 必须带 content-encoding: gzip(否则手机浏览器不解压 → 乱码)");
+  assert.equal(reply.bodyBase64, true);
+  const raw = Buffer.from(reply.body, "base64");
+  assert.ok(raw.length < Buffer.byteLength(BIG_JSON), `压缩后应更小 (${raw.length} < ${Buffer.byteLength(BIG_JSON)})`);
+  assert.equal(gunzipSync(raw).toString("utf8"), BIG_JSON, "gzip body 解压后应与上游原文一致");
+});
+
+test("集成:未带 gzip Accept-Encoding 时不压缩,body 为原文", async () => {
+  const reply = await request({
+    id: "g2",
+    method: "GET",
+    path: "/big-json",
+    headers: { "user-agent": "phone-browser" }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(reply.headers["content-encoding"], undefined);
+  assert.equal(Buffer.from(reply.body, "base64").toString("utf8"), BIG_JSON);
+});
+
+test("集成:小响应(<1KB)不压缩", async () => {
+  const reply = await request({
+    id: "g3",
+    method: "GET",
+    path: "/tiny",
+    headers: { "accept-encoding": GZIP_ACCEPT }
+  });
+  assert.equal(reply.status, 200);
+  assert.equal(reply.headers["content-encoding"], undefined);
+  assert.equal(Buffer.from(reply.body, "base64").toString("utf8"), TINY_TEXT);
+});
+
+test("集成:204 响应不压缩", async () => {
+  const reply = await request({
+    id: "g4",
+    method: "GET",
+    path: "/no-content",
+    headers: { "accept-encoding": GZIP_ACCEPT }
+  });
+  assert.equal(reply.status, 204);
+  assert.equal(reply.headers["content-encoding"], undefined);
+});

package/clients/dsh-remote/test/lifecycle.test.mjs

@@ -0,0 +1,7 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { childStopped } from "../src/lifecycle.mjs";
+
+test("被信号终止的 bridge 子进程可以重新拉起", () => {
+  assert.equal(childStopped({ exitCode: null, signalCode: "SIGTERM" }), true);
+});

package/clients/dsh-remote/test/tunnel-auth.test.mjs

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import http from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BRIDGE = path.join(HERE, "..", "dsh-bridge.mjs");
+
+test("router 以 4003 拒绝过期 JWT 后重新登录再连接", async () => {
+  let loginCount = 0;
+  const api = http.createServer((req, res) => {
+    const body = req.url === "/api/device-login"
+      ? { token: `token-${++loginCount}` }
+      : req.url === "/api/devices"
+        ? { device: { id: "dev-000000000001" } }
+        : { error: "not found" };
+    res.writeHead(req.url === "/api/devices" ? 201 : 200, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  });
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+
+  const registrations = [];
+  const wss = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+  await new Promise((resolve) => wss.once("listening", resolve));
+  const gotTwo = new Promise((resolve) => {
+    wss.on("connection", (ws) => ws.once("message", (raw) => {
+      registrations.push(JSON.parse(raw.toString()).token);
+      if (registrations.length === 1) ws.close(4003, "bad token");
+      if (registrations.length === 2) resolve();
+    }));
+  });
+
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), "dsh-bridge-test-"));
+  const child = spawn(process.execPath, [BRIDGE], {
+    env: {
+      ...process.env,
+      DSH_BRIDGE_API: `http://127.0.0.1:${api.address().port}`,
+      DSH_BRIDGE_TUNNEL_URL: `ws://127.0.0.1:${wss.address().port}`,
+      DSH_BRIDGE_PHONE: "test-account",
+      DSH_BRIDGE_PASSWORD: "test-password",
+      DSH_BRIDGE_DEVICE_ID: "dev-000000000001",
+      DSH_BRIDGE_CONFIG: path.join(tempDir, "config.json")
+    },
+    stdio: "ignore"
+  });
+
+  try {
+    await Promise.race([
+      gotTwo,
+      delay(5_000, null, { ref: false }).then(() => { throw new Error("bridge 未在 5 秒内重连"); })
+    ]);
+    assert.deepEqual(registrations, ["token-1", "token-2"]);
+    assert.equal(loginCount, 2);
+  } finally {
+    child.kill();
+    wss.close();
+    api.close();
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test("router 不再响应心跳时主动断开半开隧道并重连", async () => {
+  const api = http.createServer((req, res) => {
+    const body = req.url === "/api/device-login"
+      ? { token: "token" }
+      : { device: { id: "dev-000000000002" } };
+    res.writeHead(req.url === "/api/devices" ? 201 : 200, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  });
+  await new Promise((resolve) => api.listen(0, "127.0.0.1", resolve));
+
+  let registrations = 0;
+  const wss = new WebSocketServer({ host: "127.0.0.1", port: 0, autoPong: false });
+  await new Promise((resolve) => wss.once("listening", resolve));
+  const reconnected = new Promise((resolve) => {
+    wss.on("connection", (ws) => ws.once("message", () => {
+      if (++registrations === 2) resolve();
+    }));
+  });
+
+  const child = spawn(process.execPath, [BRIDGE], {
+    env: {
+      ...process.env,
+      DSH_BRIDGE_API: `http://127.0.0.1:${api.address().port}`,
+      DSH_BRIDGE_TUNNEL_URL: `ws://127.0.0.1:${wss.address().port}`,
+      DSH_BRIDGE_HEARTBEAT_MS: "100",
+      DSH_BRIDGE_PHONE: "test-account",
+      DSH_BRIDGE_PASSWORD: "test-password",
+      DSH_BRIDGE_DEVICE_ID: "dev-000000000002"
+    },
+    stdio: "ignore"
+  });
+
+  try {
+    await Promise.race([
+      reconnected,
+      delay(4_000, null, { ref: false }).then(() => { throw new Error("bridge 未主动重连半开隧道"); })
+    ]);
+    assert.equal(registrations, 2);
+  } finally {
+    child.kill();
+    wss.close();
+    api.close();
+  }
+});

package/docs/self-hosting.md

@@ -0,0 +1,109 @@
+# Self-Hosting Guide
+
+dsh-remote is designed so that anyone with a server can run the entire remote-control
+stack themselves. The self-hosted edition needs **no account system**: authentication
+is a simple access key, exchanged for short-lived local JWTs by the router.
+
+The self-hosted stack:
+
+```
+手机浏览器
+  └─ /app/ 访问密钥登录(POST /_login) → /_devices 选设备 → /remote/<deviceId>/…
+       │
+  你的 nginx (HTTPS)
+     ├─ /app/        → 静态 PWA (clients/dsh-web/native.html)
+     ├─ /_devices /_quota /_login /remote/ /_bridge / → relay-router
+```
+
+- **relay-router** is the only server component. It registers bridges over
+  WebSocket (`/_bridge`), serves the real-time device list (`/_devices`), proxies
+  HTTP/WS traffic to the right device (`/remote/<deviceId>/…`), and enforces
+  per-plan bandwidth/traffic quotas.
+- Authentication: `DSH_LOCAL_ACCESS_KEYS` (comma-separated) → `POST /_login`
+  → 2h local JWT. The router also accepts SaaS JWTs if
+  `DSH_ENTERPRISE_JWT_SECRET` is set, so a router can serve both modes at once.
+
+## Requirements
+
+- A server with Node.js ≥ 22 and a public HTTPS endpoint (your own domain +
+  certificate). The router itself speaks plain HTTP/WS; terminate TLS at nginx
+  or Caddy in front of it.
+- The phone and the desktop machine must reach the same HTTPS endpoint.
+
+## Option A — Docker (recommended)
+
+```bash
+git clone https://github.com/mrRisega/dsh-remote.git && cd dsh-remote
+
+# 生成密钥与访问密钥(建议 >= 32 字节随机串)
+DSH_LOCAL_JWT_SECRET=$(openssl rand -hex 32) \
+DSH_LOCAL_ACCESS_KEYS=$(openssl rand -base64 9) \
+docker compose up -d
+
+curl -i http://127.0.0.1:13444/_devices    # 401 = 正常(需登录态)
+```
+
+Then put nginx in front (see `deploy/nginx-13443-remote-router.conf` for the
+location blocks and `map $http_upgrade $connection_upgrade`).
+
+## Option B — Bare Node
+
+```bash
+git clone https://github.com/mrRisega/dsh-remote.git && cd dsh-remote
+npm install
+bash deploy/install-open.sh                # 生成 open.env(0600)并启动 router
+```
+
+`install-open.sh` prints your access key and the public entry URL. `open.env`
+holds `DSH_ENTERPRISE_JWT_SECRET`, `DSH_LOCAL_JWT_SECRET`,
+`DSH_LOCAL_ACCESS_KEYS` and `DSH_ROUTER_PORT` — treat it as a credential file.
+
+## Serving the phone app (PWA)
+
+`clients/dsh-web/native.html` is a single-file PWA. Point nginx at it:
+
+```nginx
+location /app/ {
+    alias /srv/dsh-remote/app/;
+    index native.html;
+    add_header Cache-Control "no-cache";
+}
+```
+
+Self-hosted users sign in with the access key (`/app/` login form). The PWA then
+lists online devices from `/_devices` and routes into `dsh web` through the tunnel.
+
+## Connecting the desktop (controlled computer)
+
+```bash
+npx @mrrisega/dsh-remote setup --server wss://你的域名:端口 --key 你的访问密钥
+```
+
+This writes the local config, verifies the key against `/_login`, and installs a
+launchd/systemd service that keeps the bridge alive. The bridge auto-starts when
+`dsh web` (127.0.0.1:3080) is up.
+
+## Configuration reference (open.env)
+
+| Variable | Meaning |
+|---|---|
+| `DSH_ENTERPRISE_JWT_SECRET` | JWT secret (also accepts SaaS tokens; generate randomly) |
+| `DSH_LOCAL_JWT_SECRET` | JWT secret for local (self-hosted) auth |
+| `DSH_LOCAL_ACCESS_KEYS` | Comma-separated access keys for `/_login` |
+| `DSH_ROUTER_PORT` | Listen port (default 13444) |
+| `DSH_ROUTER_QUOTA_FREE_MAX_BPS` etc. | Optional quota overrides (see `packages/relay-router/README.md`) |
+| `DSH_ROUTER_PRO_MAX_ONLINE` | Max simultaneously online devices (default 3) |
+
+## Security notes
+
+- The access key is the root credential of your instance. Keep `open.env` at
+  mode 0600, never commit or share it; rotate it like a password.
+- Always serve `/_login` and the tunnel over HTTPS/WSS in production.
+- Self-hosted mode has no account system: device access is governed by the
+  router's live registry, not by an account database.
+
+## Switching back to SaaS
+
+In the dsh web plugin panel choose connection mode → **Cloud service**, sign in
+with your phone account. Local keys are cleared from the client config; SaaS
+data is unaffected.