@grest-ts/discovery-local 0.0.37 → 0.0.39

package/src/local/GGDiscoveryIPC.ts

@@ -8,10 +8,17 @@ export interface DiscoverApiResult {
     error?: string;
 }
 
+export enum DiscoveryServerKind {
+    Bin = "bin",
+    Embedded = "embedded",
+}
+
 export const GGDiscoveryIPC = {
     discoveryServer: {
         register: IPCServer.defineRequest<GGServiceDiscoveryEntry[], void>("discovery/register"),
         unregister: IPCServer.defineRequest<GGServiceDiscoveryEntry[], void>("discovery/unregister"),
         discoverApi: IPCServer.defineRequest<string, DiscoverApiResult>("discovery/discoverApi"),
+        getServerInfo: IPCServer.defineRequest<undefined, {kind: DiscoveryServerKind}>("discovery/getServerInfo"),
+        requestYield: IPCServer.defineRequest<undefined, void>("discovery/requestYield"),
     }
 }

package/src/local/GGLocalDiscoveryClient.ts

@@ -11,6 +11,18 @@ import {SERVER_ERROR} from "@grest-ts/schema";
  */
 export const GG_LOCAL_ROUTER_PORT = "GG_LOCAL_ROUTER_PORT"
 
+/** Default port for the local discovery router. Centralised so a future
+ *  change (env-var override, per-environment isolation) has one hook. */
+export function getLocalDiscoveryPort(): number {
+    const v = process.env[GG_LOCAL_ROUTER_PORT];
+    if (v === undefined) return 9000;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new Error(`Invalid ${GG_LOCAL_ROUTER_PORT}=${v}, expected positive integer`);
+    }
+    return n;
+}
+
 export class GGLocalDiscoveryClient extends GGDiscoveryClient {
 
     public override readonly isLocal = true;
@@ -77,12 +89,34 @@ export class GGLocalDiscoveryClient extends GGDiscoveryClient {
     }
 
     protected async ensureConnected(): Promise<void> {
-        if (!this.client.isConnected()) {
-            await this.client.connect();
+        if (this.client.isConnected()) return;
+        // Retry with backoff: when the router runs as its own process
+        // (e.g. launched via the `discovery-local` bin), a runtime can
+        // come up before the router has bound its port. Tolerate that
+        // instead of failing the runtime's startup outright.
+        const maxRetries = 20;
+        for (let attempt = 0; ; attempt++) {
+            try {
+                await this.client.connect();
+                return;
+            } catch (err: any) {
+                if (attempt >= maxRetries || !isConnectionError(err)) throw err;
+                GGLog.debug(this, "Waiting for discovery router...");
+                await new Promise(r => setTimeout(r, Math.min(500 * Math.pow(1.5, attempt), 5000)));
+            }
         }
     }
 }
 
+/** True for the transient socket errors seen while a router process is
+ *  still coming up — worth retrying, unlike a real protocol failure. */
+function isConnectionError(err: any): boolean {
+    const codes = ["ECONNREFUSED", "ETIMEDOUT", "ECONNRESET", "ENOENT"];
+    const has = (code?: string) => code !== undefined && codes.includes(code);
+    return has(err?.code) || has(err?.cause?.code)
+        || has(err?.originalError?.code) || has(err?.originalError?.cause?.code);
+}
+
 /**
  * What consumers need to discover and connect to a service
  */

package/src/local/GGLocalDiscoveryResilientClient.ts

@@ -1,15 +1,19 @@
 import {GGLog} from "@grest-ts/logger";
 import {IPCServer} from "@grest-ts/ipc";
 import {GGLocalDiscoveryServer} from "./GGLocalDiscoveryServer";
-import {GGLocalDiscoveryClient} from "./GGLocalDiscoveryClient";
+import {GGLocalDiscoveryClient, getLocalDiscoveryPort} from "./GGLocalDiscoveryClient";
+import {GGDiscoveryIPC, DiscoveryServerKind} from "./GGDiscoveryIPC";
 
 export class GGLocalDiscoveryResilientClient extends GGLocalDiscoveryClient {
 
     private discoveryServer?: GGLocalDiscoveryServer;
     private isLeader = false;
     private isShuttingDown = false;
+    /** Once any bin has held the port in this runtime's lifetime, never
+     *  bid for it again. In-memory only. */
+    private seenBinBasedMaster = false;
 
-    constructor(port = 9000) {
+    constructor(port = getLocalDiscoveryPort()) {
         super(port);
     }
 
@@ -32,12 +36,19 @@ export class GGLocalDiscoveryResilientClient extends GGLocalDiscoveryClient {
 
     private async becomeLeaderOrFollower(): Promise<void> {
         if (this.isShuttingDown) return;
+        if (this.seenBinBasedMaster) return this.connectToLeader();
 
-        const server = new IPCServer(this.port);
-        const router = new GGLocalDiscoveryServer(server);
+        const router = new GGLocalDiscoveryServer(new IPCServer(this.port));
         if (await router.start()) {
             this.discoveryServer = router;
             this.isLeader = true;
+            router.onYield = async () => {
+                GGLog.warn(this, "Yielding leadership to authoritative discovery (bin); will not bid for the port again in this runtime");
+                this.seenBinBasedMaster = true;
+                this.isLeader = false;
+                this.discoveryServer = undefined;
+                await this.connectToLeader();
+            };
             GGLog.info(this, "This instance is LEADER");
         } else {
             this.isLeader = false;
@@ -52,18 +63,32 @@ export class GGLocalDiscoveryResilientClient extends GGLocalDiscoveryClient {
         try {
             await this.client.connect();
 
+            if (!this.seenBinBasedMaster) {
+                const info = await this.client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.getServerInfo, undefined);
+                if (info.kind === DiscoveryServerKind.Bin) {
+                    GGLog.warn(this, "Connected to authoritative discovery (bin); will not bid for the port in this runtime");
+                    this.seenBinBasedMaster = true;
+                }
+            }
+
+            // Re-publish entries on every successful connect — covers
+            // initial register, follower-on-leader-death, and post-yield
+            // reconnect uniformly. Server-side dedup on (clientId, api)
+            // makes this idempotent, so the wrapped register()'s own
+            // super.register() call is a harmless no-op.
+            if (this.entries.length > 0) {
+                await this.client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, this.entries);
+            }
+
             this.client.onClose(async () => {
                 if (this.isShuttingDown) return;
                 GGLog.warn(this, "Leader died");
                 await this.becomeLeaderOrFollower();
-                if (this.isLeader && this.entries.length > 0) {
-                    await super.register();
-                }
             });
 
             GGLog.debug(this, "Connected to leader");
         } catch (err: any) {
-            GGLog.error(this, `Failed to connect to leader: ${err.message}`);
+            GGLog.error(this, `Discovery router not reachable on port ${this.port} — is @grest-ts/discovery-local running? Will retry. (${err.message || err.code || err})`);
             await this.delay(1000);
             await this.connectToLeader();
         }

package/src/local/GGLocalDiscoveryServer.ts

@@ -5,7 +5,7 @@ import {FirstStrategy} from "./routing/strategies/FirstStrategy";
 import {LastStrategy} from "./routing/strategies/LastStrategy";
 import {RandomStrategy} from "./routing/strategies/RandomStrategy";
 import {RoundRobinStrategy} from "./routing/strategies/RoundRobinStrategy";
-import {GGDiscoveryIPC} from "./GGDiscoveryIPC";
+import {GGDiscoveryIPC, DiscoveryServerKind} from "./GGDiscoveryIPC";
 import {GGServiceDiscoveryEntry} from "./GGLocalDiscoveryClient";
 
 export const ROUTING_STRATEGIES = {
@@ -32,8 +32,9 @@ export class GGLocalDiscoveryServer {
     private readonly server: IPCServer;
     private readonly routes: Map<string, RegisteredEntry[]> = new Map();
     private readonly routingStrategies: Map<string, RoutingStrategy> = new Map();
-
-    constructor(server: IPCServer) {
+    public onYield?: () => Promise<void>;
+  
+    constructor(server: IPCServer, public readonly kind: DiscoveryServerKind = DiscoveryServerKind.Embedded) {
         this.server = server;
 
         // Socket handlers for framework communication
@@ -57,6 +58,17 @@ export class GGLocalDiscoveryServer {
             return {success: false, error: "Service '" + apiName + "' is not registered! Did you forget to start it?"};
         });
 
+        this.server.onFrameworkMessage(GGDiscoveryIPC.discoveryServer.getServerInfo, async () => ({kind: this.kind}));
+
+        // Defer release so the ack flushes before we close the socket.
+        // onYield owners (e.g. resilient client) own teardown themselves.
+        this.server.onFrameworkMessage(GGDiscoveryIPC.discoveryServer.requestYield, async () => {
+            setTimeout(async () => {
+                await this.teardown();
+                await this.onYield?.();
+            }, 10);
+        });
+
         this.server.setRouteProxyResolver((path) => {
             return this.matchRoute(path)?.baseUrl || undefined;
         })
@@ -106,8 +118,16 @@ export class GGLocalDiscoveryServer {
 
     public addRoute(route: GGServiceDiscoveryEntry): void {
         const existing = this.routes.get(route.api) ?? [];
-        existing.push(route);
-        this.routes.set(route.api, existing);
+        const stored = route as RegisteredEntry;
+        // Dedup on (clientId, api) so a client re-registering its own
+        // route — e.g. on reconnect after a leader restart — replaces
+        // its previous entry instead of appending a duplicate. Routes
+        // from different clients (legitimate replicas) coexist.
+        const filtered = stored.clientId !== undefined
+            ? existing.filter(r => r.clientId !== stored.clientId)
+            : existing;
+        filtered.push(stored);
+        this.routes.set(route.api, filtered);
         GGLog.info(this, `Added route: ${route.pathPrefix} (${route.api}) -> ${route.baseUrl}`);
     }
 

package/src/local/yield.test.ts

@@ -0,0 +1,136 @@
+import {IPCServer, IPCClient} from "@grest-ts/ipc";
+import {GGLocatorScope} from "@grest-ts/locator";
+import {GGLocalDiscoveryServer} from "./GGLocalDiscoveryServer";
+import {GGLocalDiscoveryResilientClient} from "./GGLocalDiscoveryResilientClient";
+import {GGDiscoveryIPC, DiscoveryServerKind} from "./GGDiscoveryIPC";
+
+async function startServer(kind: DiscoveryServerKind): Promise<{server: GGLocalDiscoveryServer, port: number}> {
+    const ipc = new IPCServer(0);
+    const server = new GGLocalDiscoveryServer(ipc, kind);
+    if (!(await server.start())) throw new Error("bind failed");
+    return {server, port: ipc.getPort()};
+}
+
+async function isPortFree(port: number): Promise<boolean> {
+    const probe = new IPCServer(port);
+    const ok = await probe.start();
+    if (ok) await probe.teardown();
+    return ok;
+}
+
+describe("yield protocol", () => {
+
+    beforeEach(() => {
+        new GGLocatorScope("YieldProtocolTest").enter();
+    });
+
+    test("getServerInfo returns kind; requestYield without onYield tears down", async () => {
+        const {server, port} = await startServer(DiscoveryServerKind.Bin);
+        const client = new IPCClient(port);
+        await client.connect();
+        const info = await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.getServerInfo, undefined);
+        expect(info.kind).toBe(DiscoveryServerKind.Bin);
+        await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.requestYield, undefined);
+        client.disconnect();
+        await new Promise(r => setTimeout(r, 100));
+        expect(await isPortFree(port)).toBe(true);
+        await server.teardown().catch((): undefined => undefined);
+    });
+
+    test("requestYield invokes onYield after teardown", async () => {
+        const {server, port} = await startServer(DiscoveryServerKind.Embedded);
+        let firedAfterTeardown = false;
+        server.onYield = async () => { firedAfterTeardown = await isPortFree(port); };
+        const client = new IPCClient(port);
+        await client.connect();
+        await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.requestYield, undefined);
+        client.disconnect();
+        await new Promise(r => setTimeout(r, 100));
+        expect(firedAfterTeardown).toBe(true);
+        expect(await isPortFree(port)).toBe(true);
+    });
+
+    test("resilient client that connected to a bin never re-bids after the bin dies", async () => {
+        const {server: bin, port} = await startServer(DiscoveryServerKind.Bin);
+
+        const subscope = new GGLocatorScope("ResilientClientTest");
+        subscope.setLifecycleOwner(() => undefined);
+        subscope.enter();
+        const resilient = new GGLocalDiscoveryResilientClient(port);
+        await resilient.register();
+
+        await bin.teardown();
+        await new Promise(r => setTimeout(r, 200));
+
+        expect(await isPortFree(port)).toBe(true);
+        await resilient.unregister();
+    });
+
+    test("addRoute dedups (same clientId, same api) on re-register", async () => {
+        const {server, port} = await startServer(DiscoveryServerKind.Embedded);
+        try {
+            const client = new IPCClient(port);
+            await client.connect();
+            const entry = {api: "myapi", baseUrl: "http://localhost:1111", pathPrefix: "/api/my/"};
+            await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, [entry]);
+            await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, [entry]);
+            await client.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, [entry]);
+            // Internal: same clientId + api should appear exactly once.
+            expect(server.getRoute("myapi")?.baseUrl).toBe("http://localhost:1111");
+            const internalRoutes = (server as unknown as {routes: Map<string, unknown[]>}).routes.get("myapi");
+            expect(internalRoutes?.length).toBe(1);
+            client.disconnect();
+        } finally {
+            await server.teardown();
+        }
+    });
+
+    test("addRoute keeps entries from different clients (legitimate replicas)", async () => {
+        const {server, port} = await startServer(DiscoveryServerKind.Embedded);
+        try {
+            const a = new IPCClient(port);
+            const b = new IPCClient(port);
+            await a.connect("replica-a");
+            await b.connect("replica-b");
+            await a.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, [{api: "rep", baseUrl: "http://localhost:2001", pathPrefix: "/api/rep/"}]);
+            await b.sendFrameworkRequest(GGDiscoveryIPC.discoveryServer.register, [{api: "rep", baseUrl: "http://localhost:2002", pathPrefix: "/api/rep/"}]);
+            const internalRoutes = (server as unknown as {routes: Map<string, Array<{baseUrl: string}>>}).routes.get("rep");
+            expect(internalRoutes?.length).toBe(2);
+            expect(new Set(internalRoutes!.map(r => r.baseUrl))).toEqual(new Set(["http://localhost:2001", "http://localhost:2002"]));
+            a.disconnect();
+            b.disconnect();
+        } finally {
+            await server.teardown();
+        }
+    });
+
+    test("resilient follower re-publishes its entries on a new leader after the old one dies", async () => {
+        const {server: leader1, port} = await startServer(DiscoveryServerKind.Bin);
+
+        const subscope = new GGLocatorScope("ResilientReregisterTest");
+        subscope.setLifecycleOwner(() => undefined);
+        subscope.enter();
+        const resilient = new GGLocalDiscoveryResilientClient(port);
+        resilient.registerRoutes([{runtime: "test", api: "myapi", protocol: "http", port: 1234, pathPrefix: "/api/my/"}]);
+        await resilient.register();
+        // Sanity: route is on leader1.
+        expect(leader1.getRoute("myapi")?.baseUrl).toBe("http://localhost:1234");
+
+        await leader1.teardown();
+        // New leader on the SAME port (also a "bin" so the resilient stays loyal).
+        const ipc2 = new IPCServer(port);
+        const leader2 = new GGLocalDiscoveryServer(ipc2, DiscoveryServerKind.Bin);
+        if (!(await leader2.start())) throw new Error("leader2 bind failed");
+        try {
+            // Wait long enough for resilient's onClose (1s retry) to trigger
+            // a fresh connectToLeader → re-register.
+            for (let i = 0; i < 20 && !leader2.getRoute("myapi"); i++) {
+                await new Promise(r => setTimeout(r, 200));
+            }
+            expect(leader2.getRoute("myapi")?.baseUrl).toBe("http://localhost:1234");
+        } finally {
+            await resilient.unregister();
+            await leader2.teardown();
+        }
+    });
+});