The goal is to provide, as far as possible, seamless "just go build it" support for Go iroh hackers without requiring them to deal with shared libraries, the Rust toolchain or a deepdive in how FFI works. The current approach is to embed libiroh as a staticlib built with Rust for each platform. We use musl to avoid glibc incompatibilities on different linux systems. It's then possible to build a static binary with go build or with Zig. iroh-go does require CGO_ENABLED=1.

Approach

iroh-go is generated directly from iroh-ffi guaranteeing compatibility and long-term alignment with upstream. Some API wrappers are implemented to smooth over some of the unavoidable rough edges of FFI binding generation. This is a different approach than e.g. go-iroh which is a custom port.

Version support

iroh: v1.0.0
iroh-ffi: v1.2.0

Platform support

Note

More platform can be provided on request and pending some support to build binaries for specific architectures. If you would like to help out, please let us know! See #8 and #9 for more.

x86_64-unknown-linux-musl
aarch64-unknown-linux-musl

Documentation

Original Rust API: docs.rs
Go bindings: godocs.io
Community bindings docs: docs.iroh.computer
Resources for grokking connection shutdown: iroh.computer/blog/closing-a-quic-connection, echo.rs and listen.rs. Also see RecvStream and SendStream.

Examples

See examples. Some of them use the API wrapper, and some of them use the low-level API bindings. We're still experimenting. See also the upstream examples (in Rust) for inspiration.

Generate bindings

See iroh-go for the Rust toolchain configuration. Run ./scripts/generate.sh to build a new set of libraries which end up vendored in libs.

Who is using it?

Note

Please add your own if you're using iroh-go 🙏

iroh-tracker

Known issues

We patched the upstream iroh-ffi endpoint.rs to fix an incompatibility with uniffi-bindgen-go. See this commit for more.
We patched the upstream iroh-ffi Cargo.toml to remove the crate-type configuration when runnings builds here. See this commit for more.
Error handling is not super ergonomic due to iroh-ffi#263. We have created an error handling wrapper API which is documented in ./examples/errors to improve on the situation.
Some interfaces such as conn.Closed() and endpoint.Online() should ideally expose a send/receive channel interface but instead work as a blocking call (where .await() is called internally).

Licenses

Apache 2.0 & MIT, following the upstream licensing choices in iroh-ffi.

Contributing

CONTRIBUTING.md.