@statewalker/httpeers-libp2p 0.1.3

package/src/serve-peer.ts

@@ -0,0 +1,141 @@
+/**
+ * A mount table, served to the mesh.
+ *
+ * THE SEAM THREE ASSEMBLIES COLLAPSE INTO. The prototype builds a peer three
+ * times — the Node hub, the browser hub and the test hub — each wiring a node,
+ * a reservation, identity registration, a router and mounts in its own order,
+ * and the coverage audit found that the one symbol every assembly turns on was
+ * exported nowhere. This is it.
+ *
+ * WHAT IT DOES NOT DO, and the omission is the design. It does not verify a
+ * token, evaluate a policy, or know what a hub is. `access` is a middleware
+ * the caller supplies — `withAccess` from `@statewalker/httpeers-access`, or
+ * nothing at all for a peer that trusts its transport — because this package
+ * must not learn about Biscuit and `httpeers-access` must not learn about
+ * libp2p. They meet at a `FetchHandler`, which is the only contract either
+ * needs.
+ *
+ * IDENTITY IS REGISTERED BEFORE ANYTHING DOWNSTREAM RUNS. `serveTransport`
+ * gives every inbound stream its own `Duplex` closing over that stream's
+ * Noise-proven `remotePeer`, and calls `registerPeer` on the request before
+ * the handler sees it. That ordering is the whole basis of the binding check:
+ * a token's subject is compared against what the TRANSPORT proved, never
+ * against anything the caller said.
+ */
+
+import type { Libp2p } from "@libp2p/interface";
+import type { FetchHandler, Mounts, PeerIdStr } from "@statewalker/httpeers-core";
+import { createPeerRouter } from "@statewalker/httpeers-core";
+import type { CallOnLimitedConnection } from "./link.js";
+import { createRemote, PROTOCOL, serveTransport } from "./transport.js";
+
+export interface ServePeerInit {
+  node: Libp2p;
+  /**
+   * What this peer serves. A value, or a factory taking the peer's own id —
+   * a hub's endpoints need to know which mesh they are, and the alternative
+   * is for this package to learn what a hub is.
+   */
+  mounts: Mounts | ((self: PeerIdStr) => Mounts);
+  /**
+   * Everything between the transport and the mounts: identity binding and
+   * policy. Omitted, requests reach the mounts with only the transport's
+   * proof — which is a legitimate shape for a peer whose mounts are public,
+   * and a serious mistake for one whose are not.
+   *
+   * Passed through to the router, which applies it to LOCAL handling only.
+   * That distinction is load-bearing and easy to lose: wrapping the whole
+   * router instead would run policy over FORWARDED requests too, and an
+   * outbound call is not this peer's business to authorize.
+   */
+  access?: (next: FetchHandler) => FetchHandler;
+  /**
+   * May this request be forwarded to `target`? **Deny by default**, and the
+   * default is inherited rather than restated here.
+   *
+   * Relaying is a distinct capability, not a side effect of knowing how to
+   * route: without it any peer can make this one dial a third party and pump
+   * a stream on its behalf. The hole is invisible for a while because it
+   * fails CLOSED at the far end — the third party rejects the tokenless
+   * request, so every observable outcome looks right. The damage is the work
+   * done, not the answer given.
+   */
+  allowForward?: (request: Request, target: PeerIdStr) => Promise<boolean>;
+  protocol?: string;
+  /** Forwarded to the transport; see `transport.ts` for what each bounds. */
+  maxInboundStreams?: number;
+  maxOutboundStreams?: number;
+  drainTimeoutMs?: number;
+  /**
+   * Accept streams on limited connections (relay circuits) -- SERVING ONLY. A
+   * HUB sets it, so members that can reach it only through the public relay
+   * are served; a member never does, so the hub's relay limits still bound
+   * member-to-member traffic.
+   */
+  serveOnLimitedConnection?: boolean;
+  /**
+   * Open streams on limited connections to the peers this allows -- CALLING
+   * ONLY, and it covers every outbound path of this peer (`call`, and the
+   * router's forwarding behind `dispatch`). A member in relay mode passes
+   * `(peerId) => peerId === hubPeerId`. See `CallOnLimitedConnection`.
+   */
+  callOnLimitedConnection?: CallOnLimitedConnection;
+}
+
+export interface Peer {
+  peerId: PeerIdStr;
+  /** Every multiaddr this node is reachable on, right now. */
+  addrs(): string[];
+  /** Inbound, after identity binding and policy. Exposed so an edge can reuse it locally. */
+  dispatch: FetchHandler;
+  /** Call another peer. The request's URL path is what the far side routes on. */
+  call(peerId: PeerIdStr, request: Request): Promise<Response>;
+  stop(): Promise<void>;
+}
+
+export async function servePeer(init: ServePeerInit): Promise<Peer> {
+  const peerId = init.node.peerId.toString();
+  const protocol = init.protocol ?? PROTOCOL;
+
+  const mounts = typeof init.mounts === "function" ? init.mounts(peerId) : init.mounts;
+
+  const remote = createRemote({
+    node: init.node,
+    protocol,
+    maxOutboundStreams: init.maxOutboundStreams,
+    callOnLimitedConnection: init.callOnLimitedConnection,
+  });
+
+  const dispatch = createPeerRouter({
+    selfPeerId: peerId,
+    mounts,
+    remote,
+    access: init.access,
+    allowForward: init.allowForward,
+  });
+
+  const stopServing = await serveTransport({
+    node: init.node,
+    dispatch,
+    protocol,
+    maxInboundStreams: init.maxInboundStreams,
+    maxOutboundStreams: init.maxOutboundStreams,
+    drainTimeoutMs: init.drainTimeoutMs,
+    runOnLimitedConnection: init.serveOnLimitedConnection,
+  });
+
+  let stopped = false;
+  return {
+    peerId,
+    addrs: () => init.node.getMultiaddrs().map((a) => a.toString()),
+    dispatch,
+    call: async (target, request) => remote(target, request),
+    async stop() {
+      // Idempotent: an assembly that tears down twice — a page unloading while
+      // a test also cleans up — must not see the second call throw.
+      if (stopped) return;
+      stopped = true;
+      await stopServing();
+    },
+  };
+}

