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

Tasks — network-plugin-middleware

Blocked on: network-core.

1. Scaffold

• 1.1 packages/network/network-plugin-middleware/ with package.json (@suaveplan/network-plugin-middleware@0.0.0), tsconfig.json, vitest.config.ts, README.md.
• 1.2 Workspace deps: @suaveplan/network, @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/rate-limiter, @opentelemetry/api, zod.
• 1.3 sideEffects: false.

2. Types

• 2.1 src/types/middleware.types.ts — Middleware, MiddlewareContext, MiddlewarePriority.
• 2.2 src/types/chain.types.ts — ChainDirection, ChainResult, ErrorPolicy.
• 2.3 src/error-codes.ts — defineCodes("NET_MW", [...]).

3. Middleware manager

• 3.1 src/manager/middleware-manager.ts — MiddlewareManager.
• 3.2 register(middleware), unregister(id), enable(id), disable(id).
• 3.3 Orders by priority band: CRITICAL (0–99), HIGH (100–199), NORMAL (200–299), LOW (300–399), BACKGROUND (400+).
• 3.4 Executes incoming and outgoing chains independently.

4. Logging middleware

• 4.1 src/logging/logging-middleware.ts — LoggingMiddleware.
• 4.2 Configurable body inclusion, max body size, custom formatter.
• 4.3 Publishes middleware:logged on bus.

5. Validation middleware

• 5.1 src/validation/validation-middleware.ts — ValidationMiddleware.
• 5.2 Per-MessageType Zod schemas.
• 5.3 Strict mode: reject invalid. Lenient mode: log warning, forward.

6. Transformation middleware

• 6.1 src/transformation/transformation-middleware.ts — TransformationMiddleware.
• 6.2 Type-specific transform functions.
• 6.3 Examples: compress large payloads, strip debug fields, inject trace context.

7. Metrics middleware

• 7.1 src/metrics/metrics-middleware.ts — MetricsMiddleware.
• 7.2 Collects size, processing time, queue wait time per message.
• 7.3 Publishes middleware:metrics on bus.

8. Throttling middleware

• 8.1 src/throttling/throttling-middleware.ts — ThrottlingMiddleware.
• 8.2 Token-bucket rate limiting using @suaveplan/rate-limiter.
• 8.3 Global, per-peer, per-type limits with burst support.

9. Security middleware

• 9.1 src/security/security-middleware.ts — SecurityMiddleware.
• 9.2 Auto-applies crypto transforms based on message type and destination tier.
• 9.3 Integrates with network-plugin-crypto-messages for signing/encryption.

10. I18n middleware

• 10.1 src/i18n/i18n-middleware.ts — I18nMiddleware.
• 10.2 Injects locale metadata into message headers.
• 10.3 Handles RTL text markers.
• 10.4 Standardizes timestamps to UTC internally.

11. Plugin wrapper

• 11.1 src/plugin/middleware-plugin.ts — MiddlewarePlugin implements NetworkPlugin.
• 11.2 Installs all middleware on install(), wires into NetworkNode.send() and incoming path.

12. Spec

• 12.1 Update openspec/specs/network/spec.md with NET-41.

13. Conformance tests

• 13.1 src/manager/manager.spec-conformance.test.ts — registration, ordering, enable/disable.
• 13.2 src/logging/logging.spec-conformance.test.ts — body inclusion, formatting, max size.
• 13.3 src/validation/validation.spec-conformance.test.ts — schema validation, strict/lenient.
• 13.4 src/transformation/transformation.spec-conformance.test.ts — type-specific transforms.
• 13.5 src/metrics/metrics.spec-conformance.test.ts — size/timing, bus publication.
• 13.6 src/throttling/throttling.spec-conformance.test.ts — global/per-peer/per-type, burst.
• 13.7 src/security/security.spec-conformance.test.ts — auto-crypto per policy.
• 13.8 src/i18n/i18n.spec-conformance.test.ts — locale injection, RTL, timestamps.
• 13.9 src/chain/chain.spec-conformance.test.ts — null-drop, error-policy, direction.
• 13.10 src/error-codes.spec-conformance.test.ts — frozen registry.

14. Verify

• 14.1 bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-middleware green.
• 14.2 bunx turbo test:coverage --filter=@suaveplan/network-plugin-middleware 100/100/100/100.
• 14.3 bun scripts/openspec-conformance.ts @suaveplan/network-plugin-middleware PASS.