@kb-labs/rest-api-app 1.3.0

package/src/middleware/error-guard.ts

@@ -0,0 +1,69 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware/error-guard
+ * Global error guard for plugin routes
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { PluginErrorEnvelope } from '@kb-labs/rest-api-contracts';
+import { ErrorCode } from '@kb-labs/rest-api-contracts';
+import { platform } from '@kb-labs/core-runtime';
+
+/**
+ * Register global error handler for plugin routes
+ * Never crashes the API - all errors are converted to ErrorEnvelope
+ */
+export function registerErrorGuard(server: FastifyInstance): void {
+  // Global error handler
+  server.setErrorHandler((error: any, request, reply) => {
+    // Handle plugin errors (already ErrorEnvelope)
+    if (
+      error &&
+      typeof error === 'object' &&
+      'status' in error &&
+      error.status === 'error' &&
+      'meta' in error &&
+      error.meta &&
+      typeof error.meta === 'object' &&
+      'pluginId' in error.meta
+    ) {
+      const envelope = error as unknown as PluginErrorEnvelope;
+      reply.status(envelope.http).send(envelope);
+      return;
+    }
+
+    // Generic error - convert to PluginErrorEnvelope
+    const requestId = (request.id as string) || 'unknown';
+    const envelope: PluginErrorEnvelope = {
+      status: 'error',
+      http: error.statusCode || 500,
+      code: ErrorCode.INTERNAL,
+      message: error.message || 'Internal server error',
+      details: {
+        error: error.message || String(error),
+      },
+      trace: error.stack,
+      meta: {
+        requestId,
+        pluginId: 'system',
+        pluginVersion: 'unknown',
+        routeOrCommand: request.url || 'unknown',
+        timeMs: 0,
+      },
+    };
+
+    reply.status(envelope.http).send(envelope);
+  });
+
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error: Error) => {
+    platform.logger.fatal('Uncaught exception', error, { source: 'error-guard' });
+    // Don't exit - let Fastify handle it
+  });
+
+  // Handle unhandled rejections
+  process.on('unhandledRejection', (reason: unknown) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    platform.logger.error('Unhandled rejection', error, { source: 'error-guard' });
+    // Don't exit - let Fastify handle it
+  });
+}

package/src/middleware/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @module @kb-labs/rest-api-app/middleware
+ * Middleware registration
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { registerEnvelopeMiddleware } from './envelope';
+import { registerRequestIdMiddleware } from './request-id';
+import { registerMockModeMiddleware } from './mock-mode';
+import { registerSecurityHeadersMiddleware } from './security-headers';
+import { registerCacheMiddleware } from './cache';
+import { registerMetricsMiddleware } from './metrics';
+import { registerErrorGuard } from './error-guard';
+import { registerStartupGuard } from './startup-guard';
+import { registerRequestTimeoutGuard } from './request-timeout';
+
+/**
+ * Register all middleware
+ */
+export function registerMiddleware(
+  server: FastifyInstance,
+  config: RestApiConfig
+): void {
+  registerStartupGuard(server, config);
+  registerSecurityHeadersMiddleware(server);
+  registerRequestIdMiddleware(server);
+  registerMockModeMiddleware(server, config);
+  registerCacheMiddleware(server);
+  registerRequestTimeoutGuard(server, config);
+  registerMetricsMiddleware(server);
+  registerEnvelopeMiddleware(server, config);
+
+  // Global error guard for plugin routes (must be last)
+  registerErrorGuard(server);
+}
+