Updates
This commit is contained in:
Raven Scott
@@ -3,3 +3,7 @@
|
||||
## [0.0.0-scaffold] — Wave 8
|
||||
|
||||
- Registry scaffold: file tree, load smoke tests, docs stubs
|
||||
## [0.3.2] - 2026-05-21
|
||||
|
||||
### Changed
|
||||
- Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
|
||||
|
||||
@@ -1,28 +1,43 @@
|
||||
# hyper-p2p-topic-channel
|
||||
|
||||
**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `topic-channel/v1` · **Wave:** 8
|
||||
Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
|
||||
|
||||
Named topic channels.
|
||||
**Category:** General
|
||||
|
||||
## Holepunch references (inspiration only)
|
||||
**Composes with:**
|
||||
|
||||
- `protomux`
|
||||
**Protocol:** `topic-channel/v1`
|
||||
|
||||
> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
|
||||
## When to use
|
||||
|
||||
## Composes with
|
||||
Multi-peer apps that need general over a shared Hyperswarm topic.
|
||||
|
||||
- `hyper-p2p-gossip-mesh`
|
||||
## When not to use
|
||||
|
||||
## Planned API
|
||||
Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
|
||||
|
||||
- `constructor(opts)` — topic, optional keyPair
|
||||
- `getStats()` — scaffold counters
|
||||
- `ready()` — no-op until implemented
|
||||
- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
|
||||
## Quick start
|
||||
|
||||
## Layout
|
||||
```js
|
||||
const { HyperP2PTopicChannel } = require('hyper-p2p-topic-channel')
|
||||
const topic = process.argv[2] // 64-char hex or string
|
||||
const mod = new HyperP2PTopicChannel({ topic, enableBackgroundTimers: false })
|
||||
await mod.ready() // joins swarm when topic set
|
||||
// ... application logic ...
|
||||
await mod.close()
|
||||
```
|
||||
|
||||
`modules/messaging-pubsub/hyper-p2p-topic-channel/`
|
||||
## Docs
|
||||
|
||||
See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
|
||||
- [docs/api.md](docs/api.md) — constructor, methods, events, errors
|
||||
- [docs/architecture.md](docs/architecture.md) — wire types, state, composition
|
||||
- [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
|
||||
- [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
|
||||
|
||||
- Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `topic-channel-two-node.js`
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
npm install && npm test
|
||||
```
|
||||
|
||||
@@ -1,23 +1,91 @@
|
||||
# hyper-p2p-topic-channel API
|
||||
# API: hyper-p2p-topic-channel
|
||||
|
||||
**Status:** scaffold · **Protocol:** `topic-channel/v1`
|
||||
**Protocol:** `topic-channel/v1`
|
||||
|
||||
## Class `HyperP2PTopicChannel`
|
||||
**Export:** `HyperP2PTopicChannel`
|
||||
|
||||
Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
|
||||
## Overview
|
||||
|
||||
### `constructor(opts?)`
|
||||
Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
|
||||
|
||||
### `getStats()`
|
||||
## Constructor
|
||||
|
||||
Returns `{ created, errors, protocol, tier: 'scaffold' }`.
|
||||
```js
|
||||
const mod = new HyperP2PTopicChannel(opts)
|
||||
```
|
||||
|
||||
### `ready()`
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `topic` | varies | null | topic |
|
||||
| `keyPair` | KeyPair | random Ed25519 | keyPair |
|
||||
|
||||
Resolves immediately (no-op).
|
||||
## Methods
|
||||
|
||||
## Wire (planned)
|
||||
### `subscribe(channel, handler)`
|
||||
|
||||
| Message | Direction | Notes |
|
||||
|---------|-----------|-------|
|
||||
| TBD | gossip | Defined in implementation pass |
|
||||
- **Returns:** `value`
|
||||
- **Throws:**
|
||||
- `Error: handler must be a function`
|
||||
|
||||
### `unsubscribe(channel)`
|
||||
|
||||
- **Returns:** `value`
|
||||
- **Throws:** — (none documented in method body)
|
||||
|
||||
### `publish(channel, payload, opts = {})`
|
||||
|
||||
- **Returns:** `value`
|
||||
- **Throws:** — (none documented in method body)
|
||||
|
||||
### `getRetained(channel)`
|
||||
|
||||
- **Returns:** `value`
|
||||
- **Throws:** — (none documented in method body)
|
||||
|
||||
### `syncRetained(channel)`
|
||||
|
||||
- **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)
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Payload |
|
||||
|-------|---------|
|
||||
| `closed` | no payload |
|
||||
| `message` | payload object |
|
||||
|
||||
## getStats()
|
||||
|
||||
Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
|
||||
Library-only modules may include `mode: 'local'`.
|
||||
|
||||
## Errors
|
||||
|
||||
Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
|
||||
|
||||
## P2P
|
||||
|
||||
When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `topic-channel/v1`.
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
npm install && npm test
|
||||
```
|
||||
|
||||
Integration: [`../../../real_tests/integration/topic-channel-two-node.js`](../../../real_tests/integration/topic-channel-two-node.js)
|
||||
@@ -1,22 +1,46 @@
|
||||
# hyper-p2p-topic-channel architecture
|
||||
# Architecture: hyper-p2p-topic-channel
|
||||
|
||||
**Tier:** production · **Category:** `messaging-pubsub` · **Protocol:** `topic-channel/v1`
|
||||
**Category:** General
|
||||
|
||||
## Role
|
||||
```mermaid
|
||||
flowchart LR
|
||||
App[Application] --> Mod[HyperP2PTopicChannel]
|
||||
Mod --> Mux[Protomux topic-channel/v1]
|
||||
Mux --> Swarm[Hyperswarm]
|
||||
```
|
||||
|
||||
Named topic channels over Hyperswarm + Protomux: subscribe, publish, optional retained messages per channel.
|
||||
## Sequence (P2P)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App
|
||||
participant Mod as Module
|
||||
participant SW as Hyperswarm
|
||||
participant Peer
|
||||
App->>Mod: ready(topic)
|
||||
Mod->>SW: join(topic)
|
||||
SW->>Peer: connection
|
||||
Mod->>Peer: gossip / Protomux
|
||||
Peer-->>Mod: onmessage
|
||||
Mod-->>App: emit(event)
|
||||
```
|
||||
|
||||
## Wire messages
|
||||
|
||||
| type | Direction | Fields |
|
||||
|------|-----------|--------|
|
||||
| `subscribe` | gossip | `channel`, `peer` |
|
||||
| `unsubscribe` | gossip | `channel`, `peer` |
|
||||
| `publish` | gossip | `channel`, `payload`, `from`, `at`, `qos`, `retain` |
|
||||
| `retained-sync` | gossip | `channel`, `payload`, `from`, `at` |
|
||||
| type | fields | direction | behavior |
|
||||
|------|--------|-----------|----------|
|
||||
| `publish` | at, channe, channel, payload, qos, retain, type | gossip | Handled in onmessage / gossipSend |
|
||||
| `retained-sync` | at, channel, from, payload | gossip | Handled in onmessage / gossipSend |
|
||||
| `subscribe` | peer, type | gossip | Handled in onmessage / gossipSend |
|
||||
| `unsubscribe` | peer, type | gossip | Handled in onmessage / gossipSend |
|
||||
|
||||
## State model
|
||||
|
||||
- In-memory `Map` / `Set` structures for hot path
|
||||
- Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
|
||||
- `close()` tears down swarm, timers, and clears ephemeral state
|
||||
|
||||
## Composition
|
||||
|
||||
Composes with `hyper-p2p-gossip-mesh`, `hyper-p2p-topic-lease`, `hyper-p2p-subscription-lease`.
|
||||
Composes with: see MODULE_CATEGORIES.md.
|
||||
|
||||
Uses `../../_shared/p2p-bare.js` (`initModuleSwarm`, `gossipSend`).
|
||||
|
||||
Reference in New Issue
Block a user