From 08d67a0fd199e1dca603cd702b3f14961adf23e9 Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Wed, 17 Dec 2025 15:05:56 -0800 Subject: [PATCH] add info about ffi --- deployment/other-languages.mdx | 102 +++++++++++++++++++++++++++++++++ docs.json | 2 +- 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 deployment/other-languages.mdx diff --git a/deployment/other-languages.mdx b/deployment/other-languages.mdx new file mode 100644 index 0000000..9a96dd7 --- /dev/null +++ b/deployment/other-languages.mdx @@ -0,0 +1,102 @@ +--- +title: "Using Iroh in Other Languages" +--- + +While iroh is written in Rust, it can be used in many other languages and +environments. + +There are several practical approaches to using iroh in your language of choice: + +### Write a Wrapper + +If you're comfortable with a little bit of Rust, write your own small +wrapper around iroh that covers just what you need and exposes your application +specific functionality over a local http server or daemon. This approach: + +- Gives you full control over the functionality you expose +- Requires minimal Rust knowledge beyond basic CLI patterns +- Can be called from any language +- Check out [sendme](https://github.com/n0-computer/sendme), [callme](https://github.com/n0-computer/callme), and [dumbpipe](https://github.com/n0-computer/dumbpipe) as examples + +### Build Your Own FFI Wrapper + +Write your own FFI wrapper from Rust to your target language (Python, Go, etc.) +that covers just what you need from the iroh API and protocols. This gives you: + +- Complete control over the API surface +- The ability to tailor it to your specific use case +- Type-safe bindings for your language +- Reference [iroh-ffi](https://github.com/n0-computer/iroh-ffi) for patterns and examples + +### Community Bindings + +The community has built language bindings that are open source and available for use: + +**TypeScript/JavaScript**: [iroh-ts](https://github.com/rayhanadev/iroh-ts) - Community-maintained TypeScript bindings for iroh, enabling JavaScript and TypeScript developers to use iroh in their applications. + +### Professional Bindings Support + +The number0 engineering team can help you build and maintain production-grade +language-specific bindings. [Contact us](https://n0.computer) to discuss your +requirements. + + +## WebAssembly and Browsers + +Iroh can be compiled to WebAssembly for use in browsers! + +As of the iroh 0.33 release, iroh can be used in projects that compile to WebAssembly. +Add `iroh` to your browser project's dependencies and keep building it using [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen/). + +For end-to-end examples of integrating iroh into a browser page, see these examples on our [iroh-examples repository](https://github.com/n0-computer/iroh-examples): +- An [iroh echo server in the browser](https://github.com/n0-computer/iroh-examples/tree/main/browser-echo). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-echo/index.html) +- An [browser chat room UI](https://github.com/n0-computer/iroh-examples/tree/main/browser-chat) based on the [iroh gossip chat example](/examples/chat). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-chat/index.html) + +### Browser Limitations + +When you're in a browser context - as opposed to in a native app or on desktop, you're in a strict "sandbox" that disallows a few things iroh relies upon, e.g. sending UDP packets directly. +Thus, we need to work around these limitations and can't provide you with the full magic of iroh just yet. + +We envision that most applications will use iroh browser support as an additional feature to complement existing deployments to desktops, native apps or servers, where they'll be able to make use of everything that iroh offers. + +**No direct connections**: All connections from browsers to somewhere else need to flow via a relay server. +This is because we can't port our hole-punching logic in iroh to browsers: They don't support sending UDP packets to IP addresses from inside the browser sandbox. + +Keep in mind that *connections are end-to-end encrypted*, as always with iroh. +So even though traffic from browsers is always relayed, it can't be decrypted by the relay. + +There are other ways of getting direct connections going, such as WebTransport +with `serverCertificateHashes`, or WebRTC. We may expand iroh's browser support +to make use of these to try to generate direct connections even when a browser +node is involved in the connection. + +**`iroh` crate features**: As of iroh version 0.33, you need to disable all optional features on iroh for the Wasm build to succeed. +To do so, depend on iroh via `iroh = { version = "0.33", default-features = false }`. +This will install a version of iroh with default features, except it doesn't track `metrics` locally. +We'll get rid of this limitation very soon (likely with iroh version 0.34). +Non-default features like `discovery-local-network` or `discovery-dht` will likely never be available in browsers, unless browser APIs making them possible are added. + +**npm package**: Currently we don't bundle iroh's Wasm build as an NPM package. +There is no technical limitation for this: You could build this today! +Should you need javascript APIs, we recommend that you write an application-specific rust wrapper crate that depends on iroh and exposes whatever the javascript side needs via [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen/). + +### Use in node.js/bun.js/deno + +We check that the browser version of iroh works in node.js regularly. +And it's likely that Deno will work out of the box, too, given it closely resembles the browser's Web APIs. +We haven't checked if bun.js works right now, and don't have plans to check that continually. + +As these runtimes are outside the browser sandbox, it would technically be possible to ship bigger parts of iroh to these environments, such as all hole-punching related functionality. +However, we currently don't plan to expand the browser-related WebAssembly work to integrate with that. +In the future, it's more likely we'll use [NAPI](https://napi.rs) or [WASI](https://wasi.dev/) to make these integrations possible. + +### Troubleshooting WebAssembly Builds + +Getting rust code to successfully build for browsers can be tricky. +We've started a [discussion on github](https://github.com/n0-computer/iroh/discussions/3200) to collect common issues hit when trying to compile iroh or projects using iroh to WebAssembly. +Take a look at answers in that discussion for any clues if you're encountering build issues. +Otherwise feel free to open a discussion or a thread on that discussion with your specific issue. + +## Contributing + +If you're interested in creating or maintaining bindings for other languages, we'd love to hear from you! Join the [iroh Discord](https://www.iroh.computer/discord) to connect with the community. diff --git a/docs.json b/docs.json index 527251d..237c77b 100644 --- a/docs.json +++ b/docs.json @@ -63,7 +63,7 @@ "deployment/metrics", "deployment/security-privacy", "deployment/troubleshooting", - "deployment/wasm-browser-support" + "deployment/other-languages" ] }, {