@pipeline-builder/api-server 3.1.0

package/lib/api/server.js

@@ -0,0 +1,144 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServer = startServer;
+exports.runServer = runServer;
+const api_core_1 = require("@pipeline-builder/api-core");
+const pipeline_core_1 = require("@pipeline-builder/pipeline-core");
+const tracing_1 = require("./tracing");
+const logger = (0, api_core_1.createLogger)('Server');
+/**
+ * Start an Express server with graceful shutdown handling
+ *
+ * Features:
+ * - Automatic database connection testing
+ * - Graceful shutdown on SIGINT/SIGTERM
+ * - SSE connection cleanup
+ * - Configurable shutdown timeout
+ *
+ * @param app - Express application
+ * @param options - Server options
+ * @returns Server instance and control functions
+ *
+ * @example
+ * ```typescript
+ * const { app, sseManager } = createApp();
+ *
+ * app.post('/api/resource', requireAuth, handler);
+ *
+ * await startServer(app, {
+ *   name: 'My Microservice',
+ *   sseManager,
+ *   onStart: (port) => console.log(`Listening on ${port}`),
+ * });
+ * ```
+ */
+async function startServer(app, options = {}) {
+    const serverConfig = pipeline_core_1.Config.get('server');
+    const { name = 'Microservice', sseManager, shutdownTimeoutMs = 15000, onStart, onShutdown, onBeforeStart, testDatabase, closeDatabase, } = options;
+    const port = options.port ?? serverConfig.port;
+    // Validate auth configuration at server startup (not during CDK synthesis)
+    pipeline_core_1.Config.validateAuth();
+    logger.info(`Starting ${name}...`);
+    // Pre-start hook (e.g., initialize external connections)
+    if (onBeforeStart) {
+        await onBeforeStart();
+    }
+    // Test database connection
+    if (testDatabase !== false) {
+        const dbHealthy = testDatabase
+            ? await testDatabase()
+            : await (0, pipeline_core_1.getConnection)().testConnection();
+        if (!dbHealthy) {
+            throw new Error('Database connection failed');
+        }
+        logger.info('Database connection established');
+    }
+    // Start server
+    const server = app.listen(port, () => {
+        logger.info(`${name} listening on port: ${port}`);
+        logger.info(`Platform URL: ${serverConfig.platformUrl}`);
+        onStart?.(port);
+    });
+    // Shutdown handler (guarded against concurrent signals)
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (signal) {
+            logger.info(`${signal} received, shutting down gracefully...`);
+        }
+        // Custom shutdown callback
+        if (onShutdown) {
+            try {
+                await onShutdown();
+            }
+            catch (error) {
+                logger.error('Error in onShutdown callback', { error });
+            }
+        }
+        // Close SSE connections
+        if (sseManager) {
+            sseManager.shutdown();
+            logger.info('SSE connections closed');
+        }
+        // Close HTTP server
+        server.close(async () => {
+            logger.info('HTTP server closed');
+            // Shutdown OpenTelemetry tracing
+            await (0, tracing_1.shutdownTracing)().catch(err => logger.error('Error shutting down tracing', { error: err }));
+            // Close database connection
+            if (closeDatabase !== false) {
+                try {
+                    if (closeDatabase) {
+                        await closeDatabase();
+                    }
+                    else {
+                        await (0, pipeline_core_1.closeConnection)();
+                    }
+                    logger.info('Database connection closed');
+                }
+                catch (error) {
+                    logger.error('Error closing database', { error });
+                }
+            }
+            process.exit(0);
+        });
+        // Force shutdown after timeout
+        setTimeout(() => {
+            logger.error('Forced shutdown after timeout');
+            process.exit(1);
+        }, shutdownTimeoutMs).unref();
+    };
+    // Register signal handlers
+    process.once('SIGINT', () => void shutdown('SIGINT'));
+    process.once('SIGTERM', () => void shutdown('SIGTERM'));
+    return {
+        server,
+        port,
+        shutdown: () => shutdown(),
+    };
+}
+/**
+ * Simple server start wrapper with error handling
+ *
+ * @param app - Express application
+ * @param options - Server options
+ *
+ * @example
+ * ```typescript
+ * const { app, sseManager } = createApp();
+ * app.post('/api/resource', handler);
+ *
+ * void runServer(app, { name: 'My Service', sseManager });
+ * ```
+ */
+function runServer(app, options = {}) {
+    startServer(app, options).catch((error) => {
+        logger.error('Failed to start server', { error });
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FwaS9zZXJ2ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBLCtDQUErQztBQUMvQyxzQ0FBc0M7O0FBeUV0QyxrQ0FnSEM7QUFnQkQsOEJBS0M7QUEzTUQseURBQTBEO0FBQzFELG1FQUF5RjtBQUV6Rix1Q0FBNEM7QUFHNUMsTUFBTSxNQUFNLEdBQUcsSUFBQSx1QkFBWSxFQUFDLFFBQVEsQ0FBQyxDQUFDO0FBc0N0Qzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXlCRztBQUNJLEtBQUssVUFBVSxXQUFXLENBQy9CLEdBQVksRUFDWixVQUE4QixFQUFFO0lBRWhDLE1BQU0sWUFBWSxHQUFHLHNCQUFNLENBQUMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQzFDLE1BQU0sRUFDSixJQUFJLEdBQUcsY0FBYyxFQUNyQixVQUFVLEVBQ1YsaUJBQWlCLEdBQUcsS0FBSyxFQUN6QixPQUFPLEVBQ1AsVUFBVSxFQUNWLGFBQWEsRUFDYixZQUFZLEVBQ1osYUFBYSxHQUNkLEdBQUcsT0FBTyxDQUFDO0lBQ1osTUFBTSxJQUFJLEdBQUcsT0FBTyxDQUFDLElBQUksSUFBSSxZQUFZLENBQUMsSUFBSSxDQUFDO0lBRS9DLDJFQUEyRTtJQUMzRSxzQkFBTSxDQUFDLFlBQVksRUFBRSxDQUFDO0lBRXRCLE1BQU0sQ0FBQyxJQUFJLENBQUMsWUFBWSxJQUFJLEtBQUssQ0FBQyxDQUFDO0lBRW5DLHlEQUF5RDtJQUN6RCxJQUFJLGFBQWEsRUFBRSxDQUFDO1FBQ2xCLE1BQU0sYUFBYSxFQUFFLENBQUM7SUFDeEIsQ0FBQztJQUVELDJCQUEyQjtJQUMzQixJQUFJLFlBQVksS0FBSyxLQUFLLEVBQUUsQ0FBQztRQUMzQixNQUFNLFNBQVMsR0FBRyxZQUFZO1lBQzVCLENBQUMsQ0FBQyxNQUFNLFlBQVksRUFBRTtZQUN0QixDQUFDLENBQUMsTUFBTSxJQUFBLDZCQUFhLEdB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Q0FBQztJQUVGLDJCQUEyQjtJQUMzQixPQUFPLENBQUMsSUFBSSxDQUFDLFFBQVEsRUFBRSxHQUFHLEVBQUUsQ0FBQyxLQUFLLFFBQVEsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDO0lBQ3RELE9BQU8sQ0FBQyxJQUFJLENBQUMsU0FBUyxFQUFFLEdBQUcsRUFBRSxDQUFDLEtBQUssUUFBUSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUM7SUFFeEQsT0FBTztRQUNMLE1BQU07UUFDTixJQUFJO1FBQ0osUUFBUSxFQUFFLEdBQUcsRUFBRSxDQUFDLFFBQVEsRUFBRTtLQUMzQixDQUFDO0FBQ0osQ0FBQztBQUVEOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFDSCxTQUFnQixTQUFTLENBQUMsR0FBWSxFQUFFLFVBQThCLEVBQUU7SUFDdEUsV0FBVyxDQUFDLEdBQUcsRUFBRSxPQUFPLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxLQUFLLEVBQUUsRUFBRTtRQUN4QyxNQUFNLENBQUMsS0FBSyxDQUFDLHdCQUF3QixFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUMsQ0FBQztRQUNsRCxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDO0lBQ2xCLENBQUMsQ0FBQyxDQUFDO0FBQ0wsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIENvcHlyaWdodCAyMDI2IFBpcGVsaW5lIEJ1aWxkZXIgQ29udHJpYnV0b3JzXG4vLyBTUERYLUxpY2Vuc2UtSWRlbnRpZmllcjogQXBhY2hlLTIuMFxuXG5pbXBvcnQgeyBTZXJ2ZXIgfSBmcm9tICdodHRwJztcbmltcG9ydCB7IGNyZWF0ZUxvZ2dlciB9IGZyb20gJ0BwaXBlbGluZS1idWlsZGVyL2FwaS1jb3JlJztcbmltcG9ydCB7IENvbmZpZywgZ2V0Q29ubmVjdGlvbiwgY2xvc2VDb25uZWN0aW9uIH0gZnJvbSAnQHBpcGVsaW5lLWJ1aWxkZXIvcGlwZWxpbmUtY29yZSc7XG5pbXBvcnQgeyBFeHByZXNzIH0gZnJvbSAnZXhwcmVzcyc7XG5pbXBvcnQgeyBzaHV0ZG93blRyYWNpbmcgfSBmcm9tICcuL3RyYWNpbmcnO1xuaW1wb3J0IHsgU1NFTWFuYWdlciB9IGZyb20gJy4uL2h0dHAvc3NlLWNvbm5lY3Rpb24tbWFuYWdlcic7XG5cbmNvbnN0IGxvZ2dlciA9IGNyZWF0ZUxvZ2dlcignU2VydmVyJyk7XG5cbi8qKlxuICogT3B0aW9ucyBmb3Igc3RhcnRpbmcgYSBzZXJ2ZXJcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBTdGFydFNlcnZlck9wdGlvbnMge1xuICAvKiogU2VydmljZSBuYW1lIGZvciBsb2dnaW5nICovXG4gIG5hbWU/OiBzdHJpbmc7XG4gIC8qKiBQb3J0IHRvIGxpc3RlbiBvbiAoZGVmYXVsdDogZnJvbSBjb25maWcpICovXG4gIHBvcnQ/OiBudW1iZXI7XG4gIC8qKiBTU0UgbWFuYWdlciBmb3IgZ3JhY2VmdWwgc2h1dGRvd24gKi9cbiAgc3NlTWFuYWdlcj86IFNTRU1hbmFnZXI7XG4gIC8qKiBTaHV0ZG93biB0aW1lb3V0IGluIG1pbGxpc2Vjb25kcyAoZGVmYXVsdDogMTUwMDApICovXG4gIHNodXRkb3duVGltZW91dE1zPzogbnVtYmVyO1xuICAvKiogQ2FsbGJhY2sgYWZ0ZXIgc2VydmVyIHN0YXJ0cyAqL1xuICBvblN0YXJ0PzogKHBvcnQ6IG51bWJlcikgPT4gdm9pZDtcbiAgLyoqIENhbGxiYWNrIGJlZm9yZSBzaHV0ZG93biAqL1xuICBvblNodXRkb3duPzogKCkgPT4gUHJvbWlzZTx2b2lkPjtcbiAgLyoqIFJ1bnMgYmVmb3JlIGRhdGFiYXNlIGNoZWNrIChlLmcuLCBpbml0aWFsaXplIGV4dGVybmFsIGNvbm5lY3Rpb25zKSAqL1xuICBvbkJlZm9yZVN0YXJ0PzogKCkgPT4gUHJvbWlzZTx2b2lkPjtcbiAgLyoqIEN1c3RvbSBkYXRhYmFzZSBoZWFsdGggY2hlY2ssIG9yIGZhbHNlIHRvIHNraXAuIERlZmF1bHQ6IFBvc3RncmVTUUwgdGVzdENvbm5lY3Rpb24gKi9cbiAgdGVzdERhdGFiYXNlPzogKCgpID0+IFByb21pc2U8Ym9vbGVhbj4pIHwgZmFsc2U7XG4gIC8qKiBDdXN0b20gZGF0YWJhc2UgY2xvc2UsIG9yIGZhbHNlIHRvIHNraXAuIERlZmF1bHQ6IFBvc3RncmVTUUwgY2xvc2VDb25uZWN0aW9uICovXG4gIGNsb3NlRGF0YWJhc2U/OiAoKCkgPT4gUHJvbWlzZTx2b2lkPikgfCBmYWxzZTtcbn1cblxuLyoqXG4gKiBSZXN1bHQgb2Ygc3RhcnRpbmcgYSBzZXJ2ZXJcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBTdGFydFNlcnZlclJlc3VsdCB7XG4gIC8qKiBIVFRQIHNlcnZlciBpbnN0YW5jZSAqL1xuICBzZXJ2ZXI6IFNlcnZlcjtcbiAgLyoqIFBvcnQgdGhlIHNlcnZlciBpcyBsaXN0ZW5pbmcgb24gKi9cbiAgcG9ydDogbnVtYmVyO1xuICAvKiogRnVuY3Rpb24gdG8gbWFudWFsbHkgdHJpZ2dlciBzaHV0ZG93biAqL1xuICBzaHV0ZG93bjogKCkgPT4gUHJvbWlzZTx2b2lkPjtcbn1cblxuLyoqXG4gKiBTdGFydCBhbiBFeHByZXNzIHNlcnZlciB3aXRoIGdyYWNlZnVsIHNodXRkb3duIGhhbmRsaW5nXG4gKlxuICogRmVhdHVyZXM6XG4gKiAtIEF1dG9tYXRpYyBkYXRhYmFzZSBjb25uZWN0aW9uIHRlc3RpbmdcbiAqIC0gR3JhY2VmdWwgc2h1dGRvd24gb24gU0lHSU5UL1NJR1RFUk1cbiAqIC0gU1NFIGNvbm5lY3Rpb24gY2xlYW51cFxuICogLSBDb25maWd1cmFibGUgc2h1dGRvd24gdGltZW91dFxuICpcbiAqIEBwYXJhbSBhcHAgLSBFeHByZXNzIGFwcGxpY2F0aW9uXG4gKiBAcGFyYW0gb3B0aW9ucyAtIFNlcnZlciBvcHRpb25zXG4gKiBAcmV0dXJucyBTZXJ2ZXIgaW5zdGFuY2UgYW5kIGNvbnRyb2wgZnVuY3Rpb25zXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IHsgYXBwLCBzc2VNYW5hZ2VyIH0gPSBjcmVhdGVBcHAoKTtcbiAqXG4gKiBhcHAucG9zdCgnL2FwaS9yZXNvdXJjZScsIHJlcXVpcmVBdXRoLCBoYW5kbGVyKTtcbiAqXG4gKiBhd2FpdCBzdGFydFNlcnZlcihhcHAsIHtcbiAqICAgbmFtZTogJ015IE1pY3Jvc2VydmljZScsXG4gKiAgIHNzZU1hbmFnZXIsXG4gKiAgIG9uU3RhcnQ6IChwb3J0KSA9PiBjb25zb2xlLmxvZyhgTGlzdGVuaW5nIG9uICR7cG9ydH1gKSxcbiAqIH0pO1xuICogYGBgXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBzdGFydFNlcnZlcihcbiAgYXBwOiBFeHByZXNzLFxuICBvcHRpb25zOiBTdGFydFNlcnZlck9wdGlvbnMgPSB7fSxcbik6IFByb21pc2U8U3RhcnRTZXJ2ZXJSZXN1bHQ+IHtcbiAgY29uc3Qgc2VydmVyQ29uZmlnID0gQ29uZmlnLmdldCgnc2VydmVyJyk7XG4gIGNvbnN0IHtcbiAgICBuYW1lID0gJ01pY3Jvc2VydmljZScsXG4gICAgc3NlTWFuYWdlcixcbiAgICBzaHV0ZG93blRpbWVvdXRNcyA9IDE1MDAwLFxuICAgIG9uU3RhcnQsXG4gICAgb25TaHV0ZG93bixcbiAgICBvbkJlZm9yZVN0YXJ0LFxuICAgIHRlc3REYXRhYmFzZSxcbiAgICBjbG9zZURhdGFiYXNlLFxuICB9ID0gb3B0aW9ucztcbiAgY29uc3QgcG9ydCA9IG9wdGlvbnMucG9ydCA/PyBzZXJ2ZXJDb25maWcucG9ydDtcblxuICAvLyBWYWxpZGF0ZSBhdXRoIGNvbmZpZ3VyYXRpb24gYXQgc2VydmVyIHN0YXJ0dXAgKG5vdCBkdXJpbmcgQ0RLIHN5bnRoZXNpcylcbiAgQ29uZmlnLnZhbGlkYXRlQXV0aCgpO1xuXG4gIGxvZ2dlci5pbmZvKGBTdGFydGluZyAke25hbWV9Li4uYCk7XG5cbiAgLy8gUHJlLXN0YXJ0IGhvb2sgKGUuZy4sIGluaXRpYWxpemUgZXh0ZXJuYWwgY29ubmVjdGlvbnMpXG4gIGlmIChvbkJlZm9yZVN0YXJ0KSB7XG4gICAgYXdhaXQgb25CZWZvcmVTdGFydCgpO1xuICB9XG5cbiAgLy8gVGVzdCBkYXRhYmFzZSBjb25uZWN0aW9uXG4gIGlmICh0ZXN0RGF0YWJhc2UgIT09IGZhbHNlKSB7XG4gICAgY29uc3QgZGJIZWFsdGh5ID0gdGVzdERhdGFiYXNlXG4gICAgICA/IGF3YWl0IHRlc3REYXRhYmFzZSgpXG4gICAgICA6IGF3YWl0IGdldENvbm5lY3Rpb24oKS50ZXN0Q29ubmVjdGlvbigpO1xuXG4gICAgaWYgKCFkYkhlYWx0aHkpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcignRGF0YWJhc2UgY29ubmVjdGlvbiBmYWlsZWQnKTtcbiAgICB9XG5cbiAgICBsb2dnZXIuaW5mbygnRGF0YWJhc2UgY29ubmVjdGlvbiBlc3RhYmxpc2hlZCcpO1xuICB9XG5cbiAgLy8gU3RhcnQgc2VydmVyXG4gIGNvbnN0IHNlcnZlciA9IGFwcC5saXN0ZW4ocG9ydCwgKCkgPT4ge1xuICAgIGxvZ2dlci5pbmZvKGAke25hbWV9IGxpc3RlbmluZyBvbiBwb3J0OiAke3BvcnR9YCk7XG4gICAgbG9nZ2VyLmluZm8oYFBsYXRmb3JtIFVSTDogJHtzZXJ2ZXJDb25maWcucGxhdGZvcm1Vcmx9YCk7XG4gICAgb25TdGFydD8uKHBvcnQpO1xuICB9KTtcblxuICAvLyBTaHV0ZG93biBoYW5kbGVyIChndWFyZGVkIGFnYWluc3QgY29uY3VycmVudCBzaWduYWxzKVxuICBsZXQgc2h1dHRpbmdEb3duID0gZmFsc2U7XG4gIGNvbnN0IHNodXRkb3duID0gYXN5bmMgKHNpZ25hbD86IHN0cmluZykgPT4ge1xuICAgIGlmIChzaHV0dGluZ0Rvd24pIHJldHVybjtcbiAgICBzaHV0dGluZ0Rvd24gPSB0cnVlO1xuXG4gICAgaWYgKHNpZ25hbCkge1xuICAgICAgbG9nZ2VyLmluZm8oYCR7c2lnbmFsfSByZWNlaXZlZCwgc2h1dHRpbmcgZG93biBncmFjZWZ1bGx5Li4uYCk7XG4gICAgfVxuXG4gICAgLy8gQ3VzdG9tIHNodXRkb3duIGNhbGxiYWNrXG4gICAgaWYgKG9uU2h1dGRvd24pIHtcbiAgICAgIHRyeSB7XG4gICAgICAgIGF3YWl0IG9uU2h1dGRvd24oKTtcbiAgICAgIH0gY2F0Y2ggKGVycm9yKSB7XG4gICAgICAgIGxvZ2dlci5lcnJvcignRXJyb3IgaW4gb25TaHV0ZG93biBjYWxsYmFjaycsIHsgZXJyb3IgfSk7XG4gICAgICB9XG4gICAgfVxuXG4gICAgLy8gQ2xvc2UgU1NFIGNvbm5lY3Rpb25zXG4gICAgaWYgKHNzZU1hbmFnZXIpIHtcbiAgICAgIHNzZU1hbmFnZXIuc2h1dGRvd24oKTtcbiAgICAgIGxvZ2dlci5pbmZvKCdTU0UgY29ubmVjdGlvbnMgY2xvc2VkJyk7XG4gICAgfVxuXG4gICAgLy8gQ2xvc2UgSFRUUCBzZXJ2ZXJcbiAgICBzZXJ2ZXIuY2xvc2UoYXN5bmMgKCkgPT4ge1xuICAgICAgbG9nZ2VyLmluZm8oJ0hUVFAgc2VydmVyIGNsb3NlZCcpO1xuXG4gICAgICAvLyBTaHV0ZG93biBPcGVuVGVsZW1ldHJ5IHRyYWNpbmdcbiAgICAgIGF3YWl0IHNodXRkb3duVHJhY2luZygpLmNhdGNoKGVyciA9PiBsb2dnZXIuZXJyb3IoJ0Vycm9yIHNodXR0aW5nIGRvd24gdHJhY2luZycsIHsgZXJyb3I6IGVyciB9KSk7XG5cbiAgICAgIC8vIENsb3NlIGRhdGFiYXNlIGNvbm5lY3Rpb25cbiAgICAgIGlmIChjbG9zZURhdGFiYXNlICE9PSBmYWxzZSkge1xuICAgICAgICB0cnkge1xuICAgICAgICAgIGlmIChjbG9zZURhdGFiYXNlKSB7XG4gICAgICAgICAgICBhd2FpdCBjbG9zZURhdGFiYXNlKCk7XG4gICAgICAgICAgfSBlbHNlIHtcbiAgICAgICAgICAgIGF3YWl0IGNsb3NlQ29ubmVjdGlvbigpO1xuICAgICAgICAgIH1cbiAgICAgICAgICBsb2dnZXIuaW5mbygnRGF0YWJhc2UgY29ubmVjdGlvbiBjbG9zZWQnKTtcbiAgICAgICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgICAgICBsb2dnZXIuZXJyb3IoJ0Vycm9yIGNsb3NpbmcgZGF0YWJhc2UnLCB7IGVycm9yIH0pO1xuICAgICAgICB9XG4gICAgICB9XG5cbiAgICAgIHByb2Nlc3MuZXhpdCgwKTtcbiAgICB9KTtcblxuICAgIC8vIEZvcmNlIHNodXRkb3duIGFmdGVyIHRpbWVvdXRcbiAgICBzZXRUaW1lb3V0KCgpID0+IHtcbiAgICAgIGxvZ2dlci5lcnJvcignRm9yY2VkIHNodXRkb3duIGFmdGVyIHRpbWVvdXQnKTtcbiAgICAgIHByb2Nlc3MuZXhpdCgxKTtcbiAgICB9LCBzaHV0ZG93blRpbWVvdXRNcykudW5yZWYoKTtcbiAgfTtcblxuICAvLyBSZWdpc3RlciBzaWduYWwgaGFuZGxlcnNcbiAgcHJvY2Vzcy5vbmNlKCdTSUdJTlQnLCAoKSA9PiB2b2lkIHNodXRkb3duKCdTSUdJTlQnKSk7XG4gIHByb2Nlc3Mub25jZSgnU0lHVEVSTScsICgpID0+IHZvaWQgc2h1dGRvd24oJ1NJR1RFUk0nKSk7XG5cbiAgcmV0dXJuIHtcbiAgICBzZXJ2ZXIsXG4gICAgcG9ydCxcbiAgICBzaHV0ZG93bjogKCkgPT4gc2h1dGRvd24oKSxcbiAgfTtcbn1cblxuLyoqXG4gKiBTaW1wbGUgc2VydmVyIHN0YXJ0IHdyYXBwZXIgd2l0aCBlcnJvciBoYW5kbGluZ1xuICpcbiAqIEBwYXJhbSBhcHAgLSBFeHByZXNzIGFwcGxpY2F0aW9uXG4gKiBAcGFyYW0gb3B0aW9ucyAtIFNlcnZlciBvcHRpb25zXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGNvbnN0IHsgYXBwLCBzc2VNYW5hZ2VyIH0gPSBjcmVhdGVBcHAoKTtcbiAqIGFwcC5wb3N0KCcvYXBpL3Jlc291cmNlJywgaGFuZGxlcik7XG4gKlxuICogdm9pZCBydW5TZXJ2ZXIoYXBwLCB7IG5hbWU6ICdNeSBTZXJ2aWNlJywgc3NlTWFuYWdlciB9KTtcbiAqIGBgYFxuICovXG5leHBvcnQgZnVuY3Rpb24gcnVuU2VydmVyKGFwcDogRXhwcmVzcywgb3B0aW9uczogU3RhcnRTZXJ2ZXJPcHRpb25zID0ge30pOiB2b2lkIHtcbiAgc3RhcnRTZXJ2ZXIoYXBwLCBvcHRpb25zKS5jYXRjaCgoZXJyb3IpID0+IHtcbiAgICBsb2dnZXIuZXJyb3IoJ0ZhaWxlZCB0byBzdGFydCBzZXJ2ZXInLCB7IGVycm9yIH0pO1xuICAgIHByb2Nlc3MuZXhpdCgxKTtcbiAgfSk7XG59XG4iXX0=

package/lib/api/tracing.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Initialize OpenTelemetry tracing with OTLP HTTP exporter.
+ * Configured via `Config.get('observability').tracing`.
+ *
+ * @example
+ * ```typescript
+ * import { initTracing } from '@pipeline-builder/api-server';
+ * initTracing('pipeline-service');
+ * ```
+ */
+export declare function initTracing(serviceName: string): void;
+/**
+ * Shutdown the OpenTelemetry SDK gracefully.
+ */
+export declare function shutdownTracing(): Promise<void>;

package/lib/api/tracing.js

@@ -0,0 +1,53 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTracing = initTracing;
+exports.shutdownTracing = shutdownTracing;
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const resources_1 = require("@opentelemetry/resources");
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const api_core_1 = require("@pipeline-builder/api-core");
+const pipeline_core_1 = require("@pipeline-builder/pipeline-core");
+const logger = (0, api_core_1.createLogger)('Tracing');
+let sdk = null;
+/**
+ * Initialize OpenTelemetry tracing with OTLP HTTP exporter.
+ * Configured via `Config.get('observability').tracing`.
+ *
+ * @example
+ * ```typescript
+ * import { initTracing } from '@pipeline-builder/api-server';
+ * initTracing('pipeline-service');
+ * ```
+ */
+function initTracing(serviceName) {
+    const { tracing } = pipeline_core_1.Config.getAny('observability');
+    if (!tracing.enabled) {
+        logger.debug('OpenTelemetry tracing disabled (set OTEL_TRACING_ENABLED=true to enable)');
+        return;
+    }
+    if (sdk) {
+        logger.debug('OpenTelemetry already initialized');
+        return;
+    }
+    const exporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
+        url: tracing.endpoint,
+    });
+    sdk = new sdk_node_1.NodeSDK({
+        resource: (0, resources_1.resourceFromAttributes)({ 'service.name': serviceName }),
+        traceExporter: exporter,
+    });
+    sdk.start();
+    logger.info(`OpenTelemetry tracing initialized for ${serviceName}`);
+}
+/**
+ * Shutdown the OpenTelemetry SDK gracefully.
+ */
+async function shutdownTracing() {
+    if (sdk) {
+        await sdk.shutdown();
+        sdk = null;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2luZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9hcGkvdHJhY2luZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7QUFzQnRDLGtDQXdCQztBQUtELDBDQUtDO0FBdERELHNGQUE0RTtBQUM1RSx3REFBa0U7QUFDbEUsc0RBQWtEO0FBQ2xELHlEQUEwRDtBQUMxRCxtRUFBeUQ7QUFFekQsTUFBTSxNQUFNLEdBQUcsSUFBQSx1QkFBWSxFQUFDLFNBQVMsQ0FBQyxDQUFDO0FBRXZDLElBQUksR0FBRyxHQUFtQixJQUFJLENBQUM7QUFFL0I7Ozs7Ozs7OztHQVNHO0FBQ0gsU0FBZ0IsV0FBVyxDQUFDLFdBQW1CO0lBQzdDLE1BQU0sRUFBRSxPQUFPLEVBQUUsR0FBRyxzQkFBTSxDQUFDLE1BQU0sQ0FBQyxlQUFlLENBQXdELENBQUM7SUFFMUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxPQUFPLEVBQUUsQ0FBQztRQUNyQixNQUFNLENBQUMsS0FBSyxDQUFDLDBFQUEwRSxDQUFDLENBQUM7UUFDekYsT0FBTztJQUNULENBQUM7SUFFRCxJQUFJLEdBQUcsRUFBRSxDQUFDO1FBQ1IsTUFBTSxDQUFDLEtBQUssQ0FBQyxtQ0FBbUMsQ0FBQyxDQUFDO1FBQ2xELE9BQU87SUFDVCxDQUFDO0lBRUQsTUFBTSxRQUFRLEdBQUcsSUFBSSw0Q0FBaUIsQ0FBQztRQUNyQyxHQUFHLEVBQUUsT0FBTyxDQUFDLFFBQVE7S0FDdEIsQ0FBQyxDQUFDO0lBRUgsR0FBRyxHQUFHLElBQUksa0JBQU8sQ0FBQztRQUNoQixRQUFRLEVBQUUsSUFBQSxrQ0FBc0IsRUFBQyxFQUFFLGNBQWMsRUFBRSxXQUFXLEVBQUUsQ0FBQztRQUNqRSxhQUFhLEVBQUUsUUFBUTtLQUN4QixDQUFDLENBQUM7SUFFSCxHQUFHLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDWixNQUFNLENBQUMsSUFBSSxDQUFDLHlDQUF5QyxXQUFXLEVBQUUsQ0FBQyxDQUFDO0FBQ3RFLENBQUM7QUFFRDs7R0FFRztBQUNJLEtBQUssVUFBVSxlQUFlO0lBQ25DLElBQUksR0FBRyxFQUFFLENBQUM7UUFDUixNQUFNLEdBQUcsQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNyQixHQUFHLEdBQUcsSUFBSSxDQUFDO0lBQ2IsQ0FBQztBQUNILENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuaW1wb3J0IHsgT1RMUFRyYWNlRXhwb3J0ZXIgfSBmcm9tICdAb3BlbnRlbGVtZXRyeS9leHBvcnRlci10cmFjZS1vdGxwLWh0dHAnO1xuaW1wb3J0IHsgcmVzb3VyY2VGcm9tQXR0cmlidXRlcyB9IGZyb20gJ0BvcGVudGVsZW1ldHJ5L3Jlc291cmNlcyc7XG5pbXBvcnQgeyBOb2RlU0RLIH0gZnJvbSAnQG9wZW50ZWxlbWV0cnkvc2RrLW5vZGUnO1xuaW1wb3J0IHsgY3JlYXRlTG9nZ2VyIH0gZnJvbSAnQHBpcGVsaW5lLWJ1aWxkZXIvYXBpLWNvcmUnO1xuaW1wb3J0IHsgQ29uZmlnIH0gZnJvbSAnQHBpcGVsaW5lLWJ1aWxkZXIvcGlwZWxpbmUtY29yZSc7XG5cbmNvbnN0IGxvZ2dlciA9IGNyZWF0ZUxvZ2dlcignVHJhY2luZycpO1xuXG5sZXQgc2RrOiBOb2RlU0RLIHwgbnVsbCA9IG51bGw7XG5cbi8qKlxuICogSW5pdGlhbGl6ZSBPcGVuVGVsZW1ldHJ5IHRyYWNpbmcgd2l0aCBPVExQIEhUVFAgZXhwb3J0ZXIuXG4gKiBDb25maWd1cmVkIHZpYSBgQ29uZmlnLmdldCgnb2JzZXJ2YWJpbGl0eScpLnRyYWNpbmdgLlxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBpbXBvcnQgeyBpbml0VHJhY2luZyB9IGZyb20gJ0BwaXBlbGluZS1idWlsZGVyL2FwaS1zZXJ2ZXInO1xuICogaW5pdFRyYWNpbmcoJ3BpcGVsaW5lLXNlcnZpY2UnKTtcbiAqIGBgYFxuICovXG5leHBvcnQgZnVuY3Rpb24gaW5pdFRyYWNpbmcoc2VydmljZU5hbWU6IHN0cmluZyk6IHZvaWQge1xuICBjb25zdCB7IHRyYWNpbmcgfSA9IENvbmZpZy5nZXRBbnkoJ29ic2VydmFiaWxpdHknKSBhcyB7IHRyYWNpbmc6IHsgZW5hYmxlZDogYm9vbGVhbjsgZW5kcG9pbnQ6IHN0cmluZyB9IH07XG5cbiAgaWYgKCF0cmFjaW5nLmVuYWJsZWQpIHtcbiAgICBsb2dnZXIuZGVidWcoJ09wZW5UZWxlbWV0cnkgdHJhY2luZyBkaXNhYmxlZCAoc2V0IE9URUxfVFJBQ0lOR19FTkFCTEVEPXRydWUgdG8gZW5hYmxlKScpO1xuICAgIHJldHVybjtcbiAgfVxuXG4gIGlmIChzZGspIHtcbiAgICBsb2dnZXIuZGVidWcoJ09wZW5UZWxlbWV0cnkgYWxyZWFkeSBpbml0aWFsaXplZCcpO1xuICAgIHJldHVybjtcbiAgfVxuXG4gIGNvbnN0IGV4cG9ydGVyID0gbmV3IE9UTFBUcmFjZUV4cG9ydGVyKHtcbiAgICB1cmw6IHRyYWNpbmcuZW5kcG9pbnQsXG4gIH0pO1xuXG4gIHNkayA9IG5ldyBOb2RlU0RLKHtcbiAgICByZXNvdXJjZTogcmVzb3VyY2VGcm9tQXR0cmlidXRlcyh7ICdzZXJ2aWNlLm5hbWUnOiBzZXJ2aWNlTmFtZSB9KSxcbiAgICB0cmFjZUV4cG9ydGVyOiBleHBvcnRlcixcbiAgfSk7XG5cbiAgc2RrLnN0YXJ0KCk7XG4gIGxvZ2dlci5pbmZvKGBPcGVuVGVsZW1ldHJ5IHRyYWNpbmcgaW5pdGlhbGl6ZWQgZm9yICR7c2VydmljZU5hbWV9YCk7XG59XG5cbi8qKlxuICogU2h1dGRvd24gdGhlIE9wZW5UZWxlbWV0cnkgU0RLIGdyYWNlZnVsbHkuXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBzaHV0ZG93blRyYWNpbmcoKTogUHJvbWlzZTx2b2lkPiB7XG4gIGlmIChzZGspIHtcbiAgICBhd2FpdCBzZGsuc2h1dGRvd24oKTtcbiAgICBzZGsgPSBudWxsO1xuICB9XG59XG4iXX0=

package/lib/http/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sse-connection-manager';
+export * from './ws-manager';

package/lib/http/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./sse-connection-manager"), exports);
+__exportStar(require("./ws-manager"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaHR0cC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUEsK0NBQStDO0FBQy9DLHNDQUFzQzs7Ozs7Ozs7Ozs7Ozs7OztBQUV0QywyREFBeUM7QUFDekMsK0NBQTZCIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQ29weXJpZ2h0IDIwMjYgUGlwZWxpbmUgQnVpbGRlciBDb250cmlidXRvcnNcbi8vIFNQRFgtTGljZW5zZS1JZGVudGlmaWVyOiBBcGFjaGUtMi4wXG5cbmV4cG9ydCAqIGZyb20gJy4vc3NlLWNvbm5lY3Rpb24tbWFuYWdlcic7XG5leHBvcnQgKiBmcm9tICcuL3dzLW1hbmFnZXInO1xuIl19

package/lib/http/sse-connection-manager.d.ts

@@ -0,0 +1,145 @@
+import { Response } from 'express';
+/**
+ * Event types for SSE logging
+ */
+export type SSEEventType = 'INFO' | 'WARN' | 'ERROR' | 'COMPLETED' | 'ROLLBACK' | 'MESSAGE';
+/**
+ * SSE payload structure
+ */
+export interface SSEPayload {
+    ts: string;
+    type: SSEEventType;
+    message: string;
+    data?: unknown;
+}
+/**
+ * SSE client with connection tracking
+ */
+export interface SSEClient {
+    id: string;
+    res: Response;
+    connectedAt: number;
+    timeout: NodeJS.Timeout;
+    /** Number of consecutive backpressure events (write returned false). */
+    backpressureCount: number;
+}
+/**
+ * SSE Manager configuration options
+ */
+export interface SSEManagerOptions {
+    /** Maximum clients allowed per request ID (default: 10) */
+    maxClientsPerRequest?: number;
+    /** Client timeout in milliseconds (default: 30 minutes) */
+    clientTimeoutMs?: number;
+    /** Interval for cleanup checks in milliseconds (default: 5 minutes) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * SSE Manager statistics
+ */
+export interface SSEManagerStats {
+    totalRequests: number;
+    totalClients: number;
+    oldestConnectionMs: number | null;
+}
+/**
+ * SSE helper class with memory leak protection
+ *
+ * Features:
+ * - Client limits per request ID
+ * - Automatic timeout for idle connections
+ * - Periodic cleanup of stale connections
+ * - Connection statistics
+ *
+ * @example
+ * ```typescript
+ * const sseManager = new SSEManager({ maxClientsPerRequest: 5 });
+ * app.get('/logs/:requestId', sseManager.middleware());
+ *
+ * // Send events
+ * sseManager.send('request-123', 'INFO', 'Processing...');
+ * ```
+ */
+export declare class SSEManager {
+    private clients;
+    private readonly maxClientsPerRequest;
+    private readonly clientTimeoutMs;
+    private cleanupInterval;
+    constructor(options?: SSEManagerOptions);
+    /**
+     * Adds a client to the SSE manager
+     *
+     * @param requestId - Unique request ID
+     * @param res - Express Response object
+     * @returns true if client was added, false if rejected (limit reached)
+     */
+    addClient(requestId: string, res: Response): boolean;
+    /**
+     * Removes a client from the manager
+     */
+    private removeClient;
+    /**
+     * Sends a message to all SSE clients for a requestId
+     *
+     * @param requestId - Request ID
+     * @param type - Event type
+     * @param message - Message string
+     * @param data - Optional additional data
+     * @returns Number of clients the message was sent to
+     */
+    send(requestId: string, type: SSEEventType, message: string, data?: unknown): number;
+    /**
+     * Broadcast a message to all connected clients across all requests
+     *
+     * @param type - Event type
+     * @param message - Message string
+     * @param data - Optional additional data
+     * @returns Total number of clients the message was sent to
+     */
+    broadcast(type: SSEEventType, message: string, data?: unknown): number;
+    /**
+     * Close all clients for a specific request
+     *
+     * @param requestId - Request ID to close
+     * @param finalMessage - Optional final message to send before closing
+     */
+    closeRequest(requestId: string, finalMessage?: string): void;
+    /**
+     * Get statistics about current connections
+     */
+    getStats(): SSEManagerStats;
+    /**
+     * Check if a request has any connected clients
+     */
+    hasClients(requestId: string): boolean;
+    /**
+     * Get the number of clients for a specific request
+     */
+    getClientCount(requestId: string): number;
+    /**
+     * Middleware to initialize SSE connection
+     *
+     * @example
+     * ```typescript
+     * app.get('/logs/:requestId', sseManager.middleware());
+     * ```
+     */
+    middleware(): (req: {
+        params: {
+            requestId: string;
+        };
+    }, res: Response) => void;
+    /**
+     * Start periodic cleanup of stale connections
+     */
+    private startCleanupInterval;
+    /**
+     * Clean up stale connections using single-pass partition.
+     * O(R × C) instead of O(R × C²), and avoids mutation-during-iteration.
+     */
+    private cleanup;
+    /**
+     * Shutdown the SSE manager and close all connections
+     */
+    shutdown(): void;
+}