🤖 fix: bracket IPv6 host URLs in lockfile

Change-Id: I9f29384286bd75aa25000758c887f608df99d607
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

src/node/orpc/server.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { createOrpcServer } from "./server";
+import type { ORPCContext } from "./context";
+
+function getErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) {
+    return null;
+  }
+
+  if (!("code" in error)) {
+    return null;
+  }
+
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" ? code : null;
+}
+
+describe("createOrpcServer", () => {
+  test("brackets IPv6 hosts in returned URLs", async () => {
+    // Minimal context stub - router won't be exercised by this test.
+    const stubContext: Partial<ORPCContext> = {};
+
+    let server: Awaited<ReturnType<typeof createOrpcServer>> | null = null;
+
+    try {
+      server = await createOrpcServer({
+        host: "::1",
+        port: 0,
+        context: stubContext as ORPCContext,
+        authToken: "test-token",
+      });
+    } catch (error) {
+      const code = getErrorCode(error);
+
+      // Some CI environments may not have IPv6 enabled.
+      if (code === "EAFNOSUPPORT" || code === "EADDRNOTAVAIL") {
+        return;
+      }
+
+      throw error;
+    }
+
+    try {
+      expect(server.baseUrl).toMatch(/^http:\/\/\[::1\]:\d+$/);
+      expect(server.wsUrl).toMatch(/^ws:\/\/\[::1\]:\d+\/orpc\/ws$/);
+      expect(server.specUrl).toMatch(/^http:\/\/\[::1\]:\d+\/api\/spec\.json$/);
+      expect(server.docsUrl).toMatch(/^http:\/\/\[::1\]:\d+\/api\/docs$/);
+    } finally {
+      await server.close();
+    }
+  });
+});

src/node/orpc/server.ts

@@ -66,6 +66,23 @@ export interface OrpcServer {
 
 // --- Server Factory ---
 
+function formatHostForUrl(host: string): string {
+  const trimmed = host.trim();
+
+  // IPv6 URLs must be bracketed: http://[::1]:1234
+  if (trimmed.includes(":")) {
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      return trimmed;
+    }
+
+    // If the host contains a zone index (e.g. fe80::1%en0), percent must be encoded.
+    const escaped = trimmed.replaceAll("%", "%25");
+    return `[${escaped}]`;
+  }
+
+  return trimmed;
+}
+
 /**
  * Create an oRPC server with HTTP and WebSocket endpoints.
  *
@@ -235,16 +252,17 @@ export async function createOrpcServer({
 
   // Wildcard addresses (0.0.0.0, ::) are not routable - convert to loopback for lockfile
   const connectableHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+  const connectableHostForUrl = formatHostForUrl(connectableHost);
 
   return {
     httpServer,
     wsServer,
     app,
     port: actualPort,
-    baseUrl: `http://${connectableHost}:${actualPort}`,
-    wsUrl: `ws://${connectableHost}:${actualPort}/orpc/ws`,
-    specUrl: `http://${connectableHost}:${actualPort}/api/spec.json`,
-    docsUrl: `http://${connectableHost}:${actualPort}/api/docs`,
+    baseUrl: `http://${connectableHostForUrl}:${actualPort}`,
+    wsUrl: `ws://${connectableHostForUrl}:${actualPort}/orpc/ws`,
+    specUrl: `http://${connectableHostForUrl}:${actualPort}/api/spec.json`,
+    docsUrl: `http://${connectableHostForUrl}:${actualPort}/api/docs`,
     close: async () => {
       // Close WebSocket server first
       wsServer.close();