Complete Plugin System with Error Handling, Timeouts, and First-Party Plugins

[OthmanImam]

• Closes Lifecycle Error Handling and Timeouts #416

Overview

This comprehensive PR implements a complete plugin system for the @mindblock/middleware package with robust error handling, timeout management, and production-ready first-party plugins. All implementation is confined to the middleware repository with no backend modifications.

Features

1. Performance Benchmarks (#369)

• Automated benchmarking script measuring middleware overhead against baseline
• Tracks requests/second, latency percentiles (p50, p95, p99), and error rates
• Individual profiling for JWT Auth, RBAC, Security Headers, Timeout, Circuit Breaker, Correlation ID
• Compare middlewares by contribution to overall latency
• CLI commands: npm run benchmark and npm run benchmark:ci

Files:

• scripts/benchmark.ts - Load testing implementation
• docs/PERFORMANCE.md - Benchmarking documentation (updated)
• tests/integration/benchmark.integration.spec.ts - Test coverage

2. External Plugin Loader System

• PluginInterface - Standard contract for all plugins
• PluginLoader - Low-level discovery, loading, and lifecycle management
• PluginRegistry - High-level plugin orchestration and management
• Plugin lifecycle hooks: onLoad, onInit, onActivate, onDeactivate, onUnload, onReload
• Configuration validation with JSON Schema support
• Semantic version compatibility checking
• Plugin dependency resolution
• Priority-based execution ordering
• Comprehensive error handling (10 custom error types)

Files:

• src/common/interfaces/plugin.interface.ts - Plugin types and metadata
• src/common/interfaces/plugin.errors.ts - Error classes
• src/common/utils/plugin-loader.ts - Loader service (650+ lines)
• src/common/utils/plugin-registry.ts - Registry service (400+ lines)
• src/plugins/example.plugin.ts - Template plugin for developers
• docs/PLUGINS.md - Complete plugin documentation (750+ lines)
• docs/PLUGIN_QUICKSTART.md - Quick start guide for plugin developers (600+ lines)
• tests/integration/plugin-system.integration.spec.ts - Integration tests

3. Lifecycle Error Handling and Timeouts

• LifecycleTimeoutManager - Robust timeout and retry management
• Configurable timeouts for all lifecycle hooks (onLoad, onInit, onActivate, etc.)
• Four recovery strategies: RETRY, FAIL_FAST, GRACEFUL, ROLLBACK
• Exponential backoff for automatic retries
• Execution history and diagnostics tracking
• Per-plugin configuration management
• Error context recording with detailed diagnostics
• Multiple plugins support with independent state
• Execution statistics and health monitoring

Files:

• src/common/utils/lifecycle-timeout-manager.ts - Timeout manager (400+ lines)
• tests/integration/lifecycle-timeout-manager.spec.ts - Comprehensive tests
• docs/LIFECYCLE-TIMEOUTS.md - Complete documentation (500+ lines)
• docs/LIFECYCLE-TIMEOUTS-QUICKSTART.md - Quick start guide

4. First-Party Request Logger Plugin

• RequestLoggerPlugin - Production-ready HTTP request logging middleware
• Structured logging with request/response timing and status codes
• Configurable log levels (debug, info, warn, error)
• Path exclusion with glob pattern support
• Request ID extraction/generation for correlation tracking
• Sensitive header filtering (auth, cookies, API keys)
• Color-coded terminal output (ANSI escape codes)
• Runtime configuration API (setLogLevel, addExcludePaths, etc.)
• Comprehensive 330+ line integration tests

Files:

• src/plugins/request-logger.plugin.ts - Plugin implementation (650+ lines)
• tests/integration/request-logger.integration.spec.ts - Integration tests
• docs/REQUEST-LOGGER.md - Complete documentation (650+ lines)
• docs/REQUEST-LOGGER-QUICKSTART.md - Quick start guide
• docs/REQUEST-LOGGER-CONFIG.md - Configuration best practices

Usage

Performance Benchmarking

npm run benchmark

Outputs comprehensive latency overhead comparison for each middleware.

Loading Plugins

import { PluginRegistry } from '@mindblock/middleware';

const registry = new PluginRegistry();
await registry.init();

const plugin = await registry.load('@yourorg/plugin-example');
await registry.initialize(plugin.metadata.id);
await registry.activate(plugin.metadata.id);

Request Logger Plugin

const registry = new PluginRegistry();
await registry.init();

const logger = await registry.load('@mindblock/plugin-request-logger', {
  enabled: true,
  options: {
    logLevel: 'info',
    excludePaths: ['/health', '/metrics'],
    colorize: true
  }
});

app.use(logger.plugin.getMiddleware());

Lifecycle Error Handling

import { LifecycleTimeoutManager, RecoveryStrategy } from '@mindblock/middleware';

const timeoutManager = new LifecycleTimeoutManager();

timeoutManager.setTimeoutConfig('my-plugin', {
  onLoad: 5000,
  onActivate: 3000
});

timeoutManager.setRecoveryConfig('my-plugin', {
  strategy: RecoveryStrategy.RETRY,
  maxRetries: 2,
  retryDelayMs: 100,
  backoffMultiplier: 2
});

await timeoutManager.executeWithTimeout(
  'my-plugin',
  'onActivate',
  () => plugin.onActivate(),
  3000
);

Testing

• Benchmark integration tests validate middleware setup
• Plugin system tests cover lifecycle hooks, configuration validation, dependency resolution, error handling, and batch operations
• Request Logger plugin tests cover all features and edge cases
• Lifecycle timeout manager tests cover all recovery strategies, exponential backoff, and diagnostics

Run tests: npm test

Dependencies Added

• autocannon@^7.15.0 - Load testing library (already installed, fallback to simple HTTP client)
• semver@^7.6.0 - Semantic version validation
• @types/semver@^7.5.8 - TypeScript definitions
• ts-node@^10.9.2 - TypeScript execution

Documentation

• PERFORMANCE.md - Performance optimization guide and benchmarking docs
• PLUGINS.md - Comprehensive plugin system documentation with examples
• PLUGIN_QUICKSTART.md - Quick start for plugin developers with patterns and examples
• LIFECYCLE-TIMEOUTS.md - Complete timeout and error handling documentation
• LIFECYCLE-TIMEOUTS-QUICKSTART.md - Quick start for timeout management
• REQUEST-LOGGER.md - Complete request logger documentation
• REQUEST-LOGGER-QUICKSTART.md - Quick start for request logging
• REQUEST-LOGGER-CONFIG.md - Configuration best practices
• README.md - Updated with plugin system overview and first-party plugins

Breaking Changes

None. All additions are backward compatible.

Commits

• 4f83f97 - feat: feat(streak): build streak screen, calendar component, and exclude sidenav from full-screen pages #369 add per-middleware performance benchmarks
• 1e04e8f - feat: External Plugin Loader for npm packages
• f6daf13 - feat: First-Party Request Logger Plugin - HTTP request logging with configurable verbosity, path filtering, and request ID correlation
• 7fbfc8e - feat: Lifecycle Error Handling and Timeouts - Robust timeout and retry management for plugin lifecycle operations

---

Ready for review and merge into main after testing!

Architecture Overview

This PR establishes a complete plugin ecosystem with:

1. Plugin System Core - Dynamic loading, lifecycle management, configuration validation
2. Error Resilience - Timeout protection, retry strategies, graceful degradation
3. Production Plugins - Ready-to-use middleware components
4. Developer Experience - Comprehensive documentation, examples, and testing

The implementation provides a solid foundation for extensible middleware architecture while maintaining backward compatibility and production reliability.

• Closes First-Party Plugin — Request Logger Plugin #418

[drips-wave]

@OthmanImam Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits