Skip to content

Commit 004eaa5

Browse files
committed
Merge branch 'main' into blobs-1g-test
2 parents 18b31d5 + 29f0591 commit 004eaa5

File tree

2 files changed

+49
-1
lines changed

2 files changed

+49
-1
lines changed

README.md

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ request blobs or ranges of blobs, as well as collections.
77

88
The requester opens a quic stream to the provider and sends the request. The provider answers with the requested data, encoded as [blake3](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf) verified streams, on the same quic stream.
99

10-
This crate is usually used together with [iroh-net](https://crates.io/crates/iroh-net), but can also be used with normal [quinn](https://crates.io/crates/quinn) connections. Connection establishment is left up to the user or a higher level APIs such as the iroh CLI.
10+
This crate is usually used together with [iroh](https://crates.io/crates/iroh), but can also be used with normal [quinn](https://crates.io/crates/quinn) connections. Connection establishment is left up to the user or a higher level APIs such as the iroh CLI.
1111

1212
## Concepts
1313

@@ -21,6 +21,53 @@ This crate is usually used together with [iroh-net](https://crates.io/crates/iro
2121

2222
- **Requester:** The side that asks for data. It is initiating requests to one or many providers.
2323

24+
25+
## Getting started
26+
27+
The `iroh-blobs` protocol was designed to be used in conjunction with `iroh`. [Iroh](https://docs.rs/iroh) is a networking library for making direct connections, these connections are what power the data transfers in `iroh-blobs`.
28+
29+
Iroh provides a [`Router`](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html) that takes an [`Endpoint`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html) and any protocols needed for the application. Similar to a router in webserver library, it runs a loop accepting incoming connections and routes them to the specific protocol handler, based on `ALPN`.
30+
31+
Here is a basic example of how to set up `iroh-blobs` with `iroh`:
32+
33+
```rust
34+
use iroh::{protocol::Router, Endpoint};
35+
use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool};
36+
37+
#[tokio::main]
38+
async fn main() -> anyhow::Result<()> {
39+
// create an iroh endpoint that includes the standard discovery mechanisms
40+
// we've built at number0
41+
let endpoint = Endpoint::builder().discovery_n0().bind().await?;
42+
43+
// spawn a local pool with one thread per CPU
44+
// for a single threaded pool use `LocalPool::single`
45+
let local_pool = LocalPool::default();
46+
47+
// create an in-memory blob store
48+
// use `iroh_blobs::net_protocol::Blobs::persistent` to load or create a
49+
// persistent blob store from a path
50+
let blobs = Blobs::memory().build(local_pool.handle(), &endpoint);
51+
52+
// turn on the "rpc" feature if you need to create blobs and tags clients
53+
let blobs_client = blobs.client();
54+
let tags_client = blobs_client.tags();
55+
56+
// build the router
57+
let router = Router::builder(endpoint)
58+
.accept(iroh_blobs::ALPN, blobs.clone())
59+
.spawn()
60+
.await?;
61+
62+
// do fun stuff with the blobs protocol!
63+
// make sure not to drop the local_pool before you are finished
64+
router.shutdown().await?;
65+
drop(local_pool);
66+
drop(tags_client);
67+
Ok(())
68+
}
69+
```
70+
2471
## Examples
2572

2673
Examples that use `iroh-blobs` can be found in the `iroh` crate. the iroh crate publishes `iroh_blobs` as `iroh::bytes`.

src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
#![doc = include_str!("../README.md")]
12
//! Blobs layer for iroh.
23
//!
34
//! The crate is designed to be used from the [iroh] crate, which provides a

0 commit comments

Comments
 (0)