docs: add "Getting Started" to the README and add the readme to the d…

…ocs (#19)

* add "Getting Started" to the README and add the readme to the docs

* add readme code to an example

* add deny from other protos

---------

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

README.md

@@ -10,6 +10,36 @@ The `net` module connects the protocol to the networking stack from `iroh-net`.
 
 The `net` module is optional behind the `net` feature flag (enabled by default).
 
+# Getting Started
+
+The `iroh-gossip` 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 how gossip messages are sent.
+
+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-gossip` with `iroh`:
+```rust
+use iroh::{protocol::Router, Endpoint};
+use iroh_gossip::{net::Gossip, ALPN};
+
+#[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?;
+
+    // build gossip protocol
+    let gossip = Gossip::builder().spawn(endpoint.clone()).await?;
+
+    // setup router
+    let router = Router::builder(endpoint.clone())
+        .accept(ALPN, gossip.clone())
+        .spawn()
+        .await?;
+    // do fun stuff with the gossip protocol
+    router.shutdown().await?;
+    Ok(())
+}
+```
 
 # License
 

deny.toml

@@ -33,6 +33,7 @@ license-files = [
 [advisories]
 ignore = [
       "RUSTSEC-2024-0384", # unmaintained, no upgrade available
+      "RUSTSEC-2024-0421", # todo: remove when iroh gets updated
 ]
 
 [sources]

examples/setup.rs

@@ -0,0 +1,21 @@
+use iroh::{protocol::Router, Endpoint};
+use iroh_gossip::{net::Gossip, ALPN};
+
+#[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?;
+
+    // build gossip protocol
+    let gossip = Gossip::builder().spawn(endpoint.clone()).await?;
+
+    // setup router
+    let router = Router::builder(endpoint.clone())
+        .accept(ALPN, gossip.clone())
+        .spawn()
+        .await?;
+    // do fun stuff with the gossip protocol
+    router.shutdown().await?;
+    Ok(())
+}

src/lib.rs

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