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

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

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.