@statewalker/httpeers-libp2p 0.1.3

package/dist/transport.d.ts

@@ -0,0 +1,314 @@
+import type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+export type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+import type { FetchHandler, PeerIdStr, Remote } from "@statewalker/httpeers-core";
+import { PeerCallError } from "@statewalker/httpeers-core";
+import { type CallOnLimitedConnection } from "./link.js";
+/**
+ * A namespaced protocol id, passed explicitly rather than left at
+ * `webrun-streams-libp2p`'s package default (`/webrun-streams/1.0.0`). The
+ * protocol id is the demux key libp2p uses to route an inbound stream to a
+ * handler on the node: sharing the generic default would collide with any
+ * other `webrun-streams` consumer sharing the same libp2p node.
+ */
+export declare const PROTOCOL = "/httpeers/1.0.0";
+/**
+ * Per-connection concurrent stream cap, applied to both directions — THE
+ * SERVER-SIDE CONTRACT (ledger note 18 §6, T-3/Task 18 step 3): libp2p's own
+ * default is 32 inbound / 64 outbound streams per protocol per connection;
+ * past the inbound number, a new stream is RESET, not queued, and the caller
+ * observes that reset as `PeerStreamResetError` (`kind: "stream-reset"`,
+ * `errors.ts` row 3b, `mapPeerCallError`'s `TooManyInboundProtocolStreamsError`
+ * branch) — never a raw libp2p exception, but still a rejected call with no
+ * retry or backoff of its own. 512 is the recorded precedent from the
+ * stream-limits task (6a) and its regression tests in
+ * `webrun-streams-libp2p`. Raising it moves this cliff outward; it does not
+ * remove it, which is why `DEFAULT_MAX_CONCURRENT_OUTBOUND` below exists —
+ * see that constant's doc comment for the client-side half of this contract.
+ *
+ * THE EXPOSURE WINDOW this cap forms together with `DEFAULT_DRAIN_TIMEOUT_MS`
+ * (the OTHER half of the same contract, Task 18 step 3): a peer that opens
+ * every one of its 512 allowed streams and then stops reading pins
+ * `DEFAULT_MAX_STREAMS * DEFAULT_DRAIN_TIMEOUT_MS` = 512 * 15s ≈ 2.1
+ * stream-hours of this node's buffer before the last one is dropped. See
+ * `DEFAULT_DRAIN_TIMEOUT_MS`'s own doc comment for why 15s (not
+ * `webrun-streams-libp2p`'s 5-minute default) was chosen once this cap was
+ * raised past libp2p's own default. Both numbers are stated here as ONE
+ * contract, not two independently-tunable knobs: changing either without
+ * re-deriving this product reopens a cliff of a different shape.
+ */
+export declare const DEFAULT_MAX_STREAMS = 512;
+/**
+ * How long a served stream waits for a backpressured peer to drain before
+ * being dropped. This is the ONLY bound on a peer that requests something
+ * and then stops reading without closing — the serving side has no
+ * `.return`/abort escape the way `connect`'s caller side does.
+ *
+ * It multiplies with `DEFAULT_MAX_STREAMS`: a peer that opens the full
+ * stream cap and never reads any of them pins `DEFAULT_MAX_STREAMS *
+ * drainTimeoutMs` stream-milliseconds of server-side buffer before every one
+ * of them is finally dropped. `webrun-streams-libp2p`'s own default (5
+ * minutes) times a 512-stream cap is ~42.7 stream-hours of exposure — too
+ * generous to leave in force once the cap itself has been raised well past
+ * libp2p's default. 15 seconds is chosen instead: long enough that a
+ * legitimate reader on a slow or lossy link still has room to drain a
+ * response chunk (multiple seconds of headroom even at very low bandwidth),
+ * short enough that the worst case — every one of 512 streams held open by a
+ * peer that never reads — caps out at 512 * 15s ≈ 2.1 stream-hours and clears
+ * within one operational window rather than requiring intervention.
+ */
+export declare const DEFAULT_DRAIN_TIMEOUT_MS = 15000;
+/**
+ * T-2's request timeout contract: how long `Peer.call()` / `Remote` wait —
+ * across queueing for a local concurrency slot (T-3/Task 18, see
+ * `DEFAULT_MAX_CONCURRENT_OUTBOUND` below), dialing, protocol negotiation,
+ * and the response itself — before giving up and rejecting with
+ * `PeerRequestTimeoutError`. This is a CONTRACT, not a tuning knob picked in
+ * isolation: no caller of this package may assume an unbounded wait for a
+ * response, ever, and this is the number that bounds it by default.
+ *
+ * T-3 DELIBERATELY DID NOT ADD A SEPARATE QUEUE TIMEOUT. When Task 18 added
+ * the outbound semaphore, the queue wait it introduces was placed INSIDE
+ * this same race rather than behind its own timer — see
+ * `DEFAULT_MAX_CONCURRENT_OUTBOUND`'s doc comment for the reasoning and the
+ * worst-case arithmetic that decision avoids.
+ *
+ * CHOSEN BELOW `DEFAULT_DRAIN_TIMEOUT_MS` (15s) AND `PROTOCOL_NEGOTIATION_TIMEOUT`
+ * (10s, libp2p's own default for how long protocol negotiation may take —
+ * `libp2p/dist/src/connection-manager/constants.defaults.js`), deliberately:
+ * 8s < 10s < 15s. That ordering means THIS timeout is always the first bound
+ * to trip. A caller therefore always observes a typed
+ * `PeerRequestTimeoutError` for any hang, never a raw libp2p `TimeoutError`
+ * leaking through from the negotiation phase, and the drain timeout exists
+ * purely as a transport-internal safety net most requests will never reach.
+ * The reverse ordering — a request timeout longer than the drain timeout —
+ * would mean the transport gives up on a stalled response before the
+ * caller's own timeout ever fires, which is a coherent choice only when
+ * deliberate; it is not the choice made here.
+ *
+ * 8 seconds: generous enough that an ordinary handler (token verification,
+ * a store lookup, one hop through a relay) never trips it under normal
+ * load, short enough that a caller waiting on a mesh peer notices "this
+ * peer is not answering" within under two heartbeat intervals (the
+ * heartbeat cadence this design assumes is 5s — see `DEFAULT_MINT_TTL_MS`'s
+ * doc comment in `peer.ts`) rather than being left hanging indefinitely.
+ * Override via `requestTimeoutMs` when a deployment knows better.
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 8000;
+/**
+ * T-3 (Task 18): the CLIENT-SIDE half of the concurrency contract
+ * `DEFAULT_MAX_STREAMS` states the server-side half of. Ledger note 18 §6 is
+ * explicit that raising `maxInboundStreams`/`maxOutboundStreams` to 512
+ * (Task 6a) MOVED the cliff rather than removing it: past the cap, libp2p
+ * RESETS the stream instead of queueing it, so a caller sees a rejected
+ * promise instead of latency, and nothing retries or backs off. This
+ * constant bounds `createRemote`'s own concurrency instead, so a well-behaved
+ * `Remote` never has to find that cliff at all: `createRemote` runs every
+ * outbound call through a private, in-process semaphore of this width before
+ * it ever calls `connect()` (which is what triggers libp2p's own
+ * `maxOutboundStreams` check, `TooManyOutboundProtocolStreamsError` --
+ * `errors.ts` row 3a). Excess calls QUEUE, in FIFO order, rather than racing
+ * each other into that cap.
+ *
+ * DEFAULTED TO `DEFAULT_MAX_STREAMS`, NOT SOME OTHER NUMBER, DELIBERATELY:
+ * this is a per-`Remote` (i.e. per-`Peer`) budget, not per-target-peer, so a
+ * `Peer` that only ever calls ONE target sees IDENTICAL admitted concurrency
+ * to before -- it will now queue instead of reset at the same threshold,
+ * never tighter -- while a `Peer` fanning calls out to MANY targets at once
+ * (a relay/hub forwarding on behalf of several callers) gets an additional,
+ * new global ceiling on its own total outbound fan-out that did not exist
+ * before this task. That second effect is intentional: `DEFAULT_MAX_STREAMS`
+ * is a PER-CONNECTION cap, so nothing previously bounded how many
+ * connections' worth of streams one `Remote` could have open at once: a
+ * `Peer` calling 20 different targets at 512 streams apiece could reach
+ * 10,240 concurrent outbound streams without ever touching any single
+ * connection's cap. That is exactly the kind of local resource exhaustion a
+ * DoS-adjacent control (see `DEFAULT_MAX_STREAMS`'s own doc comment) should
+ * not leave open just because it happens to fan out across many peers
+ * instead of one.
+ *
+ * THE AT-LIMIT CONTRACT (the decision ledger note 18 §6 left open --
+ * "queue, reject fast, or apply backpressure to the caller"): QUEUE, with a
+ * BOUNDED wait, then REJECT with a typed error from Task 17's taxonomy --
+ * never a silent reset (that would just be `DEFAULT_MAX_STREAMS`'s cliff
+ * again, moved one layer up), and never an unbounded queue (an unfailing
+ * queue under sustained overload is a slow-motion version of the same
+ * failure the timeout policy already rules out for every other kind of
+ * hang). Concretely: the bound is `DEFAULT_REQUEST_TIMEOUT_MS`, not a
+ * second, independent timer. `createRemote`'s `withRequestTimeout` race
+ * already covers "dial, negotiate, respond"; queueing for a `Semaphore`
+ * permit is placed INSIDE that same race (before `connect()` is even
+ * called), not layered outside it, specifically so a queued call that never
+ * gets a permit rejects with the SAME `PeerRequestTimeoutError` an
+ * unresponsive peer would produce, and within the SAME bound. The
+ * alternative -- a queue timeout on top of the existing request timeout --
+ * was considered and rejected: a caller that waits `requestTimeoutMs` in the
+ * queue and then gets a fresh `requestTimeoutMs` for the call itself sees up
+ * to 2 * `DEFAULT_REQUEST_TIMEOUT_MS` (16s) worst case, silently doubling a
+ * contract Task 17 wrote down as an 8-second promise. Sharing one budget
+ * keeps that promise: `Peer.call()` / `Remote` never wait longer than
+ * `requestTimeoutMs` for ANY reason, queueing included. Whichever reason
+ * wins the race, `mapPeerCallError`'s `if (err instanceof PeerCallError)
+ * return err` passes it through unchanged, so this never becomes a new
+ * taxonomy row -- `PeerRequestTimeoutError`'s trigger set simply grows to
+ * include "gave up waiting for a local concurrency slot," alongside its
+ * existing "gave up waiting for a response."
+ *
+ * A held permit is released in a `finally` (see `createRemote`) regardless
+ * of how the call ends -- success, a mapped `PeerCallError`, or the timeout
+ * race itself -- so one failing call can never permanently strand a slot.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_OUTBOUND = 512;
+/**
+ * Map whatever a failed dial/call/timeout actually threw onto this
+ * package's own taxonomy (`errors.ts`), so `Peer.call()` / `Remote` keep
+ * the contract "you get a `PeerCallError`, never a raw transport
+ * exception". Exported so a future transport adapter (or a test) can see
+ * exactly which condition maps to which class; see each class's own doc
+ * comment in `errors.ts` for the library source each case is grounded in.
+ *
+ * Matched by `.name` string, not `instanceof`, for three of the cases
+ * below (`NoValidAddressesError`, `DialError`/`DialDeniedError`,
+ * `TransferLimitError`): none is part of `@libp2p/interface`'s (or any
+ * dependency this package actually has) public export surface, so there is
+ * no class to import and compare against. `.name` is reliably set on the
+ * *instance*, not only the `static name`, in every libp2p error class this
+ * was checked against (`@libp2p/interface/dist/src/errors.js`,
+ * `libp2p/dist/src/errors.js`), which is what makes the string check sound
+ * rather than a guess.
+ */
+export declare function mapPeerCallError(err: unknown, peerId: PeerIdStr): PeerCallError;
+export interface CreateNodeInit {
+    /**
+     * Multiaddrs to listen on. Omit (or pass an empty array) for a dial-only
+     * node — one that can call out but accepts no inbound connections, which
+     * is a legitimate deployment shape (a client-only edge peer).
+     */
+    listen?: string[];
+    /**
+     * The node's own signing key. Omit to let libp2p generate one internally
+     * — fine for a peer that never needs to prove that key again once the
+     * node exists. `createPeer` generates and RETAINS this key itself (never
+     * here) when it needs to mint tokens later, because `createLibp2p` never
+     * hands a generated key back out; if the caller doesn't keep the
+     * reference before calling this function, it is gone for good.
+     */
+    privateKey?: Ed25519PrivateKey;
+    /**
+     * The libp2p transports this node speaks. **Required, and deliberately so.**
+     *
+     * The prototype hard-coded `tcp()` here, which made importing this module at
+     * all pull a Node-only transport into a browser bundle — in a package whose
+     * root export is supposed to run on both. There is no sensible default: a
+     * server wants `tcp()`, a page wants `webRTC()` and `webSockets()`, and
+     * guessing produces a node that cannot dial anything on the platform it
+     * actually ran on.
+     *
+     * `./node` and `./browser` supply the profiles; this stays platform-free.
+     */
+    transports: TransportFactory[];
+    /**
+     * Extra libp2p services — `circuitRelayServer()` for a hub, say. Merged
+     * over the `identify` this always registers.
+     */
+    services?: Record<string, unknown>;
+    /** A connection gater, e.g. membership. */
+    connectionGater?: unknown;
+}
+/**
+ * A libp2p transport factory — `tcp()`, `webSockets()`, `webRTC()`.
+ *
+ * Typed loosely on purpose: naming libp2p's `Transport` here would drag the
+ * whole interface package into the signature for no gain, and every caller
+ * passes the result of a factory it already imported.
+ */
+export type TransportFactory = (components: never) => unknown;
+/**
+ * Build a libp2p node with the transport stack this package's tests and
+ * `createPeer`'s default construction path both rely on: TCP, Noise
+ * (connection encryption — this is what makes `ConnectionContext.remotePeer`
+ * trustworthy), Yamux (stream muxing) and identify (address exchange, so a
+ * peer dialled once by full multiaddr can be dialled again by bare peerId —
+ * see `createRemote`). Not the only file allowed to build a node makes this
+ * package's swappable-transport claim false, so this stays inside
+ * `transport-duplex.ts`; `peer.ts` calls it, never `createLibp2p` directly.
+ */
+export declare function createNode(init: CreateNodeInit): Promise<Libp2p>;
+export interface ServeTransportInit {
+    node: Libp2p;
+    /** The composed peer router — everything downstream of identity. */
+    dispatch: FetchHandler;
+    /** Defaults to `PROTOCOL`. */
+    protocol?: string;
+    /** Defaults to `DEFAULT_DRAIN_TIMEOUT_MS`. See that constant's doc comment. */
+    drainTimeoutMs?: number;
+    /** Defaults to `DEFAULT_MAX_STREAMS`. See that constant's doc comment. */
+    maxInboundStreams?: number;
+    /** Defaults to `DEFAULT_MAX_STREAMS`. See that constant's doc comment. */
+    maxOutboundStreams?: number;
+    /** Accept streams on limited connections too -- serving only. See `Libp2pLinkInit.serveOnLimitedConnection`. */
+    runOnLimitedConnection?: boolean;
+}
+/**
+ * Register the httpeers protocol handler on `node`. Every inbound stream
+ * gets its own `Duplex`, closing over that stream's proven `remotePeer` —
+ * `registerPeer` runs before `dispatch` is ever called, so every handler
+ * downstream (the binding middleware first) sees the identity the transport
+ * itself proved, never anything the peer merely claims.
+ *
+ * Returns the teardown function `serveConnections` itself returns
+ * (`node.unhandle` for this protocol).
+ */
+export declare function serveTransport(init: ServeTransportInit): Promise<() => Promise<void>>;
+export interface CreateRemoteInit {
+    node: Libp2p;
+    /** Defaults to `PROTOCOL`. */
+    protocol?: string;
+    /** Defaults to `DEFAULT_DRAIN_TIMEOUT_MS`. See that constant's doc comment. */
+    drainTimeoutMs?: number;
+    /**
+     * Defaults to `DEFAULT_MAX_STREAMS`. Set here too, not only on the serving
+     * side: a peer both serves and dials (a relay forwards by dialing out), so
+     * the outbound cap needs the same headroom as the inbound one.
+     */
+    maxOutboundStreams?: number;
+    /**
+     * Defaults to `DEFAULT_REQUEST_TIMEOUT_MS`. See that constant's doc
+     * comment for the value, the contract it states, and its relationship to
+     * `drainTimeoutMs`.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * T-3 (Task 18): the width of this `Remote`'s outbound admission
+     * semaphore. Defaults to `DEFAULT_MAX_CONCURRENT_OUTBOUND`. See that
+     * constant's doc comment for the full contract -- what "width" bounds
+     * (this `Remote`'s total in-flight calls, across every target peer, not
+     * per-connection), and why queueing past it shares `requestTimeoutMs`
+     * rather than getting its own timer.
+     */
+    maxConcurrentOutbound?: number;
+    /** Open streams on limited connections to the peers this allows. See `CallOnLimitedConnection`. */
+    callOnLimitedConnection?: CallOnLimitedConnection;
+}
+/**
+ * Build the `Remote` seam `createPeerRouter` forwards through: dial `target`
+ * over libp2p and run the request over the resulting `Duplex`. Outbound is
+ * definitionally identity-free — nothing here registers a peer binding,
+ * because the *caller's* proven identity has no meaning on a connection *we*
+ * initiated.
+ *
+ * Every rejection from the returned function is a `PeerCallError` (see
+ * `errors.ts` and `mapPeerCallError` above) — never a raw libp2p exception,
+ * and never an unbounded wait: the whole queue-dial-negotiate-respond
+ * sequence (T-3/Task 18 added the queueing step) is raced against
+ * `requestTimeoutMs`.
+ *
+ * ONE `Semaphore` PER `Remote`, NOT PER CALL: `createRemote` is called once
+ * per `Peer` (see `peer.ts`'s `createPeer`), so the semaphore built here is
+ * that peer's single, shared outbound admission gate for as long as the
+ * `Peer` lives -- every call through this `Remote`, to every target,
+ * competes for the same `maxConcurrentOutbound` permits. See
+ * `DEFAULT_MAX_CONCURRENT_OUTBOUND`'s doc comment for why that scope (global
+ * to this `Remote`, not per-target-peer) was chosen.
+ */
+export declare function createRemote(init: CreateRemoteInit): Remote;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}