feat: redirect /<prefix> across symmetric webmux instances

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hugocasa

backend/src/__tests__/domain-policies.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "bun:test";
-import { allocateServicePorts } from "../domain/policies";
+import {
+  allocateServicePorts,
+  deriveInstancePrefix,
+  isValidInstancePrefix,
+  sanitizeInstancePrefix,
+} from "../domain/policies";
 
 describe("allocateServicePorts", () => {
   it("allocates the first free slot across existing worktree metadata", () => {
@@ -40,3 +45,53 @@ describe("allocateServicePorts", () => {
     });
   });
 });
+
+describe("sanitizeInstancePrefix", () => {
+  it("lowercases and replaces non-alphanumerics with hyphens", () => {
+    expect(sanitizeInstancePrefix("My Project")).toBe("my-project");
+    expect(sanitizeInstancePrefix("Some_Repo.v2")).toBe("some-repo-v2");
+  });
+
+  it("collapses runs of hyphens and trims edges", () => {
+    expect(sanitizeInstancePrefix("--__foo bar__--")).toBe("foo-bar");
+  });
+
+  it("returns an empty string when nothing usable remains", () => {
+    expect(sanitizeInstancePrefix("***")).toBe("");
+  });
+});
+
+describe("isValidInstancePrefix", () => {
+  it("accepts lowercase alphanumeric and hyphens", () => {
+    expect(isValidInstancePrefix("webmux")).toBe(true);
+    expect(isValidInstancePrefix("webmux-2")).toBe(true);
+    expect(isValidInstancePrefix("ab12-cd")).toBe(true);
+  });
+
+  it("rejects uppercase, leading hyphen, or invalid chars", () => {
+    expect(isValidInstancePrefix("Webmux")).toBe(false);
+    expect(isValidInstancePrefix("-bad")).toBe(false);
+    expect(isValidInstancePrefix("has space")).toBe(false);
+    expect(isValidInstancePrefix("")).toBe(false);
+  });
+});
+
+describe("deriveInstancePrefix", () => {
+  it("returns the basename when no collision", () => {
+    expect(deriveInstancePrefix("/home/me/projects/webmux", [])).toBe("webmux");
+    expect(deriveInstancePrefix("/srv/widgets/", [])).toBe("widgets");
+  });
+
+  it("falls back to a default when the basename has no alphanumerics", () => {
+    expect(deriveInstancePrefix("/repo/...", [])).toBe("webmux");
+  });
+
+  it("appends -2, -3, ... to avoid collisions", () => {
+    expect(deriveInstancePrefix("/a/webmux", ["webmux"])).toBe("webmux-2");
+    expect(deriveInstancePrefix("/a/webmux", ["webmux", "webmux-2"])).toBe("webmux-3");
+  });
+
+  it("sanitizes weird basenames", () => {
+    expect(deriveInstancePrefix("/projects/My Cool App!", [])).toBe("my-cool-app");
+  });
+});

