@the-seeker/server-agent 0.1.1 → 0.2.0

package/README.md

@@ -73,7 +73,7 @@ nginx 상대 로그 경로는 필요할 때만 `nginx -V`의 `--prefix`를 조
 변환합니다(nginx 기본값 `/usr/local/nginx`). 요청별 변수가 포함된 로그 경로는
 정적인 파일로 확정할 수 없어 광고하지 않습니다.
 
-PM2 실행 위치는 `PM2_BIN`, 데이터 위치는 `pm2Home` 또는 `PM2_HOME`으로 설정합니다.
+PM2 실행 파일은 `PM2_BIN`으로 설정하며, 이 값은 `jlist` 폴백 경로에서만 사용합니다. 데이터 위치는 `pm2Home` 또는 `PM2_HOME`으로 설정합니다.
 PM2 환경·실행 인수·실행 경로는 반환하지 않습니다. 로그 경로와 journal unit은
 `SourceRegistry` 내부에 보관하고 `tail(sourceId, lines, signal?)`로만 읽습니다.
 `lines`는 1~500이며 프로토콜 요청은 100/200/500만 허용합니다.
@@ -84,9 +84,44 @@ capability: `available`=조회 성공, `unsupported`=OS 미지원 또는 nginx
 `not_installed`=실행 파일 없음, `permission_denied`=권한 부족, `error`=기타 조회/파싱 실패.
 호스트 조회 실패는 호출자가 처리하고 host capability를 `error`로 지정합니다.
 
+## PM2 수집 방식
+
+0.2.0부터 heartbeat(기본 15초)마다 `pm2 jlist`를 자식 프로세스로 실행하지 않습니다. 대신 PM2 데몬의 RPC 유닉스 소켓 `$PM2_HOME/rpc.sock`에 연결해 `getMonitorData`를 한 번 호출한 뒤 연결을 닫습니다. PM2 CLI가 데몬과 통신할 때 사용하는 것과 같은 amp/axon-rpc 프로토콜을 사용하며, 추가 의존성은 없습니다.
+
+받은 데이터는 기존과 같은 허용 필드(zod allowlist)만 남깁니다. `pm2_env`의 환경 변수, 실행 인수, 실행 경로는 전송하지 않습니다. `pm2.describe` 온디맨드 요청도 같은 RPC 경로를 사용합니다.
+
+폴백 규칙은 다음과 같습니다.
+
+- 소켓이 없거나 데몬이 실행 중이 아니어서 `ENOENT`가 발생하면, PM2 실행 파일이 있을 때 `available`과 빈 프로세스 목록을 반환합니다. 데몬을 띄우는 부작용을 막기 위해 `jlist`는 실행하지 않습니다. 실행 파일도 없으면 `not_installed`를 반환합니다.
+- 소켓 권한 오류인 `EACCES`는 `permission_denied`로 반환합니다.
+- 그 밖의 오류는 PM2 실행 파일이 있을 때 해당 heartbeat에 한해 `pm2 jlist`를 한 번 실행해 폴백합니다. 여기에는 8초 타임아웃, 프로토콜 불일치, 16MiB를 초과한 응답이 포함됩니다. 실행 파일이 없으면 `error`를 반환합니다.
+
+예전 방식을 강제로 사용하려면 `PM2_COLLECTOR=jlist`를 설정합니다.
+
+systemd에서는 다음과 같이 설정할 수 있습니다.
+
+```bash
+sudo systemctl edit theseeker-agent
+```
+
+```ini
+[Service]
+Environment=PM2_COLLECTOR=jlist
+```
+
+설정 후 `sudo systemctl restart theseeker-agent`를 실행합니다.
+
+`rpc.sock`은 PM2 데몬 소유자만 접근할 수 있습니다. 따라서 `install --user`에는 PM2 데몬 소유자를 지정해야 합니다. 소유자는 다음 명령으로 확인할 수 있습니다.
+
+```bash
+ps -eo user,cmd | grep "PM2 v"
+```
+
+소켓 위치는 `PM2_HOME` 또는 `--pm2-home`으로 결정합니다.
+
 ## 문제 해결
 
-systemd의 PATH에서 nvm으로 설치한 PM2가 보이지 않으면 capability가 `not_installed`가 될 수 있습니다. `@the-seeker/server-agent@0.1.1`부터는 실행 중인 node의 `dirname(process.execPath)/pm2`를 자동으로 찾고, `install`이 systemd unit에 `Environment=PATH=<node bin dir>:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`을 기록합니다. 업그레이드 후 호스트에서 `install`을 다시 실행하면 됩니다.
+systemd의 PATH에서 nvm으로 설치한 PM2가 보이지 않으면 capability가 `not_installed`가 될 수 있습니다. `@the-seeker/server-agent@0.1.1`부터는 실행 중인 node의 `dirname(process.execPath)/pm2`를 자동으로 찾고, `install`이 systemd unit에 `Environment=PATH=<node bin dir>:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`을 기록합니다. 업그레이드 후 호스트에서 `install`을 다시 실행하면 됩니다(0.1.1은 이어서 `sudo systemctl restart theseeker-agent` 필요, 0.1.2부터 `install`이 자동 재시작).
 
 자동 설정을 쓰지 않을 때는 systemd drop-in으로 PM2 실행 파일을 지정합니다.
 

