@statewalker/httpeers-libp2p 0.1.3

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * The transport — the one package in the extraction that knows what libp2p is.
+ *
+ * An explicit list, never `export *`: the barrel this code came from ended
+ * with `export * from "./transport-duplex.js"`, which is how a package that
+ * documented itself as isomorphic pulled libp2p, TCP, Noise and yamux into
+ * every consumer's bundle.
+ */
+
+/**
+ * The SECOND ALTITUDE: duplex streams over the mesh.
+ *
+ * A fetch-only contract cannot express a WebSocket — both sides talking with
+ * neither input closed. These run one `Duplex` per libp2p stream, addressed by
+ * `(peerId, path)`, with identity captured per stream by closure exactly as
+ * the fetch path does it.
+ */
+export {
+  createDuplexMounts,
+  DUPLEX_PROTOCOL,
+  type DuplexContext,
+  type DuplexHandler,
+  type DuplexMounts,
+  NO_MOUNT,
+  type OpenDuplexInit,
+  openDuplex,
+  type PeerDuplex,
+  type ServeDuplexInit,
+  serveDuplex,
+} from "./duplex.js";
+export {
+  decodeHopAnswer,
+  HOP_RESERVE_TIMEOUT_MS,
+  HOP_STATUS_NAMES,
+  HOP_STATUS_OK,
+  type HopAnswer,
+  RelayNotConnectedError,
+  type RelayReservationGrant,
+  RelayReservationRefusedError,
+  requestRelayReservation,
+} from "./hop-reserve.js";
+export {
+  HubReservationError,
+  type HubReservationRefusal,
+  hubRoute,
+  leaveRelay,
+  reachHub,
+  reachHubRelayed,
+  reserveOnHub,
+  type SuperviseHubReservationInit,
+  superviseHubReservation,
+} from "./hub-link.js";
+export {
+  HUB_MAX_RESERVATIONS,
+  type HubRelayComponents,
+  type HubRelayServiceInit,
+  hubRelayService,
+  type IsMember,
+  membershipGater,
+  releaseReservation,
+} from "./hub-relay.js";
+export {
+  type BytesStore,
+  decodeKey,
+  encodeKey,
+  type GenerateKeyInit,
+  generateKey,
+  type IdentityStore,
+  type IdentityStoreInit,
+  identityStore,
+  peerIdOf,
+  type SignerLike,
+  signerOf,
+} from "./identity.js";
+export type { CallOnLimitedConnection } from "./link.js";
+export { lastPeerIdOf } from "./multiaddr-parts.js";
+export {
+  type CircuitAddrs,
+  circuitAddrs,
+  DEFAULT_RENEWAL_INTERVAL_MS,
+  dialRelay,
+  MAX_RENEWAL_INTERVAL_MS,
+  MIN_RENEWAL_INTERVAL_MS,
+  RESERVATION_LOSS_GRACE_MS,
+  RESERVATION_POLL_ATTEMPTS,
+  RESERVATION_POLL_INTERVAL_MS,
+  type RelayLog,
+  type RelayReservationEvent,
+  type RelayReservationState,
+  type RelayReservationStatus,
+  type RelaySupervisor,
+  renewalDelayMs,
+  renewalIntervalMs,
+  reservationHealthy,
+  retryDelayMs,
+  type SuperviseRelayInit,
+  superviseRelay,
+  type WaitForCircuitReservationInit,
+  waitForCircuitReservation,
+} from "./reservation.js";
+export { type Peer, type ServePeerInit, servePeer } from "./serve-peer.js";
+export { globalTimers, type TimerHandle, type Timers } from "./timers.js";
+export {
+  type CreateNodeInit,
+  type CreateRemoteInit,
+  createNode,
+  createRemote,
+  DEFAULT_DRAIN_TIMEOUT_MS,
+  DEFAULT_MAX_STREAMS,
+  PROTOCOL,
+  type ServeTransportInit,
+  serveTransport,
+  type TransportFactory,
+} from "./transport.js";

package/src/link.ts