package/src/timers.ts

@@ -0,0 +1,47 @@
+/**
+ * The timer seam: the four calls anything long-lived in this package schedules
+ * with, behind an interface instead of the global functions.
+ *
+ * WHY, AND IT IS NOT TESTABILITY. A browser throttles `setTimeout` and
+ * `setInterval` in a background tab -- to once a minute, and on some engines
+ * far less -- and a hub running in a tab is a hub whose relay reservation is
+ * renewed on the browser's schedule rather than on the relay's. The fix is
+ * `worker-timers`, which schedules from a Web Worker and is not throttled; the
+ * fix is NOT to shorten the interval, which changes nothing about what the
+ * browser does to it. That wiring is deliberately not here yet (the Node hub is
+ * what runs today); this seam is what makes it a one-line change later:
+ *
+ *   import { clearInterval, clearTimeout, setInterval, setTimeout } from "worker-timers";
+ *   const timers: Timers = { setTimeout, clearTimeout, setInterval, clearInterval };
+ *
+ * Tests get the seam for free, and that is the cheaper of the two reasons.
+ *
+ * `TimerHandle` IS `unknown` ON PURPOSE. Node's timers return an object,
+ * browsers return a number, `worker-timers` returns a number of its own that
+ * only its own `clearTimeout` understands. An implementation must therefore
+ * only ever hand its OWN handles back to its OWN clear functions -- which is
+ * exactly what an opaque type states and a `number` alias would quietly
+ * permit callers to violate.
+ */
+
+/** A handle from one `Timers` implementation, meaningful only to that same one. */
+export type TimerHandle = unknown;
+
+export interface Timers {
+  setTimeout(handler: () => void, delayMs: number): TimerHandle;
+  clearTimeout(handle: TimerHandle): void;
+  setInterval(handler: () => void, delayMs: number): TimerHandle;
+  clearInterval(handle: TimerHandle): void;
+}
+
+/** The global timers, which is what everything uses unless it is told otherwise. */
+export const globalTimers: Timers = {
+  setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+  clearTimeout: (handle) => {
+    if (handle !== undefined) clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+  setInterval: (handler, delayMs) => setInterval(handler, delayMs),
+  clearInterval: (handle) => {
+    if (handle !== undefined) clearInterval(handle as ReturnType<typeof setInterval>);
+  },
+};