98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
# OpenSpec Change: network-plugin-protocol
|
|
|
|
- **Change ID**: network-plugin-protocol
|
|
- **Package**: `@suaveplan/network-plugin-protocol` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
The tiered network needs a compact, versioned binary protocol for all messages between peers. The genesis `bitpacker` package provides the binary serialization, and `serialize` provides schemas. This plugin implements a 13-byte header + binary payload format that replaces the suaveplan `network-protocol` stub. It integrates with the `streams` transforms for real encryption, compression, and framing.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `ProtocolPlugin` class implementing `NetworkPlugin`.
|
|
- **ADDED**: `BinaryProtocol` — 13-byte header: `version(1) | flags(1) | messageType(1) | timestamp(8) | payloadLength(2)`.
|
|
- **ADDED**: `MessageEncoder` / `MessageDecoder` — schema-aware encoding/decoding using `@suaveplan/bitpacker`.
|
|
- **ADDED**: `ProtocolPipeline` — wires `lengthPrefixEncode` → `CryptoTransform` → `compressStream` for outgoing, and reverse for incoming.
|
|
- **ADDED**: `FastPathDispatcher` — zero-copy fast path for common message types (heartbeat, ping, registry delta). Bypasses full pipeline when message type is in the fast-path allowlist and no encryption/compression is required.
|
|
- **ADDED**: `NETWORK_PROTO_CODES` — frozen error registry.
|
|
|
|
## Out of scope
|
|
|
|
- Protocol negotiation / version handshake → future `network-plugin-protocol-negotiation`.
|
|
- Custom message types beyond registry/governance/topology/failover → future plugins register their own.
|
|
|
|
## Source mapping
|
|
|
|
This change derives from `../suaveplan/enterprise/network-protocol.md` and `../suaveplan/packages/universal/network-protocol/`.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| 13-byte binary header | `network-protocol/README.md` §Binary Protocol | verbatim |
|
|
| Version, flags, messageType, timestamp, payloadLength | `network-protocol/README.md` §Binary Protocol | verbatim |
|
|
| Schema-aware encoding | `network-protocol/README.md` §Message Encoder/Decoder | reworded; uses `@suaveplan/bitpacker` |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| `ProtocolPipeline` using `streams` transforms | Genesis has real crypto/compression/framing; protocol should use them |
|
|
| `ProtocolPlugin` implements `NetworkPlugin` | Required to plug into `NetworkNode` |
|
|
|
|
## Verification approach
|
|
|
|
- `src/protocol/protocol.spec-conformance.test.ts` — pins header format, version, flags.
|
|
- `src/encoder/encoder.spec-conformance.test.ts` — pins schema encoding, roundtrip.
|
|
- `src/pipeline/pipeline.spec-conformance.test.ts` — pins pipeline ordering, error handling.
|
|
- `tests/dep-graph.test.ts` — pins direct import of `@suaveplan/bitpacker`, `@suaveplan/streams`.
|
|
|
|
## Enhancement: Serialization Strategy Framework
|
|
|
|
**Source**: `docs/old-network-planning/PHASE_9.md` §Serialization Strategies
|
|
|
|
The protocol plugin currently assumes a single binary encoding. The old docs defined multiple serialization strategies with a factory pattern:
|
|
|
|
- **JSON Serializer** — human-readable, widely compatible
|
|
- **Binary Serializer** — compact, schema-based, optional compression
|
|
- **MessagePack Serializer** — compact binary with extensions
|
|
- **Protocol Buffers Serializer** — schema-based with versioning
|
|
- **SerializerFactory** — selects serializer by content type with fallback
|
|
|
|
**Added to this change**:
|
|
|
|
- `SerializerFactory` — registers serializers by content type, returns default on unknown.
|
|
- `JsonSerializer`, `BinarySerializer`, `MessagePackSerializer` — implement `ISerializer`.
|
|
- Content-type negotiation in 13-byte header flags.
|
|
|
|
## Enhancement: Message Priority Queue & Adaptive Batching
|
|
|
|
**Source**: `docs/old-network-planning/PHASE_3.md` §PriorityMessageQueue, `DESCRIPTION.md` §Adaptive Batching
|
|
|
|
The protocol needs explicit message queueing and batching:
|
|
|
|
- `PriorityMessageQueue` — multiple internal queues (one per priority tier). FIFO within same tier. CRITICAL messages bypass queue.
|
|
- `MessageBatcher` — groups related messages by type/recipient. Flushes on size, time, or priority trigger. Adaptive interval based on network conditions.
|
|
- `BackpressureController` — detects overwhelmed downstream and slows production.
|
|
|
|
## Enhancement: Message TTL & Loop Detection
|
|
|
|
**Source**: `docs/old-network-planning/PHASE_3.md` §Message Expiration
|
|
|
|
- `MessageTTL` — time-to-live in hops. Drops message when `ttl <= 0`.
|
|
- `LoopDetector` — tracks `visitedNodes` in envelope header. Drops on cycle detection.
|
|
- `DuplicateDetector` — deduplicates broadcast messages via `messageId` + bloom filter.
|
|
|
|
## Enhancement: Route Caching
|
|
|
|
**Source**: `docs/old-network-planning/PHASE_3.md` §Route Caching
|
|
|
|
- `RouteCache` — caches frequently used `(source, target) → nextHop` mappings.
|
|
- Cache invalidation on `topology:changed` bus event.
|
|
- Adaptive cache size based on memory availability.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|