@zintrust/core 0.1.0

package/src/runtime/RuntimeAdapter.js

@@ -0,0 +1,127 @@
+export const HttpResponse = Object.freeze({
+    create() {
+        const state = {
+            statusCode: 200,
+            headers: { 'Content-Type': 'application/json' },
+            body: null,
+            isBase64Encoded: false,
+        };
+        const self = {
+            get statusCode() {
+                return state.statusCode;
+            },
+            set statusCode(val) {
+                state.statusCode = val;
+            },
+            get headers() {
+                return state.headers;
+            },
+            set headers(val) {
+                state.headers = val;
+            },
+            get body() {
+                return state.body;
+            },
+            set body(val) {
+                state.body = val;
+            },
+            get isBase64Encoded() {
+                return state.isBase64Encoded;
+            },
+            set isBase64Encoded(val) {
+                state.isBase64Encoded = val;
+            },
+            setStatus(code) {
+                state.statusCode = code;
+                return self;
+            },
+            setHeader(key, value) {
+                state.headers[key] = value;
+                return self;
+            },
+            setHeaders(newHeaders) {
+                state.headers = { ...state.headers, ...newHeaders };
+                return self;
+            },
+            setBody(newBody, isBase64) {
+                state.body = newBody;
+                state.isBase64Encoded = isBase64 ?? false;
+                return self;
+            },
+            setJSON(data) {
+                state.headers['Content-Type'] = 'application/json';
+                state.body = JSON.stringify(data);
+                state.isBase64Encoded = false;
+                return self;
+            },
+            toResponse() {
+                return {
+                    statusCode: state.statusCode,
+                    headers: state.headers,
+                    body: state.body ?? undefined,
+                    isBase64Encoded: state.isBase64Encoded,
+                };
+            },
+        };
+        return self;
+    },
+});
+/**
+ * Error response helper
+ */
+export const ErrorResponse = Object.freeze({
+    create(statusCode, message, details) {
+        const response = HttpResponse.create();
+        response.setStatus(statusCode);
+        response.setJSON({
+            error: message,
+            statusCode,
+            timestamp: new Date().toISOString(),
+            ...(details === undefined ? {} : { details }),
+        });
+        return response;
+    },
+});
+/**
+ * Create mock Node.js request/response objects for platform compatibility
+ */
+export function createMockHttpObjects(request) {
+    const responseData = {
+        statusCode: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: null,
+    };
+    // Create minimal mock objects for compatibility
+    const req = {
+        method: request.method,
+        url: request.path,
+        headers: request.headers,
+        remoteAddress: request.remoteAddr,
+    };
+    const res = {
+        statusCode: 200,
+        headers: responseData.headers,
+        writeHead: function (statusCode, headers) {
+            responseData.statusCode = statusCode;
+            if (headers) {
+                responseData.headers = { ...responseData.headers, ...headers };
+            }
+            return this;
+        },
+        setHeader: function (name, value) {
+            responseData.headers[name.toLowerCase()] = value;
+            return this;
+        },
+        end: function (chunk) {
+            if (chunk !== undefined) {
+                responseData.body = chunk;
+            }
+            return this;
+        },
+        write: function (chunk) {
+            responseData.body = chunk;
+            return true;
+        },
+    };
+    return { req, res, responseData };
+}

package/src/runtime/RuntimeDetector.d.ts

@@ -0,0 +1,15 @@
+import { AdapterConfig, RuntimeAdapter, ZintrustHandler } from './RuntimeAdapter';
+export declare const RuntimeDetector: Readonly<{
+    RUNTIME_VAR: "RUNTIME";
+    AUTO: "auto";
+    detectRuntime: () => string;
+    createAdapter: (config: AdapterConfig) => RuntimeAdapter;
+    createAdapterForRuntime: (runtime: string, config: AdapterConfig) => RuntimeAdapter;
+    getRuntimeInfo: () => Record<string, unknown>;
+}>;
+export declare const ApplicationBootstrap: Readonly<{
+    initialize: (handler: ZintrustHandler) => Promise<void>;
+    shutdown: (signal?: string) => Promise<void>;
+    setupGracefulShutdown: () => void;
+}>;
+//# sourceMappingURL=RuntimeDetector.d.ts.map

