@noony-serverless/core 0.3.3 → 0.4.0

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopProvider = void 0;
+/**
+ * Noop (No-operation) Telemetry Provider
+ *
+ * This provider does nothing and is used as:
+ * 1. Fallback when other providers fail validation
+ * 2. Default when telemetry is disabled (NODE_ENV=test)
+ * 3. Placeholder when no configuration is provided
+ *
+ * It implements all TelemetryProvider methods as no-ops to ensure
+ * the application continues to work even when telemetry fails.
+ *
+ * @example
+ * // Automatically used as fallback
+ * const provider = new NoopProvider();
+ * await provider.initialize({ serviceName: 'test' });
+ * const span = provider.createSpan(context); // Returns undefined
+ */
+class NoopProvider {
+    name = 'noop';
+    /**
+     * Noop provider is always valid
+     */
+    async validate() {
+        return { valid: true };
+    }
+    /**
+     * No-op initialization
+     */
+    async initialize(_config) {
+        // Do nothing
+    }
+    /**
+     * Always returns undefined (no span created)
+     */
+    createSpan(_context) {
+        return undefined;
+    }
+    /**
+     * No-op metric recording
+     */
+    recordMetric(_name, _value, _attributes) {
+        // Do nothing
+    }
+    /**
+     * No-op logging
+     */
+    log(_level, _message, _attributes) {
+        // Do nothing
+    }
+    /**
+     * Always ready (does nothing, so always ready)
+     */
+    isReady() {
+        return true;
+    }
+    /**
+     * No-op shutdown
+     */
+    async shutdown() {
+        // Do nothing
+    }
+}
+exports.NoopProvider = NoopProvider;
+//# sourceMappingURL=noop-provider.js.map

package/build/core/telemetry/providers/opentelemetry-provider.d.ts

@@ -0,0 +1,102 @@
+import { Context } from '../../core';
+import { TelemetryProvider, ValidationResult, GenericSpan, TelemetryConfig } from '../provider';
+/**
+ * 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'
+ *   });
+ * }
+ */
+export declare class OpenTelemetryProvider implements TelemetryProvider {
+    readonly name = "opentelemetry";
+    private sdk?;
+    private tracer?;
+    private meter?;
+    private ready;
+    /**
+     * 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)
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Initialize OpenTelemetry SDK
+     *
+     * Sets up:
+     * - Resource attributes (service name, version, environment)
+     * - OTLP trace exporter
+     * - Composite propagator (W3C + Cloud Trace)
+     * - Tracer and Meter providers
+     */
+    initialize(config: TelemetryConfig): Promise<void>;
+    /**
+     * Create an OpenTelemetry span
+     *
+     * Creates a SERVER span with HTTP semantic conventions.
+     * Returns undefined if provider is not ready.
+     */
+    createSpan(context: Context<unknown, unknown>): GenericSpan | undefined;
+    /**
+     * Record a metric as a histogram
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /**
+     * Log with trace correlation
+     *
+     * Adds trace and span IDs to log output when available.
+     */
+    log(level: string, message: string, attributes?: Record<string, unknown>): void;
+    /**
+     * Check if OpenTelemetry provider is ready
+     */
+    isReady(): boolean;
+    /**
+     * Shutdown OpenTelemetry SDK
+     *
+     * Flushes pending telemetry data and closes exporters.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * 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)
+     */
+    private createPropagator;
+    /**
+     * Detect if running on Google Cloud Platform
+     */
+    private isRunningOnGCP;
+}
+//# sourceMappingURL=opentelemetry-provider.d.ts.map

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/ProcessingMiddleware.d.ts

@@ -42,7 +42,7 @@ export interface ProcessingMiddlewareConfig {
     parser?: BodyParserConfig;
     query?: QueryProcessingConfig;
     attributes?: AttributesConfig;
-    skipProcessing?: (context: Context) => boolean;
+    skipProcessing?: <TBody, TUser>(context: Context<TBody, TUser>) => boolean;
 }
 /**
  * Consolidated ProcessingMiddleware that combines body parsing, query processing, and attribute extraction.
@@ -52,6 +52,9 @@ export interface ProcessingMiddlewareConfig {
  * - QueryParametersMiddleware
  * - HttpAttributesMiddleware
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ *
  * @example
  * Complete processing setup:
  * ```typescript
@@ -95,10 +98,10 @@ export interface ProcessingMiddlewareConfig {
  *   }));
  * ```
  */
-export declare class ProcessingMiddleware implements BaseMiddleware {
+export declare class ProcessingMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
     private config;
     constructor(config?: ProcessingMiddlewareConfig);
-    before(context: Context): Promise<void>;
+    before(context: Context<TBody, TUser>): Promise<void>;
     private extractAttributes;
     private processQueryParameters;
     private parseBody;

package/build/middlewares/ProcessingMiddleware.js

@@ -10,6 +10,9 @@ const core_1 = require("../core");
  * - QueryParametersMiddleware
  * - HttpAttributesMiddleware
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ *
  * @example
  * Complete processing setup:
  * ```typescript

package/build/middlewares/dependencyInjectionMiddleware.d.ts

@@ -1,9 +1,12 @@
 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.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * Basic service injection:
@@ -145,18 +148,24 @@ import { BaseMiddleware, Context } from '../core';
  *   });
  * ```
  */
-export declare class DependencyInjectionMiddleware implements BaseMiddleware {
+export declare class DependencyInjectionMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
     private services;
-    constructor(services: {
-        id: any;
-        value: any;
-    }[]);
-    before(context: Context): Promise<void>;
+    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>;
 }
 /**
  * Factory function that creates a dependency injection middleware.
  * Creates a new container instance for each request to avoid shared state issues.
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
  * @param services - Array of service definitions with id and value
  * @returns BaseMiddleware object with dependency injection logic
  *
@@ -245,8 +254,11 @@ export declare class DependencyInjectionMiddleware implements BaseMiddleware {
  *   });
  * ```
  */
-export declare const dependencyInjection: (services?: {
-    id: any;
-    value: any;
-}[]) => BaseMiddleware;
+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