89 lines
5.9 KiB
Markdown
89 lines
5.9 KiB
Markdown
# 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.
|