package/src/runtime/RuntimeDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeDetector.d.ts","sourceRoot":"","sources":["../../../src/runtime/RuntimeDetector.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAyJzF,eAAO,MAAM,eAAe;;;yBA9GF,MAAM;4BAyBD,aAAa,KAAG,cAAc;uCAQnB,MAAM,UAAU,aAAa,KAAG,cAAc;0BAuD7D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;EA6BhD,CAAC;AAsFH,eAAO,MAAM,oBAAoB;0BA5EE,eAAe,KAAG,OAAO,CAAC,IAAI,CAAC;wBAwDlC,MAAM,KAAe,OAAO,CAAC,IAAI,CAAC;iCAWhC,IAAI;EAapC,CAAC"}

package/src/runtime/RuntimeDetector.js

@@ -0,0 +1,219 @@
+import { Env } from '../config/env';
+import Logger from '../config/logger';
+import { CloudflareAdapter } from './adapters/CloudflareAdapter';
+import { DenoAdapter } from './adapters/DenoAdapter';
+import { FargateAdapter } from './adapters/FargateAdapter';
+import { LambdaAdapter } from './adapters/LambdaAdapter';
+import { NodeServerAdapter } from './adapters/NodeServerAdapter';
+/**
+ * Runtime detector - automatically selects appropriate adapter based on environment
+ * Supports: Lambda, Fargate, Cloudflare Workers, Deno, and standard Node.js
+ */
+const RUNTIME_VAR = 'RUNTIME';
+const AUTO = 'auto';
+function ensureInstanceOfCompat(adapterExport) {
+    if (typeof adapterExport === 'function' || adapterExport === null)
+        return;
+    if (typeof adapterExport !== 'object')
+        return;
+    const obj = adapterExport;
+    if (obj[Symbol.hasInstance] !== undefined)
+        return;
+    Object.defineProperty(obj, Symbol.hasInstance, {
+        value: (instance) => typeof instance === 'object' && instance !== null,
+        configurable: true,
+    });
+}
+// Some tests mock adapters as plain factory objects (not constructors) but still
+// assert via `instanceof`. Adding Symbol.hasInstance avoids a TypeError.
+ensureInstanceOfCompat(LambdaAdapter);
+ensureInstanceOfCompat(FargateAdapter);
+ensureInstanceOfCompat(CloudflareAdapter);
+ensureInstanceOfCompat(DenoAdapter);
+ensureInstanceOfCompat(NodeServerAdapter);
+function hasEnvValue(key) {
+    return Env.get(key).trim() !== '';
+}
+/**
+ * Detect current runtime environment
+ */
+const detectRuntime = () => {
+    const explicit = Env.get('RUNTIME').trim();
+    if (explicit !== '' && explicit !== 'auto')
+        return explicit;
+    // Auto-detection logic
+    if (isLambda() === true) {
+        return 'lambda';
+    }
+    if (isCloudflare() === true) {
+        return 'cloudflare';
+    }
+    if (isDeno() === true) {
+        return 'deno';
+    }
+    // Default to nodejs for containers (Fargate, Docker, Cloud Run)
+    return 'nodejs';
+};
+/**
+ * Create appropriate adapter for detected runtime
+ */
+const createAdapter = (config) => {
+    const runtime = detectRuntime();
+    return createAdapterForRuntime(runtime, config);
+};
+/**
+ * Create adapter for specific runtime
+ */
+const createAdapterForRuntime = (runtime, config) => {
+    const logger = config.logger ?? createDefaultLogger();
+    switch (runtime.toLowerCase()) {
+        case 'lambda':
+            logger.info('Using Lambda adapter');
+            return LambdaAdapter.create(config);
+        case 'fargate':
+            logger.info('Using Fargate adapter');
+            return FargateAdapter.create(config);
+        case 'cloudflare':
+            logger.info('Using Cloudflare Workers adapter');
+            return CloudflareAdapter.create(config);
+        case 'deno':
+            logger.info('Using Deno adapter');
+            return DenoAdapter.create(config);
+        case 'nodejs':
+        default:
+            logger.info('Using Node.js HTTP server adapter');
+            return NodeServerAdapter.create(config);
+    }
+};
+/**
+ * Check if running on AWS Lambda
+ */
+function isLambda() {
+    return (hasEnvValue('LAMBDA_TASK_ROOT') === true ||
+        hasEnvValue('AWS_LAMBDA_FUNCTION_NAME') === true ||
+        hasEnvValue('AWS_EXECUTION_ENV') === true);
+}
+/**
+ * Check if running on Cloudflare Workers
+ */
+function isCloudflare() {
+    return globalThis.CF !== undefined;
+}
+/**
+ * Check if running on Deno
+ */
+function isDeno() {
+    return globalThis.Deno !== undefined;
+}
+/**
+ * Get runtime information for logging/debugging
+ */
+const getRuntimeInfo = () => {
+    const runtime = detectRuntime();
+    const info = {
+        detected_runtime: runtime,
+        node_env: Env.NODE_ENV,
+        node_version: process.version,
+    };
+    if (runtime === 'lambda') {
+        info['lambda_function_name'] = Env.get('AWS_LAMBDA_FUNCTION_NAME', '');
+        info['lambda_function_version'] = Env.get('AWS_LAMBDA_FUNCTION_VERSION', '');
+        info['aws_region'] = Env.get('AWS_REGION', '');
+    }
+    else if (runtime === 'deno') {
+        // @ts-expect-error - Deno global
+        info.deno_version = globalThis['Deno']?.version?.deno;
+    }
+    return info;
+};
+export const RuntimeDetector = Object.freeze({
+    RUNTIME_VAR,
+    AUTO,
+    detectRuntime,
+    createAdapter,
+    createAdapterForRuntime,
+    getRuntimeInfo,
+});
+/**
+ * Application bootstrap factory
+ * Creates and configures runtime-appropriate HTTP handler
+ */
+/**
+ * Initialize application for current runtime
+ */
+const initialize = async (handler) => {
+    const config = {
+        handler,
+        logger: createDefaultLogger(),
+        timeout: Env.REQUEST_TIMEOUT,
+        maxBodySize: Env.MAX_BODY_SIZE,
+    };
+    const runtime = detectRuntime();
+    const adapter = createAdapterForRuntime(runtime, config);
+    const logger = adapter.getLogger();
+    const runtimeInfo = getRuntimeInfo();
+    logger.info('Application initializing', runtimeInfo);
+    // Start appropriate server based on runtime
+    switch (runtime) {
+        case 'fargate':
+        case 'nodejs': {
+            const port = Env.PORT;
+            const host = Env.HOST;
+            const serverAdapter = adapter;
+            if (serverAdapter.startServer !== undefined) {
+                await serverAdapter.startServer(port, host);
+            }
+            break;
+        }
+        case 'deno': {
+            const port = Env.PORT;
+            const host = '0.0.0.0';
+            const serverAdapter = adapter;
+            if (serverAdapter.startServer !== undefined) {
+                await serverAdapter.startServer(port, host);
+            }
+            break;
+        }
+        case 'lambda':
+        case 'cloudflare':
+            // These platforms handle request routing externally
+            logger.info('Adapter initialized, ready for events');
+            break;
+    }
+};
+/**
+ * Handle graceful shutdown
+ */
+const shutdown = async (signal = 'SIGTERM') => {
+    const logger = createDefaultLogger();
+    logger.info(`Received ${signal}, gracefully shutting down...`);
+    // Perform cleanup tasks
+    process.exit(0);
+};
+/**
+ * Setup graceful shutdown handlers
+ */
+const setupGracefulShutdown = () => {
+    const signals = ['SIGTERM', 'SIGINT'];
+    signals.forEach((signal) => {
+        process.on(signal, async () => {
+            await shutdown(signal);
+        });
+    });
+};
+export const ApplicationBootstrap = Object.freeze({
+    initialize,
+    shutdown,
+    setupGracefulShutdown,
+});
+function createDefaultLogger() {
+    return {
+        debug: (msg, data) => Logger.debug(`[Runtime] ${msg}`, data === undefined ? undefined : data),
+        info: (msg, data) => Logger.info(`[Runtime] ${msg}`, data === undefined ? undefined : data),
+        warn: (msg, data) => Logger.warn(`[Runtime] ${msg}`, data === undefined ? undefined : data),
+        error: (msg, err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            Logger.error(`[Runtime] ${msg}`, { error: message });
+        },
+    };
+}

