@expressive-tea/core 2.0.0

package/engines/health/index.d.ts

@@ -0,0 +1,120 @@
+import ExpressiveTeaEngine from '../../classes/Engine';
+/**
+ * Health check status
+ * @since 2.0.0
+ */
+export type HealthStatus = 'pass' | 'fail' | 'warn';
+/**
+ * Individual health check result
+ * @since 2.0.0
+ */
+export interface HealthCheckResult {
+    /** Check status */
+    status: HealthStatus;
+    /** Optional details about the check */
+    details?: Record<string, any>;
+    /** Optional error message if failed */
+    error?: string;
+}
+/**
+ * Health check function
+ * @since 2.0.0
+ */
+export type HealthCheckFunction = () => Promise<HealthCheckResult> | HealthCheckResult;
+/**
+ * Health check definition
+ * @since 2.0.0
+ */
+export interface HealthCheck {
+    /** Unique name for this health check */
+    name: string;
+    /** The check function to execute */
+    check: HealthCheckFunction;
+    /** Whether this check is critical for readiness */
+    critical?: boolean;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Health Check Engine
+ *
+ * Provides standardized health check endpoints for monitoring and orchestration:
+ * - `/health` - Detailed health status with all checks
+ * - `/health/live` - Liveness probe (always 200 if server is running)
+ * - `/health/ready` - Readiness probe (200 only if all critical checks pass)
+ *
+ * Compatible with Kubernetes liveness and readiness probes.
+ *
+ * @class HealthCheckEngine
+ * @extends ExpressiveTeaEngine
+ * @since 2.0.0
+ * @summary Standardized health check endpoints for monitoring
+ *
+ * @example
+ * // Enable health checks with custom checks
+ * @HealthCheck({
+ *   checks: [
+ *     {
+ *       name: 'database',
+ *       check: async () => {
+ *         const isConnected = await db.ping();
+ *         return { status: isConnected ? 'pass' : 'fail' };
+ *       },
+ *       critical: true,
+ *       timeout: 5000
+ *     },
+ *     {
+ *       name: 'cache',
+ *       check: async () => {
+ *         const isReady = await redis.ping();
+ *         return {
+ *           status: isReady ? 'pass' : 'warn',
+ *           details: { connected: isReady }
+ *         };
+ *       }
+ *     }
+ *   ]
+ * })
+ * class MyApp extends Boot {}
+ */
+export default class HealthCheckEngine extends ExpressiveTeaEngine {
+    private checks;
+    /**
+     * Register a health check
+     * @param check - Health check configuration
+     * @since 2.0.0
+     */
+    registerCheck(check: HealthCheck): void;
+    /**
+     * Execute a single health check with timeout
+     * @param check - Health check to execute
+     * @returns Check result
+     * @private
+     */
+    private executeCheck;
+    /**
+     * Initialize health check routes
+     * @since 2.0.0
+     */
+    init(): Promise<void>;
+    /**
+     * Start the health check engine
+     * @since 2.0.0
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the health check engine
+     * @since 2.0.0
+     */
+    stop(): Promise<void>;
+    /**
+     * Determine if this engine should be registered
+     *
+     * Health checks are enabled by default for all applications.
+     * To disable, set `enableHealthChecks: false` in ServerSettings.
+     *
+     * @returns true if health checks should be enabled
+     * @since 2.0.0
+     */
+    static canRegister(): boolean;
+}

package/engines/health/index.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const Engine_1 = require("../../classes/Engine");
+/**
+ * Health Check Engine
+ *
+ * Provides standardized health check endpoints for monitoring and orchestration:
+ * - `/health` - Detailed health status with all checks
+ * - `/health/live` - Liveness probe (always 200 if server is running)
+ * - `/health/ready` - Readiness probe (200 only if all critical checks pass)
+ *
+ * Compatible with Kubernetes liveness and readiness probes.
+ *
+ * @class HealthCheckEngine
+ * @extends ExpressiveTeaEngine
+ * @since 2.0.0
+ * @summary Standardized health check endpoints for monitoring
+ *
+ * @example
+ * // Enable health checks with custom checks
+ * @HealthCheck({
+ *   checks: [
+ *     {
+ *       name: 'database',
+ *       check: async () => {
+ *         const isConnected = await db.ping();
+ *         return { status: isConnected ? 'pass' : 'fail' };
+ *       },
+ *       critical: true,
+ *       timeout: 5000
+ *     },
+ *     {
+ *       name: 'cache',
+ *       check: async () => {
+ *         const isReady = await redis.ping();
+ *         return {
+ *           status: isReady ? 'pass' : 'warn',
+ *           details: { connected: isReady }
+ *         };
+ *       }
+ *     }
+ *   ]
+ * })
+ * class MyApp extends Boot {}
+ */
+let HealthCheckEngine = class HealthCheckEngine extends Engine_1.default {
+    constructor() {
+        super(...arguments);
+        this.checks = [];
+    }
+    /**
+     * Register a health check
+     * @param check - Health check configuration
+     * @since 2.0.0
+     */
+    registerCheck(check) {
+        this.checks.push(check);
+    }
+    /**
+     * Execute a single health check with timeout
+     * @param check - Health check to execute
+     * @returns Check result
+     * @private
+     */
+    async executeCheck(check) {
+        const timeout = check.timeout || 5000;
+        try {
+            const result = await Promise.race([
+                Promise.resolve(check.check()),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Health check timeout')), timeout)),
+            ]);
+            return result;
+        }
+        catch (error) {
+            return {
+                status: 'fail',
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Initialize health check routes
+     * @since 2.0.0
+     */
+    async init() {
+        const app = this.context.getApplication();
+        // Detailed health endpoint
+        app.get('/health', async (_req, res) => {
+            const results = {};
+            let overallStatus = 'pass';
+            // Execute all checks in parallel
+            await Promise.all(this.checks.map(async (check) => {
+                const result = await this.executeCheck(check);
+                results[check.name] = result;
+                // Update overall status
+                if (result.status === 'fail') {
+                    overallStatus = 'fail';
+                }
+                else if (result.status === 'warn' && overallStatus === 'pass') {
+                    overallStatus = 'warn';
+                }
+            }));
+            const statusCode = overallStatus === 'pass' ? 200 : overallStatus === 'warn' ? 200 : 503;
+            res.status(statusCode).json({
+                status: overallStatus,
+                timestamp: new Date().toISOString(),
+                checks: results,
+            });
+        });
+        // Liveness probe - always returns 200 if server is running
+        app.get('/health/live', (_req, res) => {
+            res.status(200).json({
+                status: 'pass',
+                timestamp: new Date().toISOString(),
+            });
+        });
+        // Readiness probe - returns 200 only if all critical checks pass
+        app.get('/health/ready', async (_req, res) => {
+            const criticalChecks = this.checks.filter((c) => c.critical);
+            if (criticalChecks.length === 0) {
+                // No critical checks, always ready
+                res.status(200).json({
+                    status: 'pass',
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            const results = {};
+            let isReady = true;
+            // Execute only critical checks
+            await Promise.all(criticalChecks.map(async (check) => {
+                const result = await this.executeCheck(check);
+                results[check.name] = result;
+                if (result.status === 'fail') {
+                    isReady = false;
+                }
+            }));
+            res.status(isReady ? 200 : 503).json({
+                status: isReady ? 'pass' : 'fail',
+                timestamp: new Date().toISOString(),
+                checks: results,
+            });
+        });
+    }
+    /**
+     * Start the health check engine
+     * @since 2.0.0
+     */
+    async start() {
+        // Nothing to start - routes are already registered
+    }
+    /**
+     * Stop the health check engine
+     * @since 2.0.0
+     */
+    async stop() {
+        // Clear checks on shutdown
+        this.checks = [];
+    }
+    /**
+     * Determine if this engine should be registered
+     *
+     * Health checks are enabled by default for all applications.
+     * To disable, set `enableHealthChecks: false` in ServerSettings.
+     *
+     * @returns true if health checks should be enabled
+     * @since 2.0.0
+     */
+    static canRegister() {
+        return true;
+    }
+};
+HealthCheckEngine = tslib_1.__decorate([
+    (0, inversify_1.injectable)(),
+    (0, inversify_1.injectFromBase)({ extendConstructorArguments: true })
+], HealthCheckEngine);
+exports.default = HealthCheckEngine;

package/engines/http/index.d.ts

@@ -0,0 +1,12 @@
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { BOOT_STAGES } from '@expressive-tea/commons';
+import ExpressiveTeaEngine from '../../classes/Engine';
+export default class HTTPEngine extends ExpressiveTeaEngine {
+    private listen;
+    start(): Promise<(http.Server | https.Server)[]>;
+    init(): Promise<void>;
+    resolveStages(stages: BOOT_STAGES[], ...extraArgs: unknown[]): Promise<unknown[]>;
+    resolveProxyContainers(): void;
+    static canRegister(): boolean;
+}

package/engines/http/index.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const boot_helper_1 = require("../../helpers/boot-helper");
+const commons_1 = require("@expressive-tea/commons");
+const commons_2 = require("@expressive-tea/commons");
+const commons_3 = require("@expressive-tea/commons");
+const Engine_1 = require("../../classes/Engine");
+let HTTPEngine = class HTTPEngine extends Engine_1.default {
+    async listen(server, port) {
+        return new Promise((resolve, reject) => {
+            server.listen(port);
+            server.on('error', error => {
+                reject(error);
+            });
+            server.on('listening', () => {
+                console.log(`Running HTTP Server on [${port}]`);
+                resolve(server);
+            });
+        });
+    }
+    async start() {
+        const servers = [
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            await this.listen(this.server, this.settings.get('port')),
+            (this.serverSecure) ? await this.listen(this.serverSecure, this.settings.get('securePort')) : null
+        ];
+        const listenerServers = servers.filter((server) => server !== null);
+        await this.resolveStages([commons_1.BOOT_STAGES.START], ...listenerServers);
+        return listenerServers;
+    }
+    async init() {
+        (0, boot_helper_1.resolveDirectives)(this.context, this.context.getApplication());
+        (0, boot_helper_1.resolveStatic)(this.context, this.context.getApplication());
+        // HTTP Engine Resolve Stages
+        this.resolveProxyContainers();
+        await this.resolveStages(commons_1.BOOT_ORDER);
+        await this.resolveStages([commons_1.BOOT_STAGES.AFTER_APPLICATION_MIDDLEWARES, commons_1.BOOT_STAGES.ON_HTTP_CREATION], this.server, this.serverSecure);
+    }
+    async resolveStages(stages, ...extraArgs) {
+        return Promise.all(stages.map(async (s) => (0, boot_helper_1.resolveStage)(s, this.context, this.context.getApplication(), ...extraArgs)));
+    }
+    resolveProxyContainers() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const ProxyContainers = commons_3.Metadata.get(commons_1.ROUTER_PROXIES_KEY, (0, commons_2.getClass)(this.context)) || [];
+        for (const Container of ProxyContainers) {
+            (0, boot_helper_1.resolveProxy)(Container, this.context.getApplication());
+        }
+    }
+    static canRegister() {
+        return true;
+    }
+};
+HTTPEngine = tslib_1.__decorate([
+    (0, inversify_1.injectable)(),
+    (0, inversify_1.injectFromBase)({ extendConstructorArguments: true })
+], HTTPEngine);
+exports.default = HTTPEngine;

package/engines/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Core Engine Registration
+ *
+ * Automatically registers all core Expressive Tea engines with the EngineRegistry.
+ * Import this file to enable all core engines with proper dependency order.
+ *
+ * Engine Priority Order:
+ * - 0: HTTPEngine (base engine, no dependencies)
+ * - 5: HealthCheckEngine (health endpoints, depends on http)
+ * - 10: SocketIOEngine, WebsocketEngine (depend on http)
+ * - 20: TeapotEngine, TeacupEngine (depend on http, socketio)
+ *
+ * @example
+ * ```typescript
+ * import '@expressive-tea/core/engines'; // Registers all core engines
+ * import Boot from '@expressive-tea/core';
+ *
+ * class MyApp extends Boot {}
+ * ```
+ *
+ * @module engines
+ * @since 2.0.0
+ */
+import EngineRegistry from '../classes/EngineRegistry';
+import HTTPEngine from './http';
+import HealthCheckEngine from './health';
+import SocketIOEngine from './socketio';
+import WebsocketEngine from './websocket';
+import TeapotEngine from './teapot';
+import TeacupEngine from './teacup';
+export { HTTPEngine, HealthCheckEngine, SocketIOEngine, WebsocketEngine, TeapotEngine, TeacupEngine };
+export default EngineRegistry;

package/engines/index.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Core Engine Registration
+ *
+ * Automatically registers all core Expressive Tea engines with the EngineRegistry.
+ * Import this file to enable all core engines with proper dependency order.
+ *
+ * Engine Priority Order:
+ * - 0: HTTPEngine (base engine, no dependencies)
+ * - 5: HealthCheckEngine (health endpoints, depends on http)
+ * - 10: SocketIOEngine, WebsocketEngine (depend on http)
+ * - 20: TeapotEngine, TeacupEngine (depend on http, socketio)
+ *
+ * @example
+ * ```typescript
+ * import '@expressive-tea/core/engines'; // Registers all core engines
+ * import Boot from '@expressive-tea/core';
+ *
+ * class MyApp extends Boot {}
+ * ```
+ *
+ * @module engines
+ * @since 2.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeacupEngine = exports.TeapotEngine = exports.WebsocketEngine = exports.SocketIOEngine = exports.HealthCheckEngine = exports.HTTPEngine = void 0;
+const EngineRegistry_1 = require("../classes/EngineRegistry");
+const http_1 = require("./http");
+exports.HTTPEngine = http_1.default;
+const health_1 = require("./health");
+exports.HealthCheckEngine = health_1.default;
+const socketio_1 = require("./socketio");
+exports.SocketIOEngine = socketio_1.default;
+const websocket_1 = require("./websocket");
+exports.WebsocketEngine = websocket_1.default;
+const teapot_1 = require("./teapot");
+exports.TeapotEngine = teapot_1.default;
+const teacup_1 = require("./teacup");
+exports.TeacupEngine = teacup_1.default;
+/**
+ * Register HTTP Engine
+ * Priority: 0 (runs first)
+ * Dependencies: none
+ */
+EngineRegistry_1.default.register({
+    engine: http_1.default,
+    name: 'http',
+    version: '2.0.0',
+    priority: 0,
+    dependencies: []
+});
+/**
+ * Register Health Check Engine
+ * Priority: 5
+ * Dependencies: http (needs HTTP server for endpoints)
+ */
+EngineRegistry_1.default.register({
+    engine: health_1.default,
+    name: 'health',
+    version: '2.0.0',
+    priority: 5,
+    dependencies: ['http']
+});
+/**
+ * Register SocketIO Engine
+ * Priority: 10
+ * Dependencies: http (needs HTTP server to attach to)
+ */
+EngineRegistry_1.default.register({
+    engine: socketio_1.default,
+    name: 'socketio',
+    version: '2.0.0',
+    priority: 10,
+    dependencies: ['http']
+});
+/**
+ * Register Websocket Engine
+ * Priority: 10
+ * Dependencies: http (needs HTTP server to attach to)
+ */
+EngineRegistry_1.default.register({
+    engine: websocket_1.default,
+    name: 'websocket',
+    version: '2.0.0',
+    priority: 10,
+    dependencies: ['http']
+});
+/**
+ * Register Teapot Engine (Microservice Gateway Server)
+ * Priority: 20
+ * Dependencies: http, socketio
+ */
+EngineRegistry_1.default.register({
+    engine: teapot_1.default,
+    name: 'teapot',
+    version: '2.0.0',
+    priority: 20,
+    dependencies: ['http', 'socketio']
+});
+/**
+ * Register Teacup Engine (Microservice Gateway Client)
+ * Priority: 20
+ * Dependencies: http, socketio
+ */
+EngineRegistry_1.default.register({
+    engine: teacup_1.default,
+    name: 'teacup',
+    version: '2.0.0',
+    priority: 20,
+    dependencies: ['http', 'socketio']
+});
+exports.default = EngineRegistry_1.default;

package/engines/socketio/index.d.ts

@@ -0,0 +1,7 @@
+import ExpressiveTeaEngine from '../../classes/Engine';
+export default class SocketIOEngine extends ExpressiveTeaEngine {
+    private io;
+    private ioSecure;
+    init(): void;
+    static canRegister(): boolean;
+}

package/engines/socketio/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const socket_io_1 = require("socket.io");
+const inversify_1 = require("inversify");
+const Engine_1 = require("../../classes/Engine");
+const commons_1 = require("@expressive-tea/commons");
+const constants_1 = require("../constants/constants");
+let SocketIOEngine = class SocketIOEngine extends Engine_1.default {
+    init() {
+        const commonConfig = {
+            path: '/exp-tea/',
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            transports: ['websocket', 'polling']
+        };
+        this.io = this.server && new socket_io_1.Server(this.server, Object.assign({}, commonConfig));
+        this.ioSecure = this.serverSecure && new socket_io_1.Server(this.serverSecure, Object.assign({}, commonConfig));
+        commons_1.Metadata.set(constants_1.SOCKET_IO_INSTANCE_KEY, this.io, this.context);
+        commons_1.Metadata.set(constants_1.SOCKET_IO_SECURE_INSTANCE_KEY, this.ioSecure, this.context);
+    }
+    static canRegister() {
+        return true;
+    }
+};
+SocketIOEngine = tslib_1.__decorate([
+    (0, inversify_1.injectable)(),
+    (0, inversify_1.injectFromBase)({ extendConstructorArguments: true })
+], SocketIOEngine);
+exports.default = SocketIOEngine;
+;

package/engines/teacup/index.d.ts

@@ -0,0 +1,27 @@
+import ExpressiveTeaEngine from '../../classes/Engine';
+import Boot from '../../classes/Boot';
+export default class TeacupEngine extends ExpressiveTeaEngine {
+    private teacupSettings;
+    private publicKey;
+    private privateKey;
+    private publicServerKey;
+    private serverSignature;
+    private clientSignature;
+    private client;
+    private isStopping;
+    private header;
+    private handshaked;
+    private accepted;
+    start(): Promise<void>;
+    static canRegister(ctx?: Boot): boolean;
+    /**
+     * Graceful shutdown for TeacupEngine
+     *
+     * Disconnects the socket.io-client connection and prevents automatic reconnection.
+     * This method is idempotent and safe to call multiple times.
+     *
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     * @since 2.0.0
+     */
+    stop(): Promise<void>;
+}