Raven ScottandCursor
7cb1612e71
Complete manual documentation cleanup for the storage stack and expand category-level guides across the library. Documentation (23 storage modules): - Rewrite Methods sections in all storage-hypercore, storage-hyperbee, storage-autobase, and storage-hyperdrive api.md files from index.js - Remove every "module-specific (see implementation)" placeholder in storage - Fix bitfield-scheduler, bee-batch-write, bee-range-watch, drive-gc-sweep APIs Category READMEs (modules/): - trust-security, consensus-coordination, routing-advanced — tables + hub links - MODULE_CATEGORIES.md typo fix (scaffold tier description) Code: - hyper-p2p-trust-graph: hasEdge(), nodeCount(), getStats with protocol - hyper-p2p-circuit-breaker: listCircuitIds(), reset() - hyper-p2p-distributed-lock: getStats merges metrics + active lock counts Parent workspace (not in this repo) also received doc hubs for all 29 categories in docs/README.md and MODULE_DOC_PASS.md giant-pass tracker. Co-authored-by: Cursor <[email protected]>
110 lines
2.8 KiB
Markdown
110 lines
2.8 KiB
Markdown
# API: hyper-p2p-autobase-view-sync
|
|
|
|
**Protocol:** `autobase-view-sync/v1`
|
|
|
|
**Export:** `HyperP2PAutobaseViewSync`
|
|
|
|
## Overview
|
|
|
|
Gossip-synced Autobase view version + content hash; reactive UIs can mirror via `hyper-p2p-reactive-state`.
|
|
|
|
## Constructor
|
|
|
|
```js
|
|
const mod = new HyperP2PAutobaseViewSync(opts)
|
|
```
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `topic` | string \| Buffer \| null | null | Hyperswarm topic; gossip attaches when set |
|
|
| `keyPair` | Ed25519 KeyPair | random | Signing identity for swarm |
|
|
| `autobase` | object \| null | null | Attached autobase instance (`attach()` also supported) |
|
|
|
|
## Methods
|
|
|
|
### `attach(autobase) → this`
|
|
|
|
Validates autobase via `assertAutobase`.
|
|
|
|
### `publishView(version) → view`
|
|
|
|
Updates local view when `version >= _view.version`, gossips `view-sync`, emits `publish`.
|
|
|
|
- **Returns:** `{ version, hash, at }` where `hash` is `sha256("view:" + version)` hex
|
|
- **Throws:** `version must be non-negative`
|
|
|
|
### `mergeRemoteView(view) → boolean`
|
|
|
|
Advances when remote `version` is newer; rejects same version with conflicting `hash`.
|
|
|
|
- **Returns:** `true` when merged, `false` when rejected
|
|
- **Emits:** `merged` on success
|
|
|
|
### `currentView() → view`
|
|
|
|
- **Returns:** shallow copy of `{ version, hash, at, mergedAt? }`
|
|
|
|
### `isAtLeast(version) → boolean`
|
|
|
|
### `behindBy(version) → number`
|
|
|
|
- **Returns:** `max(0, version - _view.version)`
|
|
- **Throws:** `version must be non-negative`
|
|
|
|
### `getStats() → object`
|
|
|
|
`{ published, merged, gossipIn, gossipOut, view, protocol }`.
|
|
|
|
### `async ready() → this`
|
|
|
|
Joins gossip when `topic` is set; inbound `view-sync` calls `mergeRemoteView`.
|
|
|
|
### `async close() → void`
|
|
|
|
Destroys swarm; emits `closed`.
|
|
|
|
## Events
|
|
|
|
| Event | Payload |
|
|
|-------|---------|
|
|
| `publish` | published view |
|
|
| `merged` | merged view state |
|
|
| `closed` | no payload |
|
|
|
|
## getStats()
|
|
|
|
Returns `{ ...this._stats, protocol }` plus module-specific counters (pending queues, registry sizes, gossip in/out when P2P).
|
|
Local modules report hot-path counters only; P2P modules include gossip traffic when `topic` is set.
|
|
|
|
## Errors
|
|
|
|
Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
|
|
|
|
Validation helpers may throw `ValidationError` (e.g. `peer is required`, `path is required`).
|
|
|
|
### Documented `throw new Error(...)` strings
|
|
|
|
- `version must be non-negative`
|
|
|
|
## P2P
|
|
|
|
When `topic` is set, `ready()` joins Hyperswarm and opens gossip for `autobase-view-sync/v1`.
|
|
Outbound payloads use `sendGossip` (Protomux peer map); inbound handled in `_onGossip`.
|
|
|
|
### Gossip message types
|
|
|
|
- `view-sync`
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
npm install && npm test
|
|
```
|
|
|
|
## Common flows
|
|
|
|
1. `publishView(version)` — gossip `view-sync`.
|
|
2. `mergeRemoteView(view)` — monotonic version merge.
|
|
3. `currentView()` — local snapshot.
|
|
|