Updates

2026-05-20 23:36:32 -04:00
parent a020270cb1
commit be94546cd3
218 changed files with 9189 additions and 3078 deletions
@@ -1,84 +1,77 @@
 # API: hyper-p2p-stream-tee

-**Protocol:** `stream-tee/v1`
+**Protocol:** `stream-tee/v1` (local fan-out)

-**Export:** `HyperP2PStreamTee`
+**Export:** `HyperP2PStreamTee`, `PROTOCOL`

 ## Overview

-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-
-## Constructor
-
-```js
-const mod = new HyperP2PStreamTee(opts)
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
-| `keyPair` | KeyPair | random | Ed25519 key pair |
+Fan-out `write(chunk)` to named branches, each with its own FIFO chunk queue. Useful for teeing one ingress stream to logging and processing paths.

 ## Methods

 ### `addBranch(name)`

- **Returns:** `value`
- **Throws:**
-  - `Error: branch name required`
+- **Returns:** unsubscribe function
+- **Throws:** `branch name required`

-### `write(chunk)`
+### `write(chunk)` / `readBranch(name)` / `pending(name)`

- **Returns:** `value`
- **Throws:**
-  - `Error: chunk required`
-
-### `readBranch(name)`
-
- **Returns:** `value`
- **Throws:** — (none documented in method body)
-
-### `pending(name)`
-
- **Returns:** `value`
- **Throws:** — (none documented in method body)
-
-### `getStats(—)`
-
- **Returns:** `object`
- **Throws:** — (none documented in method body)
-
-### `ready(—)`
-
- **Returns:** `Promise`
- **Throws:** — (none documented in method body)
-
-### `close(—)`
-
- **Returns:** `Promise<void>`
- **Throws:** — (none documented in method body)
+### `getStats()` / `ready()` / `close()`

 ## Events

-| Event | Payload |
-|-------|---------|
-| `data` | buf |
+`data` on every write.

-## getStats()
+## Wire

-Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
-Library-only modules may include `mode: 'local'`.
+None.

-## Errors
+## Composition

-Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
-
-## P2P
-
-When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-tee/v1`.
+`hyper-p2p-stream-transform`, `hyper-p2p-stream-chunker`.

 ## Testing

-```bash
-npm install && npm test
-```
+`npm test`
+
+## Example
+
+`examples/basic.js`
+
+## State model
+
+Each branch stores chunk array; `write` duplicates buffer reference to all branches.
+
+## Performance
+
+Memory multiplies by branch count × queued chunks.
+
+## Versioning
+
+Local-only `stream-tee/v1` id.
+
+## Security
+
+Branches share buffer references; treat as trusted in-process only.
+
+## Related modules
+
+- `hyper-p2p-stream-transform` — per-branch mapping
+
+## Changelog
+
+- Wave 8–9: local tee for stream pipeline examples and integration tests.
+- `addBranch` returns unsubscribe to drop a branch without closing tee.
+
+## Integration checklist
+
+1. `addBranch('audit')` and `addBranch('process')`.
+2. `write(chunk)` fans out to both queues.
+3. `readBranch('process')` consumes on worker tick.
+4. `close()` clears all branches on shutdown.
+5. Use `pending(name)` to detect backlog before applying backpressure upstream.
+
+## See also
+
+[`docs/architecture.md`](architecture.md)