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.
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
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/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"
]
},
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.
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