suaveplan/openspec/archive/2026-05-12-enterprise-browser-network-libp2p/tasks.md

Tasks: enterprise-browser-network-libp2p

Change ID: enterprise-browser-network-libp2p Package: @suaveplan/network-libp2p Target path: browser/network/network-libp2p Prerequisite packages on Verdaccio: @suaveplan/network, @suaveplan/serialize, @suaveplan/error, @suaveplan/types, @suaveplan/events

---

1. Scaffold

• Create browser/network/network-libp2p/ directory tree per layout in proposal.md.
• Write package.json at version 0.1.0 — no react / react-dom in runtime deps.
  • dependencies: @suaveplan/network workspace:^, @suaveplan/serialize workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/events workspace:^, all libp2p packages from Bun catalog, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
• Write tsconfig.json and vitest.config.ts (pool: forks).

---

2. Error codes (src/error-codes.ts)

• Define Libp2pErrorCode: LIBP2P_DIAL_FAILED, LIBP2P_STREAM_RESET, LIBP2P_UNSUPPORTED_TRANSPORT, LIBP2P_BOOTSTRAP_REJECTED, LIBP2P_RELAY_INVALID.
• Export registerLibp2pErrorCodes() and call eagerly.

---

3. Config schema (src/config/config-schema/)

• Define Libp2pConfigSchema (Zod):
  • listenAddresses?: string[]
  • bootstrapPeers?: string[] — required when strict: true
  • relayAddrs?: string[] — validated by validateRelayAddrs()
  • enableWebRTC?: boolean, enableWebSockets?: boolean, strict?: boolean (default true)
• Export validateLibp2pConfig(config) throwing LIBP2P_BOOTSTRAP_REJECTED when strict + empty bootstrap list.
• Register schema in @suaveplan/schema-registry.
• Write config-schema.md.

---

4. Presets (src/presets/presets/)

• Implement presets.browserP2P(), presets.browserBrowser(), presets.browserNode() returning valid Libp2pConfig objects.
• Write presets.test.ts asserting each preset passes schema validation and has non-empty transport list.
• Write presets.md.

---

5. Peer message (src/lib/peer-message/)

• Define PeerMessage wire format with protocol, payload, from fields.
• Zod schema for PeerMessage.
• Write peer-message.test.ts, peer-message.md.

---

6. Stream handler (src/lib/stream-handler/)

• Implement StreamHandler registration: registerProtocol(protocol, handler), unregisterProtocol(protocol), dispatch incoming streams.
• Write stream-handler.test.ts, stream-handler.md.

---

7. Messaging (src/lib/libp2p-messaging/)

• Implement sendMessage(peerId, protocol, payload) + requestResponse(peerId, protocol, payload) over a libp2p stream.
• Wire OTel histograms libp2p.stream_ttfb_ms.
• Write libp2p-messaging.test.ts (≤500 lines, split by responsibility), libp2p-messaging.md.

---

8. Send-to-peer helpers (src/lib/send-to-peer/)

• Implement convenience helpers: sendToPeer, broadcastToPeers, sendToAll.
• Write send-to-peer.test.ts, send-to-peer.md.

---

9. Connection (src/lib/libp2p-connection/)

• Implement createLibp2pNode(config: Libp2pConfig): Promise<Libp2p> — calls createLibp2p() with transport/muxer/encryption assembled from config.
• Apply bootstrap gate: refuse public default bootstrap peers when strict: true.
• Write libp2p-connection.test.ts, libp2p-connection.md.

---

10. Transport (src/transport/libp2p-transport/)

• Implement Libp2pTransport composing all lib/ modules.
• Wire OTel counters libp2p.connections_opened_total, libp2p.streams_opened_total, libp2p.bytes_in_total, libp2p.bytes_out_total.
• Write libp2p-transport.test.ts (unit: wires components together), libp2p-transport.md, libp2p-transport.types.ts.

---

11. Integration test (tests/integration.test.ts)

• Two in-process libp2p nodes using the echo protocol; assert message round-trip.
• Strict-mode gate: config with empty bootstrapPeers + strict: true throws LIBP2P_BOOTSTRAP_REJECTED.
• Relay-addr validation: invalid multiaddr format throws LIBP2P_RELAY_INVALID.

---

12. Playwright E2E (e2e/libp2p.spec.ts)

• Two Chromium browser contexts; each runs a Vite-bundled test page with a real Libp2pTransport node.
• Nodes discover each other via a shared bootstrap addr.
• Echo protocol: send message from A to B, assert received at B.

---

13. Docs

• Write .md per module (≥200 words, examples, API reference).
• Write README.md with transport-preset table, strict-mode guidance, companion-package link.

---

14. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/network-libp2p — green.
• bunx turbo test:coverage --filter=@suaveplan/network-libp2p — 100%.
• bun run docs:check --filter=@suaveplan/network-libp2p — zero errors.
• No react in runtime deps; no vi.mock, any, ts-ignore, .skip.
• Playwright E2E two-node echo round trip passes.
• bun scripts/publish.ts --package @suaveplan/network-libp2p.
• Archive to openspec/archive/2026-04-24-enterprise-browser-network-libp2p/.