DOCSEARCHbyAlgolia
Submit Docs

Iroh Examples

repository·main·Indexed 42 days ago

https://github.com/n0-computer/iroh-examples

A collection of practical examples demonstrating the usage of the Iroh networking stack and its libraries. Includes implementations for WASM, custom routing, and integrations with Automerge, Extism, and FROST (Flexible Round-Optimized Schnorr Threshold Signatures), as well as demos for browser-based chat, blobs, and echo services.

Tokens
33.1K
Snippets
146
Records
172
Agent score
53%

What's inside Iroh Examples

  1. Overview of the browser-chat application

    main

    The browser-chat application is a chat system that runs in both the browser and the command line. It leverages iroh-gossip to facilitate message passing between peers sharing a common channel.

    The project is composed of four main parts:

    • shared: A Rust library providing the ChatNode abstraction, which uses iroh and iroh-gossip to power ephemeral gossip chat.
    • cli: A command-line interface built using the shared library.
    • browser-wasm: A Rust wrapper around the shared library that uses wasm-bindgen to export JavaScript bindings.
    • frontend: A TypeScript web application built with React, shadcn components, and Vite.

  2. Overview of Iroh Examples

    main
    The iroh-examples repository provides various implementations and demonstrations of how to use the iroh core library or its individual crates. These examples range from browser-based WASM implementations to advanced networking patterns like custom routers and message framing. For highly experimental features, refer to the iroh-experiments repository.

  4. Understand the iroh-blobs project structure

    main

    The browser-blobs directory contains a single Rust crate designed to be compiled for both WebAssembly (WASM) and the Command Line Interface (CLI).

    • Shared Logic: src/node.rs contains the core code used by both WASM and CLI.
    • WASM Wrapper: src/wasm.rs provides a wrapper around the BlobNode (defined in src/node.rs) to convert types into browser-compatible formats.
    • CLI Entrypoint: src/bin/cli.rs is the binary for the command line interface.
    • Web Frontend: The public directory contains the vanilla JavaScript web application.
    • Build Process: Running npm run build compiles the crate to WASM, generates JavaScript bindings via wasm-bindgen, and outputs the results to public/wasm for use by public/main.js.

  5. Understand the iroh-automerge-repo implementation

    main

    The project is composed of three main components:

    • IrohRepo struct (in lib.rs): The core implementation that combines an iroh::Endpoint with a samod::Samod automerge repository. It implements iroh::protocol::ProtocolHandler, allowing it to be used with an iroh::protocol::Router to accept incoming connections.
    • codec.rs: A utility that adapts tokio-util's LengthDelimitedCodec to work with Vec<u8> instead of Bytes.
    • main.rs: The CLI entrypoint providing the user interface for creating, upserting, and printing documents.

  6. Understand the browser-echo project structure

    main

    The browser-echo example is a single Rust crate designed to be compiled for both WebAssembly (browser) and CLI environments.

    Key components include:

    • Shared Logic: src/node.rs contains the core EchoNode logic used by both WASM and CLI.
    • WASM Wrapper: src/wasm.rs provides a wrapper around EchoNode to convert types into browser-compatible equivalents.
    • CLI Entrypoint: src/bin/cli.rs defines the command-line interface.
    • Frontend Assets: The public directory contains the HTML, CSS, and JavaScript. main.js imports the WASM bindings generated in public/wasm by wasm-bindgen during the build process.

  7. Implement message framing on Iroh streams

    main

    When implementing a custom protocol over Iroh connections, you are working with raw byte streams. To send discrete messages (rather than a continuous stream of bytes), you must implement "framing" to define message boundaries.

    In this pattern, you wrap the Iroh SendStream and RecvStream (obtained via iroh::Connection::open_bi) using tokio_util::codec to transform them from byte-oriented streams into message-oriented Stream and Sink objects.

    The Framing Workflow:

    1. Obtain Streams: Use iroh::Connection::open_bi to get SendStream and RecvStream. These implement AsyncWrite and AsyncRead respectively.
    2. Apply Codec: Wrap the streams using tokio_util::codec::FramedRead and tokio_util::codec::FramedWrite with a LengthDelimitedCodec.
    3. Define Boundaries: The LengthDelimitedCodec prefixes each message with a big-endian encoded u32 representing the length of the following message, allowing the receiver to identify message boundaries.
    4. Serialize Data: Use a serialization format like postcard and serde to convert your data structures (e.g., a Move struct) into bytes::Bytes before sending them through the Sink.
    // Conceptual workflow summary:
// 1. iroh::Connection::open_bi -> SendStream (AsyncWrite), RecvStream (AsyncRead)
// 2. Wrap with tokio_util::codec::FramedWrite<SendStream, LengthDelimitedCodec> -> Sink<Bytes>
// 3. Wrap with tokio_util::codec::FramedRead<RecvStream, LengthDelimitedCodec> -> Stream<Bytes>
// 4. Use postcard/serde to serialize structs into Bytes

  8. Implement a custom Iroh Router

    main
    If the standard iroh::protocol::Router does not provide sufficient control or customization for your needs, you should implement your own router. The custom-router example demonstrates how to build a router that allows for adding and removing protocols at runtime.

  9. How iroh-automerge integrates Automerge and Iroh

    main

    This example combines two core technologies:

    • Automerge: A Conflict-Free Replicated Data Type (CRDT) that represents JSON-like data. It allows machines to gossip updates and data to eventually converge to the same state without a single source of truth.
    • Iroh: Provides the peer-to-peer connectivity layer. Instead of using IP addresses or domain names, Iroh identifies nodes using cryptographic public keys. This allows for secure, encrypted connections that can be automatically upgraded to direct peer-to-peer connections.

  11. Run the Iroh gateway example

    main

    The Iroh gateway is a stateless HTTP gateway that serves content from a local or remote Iroh node using the iroh-blobs protocol. It supports range requests (allowing for video streaming and seeking) and MIME type sniffing.

    Prerequisites

    • An up-to-date version of Rust installed via rustup (including rustc and cargo).
    • An active Iroh node containing the content you wish to serve.
    cargo run --default_node <ENDPOINT_ID>

  12. Run the iroh browser echo CLI version

    main

    The CLI version of the echo demo allows you to either accept incoming connections or initiate a connection to a remote endpoint using the Echo protocol. The protocol is shared with the browser version, allowing browser and CLI endpoints to communicate.

    # To accept connections:
cargo run --features cli -- accept

# To initiate a connection:
cargo run --features cli -- connect <ENDPOINT-ID> <PAYLOAD>