@rse/ase 0.0.6 → 0.0.8

package/dst/ase-service.js

@@ -6,70 +6,26 @@
 import path from "node:path";
 import fs from "node:fs";
 import net from "node:net";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
-import { parseDocument } from "yaml";
 import Hapi from "@hapi/hapi";
 import axios from "axios";
+import { isMap } from "yaml";
+import * as v from "valibot";
+import prettyMs from "pretty-ms";
+import { Config, configSchema } from "./ase-config.js";
 const SERVE_ENV = "ASE_SERVICE_SERVE";
+const PORT_ENV = "ASE_SERVICE_PORT";
 const HOST = "127.0.0.1";
 const IDLE_MS = 30 * 60 * 1000;
 const TICK_MS = 60 * 1000;
 const PORT_MIN = 42000;
 const PORT_MAX = 44000;
 const PORT_TRIES = 20;
-/*  upward-walk on filesystem for a file path relative to a start directory  */
-const findUpward = (start, rel) => {
-    let dir = start;
-    for (;;) {
-        const candidate = path.join(dir, rel);
-        if (fs.existsSync(candidate))
-            return candidate;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-};
-/*  load optional ".ase/config.yaml" and ".ase/service.yaml" files  */
-const loadContext = () => {
-    /*  find files  */
-    const cfgPath = findUpward(process.cwd(), ".ase/config.yaml");
-    const svcPath = findUpward(process.cwd(), ".ase/service.yaml");
-    /*  determine project id  */
-    let projectId;
-    if (cfgPath !== null) {
-        const doc = parseDocument(fs.readFileSync(cfgPath, "utf8"));
-        projectId = doc.get("project-id");
-    }
-    if (projectId === undefined || projectId === null)
-        projectId = path.basename(process.cwd());
-    if (typeof projectId !== "string" || projectId.length === 0)
-        throw new Error(`invalid "project-id" in ${cfgPath ?? "<cwd basename>"}`);
-    /*  determine service port  */
-    let port = null;
-    if (svcPath !== null) {
-        const doc = parseDocument(fs.readFileSync(svcPath, "utf8"));
-        const raw = doc.get("port");
-        if (raw !== undefined && raw !== null) {
-            if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1024 || raw > 65535)
-                throw new Error(`invalid "port" in ${svcPath} (expected integer 1024..65535)`);
-            port = raw;
-        }
-    }
-    /*  determine path to ".ase" directory  */
-    const aseDir = cfgPath !== null ? path.dirname(cfgPath) :
-        svcPath !== null ? path.dirname(svcPath) :
-            path.join(process.cwd(), ".ase");
-    /*  determine path to final ".ase/service.yaml" file  */
-    const finalSvc = svcPath !== null ? svcPath : path.join(aseDir, "service.yaml");
-    /*  return context information  */
-    return {
-        projectId,
-        port,
-        svcPath: finalSvc,
-        aseDir
-    };
-};
+/*  schema for ".ase/service.yaml"  */
+const serviceSchema = v.nullish(v.strictObject({
+    port: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1024), v.maxValue(65535)))
+}));
 /*  try binding a single candidate port to verify availability  */
 const tryBind = (port) => {
     return new Promise((resolve) => {
@@ -93,20 +49,29 @@ const allocatePort = async () => {
     throw new Error(`failed to allocate a port in ${PORT_MIN}..${PORT_MAX} after ${PORT_TRIES} attempts`);
 };
 /*  persist an allocated port into ".ase/service.yaml"  */
-const persistPort = (svcPath, port) => {
-    fs.mkdirSync(path.dirname(svcPath), { recursive: true });
-    const text = fs.existsSync(svcPath) ? fs.readFileSync(svcPath, "utf8") : "";
-    const doc = parseDocument(text);
-    doc.set("port", port);
-    fs.writeFileSync(svcPath, doc.toString(), "utf8");
+const persistPort = (svc, port) => {
+    svc.set("port", port);
+    svc.write();
+};
+/*  clear the persisted port and remove ".ase/service.yaml" if it is empty  */
+const clearPort = (svc) => {
+    svc.delete("port");
+    const root = svc.get();
+    const empty = root === undefined || root === null || (isMap(root) && root.items.length === 0);
+    if (empty) {
+        if (fs.existsSync(svc.filename))
+            fs.rmSync(svc.filename);
+    }
+    else
+        svc.write();
 };
 /*  distinguish ECONNREFUSED from other Axios transport errors  */
 const isConnRefused = (err) => {
     const e = err;
     return e?.code === "ECONNREFUSED" || e?.cause?.code === "ECONNREFUSED";
 };
-/*  probe the service  */
-const probe = async (port) => {
+/*  probe the service and verify ASE identity banner  */
+const probe = async (port, projectId) => {
     try {
         const r = await axios.request({
             method: "OPTIONS",
@@ -114,7 +79,10 @@ const probe = async (port) => {
             timeout: 2000,
             validateStatus: () => true
         });
-        return r.status;
+        if (r.status < 200 || r.status >= 300)
+            return false;
+        const d = r.data;
+        return d?.ase === true && d?.projectId === projectId;
     }
     catch (err) {
         if (isConnRefused(err))
@@ -122,148 +90,305 @@ const probe = async (port) => {
         throw err;
     }
 };
-/*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
-const runService = async (ctx) => {
-    /*  establish HAPI HTTP/REST service  */
-    const server = Hapi.server({ host: HOST, port: ctx.port });
-    /*  track last activity  */
-    let lastActivity = Date.now();
-    server.ext("onRequest", (_request, h) => {
-        lastActivity = Date.now();
-        return h.continue;
-    });
-    /*  listen to HTTP/REST endpoints  */
-    server.route({
-        method: "OPTIONS",
-        path: "/",
-        handler: (_request, h) => {
-            return h.response().code(204);
-        }
-    });
-    server.route({
-        method: "GET",
-        path: "/stop",
-        handler: (_request, h) => {
-            setImmediate(async () => {
-                await server.stop({ timeout: 1000 });
-                process.exit(0);
-            });
-            return h.response({ ok: true }).code(200);
-        }
-    });
-    server.route({
-        method: "POST",
-        path: "/command",
-        options: { payload: { parse: true, allow: "application/json" } },
-        handler: (request, h) => {
-            const payload = request.payload;
-            if (!payload || typeof payload.command !== "string")
-                return h.response({ error: "missing or invalid 'command' field" }).code(400);
-            if (payload.command === "foo") {
-                return h.response({
-                    ok: true,
-                    projectId: ctx.projectId,
-                    command: "Hello World" // FIXME
-                }).code(200);
-            }
-            else
-                return h.response({ error: "invalid 'command' field" }).code(400);
-        }
-    });
-    /*  start service  */
-    try {
-        await server.start();
-    }
-    catch (err) {
-        const e = err;
-        if (e.code === "EADDRINUSE") {
-            /*  race-loser re-probe: another "ase service start" won the race  */
-            const status = await probe(ctx.port).catch(() => null);
-            if (status !== null && status >= 200 && status < 300)
-                process.exit(0);
-            process.stderr.write(`ase: service: port ${ctx.port} in use, but not responding!\n`);
-            process.exit(1);
-        }
-        process.stderr.write(`ase: service: ${e.message}\n`);
-        process.exit(1);
-    }
-    /*  stop service after idle timeout  */
-    setInterval(() => {
-        if (Date.now() - lastActivity > IDLE_MS) {
-            server.stop({ timeout: 1000 }).then(() => {
-                process.exit(0);
-            });
-        }
-    }, TICK_MS).unref();
-};
 /*  spawn the current executable detached as a background service  */
-const spawnDetached = (aseDir) => {
+const spawnDetached = (aseDir, port) => {
     fs.mkdirSync(aseDir, { recursive: true });
     const logFile = path.join(aseDir, "service.log");
-    const log = fs.openSync(logFile, "a");
-    const child = spawn(process.execPath, [process.argv[1], "service", "start"], {
+    const fd = fs.openSync(logFile, "a");
+    const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
+    const child = spawn(process.execPath, [entry, "service", "start"], {
         detached: true,
-        env: { ...process.env, [SERVE_ENV]: "1" },
-        stdio: ["ignore", log, log]
+        env: { ...process.env, [SERVE_ENV]: "1", [PORT_ENV]: String(port) },
+        stdio: ["ignore", fd, fd]
     });
-    child.unref();
+    fs.closeSync(fd);
+    return { child, logFile };
 };
-/*  start flow: ensure port, probe, optionally detach  */
-const doStart = async () => {
-    const ctx = loadContext();
-    let port = ctx.port;
-    if (port === null) {
-        port = await allocatePort();
-        persistPort(ctx.svcPath, port);
+/*  read the last N non-empty lines of a log file for diagnostics  */
+const readLogTail = (logFile, lines) => {
+    let fd = null;
+    try {
+        fd = fs.openSync(logFile, "r");
+        const size = fs.fstatSync(fd).size;
+        const CHUNK = 8192;
+        const buf = Buffer.alloc(CHUNK);
+        let pos = size;
+        let tail = "";
+        let count = 0;
+        while (pos > 0 && count <= lines) {
+            const n = Math.min(CHUNK, pos);
+            pos -= n;
+            fs.readSync(fd, buf, 0, n, pos);
+            tail = buf.toString("utf8", 0, n) + tail;
+            count = 0;
+            for (let i = 0; i < tail.length; i++)
+                if (tail.charCodeAt(i) === 10)
+                    count++;
+        }
+        const all = tail.split("\n").filter((l) => l.length > 0);
+        return all.slice(-lines).join("\n");
     }
-    if (process.env[SERVE_ENV] === "1") {
-        await runService({ ...ctx, port });
-        return await new Promise(() => { });
+    catch {
+        return "";
     }
-    const status = await probe(port);
-    if (status !== null && status >= 200 && status < 300)
-        return 0;
-    spawnDetached(ctx.aseDir);
-    for (let i = 0; i < 50; i++) {
-        await new Promise((resolve) => setTimeout(resolve, 100));
-        const s = await probe(port);
-        if (s !== null && s >= 200 && s < 300)
-            return 0;
+    finally {
+        if (fd !== null)
+            fs.closeSync(fd);
     }
-    throw new Error("service failed to start within timeout");
 };
-/*  stop flow: no-op if no port configured or connection refused  */
-const doStop = async () => {
-    const ctx = loadContext();
-    if (ctx.port === null)
-        return 0;
-    try {
-        const r = await axios.request({
+/*  CLI command "ase service"  */
+export default class ServiceCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  load optional ".ase/config.yaml" and ".ase/service.yaml" files  */
+    loadContext() {
+        /*  load files  */
+        const cfg = new Config("config", configSchema, this.log);
+        cfg.read();
+        const svc = new Config("service", serviceSchema, this.log);
+        svc.read();
+        /*  determine project id  */
+        const rawId = cfg.get("project.id");
+        const projectId = rawId ?? path.basename(process.cwd());
+        /*  determine service port  */
+        const rawPort = svc.get("port");
+        const port = rawPort ?? null;
+        /*  determine path to ".ase" directory  */
+        const aseDir = path.dirname(svc.filename);
+        /*  return context information  */
+        return {
+            projectId,
+            port,
+            svc,
+            aseDir
+        };
+    }
+    /*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
+    async runService(ctx) {
+        /*  establish HAPI HTTP/REST service  */
+        const server = Hapi.server({ host: HOST, port: ctx.port });
+        /*  track start time and last activity  */
+        const startTime = Date.now();
+        let lastActivity = Date.now();
+        let stopping = false;
+        server.ext("onRequest", (_request, h) => {
+            lastActivity = Date.now();
+            return h.continue;
+        });
+        /*  listen to HTTP/REST endpoints  */
+        server.route({
+            method: "OPTIONS",
+            path: "/",
+            handler: (_request, h) => {
+                return h.response({ ase: true, projectId: ctx.projectId }).code(200);
+            }
+        });
+        server.route({
             method: "GET",
-            url: `http://${HOST}:${ctx.port}/stop`,
-            timeout: 5000,
-            validateStatus: () => true
+            path: "/stop",
+            handler: (_request, h) => {
+                setImmediate(async () => {
+                    await server.stop({ timeout: 1000 });
+                    process.exit(0);
+                });
+                return h.response({ ok: true }).code(200);
+            }
         });
-        return r.status >= 200 && r.status < 300 ? 0 : 1;
+        server.route({
+            method: "POST",
+            path: "/command",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (!payload || typeof payload.command !== "string")
+                    return h.response({ error: "missing or invalid 'command' field" }).code(400);
+                const cmd = payload.command;
+                if (cmd === "ping")
+                    return h.response({ ok: true, pong: true }).code(200);
+                if (cmd === "status")
+                    return h.response({
+                        ok: true,
+                        projectId: ctx.projectId,
+                        port: ctx.port,
+                        uptimeMs: Date.now() - startTime
+                    }).code(200);
+                return h.response({ error: "unknown command", command: cmd }).code(400);
+            }
+        });
+        /*  start service  */
+        try {
+            await server.start();
+            persistPort(ctx.svc, ctx.port);
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === "EADDRINUSE") {
+                /*  race-loser re-probe: another "ase service start" won the race  */
+                const match = await probe(ctx.port, ctx.projectId).catch(() => null);
+                if (match === true)
+                    process.exit(0);
+                this.log.write("error", `service: port ${ctx.port} in use, but not responding!`);
+                clearPort(ctx.svc);
+                process.exit(1);
+            }
+            this.log.write("error", `service: ${e.message}`);
+            process.exit(1);
+        }
+        /*  stop service after idle timeout  */
+        setInterval(async () => {
+            if (stopping)
+                return;
+            if (Date.now() - lastActivity > IDLE_MS) {
+                stopping = true;
+                try {
+                    await server.stop({ timeout: 1000 });
+                    clearPort(ctx.svc);
+                    process.exit(0);
+                }
+                catch (err) {
+                    const e = err;
+                    this.log.write("error", `service: stop failed: ${e.message}`);
+                    clearPort(ctx.svc);
+                    process.exit(1);
+                }
+            }
+        }, TICK_MS).unref();
     }
-    catch (err) {
-        if (isConnRefused(err))
+    /*  start flow: ensure port, probe, optionally detach  */
+    async doStart() {
+        const ctx = this.loadContext();
+        let port = ctx.port;
+        if (process.env[SERVE_ENV] === "1") {
+            const raw = process.env[PORT_ENV];
+            port = raw !== undefined ? Number(raw) : await allocatePort();
+            await this.runService({ ...ctx, port });
+            return await new Promise(() => { });
+        }
+        if (port !== null) {
+            const match = await probe(port, ctx.projectId);
+            if (match === true) {
+                this.log.write("info", `service: already running on port ${port}`);
+                return 0;
+            }
+        }
+        /*  bounded retry across the bind/start TOCTOU window: on each attempt
+            re-allocate, re-persist, re-spawn; early-break on foreign listener  */
+        let lastErr = new Error("service failed to start within timeout");
+        for (let attempt = 0; attempt < 3; attempt++) {
+            port = await allocatePort();
+            const { child, logFile } = spawnDetached(ctx.aseDir, port);
+            let exited = false;
+            let exitCode = null;
+            let resolveExit = () => { };
+            const exitPromise = new Promise((resolve) => {
+                resolveExit = resolve;
+            });
+            const onExit = (code) => {
+                exited = true;
+                exitCode = code;
+                resolveExit();
+            };
+            child.once("exit", onExit);
+            let foreign = false;
+            let success = false;
+            try {
+                for (let i = 0; i < 50; i++) {
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                    if (exited)
+                        break;
+                    const s = await probe(port, ctx.projectId);
+                    if (s === true) {
+                        this.log.write("info", `service: started on port ${port}`);
+                        child.unref();
+                        success = true;
+                        return 0;
+                    }
+                    if (s === false) {
+                        foreign = true;
+                        break;
+                    }
+                }
+                const tail = readLogTail(logFile, 20);
+                const reason = exited ?
+                    `service exited during startup (code ${exitCode})` :
+                    foreign ?
+                        `service lost port ${port} race to a foreign listener` :
+                        "service failed to start within timeout";
+                const detail = tail.length > 0 ? `\n---- ${logFile} (tail) ----\n${tail}` : "";
+                lastErr = new Error(`${reason}${detail}`);
+            }
+            finally {
+                child.removeListener("exit", onExit);
+                if (!success && !exited) {
+                    child.kill("SIGTERM");
+                    await Promise.race([
+                        exitPromise,
+                        new Promise((resolve) => setTimeout(resolve, 1000))
+                    ]);
+                    if (!exited) {
+                        child.kill("SIGKILL");
+                        await exitPromise;
+                    }
+                }
+            }
+        }
+        clearPort(ctx.svc);
+        throw lastErr;
+    }
+    /*  status flow: report whether the service is running  */
+    async doStatus() {
+        const ctx = this.loadContext();
+        if (ctx.port === null) {
+            process.stdout.write("service: not running (no port configured)\n");
+            return 1;
+        }
+        const match = await probe(ctx.port, ctx.projectId);
+        if (match === true) {
+            const r = await axios.request({
+                method: "POST",
+                url: `http://${HOST}:${ctx.port}/command`,
+                headers: { "Content-Type": "application/json" },
+                data: { command: "status" },
+                timeout: 2000,
+                validateStatus: () => true
+            });
+            const d = r.data;
+            const uptimeMs = typeof d?.uptimeMs === "number" ? d.uptimeMs : 0;
+            const uptime = prettyMs(uptimeMs, { verbose: true });
+            process.stdout.write(`service: running on port ${ctx.port} (uptime: ${uptime})\n`);
             return 0;
-        throw err;
+        }
+        if (match === false) {
+            process.stdout.write(`service: not running (port ${ctx.port} in use by foreign service)\n`);
+            return 1;
+        }
+        process.stdout.write(`service: not running (port ${ctx.port} not responding)\n`);
+        return 1;
     }
-};
-/*  passthrough flow: POST /command with the arbitrary cmd token  */
-const doPassthrough = async (cmd) => {
-    const ctx = loadContext();
-    if (ctx.port === null)
-        throw new Error("service not running (no port configured)");
-    try {
+    /*  send command: POST /command with the arbitrary cmd token  */
+    async doSend(cmd) {
+        let ctx = this.loadContext();
+        if (ctx.port === null) {
+            await this.doStart();
+            ctx = this.loadContext();
+            if (ctx.port === null)
+                throw new Error("service not running (no port configured after auto-start)");
+        }
+        const match = await probe(ctx.port, ctx.projectId);
+        if (match !== true) {
+            await this.doStart();
+            ctx = this.loadContext();
+            if (ctx.port === null)
+                throw new Error("service not running (no port configured after auto-start)");
+        }
         const r = await axios.request({
             method: "POST",
             url: `http://${HOST}:${ctx.port}/command`,
             headers: { "Content-Type": "application/json" },
             data: { command: cmd },
-            timeout: 0,
+            timeout: 5000,
             validateStatus: () => true,
             responseType: "text",
             transformResponse: [(x) => x]
@@ -274,36 +399,71 @@ const doPassthrough = async (cmd) => {
             process.stdout.write("\n");
         return r.status >= 200 && r.status < 300 ? 0 : 1;
     }
-    catch (err) {
-        if (isConnRefused(err))
-            throw new Error("service not running (connection refused)");
-        throw err;
+    /*  stop flow: no-op if no port configured or connection refused  */
+    async doStop() {
+        const ctx = this.loadContext();
+        if (ctx.port === null) {
+            this.log.write("info", "service: not running (no port configured)");
+            return 0;
+        }
+        const match = await probe(ctx.port, ctx.projectId);
+        if (match === false) {
+            this.log.write("info", `service: not running (port ${ctx.port} in use by foreign service)`);
+            return 1;
+        }
+        if (match === null) {
+            this.log.write("info", `service: not running (port ${ctx.port} not responding)`);
+            clearPort(ctx.svc);
+            return 0;
+        }
+        const r = await axios.request({
+            method: "GET",
+            url: `http://${HOST}:${ctx.port}/stop`,
+            timeout: 5000,
+            validateStatus: () => true
+        });
+        const ok = r.status >= 200 && r.status < 300;
+        clearPort(ctx.svc);
+        return ok ? 0 : 1;
     }
-};
-/*  command-line handling  */
-const serviceCommand = {
-    command: "service",
-    describe: "Manage per-project background HTTP service",
-    builder: (yargs) => {
-        return yargs
-            .command("start", "Start the background service", {}, async () => {
-            process.exit(await doStart());
-        })
-            .command("stop", "Stop the background service", {}, async () => {
-            process.exit(await doStop());
-        })
-            .command("$0 <cmd>", "Send an arbitrary command to the service", (y) => {
-            return y.positional("cmd", {
-                type: "string",
-                describe: "Command token to dispatch"
-            });
-        }, async (argv) => {
-            process.exit(await doPassthrough(String(argv.cmd)));
-        })
-            .demandCommand(1, "You need to specify a service subcommand");
-    },
-    handler: () => {
-        /*  dispatched by nested subcommands  */
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase service"  */
+        const service = program
+            .command("service")
+            .description("Manage per-project background HTTP service")
+            .action(() => {
+            service.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase service start"  */
+        service
+            .command("start")
+            .description("Start the background service")
+            .action(async () => {
+            process.exit(await this.doStart());
+        });
+        /*  register CLI sub-command "ase service status"  */
+        service
+            .command("status")
+            .description("Report whether the background service is running")
+            .action(async () => {
+            process.exit(await this.doStatus());
+        });
+        /*  register CLI sub-command "ase service send"  */
+        service
+            .command("send")
+            .description("Send a command to the background service")
+            .argument("<cmd>", "Command token to dispatch to the service")
+            .action(async (cmd) => {
+            process.exit(await this.doSend(cmd));
+        });
+        /*  register CLI sub-command "ase service stop"  */
+        service
+            .command("stop")
+            .description("Stop the background service")
+            .action(async () => {
+            process.exit(await this.doStop());
+        });
     }
-};
-export default serviceCommand;
+}