pluto-rtc 0.0.2

package/wasm/pkg/README.md

@@ -0,0 +1,218 @@
+# iroh-wasm
+
+WASM bindings for [iroh](https://iroh.computer) that enable P2P networking in web browsers.
+
+This module compiles the iroh Rust library to WebAssembly, allowing browsers to participate in P2P file sharing without a backend server.
+
+## Architecture
+
+```
+Browser (Web App)
+    ↓
+WasmIrohConnection.ts (TypeScript)
+    ↓
+WASM Module (this crate)
+    ↓
+iroh crate (Rust networking)
+    ↓
+WebTransport (browser API)
+```
+
+## Features
+
+- **In-browser P2P**: No backend required for web clients
+- **QUIC over WebTransport**: Modern protocol for efficient data transfer
+- **Streaming API**: ReadableStream/WritableStream for large file transfers
+- **Node persistence** (future): Use IndexedDB for persistent identity
+
+## Build
+
+### Prerequisites
+- Rust toolchain
+- `wasm-pack` installed: `cargo install wasm-pack`
+- LLVM/Clang (for linking)
+
+### Build Command
+
+From the project root:
+```bash
+npm run build:wasm
+```
+
+Or manually:
+```bash
+cd src-tauri/iroh-wasm
+wasm-pack build --target web --out-dir ../../src/services/iroh/wasm/pkg
+```
+
+This generates:
+- `pkg/iroh_wasm_bg.wasm` - Compiled WebAssembly binary
+- `pkg/iroh_wasm.js` - JavaScript bindings
+- `pkg/iroh_wasm.d.ts` - TypeScript type definitions
+
+### Output Location
+
+The build outputs to `src/services/iroh/wasm/pkg/` (git-ignored) so the frontend can import it:
+
+```typescript
+import init, { IrohNode } from './wasm/pkg/iroh_wasm';
+```
+
+## Source Structure
+
+```
+src/
+├── lib.rs      # WASM entry point, exports
+├── node.rs     # IrohNode implementation
+└── stream.rs   # BiStream wrapper for QUIC streams
+```
+
+### lib.rs
+- Initializes wasm-bindgen
+- Exports `IrohNode` and `BiStream` types
+- Sets up panic hooks for debugging
+
+### node.rs
+**Type**: `IrohNode`
+
+Main WASM-exposed class that manages the iroh node instance.
+
+**Methods**:
+```rust
+impl IrohNode {
+    // Create new node (in-memory for now)
+    #[wasm_bindgen(constructor)]
+    pub async fn new() -> Result<IrohNode, JsValue>;
+
+    // Get local node ID
+    #[wasm_bindgen]
+    pub fn node_id(&self) -> String;
+
+    // Connect to remote peer
+    #[wasm_bindgen]
+    pub async fn connect(&self, endpoint_addr: String) 
+        -> Result<Connection, JsValue>;
+
+    // Accept incoming connection
+    #[wasm_bindgen]
+    pub async fn accept(&self) -> Result<Connection, JsValue>;
+
+    // Open bidirectional stream
+    #[wasm_bindgen]
+    pub async fn open_bi(&self) -> Result<BiStream, JsValue>;
+}
+```
+
+### stream.rs
+**Type**: `BiStream`
+
+Wraps iroh's bidirectional QUIC streams in browser-compatible streams.
+
+**Returns**:
+- `ReadableStream<Uint8Array>` - For receiving data
+- `WritableStream<Uint8Array>` - For sending data
+
+**Usage from TypeScript**:
+```typescript
+const stream = await connection.open_bi();
+const reader = stream.readable.getReader();
+const writer = stream.writable.getWriter();
+
+// Send data
+await writer.write(new Uint8Array([1, 2, 3]));
+
+// Receive data
+const { value, done } = await reader.read();
+```
+
+## Integration with Frontend
+
+### WasmIrohConnection.ts
+
+The TypeScript wrapper (`src/services/iroh/WasmIrohConnection.ts`) uses this WASM module:
+
+```typescript
+import init, { IrohNode } from './wasm/pkg/iroh_wasm';
+
+// Lazy load WASM
+await init();
+
+// Create singleton node
+const node = await IrohNode.new();
+
+// Get node ID
+const nodeId = node.node_id();
+
+// Connect to peer
+const connection = await node.connect(peerEndpointAddr);
+
+// Open stream
+const biStream = await connection.open_bi();
+```
+
+## Platform Differences
+
+| Feature | Desktop/Mobile (Tauri) | Web (WASM) |
+|---------|------------------------|------------|
+| Backend | Rust via Tauri commands | Direct WASM calls |
+| Storage | Persistent (filesystem) | In-memory |
+| Transport | QUIC over UDP | QUIC over WebTransport |
+| Performance | Native speed | Near-native |
+
+## Limitations
+
+### Current
+- **No persistence**: Node identity resets on page reload
+- **Memory-only**: No disk storage (by design for security)
+- **Single node**: One node per browser tab
+
+### Future Improvements
+1. **IndexedDB storage**: Persist node identity across sessions
+2. **Service Worker**: Background P2P even when page closed
+3. **Better error handling**: More descriptive errors from Rust→JS
+4. **Connection pooling**: Reuse connections across components
+
+## Debugging
+
+### Enable WASM logs:
+```typescript
+// In browser console
+localStorage.setItem('debug', 'iroh:*');
+```
+
+### Common Issues
+
+**"Memory access out of bounds"**
+- WASM memory exhausted
+- Try reducing concurrent connections/streams
+
+**"WebTransport not supported"**
+- Browser doesn't support WebTransport
+- Requires Chrome 97+, Edge 97+, or Opera 83+
+
+**"Module not found"**
+- WASM not built or path incorrect
+- Run `npm run build:wasm`
+- Check `src/services/iroh/wasm/pkg/` exists
+
+## Dependencies
+
+Key Rust crates:
+- `iroh` - P2P networking
+- `wasm-bindgen` - Rust↔JavaScript bindings
+- `web-sys` - Browser API access
+- `js-sys` - JavaScript type system
+
+## Performance
+
+- **Build time**: ~60 seconds (release mode)
+- **WASM size**: ~2MB (gzipped: ~600KB)
+- **Startup time**: ~100ms (first load)
+- **Memory**: ~5MB per node
+
+## See Also
+
+- [Complete Iroh Architecture](../../docs/IROH_ARCHITECTURE.md) - Full system documentation
+- [Frontend README](../../src/services/iroh/README.md) - TypeScript integration
+- [Backend README](../../src-tauri/src/iroh/README.md) - Rust implementation
+- [wasm-bindgen Book](https://rustwasm.github.io/wasm-bindgen/) - WASM bindings guide

package/wasm/pkg/iroh_wasm.d.ts

@@ -0,0 +1,148 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * The `ReadableStreamType` enum.
+ *
+ * *This API requires the following crate features to be activated: `ReadableStreamType`*
+ */
+
+type ReadableStreamType = "bytes";
+
+export class BiStream {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly endpoint_id: string;
+    readonly recv: ReadableStream;
+    readonly send: WritableStream;
+}
+
+export class IntoUnderlyingByteSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+
+export class IntoUnderlyingSink {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+
+export class IntoUnderlyingSource {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+
+export class IrohNode {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    addNodeAddr(node_id: string, relay_url: string | null | undefined, direct_addresses: string[]): Promise<void>;
+    connect(endpoint_id: string): ReadableStream;
+    disconnect(endpoint_id: string): Promise<void>;
+    events(): ReadableStream;
+    incoming_streams(): ReadableStream;
+    node_addr(): Promise<string>;
+    open_bi(endpoint_id: string): Promise<BiStream>;
+    open_uni(endpoint_id: string): Promise<WritableStream>;
+    static spawn(secret_key?: Uint8Array | null): Promise<IrohNode>;
+    readonly endpoint_id: string;
+    readonly secret_key: Uint8Array;
+}
+
+export function start(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly start: () => void;
+    readonly __wbg_bistream_free: (a: number, b: number) => void;
+    readonly bistream_recv: (a: number) => any;
+    readonly bistream_send: (a: number) => any;
+    readonly bistream_endpoint_id: (a: number) => [number, number];
+    readonly __wbg_irohnode_free: (a: number, b: number) => void;
+    readonly irohnode_spawn: (a: number, b: number) => any;
+    readonly irohnode_events: (a: number) => any;
+    readonly irohnode_incoming_streams: (a: number) => any;
+    readonly irohnode_addNodeAddr: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
+    readonly irohnode_endpoint_id: (a: number) => [number, number];
+    readonly irohnode_secret_key: (a: number) => [number, number];
+    readonly irohnode_node_addr: (a: number) => any;
+    readonly irohnode_connect: (a: number, b: number, c: number) => [number, number, number];
+    readonly irohnode_disconnect: (a: number, b: number, c: number) => any;
+    readonly irohnode_open_bi: (a: number, b: number, c: number) => any;
+    readonly irohnode_open_uni: (a: number, b: number, c: number) => any;
+    readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
+    readonly intounderlyingsource_pull: (a: number, b: any) => any;
+    readonly intounderlyingsource_cancel: (a: number) => void;
+    readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
+    readonly intounderlyingsink_write: (a: number, b: any) => any;
+    readonly intounderlyingsink_close: (a: number) => any;
+    readonly intounderlyingsink_abort: (a: number, b: any) => any;
+    readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
+    readonly intounderlyingbytesource_type: (a: number) => number;
+    readonly intounderlyingbytesource_autoAllocateChunkSize: (a: number) => number;
+    readonly intounderlyingbytesource_start: (a: number, b: any) => void;
+    readonly intounderlyingbytesource_pull: (a: number, b: any) => any;
+    readonly intounderlyingbytesource_cancel: (a: number) => void;
+    readonly ring_core_0_17_14__bn_mul_mont: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasm_bindgen__closure__destroy__h7cf29a7e95a6517c: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__heb08e36b77a85b9c: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h18332ba013e398aa: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h87cf50f4bd51ca2e: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h920903f13ccee978: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h5ecb98b48ddb9e08: (a: number, b: number) => void;
+    readonly wasm_bindgen__closure__destroy__h5c4e7138d6491581: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h39b19e5fabe12541: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h993a01742f0967bf: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hb5204d4e41ff3977: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h650bb17850b2b136: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h36c5adc97d437817: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__hb17976c66e1a6d68: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h81b4c013358ef500: (a: number, b: number) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h19f413c72615257c: (a: number, b: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_drop_slice: (a: number, b: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;