diff --git a/docs/architecture/event-targets.md b/docs/architecture/event-targets.md index 91b0610..ec7ef63 100644 --- a/docs/architecture/event-targets.md +++ b/docs/architecture/event-targets.md @@ -65,5 +65,5 @@ This is analogous to Redis's `SUBSCRIBE`/`UNSUBSCRIBE` commands — control mess | [WebSocket Client](websocket-client.md) | `@alkdev/pubsub/event-target-websocket-client` | Not yet implemented | | [WebSocket Server](websocket-server.md) | `@alkdev/pubsub/event-target-websocket-server` | Not yet implemented | | [Worker](worker.md) | `@alkdev/pubsub/event-target-worker` | Not yet implemented (R&D on Node vs Web Worker) | -| [Iroh Spoke](iroh-spoke.md) | `@alkdev/pubsub/event-target-iroh-spoke` | Not yet implemented (R&D on binding) | -| [Iroh Hub](iroh-hub.md) | `@alkdev/pubsub/event-target-iroh-hub` | Not yet implemented (R&D on binding) | \ No newline at end of file +| [Iroh Spoke](iroh-spoke.md) | `@alkdev/pubsub/event-target-iroh-spoke` | Deferred (pending fork of iroh-ts) | +| [Iroh Hub](iroh-hub.md) | `@alkdev/pubsub/event-target-iroh-hub` | Deferred (pending fork of iroh-ts) | \ No newline at end of file diff --git a/docs/architecture/event-targets/iroh-hub.md b/docs/architecture/event-targets/iroh-hub.md index 23bb5ea..124c06d 100644 --- a/docs/architecture/event-targets/iroh-hub.md +++ b/docs/architecture/event-targets/iroh-hub.md @@ -6,8 +6,8 @@ last_updated: 2026-05-08 # Iroh Hub Event Target **Import**: `@alkdev/pubsub/event-target-iroh-hub` -**Peer dep**: `@rayhanadev/iroh` (optional, NAPI-RS native addon) -**Status**: Not yet implemented. Needs R&D on binding stability, NAPI under Deno. +**Peer dep**: `@alkdev/iroh` (optional, NAPI-RS native addon — pending fork of iroh-ts) +**Status**: Deferred. Pending fork of iroh-ts with Linux + WASM platform targets. P2P QUIC event target for the hub (server) side. The hub accepts incoming connections and bidirectional streams. Manages multiple connected spokes. @@ -78,7 +78,7 @@ dispatchEvent(event) { ## R&D Needed -1. **Binding stability** — same as spoke adapter. `@rayhanadev/iroh` needs testing. +1. **Fork of iroh-ts** — same as spoke adapter. Pending fork as `@alkdev/iroh`. 2. **Concurrent accept** — can `endpoint.accept()` handle multiple simultaneous connections? 3. **Stream vs. Connection per spoke** — current design: one bidirectional stream per spoke on a single connection. Alternative: one connection per spoke. Need to benchmark which is better for the expected workload. 4. **iroh-gossip** — for true broadcast to many spokes, `iroh-gossip` would be more efficient than per-spoke streams. Not yet available in TS. The current subscription-tracked fan-out design works for moderate fan-out; gossip would be an optimization for very large fan-out later. diff --git a/docs/architecture/event-targets/iroh-spoke.md b/docs/architecture/event-targets/iroh-spoke.md index 5908e31..1fb76b0 100644 --- a/docs/architecture/event-targets/iroh-spoke.md +++ b/docs/architecture/event-targets/iroh-spoke.md @@ -6,8 +6,8 @@ last_updated: 2026-05-08 # Iroh Spoke Event Target **Import**: `@alkdev/pubsub/event-target-iroh-spoke` -**Peer dep**: `@rayhanadev/iroh` (optional, NAPI-RS native addon) -**Status**: Not yet implemented. Needs R&D on binding stability and Deno/NAPI compatibility. +**Peer dep**: `@alkdev/iroh` (optional, NAPI-RS native addon — pending fork of iroh-ts) +**Status**: Deferred. Pending fork of iroh-ts with Linux + WASM platform targets. P2P QUIC event target for the spoke (client) side. The spoke initiates the connection and opens the bidirectional stream. @@ -70,9 +70,8 @@ Control events use the existing `EventEnvelope` format: ## R&D Needed -1. **Binding stability** — `@rayhanadev/iroh` has one author and no tests. API surface is small (10 methods) but needs validation. -2. **NAPI under Deno** — NAPI-RS `.node` binaries need testing under Deno 2.x. -3. **Stream multiplexing** — multiple `openBi()` streams on one connection vs. single stream with multiplexed events. Single stream + JSON framing is simpler. -4. **Reconnection** — `RecvStream.readExact()` throws on connection close. Need to propagate this to listeners and support reconnect. +1. **Fork of iroh-ts** — `@rayhanadev/iroh` has one author and no tests. We plan to fork as `@alkdev/iroh` with Linux (NAPI-RS) + WASM platform targets. Windows and macOS native builds are deferred — cross-compilation from Linux is possible with NAPI but tricky, and macOS licensing is dubious for CI. Initial release: Linux native + WASM fallback. Adding other platforms is a future accessibility concern. +2. **Stream multiplexing** — multiple `openBi()` streams on one connection vs. single stream with multiplexed events. Single stream + JSON framing is simpler. +3. **Reconnection** — `RecvStream.readExact()` throws on connection close. Need to propagate this to listeners and support reconnect. See [../iroh-transport.md](../iroh-transport.md) for full protocol details, identity, and comparison with WebSocket. \ No newline at end of file diff --git a/docs/architecture/iroh-transport.md b/docs/architecture/iroh-transport.md index fe7c3de..b5cbff3 100644 --- a/docs/architecture/iroh-transport.md +++ b/docs/architecture/iroh-transport.md @@ -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. \ No newline at end of file +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. \ No newline at end of file