docs: add "getting started" instructions to the readme (#32)

* docs: add `INSTALL.md` with "getting started" instructions

* remove INSTALL.md, move content to README.md

* add example from readme as separate example

---------

Co-authored-by: “ramfox” <“kasey@n0.computer”>
Co-authored-by: Ruediger Klaehn <rklaehn@protonmail.com>

Cargo.toml

@@ -151,6 +151,10 @@ required-features = ["example-iroh"]
 name = "custom-protocol"
 required-features = ["example-iroh"]
 
+[[example]]
+name = "setup"
+required-features = ["example-iroh"]
+
 [lints.rust]
 missing_debug_implementations = "warn"
 

README.md

@@ -7,7 +7,7 @@ request blobs or ranges of blobs, as well as collections.
 
 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.
 
-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.
+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.
 
 ## Concepts
 
@@ -21,6 +21,53 @@ This crate is usually used together with [iroh-net](https://crates.io/crates/iro
 
 - **Requester:** The side that asks for data. It is initiating requests to one or many providers.
 
+
+## Getting started
+
+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`.
+
+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`.
+
+Here is a basic example of how to set up `iroh-blobs` with `iroh`:
+
+```rust
+use iroh::{protocol::Router, Endpoint};
+use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // create an iroh endpoint that includes the standard discovery mechanisms
+    // we've built at number0
+    let endpoint = Endpoint::builder().discovery_n0().bind().await?;
+
+    // spawn a local pool with one thread per CPU
+    // for a single threaded pool use `LocalPool::single`
+    let local_pool = LocalPool::default();
+
+    // create an in-memory blob store
+    // use `iroh_blobs::net_protocol::Blobs::persistent` to load or create a
+    // persistent blob store from a path
+    let blobs = Blobs::memory().build(local_pool.handle(), &endpoint);
+
+    // turn on the "rpc" feature if you need to create blobs and tags clients
+    let blobs_client = blobs.client();
+    let tags_client = blobs_client.tags();
+
+    // build the router
+    let router = Router::builder(endpoint)
+        .accept(iroh_blobs::ALPN, blobs.clone())
+        .spawn()
+        .await?;
+
+    // do fun stuff with the blobs protocol!
+    // make sure not to drop the local_pool before you are finished
+    router.shutdown().await?;
+    drop(local_pool);
+    drop(tags_client);
+    Ok(())
+}
+```
+
 ## Examples
 
 Examples that use `iroh-blobs` can be found in the `iroh` crate. the iroh crate publishes `iroh_blobs` as `iroh::bytes`.

examples/setup.rs

@@ -0,0 +1,35 @@
+use iroh::{protocol::Router, Endpoint};
+use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // create an iroh endpoint that includes the standard discovery mechanisms
+    // we've built at number0
+    let endpoint = Endpoint::builder().discovery_n0().bind().await?;
+
+    // spawn a local pool with one thread per CPU
+    // for a single threaded pool use `LocalPool::single`
+    let local_pool = LocalPool::default();
+
+    // create an in-memory blob store
+    // use `iroh_blobs::net_protocol::Blobs::persistent` to load or create a
+    // persistent blob store from a path
+    let blobs = Blobs::memory().build(local_pool.handle(), &endpoint);
+
+    // turn on the "rpc" feature if you need to create blobs and tags clients
+    let blobs_client = blobs.client();
+    let tags_client = blobs_client.tags();
+
+    // build the router
+    let router = Router::builder(endpoint)
+        .accept(iroh_blobs::ALPN, blobs.clone())
+        .spawn()
+        .await?;
+
+    // do fun stuff with the blobs protocol!
+    // make sure not to drop the local_pool before you are finished
+    router.shutdown().await?;
+    drop(local_pool);
+    drop(tags_client);
+    Ok(())
+}

src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 //! Blobs layer for iroh.
 //!
 //! The crate is designed to be used from the [iroh] crate, which provides a