srvmd 0.1.0 → 0.1.1

package/ARCHITECTURE.md

@@ -42,7 +42,24 @@ flowchart TB
 - `server` 可以使用 Bun 和 Node API，不导入 `web` 源码，不访问 DOM。
 - `web` 可以使用 DOM 和浏览器 API，不导入 `server` 源码，不读文件系统。
 - `shared` 只包含类型、契约和常量，不依赖任何运行时。
-- `cli` 只负责进程边界：解析参数、启动服务器、输出、信号。
+- `cli` 只负责进程边界：解析参数、启动服务器、输出、信号，以及跟随终端和父进程退出。
+
+## 进程生命周期
+
+`src/cli/lifecycle.ts` 决定服务器何时退出，三条触发路径最终都走同一个 `shutdown`：
+
+| 触发 | 机制 | 备注 |
+| --- | --- | --- |
+| `Ctrl+C`、`SIGTERM`、`SIGHUP` | 信号处理器 | 注册后覆盖继承来的 `SIG_IGN`（`nohup`、部分终端启动器） |
+| 终端关闭 | 每秒 `readlink /proc/self/fd/{0,1,2}` | 仅 Linux，其他平台没有 `/proc` |
+| 父进程消失 | 每秒比对 `process.ppid` | 只覆盖启动之后父进程才消失的情况 |
+
+约定：
+
+- `shutdown` 先 `running.close()`，再 `process.exit(0)`；重复信号只生效一次。
+- 处理器紧跟 `startServer` 安装，`--open` 等可能阻塞的操作不能挡在中间。
+- 启动时就已是孤儿（reaper 或容器 `PID 1` 为父进程）无法与 supervisor 拉起区分，因此不做处理；要常驻请用 systemd、Docker 等 supervisor。
+- 因为信号处理器覆盖了 `SIG_IGN`，`nohup` 和 `setsid` 都不能让服务脱离终端存活。
 
 ## 目录职责
 

package/README.md

@@ -76,6 +76,16 @@ srvmd ./docs --theme dark     # Dark theme by default
 - A directory request without a trailing `/` receives a `301` redirect
 - Hidden files and directories starting with `.` are not served or listed
 
