@noony-serverless/core 0.3.4 → 0.4.1

package/build/core/telemetry/providers/opentelemetry-provider.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTelemetryProvider = void 0;
+/**
+ * Standard OpenTelemetry SDK 2.0 Provider
+ *
+ * Implements telemetry using the official OpenTelemetry JavaScript SDK.
+ * Supports OTLP exporters for traces, metrics, and logs.
+ *
+ * Requirements:
+ * - Node.js >= 18.19.0 or >= 20.6.0
+ * - OTEL_EXPORTER_OTLP_ENDPOINT environment variable
+ * - @opentelemetry/sdk-node and related packages installed
+ *
+ * Auto-selected when OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ *
+ * @example
+ * // Environment setup
+ * OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
+ *
+ * // Usage
+ * const provider = new OpenTelemetryProvider();
+ * const validation = await provider.validate();
+ * if (validation.valid) {
+ *   await provider.initialize({
+ *     serviceName: 'my-service',
+ *     serviceVersion: '1.0.0'
+ *   });
+ * }
+ */
+class OpenTelemetryProvider {
+    name = 'opentelemetry';
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sdk; // NodeSDK
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tracer; // Tracer
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    meter; // Meter
+    ready = false;
+    /**
+     * Validate OpenTelemetry configuration
+     *
+     * Checks:
+     * 1. OTEL_EXPORTER_OTLP_ENDPOINT is set
+     * 2. Endpoint is a valid URL
+     * 3. Required packages are available (checked lazily during init)
+     */
+    async validate() {
+        const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+        if (!endpoint) {
+            return {
+                valid: false,
+                reason: 'OTEL_EXPORTER_OTLP_ENDPOINT environment variable not set',
+            };
+        }
+        try {
+            new URL(endpoint);
+        }
+        catch {
+            return {
+                valid: false,
+                reason: `OTEL_EXPORTER_OTLP_ENDPOINT is not a valid URL: ${endpoint}`,
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Initialize OpenTelemetry SDK
+     *
+     * Sets up:
+     * - Resource attributes (service name, version, environment)
+     * - OTLP trace exporter
+     * - Composite propagator (W3C + Cloud Trace)
+     * - Tracer and Meter providers
+     */
+    async initialize(config) {
+        try {
+            // Dynamic require to avoid compile-time dependency on OTEL packages
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const otelApi = require('@opentelemetry/api');
+            const { trace, metrics } = otelApi;
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const sdkNode = require('@opentelemetry/sdk-node');
+            const { NodeSDK } = sdkNode;
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const exporterHttp = require('@opentelemetry/exporter-trace-otlp-http');
+            const { OTLPTraceExporter } = exporterHttp;
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const resources = require('@opentelemetry/resources');
+            const { Resource } = resources;
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const semConv = require('@opentelemetry/semantic-conventions');
+            const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = semConv;
+            // Create resource with service metadata
+            const resource = new Resource({
+                [ATTR_SERVICE_NAME]: config.serviceName,
+                [ATTR_SERVICE_VERSION]: config.serviceVersion || '1.0.0',
+                environment: config.environment || 'production',
+            });
+            // Configure trace exporter
+            const traceExporter = new OTLPTraceExporter({
+                url: config.exporters?.traces?.[0]?.endpoint ||
+                    process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+                headers: config.exporters?.traces?.[0]?.headers,
+                timeoutMillis: config.exporters?.traces?.[0]?.timeout,
+            });
+            // Configure composite propagator for W3C + Cloud Trace support
+            const textMapPropagator = this.createPropagator(config);
+            // Initialize SDK
+            this.sdk = new NodeSDK({
+                resource,
+                traceExporter,
+                textMapPropagator, // Use composite propagator
+            });
+            await this.sdk.start();
+            // Get tracer and meter
+            this.tracer = trace.getTracer(config.serviceName, config.serviceVersion || '1.0.0');
+            this.meter = metrics.getMeter(config.serviceName, config.serviceVersion || '1.0.0');
+            this.ready = true;
+            console.log('[Telemetry] OpenTelemetry provider initialized');
+            console.log('[Telemetry] Exporting to:', config.exporters?.traces?.[0]?.endpoint ||
+                process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+        }
+        catch (error) {
+            console.error('[Telemetry] Failed to initialize OpenTelemetry provider:', error);
+            this.ready = false;
+            // Check if error is due to missing packages
+            if (error instanceof Error &&
+                error.message.includes('Cannot find module')) {
+                console.error('[Telemetry] OpenTelemetry packages not installed. Run:');
+                console.error('  npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions');
+            }
+        }
+    }
+    /**
+     * Create an OpenTelemetry span
+     *
+     * Creates a SERVER span with HTTP semantic conventions.
+     * Returns undefined if provider is not ready.
+     */
+    createSpan(context) {
+        if (!this.ready || !this.tracer)
+            return undefined;
+        try {
+            // Dynamic import for SpanKind
+            const SpanKind = 1; // SERVER = 1 in OpenTelemetry
+            const span = this.tracer.startSpan('http.request', {
+                kind: SpanKind,
+                attributes: {
+                    'http.method': context.req.method,
+                    'http.url': context.req.url || context.req.path,
+                    'http.target': context.req.path || '/',
+                    'request.id': context.requestId,
+                    'http.user_agent': context.req.headers?.['user-agent'] || '',
+                },
+            });
+            return {
+                setAttributes: (attrs) => {
+                    span.setAttributes(attrs);
+                },
+                recordException: (error) => {
+                    span.recordException(error);
+                },
+                setStatus: (status) => {
+                    span.setStatus(status);
+                },
+                end: () => {
+                    span.end();
+                },
+            };
+        }
+        catch (error) {
+            console.error('[Telemetry] Failed to create span:', error);
+            return undefined;
+        }
+    }
+    /**
+     * Record a metric as a histogram
+     */
+    recordMetric(name, value, attributes) {
+        if (!this.ready || !this.meter)
+            return;
+        try {
+            const histogram = this.meter.createHistogram(name, {
+                description: `Histogram for ${name}`,
+                unit: 'ms',
+            });
+            histogram.record(value, attributes);
+        }
+        catch (error) {
+            console.error('[Telemetry] Failed to record metric:', error);
+        }
+    }
+    /**
+     * Log with trace correlation
+     *
+     * Adds trace and span IDs to log output when available.
+     */
+    log(level, message, attributes) {
+        if (!this.ready)
+            return;
+        try {
+            // Try to get active span for correlation
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { trace } = require('@opentelemetry/api');
+            const span = trace.getActiveSpan();
+            const traceContext = span
+                ? {
+                    traceId: span.spanContext().traceId,
+                    spanId: span.spanContext().spanId,
+                    traceFlags: span.spanContext().traceFlags,
+                }
+                : {};
+            console.log(JSON.stringify({
+                level,
+                message,
+                ...traceContext,
+                ...attributes,
+                timestamp: new Date().toISOString(),
+            }));
+        }
+        catch (error) {
+            // Fallback to simple logging
+            console.log(JSON.stringify({ level, message, ...attributes }));
+        }
+    }
+    /**
+     * Check if OpenTelemetry provider is ready
+     */
+    isReady() {
+        return this.ready;
+    }
+    /**
+     * Shutdown OpenTelemetry SDK
+     *
+     * Flushes pending telemetry data and closes exporters.
+     */
+    async shutdown() {
+        if (this.ready && this.sdk) {
+            try {
+                await this.sdk.shutdown();
+                console.log('[Telemetry] OpenTelemetry provider shutdown complete');
+            }
+            catch (error) {
+                console.error('[Telemetry] Error during shutdown:', error);
+            }
+            finally {
+                this.ready = false;
+            }
+        }
+    }
+    /**
+     * Create composite propagator based on configuration
+     *
+     * Supports:
+     * - W3C Trace Context (traceparent/tracestate)
+     * - Google Cloud Trace Context (X-Cloud-Trace-Context)
+     *
+     * When running on GCP, both formats are enabled by default for compatibility.
+     * This allows trace IDs to be synchronized between Cloud Run Load Balancer
+     * and your application.
+     *
+     * @param config Telemetry configuration
+     * @returns Configured propagator (W3C, Cloud Trace, or Composite)
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    createPropagator(config) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const propagators = [];
+            // Determine which propagators to use
+            const useCloudTrace = config.propagation?.cloudTrace ?? this.isRunningOnGCP();
+            const useW3C = config.propagation?.w3c ?? true;
+            // Add Cloud Trace propagator (priority 1 - reads X-Cloud-Trace-Context from GCP)
+            if (useCloudTrace) {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    const cloudPropagator = require('@google-cloud/opentelemetry-cloud-trace-propagator');
+                    const { CloudPropagator } = cloudPropagator;
+                    propagators.push(new CloudPropagator());
+                    console.log('[Telemetry] CloudPropagator enabled for GCP trace compatibility');
+                }
+                catch (error) {
+                    console.warn('[Telemetry] CloudPropagator requested but package not installed:', error instanceof Error ? error.message : error);
+                    console.warn('[Telemetry] Install with: npm install @google-cloud/opentelemetry-cloud-trace-propagator');
+                }
+            }
+            // Add W3C Trace Context propagator (priority 2 - standard traceparent)
+            if (useW3C) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const otelCore = require('@opentelemetry/core');
+                const { W3CTraceContextPropagator } = otelCore;
+                propagators.push(new W3CTraceContextPropagator());
+                console.log('[Telemetry] W3CTraceContextPropagator enabled');
+            }
+            // If multiple propagators, use CompositePropagator
+            if (propagators.length > 1) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const otelCore = require('@opentelemetry/core');
+                const { CompositePropagator } = otelCore;
+                return new CompositePropagator({ propagators });
+            }
+            // If only one propagator, use it directly
+            if (propagators.length === 1) {
+                return propagators[0];
+            }
+            // Fallback to W3C if no propagators configured
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const otelCore = require('@opentelemetry/core');
+            const { W3CTraceContextPropagator } = otelCore;
+            return new W3CTraceContextPropagator();
+        }
+        catch (error) {
+            console.error('[Telemetry] Failed to create propagator:', error);
+            // Return W3C propagator as safe fallback
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const otelCore = require('@opentelemetry/core');
+                const { W3CTraceContextPropagator } = otelCore;
+                return new W3CTraceContextPropagator();
+            }
+            catch (fallbackError) {
+                console.error('[Telemetry] Failed to create fallback propagator:', fallbackError);
+                return undefined;
+            }
+        }
+    }
+    /**
+     * Detect if running on Google Cloud Platform
+     */
+    isRunningOnGCP() {
+        return !!(process.env.GOOGLE_CLOUD_PROJECT ||
+            process.env.GCLOUD_PROJECT ||
+            process.env.GCP_PROJECT ||
+            process.env.K_SERVICE || // Cloud Run
+            process.env.FUNCTION_NAME || // Cloud Functions
+            process.env.GAE_APPLICATION // App Engine
+        );
+    }
+}
+exports.OpenTelemetryProvider = OpenTelemetryProvider;
+//# sourceMappingURL=opentelemetry-provider.js.map

package/build/middlewares/bodyValidationMiddleware.js

@@ -91,7 +91,7 @@ exports.BodyValidationMiddleware = BodyValidationMiddleware;
 // Modified to fix type instantiation error
 const bodyValidatorMiddleware = (schema) => ({
     before: async (context) => {
-        context.req.parsedBody = await validateBody(schema, context.req.body);
+        context.req.parsedBody = await validateBody(schema, context.req.parsedBody);
     },
 });
 exports.bodyValidatorMiddleware = bodyValidatorMiddleware;

package/build/middlewares/dependencyInjectionMiddleware.d.ts

@@ -1,4 +1,5 @@
 import { BaseMiddleware, Context } from '../core';
+import { ServiceDefinition } from '../core/containerPool';
 /**
  * Middleware to inject dependencies into the request context using typedi.
  * This allows handlers to access shared services or data via context.container.
@@ -149,10 +150,14 @@ import { BaseMiddleware, Context } from '../core';
  */
 export declare class DependencyInjectionMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
     private services;
-    constructor(services: {
-        id: any;
-        value: any;
-    }[]);
+    private options?;
+    constructor(services?: ServiceDefinition[], options?: {
+        /**
+         * Service scope: 'global' for process-lifetime, 'local' for request-lifetime
+         * @default 'local'
+         */
+        scope?: "global" | "local";
+    } | undefined);
     before(context: Context<TBody, TUser>): Promise<void>;
 }
 /**
@@ -249,8 +254,11 @@ export declare class DependencyInjectionMiddleware<TBody = unknown, TUser = unkn
  *   });
  * ```
  */
-export declare const dependencyInjection: <TBody = unknown, TUser = unknown>(services?: {
-    id: any;
-    value: any;
-}[]) => BaseMiddleware<TBody, TUser>;
+export declare const dependencyInjection: <TBody = unknown, TUser = unknown>(services?: ServiceDefinition[], options?: {
+    /**
+     * Service scope: 'global' for process-lifetime, 'local' for request-lifetime
+     * @default 'local'
+     */
+    scope?: "global" | "local";
+}) => BaseMiddleware<TBody, TUser>;
 //# sourceMappingURL=dependencyInjectionMiddleware.d.ts.map

package/build/middlewares/dependencyInjectionMiddleware.js

@@ -2,7 +2,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dependencyInjection = exports.DependencyInjectionMiddleware = void 0;
-const typedi_1 = require("typedi");
+const containerPool_1 = require("../core/containerPool");
 /**
  * Middleware to inject dependencies into the request context using typedi.
  * This allows handlers to access shared services or data via context.container.
@@ -153,14 +153,25 @@ const typedi_1 = require("typedi");
  */
 class DependencyInjectionMiddleware {
     services;
-    constructor(services) {
+    options;
+    constructor(services = [], options) {
         this.services = services;
+        this.options = options;
     }
     async before(context) {
-        this.services.forEach((service) => {
-            typedi_1.Container.set(service.id, service.value);
-        });
-        context.container = typedi_1.Container.of();
+        const scope = this.options?.scope || 'local';
+        if (scope === 'global') {
+            // Register services globally (process-lifetime)
+            // ⚠️ Use sparingly - only for truly shared services like DB connections
+            containerPool_1.containerPool.initializeGlobal(this.services);
+        }
+        else {
+            // Register services locally (request-lifetime)
+            // ✅ Recommended for most use cases - isolated per request
+            this.services.forEach((service) => {
+                context.container?.set(service.id, service.value);
+            });
+        }
     }
 }
 exports.DependencyInjectionMiddleware = DependencyInjectionMiddleware;
@@ -258,12 +269,21 @@ exports.DependencyInjectionMiddleware = DependencyInjectionMiddleware;
  *   });
  * ```
  */
-const dependencyInjection = (services = []) => ({
+const dependencyInjection = (services = [], options) => ({
     before: async (context) => {
-        services.forEach((service) => {
-            typedi_1.Container.set(service.id, service.value);
-        });
-        context.container = typedi_1.Container.of();
+        const scope = options?.scope || 'local';
+        if (scope === 'global') {
+            // Register services globally (process-lifetime)
+            // ⚠️ Use sparingly - only for truly shared services like DB connections
+            containerPool_1.containerPool.initializeGlobal(services);
+        }
+        else {
+            // Register services locally (request-lifetime)
+            // ✅ Recommended for most use cases - isolated per request
+            services.forEach((service) => {
+                context.container?.set(service.id, service.value);
+            });
+        }
     },
 });
 exports.dependencyInjection = dependencyInjection;

package/build/middlewares/guards/adapters/CustomTokenVerificationPortAdapter.d.ts

@@ -245,7 +245,7 @@ export declare class TokenVerificationAdapterFactory {
      * @param expirationField - Optional field name for expiration (e.g., 'expiresAt', 'exp')
      * @returns Configured adapter for API key tokens
      */
-    static forAPIKey<T extends Record<string, any>>(verificationPort: CustomTokenVerificationPort<T>, userIdField: keyof T, expirationField?: keyof T): CustomTokenVerificationPortAdapter<T>;
+    static forAPIKey<T extends object>(verificationPort: CustomTokenVerificationPort<T>, userIdField: keyof T, expirationField?: keyof T): CustomTokenVerificationPortAdapter<T>;
     /**
      * Create adapter for OAuth tokens with standard OAuth claims.
      *

package/build/middlewares/guards/guards/FastAuthGuard.d.ts

@@ -43,7 +43,7 @@ export interface AuthenticationResult {
     success: boolean;
     user?: UserContext;
     token?: {
-        decoded: any;
+        decoded: unknown;
         raw: string;
         expiresAt: string;
         issuer?: string;
@@ -63,7 +63,7 @@ export interface AuthGuardConfig {
     allowedIssuers?: string[];
     requireEmailVerification: boolean;
     allowInactiveUsers: boolean;
-    customValidation?: (token: any, user: UserContext) => Promise<boolean>;
+    customValidation?: (token: unknown, user: UserContext) => Promise<boolean>;
 }
 /**
  * Token validation service interface
@@ -74,17 +74,17 @@ export interface TokenValidator {
      */
     validateToken(token: string): Promise<{
         valid: boolean;
-        decoded?: any;
+        decoded?: unknown;
         error?: string;
     }>;
     /**
      * Extract user ID from decoded token
      */
-    extractUserId(decoded: any): string;
+    extractUserId(decoded: unknown): string;
     /**
      * Check if token is expired
      */
-    isTokenExpired(decoded: any): boolean;
+    isTokenExpired(decoded: unknown): boolean;
 }
 /**
  * Fast Authentication Guard Implementation

package/build/middlewares/guards/guards/FastAuthGuard.js

@@ -215,14 +215,15 @@ let FastAuthGuard = class FastAuthGuard {
                 }
             }
             // Build successful authentication result
+            const decoded = tokenValidation.decoded;
             const authResult = {
                 success: true,
                 user: userContext,
                 token: {
                     decoded: tokenValidation.decoded,
                     raw: token,
-                    expiresAt: new Date(tokenValidation.decoded.exp * 1000).toISOString(),
-                    issuer: tokenValidation.decoded.iss,
+                    expiresAt: new Date(decoded.exp * 1000).toISOString(),
+                    issuer: decoded.iss,
                 },
                 cached: false,
                 resolutionTimeUs: Number(process.hrtime.bigint() - startTime) / 1000,

package/build/middlewares/guards/guards/PermissionGuardFactory.d.ts

@@ -162,16 +162,14 @@ export declare class PermissionGuardFactory {
     getStats(): {
         totalGuards: number;
         guardsByType: Record<string, number>;
-        individualGuardStats: {
-            guardType: string;
-            checkCount: number;
-            successCount: number;
-            failureCount: number;
-            successRate: number;
+        individualGuardStats: ReturnType<BasePermissionGuard['getStats']>[];
+        aggregatedStats: {
+            totalChecks: number;
+            totalSuccesses: number;
+            totalFailures: number;
+            overallSuccessRate: number;
             averageProcessingTimeUs: number;
-            totalProcessingTimeUs: number;
-        }[];
-        aggregatedStats: any;
+        };
     };
     /**
      * Clear guard cache

package/build/middlewares/guards/resolvers/ExpressionPermissionResolver.d.ts

@@ -118,7 +118,7 @@ export declare class ExpressionPermissionResolver extends PermissionResolver<Per
     /**
      * Check if this resolver can handle the given requirement type
      */
-    canHandle(requirement: any): requirement is PermissionExpression;
+    canHandle(requirement: unknown): requirement is PermissionExpression;
     /**
      * Normalize expression for consistent cache keys
      *

package/build/middlewares/guards/resolvers/ExpressionPermissionResolver.js

@@ -412,7 +412,7 @@ class ExpressionPermissionResolver extends PermissionResolver_1.PermissionResolv
      * Check if this resolver can handle the given requirement type
      */
     canHandle(requirement) {
-        return (requirement &&
+        return (!!requirement &&
             typeof requirement === 'object' &&
             PermissionResolver_1.PermissionUtils.isValidExpression(requirement));
     }

package/build/middlewares/guards/resolvers/PermissionResolver.d.ts

@@ -19,7 +19,7 @@
  * different types of permission requirements. The generic type T represents
  * the specific requirement format for each resolver.
  */
-export declare abstract class PermissionResolver<T = any> {
+export declare abstract class PermissionResolver<T = unknown> {
     /**
      * Check if user permissions satisfy the requirement
      *

package/build/middlewares/guards/resolvers/PlainPermissionResolver.d.ts

@@ -96,6 +96,6 @@ export declare class PlainPermissionResolver extends PermissionResolver<string[]
      * @param requirement - The requirement to check
      * @returns true if this resolver can handle the requirement
      */
-    canHandle(requirement: any): requirement is string[];
+    canHandle(requirement: unknown): requirement is string[];
 }
 //# sourceMappingURL=PlainPermissionResolver.d.ts.map

package/build/middlewares/guards/resolvers/WildcardPermissionResolver.d.ts

@@ -141,6 +141,6 @@ export declare class WildcardPermissionResolver extends PermissionResolver<strin
     /**
      * Check if this resolver can handle the given requirement type
      */
-    canHandle(requirement: any): requirement is string[];
+    canHandle(requirement: unknown): requirement is string[];
 }
 //# sourceMappingURL=WildcardPermissionResolver.d.ts.map