npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@statewalker/httpeers-bridge

v0.4.0

Published

Fetch over a duplex, both directions, with no transport in it. The seam libp2p, MessagePorts and anything else plug into.

Readme

@statewalker/httpeers-bridge

What it is

HTTP between peers over any duplex stream, in both directions, with no transport in it. A transport supplies a PeerLink — "open a duplex to this peer" and "accept duplexes, telling me who is on the other end". This package serves a FetchHandler over that link and calls other peers through it: a Request in, a Response out, one duplex per call.

Why it exists

Carrying HTTP over a duplex is done by @statewalker/webrun-http-streams. A mesh needs two more things that neither the streams layer nor the transport knows about: the transport-proven caller bound to every inbound request, and outbound calls that are bounded in number and time. Keeping both here, behind the two-method PeerLink, means libp2p, MessagePorts or a WebSocket all get the same behaviour, and the mesh logic can be tested without a relay, a hub or WebRTC.

How to use

pnpm add @statewalker/httpeers-bridge

No peer dependencies. Runs in Node, workers and browsers.

| Import | Gives | |---|---| | . | serveFetchOverLink, createRemoteOverLink, the PeerLink / PeerConnection types, DEFAULT_MAX_CONCURRENT_OUTBOUND (64), DEFAULT_REQUEST_TIMEOUT_MS (30 000) | | ./ports | pairedLinks — two links joined back to back over MessageChannel |

interface PeerLink {
  open(peerId: PeerIdStr): Promise<PeerConnection>;                        // a duplex to that peer
  serve(handlerFor: (peer: ProvenPeer) => Duplex): Promise<() => Promise<void>>; // accept duplexes
}

Examples

Two peers in one process, over MessageChannel:

import { createRemoteOverLink, serveFetchOverLink } from "@statewalker/httpeers-bridge";
import { pairedLinks } from "@statewalker/httpeers-bridge/ports";
import { lookupPeer } from "@statewalker/httpeers-core";

const [linkA, linkB] = pairedLinks(peerA, peerB);

const stop = await serveFetchOverLink({
  link: linkB,
  dispatch: async (req) => new Response(`hello, ${String(lookupPeer(req))}`),
});

const call = createRemoteOverLink({ link: linkA }); // options: maxConcurrentOutbound, requestTimeoutMs, mapError, mapBodyError
const res = await call(peerB, new Request("http://peer.local/hello"));
await res.text(); // "hello, <peerA>"
await stop();

A transport-specific error mapping:

import { PeerUnreachableError } from "@statewalker/httpeers-core";

const call = createRemoteOverLink({
  link,
  mapError: (error, target) =>
    String(error).includes("All multiaddr dials failed") ? new PeerUnreachableError(target) : undefined,
});

Internals

The caller's identity is overwritten on arrival

serveFetchOverLink calls registerPeer(req, peer) on every inbound request before dispatch, with the peer the link proved. registerPeer deletes x-httpeers-peer before setting it, so a request that arrives with a hand-set value is corrected here rather than believed downstream. That one line is why a peer cannot lie about who it is.

Outbound calls are bounded, because unbounded calls fail somewhere else

createRemoteOverLink holds a concurrency permit (64 by default) across all targets and a per-call timeout (30 s, dial included), and cleans up even when the timeout fires mid-dial. Without the permit, a page that fires a hundred calls opens a hundred streams at once, the far side's inbound limit refuses some of them, and the symptom is unrelated calls failing.

The permit counts calls waiting for their response head: it is taken before the dial and given back as soon as the head arrives. A call whose body is still streaming (an SSE stream, a tunnel, a large download, a body nobody reads) keeps its duplex but holds no permit. So the permit bounds how many streams are being opened at once, not how many are open; long-lived bodies still count against the transport's own per-connection stream limit.

The duplex is closed only on the error path

The call resolves as soon as the response head is parsed, while the body is still streaming over the same duplex. Closing it in a finally would yield a Response whose .text() never resolves — and a test suite that times out instead of failing, which is what duplex bugs look like.

Error mapping belongs to the transport

mapError is a caller option because error text is transport-specific: libp2p says "All multiaddr dials failed", a WebSocket says something else. A bridge that matched one transport's wording would mis-classify every other. Return undefined to let the original error through.

mapError sees failures before the response head only. An error that ends the response body goes to a second option, mapBodyError, which maps nothing by default. They are separate because a body can fail in two ways: the transport cut the call short (the peer died mid-body), or the serving peer's own code failed and sent its error across, rebuilt with the peer's name and message. Only the first is the transport's to classify: a mapper written for pre-head failures would read a far handler's TimeoutError as this side's request timeout. So mapBodyError should map only what the transport raises when a stream is cut (@statewalker/httpeers-libp2p maps PeerGoneError and nothing else) and return undefined for the rest. The caller's own abort is never mapped: the body fails with signal.reason.

A MessagePort proves nothing, so ./ports asserts identity

| Link | Where | Proves identity by | |---|---|---| | libp2p | @statewalker/httpeers-libp2p (servePeer) | the Noise handshake | | MessagePorts | ./ports (pairedLinks) | assertion at construction |

Whoever holds a port is whoever holds the port. pairedLinks(peerA, peerB) asserts the two identities when it is built, which is honest for a test harness and for an in-process or same-origin transport where the channel is the trust boundary. That is why it has its own entry point. Each open() creates a fresh channel, so "one duplex per call" holds exactly as it does over libp2p. Pass a channel factory to run over something other than the global MessageChannel. A link that cannot establish identity should pass ANONYMOUS, never a guess.

Dependencies

@statewalker/httpeers-core (headers, types), @statewalker/webrun-http-streams (HTTP over a duplex), @statewalker/webrun-streams (the Duplex type), @statewalker/webrun-rpc (a duplex over a MessagePort, for ./ports).

Tests run over MessagePorts — a request and a response in both directions, a forged x-httpeers-peer overwritten by what the link proved, and a 256 KiB body that streams: pnpm --filter @statewalker/httpeers-bridge test. The libp2p path is tested in @statewalker/httpeers-libp2p.

License

MIT