@anhlp/alp-client 0.0.0-beta.2 → 0.0.1-beta.3

package/dist/index.d.ts

@@ -68,17 +68,32 @@ export function connect(socketPath: string, client?: {
     name: string;
     version: string;
 }, options?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions): Promise<AlpClient>;
+export function readDaemonLifecycle(home: any): Promise<{
+    token: string;
+    pid: number;
+    bootTime: number;
+    action: string;
+} | undefined>;
+/** Serializes requested starts and stops, including the time before alpd has a lock.
+ * Rename publishes a fully populated directory: an existing nonempty directory cannot
+ * be replaced. Reaping/release unlinks only its unique owner token, then rmdir; even
+ * racing stale reapers cannot remove a successor's nonempty directory.
+ */
+export function withDaemonLifecycle(home: any, action: any, run: any, { joinStart }?: {
+    joinStart?: boolean | undefined;
+}): Promise<any>;
 /**
  * Returns the socket of a ready daemon, starting one when none runs.
  * `entry` is the daemon script; it is started through its own detaching launcher so the
  * daemon outlives the client that started it.
  */
-export function ensureDaemon({ home, entry, env, execPath, timeoutMs }?: {
+export function ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleLocked }?: {
     home?: string | undefined;
     entry?: string | undefined;
     env?: NodeJS.ProcessEnv | undefined;
     execPath?: string | undefined;
     timeoutMs?: number | undefined;
+    lifecycleLocked?: boolean | undefined;
 }): Promise<any>;
 export function discoverIntegration(name?: string, options?: {}): Promise<string | undefined>;
 export function startIntegration(nameOrOptions?: string): Promise<any>;

package/dist/index.js

@@ -1,7 +1,7 @@
 // packages/client/src/index.js
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { open, readFile, realpath, stat, lstat, mkdir, readlink, unlink } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { open, readFile, writeFile, realpath, stat, lstat, mkdir, readlink, unlink, readdir, rename, rmdir, link } from "node:fs/promises";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
@@ -197,10 +197,86 @@ async function tail(file, lines = 30) {
     return "";
   }
 }
