@podway/relay 0.2.4 → 0.2.6

package/FAQ.md

@@ -33,15 +33,31 @@ normal login shell. If `npx` works after you log in but fails in a script, set
 
 ## How do I make the relay survive a reboot?
 
-The relay itself does not need root. Use whichever startup mechanism your host
-provides:
+The relay itself does not need root. For a machine that starts it at boot, **install it once** instead
+of running it through `npx`: `npx` unpacks the package into a cache on every start, and a start that is
+cut off (a reboot, two starts at once) can leave that cache broken so the next start fails with
+`ENOTEMPTY`.
+
+```bash
+npm i -g @podway/relay@latest      # update later with the same command
+relay status                       # check it runs
+```
+
+If `npm i -g` says "permission denied", give npm a folder in your home first:
+
+```bash
+npm config set prefix ~/.npm-global
+echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.profile && . ~/.profile
+```
+
+Then use whichever startup mechanism your host provides:
 
 - **Synology DSM**: Go to Control Panel → Task Scheduler → Create →
   Triggered Task → User-defined script, then choose **Boot-up**. Run:
 
   ```bash
-  export PATH=/path/to/node/bin:$PATH   # wherever npx actually lives, see above
-  npx @podway/relay@latest start --gateway <url> --accept
+  export PATH=$HOME/.npm-global/bin:/path/to/node/bin:$PATH   # where relay and node live
+  relay start --gateway <url> --accept
   ```
 
 - **A systemd host**: If you have root, create a service that runs the same
@@ -52,6 +68,9 @@ provides:
 The scheduler only needs to run the command once. `start` moves the relay into
 the background and exits.
 
+It is safe to run `relay stop` first, "just in case": it returns within a few seconds even on a
+slow NAS (it waits up to 5 s for the old relay to exit, then force-stops it).
+
 ## Do I need to pass `--code` again every time it starts?
 
 No. `--code` is only used for the first pairing. The relay saves a reconnect
