alkdev/pubsub
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Mark Iroh adapters as deferred pending fork of iroh-ts

Browse Source 
Update peer dep from @rayhanadev/iroh to @alkdev/iroh. Document
platform strategy: Linux native + WASM fallback, Windows/macOS
deferred. Fix outdated single-import reference in iroh-transport.md
to split spoke/hub imports. Resolve binding stability and NAPI/Deno
R&D items as covered by the fork path.
This commit is contained in:
glm-5.1
2026-05-08 03:59:35 +00:00
parent bc0c2589c7
commit e60f0a1aa0
4 changed files with 22 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/architecture/iroh-transport.md
View File

@@ -1,14 +1,14 @@
---
status: draft
last_updated: 2026-05-01
last_updated: 2026-05-08
---
# Iroh Transport
P2P QUIC event target using iroh. More complex than the other transports due to NAT traversal, crypto identity, and byte-stream framing.
**Import**: `@alkdev/pubsub/event-target-iroh` (not yet implemented)
**Peer dep**: `@rayhanadev/iroh` (optional, NAPI-RS native addon)
**Import**: `@alkdev/pubsub/event-target-iroh-spoke` and `@alkdev/pubsub/event-target-iroh-hub` (not yet implemented)
**Peer dep**: `@alkdev/iroh` (optional, NAPI-RS native addon — pending fork of iroh-ts)
## Why Iroh
@@ -21,7 +21,13 @@ WebSocket requires the hub to have a publicly reachable address. Iroh solves:
## Iroh Binding
Using `@rayhanadev/iroh` (v0.1.1) as the NAPI-RS binding. Community binding, one author, no tests. It has everything needed for hub-spoke 1:1 bidirectional streams:
Using `@alkdev/iroh` (pending fork of `@rayhanadev/iroh`) as the NAPI-RS binding. The original `@rayhanadev/iroh` has one author and no tests — we plan to fork it with the following platform strategy:
- **Linux**: Native NAPI-RS `.node` binary (primary target)
- **WASM**: Fallback for other environments (browser, Deno)
- **Windows/macOS**: Deferred. Cross-compilation from Linux is possible with NAPI but tricky; macOS CI licensing is dubious. Adding these platforms is a future accessibility concern.
The API surface we use is small (10 methods):
| Method | Purpose |
|--------|---------|
@@ -135,6 +141,5 @@ For now, 1:1 connections are sufficient. The hub fans out to multiple spokes by
## Open Questions
1. **Binding stability** — `@rayhanadev/iroh` has one author and no tests. If it breaks, we may need to fork or write our own NAPI wrapper. Mitigation: the API surface we use is small (10 methods) and the binding is thin.
2. **NAPI under Deno** — NAPI-RS `.node` binaries need testing under Deno 2.x. Since we're building with tsup for npm, the runtime is Node.js.
3. **Datagram support** — `sendDatagram`/`readDatagram` could be used for fire-and-forget events (no response expected). Not needed for hub-spoke but could be useful for broadcast. Deferred.
1. **Fork of iroh-ts** — `@rayhanadev/iroh` has one author and no tests. We plan to fork as `@alkdev/iroh` with Linux native + WASM fallback. Windows and macOS native builds deferred. Mitigation: the API surface we use is small (10 methods) and the binding is thin.
2. **Datagram support** — `sendDatagram`/`readDatagram` could be used for fire-and-forget events (no response expected). Not needed for hub-spoke but could be useful for broadcast. Deferred.