iroh

TypeScript/JavaScript bindings for iroh — peer-to-peer networking with QUIC.

Iroh is a library for establishing direct connections between devices. It uses QUIC for transport with built-in NAT traversal via relay servers and hole punching.

Installation

npm install @rayhanadev/iroh
# or
bun add @rayhanadev/iroh

Quick Start

import { Endpoint, initLogging } from "@rayhanadev/iroh";

// Optional: enable logging
initLogging("info");

// Create an endpoint
const endpoint = await Endpoint.create();
console.log("Node ID:", endpoint.nodeId());

// Wait for relay connection
await endpoint.online();
console.log("Online!");

// Clean up
await endpoint.close();

Examples

Echo Server

import { Endpoint } from "@rayhanadev/iroh";

const ALPN = "my-app/1";

async function server() {
  const endpoint = await Endpoint.createWithOptions({
    alpns: [ALPN],
  });

  console.log("Server node ID:", endpoint.nodeId());
  await endpoint.online();

  const conn = await endpoint.accept();
  if (!conn) return;

  console.log("Connection from:", conn.remoteNodeId());

  const { send, recv } = await conn.acceptBi();
  const data = await recv.readToEnd(1024);
  console.log("Received:", data.toString());

  await send.writeAll(data);
  await send.finish();

  await endpoint.close();
}

server();

Echo Client

import { Endpoint } from "@rayhanadev/iroh";

const ALPN = "my-app/1";
const SERVER_NODE_ID = "..."; // Get this from the server

async function client() {
  const endpoint = await Endpoint.create();

  const conn = await endpoint.connect(SERVER_NODE_ID, ALPN);
  console.log("Connected to:", conn.remoteNodeId());

  const { send, recv } = await conn.openBi();

  await send.writeAll(Buffer.from("Hello, iroh!"));
  await send.finish();

  const response = await recv.readToEnd(1024);
  console.log("Response:", response.toString());

  conn.close();
  await endpoint.close();
}

client();

API Reference

initLogging(level?: string)

Initialize logging. Levels: "trace", "debug", "info", "warn", "error".

Endpoint

The main entry point for creating and accepting connections.

| Method | Description | |--------|-------------| | static create(): Promise<Endpoint> | Create endpoint with defaults | | static createWithOptions(options): Promise<Endpoint> | Create with custom options | | nodeId(): string | Get the endpoint's public key (node ID) | | addr(): string | Get full address info (for debugging) | | online(): Promise<void> | Wait until connected to a relay | | connect(nodeId, alpn): Promise<Connection> | Connect to a remote endpoint | | accept(): Promise<Connection \| null> | Accept an incoming connection | | close(): Promise<void> | Close the endpoint | | isClosed(): boolean | Check if closed |

EndpointOptions

interface EndpointOptions {
  alpns?: string[];      // ALPN protocols to accept
  secretKey?: string;    // 32-byte hex string for deterministic identity
}

Connection

A QUIC connection to a remote peer.

| Method | Description | |--------|-------------| | remoteNodeId(): string | Get remote peer's node ID | | alpn(): Buffer | Get the ALPN protocol used | | openBi(): Promise<BiStream> | Open a bidirectional stream | | openUni(): Promise<SendStream> | Open a send-only stream | | acceptBi(): Promise<BiStream> | Accept a bidirectional stream | | acceptUni(): Promise<RecvStream> | Accept a receive-only stream | | close(errorCode?, reason?) | Close the connection | | closed(): Promise<string> | Wait for connection to close | | rtt(): number | Get round-trip time in ms | | sendDatagram(data: Buffer) | Send unreliable datagram | | readDatagram(): Promise<Buffer> | Receive unreliable datagram |

SendStream

A stream for sending data.

| Method | Description | |--------|-------------| | write(data: Buffer): Promise<number> | Write data, returns bytes written | | writeAll(data: Buffer): Promise<void> | Write all data | | finish(): Promise<void> | Signal end of stream | | reset(errorCode: number): Promise<void> | Abort the stream | | id(): Promise<string> | Get stream ID |

RecvStream

A stream for receiving data.

| Method | Description | |--------|-------------| | read(maxLength: number): Promise<Buffer \| null> | Read up to maxLength bytes | | readExact(length: number): Promise<Buffer> | Read exactly length bytes | | readToEnd(maxLength: number): Promise<Buffer> | Read all remaining data | | stop(errorCode: number): Promise<void> | Stop reading | | id(): Promise<string> | Get stream ID |

How It Works

1. Identity: Each endpoint has a unique node ID (Ed25519 public key)
2. Discovery: Endpoints connect to relay servers to be discoverable
3. Connection: When connecting, iroh tries direct UDP hole punching first, falling back to relay if needed
4. Streams: QUIC multiplexes multiple streams over a single connection

Building from Source

Requirements:

• Rust (latest stable)
• Node.js 18+ or Bun
• napi-rs CLI: npm install -g @napi-rs/cli

# Install dependencies
bun install

# Build native module
bun run build

# Build debug version
bun run build:debug

Platform Support

Pre-built binaries are available for:

• macOS (x64, arm64)
• Linux (x64)
• Windows (x64)

License

MIT