+### Process lifecycle
+
+`srvmd` runs in the foreground and stops with whatever started it:
+
+- `Ctrl+C`, `SIGTERM` and `SIGHUP` (closing the terminal, killing the tmux session, dropping the SSH connection) shut it down cleanly
+- When the launching shell or `bun run` wrapper exits, the server follows within about a second
+- A server whose launcher is already gone at startup, or whose parent is a supervisor or container `PID 1`, is left running instead of guessing
+
+Use a supervisor (systemd, Docker, a tmux session that stays alive) when the server has to outlive the terminal. `nohup` and `setsid` are not enough: the handlers override the ignored hangup, and the tty watch still notices the closed terminal.
+
 ## Architecture
 
 ```plaintext

package/README_CN.md

@@ -76,6 +76,16 @@ srvmd ./docs --theme dark     # 默认深色主题
 - 访问目录且缺少结尾 `/` 时会收到 `301` 跳转
 - 以 `.` 开头的隐藏文件不会被提供或列入目录列表
 
+### 进程生命周期
+
+`srvmd` 在前台运行，随启动它的进程一起退出：
+
+- `Ctrl+C`、`SIGTERM` 和 `SIGHUP`（关闭终端、杀掉 tmux 会话、SSH 连接断开）会触发干净退出
+- 启动它的 shell 或 `bun run` 包装进程退出后，服务会在一秒左右跟着退出
+- 启动时启动它的 shell 已经不在了，或父进程本身就是 supervisor、容器 `PID 1` 时，服务会被保留而不做猜测
+
+需要服务脱离终端长期存活时，请交给 supervisor（systemd、Docker、保持存活的 tmux 会话）。`nohup` 和 `setsid` 并不够用：信号处理器会覆盖被忽略的挂断信号，tty 轮询仍会发现终端已关闭。
+
 ## 架构
 
 ```plaintext

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srvmd",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Static file server with live-reloading Markdown rendering, built on Bun",
   "type": "module",
   "bin": {

package/src/cli/command.ts

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import pkg from "../../package.json";
 import { startServer } from "../server/create-server.ts";
 import { openInBrowser } from "./browser.ts";
-import { installSignalHandlers } from "./lifecycle.ts";
+import { installLifecycleHandlers } from "./lifecycle.ts";
 import { type RawCliOptions, toServerOptions } from "./options.ts";
 import { printStartupReport } from "./report.ts";
 
@@ -35,6 +35,9 @@ export function createCommand(): Command {
     .action(async (directory: string, raw: RawCliOptions) => {
       const options = toServerOptions(directory, raw);
       const running = await startServer(options);
+      // Installed right after the listener exists: `--open` can block in the
+      // browser launcher, and a signal arriving there would skip cleanup.
+      installLifecycleHandlers(() => running.close());
 
       printStartupReport({
         root: running.root,
@@ -51,6 +54,5 @@ export function createCommand(): Command {
       });
 
       if (raw.open) await openInBrowser(running.url);
-      installSignalHandlers(() => running.close());
     });
 }

package/src/cli/lifecycle.ts

@@ -1,13 +1,117 @@
-export function installSignalHandlers(close: () => void): void {
+import { readlinkSync } from "node:fs";
+
+/**
+ * Signals that shut the server down gracefully.
+ *
+ * SIGHUP covers a closing terminal, a killed tmux session or window, and a dropped
+ * SSH connection. Registering a JS handler also overrides an inherited SIG_IGN
+ * disposition (nohup, supervisors, some terminal launchers) which would otherwise
+ * swallow the hangup.
+ */
+const SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+
+const WATCH_INTERVAL_MS = 1000;
+
+/** Returns true once the condition it watches for has happened. */
+type Probe = () => boolean;
+
+export function installLifecycleHandlers(close: () => void): void {
   let stopping = false;
 
   const shutdown = () => {
     if (stopping) return;
     stopping = true;
-    close();
-    process.exit(0);
+    try {
+      close();
+    } finally {
+      process.exit(0);
+    }
   };
 
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+  for (const signal of SHUTDOWN_SIGNALS) process.on(signal, shutdown);
+
+  // One timer for both probes: a single tick is enough to notice either condition.
+  const probes = [parentProbe(), terminalProbe()].filter((probe): probe is Probe => probe !== null);
+  watchUntil(probes, shutdown);
+}
+
+/**
+ * A hangup only reaches a child when the shell forwards SIGHUP. When the parent
+ * disappears quietly (a background job, a wrapper that exits right away) nothing
+ * reaches the process at all, so poll the parent pid and stop once it changes.
+ *
+ * This covers a parent that dies after startup. A process that is already
+ * reparented when the probe starts (an orphan, a `PID 1` container entrypoint)
+ * looks exactly like a process started by a supervisor, so it is left running.
+ */
+export function watchParent(onGone: () => void): void {
+  watchUntil([parentProbe()], onGone);
+}
+
+/**
+ * Closing a terminal unlinks its devpts node, so a live process still holding the
+ * hung-up tty reads `/dev/pts/N (deleted)`. Polling keeps the check passive:
+ * reading stdin would stop a background job with SIGTTIN, and it cannot tell a
+ * Ctrl+D from a hangup.
+ *
+ * Linux-only; other platforms have no `/proc`, and the parent watch still applies.
+ */
+export function watchTerminal(onGone: () => void): void {
+  const probe = terminalProbe();
+  if (probe) watchUntil([probe], onGone);
+}
+
+function parentProbe(): Probe {
+  const parent = process.ppid;
+  return () => process.ppid !== parent;
+}
+
+function terminalProbe(): Probe | null {
+  if (process.platform !== "linux") return null;
+
+  const fds = ([0, 1, 2] as const).filter(isStdioTty);
+  if (fds.length === 0) return null;
+
+  return () => fds.some(isDeletedTty);
+}
+
+/** Polls every probe on one unref'd timer and calls `onGone` once any of them fires. */
+function watchUntil(probes: readonly Probe[], onGone: () => void): void {
+  if (probes.length === 0) return;
+
+  const timer = setInterval(() => {
+    if (!probes.some(probe => probe())) return;
+    clearInterval(timer);
+    onGone();
+  }, WATCH_INTERVAL_MS);
+  timer.unref();
+}
+
+function isStdioTty(fd: 0 | 1 | 2): boolean {
+  if (fd === 0) return process.stdin.isTTY === true;
+  if (fd === 1) return process.stdout.isTTY === true;
+  return process.stderr.isTTY === true;
+}
+
+function isDeletedTty(fd: number): boolean {
+  try {
+    return isDeletedTtyTarget(readlinkSync(`/proc/self/fd/${fd}`));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Device paths that get unlinked when their terminal goes away. devpts nodes are
+ * the common case; serial consoles and `/dev/console` disappear the same way.
+ * Virtual consoles (`/dev/ttyN`) are absent on purpose: they are never unlinked.
+ */
+const HUNG_UP_TTY_TARGET = /^\/dev\/(?:pts\/\d+|ttyS\d+|ttyUSB\d+|ttyACM\d+|console)$/;
+
+/** Matches the `readlink` of a hung-up tty fd, e.g. `/dev/pts/7 (deleted)`. */
+export function isDeletedTtyTarget(target: string): boolean {
+  const suffix = " (deleted)";
+  if (!target.endsWith(suffix)) return false;
+
+  return HUNG_UP_TTY_TARGET.test(target.slice(0, -suffix.length));
 }