@@ -0,0 +1,143 @@
+/**
+ * libp2p, as a `PeerLink`.
+ *
+ * This is the whole of what makes the bridge libp2p-specific: how to open a
+ * duplex to a peer, and how to accept one. Everything the bridge does with
+ * those duplexes -- binding the proven peer, one stream per call, the permit,
+ * the timeout -- lives in `@statewalker/httpeers-bridge` and is shared with
+ * every other transport, including the MessagePort one the tests use.
+ *
+ * `serveConnections` is used rather than `node.handle` by hand because it
+ * already threads a `ConnectionContext`, and `context.remotePeer` is the
+ * answer the Noise handshake established. That value is what the bridge binds
+ * to every inbound request, and it is the reason a peer cannot lie about who
+ * it is no matter what headers it sets.
+ */
+
+import type { Libp2p } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { multiaddr } from "@multiformats/multiaddr";
+import type { PeerConnection, PeerLink } from "@statewalker/httpeers-bridge";
+import type { PeerIdStr, ProvenPeer } from "@statewalker/httpeers-core";
+import type { Duplex } from "@statewalker/webrun-streams";
+import {
+  type ConnectionContext,
+  connect,
+  serveConnections,
+} from "@statewalker/webrun-streams-libp2p";
+import { DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_STREAMS, PROTOCOL } from "./transport.js";
+
+export interface Libp2pLinkInit {
+  node: Libp2p;
+  /** Defaults to `PROTOCOL`. Two meshes on one node need two protocols. */
+  protocol?: string;
+  drainTimeoutMs?: number;
+  maxInboundStreams?: number;
+  maxOutboundStreams?: number;
+  /**
+   * ACCEPT streams on LIMITED connections (a relay circuit). Off by default:
+   * libp2p refuses, and that refusal is what keeps application traffic off a
+   * relay's small budget. A hub reached over the public relay sets it; a member
+   * never does, so its hub's relay limits still bound member-to-member traffic.
+   */
+  serveOnLimitedConnection?: boolean;
+  /** OPEN streams on limited connections, to the peers this allows. See `CallOnLimitedConnection`. */
+  callOnLimitedConnection?: CallOnLimitedConnection;
+}
+
+/**
+ * Which peers a call may reach over a LIMITED connection: `true` for all of
+ * them, or a predicate evaluated per target when the call opens its stream.
+ *
+ * A PREDICATE, NOT A BOOLEAN, because the one caller that needs it -- a member
+ * whose hub is reachable only through the relay -- must say "the hub" and
+ * nothing wider: `(peerId) => peerId === hubPeerId`. Separate from
+ * `serveOnLimitedConnection` for the same reason: a member calls its hub over
+ * the circuit without opening its own serving side to circuits.
+ */
+export type CallOnLimitedConnection = boolean | ((peerId: PeerIdStr) => boolean);
+
+/** Wrap a running libp2p node as the one seam the bridge needs. */
+export function libp2pLink(init: Libp2pLinkInit): PeerLink {
+  const {
+    node,
+    protocol = PROTOCOL,
+    drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+    maxInboundStreams = DEFAULT_MAX_STREAMS,
+    maxOutboundStreams = DEFAULT_MAX_STREAMS,
+    serveOnLimitedConnection,
+    callOnLimitedConnection = false,
+  } = init;
+
+  return {
+    async open(peerId: PeerIdStr): Promise<PeerConnection> {
+      // A BARE `/p2p/<id>` dial, deliberately: a peer dialled once by full
+      // multiaddr is dialable again by id alone, and composing an address here
+      // would duplicate the routing decisions `reservation.ts` already made.
+      const limited =
+        typeof callOnLimitedConnection === "function"
+          ? callOnLimitedConnection(peerId)
+          : callOnLimitedConnection;
+      const conn = await connect({
+        node: limited ? keptCircuitFirst(node, peerId) : node,
+        peer: multiaddr(`/p2p/${peerId}`),
+        protocol,
+        drainTimeoutMs,
+        maxOutboundStreams,
+        ...(limited ? { runOnLimitedConnection: true } : {}),
+      });
+      return { call: conn.call as Duplex, close: async () => await conn.close() };
+    },
+
+    async serve(handlerFor: (peer: ProvenPeer) => Duplex): Promise<() => Promise<void>> {
+      return serveConnections(
+        {
+          node,
+          protocol,
+          drainTimeoutMs,
+          maxInboundStreams,
+          maxOutboundStreams,
+          runOnLimitedConnection: serveOnLimitedConnection,
+        },
+        (context: ConnectionContext) => handlerFor(context.remotePeer.toString()) as never,
+      );
+    },
+  };
+}
+
+/**
+ * `node`, except that a stream to `peerId` opens on the LIMITED connection
+ * already held to it when that is the only kind there is. Used only for a
+ * target `callOnLimitedConnection` allows.
+ *
+ * WHY THE FLAG ALONE IS NOT ENOUGH. libp2p 3.3.8 does not reuse a limited
+ * connection for a dial: `findExistingConnection`
+ * (`connection-manager/utils.js`) returns only connections with
+ * `limits == null`, so `dialProtocol` to a peer reachable only by a kept relay
+ * circuit dials AGAIN, from the peer store -- a second circuit per call, through
+ * whichever of the relay's addresses identify taught it. The
+ * relay-fallback conformance test measured exactly that (two new connections
+ * for two requests) before this existed. The kept connection is the one the
+ * caller chose; the stream goes there.
+ *
+ * An UNLIMITED connection still wins when there is one (a WebRTC upgrade that
+ * did come up): that case is left to libp2p's own dial, which reuses it.
+ *
+ * A NARROW STAND-IN, not a wrapper: `connect` (`webrun-streams-libp2p`) reads
+ * nothing from the node but `dialProtocol`, and giving that package a way to
+ * take a `Connection` would be a change in another repository for one caller.
+ */
+function keptCircuitFirst(node: Libp2p, peerId: PeerIdStr): Libp2p {
+  const dialer: Pick<Libp2p, "dialProtocol"> = {
+    dialProtocol: async (peer, protocols, options) => {
+      const open = node.getConnections(peerIdFromString(peerId)).filter((c) => c.status === "open");
+      const kept = open.some((c) => c.limits == null)
+        ? undefined
+        : open.find((c) => c.limits != null);
+      return kept != null
+        ? kept.newStream(protocols, options)
+        : node.dialProtocol(peer, protocols, options);
+    },
+  };
+  return dialer as Libp2p;
+}

