onelobby 0.4.1 → 0.6.0

package/dist/direct/browser-host.js

@@ -0,0 +1,93 @@
+import { encodeRoomCode } from "../joincode.js";
+import { NostrHostBridge } from "../nostr/host.js";
+import { HOST_NOSTR_FIRST_RELAY_MS } from "../nostr/limits.js";
+import { DEFAULT_NOSTR_RELAYS, DEFAULT_NOSTR_STUN } from "../nostr/relays.js";
+import { OneLobbyError } from "../signaling.js";
+import { SignalingHub, directHubOptions } from "./hub.js";
+import { LocalHubSocket } from "./hub-local.js";
+/**
+ * The startup line of a browser host, same family as `formatHostLog`:
+ * `OneLobby: browser host (no port); code 7HQ-4K2-... (Nostr); nostr 4/5 relays`.
+ */
+export function formatBrowserHostLog(code, relays) {
+    return `OneLobby: browser host (no port); code ${code} (Nostr); nostr ${relays} relays`;
+}
+export async function hostNostr(kit, opts = {}) {
+    const bp = kit.blueprint;
+    if (bp && !bp.hosting.nostr) {
+        throw new OneLobbyError("nostr_disabled", "this game has Nostr signaling turned off (hosting.nostr is false), and a browser host has no other way to be reached");
+    }
+    const defined = Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== undefined));
+    const o = bp
+        ? {
+            maxPlayers: bp.lobby.maxPlayers,
+            lateJoin: bp.lobby.lateJoin,
+            meta: { ...bp.lobby.meta },
+            ...(bp.session.rateLimit ? { rateLimit: { ...bp.session.rateLimit } } : {}),
+            ...defined,
+            nostr: { ...defined.nostr, relays: defined.nostr?.relays ?? [...bp.hosting.nostrRelays] },
+        }
+        : defined;
+    const maxPlayers = o.maxPlayers ?? 4;
+    const relays = o.nostr?.relays && o.nostr.relays.length > 0 ? o.nostr.relays : [...DEFAULT_NOSTR_RELAYS];
+    const stunUrls = o.nostr?.stun ?? [...DEFAULT_NOSTR_STUN];
+    const hub = new SignalingHub({ ...directHubOptions(maxPlayers, o.password), stunUrls });
+    const ticker = setInterval(() => hub.tick(), 1000);
+    ticker.unref?.();
+    const code = encodeRoomCode();
+    const env = kit.nostrHostEnv();
+    let bridge;
+    const teardown = () => {
+        clearInterval(ticker);
+        bridge?.close();
+    };
+    try {
+        try {
+            bridge = await NostrHostBridge.start(hub, { code, relays, connect: env.connect, clock: env.clock, wall: env.wall, maxPlayers });
+        }
+        catch (e) {
+            throw new OneLobbyError("direct_unreachable", `cannot reach any Nostr relay (${e instanceof Error ? e.message : String(e)}); a browser host has no other way to be reached`);
+        }
+        if (!(await bridge.settle(o.relayTimeoutMs ?? HOST_NOSTR_FIRST_RELAY_MS))) {
+            throw new OneLobbyError("direct_unreachable", `no Nostr relay reachable (tried ${bridge.relaysTotal}); a browser host has no IP fallback, check the connection or pass other relays`);
+        }
+        const name = o.name ?? `${kit.options.displayName || "Player"}'s game`;
+        const h = { name, maxPlayers, lateJoin: o.lateJoin ?? true, meta: o.meta, rateLimit: o.rateLimit };
+        // joiners have no address to dial: links use the hub's STUN list, no port pin
+        const lobby = await kit.hostDirectWith(h, { socketFactory: () => new LocalHubSocket(hub), wrapLinks: (inner) => inner });
+        lobby.linkAddressSink = (peerId, ip) => hub.reportLinkAddress(peerId, ip);
+        lobby.on("sessionEnded", teardown);
+        lobby.joinCode = code;
+        lobby.joinCodeKind = "nostr";
+        lobby.directCode = "";
+        lobby.directCodeKind = "none";
+        lobby.portMapping = "off";
+        lobby.directHostLog = formatBrowserHostLog(code, `${bridge.relaysConnected}/${bridge.relaysTotal}`);
+        watchVisibility(lobby, o);
+        if (o.log !== false)
+            (o.log ?? console.log)(lobby.directHostLog);
+        return lobby;
+    }
+    catch (e) {
+        teardown();
+        throw e;
+    }
+}
+/** Sets `lobby.hostHidden` and warns when the tab goes hidden: browsers throttle timers there (about 1/s, ~1/min after 5 min). */
+function watchVisibility(lobby, o) {
+    const doc = o.document !== undefined ? o.document : globalThis.document;
+    if (!doc || typeof doc.addEventListener !== "function")
+        return;
+    const warn = o.warn === false ? null : (o.warn ?? ((s) => console.warn(s)));
+    const check = () => {
+        const hidden = doc.visibilityState === "hidden";
+        const changed = hidden !== lobby.hostHidden;
+        lobby.setHostHidden(hidden);
+        if (changed && hidden)
+            warn?.("OneLobby: the host tab is hidden; the browser slows its timers, so players may lag or drop. Keep this tab visible while hosting.");
+    };
+    doc.addEventListener("visibilitychange", check);
+    lobby.on("sessionEnded", () => doc.removeEventListener("visibilitychange", check));
+    check();
+}
+//# sourceMappingURL=browser-host.js.map

