iroh-fetch
v0.6.4
Published
fetch() over iroh: reach an HTTP backend behind any NAT from browsers and Node.js
Maintainers
Readme
iroh-fetch
Call backends behind NAT as if they had a public URL. Use the standard fetch, EventSource and WebSocket, and the
traffic goes over iroh to an iroh-gateway next to your backend. It runs in browsers and
Node.js ≥ 22.
import { createIrohFetch } from "iroh-fetch";
const iroh = await createIrohFetch({
backends: {
"https://api.example.com": "<gateway endpoint id>",
"https://files.example.com": { endpointIds: ["<replica 1>", "<replica 2>"], strategy: "round-robin" },
},
});
iroh.install(); // route these origins through iroh
const users = await (await fetch("https://api.example.com/users")).json();
const events = new EventSource("https://api.example.com/events");
const socket = new WebSocket("wss://files.example.com/ws");- Full fetch semantics: redirects, cookies, streaming in both directions,
AbortSignal XMLHttpRequesttoo (axios's default browser adapter, jQuery, upload progress)- Optional service worker for
<img>,<video>, CSS and downloads of backend URLs; where there is none (LINE and other iOS in-app browsers),iroh.objectUrl(url)or<IrohImage>load images over iroh intoblob:URLs - Optional client HTTP cache (
cache: true): Cache-Control, ETag / Last-Modified revalidation, Vary,Request.cache - Optional fixed client identity (
persistIdentity,secretKey) - Standard
WebSocketandEventSource(reconnect,Last-Event-ID), plus custom headers - Many backends from one frontend, and HA replicas with failover or round-robin; a replica can name the relay it is on
(
{ endpointId, relayUrl }) so a standby on another relay connects without waiting for an address lookup - React:
import { IrohProvider, useIroh, useIrohFetch, IrohImage, useIrohObjectUrl } from "iroh-fetch/react" - CLI:
npx -p iroh-fetch iroh-proxy <endpoint id> --port 8080exposes a gateway on localhost - Node.js: a native addon (prebuilt for linux x64/arm64 glibc, linux x64 musl, macOS and Windows x64, installed as an
optional dependency) gives direct UDP connections via hole punching, with the relay as fallback; elsewhere the WASM
build is used. Force one with
engine: "native" | "wasm"orIROH_FETCH_BACKEND - Uses n0's public relays by default; for your own (faster, token-protected) relay pass
relayUrlandrelayToken, best as a function that gets the token from your backend at runtime, so it can rotate without a redeploy (guide)
Full documentation, the gateway and a live demo: https://github.com/irohkit/iroh-bridge