backend/src/__tests__/instance-registry.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { createInstanceRegistry, type InstanceEntry } from "../adapters/instance-registry";
+
+describe("instance-registry", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  async function freshRegistry(): Promise<{ dir: string; registry: ReturnType<typeof createInstanceRegistry> }> {
+    const dir = await mkdtemp(join(tmpdir(), "webmux-instance-registry-"));
+    tempDirs.push(dir);
+    return { dir, registry: createInstanceRegistry(dir) };
+  }
+
+  function makeEntry(overrides: Partial<InstanceEntry> = {}): InstanceEntry {
+    return {
+      prefix: "demo",
+      port: 5111,
+      projectDir: "/repo/demo",
+      pid: process.pid,
+      startedAt: Date.now(),
+      ...overrides,
+    };
+  }
+
+  it("registers, lists, and deregisters an entry", async () => {
+    const { registry } = await freshRegistry();
+    const entry = makeEntry();
+
+    registry.register(entry);
+    expect(registry.listLive()).toEqual([entry]);
+
+    registry.deregister(entry.port);
+    expect(registry.listLive()).toEqual([]);
+  });
+
+  it("returns an empty list when the registry directory does not exist", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "webmux-instance-registry-"));
+    await rm(dir, { recursive: true, force: true });
+    const registry = createInstanceRegistry(dir);
+    expect(registry.listLive()).toEqual([]);
+  });
+
+  it("evicts entries whose PID is no longer alive", async () => {
+    const { dir, registry } = await freshRegistry();
+    const live = makeEntry({ port: 5111 });
+    const dead = makeEntry({ port: 5112, pid: 1 << 30 });
+
+    registry.register(live);
+    registry.register(dead);
+
+    const result = registry.listLive();
+    expect(result.map((e) => e.port)).toEqual([live.port]);
+
+    // The dead entry's file should be cleaned up on read.
+    const remaining = createInstanceRegistry(dir).listLive();
+    expect(remaining).toEqual([live]);
+  });
+
+  it("ignores malformed json files", async () => {
+    const { dir, registry } = await freshRegistry();
+    registry.register(makeEntry({ port: 5111 }));
+    writeFileSync(join(dir, "5112.json"), "not json");
+    writeFileSync(join(dir, "5113.json"), JSON.stringify({ prefix: 1 }));
+
+    expect(registry.listLive().map((e) => e.port)).toEqual([5111]);
+  });
+
+  it("deregister is a no-op when the file is missing", async () => {
+    const { registry } = await freshRegistry();
+    expect(() => registry.deregister(9999)).not.toThrow();
+  });
+
+  it("overwrites an existing entry when registering the same port twice", async () => {
+    const { registry } = await freshRegistry();
+    registry.register(makeEntry({ port: 5111, prefix: "alpha" }));
+    registry.register(makeEntry({ port: 5111, prefix: "beta" }));
+
+    const entries = registry.listLive();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.prefix).toBe("beta");
+  });
+});

backend/src/__tests__/peer-routing.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import { decidePeerRouting } from "../domain/peer-routing";
+import type { InstanceEntry } from "../adapters/instance-registry";
+
+function peer(overrides: Partial<InstanceEntry> = {}): InstanceEntry {
+  return {
+    prefix: "demo",
+    port: 5111,
+    projectDir: "/repo/demo",
+    pid: 123,
+    startedAt: 1,
+    ...overrides,
+  };
+}
+
+describe("decidePeerRouting", () => {
+  it("passes through when there is no recognizable prefix segment", () => {
+    expect(decidePeerRouting("/", [peer()], 9999).kind).toBe("passthrough");
+    expect(decidePeerRouting("", [peer()], 9999).kind).toBe("passthrough");
+    expect(decidePeerRouting("/Some-Caps", [peer()], 9999).kind).toBe("passthrough");
+  });
+
+  it("passes through reserved segments", () => {
+    expect(decidePeerRouting("/api/config", [peer({ prefix: "api" })], 9999).kind).toBe("passthrough");
+    expect(decidePeerRouting("/ws/anything", [peer({ prefix: "ws" })], 9999).kind).toBe("passthrough");
+    expect(decidePeerRouting("/assets/foo.js", [peer({ prefix: "assets" })], 9999).kind).toBe("passthrough");
+  });
+
+  it("passes through when the prefix is not in the registry", () => {
+    const peers = [peer({ prefix: "alpha", port: 5111 })];
+    expect(decidePeerRouting("/beta", peers, 5111).kind).toBe("passthrough");
+    expect(decidePeerRouting("/beta/whatever", peers, 5111).kind).toBe("passthrough");
+  });
+
+  it("redirects to the peer's port when the prefix matches a different instance", () => {
+    const peers = [peer({ prefix: "windmill", port: 5112 })];
+    expect(decidePeerRouting("/windmill", peers, 5111)).toEqual({
+      kind: "redirect",
+      port: 5112,
+      path: "/",
+    });
+    expect(decidePeerRouting("/windmill/foo/bar", peers, 5111)).toEqual({
+      kind: "redirect",
+      port: 5112,
+      path: "/foo/bar",
+    });
+  });
+
+  it("rewrites in place when the matching peer is this instance", () => {
+    const peers = [peer({ prefix: "webmux", port: 5111 })];
+    expect(decidePeerRouting("/webmux", peers, 5111)).toEqual({
+      kind: "rewrite",
+      path: "/",
+    });
+    expect(decidePeerRouting("/webmux/deep/link", peers, 5111)).toEqual({
+      kind: "rewrite",
+      path: "/deep/link",
+    });
+  });
+
+  it("preserves trailing path segments and ignores query (caller appends it)", () => {
+    const peers = [peer({ prefix: "wm", port: 5113 })];
+    expect(decidePeerRouting("/wm/x/y/z", peers, 5111)).toEqual({
+      kind: "redirect",
+      port: 5113,
+      path: "/x/y/z",
+    });
+  });
+});