package/dist/direct/browser-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-host.js","sourceRoot":"","sources":["../../src/direct/browser-host.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `kit.hostNostr()`: host a direct lobby from a browser tab (or any runtime with WebSocket + WebRTC), with no Node process\n * and no listening port. The signaling hub runs inside the page, the host's own socket is wired to it in memory, and\n * joiners reach it through public Nostr relays with a normal dc1 version 1 code (spec/nostr-signaling.md). There is no IP\n * fallback: with no relay reachable it rejects with `direct_unreachable`. Nothing here imports a Node module.\n */\nimport type { HostOptions, OneLobby } from \"../onelobby.js\";\nimport type { Lobby, RateLimit } from \"../lobby.js\";\nimport { encodeRoomCode } from \"../joincode.js\";\nimport { NostrHostBridge } from \"../nostr/host.js\";\nimport { HOST_NOSTR_FIRST_RELAY_MS } from \"../nostr/limits.js\";\nimport { DEFAULT_NOSTR_RELAYS, DEFAULT_NOSTR_STUN } from \"../nostr/relays.js\";\nimport { OneLobbyError } from \"../signaling.js\";\nimport { SignalingHub, directHubOptions } from \"./hub.js\";\nimport { LocalHubSocket } from \"./hub-local.js\";\n\n/** The slice of `document` the visibility watcher uses (a test seam; default `globalThis.document`). */\nexport interface VisibilityDoc {\n  visibilityState?: string;\n  addEventListener(type: \"visibilitychange\", listener: () => void): void;\n  removeEventListener(type: \"visibilitychange\", listener: () => void): void;\n}\n\nexport interface BrowserHostOptions {\n  /** Optional; joiners must send the same one or get `bad_password`. */\n  password?: string;\n  maxPlayers?: number;\n  /** Lobby name; default \"<displayName>'s game\". */\n  name?: string;\n  lateJoin?: boolean;\n  meta?: Record<string, string>;\n  /** Per-joiner cap on incoming raw messages, e.g. `{ messages: 60, perMs: 1000 }`; the excess is dropped. */\n  rateLimit?: RateLimit;\n  /** Relays (default: the blueprint's `hosting.nostrRelays`, else the library list) and STUN servers (default Google's and Cloudflare's). */\n  nostr?: { relays?: string[]; stun?: string[] };\n  /** Receives the startup line (`lobby.directHostLog`). Default `console.log`; `false` prints nothing. */\n  log?: ((line: string) => void) | false;\n  /** Receives the warning printed when the host tab goes hidden. Default `console.warn`; `false` prints nothing. */\n  warn?: ((line: string) => void) | false;\n  /** How long to wait for a first relay before rejecting with `direct_unreachable` (default 10000). */\n  relayTimeoutMs?: number;\n  /** Test seam: the document whose `visibilityState` is watched. Default `globalThis.document`. */\n  document?: VisibilityDoc | null;\n}\n\n/** A browser host lobby: the normal Lobby (`hostHidden` / `hostHiddenChanged` tell when the tab is throttled). */\nexport type BrowserHostLobby = Lobby;\n\n/**\n * The startup line of a browser host, same family as `formatHostLog`:\n * `OneLobby: browser host (no port); code 7HQ-4K2-... (Nostr); nostr 4/5 relays`.\n */\nexport function formatBrowserHostLog(code: string, relays: string): string {\n  return `OneLobby: browser host (no port); code ${code} (Nostr); nostr ${relays} relays`;\n}\n\nexport async function hostNostr(kit: OneLobby, opts: BrowserHostOptions = {}): Promise<BrowserHostLobby> {\n  const bp = kit.blueprint;\n  if (bp && !bp.hosting.nostr) {\n    throw new OneLobbyError(\"nostr_disabled\", \"this game has Nostr signaling turned off (hosting.nostr is false), and a browser host has no other way to be reached\");\n  }\n  const defined = Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== undefined)) as BrowserHostOptions;\n  const o: BrowserHostOptions = bp\n    ? {\n        maxPlayers: bp.lobby.maxPlayers,\n        lateJoin: bp.lobby.lateJoin,\n        meta: { ...bp.lobby.meta },\n        ...(bp.session.rateLimit ? { rateLimit: { ...bp.session.rateLimit } } : {}),\n        ...defined,\n        nostr: { ...defined.nostr, relays: defined.nostr?.relays ?? [...bp.hosting.nostrRelays] },\n      }\n    : defined;\n  const maxPlayers = o.maxPlayers ?? 4;\n  const relays = o.nostr?.relays && o.nostr.relays.length > 0 ? o.nostr.relays : [...DEFAULT_NOSTR_RELAYS];\n  const stunUrls = o.nostr?.stun ?? [...DEFAULT_NOSTR_STUN];\n\n  const hub = new SignalingHub({ ...directHubOptions(maxPlayers, o.password), stunUrls });\n  const ticker = setInterval(() => hub.tick(), 1000);\n  (ticker as { unref?: () => void }).unref?.();\n  const code = encodeRoomCode();\n  const env = kit.nostrHostEnv();\n  let bridge: NostrHostBridge | undefined;\n  const teardown = () => {\n    clearInterval(ticker);\n    bridge?.close();\n  };\n  try {\n    try {\n      bridge = await NostrHostBridge.start(hub, { code, relays, connect: env.connect, clock: env.clock, wall: env.wall, maxPlayers });\n    } catch (e) {\n      throw new OneLobbyError(\"direct_unreachable\", `cannot reach any Nostr relay (${e instanceof Error ? e.message : String(e)}); a browser host has no other way to be reached`);\n    }\n    if (!(await bridge.settle(o.relayTimeoutMs ?? HOST_NOSTR_FIRST_RELAY_MS))) {\n      throw new OneLobbyError(\"direct_unreachable\", `no Nostr relay reachable (tried ${bridge.relaysTotal}); a browser host has no IP fallback, check the connection or pass other relays`);\n    }\n\n    const name = o.name ?? `${kit.options.displayName || \"Player\"}'s game`;\n    const h: HostOptions = { name, maxPlayers, lateJoin: o.lateJoin ?? true, meta: o.meta, rateLimit: o.rateLimit };\n    // joiners have no address to dial: links use the hub's STUN list, no port pin\n    const lobby = await kit.hostDirectWith(h, { socketFactory: () => new LocalHubSocket(hub), wrapLinks: (inner) => inner });\n    lobby.linkAddressSink = (peerId, ip) => hub.reportLinkAddress(peerId, ip);\n    lobby.on(\"sessionEnded\", teardown);\n\n    lobby.joinCode = code;\n    lobby.joinCodeKind = \"nostr\";\n    lobby.directCode = \"\";\n    lobby.directCodeKind = \"none\";\n    lobby.portMapping = \"off\";\n    lobby.directHostLog = formatBrowserHostLog(code, `${bridge.relaysConnected}/${bridge.relaysTotal}`);\n    watchVisibility(lobby, o);\n    if (o.log !== false) (o.log ?? console.log)(lobby.directHostLog);\n    return lobby;\n  } catch (e) {\n    teardown();\n    throw e;\n  }\n}\n\n/** Sets `lobby.hostHidden` and warns when the tab goes hidden: browsers throttle timers there (about 1/s, ~1/min after 5 min). */\nfunction watchVisibility(lobby: Lobby, o: BrowserHostOptions): void {\n  const doc: VisibilityDoc | null | undefined = o.document !== undefined ? o.document : (globalThis as { document?: VisibilityDoc }).document;\n  if (!doc || typeof doc.addEventListener !== \"function\") return;\n  const warn = o.warn === false ? null : (o.warn ?? ((s: string) => console.warn(s)));\n  const check = () => {\n    const hidden = doc.visibilityState === \"hidden\";\n    const changed = hidden !== lobby.hostHidden;\n    lobby.setHostHidden(hidden);\n    if (changed && hidden) warn?.(\"OneLobby: the host tab is hidden; the browser slows its timers, so players may lag or drop. Keep this tab visible while hosting.\");\n  };\n  doc.addEventListener(\"visibilitychange\", check);\n  lobby.on(\"sessionEnded\", () => doc.removeEventListener(\"visibilitychange\", check));\n  check();\n}\n"]}

