Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/n0-computer/iroh
A toolkit for building distributed applications
https://github.com/n0-computer/iroh
content-addressed does-anyone-read-these memes object-store realtime rust sync tags tagsoftags
Last synced: 4 days ago
JSON representation
A toolkit for building distributed applications
- Host: GitHub
- URL: https://github.com/n0-computer/iroh
- Owner: n0-computer
- License: apache-2.0
- Created: 2022-03-14T19:30:08.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-08T18:14:44.000Z (about 1 month ago)
- Last Synced: 2024-11-10T09:19:10.225Z (about 1 month ago)
- Topics: content-addressed, does-anyone-read-these, memes, object-store, realtime, rust, sync, tags, tagsoftags
- Language: Rust
- Homepage: https://iroh.computer
- Size: 84.4 MB
- Stars: 2,565
- Watchers: 35
- Forks: 161
- Open Issues: 164
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: code_of_conduct.md
Awesome Lists containing this project
- awesome-repositories - n0-computer/iroh - A toolkit for building distributed applications (Rust)
- awesome-starred - n0-computer/iroh - Bytes, distributed. (rust)
README
less net work for networks
[](https://docs.rs/iroh/)
[](https://crates.io/crates/iroh)
[](https://crates.io/crates/iroh)
[](https://discord.com/invite/DpmJgtU7cW)
[](https://www.youtube.com/@n0computer)
[](LICENSE-MIT)
[](LICENSE-APACHE)
[](https://github.com/n0-computer/iroh/actions/workflows/ci.yml)
## What is iroh?
Iroh gives you an API for dialing by public key.
You say “connect to that phone”, iroh will find & maintain the fastest connection for you, regardless of where it is.
### Hole-punching
The fastest route is a direct connection, so if necessary, iroh tries to hole-punch.
Should this fail, it can fall back to an open ecosystem of public relay servers.
To ensure these connections are as fast as possible, we [continuously measure iroh][iroh-perf].
### Built on [QUIC]
Iroh uses [Quinn] to establish [QUIC] connections between nodes.
This way you get authenticated encryption, concurrent streams with stream prioirities, a datagram transport and avoid head-of-line-blocking out of the box.
## Compose Protocols
Use pre-existing protocols built on iroh instead of writing your own:
- [iroh-blobs] for [BLAKE3]-based content-addressed blob transfer scaling from kilobytes to terrabytes
- [iroh-gossip] for establishing publish-subscribe overlay networks that scale, requiring only resources that your average phone can handle
- [iroh-docs] for an eventually-consistent key-value store of [iroh-blobs] blobs
- [iroh-willow] for an (in-construction) implementation of the [willow protocol]
## Getting Started
### Rust Library
It's easiest to use iroh from rust.
Install it using `cargo add iroh`, then on the connecting side:
```rs
const ALPN: &[u8] = b"iroh-example/echo/0";
let endpoint = Endpoint::builder().discovery_n0().bind().await?;
// Open a connection to the accepting node
let conn = endpoint.connect(addr, ALPN).await?;
// Open a bidirectional QUIC stream
let (mut send, mut recv) = conn.open_bi().await?;
// Send some data to be echoed
send.write_all(b"Hello, world!").await?;
send.finish()?;
// Receive the echo
let response = recv.read_to_end(1000).await?;
assert_eq!(&response, b"Hello, world!");
// Close the endpoint and all its connections
endpoint.close().await?;
```
And on the accepting side:
```rs
let endpoint = Endpoint::builder().discovery_n0().bind().await?;
let router = Router::builder(endpoint)
.accept(ALPN.to_vec(), Arc::new(Echo))
.spawn()
.await?;
// The protocol definition:
#[derive(Debug, Clone)]
struct Echo;
impl ProtocolHandler for Echo {
fn accept(self: Arc, connecting: Connecting) -> BoxedFuture> {
Box::pin(async move {
let connection = connecting.await?;
let (mut send, mut recv) = connection.accept_bi().await?;
// Echo any bytes received back directly.
let bytes_sent = tokio::io::copy(&mut recv, &mut send).await?;
send.finish()?;
connection.closed().await;
Ok(())
})
}
}
```
The full example code with more comments can be found at [`echo.rs`][echo-rs].
Or use one of the pre-existing protocols, e.g. [iroh-blobs] or [iroh-gossip].
### Other Languages
If you want to use iroh from other languages, make sure to check out [iroh-ffi], the repository for FFI bindings.
### Links
- [Introducing Iroh (video)][iroh-yt-video]
- [Iroh Documentation][docs]
- [Iroh Examples]
- [Iroh Experiments]
## Repository Structure
This repository contains a workspace of crates:
- `iroh`: The core library for hole-punching & communicating with relays.
- `iroh-relay`: The relay server implementation. This is the code we run in production (and you can, too!).
- `iroh-base`: Common types like `Hash`, key types or `RelayUrl`.
- `iroh-test`: Test utilities.
- `iroh-dns-server`: DNS server implementation powering the `n0_discovery` for NodeIds, running at dns.iroh.link.
- `iroh-net-report`: Analyzes your host's networking ability & NAT.
## License
Copyright 2024 N0, INC.
This project is licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
http://opensource.org/licenses/MIT)
at your option.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
[QUIC]: https://en.wikipedia.org/wiki/QUIC
[BLAKE3]: https://github.com/BLAKE3-team/BLAKE3
[Quinn]: https://github.com/quinn-rs/quinn
[iroh-blobs]: https://github.com/n0-computer/iroh-blobs
[iroh-gossip]: https://github.com/n0-computer/iroh-gossip
[iroh-docs]: https://github.com/n0-computer/iroh-docs
[iroh-willow]: https://github.com/n0-computer/iroh-willow
[iroh-doctor]: https://github.com/n0-computer/iroh-doctor
[willow protocol]: https://willowprotocol.org
[iroh-ffi]: https://github.com/n0-computer/iroh-ffi
[iroh-yt-video]: https://www.youtube.com/watch?v=RwAt36Xe3UI_
[Iroh Examples]: https://github.com/n0-computer/iroh-examples
[Iroh Experiments]: https://github.com/n0-computer/iroh-experiments
[echo-rs]: /iroh-router/examples/echo.rs
[iroh-perf]: https://perf.iroh.computer
[docs]: https://iroh.computer/docs