iroh-go

WARNING Highly Experimental ™️

Go FFI bindings for iroh via iroh-ffi.

Motivation

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.

Version support

• iroh: v1.0.3
• iroh-ffi: v1.1.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

Examples

See examples.

Run your own iroh-relay

See iroh-relay if you want more small footprint static binary goodness. You can also make use of the upstream provided docker image: n0computer/iroh-relay.

Local hacking

First, run iroh-relay in development mode with noisy logging.

RUST_LOG=info,iroh_relay=debug ./iroh-relay --dev

You can then use http://localhost:3340 as the default location of your own relay in the construction of your endpoint as follows. Once you create an endpoint, you should see your relay respond locally with corresponding logs.

preset := iroh.PresetN0DisableRelay()
relay, _ := iroh.RelayModeCustomFromUrls([]string{"http://localhost:3340"})
opts := iroh.EndpointOptions{
    Preset:    &preset,
    RelayMode: &relay,
    // ...moar config...
}

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.

Licenses

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