Initial Commit

openspec/archive/2026-05-04-network-plugin-middleware/proposal.md

@@ -0,0 +1,88 @@
+# OpenSpec Change: network-plugin-middleware
+
+- **Change ID**: network-plugin-middleware
+- **Package**: `@suaveplan/network-plugin-middleware` (new)
+- **Status**: PROPOSED
+- **Type**: new-package
+- **Date**: 2026-04-29
+
+## Why
+
+The network stack processes thousands of messages per second across multiple plugins. Without a unified interception layer, each plugin must independently handle cross-cutting concerns: logging, validation, rate limiting, transformation, and security. This leads to duplicated code, inconsistent behavior, and missed enforcement. A middleware pipeline provides a single, ordered chain where every message (incoming and outgoing) passes through configurable interceptors before reaching its destination.
+
+This plugin implements a **priority-ordered middleware chain** for the network layer, inspired by Express/Koa middleware patterns but adapted for peer-to-peer message flow.
+
+## What changes
+
+- **ADDED**: `MiddlewarePlugin` class implementing `NetworkPlugin`.
+- **ADDED**: `MiddlewareManager` — registers, orders, and executes middleware components. Supports runtime add/remove/enable/disable. Orders middleware by priority bands:
+  - `CRITICAL` (0–99) — security validation, message integrity, system health filters
+  - `HIGH` (100–199) — encryption/decryption, authentication, rate limiting
+  - `NORMAL` (200–299) — logging, metrics collection, transformations
+  - `LOW` (300–399) — content enrichment, non-critical validations, debug info
+  - `BACKGROUND` (400+) — performance monitoring, analytics, diagnostics
+- **ADDED**: `LoggingMiddleware` — records message details with configurable body inclusion, max body size, and custom formatters. Logs to `NetworkBus` topic `middleware:logged` for aggregation.
+- **ADDED**: `ValidationMiddleware` — schema-based message validation using Zod. Supports per-`MessageType` schemas. Strict mode rejects invalid messages; lenient mode logs warnings but forwards.
+- **ADDED**: `TransformationMiddleware` — modifies message structure per type. Example: compress large payloads, strip debug fields in production, inject trace context.
+- **ADDED**: `MetricsMiddleware` — collects per-message metrics: size, processing time, queue wait time. Publishes `middleware:metrics` on bus for `network-plugin-monitor`.
+- **ADDED**: `ThrottlingMiddleware` — rate limiting with token-bucket algorithm. Supports global limits, per-peer limits, per-type limits, and burst allowances. Uses `@suaveplan/rate-limiter`.
+- **ADDED**: `SecurityMiddleware` — automatic encryption/signing per policy. Intercepts outgoing messages and applies crypto transforms based on message type and destination tier.
+- **ADDED**: `I18nMiddleware` — locale-aware message handling. Injects locale metadata, handles RTL text, standardizes timestamps.
+- **ADDED**: `NETWORK_MW_CODES` — frozen error registry.
+
+## Middleware chain execution
+
+```yaml
+OUTGOING: Application → MiddlewareManager → (CRITICAL → HIGH → NORMAL → LOW → BACKGROUND) → Transport
+INCOMING: Transport → MiddlewareManager → (CRITICAL → HIGH → NORMAL → LOW → BACKGROUND) → Application
+
+If any middleware returns null, the message is DROPPED.
+If any middleware throws, the error policy applies: continue | stop | retry.
+```
+
+## Out of scope
+
+- Application-specific middleware → applications register custom middleware via the plugin API.
+- Message routing logic → handled by `network-core` `MessageRouter`.
+- Transport-specific transforms → handled by `network-plugin-protocol` pipeline.
+
+## Source mapping
+
+This derives from `docs/old-network-planning/PHASE_9.md` §Middleware System and `PLAN_ENHANCED.md` §Phase 9.
+
+| Requirement | Source lines | Notes |
+|---|---|---|
+| Priority-based ordering | `PHASE_9.md` §Middleware Priority Levels | verbatim: 5 priority bands |
+| Logging middleware | `PHASE_9.md` §Logging Middleware | reworded; uses `NetworkBus` |
+| Validation middleware | `PHASE_9.md` §Validation Middleware | reworded; uses Zod |
+| Transformation middleware | `PHASE_9.md` §Transformation Middleware | reworded |
+| Metrics middleware | `PHASE_9.md` §Metrics Middleware | reworded; publishes to bus |
+| Throttling middleware | `PHASE_9.md` §Throttling Middleware | reworded; uses `@suaveplan/rate-limiter` |
+| Direction handling | `PHASE_9.md` §Middleware Chain Execution | verbatim: incoming vs outgoing |
+| Chain interruption | `PHASE_9.md` §Chain Execution | verbatim: null → drop |
+
+### Requirements with no source line
+
+| Requirement | Justification |
+|---|---|
+| `SecurityMiddleware` | Required for automatic per-policy crypto application |
+| `I18nMiddleware` | Required for locale-aware message handling across global peers |
+| Runtime add/remove/enable/disable | Required for dynamic middleware configuration without restart |
+
+## Verification approach
+
+- `src/manager/manager.spec-conformance.test.ts` — pins registration, ordering, enable/disable, removal.
+- `src/logging/logging.spec-conformance.test.ts` — pins body inclusion, formatting, max size.
+- `src/validation/validation.spec-conformance.test.ts` — pins schema validation, strict/lenient modes.
+- `src/transformation/transformation.spec-conformance.test.ts` — pins message modification, type-specific transforms.
+- `src/metrics/metrics.spec-conformance.test.ts` — pins size/timing collection, bus publication.
+- `src/throttling/throttling.spec-conformance.test.ts` — pins global/per-peer/per-type limits, burst handling.
+- `src/security/security.spec-conformance.test.ts` — pins automatic crypto application per policy.
+- `src/i18n/i18n.spec-conformance.test.ts` — pins locale injection, RTL handling.
+- `src/chain/chain.spec-conformance.test.ts` — pins null-drop, error-policy, direction isolation.
+- `src/error-codes.spec-conformance.test.ts` — frozen registry.
+- `tests/dep-graph.test.ts` — pins no direct import of transport or protocol packages.
+
+## Migration impact
+
+None — additive only. Middleware is opt-in; existing message flow continues unchanged if no middleware is registered.