package/src/multiaddr-parts.ts

@@ -0,0 +1,29 @@
+/**
+ * Reading a peer id out of a multiaddr, without `Array.prototype.findLast`.
+ *
+ * The prototype used `findLast`, which needs `lib: ES2023`. Raising this
+ * package's lib would raise the RUNTIME floor for every consumer — the emitted
+ * code calls the method regardless of what the types allow — for one line of
+ * convenience. A reverse loop costs nothing and keeps the floor at ES2022,
+ * matching every other package here.
+ *
+ * To reverse: set `"lib": ["ES2023"]` in tsconfig.json and inline
+ * `.getComponents().findLast((c) => c.name === "p2p")?.value` at the two call
+ * sites (`reservation.ts`, `hub-link.ts`).
+ *
+ * LAST, not first, and that is the whole point: a circuit address is
+ * `/…/p2p/<relay>/p2p-circuit/p2p/<target>`, so the FIRST `p2p` component is
+ * the relay and the last is whoever the address finally names. Taking the
+ * first would hang up on the relay when asked to hang up on a peer.
+ */
+
+import type { Multiaddr } from "@multiformats/multiaddr";
+
+export function lastPeerIdOf(addr: Multiaddr): string | undefined {
+  const components = addr.getComponents();
+  for (let i = components.length - 1; i >= 0; i--) {
+    const component = components[i];
+    if (component?.name === "p2p") return component.value;
+  }
+  return undefined;
+}

package/src/node.ts

@@ -0,0 +1,63 @@
+/**
+ * The Node profile. Everything here is why the root export is not this.
+ *
+ * `tcp()` cannot run in a browser, and the prototype hard-coded it inside its
+ * node factory — so importing the transport module at all dragged a Node-only
+ * transport into a browser bundle, in a package whose whole claim is that one
+ * implementation runs on both. Separating the profiles is the fix, and the
+ * root's boundary test asserts `@libp2p/tcp` never appears there.
+ */
+
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tcp } from "@libp2p/tcp";
+import type { BytesStore } from "./identity.js";
+import type { TransportFactory } from "./transport.js";
+
+/**
+ * Transports for a server: TCP, and nothing a page could not also do.
+ *
+ * Listed as a function rather than a constant so a caller gets fresh factory
+ * instances — libp2p's are not reusable across nodes.
+ */
+export function nodeTransports(): TransportFactory[] {
+  return [tcp() as unknown as TransportFactory];
+}
+
+/**
+ * A `BytesStore` on the filesystem — where a server keeps its identity.
+ *
+ * WRITE-THEN-MOVE, not write-in-place. A key file truncated by a crash
+ * mid-write is not a corrupt file you notice, it is a mesh that silently
+ * re-founds itself on the next start: `identityStore.loadOrCreate` sees
+ * unreadable bytes, generates a new key, and every token the old identity
+ * issued stops verifying. A rename is atomic on POSIX, so the file is either
+ * the old key or the new one and never half of either.
+ *
+ * The prototype's snapshot store wrote in place; extraction prototype 04
+ * measured the consequence and this is the shape that survived it.
+ */
+export function fileBytesStore(dir: string): BytesStore {
+  return {
+    async get(key) {
+      try {
+        return new Uint8Array(await readFile(join(dir, key)));
+      } catch (error) {
+        if ((error as { code?: string }).code === "ENOENT") return undefined;
+        throw error;
+      }
+    },
+    async set(key, value) {
+      await mkdir(dir, { recursive: true });
+      const target = join(dir, key);
+      // Same directory, so the rename cannot cross a filesystem boundary —
+      // which is the one case where it would stop being atomic.
+      const staging = `${target}.${process.pid}.${Date.now()}.tmp`;
+      await writeFile(staging, value, { mode: 0o600 });
+      await rename(staging, target);
+    },
+    async delete(key) {
+      await rm(join(dir, key), { force: true });
+    },
+  };
+}