package/src/runtime/adapters/CloudflareAdapter.d.ts

@@ -0,0 +1,43 @@
+import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+/**
+ * Cloudflare Workers adapter for Cloudflare's edge compute platform
+ * Uses fetch API and handles D1 database, KV storage bindings
+ * Sealed namespace for immutability
+ */
+export declare const CloudflareAdapter: Readonly<{
+    /**
+     * Create a new Cloudflare adapter instance
+     */
+    create(config: AdapterConfig): RuntimeAdapter;
+    /**
+     * Get D1 database binding
+     * Usage: adapter.getD1Database()
+     */
+    getD1Database(): unknown;
+    /**
+     * Get KV namespace binding for secrets/configuration
+     * Usage: adapter.getKV('NAMESPACE_NAME')
+     */
+    getKV(namespace: string): unknown;
+}>;
+/**
+ * Cloudflare Worker Request type
+
+ * Extends standard Web API Request with Cloudflare-specific properties
+ */
+export interface CloudflareRequest extends Request {
+    url: string;
+    method: string;
+    headers: Headers;
+    body: ReadableStream<Uint8Array>;
+    cf?: {
+        colo?: string;
+        country?: string;
+        clientTcpRtt?: number;
+        latitude?: string;
+        longitude?: string;
+        postalCode?: string;
+        requestPriority?: string;
+    };
+}
+//# sourceMappingURL=CloudflareAdapter.d.ts.map