backend/src/adapters/instance-registry.ts

@@ -0,0 +1,108 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "../lib/log";
+
+export interface InstanceEntry {
+  prefix: string;
+  port: number;
+  projectDir: string;
+  pid: number;
+  startedAt: number;
+}
+
+export interface InstanceRegistry {
+  register(entry: InstanceEntry): void;
+  deregister(port: number): void;
+  listLive(): InstanceEntry[];
+}
+
+function defaultRegistryDir(): string {
+  const home = Bun.env.HOME ?? "/root";
+  return join(home, ".webmux", "instances");
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isInstanceEntry(value: unknown): value is InstanceEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.prefix === "string"
+    && typeof v.port === "number"
+    && typeof v.projectDir === "string"
+    && typeof v.pid === "number"
+    && typeof v.startedAt === "number";
+}
+
+export function createInstanceRegistry(dir: string = defaultRegistryDir()): InstanceRegistry {
+  function ensureDir(): void {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  function entryPath(port: number): string {
+    return join(dir, `${port}.json`);
+  }
+
+  function readEntry(filename: string): InstanceEntry | null {
+    try {
+      const raw = readFileSync(join(dir, filename), "utf8");
+      const parsed: unknown = JSON.parse(raw);
+      return isInstanceEntry(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    register(entry: InstanceEntry): void {
+      ensureDir();
+      const finalPath = entryPath(entry.port);
+      const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.tmp`;
+      const text = `${JSON.stringify(entry, null, 2)}\n`;
+      writeFileSync(tmpPath, text);
+      renameSync(tmpPath, finalPath);
+    },
+
+    deregister(port: number): void {
+      try {
+        unlinkSync(entryPath(port));
+      } catch (err: unknown) {
+        const code = (err as { code?: string } | null)?.code;
+        if (code !== "ENOENT") {
+          log.debug(`[instance-registry] deregister(${port}) failed: ${String(err)}`);
+        }
+      }
+    },
+
+    listLive(): InstanceEntry[] {
+      let filenames: string[];
+      try {
+        filenames = readdirSync(dir).filter((name) => name.endsWith(".json"));
+      } catch {
+        return [];
+      }
+
+      const live: InstanceEntry[] = [];
+      for (const filename of filenames) {
+        const entry = readEntry(filename);
+        if (!entry) continue;
+        if (!isAlive(entry.pid)) {
+          try {
+            unlinkSync(join(dir, filename));
+          } catch {
+            // best effort — another process may have cleaned it already
+          }
+          continue;
+        }
+        live.push(entry);
+      }
+      return live;
+    },
+  };
+}

backend/src/domain/peer-routing.ts

@@ -0,0 +1,35 @@
+import type { InstanceEntry } from "../adapters/instance-registry";
+import { isValidInstancePrefix } from "./policies";
+
+export type PeerRouting =
+  | { kind: "passthrough" }
+  | { kind: "rewrite"; path: string }
+  | { kind: "redirect"; port: number; path: string };
+
+/** Pure decision: given a request pathname and the live peer list, decide
+ *  whether to redirect to a peer, rewrite the URL in place (when the prefix
+ *  matches this instance), or let the request pass through to the SPA handler. */
+export function decidePeerRouting(
+  pathname: string,
+  peers: InstanceEntry[],
+  selfPort: number,
+): PeerRouting {
+  const firstSegment = pathname.split("/")[1];
+  if (!firstSegment || !isValidInstancePrefix(firstSegment)) {
+    return { kind: "passthrough" };
+  }
+  // Defense-in-depth: paths handled by the route map above never reach this code,
+  // but if a peer ever picked a colliding prefix we'd refuse to shadow them.
+  if (firstSegment === "api" || firstSegment === "ws" || firstSegment === "assets") {
+    return { kind: "passthrough" };
+  }
+
+  const peer = peers.find((entry) => entry.prefix === firstSegment);
+  if (!peer) return { kind: "passthrough" };
+
+  const remaining = pathname.slice(firstSegment.length + 1) || "/";
+  if (peer.port === selfPort) {
+    return { kind: "rewrite", path: remaining };
+  }
+  return { kind: "redirect", port: peer.port, path: remaining };
+}