+async function lifecycleOwners(home) {
+  const directory = path.join(home, "state", "alpd.starting");
+  const names = await readdir(directory).catch((error) => {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  });
+  return names.map((token) => {
+    const match = /^owner-(\d+)-(\d+)-(start|stop)-[a-f0-9-]+$/.exec(token);
+    if (!match) throw new Error("Invalid alpd startup admission owner");
+    return { token, pid: Number(match[1]), bootTime: Number(match[2]), action: match[3] };
+  });
+}
+async function readDaemonLifecycle(home) {
+  return (await lifecycleOwners(home)).find((owner) => lockAlive(owner));
+}
+async function withDaemonLifecycle(home, action, run, { joinStart = false } = {}) {
+  try {
+    await assertPrivateDirectory(home, { create: true });
+  } catch (cause) {
+    throw Object.assign(new Error(`ALP_HOME_UNUSABLE, alpd failed to start while preparing its home: ${cause.message}`, { cause }), { code: "ALP_HOME_UNUSABLE" });
+  }
+  const state = path.join(home, "state");
+  await assertPrivateDirectory(state, { create: true });
+  const directory = path.join(state, "alpd.starting");
+  const token = `owner-${process.pid}-${bootTime()}-${action}-${randomUUID()}`;
+  const candidate = path.join(state, `alpd.starting-${token}`);
+  await mkdir(candidate, { mode: 448 });
+  await writeFile(path.join(candidate, token), JSON.stringify({ pid: process.pid, bootTime: bootTime(), action }), { mode: 384 });
+  try {
+    let joined = false;
+    if (joinStart) {
+      const owner = await readDaemonLifecycle(home);
+      if (owner?.action === "start") {
+        try {
+          await link(path.join(directory, owner.token), path.join(directory, token));
+          joined = true;
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+        }
+      }
+    }
+    while (!joined) {
+      try {
+        await rename(candidate, directory);
+        break;
+      } catch (error) {
+        if (!["EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].includes(error.code)) throw error;
+        for (const owner of await lifecycleOwners(home)) {
+          if (!lockAlive(owner)) await unlink(path.join(directory, owner.token)).catch((error2) => {
+            if (error2.code !== "ENOENT") throw error2;
+          });
+        }
+        await rmdir(directory).catch((error2) => {
+          if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error2.code)) throw error2;
+        });
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    try {
+      return await run();
+    } finally {
+      await unlink(path.join(directory, token));
+      await rmdir(directory).catch((error) => {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+      });
+    }
+  } finally {
+    await unlink(path.join(candidate, token)).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    await rmdir(candidate).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
 async function ensureDaemon({ home = alpHome(), entry = (
   /** @type {string | undefined} */
   void 0
-), env = process.env, execPath = process.execPath, timeoutMs = 15e3 } = {}) {
+), env = process.env, execPath = process.execPath, timeoutMs = 15e3, lifecycleLocked = false } = {}) {
+  if (!lifecycleLocked) return withDaemonLifecycle(home, "start", () => ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleLocked: true }));
   const ready = async () => {
     const lock = await readLock(home);
     return lockAlive(lock) && lock.ready ? lock.socket : void 0;
@@ -213,7 +289,7 @@ async function ensureDaemon({ home = alpHome(), entry = (
     entry ??= await findDaemonEntry({ home, env });
     if (!entry) throw new Error("ALP daemon is not running and alpd.js was not found. Install the ALP CLI and run `alp daemon start`, or set ALP_DAEMON_ENTRY to alpd.js");
     await new Promise((resolve, reject) => {
-      const launcher = spawn(execPath, [entry, "--detach"], {
+      const launcher = spawn(execPath, [entry, "--detach", `--startup-timeout=${timeoutMs}`], {
         env: { ...env, ALP_HOME: home, ELECTRON_RUN_AS_NODE: "1" },
         stdio: ["ignore", "ignore", "pipe"],
         windowsHide: true
@@ -415,8 +491,10 @@ export {
   ensureDaemon,
   findDaemonEntry,
   lockAlive,
+  readDaemonLifecycle,
   readLock,
   redactUrl,
   releaseDaemonLock,
-  startIntegration
+  startIntegration,
+  withDaemonLifecycle
 };

package/dist/supervise.js

@@ -1,7 +1,7 @@
 // packages/client/src/supervise.js
 import { mkdir, unlink, writeFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { ensureDaemon, lockAlive, readLock } from "./index.js";
+import { ensureDaemon, lockAlive, readLock, withDaemonLifecycle } from "./index.js";
 import { installedProgram, serviceFor, startService } from "./service.js";
 var holdFile = (home) => path.join(home, "state", "alpd.held");
 async function holdDaemon(home, by = "alp daemon stop") {
@@ -24,16 +24,20 @@ async function whenReady(home, timeoutMs) {
   }
   throw new Error(`alpd did not become ready within ${timeoutMs / 1e3} s; see ${path.join(home, "logs")}`);
 }
-async function startDaemon({ home, entry, env = process.env, timeoutMs = 15e3 }) {
-  await releaseHold(home);
-  const lock = await readLock(home);
-  if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
-  const service = serviceFor({ home, env });
-  if (service && await installedProgram(service)) {
-    await startService(service);
-    return whenReady(home, timeoutMs);
-  }
-  return ensureDaemon({ home, entry, env, timeoutMs });
+async function startDaemon({ home, entry, env = process.env, timeoutMs = 15e3, automatic = false }) {
+  return withDaemonLifecycle(home, "start", async () => {
+    if (automatic) {
+      if (await daemonHeld(home)) return;
+    } else await releaseHold(home);
+    const lock = await readLock(home);
+    if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+    const service = serviceFor({ home, env });
+    if (service && await installedProgram(service)) {
+      await startService(service);
+      return whenReady(home, timeoutMs);
+    }
+    return ensureDaemon({ home, entry, env, timeoutMs, lifecycleLocked: true });
+  });
 }
 function superviseDaemon({ home, entry, env = process.env, intervalMs = 5e3, misses = 2, log = () => {
 } }) {
@@ -41,7 +45,9 @@ function superviseDaemon({ home, entry, env = process.env, intervalMs = 5e3, mis
   let missed = 0;
   let starting;
   const start = (reason) => {
-    starting ??= startDaemon({ home, entry: typeof entry === "function" ? entry() : entry, env }).then(() => log(`alpd ${reason}`), (error) => log(`could not start alpd: ${error?.message ?? error}`)).finally(() => {
+    starting ??= startDaemon({ home, entry: typeof entry === "function" ? entry() : entry, env, automatic: reason !== "started with Paseo" }).then((socket) => {
+      if (socket) log(`alpd ${reason}`);
+    }, (error) => log(`could not start alpd: ${error?.message ?? error}`)).finally(() => {
       starting = void 0;
       missed = 0;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhlp/alp-client",
-  "version": "0.0.0-beta.2",
+  "version": "0.0.1-beta.3",
   "type": "module",
   "description": "ALP client: portable JSON-RPC SDK, WebSocket and Node IPC transports, daemon discovery and setup",
   "files": [
@@ -142,8 +142,8 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@anhlp/alp-core": "0.0.0-beta.2",
-    "@anhlp/alp-protocol": "0.0.0-beta.2"
+    "@anhlp/alp-core": "0.0.1-beta.3",
+    "@anhlp/alp-protocol": "0.0.1-beta.3"
   },
   "scripts": {
     "build": "node ../../scripts/build-workspace.mjs client",

package/src/index.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { open, readFile, realpath, stat, lstat, mkdir, readlink, unlink } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { open, readFile, writeFile, realpath, stat, lstat, mkdir, readlink, unlink, readdir, rename, rmdir, link } from 'node:fs/promises';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
@@ -242,12 +242,83 @@ async function tail(file, lines = 30) {
   try { return scrubText((await readFile(file, 'utf8')).split('\n').slice(-lines).join('\n'), { max: 8000 }); } catch { return ''; }
 }
 
+/** Immutable admission identities live in filenames, including for service hard links. */
+async function lifecycleOwners(home) {
+  const directory = path.join(home, 'state', 'alpd.starting');
+  const names = await readdir(directory).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+  return names.map(token => {
+    const match = /^owner-(\d+)-(\d+)-(start|stop)-[a-f0-9-]+$/.exec(token);
+    if (!match) throw new Error('Invalid alpd startup admission owner');
+    return { token, pid: Number(match[1]), bootTime: Number(match[2]), action: match[3] };
+  });
+}
+
+export async function readDaemonLifecycle(home) {
+  return (await lifecycleOwners(home)).find(owner => lockAlive(owner));
+}
+
+/** Serializes requested starts and stops, including the time before alpd has a lock.
+ * Rename publishes a fully populated directory: an existing nonempty directory cannot
+ * be replaced. Reaping/release unlinks only its unique owner token, then rmdir; even
+ * racing stale reapers cannot remove a successor's nonempty directory.
+ */
+export async function withDaemonLifecycle(home, action, run, { joinStart = false } = {}) {
+  try {
+    await assertPrivateDirectory(home, { create: true });
+  } catch (cause) {
+    // Admission now prepares the home before the launcher can report this failure.
+    // Preserve the operator-facing startup code at this earlier boundary.
+    throw Object.assign(new Error(`ALP_HOME_UNUSABLE, alpd failed to start while preparing its home: ${cause.message}`, { cause }), { code: 'ALP_HOME_UNUSABLE' });
+  }
+  const state = path.join(home, 'state');
+  await assertPrivateDirectory(state, { create: true });
+  const directory = path.join(state, 'alpd.starting');
+  const token = `owner-${process.pid}-${bootTime()}-${action}-${randomUUID()}`;
+  const candidate = path.join(state, `alpd.starting-${token}`);
+  await mkdir(candidate, { mode: 0o700 });
+  await writeFile(path.join(candidate, token), JSON.stringify({ pid: process.pid, bootTime: bootTime(), action }), { mode: 0o600 });
+  try {
+    let joined = false;
+    if (joinStart) {
+      const owner = await readDaemonLifecycle(home);
+      if (owner?.action === 'start') {
+        try {
+          // Linking the unique source token both validates this generation and
+          // pins its directory until this service has finished starting.
+          await link(path.join(directory, owner.token), path.join(directory, token));
+          joined = true;
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+    }
+    while (!joined) {
+      try { await rename(candidate, directory); break; }
+      catch (error) {
+        if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EACCES'].includes(error.code)) throw error;
+        for (const owner of await lifecycleOwners(home)) {
+          if (!lockAlive(owner)) await unlink(path.join(directory, owner.token)).catch(error => { if (error.code !== 'ENOENT') throw error; });
+        }
+        await rmdir(directory).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+    }
+    try { return await run(); }
+    finally {
+      await unlink(path.join(directory, token));
+      await rmdir(directory).catch(error => { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; });
+    }
+  } finally {
+    await unlink(path.join(candidate, token)).catch(error => { if (error.code !== 'ENOENT') throw error; });
+    await rmdir(candidate).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
 /**
  * Returns the socket of a ready daemon, starting one when none runs.
  * `entry` is the daemon script; it is started through its own detaching launcher so the
  * daemon outlives the client that started it.
  */
-export async function ensureDaemon({ home = alpHome(), entry = /** @type {string | undefined} */ (undefined), env = process.env, execPath = process.execPath, timeoutMs = 15_000 } = {}) {
+export async function ensureDaemon({ home = alpHome(), entry = /** @type {string | undefined} */ (undefined), env = process.env, execPath = process.execPath, timeoutMs = 15_000, lifecycleLocked = false } = {}) {
+  if (!lifecycleLocked) return withDaemonLifecycle(home, 'start', () => ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleLocked: true }));
   const ready = async () => {
     const lock = await readLock(home);
     return lockAlive(lock) && lock.ready ? lock.socket : undefined;
@@ -260,7 +331,7 @@ export async function ensureDaemon({ home = alpHome(), entry = /** @type {string
     entry ??= await findDaemonEntry({ home, env });
     if (!entry) throw new Error('ALP daemon is not running and alpd.js was not found. Install the ALP CLI and run `alp daemon start`, or set ALP_DAEMON_ENTRY to alpd.js');
     await new Promise((resolve, reject) => {
-      const launcher = spawn(execPath, [entry, '--detach'], {
+      const launcher = spawn(execPath, [entry, '--detach', `--startup-timeout=${timeoutMs}`], {
         env: { ...env, ALP_HOME: home, ELECTRON_RUN_AS_NODE: '1' },
         stdio: ['ignore', 'ignore', 'pipe'],
         windowsHide: true,

package/src/supervise.js

@@ -1,6 +1,6 @@
 import { mkdir, unlink, writeFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { ensureDaemon, lockAlive, readLock } from './index.js';
+import { ensureDaemon, lockAlive, readLock, withDaemonLifecycle } from './index.js';
 import { installedProgram, serviceFor, startService } from './service.js';
 
 /**
@@ -41,16 +41,20 @@ async function whenReady(home, timeoutMs) {
  * Starts alpd for `home` unless it runs, and lifts a hold: someone asked for it.
  * Returns its socket.
  */
-export async function startDaemon({ home, entry, env = process.env, timeoutMs = 15_000 }) {
-  await releaseHold(home);
-  const lock = await readLock(home);
-  if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
-  const service = serviceFor({ home, env });
-  if (service && await installedProgram(service)) {
-    await startService(service);
-    return whenReady(home, timeoutMs);
-  }
-  return ensureDaemon({ home, entry, env, timeoutMs });
+export async function startDaemon({ home, entry, env = process.env, timeoutMs = 15_000, automatic = false }) {
+  return withDaemonLifecycle(home, 'start', async () => {
+    if (automatic) {
+      if (await daemonHeld(home)) return;
+    } else await releaseHold(home);
+    const lock = await readLock(home);
+    if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+    const service = serviceFor({ home, env });
+    if (service && await installedProgram(service)) {
+      await startService(service);
+      return whenReady(home, timeoutMs);
+    }
+    return ensureDaemon({ home, entry, env, timeoutMs, lifecycleLocked: true });
+  });
 }
 
 /**
@@ -64,8 +68,8 @@ export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5
   let missed = 0;
   let starting;
   const start = reason => {
-    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env })
-      .then(() => log(`alpd ${reason}`), error => log(`could not start alpd: ${error?.message ?? error}`))
+    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env, automatic: reason !== 'started with Paseo' })
+      .then(socket => { if (socket) log(`alpd ${reason}`); }, error => log(`could not start alpd: ${error?.message ?? error}`))
       .finally(() => { starting = undefined; missed = 0; });
     return starting;
   };