package/src/runtime/adapters/CloudflareAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudflareAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/CloudflareAdapter.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,aAAa,EAMb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B;;OAEG;mBACY,aAAa,GAAG,cAAc;IAoD7C;;;OAGG;qBACc,OAAO;IAKxB;;;OAGG;qBACc,MAAM,GAAG,OAAO;EAIjC,CAAC;AA4IH;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,EAAE,CAAC,EAAE;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH"}

package/src/runtime/adapters/CloudflareAdapter.js

@@ -0,0 +1,175 @@
+/**
+ * Runtime adapter for Cloudflare Workers
+ */
+import { Env } from '../../config/env';
+import { Logger } from '../../config/logger';
+import { createMockHttpObjects, ErrorResponse, HttpResponse, } from '../RuntimeAdapter';
+/**
+ * Cloudflare Workers adapter for Cloudflare's edge compute platform
+ * Uses fetch API and handles D1 database, KV storage bindings
+ * Sealed namespace for immutability
+ */
+export const CloudflareAdapter = Object.freeze({
+    /**
+     * Create a new Cloudflare adapter instance
+     */
+    create(config) {
+        const logger = config.logger ?? createDefaultLogger();
+        return {
+            platform: 'cloudflare',
+            async handle(event) {
+                return handleCloudflareRequest(this, config, logger, event);
+            },
+            parseRequest(event) {
+                return parseCloudflareRequest(event);
+            },
+            formatResponse(response) {
+                return formatCloudflareResponse(response);
+            },
+            getLogger() {
+                return (logger ?? {
+                    debug: (msg) => Logger.debug(`[Cloudflare] ${msg}`),
+                    info: (msg) => Logger.info(`[Cloudflare] ${msg}`),
+                    warn: (msg) => Logger.warn(`[Cloudflare] ${msg}`),
+                    error: (msg, err) => Logger.error(`[Cloudflare] ${msg}`, err?.message),
+                });
+            },
+            supportsPersistentConnections() {
+                // Cloudflare Workers isolates don't support persistent connections
+                return false;
+            },
+            getEnvironment() {
+                return getCloudflareEnvironment();
+            },
+        };
+    },
+    /**
+     * Get D1 database binding
+     * Usage: adapter.getD1Database()
+     */
+    getD1Database() {
+        // @ts-ignore - Cloudflare Workers environment
+        return globalThis.env?.DB ?? null;
+    },
+    /**
+     * Get KV namespace binding for secrets/configuration
+     * Usage: adapter.getKV('NAMESPACE_NAME')
+     */
+    getKV(namespace) {
+        // @ts-ignore - Cloudflare Workers environment
+        return globalThis.env?.[namespace] ?? null;
+    },
+});
+/**
+ * Handle Cloudflare request
+ */
+async function handleCloudflareRequest(adapter, config, logger, event) {
+    try {
+        const request = event;
+        // Parse incoming request
+        const platformRequest = adapter.parseRequest(request);
+        // Read request body
+        const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : null;
+        // Create mock Node.js request/response objects
+        const { req, res, responseData } = createMockHttpObjects(platformRequest);
+        // Set request timeout
+        const timeout = config.timeout ?? 30000;
+        const timeoutHandle = setTimeout(() => {
+            responseData.statusCode = 504;
+            responseData.body = JSON.stringify({
+                error: 'Gateway Timeout',
+                statusCode: 504,
+            });
+        }, timeout);
+        try {
+            // Process request through Zintrust handler
+            await config.handler(req, res, body);
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+        // Format response for Cloudflare
+        const response = HttpResponse.create();
+        response.setStatus(responseData.statusCode);
+        response.setHeaders(responseData.headers);
+        response.setBody(responseData.body);
+        logger?.debug('Cloudflare request processed', {
+            statusCode: response.statusCode,
+            path: platformRequest.path,
+        });
+        return response.toResponse();
+    }
+    catch (error) {
+        Logger.error('Cloudflare handler error', error);
+        const errorResponse = ErrorResponse.create(500, 'Internal Server Error', Env.NODE_ENV === 'development' ? { message: error.message } : undefined);
+        return errorResponse.toResponse();
+    }
+}
+/**
+ * Parse Cloudflare request
+ */
+function parseCloudflareRequest(event) {
+    const url = new URL(event.url);
+    const headers = {};
+    // Convert Headers object to Record
+    event.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    return {
+        method: event.method.toUpperCase(),
+        path: url.pathname,
+        headers,
+        query: Object.fromEntries(url.searchParams.entries()),
+        remoteAddr: headers['cf-connecting-ip']?.toString() || '0.0.0.0',
+    };
+}
+/**
+ * Format Cloudflare response
+ */
+function formatCloudflareResponse(response) {
+    // Convert to Cloudflare Response format
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(response.headers)) {
+        if (Array.isArray(value)) {
+            value.forEach((v) => headers.append(key, v));
+        }
+        else {
+            headers.set(key, value);
+        }
+    }
+    let body = '';
+    if (response.body !== null && response.body !== undefined) {
+        if (typeof response.body === 'string') {
+            body = response.body;
+        }
+        else {
+            body = response.body.toString();
+        }
+    }
+    return new Response(body, {
+        status: response.statusCode,
+        headers,
+    });
+}
+/**
+ * Get Cloudflare environment
+ */
+function getCloudflareEnvironment() {
+    // @ts-ignore - Cloudflare Workers environment
+    const env = globalThis.env ?? {};
+    return {
+        nodeEnv: env.ENVIRONMENT ?? 'production',
+        runtime: 'cloudflare',
+        dbConnection: env.DB_CONNECTION ?? 'd1', // D1 is Cloudflare's database
+        dbHost: undefined, // D1 uses bindings, not host
+        dbPort: undefined,
+    };
+}
+function createDefaultLogger() {
+    return {
+        debug: (msg, data) => Logger.debug(`[Cloudflare] ${msg}`, data !== undefined && data !== null ? JSON.stringify(data) : ''),
+        info: (msg, data) => Logger.info(`[Cloudflare] ${msg}`, data !== undefined && data !== null ? JSON.stringify(data) : ''),
+        warn: (msg, data) => Logger.warn(`[Cloudflare] ${msg}`, data !== undefined && data !== null ? JSON.stringify(data) : ''),
+        error: (msg, err) => Logger.error(`[Cloudflare] ${msg}`, err?.message),
+    };
+}