@@ -85,3 +104,33 @@ every authorized SSH user, not only Podway, and requires administrator access:
 sudo sed -i 's/^AllowTcpForwarding no/AllowTcpForwarding yes/' /etc/ssh/sshd_config
 sudo systemctl restart sshd   # or: synosystemctl restart sshd, on some DSM versions
 ```
+
+## `npm error code ENOTEMPTY` when I run `npx @podway/relay`
+
+A previous `npx` run was cut off and left its cache folder half-written. Delete the cache (npm downloads
+it again) and switch to the installed relay (see "How do I make the relay survive a reboot?"):
+
+```bash
+rm -rf ~/.npm/_npx
+npm i -g @podway/relay@latest
+relay status
+```
+
+## How do I see what the relay did without the web dashboard?
+
+`relay status` prints it as tables — useful on a NAS where the dashboard's local page is out of reach:
+
+```
+STATE     UPTIME    LINK           REQ 24h   OK%  DATA
+running   2d 4h     connected          412   98%  61 MB
+
+POD                          REQ   OK%  LAST
+afisha crawler               301   99%  12 s ago
+crypto sail club              88   93%  3 min ago
+
+SITE                         REQ   OK%  LAST ERROR
+polymarket.com               145   97%  403 refused, 26 min ago
+```
+
+`--since 1h|24h|7d` changes the window, `--all` shows every row, `--json` is for scripts. DATA counts
+tunnel traffic only (plain fetches have no size recorded).

package/README.md

@@ -46,7 +46,7 @@ Once started, the relay runs in the background and handles both modes.
 | `relay start --code <code> --gateway <url> --accept` | start the relay in the background |
 | `relay login <domain>` | allow signed-in fetches for one domain |
 | `relay dashboard` | open the local command center |
-| `relay status` | show the relay, gateway, and signed-in site status |
+| `relay status` | the relay at a glance, then requests per pod and per site (OK %, last error); `--since 1h\|24h\|7d`, `--all`, `--json` |
 | `relay stop` | stop it |
 | `relay reset` | remove saved sessions, logins, and pairing |
 

package/dist/main.js

@@ -1,20 +1,16 @@
 #!/usr/bin/env node
-import WebSocket from "ws";
 import { spawn } from "node:child_process";
 import { writeFileSync, readFileSync, unlinkSync, mkdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { load, save, addLoginDomain, resetProfile, profileDir, pidFile, dashboardRuntimeFile, isDomainBlocked, isPodPaused, revokeLoginDomain, } from "./config.js";
-import { RelayClient } from "./relay-client.js";
-import { RelayTunnel } from "./relay-tunnel.js";
-import { keepAwake } from "./keep-awake.js";
-import { BrowserFetcher } from "./browser-fetcher.js";
-import { RelayEventStore } from "./audit.js";
-import { serveDashboard } from "./dashboard.js";
-import { RelayRuntime } from "./runtime.js";
-import { attachHeartbeat } from "./heartbeat.js";
 import { DISCLOSURE } from "./disclosure.js";
 import { c, rows } from "./colors.js";
 import { normalizeDomain } from "./domain.js";
+import { stopPid } from "./stop.js";
+import { renderStatus, statusData, WINDOWS } from "./status.js";
+// Only `start` (the daemon) and `dashboard` need the transport, browser and dashboard modules.
+// They load lazily so `relay stop` / `relay status` stay quick on a slow NAS CPU (a DS118 runs the
+// boot task's `relay stop` before every start).
 /**
  * `relay` — one command starts a background relay; login/dashboard/stop modify it
  * through disk state (config, audit log, pidfile). No per-request approval: once
@@ -126,6 +122,10 @@ async function cmdStart(a) {
     log("");
 }
 async function runDaemon(a) {
+    const [{ default: WebSocket }, { RelayClient }, { RelayTunnel }, { keepAwake }, { BrowserFetcher }, { RelayEventStore }, { serveDashboard }, { RelayRuntime }, { attachHeartbeat }] = await Promise.all([
+        import("ws"), import("./relay-client.js"), import("./relay-tunnel.js"), import("./keep-awake.js"), import("./browser-fetcher.js"),
+        import("./audit.js"), import("./dashboard.js"), import("./runtime.js"), import("./heartbeat.js"),
+    ]);
     const gateway = arg(a, "--gateway");
     const code = arg(a, "--code") ?? "";
     const browser = new BrowserFetcher({
@@ -145,10 +145,12 @@ async function runDaemon(a) {
         if (stopping)
             return;
         stopping = true;
+        // Never hang on the way out: whatever the cleanup does, the process is gone in 4 s.
+        setTimeout(() => process.exit(0), 4000).unref();
         releaseKeepAwake();
         runtime.clearActive();
         dashboardClose?.();
-        await browser.close();
+        await Promise.race([browser.close().catch(() => undefined), new Promise((r) => setTimeout(r, 3000))]);
         try {
             unlinkSync(pidFile());
         }
@@ -352,6 +354,9 @@ async function cmdDashboard(a) {
             return;
         }
     }
+    const [{ RelayEventStore }, { RelayRuntime }, { serveDashboard }] = await Promise.all([
+        import("./audit.js"), import("./runtime.js"), import("./dashboard.js"),
+    ]);
     const cfg = load();
     const store = preview ? undefined : new RelayEventStore({ retentionDays: cfg.retentionDays ?? 30 }).init();
     const runtime = preview ? undefined : new RelayRuntime({ daemon: "stopped" });
@@ -363,22 +368,27 @@ async function cmdDashboard(a) {
     openBrowser(url);
     await new Promise(() => { }); // stay up until Ctrl-C
 }
-async function cmdStatus() {
+async function cmdStatus(a = []) {
+    const flag = (n) => a.includes(n);
+    const sinceArg = a[a.indexOf("--since") + 1];
+    const window = a.includes("--since") && sinceArg && sinceArg in WINDOWS ? sinceArg : "24h";
     const pid = isRunning();
     const cfg = load();
-    // Pad wider than the longest label ("dashboard", 9) so every value has a gutter —
-    // padEnd(9) left "dashboard" flush against its URL.
-    const label = (s) => c.dim(s.padEnd(11));
+    let startedAt;
+    try {
+        startedAt = JSON.parse(readFileSync(dashboardRuntimeFile(), "utf8")).startedAt;
+    }
+    catch { }
+    // audit.js is fs-only; reload() reads the saved history without pruning or writing.
+    const { RelayEventStore } = await import("./audit.js");
+    const store = new RelayEventStore({ retentionDays: 30 });
+    store.reload();
+    const data = statusData(store.query({ limit: 10_000 }), { state: pid ? "running" : "stopped", startedAt, link: pid ? await gatewayLinkState() : undefined }, window);
+    if (flag("--json"))
+        return log(JSON.stringify({ ...data, pid, gateway: cfg.gatewayUrl ?? null, asYou: cfg.loginDomains }, null, 2));
+    log(renderStatus(data, { limit: flag("--all") ? Infinity : 10 }));
     log("");
-    log(`${label("relay")}${pid ? c.green(`running`) + c.dim(` (pid ${pid})`) : c.yellow("not running")}`);
-    // The PROCESS being alive is not the same as the gateway LINK being up — a slept host
-    // leaves a dead link the process can't see. Ask the daemon's own dashboard for the
-    // live state so status stops reporting "running" over a dead link.
-    if (pid)
-        log(`${label("link")}${await gatewayLinkState()}`);
-    log(`${label("gateway")}${cfg.gatewayUrl ? c.cyan(cfg.gatewayUrl) : c.dim("(unset)")}`);
-    log(`${label("dashboard")}${dashboardUrl() ? c.cyan(dashboardUrl()) : c.dim("relay dashboard opens saved history")}`);
-    log(`${label("as-you")}${cfg.loginDomains.length ? cfg.loginDomains.join(", ") : c.dim("no sites signed in — all fetches are clean")}`);
+    log(c.dim(`gateway ${cfg.gatewayUrl ?? "(unset)"} · as-you ${cfg.loginDomains.length ? cfg.loginDomains.join(", ") : "none"} · --since 1h|24h|7d · --all · --json`));
     log("");
 }
 /** Live gateway-link state, read from the running daemon's local dashboard (`/data`).
@@ -388,22 +398,16 @@ async function cmdStatus() {
 async function gatewayLinkState() {
     const base = dashboardUrl();
     if (!base)
-        return c.dim("unknown (dashboard not up yet)");
+        return "starting";
     try {
         const ac = new AbortController();
         const timer = setTimeout(() => ac.abort(), 1500);
         const res = await fetch(`${base}/data`, { signal: ac.signal }).finally(() => clearTimeout(timer));
         const data = (await res.json());
-        if (data.state === "connected")
-            return c.green("connected");
-        if (data.state === "reconnecting")
-            return c.yellow("reconnecting… (host asleep or offline)");
-        if (data.state === "stopped")
-            return c.yellow("stopped");
-        return c.dim("unknown");
+        return data.state === "connected" || data.state === "reconnecting" || data.state === "stopped" ? data.state : "unknown";
     }
     catch {
-        return c.yellow("unreachable — the relay daemon isn't responding (try: relay restart)");
+        return "unreachable"; // the daemon isn't answering — relay restart
     }
 }
 /** Stop-then-start, reusing the stored gateway + reconnect token. The escape hatch for a
@@ -411,12 +415,7 @@ async function gatewayLinkState() {
 async function cmdRestart(a) {
     const pid = isRunning();
     if (pid) {
-        process.kill(pid, "SIGTERM");
-        try {
-            unlinkSync(pidFile());
-        }
-        catch { }
-        await new Promise((r) => setTimeout(r, 600)); // let it release the pid + dashboard port
+        await stopPid(pid, { files: [pidFile(), dashboardRuntimeFile()] }); // waits until it is gone (≤ 5 s)
         log(c.dim("restarting the relay…"));
     }
     else {
@@ -424,23 +423,21 @@ async function cmdRestart(a) {
     }
     return cmdStart(a);
 }
-function cmdStop() {
+async function cmdStop() {
     const pid = isRunning();
     if (!pid)
         return log(c.dim("no relay running."));
-    process.kill(pid, "SIGTERM");
-    try {
-        unlinkSync(pidFile());
-    }
-    catch { }
-    log(`${c.green("✓")} relay stopped.`);
+    const how = await stopPid(pid, { files: [pidFile(), dashboardRuntimeFile()] });
+    log(how === "killed"
+        ? `${c.green("✓")} relay stopped ${c.dim("(it did not exit within 5 s, so it was killed)")}.`
+        : `${c.green("✓")} relay stopped.`);
 }
 async function dispatch(a) {
     switch (a[0]) {
         case "start": return cmdStart(a.slice(1));
         case "login": return cmdLogin(a.slice(1));
         case "dashboard": return cmdDashboard(a.slice(1));
-        case "status": return cmdStatus();
+        case "status": return cmdStatus(a.slice(1));
         case "stop": return cmdStop();
         case "restart": return cmdRestart(a.slice(1));
         case "reset":

package/dist/status.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `relay status` stats as docker-ps style tables (owner, 2026-11-08: the web dashboard is not reachable on
+ * a headless NAS, so the terminal has to show what the relay did). Pure: events in, text/JSON out. It reads
+ * only the saved event history — no transport, browser or dashboard module — so status stays fast.
+ */
+import type { RelayEventV2 } from "./audit.js";
+export declare const WINDOWS: {
+    readonly "1h": 3600000;
+    readonly "24h": 86400000;
+    readonly "7d": number;
+};
+export type StatusWindow = keyof typeof WINDOWS;
+export interface StatusHead {
+    state: "running" | "stopped";
+    startedAt?: string;
+    link?: string;
+}
+export interface StatusData {
+    window: StatusWindow;
+    state: StatusHead["state"];
+    uptimeMs: number | null;
+    link: string | null;
+    requests: number;
+    okPct: number | null;
+    bytes: number | null;
+    pods: {
+        name: string;
+        requests: number;
+        okPct: number;
+        lastAt: string;
+    }[];
+    sites: {
+        host: string;
+        requests: number;
+        okPct: number;
+        lastError: string | null;
+        lastErrorAt: string | null;
+    }[];
+}
+export declare function statusData(events: RelayEventV2[], head: StatusHead, window: StatusWindow, now?: number): StatusData;
+export declare function ago(ms: number): string;
+export declare function renderStatus(d: StatusData, opts?: {
+    limit: number;
+    now?: number;
+}): string;

package/dist/status.js

@@ -0,0 +1,109 @@
+import { c } from "./colors.js";
+export const WINDOWS = { "1h": 3_600_000, "24h": 86_400_000, "7d": 7 * 86_400_000 };
+const ERROR_WORD = {
+    "site-refused": "refused",
+    "owner-blocked": "blocked by you",
+    "safety-blocked": "blocked (safety)",
+    "rate-limited": "rate limited",
+    "network-error": "network error",
+};
+function errorText(e) {
+    return [e.httpStatus, ERROR_WORD[e.outcome] ?? e.outcome].filter(Boolean).join(" ");
+}
+function podName(e) {
+    if (!e.source)
+        return "(unknown)";
+    if ("system" in e.source)
+        return null; // the relay's own health checks are not a pod
+    return e.source.podName || e.source.podId;
+}
+function group(events, key) {
+    const by = new Map();
+    for (const e of events) {
+        const k = key(e);
+        if (!k)
+            continue;
+        const t = Date.parse(e.startedAt);
+        const r = by.get(k) ?? { name: k, req: 0, ok: 0, last: 0 };
+        r.req++;
+        if (e.outcome === "ok")
+            r.ok++;
+        else if (!r.lastError || t > Date.parse(r.lastError.startedAt))
+            r.lastError = e;
+        r.last = Math.max(r.last, t);
+        by.set(k, r);
+    }
+    return [...by.values()].sort((a, b) => b.req - a.req || b.last - a.last);
+}
+const pct = (ok, n) => (n ? Math.round((ok / n) * 100) : 0);
+export function statusData(events, head, window, now = Date.now()) {
+    const inWindow = events.filter((e) => Date.parse(e.startedAt) >= now - WINDOWS[window]);
+    const counted = inWindow.filter((e) => podName(e) !== null);
+    const ok = counted.filter((e) => e.outcome === "ok").length;
+    return {
+        window,
+        state: head.state,
+        uptimeMs: head.state === "running" && head.startedAt ? Math.max(0, now - Date.parse(head.startedAt)) : null,
+        link: head.state === "running" ? (head.link ?? "unknown") : null,
+        requests: counted.length,
+        okPct: counted.length ? pct(ok, counted.length) : null,
+        bytes: counted.some((e) => e.mode === "tunnel") ? counted.filter((e) => e.mode === "tunnel").reduce((s, e) => s + (e.bytesUp ?? 0) + (e.bytesDown ?? 0), 0) : null,
+        pods: group(counted, podName).map((r) => ({ name: r.name, requests: r.req, okPct: pct(r.ok, r.req), lastAt: new Date(r.last).toISOString() })),
+        sites: group(counted, (e) => e.host).map((r) => ({
+            host: r.name, requests: r.req, okPct: pct(r.ok, r.req),
+            lastError: r.lastError ? errorText(r.lastError) : null,
+            lastErrorAt: r.lastError ? r.lastError.startedAt : null,
+        })),
+    };
+}
+export function ago(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s} s ago`;
+    if (s < 3600)
+        return `${Math.round(s / 60)} min ago`;
+    if (s < 86_400)
+        return `${Math.round(s / 3600)} h ago`;
+    return `${Math.round(s / 86_400)} d ago`;
+}
+function duration(ms) {
+    const m = Math.floor(ms / 60_000), h = Math.floor(m / 60), d = Math.floor(h / 24);
+    return d ? `${d}d ${h % 24}h` : h ? `${h}h ${m % 60}m` : `${m}m`;
+}
+function size(b) {
+    if (b < 1024)
+        return `${b} B`;
+    if (b < 1024 ** 2)
+        return `${Math.round(b / 1024)} KB`;
+    if (b < 1024 ** 3)
+        return `${Math.round(b / 1024 ** 2)} MB`;
+    return `${(b / 1024 ** 3).toFixed(1)} GB`;
+}
+const cut = (s, w) => (s.length > w ? s.slice(0, w - 1) + "…" : s);
+/** Columns padded to fixed widths that fit 80 columns; numbers right-aligned. */
+function table(head, widths, right, body) {
+    const line = (cells) => cells.map((v, i) => (i === cells.length - 1 ? v : right[i] ? v.padStart(widths[i]) : cut(v, widths[i]).padEnd(widths[i]))).join("  ").trimEnd();
+    return [c.dim(line(head)), ...body.map(line)];
+}
+export function renderStatus(d, opts = { limit: 10 }) {
+    const now = opts.now ?? Date.now();
+    const out = [""];
+    const stateWord = d.state === "running" ? c.green("running") : c.yellow("stopped");
+    const head = table(["STATE", "UPTIME", "LINK", `REQ ${d.window}`, "OK%", "DATA"], [8, 8, 12, 8, 4, 0], [false, false, false, true, true, false], [[d.state, d.uptimeMs === null ? "—" : duration(d.uptimeMs), d.link ?? "—", String(d.requests), d.okPct === null ? "—" : `${d.okPct}%`, d.bytes === null ? "—" : size(d.bytes)]]);
+    head[1] = head[1].replace(/^(running|stopped)/, stateWord);
+    out.push(...head);
+    if (!d.requests) {
+        out.push("", c.dim(`no pod requests in the last ${d.window}`));
+    }
+    else {
+        out.push("");
+        out.push(...table(["POD", "REQ", "OK%", "LAST"], [24, 6, 4, 0], [false, true, true, false], d.pods.slice(0, opts.limit).map((p) => [p.name, String(p.requests), `${p.okPct}%`, ago(now - Date.parse(p.lastAt))])));
+        out.push("");
+        out.push(...table(["SITE", "REQ", "OK%", "LAST ERROR"], [24, 6, 4, 0], [false, true, true, false], d.sites.slice(0, opts.limit).map((s) => [s.host, String(s.requests), `${s.okPct}%`,
+            s.lastError ? `${s.lastError}, ${ago(now - Date.parse(s.lastErrorAt))}` : "—"])));
+        const hidden = Math.max(0, d.pods.length - opts.limit) + Math.max(0, d.sites.length - opts.limit);
+        if (hidden)
+            out.push("", c.dim(`${hidden} more rows — relay status --all`));
+    }
+    return out.join("\n");
+}

