Add blobs fix links

okdistribute · okdistribute · commit b05048588a49 · 2025-12-01T18:14:10.000-08:00
diff --git a/concepts/discovery.mdx b/concepts/discovery.mdx
@@ -3,13 +3,13 @@ title: "Discovery"
 ---
 
 
-Discovery is the glue that connects an [Endpoint](/docs/concepts/endpoint#endpoint-identifiers) to something we can dial. Discovery services resolve EndpointIds to either a home Relay URL or direct-dialing information. 
+Discovery is the glue that connects an [Endpoint](/concepts/endpoints#endpoint-identifiers) to something we can dial. Discovery services resolve EndpointIds to either a home Relay URL or direct-dialing information. 
 
 <Note>
   More details on discovery in the discovery module [documentation](https://docs.rs/iroh/latest/iroh/discovery/index.html)
 </Note>
 
-Endpoint discovery is an automated system for an [Endpoint](/docs/concepts/endpoint) to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured discovery services. Usually this means publishing which [Home Relay](/docs/concepts/relay#home-relay) an endpoint is findable at, but they could also publish their direct addresses.
+Endpoint discovery is an automated system for an [Endpoint](/concepts/endpoints) to retrieve addressing information. Each iroh endpoint will automatically publish their own addressing information with configured discovery services. Usually this means publishing which [Home Relay](/concepts/relay#home-relay) an endpoint is findable at, but they could also publish their direct addresses.
 
 ## Discovery Services
 
diff --git a/concepts/endpoints.mdx b/concepts/endpoints.mdx
@@ -2,7 +2,11 @@
 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 encrypted, a [Relay](/docs/concepts/relay) server is used to make the connections reliable. Endpoints have a `EndpointID` (the public half of an Ed25519 keypair) and the private key used to sign and decrypt messages.
+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
+encrypted, a [Relay](/concepts/relays) server is used to make the
+connections reliable. 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 endpoints, while still remaining independent connections. This will result in more optimal network behaviour.
 
@@ -25,4 +29,9 @@ Due to the light-weight properties of QUIC streams a stream can only be accepted
 
 ## Building on Endpoints
 
-Endpoints are a low-level primitive that iroh exposes on purpose. For some projects like [dumbpipe](https://dumbpipe.dev), endpoints are 95% of what you need to connect any two devices on the planet. For others, like [iroh-blobs](/proto/iroh-blobs), endpoints are the foundation that higher-level protocols are built on. Most projects will not work with endpoints beyond constructing one and feeding it to one or more [protocols](/docs/concepts/protocol).
+Endpoints are a low-level primitive that iroh exposes on purpose. For some
+projects like [dumbpipe](https://dumbpipe.dev), endpoints are 95% of what you
+need to connect any two devices on the planet. For others, like
+[iroh-blobs](/proto/iroh-blobs), endpoints are the foundation that higher-level
+protocols are built on. Most projects will not work with endpoints beyond
+constructing one and feeding it to one or more [protocols](/concepts/protocols).
diff --git a/deployment/wasm-browser-support.mdx b/deployment/wasm-browser-support.mdx
@@ -11,7 +11,7 @@ Add `iroh` to your browser project's dependencies and keep building it using [wa
 
 For end-to-end examples of integrating iroh into a browser page, see these examples on our [iroh-examples repository](https://github.com/n0-computer/iroh-examples):
 - An [iroh echo server in the browser](https://github.com/n0-computer/iroh-examples/tree/main/browser-echo). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-echo/index.html)
-- An [browser chat room UI](https://github.com/n0-computer/iroh-examples/tree/main/browser-chat) based on the [iroh gossip chat example](/docs/examples/gossip-chat). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-chat/index.html)
+- An [browser chat room UI](https://github.com/n0-computer/iroh-examples/tree/main/browser-chat) based on the [iroh gossip chat example](/examples). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-chat/index.html)
 
 
 ## Limitations
diff --git a/docs.json b/docs.json
@@ -18,6 +18,7 @@
             "pages": [
               "what-is-iroh",
               "quickstart",
+              "examples",
             {
               "group": "Concepts",
               "expanded": true,
diff --git a/protocols/blobs.mdx b/protocols/blobs.mdx
@@ -22,51 +22,278 @@ cargo add iroh-blobs
 - [Primary docs and API reference](https://docs.rs/iroh-blobs/latest/iroh_blobs/)
 - [Code samples on GitHub](https://github.com/n0-computer/iroh-blobs/tree/main/examples)
 
-## Examples
+## Tutorial
 
-The crate is typically used by creating a store, a `BlobsProtocol` handler,
-and registering it with an `iroh::Router`. The code below is an illustrative
-outline — see the upstream examples for full runnable code.
+Let's dive into iroh by building a simple peer-to-peer file transfer tool in rust! 
+
+At the end we should be able to transfer a file from one device by running this:
+
+```sh
+$ cargo run -- send ./file.txt
+Indexing file.
+File analyzed. Fetch this file by running:
+cargo run -- receive blobabvojvy[...] file.txt
+```
+
+And then fetch it on any other device like so:
+```sh
+$ cargo run -- receive blobabvojvy[...] file.txt
+Starting download.
+Finished download.
+Copying to destination.
+Finished copying.
+Shutting down.
+```
+
+In this guide we'll be omitting the import statements required to get this working.
+If you're ever confused about what to import, take a look at the imports in the [complete example](https://github.com/n0-computer/iroh-blobs/blob/main/examples/transfer.rs).
+
+
+### Get set up
+
+We'll assume you've set up [rust](https://www.rust-lang.org/) and [cargo](https://doc.rust-lang.org/cargo/) on your machine.
+
+Initialize a new project by running:
+
+```bash
+cargo init file-transfer
+cd file-transfer
+```
+
+Now, add the dependencies we'll need for this tutorial:
+
+```bash
+cargo add iroh iroh-blobs tokio anyhow
+```
+
+From here on we'll be working inside the `src/main.rs` file.
+
+
+### Create an `iroh::Endpoint`
+
+To start interacting with other iroh endpoints, we need to build an `iroh::Endpoint`.
+This is what manages the possibly changing network underneath, maintains a connection to the closest relay, and finds ways to address devices by `EndpointId`.
 
 ```rust
-use iroh::{protocol::Router, Endpoint};
-use iroh_blobs::{store::mem::MemStore, BlobsProtocol, ticket::BlobTicket};
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Create an endpoint, it allows creating and accepting
+    // connections in the iroh p2p world
+    let endpoint = Endpoint::bind().await?;
+
+    // ...
 
+    Ok(())
+}
+```
+
+There we go, this is all we need to [open connections](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html#method.connect) or [accept them](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html#method.accept).
+
+### Using an existing protocol: iroh-blobs
+
+Instead of writing our own protocol from scratch, let's use [iroh-blobs](/proto/iroh-blobs), which already does what we want:
+It loads files from your file system and provides a protocol for seekable, resumable downloads of these files.
+
+```rust
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    // create an iroh endpoint that includes the standard discovery mechanisms
-    // we've built at number0
+    // Create an endpoint, it allows creating and accepting
+    // connections in the iroh p2p world
     let endpoint = Endpoint::bind().await?;
 
-    // create a protocol handler using an in-memory blob store.
+    // We initialize an in-memory backing store for iroh-blobs
     let store = MemStore::new();
-    let tag = store.add_slice(b"Hello world").await?;
-  
-    let _ = endpoint.online().await;
-    let addr = endpoint.addr();
-    let ticket = BlobTicket::new(addr, tag.hash, tag.format);
-
-    // build the router
+    // Then we initialize a struct that can accept blobs requests over iroh connections
     let blobs = BlobsProtocol::new(&store, None);
-    let router = Router::builder(endpoint)
-        .accept(iroh_blobs::ALPN, blobs)
-        .spawn();
-
-    println!("We are now serving {}", ticket);
 
-    // wait for control-c
-    tokio::signal::ctrl_c().await;
+    // ...
 
-    // clean shutdown of router and store
-    router.shutdown().await?;
     Ok(())
 }
 ```
 
-## Notes & best practices
+<Note>
+Learn more about what we mean by "protocol" on the [protocol documentation page](/concepts/protocols).
+</Note>
+
+With these two lines, we've initialized iroh-blobs and gave it access to our `Endpoint`.
+
+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.
+Which one we want to do depends on if the executable was called with `send` as an argument or `receive`, so let's parse these two options out from the CLI arguments and match on them:
+
+```rust
+// Grab all passed in arguments, the first one is the binary itself, so we skip it.
+let args: Vec<String> = std::env::args().skip(1).collect();
+// Convert to &str, so we can pattern-match easily:
+let arg_refs: Vec<&str> = args.iter().map(String::as_str).collect();
+
+match arg_refs.as_slice() {
+    ["send", filename] => {
+        todo!();
+    }
+    ["receive", ticket, filename] => {
+        todo!();
+    }
+    _ => {
+        println!("Couldn't parse command line arguments: {args:?}");
+        println!("Usage:");
+        println!("    # to send:");
+        println!("    cargo run -- send [FILE]");
+        println!("    # this will print a ticket.");
+        println!();
+        println!("    # to receive:");
+        println!("    cargo run -- receive [TICKET] [FILE]");
+    }
+}
+```
+
+We're also going to print some simple help text when there's no arguments or we can't parse them.
+
+What's left to do now is fill in the two `todo!()`s!
+
+
+### Getting ready to send
+
+If we want to make a file available over the network with iroh-blobs, we first need to hash this file.
+
+<Note>
+What does this step do?
+
+It hashes the file using [BLAKE3](https://en.wikipedia.org/wiki/BLAKE_(hash_function)) and remembers a so-called ["outboard"](https://github.com/oconnor663/bao?tab=readme-ov-file#outboard-mode) for that file.
+This outboard contains information about hashes of parts of this file.
+All of this enables some extra features with iroh-blobs like automatically verifying the integrity of the file *while it's streaming*, verified range downloads and download resumption.
+</Note>
+
+```rust
+let filename: PathBuf = filename.parse()?;
+let abs_path = std::path::absolute(&filename)?;
+
+println!("Hashing file.");
+
+// When we import a blob, we get back a "tag" that refers to said blob in the store
+// and allows us to control when/if it gets garbage-collected
+let tag = store.blobs().add_path(abs_path).await?;
+```
+
+<Note>
+For other use cases, there are other ways of importing blobs into iroh-blobs, you're not restricted to pulling them from the file system!
+You can see other options available, such as [`add_slice`](https://docs.rs/iroh-blobs/latest/iroh_blobs/api/blobs/struct.Blobs.html#method.add_slice).
+Make sure to also check out the options you can pass and their documentation for some interesting tidbits on performance.
+</Note>
+
+The return value `tag` contains the final piece of information such that another endpoint can fetch a blob from us.
+
+We'll use a `BlobTicket` to put the file's BLAKE3 hash and our endpoint's `EndpointId` into a single copy-able string:
+
+```rust
+let endpoint_id = endpoint.id();
+let ticket = BlobTicket::new(endpoint_id.into(), tag.hash, tag.format);
+
+println!("File hashed. Fetch this file by running:");
+println!(
+    "cargo run -- receive {ticket} {}",
+    filename.display()
+);
+```
+
+Now we've imported the file and produced instructions for how to fetch it, but we're actually not yet actively listening for incoming connections yet! (iroh-blobs won't do so unless you specifically tell it to do that.)
+
+For that we'll use iroh's `Router`.
+Similar to routers in webserver libraries, it runs a loop accepting incoming connections and routes them to the specific handler.
+However, instead of handlers being organized by HTTP paths, it routes based on "ALPNs".
+Read more about ALPNs and the router on the [protocol](/concepts/protocols) page.
+
+In our case, we only need a single protocol, but constructing a router also takes care of running the accept loop, so that makes our life easier:
+
+```rs
+// For sending files we build a router that accepts blobs connections & routes them
+// to the blobs protocol.
+let router = Router::builder(endpoint)
+    .accept(iroh_blobs::ALPN, blobs)
+    .spawn();
+
+tokio::signal::ctrl_c().await?;
+
+// Gracefully shut down the endpoint
+println!("Shutting down.");
+router.shutdown().await?;
+```
+
+And as you can see, as a final step we wait for the user to stop the file providing side by hitting `Ctrl+C` in the console and once they do so, we shut down the router gracefully.
+
+
+### Connecting to the other side to receive
+
+On the connection side, we got the `ticket` and the `path` from the CLI arguments and we can parse them into their `struct` versions.
+
+With them parsed
+- we first construct a `Downloader` (that can help us coordinate multiple downloads from multiple peers if we'd want to)
+- and then call `.download` with the information contained in the ticket and wait for the download to finish:
+
+<Note>
+Reusing the same downloader across multiple downloads can be more efficient, e.g. by reusing existing connections.
+In this example we don't see this, but it might come in handy for your use case.
+</Note>
+
+```rust
+let filename: PathBuf = filename.parse()?;
+let abs_path = std::path::absolute(filename)?;
+let ticket: BlobTicket = ticket.parse()?;
+
+// For receiving files, we create a "downloader" that allows us to fetch files
+// from other endpoints via iroh connections
+let downloader = store.downloader(&endpoint);
+
+println!("Starting download.");
+
+downloader
+    .download(ticket.hash(), Some(ticket.endpoint_addr().id)
+    .await?;
+
+println!("Finished download.");
+```
+
+<Note>
+The return value of `.download()` is [`DownloadProgress`](https://docs.rs/iroh-blobs/latest/iroh_blobs/api/downloader/struct.DownloadProgress.html).
+You can either `.await` it to wait for the download to finish, or you can stream out progress events instead, e.g. if you wanted to use this for showing a nice progress bar!
+</Note>
+
+As a final step, we'll export the file we just downloaded into our in-memory blobs database to the desired file path:
+
+```rust
+println!("Copying to destination.");
+
+store.blobs().export(ticket.hash(), abs_path).await?;
+
+println!("Finished copying.");
+```
+
+<Note>
+This first downloads the file completely into memory, then copies it from memory to file in a second step.
+
+There's ways to make this work without having to store the whole file in memory!
+This would involve setting up an `FsStore` instead of a `MemStore` and using `.export_with_opts` with `ExportMode::TryReference`.
+Something similar can be done on the sending side!
+We'll leave these changes as an exercise to the reader 😉
+</Note>
+
+Before we leave, we'll gracefully shut down our endpoint in the receive branch, too:
+
+```rs
+// Gracefully shut down the endpoint
+println!("Shutting down.");
+endpoint.close().await;
+```
+
+
+## That's it!
+
+You've now successfully built a small tool for peer-to-peer file transfers! 🎉
 
-- Keep message sizes appropriate for your transport; publish references to
-	large payloads and transfer the data via the blobs protocol.
-- Use HashSeq to represent sequences of blobs (e.g., chunked content).
-- Use the downloader utilities to aggregate sources and store results locally.
+The full example with the very latest version of iroh and iroh-blobs can be [viewed on github](https://github.com/n0-computer/iroh-blobs/blob/main/examples/transfer.rs).
 
+If you're hungry for more, check out
+- the [iroh rust documentation](https://docs.rs/iroh),
+- Video streaming with [iroh-roq](/protocols/streaming),
+- Writing your [own protocols](/protocols/writing-a-protocol.mdx),
+- [other examples](/examples), or
diff --git a/protocols/rpc.mdx b/protocols/rpc.mdx
@@ -2,15 +2,13 @@
 title: "RPC"
 ---
 
-## What is RPC?
-
 Remote Procedure Call (RPC) lets a program invoke functions hosted on another
 process or machine as if they were local, abstracting the transport so arguments
 and results travel over the network transparently.
 
 ## IRPC 
 
-[irpc]() is a lightweight rpc crate for iroh connections
+[irpc](https://docs.rs/irpc) is a lightweight rpc crate for creating RPC protocols over iroh connections.
 
 ### Installation
 
diff --git a/protocols/streaming.mdx b/protocols/streaming.mdx
@@ -1,5 +1,5 @@
 ---
-title: "Audio/Video Streaming"
+title: "Streaming"
 ---
 
 Streaming protocols in iroh enable efficient transfer of large or continuous
diff --git a/protocols/writing-a-protocol.mdx b/protocols/writing-a-protocol.mdx
diff --git a/quickstart.mdx b/quickstart.mdx

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@`
`18`	`18`	`"pages": [`
`19`	`19`	`"what-is-iroh",`
`20`	`20`	`"quickstart",`
	`21`	`+ "examples",`
`21`	`22`	`{`
`22`	`23`	`"group": "Concepts",`
`23`	`24`	`"expanded": true,`