diff --git a/concepts/discovery.mdx b/concepts/discovery.mdx index 1123658..92e8cf7 100644 --- a/concepts/discovery.mdx +++ b/concepts/discovery.mdx @@ -29,7 +29,7 @@ There are four different implementations of the discovery service in iroh. **By We want iroh to establish connections with as little friction as possible. Our first big push toward chipping away at this goal was adding [holepunching](/concepts/holepunching) into iroh. Now, devs no longer need to worry about opening up ports on their servers -/ firewalls or be resigned to only creating peer-to-peer connections to +/ firewalls or be resigned to only creating connections to computers inside their local NAT. But even with holepunching, you need to know *where* to dial. Dialing an endpoint in diff --git a/concepts/endpoints.mdx b/concepts/endpoints.mdx index b74f8bd..68cc8fa 100644 --- a/concepts/endpoints.mdx +++ b/concepts/endpoints.mdx @@ -3,22 +3,22 @@ title: "Endpoints" --- An _endpoint_ is the main API interface to create connections to, and accept -connections from other iroh endpoints. The connections are peer-to-peer and +connections from other iroh endpoints. The connections are end-to-end encrypted. Endpoints have a `EndpointID` (the public half of an Ed25519 keypair) and the private key used to sign and decrypt messages. Generally, an application will have a single endpoint instance. This ensures all -the connections made share the same peer-to-peer connections to other iroh +the connections made share the same connections to other iroh endpoints, while still remaining independent connections. This will result in more optimal network behaviour. ## Connections -Because we're in a peer-to-peer context, either endpoint might be operating as -the "server", so we use `connect` and `accept` to distinguish between the two. -The `connect` method is used to create a new connection to a remote endpoint, -while `accept` is used to accept incoming connections from a remote endpoint. +Either endpoint might be operating as the "server", so we use `connect` and +`accept` to distinguish between the two. The `connect` method is used to create +a new connection to a remote endpoint, while `accept` is used to accept incoming +connections from a remote endpoint. Connections are full-fledged QUIC connections, giving you access to most features of QUIC / HTTP3, including bidirectional and unidirectional streams. diff --git a/concepts/holepunching.mdx b/concepts/holepunching.mdx index 1005ecf..2f1c7ab 100644 --- a/concepts/holepunching.mdx +++ b/concepts/holepunching.mdx @@ -10,16 +10,14 @@ Imagine you're trying to video call a friend. Both of you are behind routers at home. When you try to connect directly to each other, your routers' firewalls block the incoming connection because they don't recognize it as a response to something you requested. The combination of NAT (which translates addresses) and -firewall rules (which filter traffic) makes direct peer-to-peer connections +firewall rules (which filter traffic) makes direct connections challenging. Traditionally, this problem was solved by: - **Port forwarding**: Manually configuring your router to allow specific connections (tedious and requires technical knowledge) - **Relay servers**: Routing all traffic through a third-party server (slow and expensive) -Neither solution is ideal for peer-to-peer applications. - -## The Solution: Holepunching +## The Innovation: Holepunching **Holepunching** is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers. diff --git a/concepts/protocols.mdx b/concepts/protocols.mdx index 0d788e6..40dec54 100644 --- a/concepts/protocols.mdx +++ b/concepts/protocols.mdx @@ -7,12 +7,14 @@ behavior. Once you've established an iroh connection, protocols determine what happens next: transferring files, syncing documents, broadcasting messages, or whatever your application needs. -iroh provides the encrypted, peer-to-peer connections - protocols define what to +iroh provides the pool of encrypted QUIC connections - protocols define what to do with them. ## 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** initiating and accepting connections on the same endpoint. +Unlike HTTP's client/server model where one side only sends requests and the +other only responds, peer-to-peer protocols typically support **both** +initiating and accepting connections on the same endpoint. This means: - Any peer can request data from any other peer diff --git a/concepts/relays.mdx b/concepts/relays.mdx index 11f88fa..3b3b287 100644 --- a/concepts/relays.mdx +++ b/concepts/relays.mdx @@ -37,7 +37,7 @@ Relay code is open source! You can run your own relay server, or [pick a hosting provider](https://n0des.iroh.computer). -### Why this architecture is powerful +## Why this architecture is powerful This approach makes uptime management significantly easier compared to traditional client-server architectures: diff --git a/concepts/tickets.mdx b/concepts/tickets.mdx index eb2bb56..abd5107 100644 --- a/concepts/tickets.mdx +++ b/concepts/tickets.mdx @@ -62,7 +62,7 @@ The postcard encoding keeps tickets compact despite containing multiple pieces o ## Security considerations -**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct peer-to-peer connections without a central server. +**Tickets contain IP addresses**: When you create a ticket, it embeds the IP addresses you're currently reachable at. Sharing a ticket means sharing your IP address with whoever receives it. This is intentional - it enables direct connections without a central server. This is actually *better* than many P2P systems that broadcast your IP to all peers. With tickets, you form a "cozy network" between peers you explicitly choose to connect with. diff --git a/connecting/creating-endpoint.mdx b/connecting/creating-endpoint.mdx index 0e0aa17..8a3f65c 100644 --- a/connecting/creating-endpoint.mdx +++ b/connecting/creating-endpoint.mdx @@ -6,14 +6,8 @@ An endpoint is the core building block of an iroh node. It manages network connections, handles incoming and outgoing traffic, and provides the necessary infrastructure for implementing protocols. -Once you have an Endpoint, you can use it to create connections or accept incoming connections from other endpoints. - -Unlike HTTP servers, which listen on specific ports, iroh Endpoints use a peer-to-peer -model to establish connections. This means that endpoints can connect directly -to each other without relying on a central server. - -This means that endpoints can be more resilient to network issues and can operate in -a wider range of network environments. +Once you have an Endpoint, you can use it to create connections or accept +incoming connections from other endpoints. ## Creating an Endpoint diff --git a/deployment/dedicated-infrastructure.mdx b/deployment/dedicated-infrastructure.mdx index e6cbc5c..3e1d032 100644 --- a/deployment/dedicated-infrastructure.mdx +++ b/deployment/dedicated-infrastructure.mdx @@ -8,7 +8,7 @@ DNS and end-to-end encryption over relays. This infrastructure comprises: 1. [Relays](/concepts/relays) 2. [Discovery Servers (DNS)](/concepts/discovery) -Relays forward traffic when direct peer-to-peer connections are not possible as well +Relays forward traffic when direct connections are not possible as well as facilitates holepunching for direct connections. These servers are managed and maintained by [the n0 team](https://n0.computer), and are shared by a global public network of developers. diff --git a/deployment/wasm-browser-support.mdx b/deployment/wasm-browser-support.mdx index 38d25a2..f75fc3a 100644 --- a/deployment/wasm-browser-support.mdx +++ b/deployment/wasm-browser-support.mdx @@ -28,8 +28,10 @@ This is because we can't port our hole-punching logic in iroh to browsers: They Keep in mind that *connections are end-to-end encrypted*, as always with iroh. So even though traffic from browsers is always relayed, it can't be decrypted by the relay. -There are other ways of getting peer-to-peer connections going, such as WebTransport with `serverCertificateHashes`, or WebRTC. -We may expand iroh's browser support to make use of these to try to generate fully peer-to-peer connections even when a browser node is involved in the connection. +There are other ways of getting direct connections going, such as WebTransport +with `serverCertificateHashes`, or WebRTC. We may expand iroh's browser support +to make use of these to try to generate direct connections even when a browser +node is involved in the connection. ### `iroh` crate features diff --git a/docs.json b/docs.json index 4b30ced..c4624fd 100644 --- a/docs.json +++ b/docs.json @@ -21,6 +21,7 @@ "examples/examples", { "group": "How it works", + "expanded": true, "pages": [ "concepts/endpoints", "concepts/tickets", @@ -43,7 +44,7 @@ ] }, { - "group": "Communicating over Iroh", + "group": "Building your App", "pages": [ "protocols/kv-crdts", "protocols/blobs", diff --git a/examples/chat.mdx b/examples/chat.mdx index 1f686f7..3d413b0 100644 --- a/examples/chat.mdx +++ b/examples/chat.mdx @@ -1,10 +1,13 @@ import { YouTube } from '@/components/youtube' -## Building a P2P Chat Application with Iroh +## Building a Chat Application with Iroh -This tutorial demonstrates how to build a peer-to-peer chat application from scratch using Rust and the Iroh library. While this implementation is simplified, it illustrates core concepts of P2P networking and the Iroh gossip protocol. +This tutorial demonstrates how to build a peer-to-peer chat application from +scratch using Rust and the Iroh library. While this implementation is +simplified, it illustrates core concepts of the iroh gossip +protocol. The code in the above video differs slightly from the code presented below. We recommend watching the video and following along until you get comfortable. When you are ready for a deeper dive into the code, walk through this tutorial. diff --git a/examples/examples.mdx b/examples/examples.mdx index e43baed..cc21494 100644 --- a/examples/examples.mdx +++ b/examples/examples.mdx @@ -9,7 +9,7 @@ title: "Examples" icon="image" href="https://www.iroh.computer/sendme" > - Sendme will connect your devices directly & transfer files peer-to-peer, + Sendme will connect your devices directly & transfer files, without any accounts or configuration. -A peer-to-peer multiplayer extension for Godot based on iroh. +A multiplayer extension for Godot based on iroh. - Store and transfer large binary files peer-to-peer. + Store and transfer large binary files. - Build low-latency peer-to-peer audio and video streaming applications. + Build low-latency audio and video streaming applications.