n0-computer / iroh

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.

什么是 iroh？ Iroh 为你提供了一个通过公钥进行拨号的 API。你只需说“连接到那台手机”，iroh 就会为你寻找并维护最快的连接，无论它身在何处。

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.

打洞（Hole-punching） 最快的路径是直接连接，因此在必要时，iroh 会尝试进行 NAT 打洞。如果失败，它可以回退到开放的公共中继服务器生态系统。为了确保这些连接尽可能快，我们持续对 iroh 进行性能评估。

Built on QUIC Iroh uses noq to establish QUIC connections between endpoints. This way you get authenticated encryption, concurrent streams with stream priorities, a datagram transport and avoid head-of-line-blocking out of the box.

基于 QUIC 构建 Iroh 使用 noq 在端点之间建立 QUIC 连接。通过这种方式，你可以开箱即用地获得经过身份验证的加密、具有流优先级的并发流、数据报传输，并避免队头阻塞（head-of-line-blocking）。

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 terabytes
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 构建的现有协议，而不是编写自己的协议：

iroh-blobs：用于基于 BLAKE3 的内容寻址 blob 传输，可从千字节扩展到太字节。
iroh-gossip：用于建立可扩展的发布-订阅覆盖网络，仅需普通手机即可处理的资源。
iroh-docs：用于 iroh-blobs 的最终一致性键值存储。

Getting Started: Rust Library It’s easiest to use iroh from rust. Install it using cargo add iroh, then on the connecting side:

入门：Rust 库 使用 Rust 调用 iroh 是最简单的。使用 cargo add iroh 安装它，然后在连接端：

const ALPN: &[u8] = b"iroh-example/echo/0";
let endpoint = Endpoint::bind().await?;
// Open a connection to the accepting endpoint
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!");
// As the side receiving the last application data - say goodbye
conn.close(0u32.into(), b"bye!");
// Close the endpoint and all its connections
endpoint.close().await;

And on the accepting side:

而在接收端：

let endpoint = Endpoint::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 {
    async fn accept(&self, connection: Connection) -> Result<()> {
        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. Or use one of the pre-existing protocols, e.g. iroh-blobs or iroh-gossip.

完整的示例代码及更多注释可以在 echo.rs 中找到。或者使用现有的协议，例如 iroh-blobs 或 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.

其他语言 如果你想在其他语言中使用 iroh，请务必查看 iroh-ffi，这是用于 FFI 绑定的仓库。

Repository Structure This repository contains a workspace of crates:

iroh: The core library for hole-punching & communicating with relays.
iroh-relay: The relay client and server implementation. This is the code we run in production for the public relays (and you can, too!).
iroh-base: Common types like EndpointId or RelayUrl.
iroh-dns-server: DNS server implementation powering the DNS/Pkarr address lookup for EndpointIds, running at dns.iroh.link.

仓库结构 该仓库包含一个 crate 工作区：

iroh：用于打洞和与中继通信的核心库。
iroh-relay：中继客户端和服务器实现。这是我们在生产环境中为公共中继运行的代码（你也可以运行！）。
iroh-base：通用类型，如 EndpointId 或 RelayUrl。
iroh-dns-server：DNS 服务器实现，为 EndpointIds 提供 DNS/Pkarr 地址查找支持，运行在 dns.iroh.link。