@wrongstack/persistence 0.305.0 → 0.305.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './atomic-write.js';
+export * from './project-endpoint.js';
 export * from './socket-path.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -239,6 +239,11 @@ var atomicWrite = defaultPrimitives.atomicWrite;
 var ensureDir = defaultPrimitives.ensureDir;
 var withFileLock = defaultPrimitives.withFileLock;
 
+// src/project-endpoint.ts
+import * as fsPromises from "node:fs/promises";
+import * as net from "node:net";
+import * as path2 from "node:path";
+
 // src/socket-path.ts
 function unixSocketPathLimit(platform = process.platform) {
   if (platform === "darwin" || platform === "freebsd" || platform === "openbsd") return 103;
@@ -259,13 +264,116 @@ function assertUnixSocketPathWithinLimit(socketPath, service, platform = process
     `${service} IPC socket path is ${check.byteLength} bytes, over the ${platform} sun_path limit of ${check.maxBytes} usable bytes: ${socketPath}. Set a shorter TMPDIR to relocate WrongStack IPC sockets.`
   );
 }
+
+// src/project-endpoint.ts
+var PROBE_TIMEOUT_MS = 500;
+var DEFAULT_MAX_ATTEMPTS = 3;
+var ENDPOINT_DIR_MODE = 448;
+var ENDPOINT_FILE_MODE = 384;
+function isErrno(error) {
+  return error instanceof Error;
+}
+function isProjectEndpointLive(endpoint, timeoutMs = PROBE_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (live) => {
+      if (settled) return;
+      settled = true;
+      probe.destroy();
+      resolve(live);
+    };
+    const probe = net.createConnection(endpoint);
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    timer.unref?.();
+    probe.once("connect", () => {
+      clearTimeout(timer);
+      finish(true);
+    });
+    probe.once("error", () => {
+      clearTimeout(timer);
+      finish(false);
+    });
+  });
+}
+async function ensureProjectEndpointDirectory(endpoint, service) {
+  if (process.platform === "win32") return;
+  assertUnixSocketPathWithinLimit(endpoint, service);
+  await fsPromises.mkdir(path2.dirname(endpoint), {
+    recursive: true,
+    mode: ENDPOINT_DIR_MODE
+  });
+}
+function attemptListen(server, endpoint) {
+  return new Promise((resolve) => {
+    const onError = (error) => {
+      server.removeListener("listening", onListening);
+      resolve(error);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      resolve(null);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(endpoint);
+  });
+}
+async function bindProjectEndpoint(options) {
+  const { server, endpoint, service } = options;
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const isWindows = process.platform === "win32";
+  try {
+    await ensureProjectEndpointDirectory(endpoint, service);
+  } catch (error) {
+    return {
+      outcome: "failed",
+      error: isErrno(error) ? error : new Error(String(error))
+    };
+  }
+  let reclaimed = false;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const error = await attemptListen(server, endpoint);
+    if (!error) {
+      if (!isWindows) {
+        await fsPromises.chmod(endpoint, ENDPOINT_FILE_MODE).catch(() => {
+        });
+      }
+      return { outcome: "bound", reclaimedStaleEndpoint: reclaimed };
+    }
+    if (error.code !== "EADDRINUSE") return { outcome: "failed", error };
+    if (isWindows) return { outcome: "already-owned" };
+    if (await isProjectEndpointLive(endpoint)) return { outcome: "already-owned" };
+    try {
+      await fsPromises.rm(endpoint, { force: true });
+      reclaimed = true;
+    } catch (removeError) {
+      const code = isErrno(removeError) ? removeError.code : void 0;
+      if (code !== "ENOENT") {
+        return {
+          outcome: "failed",
+          error: new Error(
+            `${service} could not reclaim its stale IPC endpoint at ${endpoint}: ${isErrno(removeError) ? removeError.message : String(removeError)}`
+          )
+        };
+      }
+    }
+  }
+  return {
+    outcome: "failed",
+    error: new Error(
+      `${service} could not bind its IPC endpoint at ${endpoint} after ${maxAttempts} attempts: the endpoint is in use but no daemon answers on it. Remove the stale socket and retry.`
+    )
+  };
+}
 export {
   PersistenceFsError,
   assertUnixSocketPathWithinLimit,
   atomicWrite,
+  bindProjectEndpoint,
   checkUnixSocketPath,
   createPersistencePrimitives,
   ensureDir,
+  isProjectEndpointLive,
   unixSocketPathLimit,
   withFileLock
 };

package/dist/project-endpoint.d.ts

@@ -0,0 +1,55 @@
+import * as net from 'node:net';
+export type BindProjectEndpointOutcome = 
+/** This process owns the endpoint. It is listening. */
+{
+    readonly outcome: 'bound';
+    readonly reclaimedStaleEndpoint: boolean;
+}
+/**
+ * A live daemon already owns this endpoint. Not an error: the caller lost a
+ * startup race it did not need to win, and must exit 0 without touching
+ * project state. Clients will reach the winner.
+ */
+ | {
+    readonly outcome: 'already-owned';
+}
+/**
+ * The endpoint could not be bound and could not be reclaimed. The caller
+ * should report `error` and exit non-zero. This is the only outcome that
+ * warrants operator attention.
+ */
+ | {
+    readonly outcome: 'failed';
+    readonly error: Error;
+};
+export interface BindProjectEndpointOptions {
+    /** A server that has NOT yet been asked to listen. */
+    readonly server: net.Server;
+    /** Endpoint to bind: a socket path, or a `\\.\pipe\...` name on Windows. */
+    readonly endpoint: string;
+    /** Service name, used only in error text (`kanban`, `sage`, ...). */
+    readonly service: string;
+    /** Override the reclaim attempt budget. Defaults to 3. */
+    readonly maxAttempts?: number;
+}
+/**
+ * True when something is accepting connections at `endpoint` right now.
+ *
+ * This is the only safe way to tell a live owner from a stale socket file, and
+ * the answer decides whether reclaiming is allowed. Any failure — refused,
+ * missing, timed out — reads as "not live": a daemon that cannot be reached
+ * within the probe window cannot be serving clients either, and leaving the
+ * project permanently unstartable is the worse outcome.
+ */
+export declare function isProjectEndpointLive(endpoint: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Bind `endpoint`, reclaiming it from a dead owner when — and only when — a
+ * liveness probe proves no owner is there.
+ *
+ * On success the socket is chmod'ed to `0600`. That is belt-and-braces next to
+ * the `0700` directory, and it is best-effort: a filesystem that rejects the
+ * chmod has not invalidated the directory boundary, so a failure here is not
+ * worth refusing to start over.
+ */
+export declare function bindProjectEndpoint(options: BindProjectEndpointOptions): Promise<BindProjectEndpointOutcome>;
+//# sourceMappingURL=project-endpoint.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/persistence",
-  "version": "0.305.0",
+  "version": "0.305.1",
   "license": "MIT",
   "description": "Dependency-free filesystem persistence primitives shared across WrongStack packages.",
   "repository": {