`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.

Platform support

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

Documentation

See docs.rs for the original Rust API documentation. The exposed Go API is 1:1. Here's the Go bindings documentation on godocs.io.

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?

iroh-tracker

Known issues

We need to patch the upstream iroh-ffi endpoint.rs to fix an incompatibility with uniffi-bindgen-go. See this commit for more.
We need to patch the upstream iroh-ffi Cargo.toml to remove the crate-type configuration when runnings builds here. See this commit for more.
Error handling is extremely inconvenient due to iroh-ffi#263. Proposals for improvement are very welcome.

Licenses

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

3.1 KiB Raw Permalink Blame History

iroh-go