obsbot-mcp 0.7.0 → 0.9.0

package/dist/ipc/coordinator.js

@@ -1,31 +1,49 @@
-import { elect, rendezvousPath } from "./rendezvous.js";
+import { elect as electEndpoint, rendezvousPath } from "./rendezvous.js";
 import { OwnerServer } from "./owner.js";
 import { OwnerClient } from "./client.js";
-/**
- * Wrap a tool runner so calls execute strictly one-at-a-time. This is THE
- * single-camera lock: it must guard both the owner's own MCP calls AND the
- * calls forwarded from clients, because the owner's local path does not pass
- * through OwnerServer's queue. Errors don't break the chain.
- */
-export function serialize(fn) {
-    let tail = Promise.resolve();
-    return (tool, args) => {
-        const run = tail.then(() => fn(tool, args));
-        tail = run.then(() => undefined, () => undefined);
-        return run;
-    };
-}
+import { CallGate, StepDownError } from "./gate.js";
+import { buildLabel, compareBuilds, unstampedBuild } from "./build-id.js";
+export const DEFAULT_TIMING = {
+    helloTimeoutMs: 2000,
+    stepDownGraceMs: 500,
+    electionJitterMs: 100,
+    stepDownTimeoutMs: 15000,
+    releaseTimeoutMs: 10000,
+    maxTakeoverRounds: 5,
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const errText = (e) => (e instanceof Error ? e.message : String(e));
 export class Coordinator {
     runLocal;
-    path;
     role = "none";
     client;
     ownerServer;
-    electing;
-    /** `runLocal` should already be serialize()-wrapped by the caller. */
-    constructor(runLocal, path = rendezvousPath()) {
+    steppingDown = false;
+    /** Client of an owner that is older than us and could not be made to hand over. */
+    blocked = false;
+    /** Counts the owners this instance has been a client of. Tells one connection from the next. */
+    connection = 0;
+    closing = false;
+    /** A role change in progress — an election, or stepping down. Never rejects. */
+    pending;
+    /** THE single-camera lock: the owner's own calls and the ones forwarded to it. */
+    gate = new CallGate();
+    path;
+    build;
+    pid;
+    release;
+    log;
+    t;
+    elect;
+    constructor(runLocal, opts = {}) {
         this.runLocal = runLocal;
-        this.path = path;
+        this.path = opts.path ?? rendezvousPath();
+        this.build = opts.build ?? unstampedBuild();
+        this.pid = opts.pid ?? process.pid;
+        this.release = opts.release ?? (async () => { });
+        this.log = opts.log ?? (() => { });
+        this.t = { ...DEFAULT_TIMING, ...opts.timing };
+        this.elect = opts.elect ?? electEndpoint;
     }
     /** Establish the initial role eagerly at startup. */
     start() {
@@ -35,59 +53,277 @@ export class Coordinator {
         return this.role;
     }
     async dispatch(tool, args) {
-        await this.ensureRole();
-        try {
-            return await this.runByRole(tool, args);
-        }
-        catch (e) {
-            if (this.role === "client" && this.client?.closed) {
-                // The owner went away mid-call → re-elect and retry exactly once.
-                this.reset();
-                await this.ensureRole();
-                return this.runByRole(tool, args);
+        let failure;
+        // Twice at most: a call that lost its owner is retried exactly once.
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const target = await this.settle();
+            try {
+                return target === "local"
+                    ? await this.gate.run(() => this.runLocal(tool, args))
+                    : await target.request({ tool, args });
+            }
+            catch (e) {
+                if (e instanceof StepDownError) {
+                    // We were the owner and are handing over; this call had not started.
+                    // settle() waits the handover out, and the retry forwards it.
+                    failure = e;
+                    continue;
+                }
+                if (target !== "local" && target.closed) {
+                    failure = e;
+                    this.ownerLost(target);
+                    continue;
+                }
+                throw e; // a genuine owner-side error → surface it unchanged
             }
-            throw e; // a genuine owner-side error → surface it unchanged
         }
+        throw failure;
     }
-    runByRole(tool, args) {
-        return this.role === "owner"
-            ? this.runLocal(tool, args)
-            : this.client.request({ tool, args });
+    /**
+     * Wait until this instance has a role it may use, and say where a call goes:
+     * run here, or forward over this connection.
+     *
+     * The answer is taken in the same tick the decision is made and handed to the
+     * caller. Calls arrive in parallel, and one of them may be reconnecting while
+     * another resumes: a caller that re-read `this.client` after an await could
+     * find it gone, or pointing at an owner nobody has checked yet.
+     */
+    async settle() {
+        let asked = false;
+        for (let round = 0; round < 8; round++) {
+            await this.ensureRole();
+            if (this.role === "owner")
+                return "local";
+            if (this.role !== "client" || !this.client)
+                continue; // a role change began while we waited
+            if (!this.blocked)
+                return this.client;
+            // An older owner that could not hand over. Ask once more, then give up:
+            // a call that succeeds on code the caller did not expect is worse than
+            // one that fails and says why.
+            if (asked)
+                throw new Error(this.blockedMessage());
+            asked = true;
+            await this.tryAgain(this.connection);
+        }
+        throw new Error(`obsbot-mcp: ipc role did not settle for ${this.path}`);
     }
     async close() {
-        if (this.ownerServer)
-            await this.ownerServer.close();
-        this.client?.close();
+        this.closing = true;
+        const server = this.ownerServer;
+        const client = this.client;
         this.reset();
+        client?.close();
+        if (server)
+            await server.close();
+        // A role change that was under way sees `closing` and cleans up after itself.
+        while (this.pending)
+            await this.pending;
     }
     reset() {
         this.role = "none";
         this.client = undefined;
         this.ownerServer = undefined;
+        this.steppingDown = false;
+        this.blocked = false;
+    }
+    jitter() {
+        return Math.floor(Math.random() * (this.t.electionJitterMs + 1));
     }
-    ensureRole() {
+    /** Queue a role change behind any already under way. The result never rejects. */
+    begin(work) {
+        const prev = this.pending ?? Promise.resolve();
+        const p = prev
+            .then(work)
+            .catch((e) => this.log(`obsbot-mcp: ipc role change failed: ${errText(e)}`))
+            .finally(() => {
+            if (this.pending === p)
+                this.pending = undefined;
+        });
+        this.pending = p;
+        return p;
+    }
+    async ensureRole() {
+        while (this.pending)
+            await this.pending;
         if (this.role !== "none")
-            return Promise.resolve();
-        // Collapse concurrent callers onto one election.
-        if (!this.electing) {
-            this.electing = this.doElect().finally(() => {
-                this.electing = undefined;
-            });
-        }
-        return this.electing;
+            return;
+        if (this.closing)
+            throw new Error("obsbot-mcp: ipc coordinator is closed");
+        let failed = false;
+        let failure;
+        await this.begin(async () => {
+            try {
+                await this.doElect();
+            }
+            catch (e) {
+                failed = true;
+                failure = e;
+            }
+        });
+        if (failed)
+            throw failure;
     }
+    /**
+     * Settle on a role: bind the endpoint, or connect to whoever holds it and
+     * compare builds. If ours is newer, ask for the endpoint and go round again.
+     */
     async doElect() {
-        const r = await elect(this.path);
-        if (r.role === "owner") {
-            this.ownerServer = new OwnerServer(r.server, (body) => {
-                const { tool, args } = body;
-                return this.runLocal(tool, args);
-            });
-            this.role = "owner";
+        let takeovers = 0;
+        for (let attempt = 0; attempt < this.t.maxTakeoverRounds + 3; attempt++) {
+            if (this.closing || this.role !== "none")
+                return;
+            const r = await this.elect(this.path);
+            if (r.role === "owner")
+                return this.becomeOwner(r.server);
+            const client = OwnerClient.adopt(r.socket);
+            let peer;
+            try {
+                peer = await client.hello(this.build, this.pid, this.t.helloTimeoutMs);
+            }
+            catch {
+                client.close(); // the owner went away between connect and hello
+                continue;
+            }
+            // An owner that cannot take part in a handover is older than anything that can.
+            if (peer.kind !== "peer")
+                return this.becomeClient(client, peer, true);
+            if (compareBuilds(this.build, peer.build) <= 0)
+                return this.becomeClient(client, peer, false);
+            // From here on the owner is older than us, so settling as its client means refusing to use it.
+            if (takeovers >= this.t.maxTakeoverRounds)
+                return this.becomeClient(client, peer, true);
+            takeovers++;
+            this.log(`obsbot-mcp: ipc takeover requested from pid ${peer.pid}`);
+            let granted;
+            try {
+                granted = await client.takeover(this.build, this.pid, this.t.helloTimeoutMs);
+            }
+            catch {
+                granted = true; // closed before it could answer: the endpoint is free either way
+            }
+            if (!granted || !(await client.waitClosed(this.t.stepDownTimeoutMs))) {
+                return this.becomeClient(client, peer, true);
+            }
+            // The old owner has let go. Go round again and bind.
+        }
+        throw new Error(`obsbot-mcp: ipc could not settle on an owner for ${this.path}`);
+    }
+    becomeOwner(server) {
+        if (this.closing) {
+            server.close();
+            return;
+        }
+        this.ownerServer = new OwnerServer(server, (body) => {
+            const { tool, args } = body;
+            return this.gate.run(() => this.runLocal(tool, args));
+        }, {
+            identity: () => ({ build: this.build, pid: this.pid }),
+            takeover: (build, pid) => this.onTakeover(build, pid),
+        });
+        this.role = "owner";
+        this.log("obsbot-mcp: ipc role=owner");
+    }
+    becomeClient(client, peer, blocked) {
+        if (this.closing) {
+            client.close();
+            return;
+        }
+        this.client = client;
+        this.role = "client";
+        this.blocked = blocked;
+        this.connection++;
+        // Re-elect when the connection closes, not when we next have something to
+        // send: an idle newer build must not sit disconnected while an older one
+        // takes the endpoint and runs calls.
+        client.onClose(() => this.ownerLost(client));
+        const owner = peer.kind === "peer"
+            ? `owner-pid=${peer.pid} owner-build=${buildLabel(peer.build)}`
+            : "owner-pid=unknown owner-build=legacy";
+        this.log(`obsbot-mcp: ipc role=client ${owner}`);
+        if (blocked) {
+            this.log("obsbot-mcp: ipc owner is older and cannot hand over; tool calls will fail until it exits");
+        }
+    }
+    /**
+     * The owner is older and still there. Try once more: a fresh connection,
+     * hello, takeover.
+     *
+     * Queued like any other role change, so calls that arrive together wait for
+     * it instead of finding the role half torn down. `seen` is the connection the
+     * caller was looking at: if that is no longer the current one, someone has
+     * asked again since, and asking a second time would tell us nothing new.
+     */
+    tryAgain(seen) {
+        return this.begin(async () => {
+            if (this.role !== "client" || !this.blocked || this.connection !== seen)
+                return;
+            const client = this.client;
+            this.reset(); // first, so closing our own connection is not mistaken for losing the owner
+            client?.close();
+            await this.doElect();
+        });
+    }
+    blockedMessage() {
+        return ("obsbot-mcp: an older instance owns the camera endpoint and cannot hand it over. " +
+            "This instance will not run calls on older code. " +
+            `Stop the process listening on ${this.path}; the next call will take over.`);
+    }
+    /**
+     * The owner has gone. Re-elect — after the grace period if it stepped down
+     * for someone, so the successor binds first; after jitter alone if it simply
+     * went, so clients that all lost it at once do not stampede.
+     */
+    ownerLost(client) {
+        if (this.client !== client || this.closing)
+            return;
+        const delay = (client.noticed ? this.t.stepDownGraceMs : 0) + this.jitter();
+        this.reset();
+        void this.begin(async () => {
+            await sleep(delay);
+            await this.doElect();
+        });
+    }
+    /** A client asks for the endpoint. Both sides run the same comparison, so this cannot disagree with it. */
+    onTakeover(build, pid) {
+        if (compareBuilds(build, this.build) <= 0) {
+            return { ipc: "takeover", granted: false, reason: "not-newer" };
+        }
+        this.stepDown(pid);
+        return { ipc: "takeover", granted: true };
+    }
+    stepDown(successorPid) {
+        if (this.steppingDown)
+            return; // a second request while stepping down needs nothing more
+        this.steppingDown = true;
+        const server = this.ownerServer;
+        this.log(`obsbot-mcp: ipc stepping down for pid ${successorPid}`);
+        void this.begin(async () => {
+            await this.gate.close(); // the call in flight finishes; nothing else starts
+            await server.idle(); // …and its reply has been written
+            await this.releaseBounded(); // the successor cannot open the camera until this is done
+            await server.stepDown({ ipc: "stepping-down", successorPid });
+            this.reset();
+            this.gate.open();
+            // Let the successor bind before we look for an owner to be a client of.
+            await sleep(this.t.stepDownGraceMs + this.jitter());
+            await this.doElect();
+        });
+    }
+    /** A release that throws or never settles must not stop the handover. */
+    async releaseBounded() {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`release did not finish in ${this.t.releaseTimeoutMs} ms`)), this.t.releaseTimeoutMs);
+        });
+        try {
+            await Promise.race([this.release(), timeout]);
+        }
+        catch (e) {
+            this.log(`obsbot-mcp: ipc release failed while stepping down: ${errText(e)}`);
         }
-        else {
-            this.client = OwnerClient.adopt(r.socket);
-            this.role = "client";
+        finally {
+            clearTimeout(timer);
         }
     }
 }

package/dist/ipc/coordinator.js.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.js","sourceRoot":"","sources":["../../src/ipc/coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB1C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,EAAY;IACpC,IAAI,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/C,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QACpB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5C,IAAI,GAAG,GAAG,CAAC,IAAI,CACb,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;AACJ,CAAC;AAID,MAAM,OAAO,WAAW;IAQH;IACA;IARX,IAAI,GAAa,MAAM,CAAC;IACxB,MAAM,CAAe;IACrB,WAAW,CAAe;IAC1B,QAAQ,CAAiB;IAEjC,sEAAsE;IACtE,YACmB,QAAkB,EAClB,OAAe,cAAc,EAAE;QAD/B,aAAQ,GAAR,QAAQ,CAAU;QAClB,SAAI,GAAJ,IAAI,CAA2B;IAC/C,CAAC;IAEJ,qDAAqD;IACrD,KAAK;QACH,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,IAA6B;QACxD,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAClD,kEAAkE;gBAClE,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;gBACxB,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACpC,CAAC;YACD,MAAM,CAAC,CAAC,CAAC,oDAAoD;QAC/D,CAAC;IACH,CAAC;IAEO,SAAS,CAAC,IAAY,EAAE,IAA6B;QAC3D,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO;YAC1B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;YAC3B,CAAC,CAAC,IAAI,CAAC,MAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACrD,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC/B,CAAC;IAEO,UAAU;QAChB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QACnD,iDAAiD;QACjD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;gBAC1C,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBACpD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAuD,CAAC;gBAC/E,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;QACvB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"coordinator.js","sourceRoot":"","sources":["../../src/ipc/coordinator.ts"],"names":[],"mappings":"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"}

package/dist/ipc/gate.d.ts

@@ -0,0 +1,14 @@
+/** Thrown to a call that had not started when the gate closed. */
+export declare class StepDownError extends Error {
+    constructor();
+}
+export declare class CallGate {
+    private tail;
+    private closed;
+    /** Run `fn` after every call queued before it. Rejects with StepDownError if the gate closes first. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Refuse calls that have not started; resolve when the running one has finished. */
+    close(): Promise<void>;
+    /** Accept calls again. */
+    open(): void;
+}

package/dist/ipc/gate.js

@@ -0,0 +1,45 @@
+// ---------------------------------------------------------------------------
+// The single-camera lock, with a way to close it.
+//
+// Tool calls run strictly one at a time: the camera is one device and the XU
+// selector-2 reply mailbox is a single shared slot, so two calls in flight at
+// once would interleave on the wire. That part is unchanged from the old
+// serialize() wrapper.
+//
+// What is new is close(). An owner that is handing the endpoint to a newer
+// build must let the call that is RUNNING finish, and must stop every call that
+// has not started — those belong to the new owner now. close() does both, and
+// resolves once nothing is running.
+// ---------------------------------------------------------------------------
+/** Thrown to a call that had not started when the gate closed. */
+export class StepDownError extends Error {
+    constructor() {
+        super("obsbot-mcp: this instance is handing the camera to a newer build");
+        this.name = "StepDownError";
+    }
+}
+export class CallGate {
+    tail = Promise.resolve();
+    closed = false;
+    /** Run `fn` after every call queued before it. Rejects with StepDownError if the gate closes first. */
+    run(fn) {
+        const run = this.tail.then(() => {
+            if (this.closed)
+                throw new StepDownError();
+            return fn();
+        });
+        // Errors don't break the chain.
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Refuse calls that have not started; resolve when the running one has finished. */
+    async close() {
+        this.closed = true;
+        await this.tail;
+    }
+    /** Accept calls again. */
+    open() {
+        this.closed = false;
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/ipc/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/ipc/gate.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,yEAAyE;AACzE,uBAAuB;AACvB,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;AAChF,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E,kEAAkE;AAClE,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC;QACE,KAAK,CAAC,kEAAkE,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,QAAQ;IACX,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3C,MAAM,GAAG,KAAK,CAAC;IAEvB,uGAAuG;IACvG,GAAG,CAAI,EAAoB;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YAC9B,IAAI,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,aAAa,EAAE,CAAC;YAC3C,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC,CAAC;QACH,gCAAgC;QAChC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAClB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC;IAED,qFAAqF;IACrF,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,IAAI,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,0BAA0B;IAC1B,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;CACF"}

package/dist/ipc/owner.d.ts

@@ -1,4 +1,6 @@
 import net from "node:net";
+import type { BuildId } from "./build-id.js";
+import { type SteppingDownBody, type TakeoverResult } from "./protocol.js";
 export type Handler = (body: unknown) => Promise<unknown>;
 export type ReplyBody = {
     ok: true;
@@ -7,15 +9,39 @@ export type ReplyBody = {
     ok: false;
     error: string;
 };
+export interface ControlHandlers {
+    /** This instance's identity, for the hello reply. */
+    identity: () => {
+        build: BuildId;
+        pid: number;
+    };
+    /** A client asks for the endpoint. Decide; if granted, the caller starts stepping down. */
+    takeover: (build: BuildId, pid: number) => TakeoverResult;
+}
 export declare class OwnerServer {
     private readonly server;
     private readonly handle;
+    private readonly control;
     /** Single promise chain → exactly one handler call runs at a time. */
     private queue;
     private readonly sockets;
-    constructor(server: net.Server, handle: Handler);
+    constructor(server: net.Server, handle: Handler, control: ControlHandlers);
     private accept;
+    /** Answer a control message at once, outside the queue. False if `msg` is not one. */
+    private answerControl;
     private enqueue;
+    /** The reply for a request, or undefined when the request must go unanswered. */
     private run;
+    /** Resolves once every request received so far has been answered or dropped. */
+    idle(): Promise<void>;
+    /**
+     * Give up the endpoint in an orderly way: free the name, tell every client
+     * why, and let what is already written reach them.
+     *
+     * end(), not destroy(): destroy() discards whatever is still buffered, which
+     * would lose the notice and could truncate the reply to the call that just
+     * finished — a snapshot is megabytes.
+     */
+    stepDown(notice: SteppingDownBody): Promise<void>;
     close(): Promise<void>;
 }

package/dist/ipc/owner.js

@@ -1,13 +1,18 @@
-import { encodeFrame, FrameDecoder } from "./protocol.js";
+import { StepDownError } from "./gate.js";
+import { encodeFrame, FrameDecoder, NOTICE_ID, asHello, asTakeover, } from "./protocol.js";
+/** How long a client gets to close its end after we have ended ours. */
+const STRAGGLER_MS = 1000;
 export class OwnerServer {
     server;
     handle;
+    control;
     /** Single promise chain → exactly one handler call runs at a time. */
     queue = Promise.resolve();
     sockets = new Set();
-    constructor(server, handle) {
+    constructor(server, handle, control) {
         this.server = server;
         this.handle = handle;
+        this.control = control;
         this.server.on("connection", (sock) => this.accept(sock));
     }
     accept(sock) {
@@ -22,8 +27,10 @@ export class OwnerServer {
                 sock.destroy(); // unrecoverable framing error → drop this client
                 return;
             }
-            for (const msg of msgs)
-                this.enqueue(sock, msg);
+            for (const msg of msgs) {
+                if (!this.answerControl(sock, msg))
+                    this.enqueue(sock, msg);
+            }
         });
         const drop = () => {
             this.sockets.delete(sock);
@@ -31,24 +38,80 @@ export class OwnerServer {
         sock.on("close", drop);
         sock.on("error", drop);
     }
+    /** Answer a control message at once, outside the queue. False if `msg` is not one. */
+    answerControl(sock, msg) {
+        const reply = (result) => {
+            if (!sock.destroyed)
+                sock.write(encodeFrame({ id: msg.id, body: { ok: true, result } }));
+        };
+        if (asHello(msg.body)) {
+            reply({ ipc: "hello", ...this.control.identity() });
+            return true;
+        }
+        const takeover = asTakeover(msg.body);
+        if (takeover) {
+            // Written before anything the grant sets in motion can close this socket.
+            reply(this.control.takeover(takeover.build, takeover.pid));
+            return true;
+        }
+        return false;
+    }
     enqueue(sock, msg) {
         // Chain onto the shared queue so requests run one-at-a-time across all
         // clients. The chain never rejects (errors become error replies), so one
         // failing op can't stall the rest.
         this.queue = this.queue.then(async () => {
             const body = await this.run(msg.body);
+            if (body === undefined)
+                return;
             if (!sock.destroyed)
                 sock.write(encodeFrame({ id: msg.id, body }));
         });
     }
+    /** The reply for a request, or undefined when the request must go unanswered. */
     async run(reqBody) {
         try {
             return { ok: true, result: await this.handle(reqBody) };
         }
         catch (e) {
+            // The gate closed before this call started: it belongs to the next owner.
+            // An error reply would be wrong — the client would surface it. Left
+            // unanswered, the closing socket makes the client retry it there.
+            if (e instanceof StepDownError)
+                return undefined;
             return { ok: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
+    /** Resolves once every request received so far has been answered or dropped. */
+    idle() {
+        return this.queue;
+    }
+    /**
+     * Give up the endpoint in an orderly way: free the name, tell every client
+     * why, and let what is already written reach them.
+     *
+     * end(), not destroy(): destroy() discards whatever is still buffered, which
+     * would lose the notice and could truncate the reply to the call that just
+     * finished — a snapshot is megabytes.
+     */
+    async stepDown(notice) {
+        // Stops listening now, which frees the endpoint for the successor; the
+        // callback waits for the connections below to finish closing.
+        const closed = new Promise((resolve) => this.server.close(() => resolve()));
+        for (const s of this.sockets) {
+            if (s.destroyed)
+                continue;
+            s.write(encodeFrame({ id: NOTICE_ID, body: notice }));
+            s.end();
+        }
+        const stragglers = setTimeout(() => {
+            for (const s of this.sockets)
+                s.destroy();
+        }, STRAGGLER_MS);
+        await closed;
+        clearTimeout(stragglers);
+        this.sockets.clear();
+    }
     async close() {
         for (const s of this.sockets)
             s.destroy();

package/dist/ipc/owner.js.map

@@ -1 +1 @@
-{"version":3,"file":"owner.js","sourceRoot":"","sources":["../../src/ipc/owner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAc,MAAM,eAAe,CAAC;AAuBtE,MAAM,OAAO,WAAW;IAMH;IACA;IANnB,sEAAsE;IAC9D,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,OAAO,GAAG,IAAI,GAAG,EAAc,CAAC;IAEjD,YACmB,MAAkB,EAClB,MAAe;QADf,WAAM,GAAN,MAAM,CAAY;QAClB,WAAM,GAAN,MAAM,CAAS;QAEhC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,CAAC;IAEO,MAAM,CAAC,IAAgB;QAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAChC,IAAI,IAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,iDAAiD;gBACjE,OAAO;YACT,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,IAAI;gBAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;IAEO,OAAO,CAAC,IAAgB,EAAE,GAAe;QAC/C,uEAAuE;QACvE,yEAAyE;QACzE,mCAAmC;QACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,SAAS;gBAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,GAAG,CAAC,OAAgB;QAChC,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1D,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC;CACF"}
+{"version":3,"file":"owner.js","sourceRoot":"","sources":["../../src/ipc/owner.ts"],"names":[],"mappings":"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"}