package/dist/stop.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stop a relay daemon and WAIT until it is gone, but never for long: SIGTERM, poll for up to
+ * `graceMs`, then SIGKILL. A boot script runs `relay stop` before `relay start`, so returning
+ * while the old daemon still holds the dashboard port or the browser profile would race the new
+ * one — and a daemon stuck in a slow shutdown (a swapping NAS) must not hang the script.
+ */
+export declare function stopPid(pid: number, opts?: {
+    graceMs?: number;
+    pollMs?: number;
+    files?: string[];
+}): Promise<"not-running" | "stopped" | "killed">;

package/dist/stop.js

@@ -0,0 +1,46 @@
+import { unlinkSync } from "node:fs";
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Stop a relay daemon and WAIT until it is gone, but never for long: SIGTERM, poll for up to
+ * `graceMs`, then SIGKILL. A boot script runs `relay stop` before `relay start`, so returning
+ * while the old daemon still holds the dashboard port or the browser profile would race the new
+ * one — and a daemon stuck in a slow shutdown (a swapping NAS) must not hang the script.
+ */
+export async function stopPid(pid, opts = {}) {
+    const { graceMs = 5000, pollMs = 100, files = [] } = opts;
+    const clean = () => { for (const f of files)
+        try {
+            unlinkSync(f);
+        }
+        catch { /* gone */ } };
+    if (!alive(pid)) {
+        clean();
+        return "not-running";
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch { /* exited meanwhile */ }
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline) {
+        if (!alive(pid)) {
+            clean();
+            return "stopped";
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch { /* exited at the last moment */ }
+    clean();
+    return "killed";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podway/relay",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Podway relay \u2014 runs a fetch relay on your machine so a pod can read pages from your network, using sessions you sign into. Install: npm i -g @podway/relay, then `relay start`.",
   "type": "module",
   "bin": {