From 83193778a7a027809de4e2a21813d451639b102d Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 24 Jun 2026 13:03:32 +0300 Subject: [PATCH 1/5] Have a separate paragraph mentioning the client server protocols Also link to example protocols, sendme as typical client server and gossip as canonical p2p proto --- concepts/protocols.mdx | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/concepts/protocols.mdx b/concepts/protocols.mdx index f032132..97e3684 100644 --- a/concepts/protocols.mdx +++ b/concepts/protocols.mdx @@ -10,10 +10,17 @@ whatever your application needs. iroh provides the pool of encrypted QUIC connections - protocols define what to do with them. +## Client-server protocols + +Sometimes it is best to have classical client and server roles at the application +level. Iroh connections do support this, and many n0 protocols are written in this +way. [Sendme], [dumbpipe], [iroh-blobs] and all [irpc] based protocols have clear +client and server roles at the application level. + ## Peer-to-peer protocols Unlike HTTP's client/server model where one side only sends requests and the -other only responds, peer-to-peer protocols typically support **both** +other only responds, peer-to-peer protocols support **both** initiating and accepting connections on the same endpoint. This means: @@ -21,10 +28,11 @@ This means: - Any peer can offer data to any other peer - Roles can change over time (today's client is tomorrow's server) +[Gossip] and [docs] are examples of peer-to-peer protocols. + You can still build client/server-style protocols if your application needs that distinction, but iroh's P2P foundation gives you more flexibility. - ## Building blocks, not a framework iroh is designed as a set of composable building blocks. The core `iroh` crate @@ -82,4 +90,11 @@ Ready to start building with protocols? **Building your own:** - [Write your own protocol guide](/protocols/writing-a-protocol) - [QUIC streaming patterns](/protocols/using-quic) -- [Router API documentation](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html) \ No newline at end of file +- [Router API documentation](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html) + +[Sendme]: https://github.com/n0-computer/sendme +[dumbpipe]: https://github.com/n0-computer/dumbpipe +[iroh-blobs]: /protocols/blobs +[irpc]: https://docs.rs/irpc +[Gossip]: /connecting/gossip +[docs]: /protocols/documents \ No newline at end of file From b83512715e2674c6368cd1051b69e027e87e9443 Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 24 Jun 2026 13:04:43 +0300 Subject: [PATCH 2/5] Move local-first lower Rationale: local first people will know iroh already and don't need this on top. People that are more familiar with client server roles should not be discouraged as in "iroh is for local first stuff primarily" --- what-is-iroh.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/what-is-iroh.mdx b/what-is-iroh.mdx index a36c91a..4989ee6 100644 --- a/what-is-iroh.mdx +++ b/what-is-iroh.mdx @@ -28,17 +28,17 @@ integrity. and real-time collaboration. ## Use cases -- **Local-first, offline-first, peer-to-peer applications**: iroh provides the networking foundation for - building applications that can operate without reliance on servers. +- **Real-time communication**: Build [chat applications](/examples/chat), [RPC +services](/protocols/rpc), and [streaming data](/protocols/streaming) with +iroh's communication protocols. - **Files & blobs**: With protocols like [iroh-blobs](/protocols/blobs), iroh enables efficient file transfer. +- **Local-first, offline-first, peer-to-peer applications**: iroh provides the networking foundation for + building applications that can operate without reliance on servers. - **Structured data**: iroh's support for flexible data protocols like [Documents](/protocols/documents) and [Automerge](/protocols/automerge) allows developers to build applications that support real-time collaborative editing and data synchronization. Any kind of CRDT or OT sync protocol can be integrated. -- **Real-time communication**: Build [chat applications](/examples/chat), [RPC -services](/protocols/rpc), and [streaming data](/protocols/streaming) with -iroh's communication protocols. ## How iroh works From 43566fc19740b1e81b0a8427d377c08ab8ee3d7d Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 24 Jun 2026 13:28:36 +0300 Subject: [PATCH 3/5] Move documents down. Documents shouldn't be the first thing we point people at, given that it is on limited support. --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 6155a92..ff43b1f 100644 --- a/docs.json +++ b/docs.json @@ -69,11 +69,11 @@ "group": "Sending Data", "expanded": false, "pages": [ - "protocols/documents", "protocols/blobs", "protocols/rpc", "protocols/automerge", "protocols/streaming", + "protocols/documents", "protocols/writing-a-protocol" ] }, From 2b4d4a7015f63792329be4e3ba5075355eba1a82 Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 24 Jun 2026 13:29:57 +0300 Subject: [PATCH 4/5] Change most to many. We got some non p2p people on the team and we don't want to give the impression that we care most about pure p2p use cases. --- about/faq.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/faq.mdx b/about/faq.mdx index a76d10f..3969d97 100644 --- a/about/faq.mdx +++ b/about/faq.mdx @@ -22,7 +22,7 @@ Because applications dial by key rather than by address, iroh is also well posit The main difference is that iroh tries to use existing IETF standards as much as possible instead of reinventing the wheel. An iroh connection is just a QUIC connection, using TLS and TLS ALPNs for protocol negotiation. If you look at one in Wireshark, it's indistinguishable from any other QUIC connection, so existing tooling works and what you learn using iroh transfers to plain QUIC and vice versa. -Most iroh contributors come out of the P2P world and had a bit of "abstraction fatigue" after years of working on traditional P2P networks. So where many P2P networks ship their own DHT for discovery, iroh resisted that temptation and instead uses the biggest DHT that already exists, [BitTorrent's Mainline DHT](/connecting/dht-address-lookup), for peer-to-peer [address lookup](/concepts/address-lookup). +Many iroh contributors come out of the P2P world and had a bit of "abstraction fatigue" after years of working on traditional P2P networks. So where many P2P networks ship their own DHT for discovery, iroh resisted that temptation and instead uses the biggest DHT that already exists, [BitTorrent's Mainline DHT](/connecting/dht-address-lookup), for peer-to-peer [address lookup](/concepts/address-lookup). Some "regular P2P networks" actually run on iroh under the hood, including [Holochain](https://blog.holochain.org) and various P2P chat apps. From 77123ff4512ad33c251fb4bb2a2fa1a63ee98690 Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 24 Jun 2026 14:23:37 +0300 Subject: [PATCH 5/5] Remove some of the peer to peer wording from the ping example. --- connect-two-endpoints.mdx | 8 ++++++-- languages/swift.mdx | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/connect-two-endpoints.mdx b/connect-two-endpoints.mdx index 37a122b..3d810b6 100644 --- a/connect-two-endpoints.mdx +++ b/connect-two-endpoints.mdx @@ -3,7 +3,9 @@ title: "Connect two endpoints" description: "Build a ping program that connects two endpoints over iroh" --- -In this tutorial we'll build a small peer-to-peer ping program using iroh and the [iroh-ping](https://github.com/n0-computer/iroh-ping) protocol. One endpoint runs as a **receiver**, prints a ticket, and waits for incoming pings. The other runs as a **sender**, dials the receiver using the ticket, and reports the round-trip time. +In this tutorial we'll build a small ping program using iroh and the [iroh-ping](https://github.com/n0-computer/iroh-ping) protocol. One endpoint runs as a **receiver**, prints a ticket, and waits for incoming pings. The other runs as a **sender**, dials the receiver using the ticket, and reports the round-trip time. + +Ping is a simple request/response protocol with sender and receiver roles. But unlike IP ping ([ICMP]), iroh ping works even if both devices are behind a NAT. The full example can be [viewed on GitHub](https://github.com/n0-computer/iroh-ping/blob/main/examples/quickstart.rs). @@ -449,9 +451,11 @@ IROH_SERVICES_API_SECRET=YOUR_API_KEY cargo run -- receiver ## More tutorials -You've now built a peer-to-peer ping tool. The full example is [on GitHub](https://github.com/n0-computer/iroh-ping). +You've now built a ping tool. The full example is [on GitHub](https://github.com/n0-computer/iroh-ping). If you're hungry for more, check out: - [Blob storage with iroh-blobs](/protocols/blobs) - [Build your own P2P chat app](/examples/chat) - [Rust API documentation](https://docs.rs/iroh) + +[ICMP]: https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol diff --git a/languages/swift.mdx b/languages/swift.mdx index ff8b31e..050d31b 100644 --- a/languages/swift.mdx +++ b/languages/swift.mdx @@ -152,7 +152,7 @@ Then in Xcode, **File → Add Package Dependencies… → Add Local…** and pic ## Next steps - Build a peer-to-peer ping over iroh and learn how tickets, ALPNs, and routers fit together. + Build a ping over iroh and learn how tickets, ALPNs, and routers fit together.