Merge pull request #4 from n0-computer/rae/docs-review2

Rae/docs review2

Author: okdistribute

about/roadmap.mdx

@@ -2,22 +2,41 @@
 title: "Relays"
 ---
 
-Relays are servers that help establish connections between devices. 
-
-Relays temporarily route encrypted traffic until a direct, P2P connection is
+Relays are servers that temporarily route encrypted traffic until a direct, P2P connection is
 feasible. Once this direct path is set up, the relay server steps back, and the
 data flows directly between devices. This approach allows Iroh to maintain a
 secure, low-latency connection, even in challenging network situations.
 
-Relays are also open source! You can run your own relay server, or use one of
-the public relays. Code is
-[here](https://github.com/n0-computer/iroh/tree/main/iroh-relay), and we build
-relay binaries for most platforms with each iroh
-[release](https://github.com/n0-computer/iroh/releases)
+There are situations where a direct connection _can't_ be established, and in
+those cases traffic falls back to running through the relay. Relay servers **do
+not** have access to the data being transmitted, as it's encrypted end-to-end.
+
+We're working on formally collecting the direct connection rate from production
+iroh networks. Anecdotal evidence points to the holepunching rate being around
+90%, meaning 9 out of 10 times, a direct connection is established.
+
+## Public relays
+
+iroh is configured with a set of public relays provided by [The n0
+team](https://n0.computer) that are free to use. The public relays rate-limit
+traffic that flows through the relay. This is to prevent abuse, and ensure the
+relays are available to everyone. There are no guarantees around uptime or
+performance when using the public relays.
 
-There are situations where a direct connection _can't_ be established, and in those cases traffic falls back to running through the relay. Relay servers **do not** have access to the data being transmitted, as it's encrypted end-to-end.
+We recommend using the public relays for development and testing, as they are
+free to use and require no setup. However, for production systems, we recommend
+using dedicated relays instead.
+
+## Dedicated relays
+
+For production use, we recommend using dedicated relays. Dedicated relays are relay
+servers that are either self-hosted or provided as a managed service. Dedicated
+relays provide better performance, security, and uptime guarantees compared to
+the public relays. 
+
+Relay code is open source! You can run your own relay server, or [pick a hosting
+provider](https://n0des.iroh.computer).
 
-We're working on formally collecting the direct connection rate from production iroh networks. Anecdotal evidence points to the holepunching rate being around 90%, meaning 9 out of 10 times, a direct connection is established.
 
 ### Why this architecture is powerful
 
@@ -53,12 +72,10 @@ to relayed, or even a mixed combination of the two. Iroh will automatically
 switch between direct and relayed connections as needed, without any action
 required from the application.
 
-## number 0 public relays
+## Read more
+
+- [Dedicated infrastructure guide](/deployment/dedicated-infrastructure)
+- [Relay source code](https://github.com/n0-computer/iroh/tree/main/iroh-relay)
+- [Relay binary releases](https://github.com/n0-computer/iroh/releases)
+- [Managed relay service](https://n0des.iroh.computer)
 
-number 0 provides a set of public relays that are free to use, and are
-configured by default. You're more than welcome to run production systems using
-the public relays if you find performance acceptable. The public relays do
-rate-limit traffic that flows through the relay. This is to prevent abuse, and
-ensure the relays are available to everyone. If you need more capacity, you can
-run your own relay server, or [contact us about a custom relay
-setup](https://n0.computer/n0ps/).

concepts/relays.mdx

@@ -34,8 +34,8 @@ async fn main() -> anyhow::Result<()> {
 
     println!("endpoint id: {:?}", endpoint.id());
 
-   let ticket = EndpointTicket::new(endpoint.addr());
-   println!("Share this ticket to let others connect to your endpoint: {ticket}");
+    let ticket = EndpointTicket::new(endpoint.addr());
+    println!("Share this ticket to let others connect to your endpoint: {ticket}");
 
     Ok(())
 }

connecting/dns-discovery.mdx

@@ -17,9 +17,18 @@ We recommend using the public relays for development and testing, as they are
 free to use and require no setup. However, for production systems, we recommend
 using dedicated relays instead.
 
+## Using dedicated relays
+
+To use dedicated relays with your iroh endpoint, you need to configure the
+endpoint to use your relay's URL.
+
+For detailed information on configuring custom relays, including code examples
+and API documentation, see the [iroh relay configuration
+guide](https://n0des.iroh.computer/docs/relays/managed).
+
 ## Why use dedicated relays in production?
 
-Using a dedicated relays can provide several benefits, including improved performance,
+Using dedicated relays can provide several benefits, including improved performance,
 enhanced security, better uptime guarantees, and greater control over your network infrastructure. By
 using your own servers, you can optimize connection speeds and reduce
 latency for your specific use case. 
@@ -64,12 +73,3 @@ For even better guarantees, you can distribute relays across multiple cloud prov
 Adding capacity means spinning up more lightweight relay instances, not provisioning databases or managing complex stateful server infrastructure. You can easily scale up for peak usage and scale down during quiet periods.
 
 This architecture inverts the traditional model: instead of treating servers as precious stateful resources and clients as disposable, relay-based architectures treat relays as disposable connection facilitators while clients own the application state and logic.
-
-## Using dedicated relays
-
-To use dedicated relays with your iroh endpoint, you need to configure the
-endpoint to use your relay's URL.
-
-For detailed information on configuring custom relays, including code examples
-and API documentation, see the [iroh relay configuration
-guide](https://n0des.iroh.computer/docs/relays/managed).

deployment/dedicated-infrastructure.mdx

@@ -200,7 +200,7 @@ async fn request(conn: &Connection, request: &[u8]) -> Result<Vec<u8>> {
 
     let response = recv.read_to_end(MAX_RESPONSE_SIZE).await?;
 
-    Ok(response);
+    Ok(response)
 }
 
 // The accepting endpoint will call this to handle all
@@ -229,7 +229,7 @@ async fn handle_request(mut send: SendStream, mut recv: RecvStream) -> Result<()
 }
 ```
 
-Please not that, in this case, the client doesn't immediately close the connection after a single request (duh!). Instead, it might want to optimistically keep the connection open for some idle time or until it knows the application won't need to make another request, and only then close the connection. All that said, it's still true that **the connecting side closes the connection**.
+Please note that, in this case, the client doesn't immediately close the connection after a single request (duh!). Instead, it might want to optimistically keep the connection open for some idle time or until it knows the application won't need to make another request, and only then close the connection. All that said, it's still true that **the connecting side closes the connection**.
 
 ## Multiple ordered Notifications
 
@@ -333,7 +333,7 @@ In that case, we need to break up the single response stream into multiple respo
 We can do this by "conceptually" splitting the "single" bi-directional stream into one uni-directional stream for the request and multiple uni-directional streams in the other direction for all the responses:
 
 ```rs
-async fn connnecting_side(conn: Connection, request: &[u8]) -> Result<()> {
+async fn connecting_side(conn: Connection, request: &[u8]) -> Result<()> {
     let mut send = conn.open_uni().await?;
     send.write_all(request).await?;
     send.finish()?;
@@ -362,9 +362,6 @@ Another thing that might or might not be important for your use case is knowing
 You can either introduce another message type that is interpreted as a finishing token, but there's another elegant way of solving this. Instead of only opening a uni-directional stream for the request, you open a bi-directional one. The response stream will only be used to indicate the final response stream ID. It then acts as a sort of "control stream" to provide auxiliary information about the request for the connecting endpoint.
 </Note>
 
-## Proxying UDP traffic using the unreliable datagram extension
-
-
 ## Time-sensitive Real-time interaction
 
 We often see users reaching for the QUIC datagram extension when implementing real-time protocols. Doing this is in most cases misguided.
@@ -377,9 +374,6 @@ A real-world example is the media over QUIC protocol (MoQ in short): MoQ is used
 The receiver then stops streams that are "too old" to be delivered, e.g. because it's a live video stream and newer frames were already fully received.
 Similarly, the sending side will also reset older streams for the application level to indicate to the QUIC stack it doesn't need to keep re-trying the transmission of an outdated live video frame. (MoQ will actually also use stream prioritization to make sure the newest video frames get scheduled to be sent first.)
 
-https://discord.com/channels/1161119546170687619/1195362941134962748/1407266901939327007
-https://discord.com/channels/976380008299917365/1063547094863978677/1248723504246030336
-
 ## Closing Connections
 
 Gracefully closing connections can be tricky to get right when first working with the QUIC API.
@@ -428,7 +422,40 @@ And again, after `handle_connection` we need to make sure to wait for `Endpoint:
 
 ## Aborting Streams
 
-https://discord.com/channels/949724860232392765/1399719019292000329/1399721482522984502
+Sometimes you need to abandon a stream before it completes - either because the data has become stale, or because you've decided you no longer need it. QUIC provides mechanisms for both the sender and receiver to abort streams gracefully.
+
+### When to abort streams
+
+A real-world example comes from Media over QUIC (MoQ), which streams live video frames. Consider this scenario:
+
+- Each video frame is sent on its own uni-directional stream
+- Frames arrive out of order due to network conditions
+- By the time an old frame finishes transmitting, newer frames have already been received
+- Continuing to receive the old frame wastes bandwidth and processing time
+
+### How to abort streams
+
+**From the sender side:**
+
+Use `SendStream::reset(error_code)` to immediately stop sending data and discard any buffered bytes. This tells QUIC to stop retrying lost packets for this stream.
+
+
+**From the receiver side:**
+
+Use `RecvStream::stop(error_code)` to tell the sender you're no longer interested in the data. This allows the sender's QUIC stack to stop retransmitting lost packets.
+
+
+### Key insights
+
+1. **Stream IDs indicate order**: QUIC stream IDs are monotonically increasing. You can compare stream IDs to determine which streams are newer without relying on application-level sequencing.
+
+2. **Both sides can abort**: Either the sender (via `reset`) or receiver (via `stop`) can abort a stream. Whichever side detects the data is no longer needed first should initiate the abort.
+
+3. **QUIC stops retransmissions**: When a stream is reset or stopped, QUIC immediately stops trying to recover lost packets for that stream, saving bandwidth and processing time.
+
+4. **Streams are cheap**: Opening a new stream is very fast (no round-trips required), so it's perfectly fine to open one stream per video frame, message, or other small unit of data.
+
+This pattern of using many short-lived streams that can be individually aborted is one of QUIC's most powerful features for real-time applications. It gives you fine-grained control over what data is worth transmitting, without the head-of-line blocking issues that would occur with a single TCP connection.
 
 ## QUIC 0-RTT features
 

protocols/using-quic.md

@@ -88,7 +88,7 @@ use iroh_ping::Ping;
 async fn main() -> anyhow::Result<()> {
     // Create an endpoint, it allows creating and accepting
     // connections in the iroh p2p world
-    let endpoint = Endpoint::builder().bind().await?;
+    let endpoint = Endpoint::bind().await?;
 
     // bring the endpoint online before accepting connections
     endpoint.online().await;
@@ -107,7 +107,6 @@ async fn main() -> anyhow::Result<()> {
 }
 ```
 
-With these two lines, we've initialized iroh-blobs and gave it access to our `Endpoint`.
 
 ### Ping: Send
 At this point what we want to do depends on whether we want to accept incoming iroh connections from the network or create outbound iroh connections to other endpoints.
@@ -124,7 +123,7 @@ use iroh_ping::Ping;
 async fn main() -> Result<()> {
     // Create an endpoint, it allows creating and accepting
     // connections in the iroh p2p world
-    let endpoint = Endpoint::builder().bind().await?;
+    let endpoint = Endpoint::bind().await?;
 
     // Then we initialize a struct that can accept ping requests over iroh connections
     let ping = Ping::new();
@@ -138,7 +137,7 @@ async fn main() -> Result<()> {
     let addr = recv_router.endpoint().addr();
 
     // create a send side & send a ping
-    let send_ep = Endpoint::builder().bind().await?;
+    let send_ep = Endpoint::bind().await?;
     let send_pinger = Ping::new();
     let rtt = send_pinger.ping(&send_ep, addr).await?;
 
@@ -180,7 +179,7 @@ relay URL, and direct addresses. An address is a structured representation of
 this information that can be consumed by iroh endpoints to dial each other.
 
 An `EndpointTicket` wraps this address into a serializable format -- a short
-string you can copy and paste. Share this sting with senders so they can dial
+string you can copy and paste. Share this string with senders so they can dial
 the receiver without manually exchanging networking details.
 
 This out of band information must be sent between the endpoints so that they can