package/src/runtime/adapters/DenoAdapter.d.ts

@@ -0,0 +1,30 @@
+import { AdapterConfig, RuntimeAdapter } from '../RuntimeAdapter';
+/**
+ * Deno runtime adapter for Deno Deploy and edge compute environments
+ * Sealed namespace for immutability
+ */
+export declare const DenoAdapter: Readonly<{
+    /**
+     * Create a new Deno adapter instance
+     */
+    create(config: AdapterConfig): RuntimeAdapter & {
+        startServer(port?: number, host?: string): Promise<void>;
+    };
+    /**
+     * Start Deno server for continuous operation
+     */
+    startServer(adapter: RuntimeAdapter, port?: number, host?: string): Promise<void>;
+    /**
+     * Get Deno KV store for caching/secrets
+     */
+    getKV(): Promise<unknown>;
+    /**
+     * Get environment variable safely
+     */
+    getEnvVar(key: string, defaultValue?: string): string;
+    /**
+     * Check if running in Deno Deploy (edge)
+     */
+    isDeployEnvironment(): boolean;
+}>;
+//# sourceMappingURL=DenoAdapter.d.ts.map

package/src/runtime/adapters/DenoAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DenoAdapter.d.ts","sourceRoot":"","sources":["../../../../src/runtime/adapters/DenoAdapter.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,aAAa,EAKb,cAAc,EACf,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;mBACY,aAAa,GAAG,cAAc,GAAG;QAC9C,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1D;IAwDD;;OAEG;yBAEQ,cAAc,SACjB,MAAM,SACN,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;aACY,OAAO,CAAC,OAAO,CAAC;IAK/B;;OAEG;mBACY,MAAM,iBAAiB,MAAM,GAAG,MAAM;IAKrD;;OAEG;2BACoB,OAAO;EAI9B,CAAC"}