package/dist/collectors/pm2-rpc.d.ts

@@ -0,0 +1,20 @@
+import type { Socket } from "node:net";
+/** amp v1: header byte `(version << 4) | argc`, then per argument a UInt32BE length followed by its bytes. */
+export declare function encodeAmpMessage(args: readonly unknown[]): Buffer;
+export declare function decodeAmpArg(arg: Buffer): unknown;
+/** amp carries no outer frame length, so TCP chunks are buffered until each frame's arguments are complete. */
+export declare class AmpFrameParser {
+    private readonly maxBytes;
+    private buffered;
+    constructor(maxBytes?: number);
+    push(chunk: Buffer): Buffer[][];
+    private read;
+}
+export interface Pm2CallOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly maxBytes?: number;
+    readonly connect?: (path: string) => Socket;
+}
+/** Minimal pm2-axon-rpc client for the PM2 daemon's `$PM2_HOME/rpc.sock`, avoiding a `pm2 jlist` subprocess. */
+export declare function pm2Call<T = unknown>(sockPath: string, method: string, params: unknown, opts?: Pm2CallOptions): Promise<T>;

package/dist/collectors/pm2-rpc.js

@@ -0,0 +1,139 @@
+import { createConnection } from "node:net";
+import { CollectionError } from "./command.js";
+const AMP_VERSION = 1;
+const MAX_ARGS = 15;
+const DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+let counter = 0;
+/** amp v1: header byte `(version << 4) | argc`, then per argument a UInt32BE length followed by its bytes. */
+export function encodeAmpMessage(args) {
+    if (args.length > MAX_ARGS)
+        throw new CollectionError("internal");
+    const parts = args.map((arg) => (Buffer.isBuffer(arg) ? arg : Buffer.from(typeof arg === "string" ? `s:${arg}` : `j:${JSON.stringify(arg)}`)));
+    const frame = [Buffer.from([(AMP_VERSION << 4) | parts.length])];
+    for (const part of parts) {
+        const length = Buffer.alloc(4);
+        length.writeUInt32BE(part.length, 0);
+        frame.push(length, part);
+    }
+    return Buffer.concat(frame);
+}
+export function decodeAmpArg(arg) {
+    const prefix = arg.subarray(0, 2).toString("utf8");
+    if (prefix === "s:")
+        return arg.subarray(2).toString("utf8");
+    if (prefix === "j:")
+        return JSON.parse(arg.subarray(2).toString("utf8"));
+    return arg;
+}
+/** amp carries no outer frame length, so TCP chunks are buffered until each frame's arguments are complete. */
+export class AmpFrameParser {
+    maxBytes;
+    buffered = Buffer.alloc(0);
+    constructor(maxBytes = DEFAULT_MAX_BYTES) {
+        this.maxBytes = maxBytes;
+    }
+    push(chunk) {
+        this.buffered = this.buffered.length === 0 ? chunk : Buffer.concat([this.buffered, chunk]);
+        if (this.buffered.length > this.maxBytes)
+            throw new CollectionError("too_large");
+        const frames = [];
+        for (;;) {
+            const frame = this.read();
+            if (!frame)
+                return frames;
+            frames.push(frame);
+        }
+    }
+    read() {
+        if (this.buffered.length < 1)
+            return null;
+        const header = this.buffered.readUInt8(0);
+        if (header >> 4 !== AMP_VERSION)
+            throw new CollectionError("internal");
+        const argc = header & 0x0f;
+        const args = [];
+        let offset = 1;
+        for (let index = 0; index < argc; index += 1) {
+            if (offset + 4 > this.buffered.length)
+                return null;
+            const length = this.buffered.readUInt32BE(offset);
+            offset += 4;
+            if (offset + length > this.buffered.length)
+                return null;
+            args.push(this.buffered.subarray(offset, offset + length));
+            offset += length;
+        }
+        this.buffered = this.buffered.subarray(offset);
+        return args;
+    }
+}
+function socketError(error) {
+    if (error instanceof CollectionError)
+        return error;
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
+    if (code === "ENOENT" || code === "ENOTSOCK" || code === "ECONNREFUSED")
+        return new CollectionError("not_found");
+    if (code === "EACCES" || code === "EPERM")
+        return new CollectionError("permission_denied");
+    return new CollectionError("internal");
+}
+function unwrapReply(frame, id) {
+    const [head, tail] = frame;
+    if (frame.length !== 2 || !head || !tail || decodeAmpArg(tail) !== id)
+        throw new CollectionError("internal");
+    const reply = decodeAmpArg(head);
+    if (typeof reply !== "object" || reply === null || "error" in reply)
+        throw new CollectionError("internal");
+    if (!("args" in reply) || !Array.isArray(reply.args))
+        throw new CollectionError("internal");
+    const values = reply.args;
+    return values[0];
+}
+/** Minimal pm2-axon-rpc client for the PM2 daemon's `$PM2_HOME/rpc.sock`, avoiding a `pm2 jlist` subprocess. */
+export function pm2Call(sockPath, method, params, opts = {}) {
+    const { timeoutMs = 8000, maxBytes = DEFAULT_MAX_BYTES, signal } = opts;
+    const connect = opts.connect ?? ((path) => createConnection(path));
+    counter += 1;
+    const id = `${process.pid}:${counter}`;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new CollectionError("timeout"));
+            return;
+        }
+        const socket = connect(sockPath);
+        const parser = new AmpFrameParser(maxBytes);
+        let settled = false;
+        const onAbort = () => fail(new CollectionError("timeout"));
+        const timer = setTimeout(onAbort, timeoutMs);
+        const settle = () => {
+            if (settled)
+                return false;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            socket.destroy();
+            return true;
+        };
+        function fail(error) {
+            if (settle())
+                reject(socketError(error));
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+        socket.on("error", fail);
+        socket.on("close", () => fail(new CollectionError("internal")));
+        socket.on("connect", () => socket.write(encodeAmpMessage([{ type: "call", method, args: [params] }, id])));
+        socket.on("data", (chunk) => {
+            try {
+                const [frame] = parser.push(chunk);
+                if (!frame)
+                    return;
+                const value = unwrapReply(frame, id);
+                if (settle())
+                    resolve(value);
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+    });
+}

package/dist/collectors/pm2.d.ts

@@ -5,7 +5,8 @@ export type Pm2Collection = {
     readonly processes: Process[];
     readonly sources: Source[];
 };
-export declare function mapPm2(text: string, registry: SourceRegistry, now?: number): Pm2Collection;
+export declare function mapPm2(list: unknown, registry: SourceRegistry, now?: number): Pm2Collection;
+export declare function resolvePm2Home(pm2Home?: string): string;
 export declare function collectPm2(registry: SourceRegistry, options?: {
     readonly pm2Home?: string;
     readonly signal?: AbortSignal;

package/dist/collectors/pm2.js

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod";
-import { capabilityError, locate, run } from "./command.js";
+import { CollectionError, capabilityError, locate, run } from "./command.js";
+import { pm2Call } from "./pm2-rpc.js";
 const jlist = z.array(z.object({
     name: z.string(), pm_id: z.number(),
     monit: z.object({ cpu: z.number().default(0), memory: z.number().default(0) }),
@@ -11,8 +12,8 @@ const jlist = z.array(z.object({
         pm_out_log_path: z.string().optional(), pm_err_log_path: z.string().optional(),
     }),
 }));
-export function mapPm2(text, registry, now = Date.now()) {
-    const entries = jlist.parse(JSON.parse(text)).slice(0, 100);
+export function mapPm2(list, registry, now = Date.now()) {
+    const entries = jlist.parse(list).slice(0, 100);
     const sources = [];
     const processes = entries.map((entry) => {
         const environment = entry.pm2_env;
@@ -31,20 +32,45 @@ export function mapPm2(text, registry, now = Date.now()) {
     });
     return { capability: "available", processes, sources: [...new Map(sources.map((source) => [source.id, source])).values()] };
 }
-export async function collectPm2(registry, options = {}) {
-    registry.clearKinds(["pm2_out", "pm2_err"]);
+export function resolvePm2Home(pm2Home) {
+    return pm2Home ?? process.env["PM2_HOME"] ?? join(homedir(), ".pm2");
+}
+function empty(capability) {
+    return { capability, processes: [], sources: [] };
+}
+/** Spawning `pm2 jlist` boots a daemon when none is running, so it stays a fallback for a reachable-but-unreadable socket. */
+async function collectViaJlist(registry, home, signal) {
     try {
         const binary = process.env["PM2_BIN"] || await locate("pm2");
         if (!binary)
-            return { capability: "not_installed", processes: [], sources: [] };
+            return empty("not_installed");
         const { stdout } = await run(binary, ["jlist"], {
             timeout: 8000, maxBuffer: 8 * 1024 * 1024,
-            env: { ...process.env, PM2_HOME: options.pm2Home ?? process.env["PM2_HOME"] ?? join(homedir(), ".pm2") },
-            ...(options.signal ? { signal: options.signal } : {}),
+            env: { ...process.env, PM2_HOME: home },
+            ...(signal ? { signal } : {}),
         });
-        return mapPm2(stdout, registry);
+        return mapPm2(JSON.parse(stdout), registry);
+    }
+    catch (error) {
+        return empty(capabilityError(error));
+    }
+}
+export async function collectPm2(registry, options = {}) {
+    registry.clearKinds(["pm2_out", "pm2_err"]);
+    const home = resolvePm2Home(options.pm2Home);
+    if (process.env["PM2_COLLECTOR"] === "jlist")
+        return await collectViaJlist(registry, home, options.signal);
+    try {
+        const list = await pm2Call(join(home, "rpc.sock"), "getMonitorData", {}, { timeoutMs: 8000, ...(options.signal ? { signal: options.signal } : {}) });
+        return mapPm2(list, registry);
     }
     catch (error) {
-        return { capability: capabilityError(error), processes: [], sources: [] };
+        const code = error instanceof CollectionError ? error.code : "internal";
+        if (code === "permission_denied")
+            return empty("permission_denied");
+        const binary = process.env["PM2_BIN"] || await locate("pm2");
+        if (code === "not_found")
+            return empty(binary ? "available" : "not_installed");
+        return binary ? await collectViaJlist(registry, home, options.signal) : empty("error");
     }
 }

package/dist/handlers.js

@@ -1,8 +1,7 @@
-import { homedir, platform as currentPlatform } from "node:os";
-import { join } from "node:path";
+import { platform as currentPlatform } from "node:os";
 import { CollectionError, locate, responseError, run } from "./collectors/command.js";
 import { collectNginx } from "./collectors/nginx.js";
-import { mapPm2 } from "./collectors/pm2.js";
+import { collectPm2 } from "./collectors/pm2.js";
 export const AGENT_REQUEST_TIMEOUT_MS = 15000;
 export const MAX_CONCURRENT_REQUESTS = 4;
 export const SUPPORTED_ACTIONS = ["logs.tail", "service.status", "pm2.describe", "nginx.sources"];
@@ -34,14 +33,10 @@ async function serviceStatus(unit, platform, signal) {
     return { unit, active_state: properties.get("ActiveState") ?? "unknown", sub_state: properties.get("SubState") ?? "unknown" };
 }
 async function describeProcess(name, registry, state, signal) {
-    const binary = process.env["PM2_BIN"] || await locate("pm2");
-    if (!binary)
-        throw new CollectionError("unsupported");
-    const { stdout } = await run(binary, ["jlist"], {
-        timeout: 8000, maxBuffer: 8 * 1024 * 1024, signal,
-        env: { ...process.env, PM2_HOME: state.pm2Home ?? process.env["PM2_HOME"] ?? join(homedir(), ".pm2") },
-    });
-    const found = mapPm2(stdout, registry).processes.find((entry) => entry.name === name);
+    const collection = await collectPm2(registry, { ...(state.pm2Home ? { pm2Home: state.pm2Home } : {}), signal });
+    if (collection.capability !== "available")
+        throw new CollectionError(capabilityCode(collection.capability));
+    const found = collection.processes.find((entry) => entry.name === name);
     if (!found)
         throw new CollectionError("not_found");
     return found;

package/dist/install/systemd.js

@@ -54,6 +54,7 @@ export function manualInstallCommands(endpoint, user, addGroups) {
         "and then runs:",
         "  sudo systemctl daemon-reload",
         `  sudo systemctl enable --now ${SERVICE_NAME}`,
+        `  sudo systemctl restart ${SERVICE_NAME}`,
     ];
 }
 export function manualGroupCommand(user) {
@@ -89,6 +90,11 @@ export async function installSystemd(environment, options) {
     if (!(await runSystemctl(environment, ["enable", "--now", SERVICE_NAME])))
         return 1;
     environment.print(`service enabled: ${SERVICE_NAME}`);
+    // `enable --now` no-ops on an already-running service, so an upgraded package or a rewritten unit/config
+    // would keep running the old process until someone restarted it by hand.
+    if (!(await runSystemctl(environment, ["restart", SERVICE_NAME])))
+        return 1;
+    environment.print(`service restarted: ${SERVICE_NAME}`);
     if (!options.addGroups)
         for (const line of manualGroupCommand(options.detection.user))
             environment.print(line);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-seeker/server-agent",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "bin": { "theseeker-agent": "dist/cli.js" },
   "engines": { "node": ">=20" },