Skip to content

Commit 678be99

Browse files
okdistributeokdistribute
committed
add more pages
1 parent 98e3f0b commit 678be99

File tree

4 files changed

+549
-8
lines changed

4 files changed

+549
-8
lines changed

‎deployment/iroh-doctor.mdx‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,29 @@
22
title: "iroh doctor"
33
---
44

5-
Placeholder: Troubleshooting and diagnostic tool usage (iroh doctor).
5+
[iroh doctor](https://github.com/n0-computer/iroh-doctor) is a command-line tool that helps you diagnose network connectivity issues with your iroh setup.
6+
7+
## Installation
8+
9+
```
10+
cargo install iroh-doctor
11+
```
612

713
## Home Relay
814

9-
All iroh endpoints will maintain a single home relay server that they're reachable at. On startup iroh will probe its configured relays & choose the one with the lowest latency.
15+
All iroh endpoints will maintain a single home relay server that they're
16+
reachable at. On startup iroh will probe its configured relays & choose the one
17+
with the lowest latency.
1018

11-
You can see this in action with [iroh doctor](https://github.com/n0-computer/iroh-doctor):
19+
Report on the current network environment, using either an explicitly provided
20+
stun host or the settings from the config file by using `iroh-doctor report`.
1221

1322
```shell
14-
$ iroh-doctor report
23+
iroh-doctor report
24+
```
25+
26+
An example output looks like this:
27+
```
1528
getting report using relay map RelayMap {
1629
nodes: {
1730
RelayUrl(

‎deployment/wasm-browser-support.mdx‎

Lines changed: 70 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,73 @@
11
---
2-
title: "WASM / Browser support"
2+
title: "WebAssembly and Browsers"
33
---
44

5-
Placeholder: Notes on running iroh in WASM and browser environments.
5+
6+
Iroh can be compiled to WebAssembly for use in browsers!
7+
8+
We first announced work on iroh in browsers via WebAssembly in a [blog post](/blog/iroh-and-the-web).
9+
As of the iroh 0.33 release, iroh can be used in projects that compile to WebAssembly.
10+
Add `iroh` to your browser project's dependencies and keep building it using [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen/).
11+
12+
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):
13+
- 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)
14+
- An [browser chat room UI](https://github.com/n0-computer/iroh-examples/tree/main/browser-chat) based on the [iroh gossip chat example](/docs/examples/gossip-chat). Check it out [in action](https://n0-computer.github.io/iroh-examples/main/browser-chat/index.html)
15+
16+
17+
## Limitations
18+
19+
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.
20+
Thus, we need to work around these limitations and can't provide you with the full magic of iroh just yet.
21+
22+
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.
23+
24+
### No direct connections
25+
26+
**All connections from browsers to somewhere else need to flow via a relay server**.
27+
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.
28+
29+
Keep in mind that *connections are end-to-end encrypted*, as always with iroh.
30+
So even though traffic from browsers is always relayed, it can't be decrypted by the relay.
31+
32+
There are other ways of getting peer-to-peer connections going, such as WebTransport with `serverCertificateHashes`, or WebRTC.
33+
We may expand iroh's browser support to make use of these to try to generate fully peer-to-peer connections even when a browser node is involved in the connection.
34+
35+
### `iroh` crate features
36+
37+
As of iroh version 0.33, you need to disable all optional features on iroh for the Wasm build to succeed.
38+
To do so, depend on iroh via `iroh = { version = "0.33", default-features = false }`.
39+
This will install a version of iroh with default features, except it doesn't track `metrics` locally.
40+
We'll get rid of this limitation very soon (likely with iroh version 0.34).
41+
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.
42+
43+
### npm package
44+
45+
Currently we don't bundle iroh's Wasm build as an NPM package.
46+
There is no technical limitation for this: You could build this today!
47+
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/).
48+
49+
### Use in node.js/bun.js/deno
50+
51+
We check that the browser version of iroh works in node.js regularly.
52+
And it's likely that Deno will work out of the box, too, given it closely resembles the browser's Web APIs.
53+
We haven't checked if bun.js works right now, and don't have plans to check that continually.
54+
55+
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.
56+
However, we currently don't plan to expand the browser-related WebAssembly work to integrate with that.
57+
In the future, it's more likely we'll use [NAPI](https://napi.rs) or [WASI](https://wasi.dev/) to make these integrations possible.
58+
If you want to try this today, take a look at our existing code at [iroh-ffi](https://github.com/n0-computer/iroh-ffi/) and feel free to adapt it to your needs or newer iroh versions.
59+
60+
61+
## Troubleshooting
62+
63+
Getting rust code to successfully build for browsers can be tricky.
64+
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.
65+
Take a look at answers in that discussion for any clues if you're encountering build issues.
66+
Otherwise feel free to open a discussion or a thread on that discussion with your specific issue.
67+
68+
69+
## Future Plans
70+
71+
We're expanding browser support from the iroh crate to our off-the-shelf protocols.
72+
[iroh-gossip](https://www.iroh.computer/proto/iroh-gossip) already supports being built for browsers starting with version 0.33.
73+

‎protocols/automerge.mdx‎

Lines changed: 94 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,97 @@
22
title: "Automerge"
33
---
44

5-
Placeholder: Integrating Automerge and CRDT interoperability notes.
5+
Automerge is a Conflict-Free Replicated Data Type (CRDT). It represents
6+
JSON-like data that can be efficiently synchronized between
7+
machines without needing a single source of truth, unlike traditional databases.
8+
This enables machine to simply gossip updates and data with each other,
9+
eventually converging to the same state on every replica.
10+
11+
## Example
12+
13+
This example highlights how to integrate [automerge's sync protocol] with
14+
[iroh's peer-to-peer connectivity].
15+
16+
17+
```bash
18+
git clone https://github.com/n0-computer/iroh-examples
19+
cd iroh-examples/iroh-automerge
20+
```
21+
22+
First, we create one endpoint that listens for sync requests using iroh's
23+
connections:
24+
25+
```sh
26+
# First Terminal
27+
> cargo run
28+
Running
29+
Endpoint Id: lkpz2uw6jf7qahl7oo6qc46qad5ysszhtdzqyotkb3pwtd7sv3va
30+
```
31+
32+
You can exchange this public key with anyone to establish a secure, encrypted
33+
connection anywhere. In most cases this connection is even automatically
34+
upgraded to a direct peer-to-peer connection.
35+
36+
Now, let's start another endpoint in the second terminal that will connect to the
37+
first endpoint:
38+
39+
```sh
40+
# Second Terminal
41+
> cargo run -- --remote-id lkpz2uw6jf7qahl7oo6qc46qad5ysszhtdzqyotkb3pwtd7sv3va
42+
Running
43+
Endpoint Id: gcq5e7mcsvwgtxfvbu7w7rkikxhfudbqt5yvl34f47qlmsyuy7wa
44+
>
45+
```
46+
47+
This will connect the two endpoints, have them exchange data and finish running
48+
within a couple of seconds.
49+
50+
Coming back to the first terminal, we'll see that the receiving end got all data:
51+
52+
```sh
53+
# Back on the first Terminal
54+
State
55+
key-0 => "value-0"
56+
key-1 => "value-1"
57+
key-2 => "value-2"
58+
key-3 => "value-3"
59+
key-4 => "value-4"
60+
```
61+
62+
## How it works
63+
64+
65+
First, we write a protocol wrapper for the Automerge sync protocol.
66+
67+
This code exposes a small iroh protocol handler that synchronizes an Automerge
68+
Document between two peers over a bi-directional stream. It uses Automerge's sync
69+
protocol messages, sent as length-prefixed binary frames, and drives a sync loop
70+
until both sides report “done.” Notifies the rest of the program when sync
71+
finishes by sending the final Automerge document over an mpsc channel.
72+
73+
During sync, the dialer opens a bidirectional stream, repeatedly generates
74+
Automerge sync messages, sends them, receives the peer’s response, integrates
75+
any remote changes, and terminates when both sides report completion. The
76+
responder follows the same loop but waits for the connection to close, ensuring
77+
both replicas converge and the final document is sent through the sync_finished
78+
channel.
79+
80+
- `initiate_sync` runs the sync loop for the dialing side: it opens a bidirectional
81+
stream, repeatedly emits Automerge sync messages (length-prefixed) while
82+
consuming messages from the peer, merges remote changes into the shared doc, and
83+
exits once both sides have no more data, finally closing the connection.
84+
- `respond_sync` mirrors the loop for the accepting side, waiting for the peer to
85+
close. The protocol handler’s accept entry point delegates to respond_sync,
86+
converts errors into AcceptError.
87+
- On successful completion, it sends a forked copy of the synchronized document
88+
through the provided channel so other components can observe the finished state.
89+
- `send_msg` and `recv_msg` implement the wire format for Automerge sync messages
90+
on top of iroh’s QUIC streams by prefixing each serialized message with its
91+
length. A zero-length frame indicates that the sender has no data to transmit in
92+
that round.
93+
94+
95+
## Learn more
96+
- [iroh-automerge example source code on Github](https://github.com/n0-computer/iroh-examples/blob/main/iroh-automerge/src/protocol.rs)
97+
- [automerge's sync protocol](https://docs.rs/automerge/latest/automerge/sync/)
98+
- [iroh's peer-to-peer connectivity](https://docs.rs/iroh/latest/iroh/net/index.html)

0 commit comments

Comments
 (0)