86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# Tasks: enterprise-browser-network-discovery-gundb
|
|
|
|
**Change ID**: enterprise-browser-network-discovery-gundb
|
|
**Package**: `@suaveplan/network-discovery-gundb`
|
|
**Target path**: `browser/network/network-discovery-gundb`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/crypto`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] Create directory tree per `proposal.md`.
|
|
- [x] `package.json` at version `0.1.0`; `sideEffects` accurately reflects Gun's import-time effects.
|
|
- `dependencies`: `@suaveplan/network workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/crypto workspace:^`, `gun`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
|
|
- `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`, `react catalog:browser`, `@types/react catalog:browser`
|
|
- [x] `tsconfig.json`, `vitest.config.ts` (pool: forks).
|
|
|
|
---
|
|
|
|
## 2. Error codes
|
|
|
|
- [x] Define `GunDBErrorCode`: `GUN_RELAY_UNREACHABLE`, `GUN_MESSAGE_REJECTED`, `GUN_SIGNATURE_INVALID`.
|
|
- [x] `registerGunDBErrorCodes()` — call eagerly.
|
|
|
|
---
|
|
|
|
## 3. GunDB schema (`src/schema/gundb-schema/`)
|
|
|
|
- [x] `GunDBMessageSchema` (Zod): `{ type: GunDBMessageType, peerId: string, metadata: GunDBPeerMetadata, signature?: string, timestamp: number }`.
|
|
- [x] `GunDBPeerMetadataSchema` (Zod): peer addresses, protocols, capabilities.
|
|
- [x] Register in `@suaveplan/schema-registry`.
|
|
- [x] Write `gundb-schema.md`.
|
|
|
|
---
|
|
|
|
## 4. GunNodeManager (`src/gun-node-manager/`)
|
|
|
|
- [x] Implement `GunNodeManager`: create Gun instance with explicit peer list; expose `get`/`put`/`on` wrappers.
|
|
- [x] Strict-mode: if `peers` empty and `strict: true`, throw `GUN_RELAY_UNREACHABLE` before Gun is created.
|
|
- [x] Write `gun-node-manager.test.ts` against a local Gun relay instance, `gun-node-manager.md`.
|
|
|
|
---
|
|
|
|
## 5. GunDBInitializer (`src/gundb-initializer/`)
|
|
|
|
- [x] Implement relay bootstrap and room namespace setup.
|
|
- [x] Write `gundb-initializer.test.ts`, `gundb-initializer.md`.
|
|
|
|
---
|
|
|
|
## 6. GunDBDiscovery (`src/gundb-discovery/`)
|
|
|
|
- [x] Implement `GunDBDiscovery`:
|
|
- On write: sign metadata with `@suaveplan/crypto` ed25519 when `config.sign: true`.
|
|
- On read: verify signature; drop with `GUN_SIGNATURE_INVALID` if invalid.
|
|
- Validate every incoming message with `GunDBMessageSchema`; drop + emit metric on failure.
|
|
- Rate limit: track updates per peer per second; drop excess.
|
|
- [x] Wire OTel metrics.
|
|
- [x] Write `gundb-discovery.test.ts` (sign/verify, strict-mode, malformed drop, rate limit), `gundb-discovery.md`, `gundb-discovery.types.ts`.
|
|
|
|
---
|
|
|
|
## 7. Story (`src/gundb-discovery/gundb-discovery.stories.tsx`)
|
|
|
|
- [x] Write Storybook story with `react` in devDeps — demonstrates live peer discovery against a local Gun relay.
|
|
|
|
---
|
|
|
|
## 8. Integration test (`tests/integration.test.ts`)
|
|
|
|
- [x] Two `GunDBDiscovery` instances against a local Gun relay; assert discovery event fires.
|
|
- [x] Strict-mode: empty `peers` throws typed error.
|
|
- [x] Signed metadata: a discovery instance without a matching key drops the peer.
|
|
|
|
---
|
|
|
|
## 9. Docs + verify
|
|
|
|
- [x] Write `.md` per module; `README.md` with strict-mode + relay-list deployment guidance.
|
|
- [x] `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-gundb` — green.
|
|
- [x] `bunx turbo test:coverage` — 100%.
|
|
- [x] `sideEffects` accurately declared (check Gun's effects; may need `["./dist/index.js"]`).
|
|
- [x] Story builds cleanly.
|
|
- [x] `bun scripts/publish.ts --package @suaveplan/network-discovery-gundb`.
|
|
- [x] Archive to `openspec/archive/2026-04-24-enterprise-browser-network-discovery-gundb/`.
|