package/dist/direct/hub-host.d.ts

@@ -1,6 +1,11 @@
 import type { SocketLike } from "../transport.js";
+import type { IpCodeKind, JoinCodeKind } from "../join-code-kind.js";
 import { SignalingHub, type HubDeps, type HubOptions } from "./hub.js";
+import { LocalHubSocket } from "./hub-local.js";
 import { PortMapper, type PortMapperOptions, type PortMapResult } from "./portmap.js";
+import type { NostrHostBridge } from "../nostr/host.js";
+/** A joiner socket with more than this much unsent data is closed (1008 "backpressure"); spec/signaling.md. */
+export declare const MAX_PENDING_WRITE_BYTES: number;
 /**
  * Whether a WebSocket handshake carrying `origin` is accepted. A web page can open a WebSocket to any address it can
  * reach, so a browser's Origin must be one we expect: in `allowed` ("*" = all), the same host:port as the request's
@@ -8,6 +13,8 @@ import { PortMapper, type PortMapperOptions, type PortMapResult } from "./portma
  * no Origin header is a native client and never gets here.
  */
 export declare function originAllowed(origin: string, host: string | undefined, allowed: readonly string[]): boolean;
+/** Whether `ip` (as the socket reports it) is 127.0.0.0/8, ::1 or an IPv4-mapped loopback address. */
+export declare function isLoopback(ip: string): boolean;
 export declare class PortInUseError extends Error {
     readonly code = "port_in_use";
     /** Windows reserved the port (EACCES: an excluded port range, often from Hyper-V, WSL or Docker); not another program. */
@@ -18,9 +25,10 @@ export declare class PortInUseError extends Error {
 export declare function portFailureHint(anyBusy: boolean, anyReserved: boolean): string;
 /**
  * Runs a {@link SignalingHub} inside a Node process and listens for joiners' signaling WebSockets on TCP `port`: the
- * Node twin of C#'s `DirectHubHost` (docs/direct-ip.md s.2, s.5 step 3). A plain `net` server with a minimal HTTP/1.1
+ * Node twin of C#'s `DirectHubHost` (docs/design/direct-ip.md s.2, s.5 step 3). A plain `net` server with a minimal HTTP/1.1
  * upgrade and RFC 6455 framing (text, close, ping/pong, fragments; client frames must be masked), so the package keeps
- * zero runtime dependencies. Any path upgrades; `GET /healthz` answers `ok`. The host's own client talks to the hub in
+ * zero runtime dependencies. Any path upgrades; `GET /healthz` answers `ok` and `GET /metrics` the hub's Prometheus text
+ * (loopback callers only), as onelobby-server does, ahead of the `http` callback. The host's own client talks to the hub in
  * memory through {@link connectLocal}. `hub.tick()` runs once a second on an unref'd timer.
  */
 /** One plain-HTTP answer from the host's port, e.g. a browser join page. */
@@ -30,6 +38,23 @@ export interface HttpReply {
     /** Content-Type, e.g. "text/html; charset=utf-8". */
     type: string;
     body: string | Uint8Array;
+    /**
+     * Extra response headers, e.g. `{ "Cache-Control": "max-age=3600" }` for a static asset (default `no-store`). The
+     * hub owns Content-Type, Content-Length and Connection; a name or value with a line break answers 500.
+     */
+    headers?: Record<string, string>;
+}
+/** `GET /joininfo` on a direct host: what a page served from the host shows as its share link (`directJoinInfo()`). */
+export interface DirectJoinInfo {
+    /** What to hand out: the Nostr code (version 1) by default, else the IP code. */
+    joinCode: string;
+    joinCodeKind: JoinCodeKind;
+    /** The IP code (address and port); equals `joinCode` when Nostr is off. */
+    directCode: string;
+    directCodeKind: IpCodeKind;
+    /** With `http`: `http://<the code's address>:<port>/`; else null. */
+    joinUrl: string | null;
+    port: number;
 }
 /** Serves plain `GET` requests on the direct port (path without the query); null answers 404. */
 export type HttpHandler = (path: string) => HttpReply | null;
@@ -45,9 +70,13 @@ export declare class DirectHubHost {
      * clients), the host's own page (Origin equal to the request's Host) and localhost pages are always allowed.
      */
     allowedOrigins: string[];
+    /** Served as JSON at `GET /joininfo` (404 while null); `hostDirect` keeps it current as the join code changes. */
+    joinInfo: DirectJoinInfo | null;
     /** The bound TCP port (the requested one, or the one the OS picked for 0). */
     readonly port: number;
     portMapper: PortMapper | null;
+    /** Nostr signaling for joiners that cannot reach the port (spec/nostr-signaling.md); set by `hostDirect`. */
+    nostr: NostrHostBridge | null;
     private readonly server;
     private readonly sockets;
     private readonly ticker;
@@ -68,33 +97,15 @@ export declare class DirectHubHost {
      * kit as `advanced.socketFactory: () => host.connectLocal()`.
      */
     connectLocal(): SocketLike;
-    /** Asks the home router to forward TCP and UDP `port` here (UPnP, then NAT-PMP; docs/direct-ip.md s.2a). */
+    /** Asks the home router to forward TCP and UDP `port` here (UPnP, then NAT-PMP; docs/design/direct-ip.md s.2a). */
     openPort(options?: PortMapperOptions): Promise<PortMapResult>;
     /** Stops listening, closes every joiner socket and removes the router mapping. Every call gets the same promise. */
     close(): Promise<void>;
     private closing?;
     private closeOnce;
     private accept;
-    /** RFC 6455 s.4.2: answers 101 with Sec-WebSocket-Accept, or 200 for /healthz, or 400/426. */
+    /** RFC 6455 s.4.2: answers 101 with Sec-WebSocket-Accept, or 200 for /healthz and /metrics (loopback only), or 400/426. */
     private handshake;
     private run;
 }
-/**
- * The direct-IP host's own signaling socket (C#'s `HubSignalingSocket`): sends go straight into the hub; the hub's
- * replies are delivered on a microtask, so callbacks never run inside the hub.
- */
-export declare class LocalHubSocket implements SocketLike {
-    private readonly hub;
-    /** Address the hub sees for the host itself (rate limits and kicks are per address). */
-    static readonly ADDRESS = "local";
-    readyState: number;
-    onopen: SocketLike["onopen"];
-    onmessage: SocketLike["onmessage"];
-    onclose: SocketLike["onclose"];
-    onerror: SocketLike["onerror"];
-    private session;
-    constructor(hub: SignalingHub);
-    send(data: string): void;
-    close(): void;
-    private finish;
-}
+export { LocalHubSocket };

package/dist/direct/hub-host.js

@@ -3,10 +3,14 @@ import { createHash } from "node:crypto";
 import { createSocket } from "node:dgram";
 import { createServer } from "node:net";
 import { SignalingHub, directHubOptions } from "./hub.js";
+import { LocalHubSocket } from "./hub-local.js";
 import { PortMapper } from "./portmap.js";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 const MAX_HEADER_BYTES = 8192;
 const HANDSHAKE_TIMEOUT_MS = 5000;
+/** A joiner socket with more than this much unsent data is closed (1008 "backpressure"); spec/signaling.md. */
+export const MAX_PENDING_WRITE_BYTES = 1024 * 1024;
+const BACKPRESSURE_GRACE_MS = 3000;
 const STATUS_TEXT = { 200: "OK", 301: "Moved Permanently", 302: "Found", 404: "Not Found", 500: "Internal Server Error" };
 /**
  * Whether a WebSocket handshake carrying `origin` is accepted. A web page can open a WebSocket to any address it can
@@ -30,6 +34,11 @@ export function originAllowed(origin, host, allowed) {
         return true;
     return host !== undefined && u.host.toLowerCase() === host.trim().toLowerCase();
 }
+/** Whether `ip` (as the socket reports it) is 127.0.0.0/8, ::1 or an IPv4-mapped loopback address. */
+export function isLoopback(ip) {
+    const a = ip.replace(/^::ffff:/i, "");
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(a) || a === "::1";
+}
 /**
  * Rejects (EADDRINUSE) when another program holds IPv4 TCP or UDP `port`. Windows lets the dual-stack listener bind
  * over a program on 0.0.0.0 (every IPv4 joiner would then reach that program), and the peer links need UDP `port`
@@ -68,6 +77,20 @@ export function portFailureHint(anyBusy, anyReserved) {
         return "Windows has reserved it (an excluded port range, often from Hyper-V, WSL or Docker); pick another port";
     return "each one is busy or reserved by Windows (an excluded port range); is another copy of the game hosting?";
 }
+const HUB_OWNED_HEADERS = new Set(["content-type", "content-length", "connection", "transfer-encoding"]);
+function replyHeaders(extra) {
+    const h = new Map([
+        ["cache-control", ["Cache-Control", "no-store"]],
+        ["x-content-type-options", ["X-Content-Type-Options", "nosniff"]],
+    ]);
+    for (const [k, v] of Object.entries(extra ?? {})) {
+        if (/[\r\n:]/.test(k) || /[\r\n]/.test(String(v)) || !k)
+            throw new Error("bad header");
+        if (!HUB_OWNED_HEADERS.has(k.toLowerCase()))
+            h.set(k.toLowerCase(), [k, String(v)]);
+    }
+    return [...h.values()].map(([k, v]) => `${k}: ${v}\r\n`).join("");
+}
 export class DirectHubHost {
     hub;
     /**
@@ -80,9 +103,13 @@ export class DirectHubHost {
      * clients), the host's own page (Origin equal to the request's Host) and localhost pages are always allowed.
      */
     allowedOrigins = [];
+    /** Served as JSON at `GET /joininfo` (404 while null); `hostDirect` keeps it current as the join code changes. */
+    joinInfo = null;
     /** The bound TCP port (the requested one, or the one the OS picked for 0). */
     port;
     portMapper = null;
+    /** Nostr signaling for joiners that cannot reach the port (spec/nostr-signaling.md); set by `hostDirect`. */
+    nostr = null;
     server;
     sockets = new Set();
     ticker;
@@ -146,7 +173,7 @@ export class DirectHubHost {
     connectLocal() {
         return new LocalHubSocket(this.hub);
     }
-    /** Asks the home router to forward TCP and UDP `port` here (UPnP, then NAT-PMP; docs/direct-ip.md s.2a). */
+    /** Asks the home router to forward TCP and UDP `port` here (UPnP, then NAT-PMP; docs/design/direct-ip.md s.2a). */
     openPort(options) {
         if (this.portMapper)
             throw new Error("the port is already being opened");
@@ -161,6 +188,7 @@ export class DirectHubHost {
     async closeOnce() {
         this.closed = true;
         clearInterval(this.ticker);
+        this.nostr?.close();
         const unmap = this.portMapper?.close();
         for (const s of this.sockets)
             s.end(closeFrame(1001, "host left"));
@@ -192,14 +220,14 @@ export class DirectHubHost {
             clearTimeout(timer);
             sock.off("data", onData);
             const rest = head.subarray(end + 4);
-            if (!this.handshake(sock, head.subarray(0, end).toString("latin1")))
+            if (!this.handshake(sock, ip, head.subarray(0, end).toString("latin1")))
                 return;
             this.run(sock, ip, rest);
         };
         sock.on("data", onData);
     }
-    /** RFC 6455 s.4.2: answers 101 with Sec-WebSocket-Accept, or 200 for /healthz, or 400/426. */
-    handshake(sock, head) {
+    /** RFC 6455 s.4.2: answers 101 with Sec-WebSocket-Accept, or 200 for /healthz and /metrics (loopback only), or 400/426. */
+    handshake(sock, ip, head) {
         const [requestLine, ...lines] = head.split("\r\n");
         const headers = new Map();
         for (const l of lines) {
@@ -208,26 +236,45 @@ export class DirectHubHost {
                 headers.set(l.slice(0, i).trim().toLowerCase(), l.slice(i + 1).trim());
         }
         const [method, path] = requestLine.split(" ");
-        const reply = (status, body) => sock.end(`HTTP/1.1 ${status}\r\nContent-Type: text/plain\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`);
+        const reply = (status, body, type = "text/plain") => sock.end(`HTTP/1.1 ${status}\r\nContent-Type: ${type}\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`);
+        // The same two endpoints as onelobby-server; /metrics stays local because this port faces the internet.
         if (method === "GET" && path === "/healthz") {
-            reply("200 OK", "ok");
+            reply("200 OK", "ok\n");
+            return false;
+        }
+        if (method === "GET" && path === "/metrics") {
+            if (isLoopback(ip))
+                reply("200 OK", this.hub.metrics.render(), "text/plain; version=0.0.4");
+            else
+                reply("403 Forbidden", "metrics are local only (OneLobby direct host)");
             return false;
         }
         const key = headers.get("sec-websocket-key");
         const upgrade = /websocket/i.test(headers.get("upgrade") ?? "");
+        // The share link for a page the host serves: a player who opened it at a LAN address still shares the public one.
+        if (method === "GET" && !upgrade && path?.split("?")[0] === "/joininfo") {
+            if (this.joinInfo)
+                reply("200 OK", JSON.stringify(this.joinInfo), "application/json");
+            else
+                reply("404 Not Found", "no join code yet");
+            return false;
+        }
         if (method === "GET" && !upgrade && this.http && path) {
             let page = null;
+            let extra = "";
             try {
                 page = this.http(path.split("?")[0]);
+                extra = replyHeaders(page?.headers);
             }
             catch {
                 page = { status: 500, type: "text/plain", body: "error" };
+                extra = replyHeaders(undefined);
             }
             const p = page ?? { status: 404, type: "text/plain", body: "not found" };
             const body = typeof p.body === "string" ? Buffer.from(p.body, "utf8") : Buffer.from(p.body);
             const status = p.status ?? 200;
             sock.write(`HTTP/1.1 ${status} ${STATUS_TEXT[status] ?? "OK"}\r\nContent-Type: ${p.type}\r\n` +
-                `Content-Length: ${body.length}\r\nCache-Control: no-store\r\nX-Content-Type-Options: nosniff\r\nConnection: close\r\n\r\n`);
+                `Content-Length: ${body.length}\r\n${extra}Connection: close\r\n\r\n`);
             sock.end(body);
             return false;
         }
@@ -246,19 +293,32 @@ export class DirectHubHost {
     }
     run(sock, ip, initial) {
         let open = true;
-        const sendText = (text) => {
-            if (open && !sock.destroyed)
-                sock.write(frame(0x1, Buffer.from(text, "utf8")));
-        };
+        let session = null;
         const shut = (code, reason) => {
             if (!open)
                 return;
             open = false;
-            if (!sock.destroyed)
+            if (sock.destroyed)
+                return;
+            // a reader that stopped reading never drains its buffer: give the close frame a moment, then cut it off
+            if (code === 1008 && reason === "backpressure") {
+                sock.write(closeFrame(code, reason));
+                setTimeout(() => sock.destroy(), BACKPRESSURE_GRACE_MS).unref?.();
+                if (session)
+                    this.hub.disconnect(session);
+            }
+            else
                 sock.end(closeFrame(code, reason));
         };
-        let session = null;
-        session = this.hub.connect(ip, sendText, () => shut(1000, "closed by the hub"));
+        const sendText = (text) => {
+            if (!open || sock.destroyed)
+                return;
+            sock.write(frame(0x1, Buffer.from(text, "utf8")));
+            // a slow or malicious reader must not grow this process's memory without bound
+            if (sock.writableLength > MAX_PENDING_WRITE_BYTES)
+                shut(1008, "backpressure");
+        };
+        session = this.hub.connect(ip, sendText, (code, reason) => shut(code ?? 1000, reason ?? "closed by the hub"));
         if (!session)
             return;
         const s = session;
@@ -414,49 +474,5 @@ class FrameReader {
         this.sink.fail(code, why);
     }
 }
-// ------------------------------------------------------------------------------------------------ in-memory socket
-/**
- * The direct-IP host's own signaling socket (C#'s `HubSignalingSocket`): sends go straight into the hub; the hub's
- * replies are delivered on a microtask, so callbacks never run inside the hub.
- */
-export class LocalHubSocket {
-    hub;
-    /** Address the hub sees for the host itself (rate limits and kicks are per address). */
-    static ADDRESS = "local";
-    readyState = 0;
-    onopen = null;
-    onmessage = null;
-    onclose = null;
-    onerror = null;
-    session;
-    constructor(hub) {
-        this.hub = hub;
-        this.session = hub.connect(LocalHubSocket.ADDRESS, (text) => queueMicrotask(() => this.readyState === 1 && this.onmessage?.({ data: text })), () => this.finish());
-        queueMicrotask(() => {
-            if (!this.session) {
-                this.finish();
-                return;
-            }
-            this.readyState = 1;
-            this.onopen?.();
-        });
-    }
-    send(data) {
-        if (this.readyState === 1 && this.session)
-            this.hub.receive(this.session, data);
-    }
-    close() {
-        const s = this.session;
-        const wasOpen = this.readyState === 1;
-        this.finish();
-        if (wasOpen && s)
-            this.hub.disconnect(s);
-    }
-    finish() {
-        if (this.readyState === 3)
-            return;
-        this.readyState = 3;
-        queueMicrotask(() => this.onclose?.());
-    }
-}
+export { LocalHubSocket };
 //# sourceMappingURL=hub-host.js.map