Initial Commit
This commit is contained in:
@@ -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.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Tasks — network-plugin-middleware
|
||||
|
||||
> Blocked on: `network-core`.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 `packages/network/network-plugin-middleware/` with `package.json` (`@suaveplan/network-plugin-middleware@0.0.0`), `tsconfig.json`, `vitest.config.ts`, `README.md`.
|
||||
- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/rate-limiter`, `@opentelemetry/api`, `zod`.
|
||||
- [x] 1.3 `sideEffects: false`.
|
||||
|
||||
## 2. Types
|
||||
|
||||
- [x] 2.1 `src/types/middleware.types.ts` — `Middleware`, `MiddlewareContext`, `MiddlewarePriority`.
|
||||
- [x] 2.2 `src/types/chain.types.ts` — `ChainDirection`, `ChainResult`, `ErrorPolicy`.
|
||||
- [x] 2.3 `src/error-codes.ts` — `defineCodes("NET_MW", [...])`.
|
||||
|
||||
## 3. Middleware manager
|
||||
|
||||
- [x] 3.1 `src/manager/middleware-manager.ts` — `MiddlewareManager`.
|
||||
- [x] 3.2 `register(middleware)`, `unregister(id)`, `enable(id)`, `disable(id)`.
|
||||
- [x] 3.3 Orders by priority band: CRITICAL (0–99), HIGH (100–199), NORMAL (200–299), LOW (300–399), BACKGROUND (400+).
|
||||
- [x] 3.4 Executes incoming and outgoing chains independently.
|
||||
|
||||
## 4. Logging middleware
|
||||
|
||||
- [x] 4.1 `src/logging/logging-middleware.ts` — `LoggingMiddleware`.
|
||||
- [x] 4.2 Configurable body inclusion, max body size, custom formatter.
|
||||
- [x] 4.3 Publishes `middleware:logged` on bus.
|
||||
|
||||
## 5. Validation middleware
|
||||
|
||||
- [x] 5.1 `src/validation/validation-middleware.ts` — `ValidationMiddleware`.
|
||||
- [x] 5.2 Per-`MessageType` Zod schemas.
|
||||
- [x] 5.3 Strict mode: reject invalid. Lenient mode: log warning, forward.
|
||||
|
||||
## 6. Transformation middleware
|
||||
|
||||
- [x] 6.1 `src/transformation/transformation-middleware.ts` — `TransformationMiddleware`.
|
||||
- [x] 6.2 Type-specific transform functions.
|
||||
- [x] 6.3 Examples: compress large payloads, strip debug fields, inject trace context.
|
||||
|
||||
## 7. Metrics middleware
|
||||
|
||||
- [x] 7.1 `src/metrics/metrics-middleware.ts` — `MetricsMiddleware`.
|
||||
- [x] 7.2 Collects size, processing time, queue wait time per message.
|
||||
- [x] 7.3 Publishes `middleware:metrics` on bus.
|
||||
|
||||
## 8. Throttling middleware
|
||||
|
||||
- [x] 8.1 `src/throttling/throttling-middleware.ts` — `ThrottlingMiddleware`.
|
||||
- [x] 8.2 Token-bucket rate limiting using `@suaveplan/rate-limiter`.
|
||||
- [x] 8.3 Global, per-peer, per-type limits with burst support.
|
||||
|
||||
## 9. Security middleware
|
||||
|
||||
- [x] 9.1 `src/security/security-middleware.ts` — `SecurityMiddleware`.
|
||||
- [x] 9.2 Auto-applies crypto transforms based on message type and destination tier.
|
||||
- [x] 9.3 Integrates with `network-plugin-crypto-messages` for signing/encryption.
|
||||
|
||||
## 10. I18n middleware
|
||||
|
||||
- [x] 10.1 `src/i18n/i18n-middleware.ts` — `I18nMiddleware`.
|
||||
- [x] 10.2 Injects locale metadata into message headers.
|
||||
- [x] 10.3 Handles RTL text markers.
|
||||
- [x] 10.4 Standardizes timestamps to UTC internally.
|
||||
|
||||
## 11. Plugin wrapper
|
||||
|
||||
- [x] 11.1 `src/plugin/middleware-plugin.ts` — `MiddlewarePlugin` implements `NetworkPlugin`.
|
||||
- [x] 11.2 Installs all middleware on `install()`, wires into `NetworkNode.send()` and incoming path.
|
||||
|
||||
## 12. Spec
|
||||
|
||||
- [x] 12.1 Update `openspec/specs/network/spec.md` with `NET-41`.
|
||||
|
||||
## 13. Conformance tests
|
||||
|
||||
- [x] 13.1 `src/manager/manager.spec-conformance.test.ts` — registration, ordering, enable/disable.
|
||||
- [x] 13.2 `src/logging/logging.spec-conformance.test.ts` — body inclusion, formatting, max size.
|
||||
- [x] 13.3 `src/validation/validation.spec-conformance.test.ts` — schema validation, strict/lenient.
|
||||
- [x] 13.4 `src/transformation/transformation.spec-conformance.test.ts` — type-specific transforms.
|
||||
- [x] 13.5 `src/metrics/metrics.spec-conformance.test.ts` — size/timing, bus publication.
|
||||
- [x] 13.6 `src/throttling/throttling.spec-conformance.test.ts` — global/per-peer/per-type, burst.
|
||||
- [x] 13.7 `src/security/security.spec-conformance.test.ts` — auto-crypto per policy.
|
||||
- [x] 13.8 `src/i18n/i18n.spec-conformance.test.ts` — locale injection, RTL, timestamps.
|
||||
- [x] 13.9 `src/chain/chain.spec-conformance.test.ts` — null-drop, error-policy, direction.
|
||||
- [x] 13.10 `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
||||
|
||||
## 14. Verify
|
||||
|
||||
- [x] 14.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-middleware` green.
|
||||
- [x] 14.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-middleware` 100/100/100/100.
|
||||
- [x] 14.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-middleware` PASS.
|
||||
Reference in New Issue
Block a user