@zintrust/core 0.1.28 → 0.1.29

package/src/microservices/MicroserviceManager.js

@@ -0,0 +1,268 @@
+/**
+ * Microservices Architecture for ZinTrust Framework
+ * Sealed namespace pattern with immutable microservice management
+ */
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { validateUrl } from '../security/UrlValidator.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+const services = new Map();
+let instance;
+let basePort = 3000;
+let nextPortOffset = 0;
+function normalizeEnabledServices() {
+    return getEnabledServices();
+}
+function isServiceEnabledByEnv(serviceName) {
+    const enabled = normalizeEnabledServices();
+    if (enabled.length === 0) {
+        return true;
+    }
+    // If SERVICES is set, treat it as an allow-list.
+    return enabled.includes(serviceName);
+}
+function toCallOptions(pathOrOptions, options) {
+    if (typeof pathOrOptions === 'string') {
+        return {
+            method: 'GET',
+            path: pathOrOptions,
+            headers: options?.['headers'] ?? undefined,
+            body: options?.['body'],
+            timeout: options?.['timeout'] ?? undefined,
+        };
+    }
+    return {
+        method: pathOrOptions['method'] ?? 'GET',
+        path: pathOrOptions['path'],
+        headers: pathOrOptions['headers'] ?? undefined,
+        body: pathOrOptions['body'],
+        timeout: pathOrOptions['timeout'] ?? undefined,
+    };
+}
+// Plain functions (will be sealed below)
+const create = () => {
+    return getMicroserviceManager().create();
+};
+const getInstance = () => {
+    instance ??= getMicroserviceManager();
+    return instance;
+};
+const reset = () => {
+    services.clear();
+    instance = undefined;
+    basePort = 3000;
+    nextPortOffset = 0;
+};
+const initialize = (configs = [], initBasePort = 3000) => {
+    instance ??= getMicroserviceManager();
+    basePort = initBasePort;
+    nextPortOffset = 0;
+    for (const config of configs) {
+        registerService(config);
+    }
+    return getMicroserviceManager();
+};
+const register = (config) => {
+    return registerService(config);
+};
+const registerService = (config) => {
+    if (isServiceEnabledByEnv(config.name) === false) {
+        Logger.info(`Service ${config.name} not in SERVICES env; skipping registration`);
+        return null;
+    }
+    const assignedPort = config.port ?? basePort + nextPortOffset;
+    nextPortOffset += 1;
+    const healthCheckUrl = typeof config.healthCheck === 'string'
+        ? config.healthCheck
+        : (config.healthCheckUrl ?? '/health');
+    const serviceConfig = {
+        ...config,
+        port: assignedPort,
+        baseUrl: config.baseUrl ?? `http://localhost:${assignedPort}`,
+        healthCheckUrl,
+        status: config.status ?? 'starting',
+    };
+    services.set(serviceConfig.name, serviceConfig);
+    Logger.info(`Registered microservice: ${serviceConfig.name}`);
+    return serviceConfig;
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const startService = async (name, _handler) => {
+    const service = services.get(name);
+    if (service === undefined) {
+        throw ErrorFactory.createNotFoundError('Service not found', { name });
+    }
+    service.status = 'running';
+    Logger.info(`Service started: ${name}`);
+    return true;
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const stopService = async (name) => {
+    const service = services.get(name);
+    if (service === undefined) {
+        return false;
+    }
+    service.status = 'stopped';
+    Logger.info(`Service stopped: ${name}`);
+    return true;
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const stopAllServices = async () => {
+    Logger.info('Stopping all microservices...');
+    for (const service of services.values()) {
+        service.status = 'stopped';
+    }
+};
+const getService = (domain, name) => {
+    const service = services.get(name);
+    if (service === undefined) {
+        return undefined;
+    }
+    return service.domain === domain ? service : undefined;
+};
+const getAllServices = () => {
+    return Array.from(services.values());
+};
+const getServicesByDomain = (domain) => {
+    return Array.from(services.values()).filter((s) => s.domain === domain);
+};
+const callService = async (name, pathOrOptions, options) => {
+    const service = services.get(name);
+    if (service === undefined) {
+        throw ErrorFactory.createNotFoundError('Service not found', { name });
+    }
+    if (service.status !== 'running') {
+        throw ErrorFactory.createConnectionError('Service not running', {
+            name,
+            status: service.status,
+        });
+    }
+    const callOptions = toCallOptions(pathOrOptions, options);
+    const path = callOptions.path ?? '/';
+    const method = (callOptions.method ?? 'GET').toUpperCase();
+    const resolvedBaseUrl = service.baseUrl ?? `http://localhost:${service.port ?? basePort}`;
+    const url = `${resolvedBaseUrl}${path}`;
+    validateUrl(url);
+    const controller = new AbortController();
+    const timeoutMs = callOptions.timeout;
+    let timeoutId;
+    if (typeof timeoutMs === 'number') {
+        // eslint-disable-next-line no-restricted-syntax
+        timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    }
+    try {
+        const init = {
+            method,
+            headers: callOptions.headers,
+            signal: controller.signal,
+        };
+        if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
+            init.body = JSON.stringify(callOptions.body ?? {});
+        }
+        const response = await globalThis.fetch(url, init);
+        const data = await response.json().catch(() => ({}));
+        return {
+            statusCode: response.status,
+            data,
+        };
+    }
+    catch (error) {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+        throw ErrorFactory.createTryCatchError('Failed to call service', error);
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+};
+const checkServiceHealth = async (name) => {
+    const service = services.get(name);
+    if (service === undefined) {
+        return false;
+    }
+    const healthPath = service.healthCheckUrl ?? '/health';
+    const resolvedBaseUrl = service.baseUrl ?? `http://localhost:${service.port ?? basePort}`;
+    const url = `${resolvedBaseUrl}${healthPath}`;
+    validateUrl(url);
+    try {
+        const response = await globalThis.fetch(url, { method: 'GET' });
+        const healthy = response.ok === true;
+        service.lastHealthCheck = Date.now();
+        return healthy;
+    }
+    catch (error) {
+        service.lastHealthCheck = Date.now();
+        const message = error instanceof Error ? error.message : String(error);
+        Logger.error('Health check failed', message);
+        return false;
+    }
+};
+const healthCheckAll = async () => {
+    const names = Array.from(services.keys());
+    const entries = await Promise.all(names.map(async (name) => [name, await checkServiceHealth(name)]));
+    return Object.fromEntries(entries);
+};
+const getStatusSummary = () => {
+    const allServices = Array.from(services.values());
+    const runningServices = allServices.filter((s) => s.status === 'running').length;
+    return {
+        totalServices: allServices.length,
+        runningServices,
+        services: allServices.map((s) => ({
+            name: s.name,
+            domain: s.domain,
+            version: s.version,
+            status: s.status,
+            lastHealthCheck: s.lastHealthCheck,
+        })),
+        timestamp: Date.now(),
+    };
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const discoverServices = async () => {
+    return Array.from(services.values());
+};
+const getMicroserviceManager = () => MicroserviceManager;
+export const MicroserviceManager = Object.freeze({
+    create,
+    getInstance,
+    reset,
+    initialize,
+    register,
+    registerService,
+    startService,
+    stopService,
+    stopAllServices,
+    getService,
+    getAllServices,
+    getServicesByDomain,
+    callService,
+    checkServiceHealth,
+    healthCheckAll,
+    getStatusSummary,
+    discoverServices,
+});
+export function isMicroservicesEnabled() {
+    const direct = (Env.get('MICROSERVICES') ?? '').trim();
+    if (direct.toLowerCase() === 'true') {
+        return true;
+    }
+    // Fallback flag used in tests/legacy setups.
+    return Env.getBool('ENABLE_MICROSERVICES', false);
+}
+export function getEnabledServices() {
+    const raw = (Env.get('SERVICES') ?? '').trim();
+    if (raw.length === 0) {
+        return [];
+    }
+    return raw
+        .split(',')
+        .map((service) => service.trim())
+        .filter((service) => service.length > 0);
+}
+// Re-export functions for backward compatibility
+export { callService, checkServiceHealth, create, discoverServices, getAllServices, getInstance, getService, getServicesByDomain, getStatusSummary, healthCheckAll, initialize, register, registerService, reset, startService, stopAllServices, stopService, };
+export default MicroserviceManager;

package/src/microservices/PostgresAdapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Minimal interfaces for PostgreSQL to avoid direct dependency on 'pg' types
+ */
+export interface PostgresPool {
+    connect(): Promise<PostgresClient>;
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+        rowCount?: number;
+    }>;
+    end(): Promise<void>;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    totalCount: number;
+    idleCount: number;
+    waitingCount: number;
+}
+export interface PostgresClient {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+        rowCount?: number;
+    }>;
+    release(): void;
+}
+export type PoolClient = PostgresClient;
+/**
+ * PostgreSQL Connection Pool Configuration
+ */
+export interface PostgresPoolConfig {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    max?: number;
+    idleTimeoutMillis?: number;
+    connectionTimeoutMillis?: number;
+    serviceName?: string;
+    isolation?: 'shared' | 'isolated';
+}
+export interface IPostgresAdapter {
+    getPoolKey(): string;
+    connect(): Promise<void>;
+    getPool(): PostgresPool;
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    execute<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        rowCount: number;
+    }>;
+    transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>;
+    getPoolStats(): {
+        totalConnections: number;
+        idleConnections: number;
+        waitingRequests: number;
+    };
+    disconnect(): Promise<void>;
+    disconnectAll(): Promise<void>;
+    createServiceSchema(schemaName: string): Promise<void>;
+    runMigrations(migrations: Array<{
+        up: (client: PoolClient) => Promise<void>;
+    }>): Promise<void>;
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * PostgreSQL Adapter with Connection Pooling
+ * Supports both shared (multi-service) and isolated (per-service) database modes
+ */
+type PostgresAdapterConstructor = {
+    new (config: PostgresPoolConfig): IPostgresAdapter;
+    create(config: PostgresPoolConfig): IPostgresAdapter;
+    prototype: IPostgresAdapter;
+};
+export declare const PostgresAdapter: PostgresAdapterConstructor;
+/**
+ * Get or create adapter instance
+ */
+export declare function getInstance(config: PostgresPoolConfig, key?: string): IPostgresAdapter;
+/**
+ * Get all instances
+ */
+export declare function getAllInstances(): IPostgresAdapter[];
+/**
+ * Disconnect all instances
+ */
+export declare function disconnectAll(): Promise<void>;
+export declare const PostgresAdapterManager: Readonly<{
+    getInstance: typeof getInstance;
+    getAllInstances: typeof getAllInstances;
+    disconnectAll: typeof disconnectAll;
+}>;
+export default PostgresAdapter;
+//# sourceMappingURL=PostgresAdapter.d.ts.map

package/src/microservices/PostgresAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresAdapter.d.ts","sourceRoot":"","sources":["../../../src/microservices/PostgresAdapter.ts"],"names":[],"mappings":"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"}

package/src/microservices/PostgresAdapter.js

@@ -0,0 +1,306 @@
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { QueryBuilder } from '../orm/QueryBuilder.js';
+const poolsByInstance = new WeakMap();
+const configByInstance = new WeakMap();
+function getAdapterConfig(adapter) {
+    const config = configByInstance.get(adapter);
+    if (config === undefined) {
+        throw ErrorFactory.createConfigError('PostgresAdapter not initialized');
+    }
+    return config;
+}
+function getPools(adapter) {
+    const pools = poolsByInstance.get(adapter);
+    if (pools === undefined) {
+        throw ErrorFactory.createConfigError('PostgresAdapter not initialized');
+    }
+    return pools;
+}
+// Function-constructor implementation (no `class` keyword) but still constructable via `new`.
+function PostgresAdapterImpl(config) {
+    const adapterConfig = {
+        max: 20,
+        idleTimeoutMillis: 30000,
+        connectionTimeoutMillis: 2000,
+        isolation: 'shared',
+        ...config,
+    };
+    poolsByInstance.set(this, new Map());
+    configByInstance.set(this, adapterConfig);
+}
+PostgresAdapterImpl.prototype.getPoolKey = function getPoolKey() {
+    const adapterConfig = getAdapterConfig(this);
+    if (adapterConfig.isolation === 'isolated' && adapterConfig.serviceName !== undefined) {
+        return `${adapterConfig.host}:${adapterConfig.port}/${adapterConfig.serviceName}`;
+    }
+    return `${adapterConfig.host}:${adapterConfig.port}/${adapterConfig.database}`;
+};
+PostgresAdapterImpl.prototype.connect = async function connect() {
+    const adapterConfig = getAdapterConfig(this);
+    const pools = getPools(this);
+    return runConnect(adapterConfig, pools, () => this.getPoolKey());
+};
+PostgresAdapterImpl.prototype.getPool = function getPool() {
+    const pools = getPools(this);
+    return runGetPool(pools, () => this.getPoolKey());
+};
+PostgresAdapterImpl.prototype.query = async function query(sql, params) {
+    return runQuery(this.getPool(), sql, params);
+};
+PostgresAdapterImpl.prototype.execute = async function execute(sql, params) {
+    return runExecute(this.getPool(), sql, params);
+};
+PostgresAdapterImpl.prototype.transaction = async function transaction(callback) {
+    return runTransaction(this.getPool(), callback);
+};
+PostgresAdapterImpl.prototype.getPoolStats = function getPoolStats() {
+    return runGetPoolStats(this.getPool());
+};
+PostgresAdapterImpl.prototype.disconnect = async function disconnect() {
+    const pools = getPools(this);
+    return runDisconnect(pools, () => this.getPoolKey());
+};
+PostgresAdapterImpl.prototype.disconnectAll = async function disconnectAll() {
+    const pools = getPools(this);
+    return runDisconnectAll(pools);
+};
+PostgresAdapterImpl.prototype.createServiceSchema = async function createServiceSchema(schemaName) {
+    const adapterConfig = getAdapterConfig(this);
+    return runCreateServiceSchema(this, adapterConfig.isolation, schemaName);
+};
+PostgresAdapterImpl.prototype.runMigrations = async function runMigrationsPublic(migrations) {
+    return runMigrations(this.getPool(), migrations);
+};
+PostgresAdapterImpl.prototype.healthCheck = async function healthCheck() {
+    return runHealthCheck(this.getPool());
+};
+export const PostgresAdapter = PostgresAdapterImpl;
+PostgresAdapter.create = (config) => new PostgresAdapter(config);
+/**
+ * Internal function to get connection pool
+ */
+function runGetPool(pools, getPoolKey) {
+    const poolKey = getPoolKey();
+    const pool = pools.get(poolKey);
+    if (pool === undefined) {
+        throw ErrorFactory.createConnectionError('Connection pool not initialized. Call connect() first.', { poolKey });
+    }
+    return pool;
+}
+/**
+ * Internal function to get pool statistics
+ */
+function runGetPoolStats(pool) {
+    return {
+        totalConnections: pool.totalCount,
+        idleConnections: pool.idleCount,
+        waitingRequests: pool.waitingCount,
+    };
+}
+/**
+ * Internal function to disconnect a pool
+ */
+async function runDisconnect(pools, getPoolKey) {
+    const poolKey = getPoolKey();
+    const pool = pools.get(poolKey);
+    if (pool !== undefined) {
+        await pool.end();
+        pools.delete(poolKey);
+        Logger.info(`🔌 PostgreSQL disconnected: ${poolKey}`);
+    }
+}
+/**
+ * Internal function to disconnect all pools
+ */
+async function runDisconnectAll(pools) {
+    const promises = Array.from(pools.values()).map(async (pool) => pool.end());
+    await Promise.all(promises);
+    pools.clear();
+    Logger.info('🔌 All PostgreSQL pools disconnected');
+}
+function isMissingEsmPackage(error, packageName) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const maybe = error;
+    const code = typeof maybe.code === 'string' ? maybe.code : '';
+    const message = typeof maybe.message === 'string' ? maybe.message : '';
+    // Some runners/wrappers preserve `code` but sanitize/omit the message.
+    if (code === 'ERR_MODULE_NOT_FOUND' && message.length === 0)
+        return true;
+    if (code === 'ERR_MODULE_NOT_FOUND' && message.includes(`'${packageName}'`))
+        return true;
+    if (message.includes(`Cannot find package '${packageName}'`))
+        return true;
+    return false;
+}
+/**
+ * Internal function to connect to PostgreSQL
+ */
+async function runConnect(adapterConfig, pools, getPoolKey) {
+    const poolKey = getPoolKey();
+    if (pools.has(poolKey) === true) {
+        Logger.info(`♻️  Reusing existing connection pool: ${poolKey}`);
+        return;
+    }
+    try {
+        // Dynamic import to keep core zero-dependency
+        const { Pool } = await import('pg');
+        const pool = new Pool({
+            host: adapterConfig.host,
+            port: adapterConfig.port,
+            database: adapterConfig.database,
+            user: adapterConfig.user,
+            password: adapterConfig.password,
+            max: adapterConfig.max,
+            idleTimeoutMillis: adapterConfig.idleTimeoutMillis,
+            connectionTimeoutMillis: adapterConfig.connectionTimeoutMillis,
+        });
+        pool.on('error', (err) => {
+            Logger.error(`Unexpected error on idle client for ${poolKey}`, err);
+        });
+        const client = await pool.connect();
+        Logger.info(`✅ PostgreSQL connected: ${adapterConfig.host}:${adapterConfig.port}/${adapterConfig.database}`);
+        client.release();
+        pools.set(poolKey, pool);
+        Logger.info(`🐘 PostgreSQL pool initialized: ${poolKey}`);
+    }
+    catch (error) {
+        if (isMissingEsmPackage(error, 'pg')) {
+            throw ErrorFactory.createConfigError("PostgreSQL pool requires the 'pg' package (run `zin add db:postgres` or `zin plugin install db:postgres`).");
+        }
+        throw ErrorFactory.createTryCatchError(`Failed to initialize PostgreSQL pool: ${error.message}`, error);
+    }
+}
+/**
+ * Internal function to execute a query
+ */
+async function runQuery(pool, sql, params) {
+    try {
+        const result = await pool.query(sql, params);
+        return result.rows;
+    }
+    catch (error) {
+        Logger.error(`PostgreSQL query failed: ${sql}`, error);
+        throw error;
+    }
+}
+/**
+ * Internal function to execute a query and return full result
+ */
+async function runExecute(pool, sql, params) {
+    try {
+        const result = await pool.query(sql, params);
+        return {
+            rows: result.rows,
+            rowCount: result.rowCount ?? 0,
+        };
+    }
+    catch (err) {
+        Logger.error(`PostgreSQL execute failed: ${sql}`, err);
+        throw err;
+    }
+}
+/**
+ * Internal function to run a transaction
+ */
+async function runTransaction(pool, callback) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const result = await callback(client);
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (err) {
+        Logger.error('Transaction failed, rolling back', err);
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Internal function to create service schema
+ */
+async function runCreateServiceSchema(adapter, isolation, schemaName) {
+    if (isolation !== 'isolated') {
+        Logger.info('ℹ️  Shared database mode: skipping schema creation');
+        return;
+    }
+    try {
+        await adapter.query(`CREATE SCHEMA IF NOT EXISTS "${schemaName}"`);
+        Logger.info(`✅ Schema created: ${schemaName}`);
+    }
+    catch (err) {
+        Logger.error(`Schema creation failed: ${schemaName}`, err);
+    }
+}
+/**
+ * Internal function to run migrations
+ */
+async function runMigrations(pool, migrations) {
+    const client = await pool.connect();
+    try {
+        // Migrations must run sequentially to preserve ordering.
+        /* eslint-disable no-await-in-loop */
+        for (const migration of migrations) {
+            await migration.up(client);
+        }
+        /* eslint-enable no-await-in-loop */
+        Logger.info(`✅ Migrations completed`);
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Internal function for health check
+ */
+async function runHealthCheck(pool) {
+    try {
+        const pingSql = QueryBuilder.create('').select('1').toSQL();
+        const result = await pool.query(pingSql);
+        return result.rows.length > 0;
+    }
+    catch (error) {
+        Logger.error('PostgreSQL health check failed', error);
+        return false;
+    }
+}
+/**
+ * Global PostgreSQL adapter instance management
+ */
+const instances = new Map();
+/**
+ * Get or create adapter instance
+ */
+export function getInstance(config, key = 'default') {
+    const existing = instances.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = PostgresAdapter.create(config);
+    instances.set(key, created);
+    return created;
+}
+/**
+ * Get all instances
+ */
+export function getAllInstances() {
+    return Array.from(instances.values());
+}
+/**
+ * Disconnect all instances
+ */
+export async function disconnectAll() {
+    await Promise.all(Array.from(instances.values()).map(async (adapter) => adapter.disconnectAll()));
+    instances.clear();
+}
+export const PostgresAdapterManager = Object.freeze({
+    getInstance,
+    getAllInstances,
+    disconnectAll,
+});
+export default PostgresAdapter;