@juspay/neurolink 9.24.0 → 9.25.0

package/dist/observability/otelBridge.js

@@ -0,0 +1,131 @@
+/**
+ * OpenTelemetry Bridge
+ * Bidirectional context propagation between NeuroLink and OpenTelemetry
+ */
+import { context, propagation, trace, } from "@opentelemetry/api";
+import { SpanStatus } from "./types/spanTypes.js";
+import { SpanSerializer } from "./utils/spanSerializer.js";
+/**
+ * Bridge for bidirectional context propagation between
+ * NeuroLink's observability system and OpenTelemetry
+ */
+export class OtelBridge {
+    tracer = trace.getTracer("neurolink-bridge");
+    /**
+     * Extract trace context from incoming request headers
+     */
+    extractContext(headers) {
+        const extractedContext = propagation.extract(context.active(), headers);
+        const spanContext = trace.getSpanContext(extractedContext);
+        return spanContext ?? null;
+    }
+    /**
+     * Inject trace context into outgoing request headers
+     */
+    injectContext(headers) {
+        propagation.inject(context.active(), headers);
+        return headers;
+    }
+    /**
+     * Create a NeuroLink span from OpenTelemetry context
+     */
+    createSpanFromOtelContext(spanContext, type, name) {
+        return SpanSerializer.createSpan(type, name, {}, undefined, spanContext.traceId);
+    }
+    /**
+     * Wrap a function with OpenTelemetry tracing that also creates NeuroLink spans
+     */
+    async wrapWithTracing(name, type, fn, onSpanEnd) {
+        const otelSpan = this.tracer.startSpan(name);
+        const neuroLinkSpan = SpanSerializer.createSpan(type, name, {}, undefined, otelSpan.spanContext().traceId);
+        try {
+            const result = await context.with(trace.setSpan(context.active(), otelSpan), () => fn(neuroLinkSpan));
+            const endedSpan = SpanSerializer.endSpan(neuroLinkSpan, SpanStatus.OK);
+            otelSpan.setStatus({ code: 1 }); // OK
+            if (onSpanEnd) {
+                onSpanEnd(endedSpan);
+            }
+            return result;
+        }
+        catch (error) {
+            const endedSpan = SpanSerializer.endSpan(neuroLinkSpan, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
+            otelSpan.setStatus({
+                code: 2, // ERROR
+                message: error instanceof Error ? error.message : String(error),
+            });
+            otelSpan.recordException(error);
+            if (onSpanEnd) {
+                onSpanEnd(endedSpan);
+            }
+            throw error;
+        }
+        finally {
+            otelSpan.end();
+        }
+    }
+    /**
+     * Convert NeuroLink span to OpenTelemetry span and export
+     */
+    exportToOtel(span) {
+        const otelSpan = this.tracer.startSpan(span.name, {
+            startTime: new Date(span.startTime),
+            attributes: this.filterAttributes(span.attributes),
+        });
+        // Add events
+        for (const event of span.events) {
+            otelSpan.addEvent(event.name, this.filterEventAttributes(event.attributes), new Date(event.timestamp));
+        }
+        // Set status (map NeuroLink status to OTel status)
+        const otelStatusCode = span.status === SpanStatus.ERROR ? 2 : 1;
+        otelSpan.setStatus({
+            code: otelStatusCode,
+            message: span.statusMessage,
+        });
+        // End span
+        if (span.endTime) {
+            otelSpan.end(new Date(span.endTime));
+        }
+        else {
+            otelSpan.end();
+        }
+    }
+    /**
+     * Get current trace context for correlation
+     */
+    getCurrentTraceContext() {
+        const spanContext = trace.getActiveSpan()?.spanContext();
+        if (!spanContext) {
+            return null;
+        }
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+        };
+    }
+    /**
+     * Filter attributes to only include OTel-compatible types
+     */
+    filterAttributes(attrs) {
+        const result = {};
+        for (const [key, value] of Object.entries(attrs)) {
+            if (typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean") {
+                result[key] = value;
+            }
+            else if (value !== undefined && value !== null) {
+                result[key] = JSON.stringify(value);
+            }
+        }
+        return result;
+    }
+    /**
+     * Filter event attributes
+     */
+    filterEventAttributes(attrs) {
+        if (!attrs) {
+            return undefined;
+        }
+        return this.filterAttributes(attrs);
+    }
+}

package/dist/observability/retryPolicy.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Retry Policy
+ * Configurable retry strategies for observability exporters
+ */
+/**
+ * Result of a retry decision
+ */
+export type RetryDecision = {
+    /** Whether to retry */
+    shouldRetry: boolean;
+    /** Delay before retry in milliseconds */
+    delayMs: number;
+    /** Reason for the decision */
+    reason: string;
+};
+/**
+ * Context for retry decision making
+ */
+export type RetryContext = {
+    /** Current attempt number (0-indexed) */
+    attempt: number;
+    /** The error that triggered the retry */
+    error: Error;
+    /** Total elapsed time since first attempt */
+    elapsedMs: number;
+    /** Operation name for logging */
+    operationName: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Retry policy interface
+ */
+export interface RetryPolicy {
+    /** Policy name for identification */
+    readonly name: string;
+    /** Decide whether to retry */
+    shouldRetry(context: RetryContext): RetryDecision;
+    /** Maximum attempts allowed */
+    readonly maxAttempts: number;
+    /** Maximum total time allowed for retries */
+    readonly maxTotalTimeMs: number;
+}
+/**
+ * Base retry policy with common configuration
+ */
+export declare abstract class BaseRetryPolicy implements RetryPolicy {
+    abstract readonly name: string;
+    readonly maxAttempts: number;
+    readonly maxTotalTimeMs: number;
+    protected readonly retryableErrors: Set<string>;
+    protected readonly nonRetryableErrors: Set<string>;
+    constructor(config: {
+        maxAttempts?: number;
+        maxTotalTimeMs?: number;
+        retryableErrors?: string[];
+        nonRetryableErrors?: string[];
+    });
+    abstract shouldRetry(context: RetryContext): RetryDecision;
+    protected isRetryableError(error: Error): boolean;
+    protected extractErrorCode(error: Error): string;
+}
+/**
+ * Exponential backoff retry policy
+ * Delay increases exponentially with each attempt
+ */
+export declare class ExponentialBackoffPolicy extends BaseRetryPolicy {
+    readonly name = "exponential-backoff";
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly jitterFactor;
+    constructor(config?: {
+        maxAttempts?: number;
+        maxTotalTimeMs?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        jitterFactor?: number;
+        retryableErrors?: string[];
+        nonRetryableErrors?: string[];
+    });
+    shouldRetry(context: RetryContext): RetryDecision;
+}
+/**
+ * Linear backoff retry policy
+ * Delay increases linearly with each attempt
+ */
+export declare class LinearBackoffPolicy extends BaseRetryPolicy {
+    readonly name = "linear-backoff";
+    private readonly delayIncrementMs;
+    private readonly initialDelayMs;
+    constructor(config?: {
+        maxAttempts?: number;
+        maxTotalTimeMs?: number;
+        initialDelayMs?: number;
+        delayIncrementMs?: number;
+        retryableErrors?: string[];
+        nonRetryableErrors?: string[];
+    });
+    shouldRetry(context: RetryContext): RetryDecision;
+}
+/**
+ * Fixed delay retry policy
+ * Same delay for all retry attempts
+ */
+export declare class FixedDelayPolicy extends BaseRetryPolicy {
+    readonly name = "fixed-delay";
+    private readonly delayMs;
+    constructor(config?: {
+        maxAttempts?: number;
+        maxTotalTimeMs?: number;
+        delayMs?: number;
+        retryableErrors?: string[];
+        nonRetryableErrors?: string[];
+    });
+    shouldRetry(context: RetryContext): RetryDecision;
+}
+/**
+ * No retry policy - never retries
+ */
+export declare class NoRetryPolicy implements RetryPolicy {
+    readonly name = "no-retry";
+    readonly maxAttempts = 1;
+    readonly maxTotalTimeMs = 0;
+    shouldRetry(_context: RetryContext): RetryDecision;
+}
+/**
+ * Circuit breaker aware retry policy
+ * Works with circuit breaker state to prevent retries when circuit is open
+ */
+export declare class CircuitBreakerAwarePolicy extends BaseRetryPolicy {
+    readonly name = "circuit-breaker-aware";
+    private readonly innerPolicy;
+    private failures;
+    private lastFailure;
+    private circuitState;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    constructor(config?: {
+        innerPolicy?: RetryPolicy;
+        failureThreshold?: number;
+        resetTimeoutMs?: number;
+        maxAttempts?: number;
+        maxTotalTimeMs?: number;
+        retryableErrors?: string[];
+        nonRetryableErrors?: string[];
+    });
+    shouldRetry(context: RetryContext): RetryDecision;
+    recordFailure(): void;
+    recordSuccess(): void;
+    getCircuitState(): "closed" | "open" | "half-open";
+    reset(): void;
+}
+/**
+ * Retry executor - executes operations with retry policy
+ */
+export declare class RetryExecutor {
+    private readonly policy;
+    constructor(policy: RetryPolicy);
+    /**
+     * Execute an operation with retry
+     * @param operation - The async operation to execute
+     * @param operationName - Name for logging
+     * @returns The result of the operation
+     * @throws The last error if all retries fail
+     */
+    execute<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+    private delay;
+}
+/**
+ * Factory for creating retry policies
+ */
+export declare class RetryPolicyFactory {
+    /**
+     * Create a default policy for production use
+     */
+    static createDefault(): ExponentialBackoffPolicy;
+    /**
+     * Create an aggressive policy for critical operations
+     */
+    static createAggressive(): ExponentialBackoffPolicy;
+    /**
+     * Create a conservative policy for non-critical operations
+     */
+    static createConservative(): LinearBackoffPolicy;
+    /**
+     * Create a circuit breaker aware policy
+     */
+    static createWithCircuitBreaker(config?: {
+        failureThreshold?: number;
+        resetTimeoutMs?: number;
+    }): CircuitBreakerAwarePolicy;
+}

package/dist/observability/retryPolicy.js

@@ -0,0 +1,383 @@
+/**
+ * Retry Policy
+ * Configurable retry strategies for observability exporters
+ */
+import { logger } from "../utils/logger.js";
+/**
+ * Base retry policy with common configuration
+ */
+export class BaseRetryPolicy {
+    maxAttempts;
+    maxTotalTimeMs;
+    retryableErrors;
+    nonRetryableErrors;
+    constructor(config) {
+        this.maxAttempts = config.maxAttempts ?? 3;
+        this.maxTotalTimeMs = config.maxTotalTimeMs ?? 60000; // 1 minute
+        this.retryableErrors = new Set(config.retryableErrors ?? [
+            "ECONNRESET",
+            "ETIMEDOUT",
+            "ECONNREFUSED",
+            "EPIPE",
+            "ENOTFOUND",
+            "ENETUNREACH",
+            "EAI_AGAIN",
+            "429", // Rate limit
+            "500", // Internal server error
+            "502", // Bad gateway
+            "503", // Service unavailable
+            "504", // Gateway timeout
+        ]);
+        this.nonRetryableErrors = new Set(config.nonRetryableErrors ?? [
+            "400", // Bad request
+            "401", // Unauthorized
+            "403", // Forbidden
+            "404", // Not found
+            "422", // Unprocessable entity
+        ]);
+    }
+    isRetryableError(error) {
+        const errorCode = this.extractErrorCode(error);
+        // Check if explicitly non-retryable
+        if (this.nonRetryableErrors.has(errorCode)) {
+            return false;
+        }
+        // Check if explicitly retryable
+        if (this.retryableErrors.has(errorCode)) {
+            return true;
+        }
+        // Default: retry on network-like errors
+        return (error.message.includes("timeout") ||
+            error.message.includes("ECONNRESET") ||
+            error.message.includes("network"));
+    }
+    extractErrorCode(error) {
+        // Check for HTTP status code in error
+        const httpMatch = error.message.match(/(\d{3})/);
+        if (httpMatch) {
+            return httpMatch[1];
+        }
+        // Check for Node.js error code
+        const nodeError = error;
+        if (nodeError.code) {
+            return nodeError.code;
+        }
+        return "UNKNOWN";
+    }
+}
+/**
+ * Exponential backoff retry policy
+ * Delay increases exponentially with each attempt
+ */
+export class ExponentialBackoffPolicy extends BaseRetryPolicy {
+    name = "exponential-backoff";
+    baseDelayMs;
+    maxDelayMs;
+    jitterFactor;
+    constructor(config) {
+        super(config ?? {});
+        this.baseDelayMs = config?.baseDelayMs ?? 1000;
+        this.maxDelayMs = config?.maxDelayMs ?? 30000;
+        this.jitterFactor = config?.jitterFactor ?? 0.1;
+    }
+    shouldRetry(context) {
+        // Check max attempts
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        // Check max total time
+        if (context.elapsedMs >= this.maxTotalTimeMs) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max total time (${this.maxTotalTimeMs}ms) exceeded`,
+            };
+        }
+        // Check if error is retryable
+        if (!this.isRetryableError(context.error)) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Error not retryable: ${context.error.message}`,
+            };
+        }
+        // Calculate delay with exponential backoff
+        const exponentialDelay = this.baseDelayMs * 2 ** context.attempt;
+        const cappedDelay = Math.min(exponentialDelay, this.maxDelayMs);
+        // Add jitter
+        const jitter = cappedDelay * this.jitterFactor * (Math.random() * 2 - 1);
+        const delayMs = Math.max(0, Math.round(cappedDelay + jitter));
+        return {
+            shouldRetry: true,
+            delayMs,
+            reason: `Retrying after ${delayMs}ms (attempt ${context.attempt + 1}/${this.maxAttempts})`,
+        };
+    }
+}
+/**
+ * Linear backoff retry policy
+ * Delay increases linearly with each attempt
+ */
+export class LinearBackoffPolicy extends BaseRetryPolicy {
+    name = "linear-backoff";
+    delayIncrementMs;
+    initialDelayMs;
+    constructor(config) {
+        super(config ?? {});
+        this.initialDelayMs = config?.initialDelayMs ?? 1000;
+        this.delayIncrementMs = config?.delayIncrementMs ?? 1000;
+    }
+    shouldRetry(context) {
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        if (context.elapsedMs >= this.maxTotalTimeMs) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max total time (${this.maxTotalTimeMs}ms) exceeded`,
+            };
+        }
+        if (!this.isRetryableError(context.error)) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Error not retryable: ${context.error.message}`,
+            };
+        }
+        const delayMs = this.initialDelayMs + context.attempt * this.delayIncrementMs;
+        return {
+            shouldRetry: true,
+            delayMs,
+            reason: `Retrying after ${delayMs}ms (attempt ${context.attempt + 1}/${this.maxAttempts})`,
+        };
+    }
+}
+/**
+ * Fixed delay retry policy
+ * Same delay for all retry attempts
+ */
+export class FixedDelayPolicy extends BaseRetryPolicy {
+    name = "fixed-delay";
+    delayMs;
+    constructor(config) {
+        super(config ?? {});
+        this.delayMs = config?.delayMs ?? 1000;
+    }
+    shouldRetry(context) {
+        if (context.attempt >= this.maxAttempts) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max attempts (${this.maxAttempts}) exceeded`,
+            };
+        }
+        if (context.elapsedMs >= this.maxTotalTimeMs) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Max total time (${this.maxTotalTimeMs}ms) exceeded`,
+            };
+        }
+        if (!this.isRetryableError(context.error)) {
+            return {
+                shouldRetry: false,
+                delayMs: 0,
+                reason: `Error not retryable: ${context.error.message}`,
+            };
+        }
+        return {
+            shouldRetry: true,
+            delayMs: this.delayMs,
+            reason: `Retrying after ${this.delayMs}ms (attempt ${context.attempt + 1}/${this.maxAttempts})`,
+        };
+    }
+}
+/**
+ * No retry policy - never retries
+ */
+export class NoRetryPolicy {
+    name = "no-retry";
+    maxAttempts = 1;
+    maxTotalTimeMs = 0;
+    shouldRetry(_context) {
+        return {
+            shouldRetry: false,
+            delayMs: 0,
+            reason: "Retry disabled",
+        };
+    }
+}
+/**
+ * Circuit breaker aware retry policy
+ * Works with circuit breaker state to prevent retries when circuit is open
+ */
+export class CircuitBreakerAwarePolicy extends BaseRetryPolicy {
+    name = "circuit-breaker-aware";
+    innerPolicy;
+    failures = 0;
+    lastFailure = 0;
+    circuitState = "closed";
+    failureThreshold;
+    resetTimeoutMs;
+    constructor(config) {
+        super(config ?? {});
+        this.innerPolicy = config?.innerPolicy ?? new ExponentialBackoffPolicy();
+        this.failureThreshold = config?.failureThreshold ?? 5;
+        this.resetTimeoutMs = config?.resetTimeoutMs ?? 30000;
+    }
+    shouldRetry(context) {
+        // Check circuit state
+        if (this.circuitState === "open") {
+            if (Date.now() - this.lastFailure > this.resetTimeoutMs) {
+                this.circuitState = "half-open";
+                logger.info(`[${this.name}] Circuit half-open, allowing probe request`);
+            }
+            else {
+                return {
+                    shouldRetry: false,
+                    delayMs: 0,
+                    reason: "Circuit breaker open",
+                };
+            }
+        }
+        // Delegate to inner policy
+        const decision = this.innerPolicy.shouldRetry(context);
+        // Record result for circuit breaker
+        if (!decision.shouldRetry) {
+            this.recordFailure();
+        }
+        return decision;
+    }
+    recordFailure() {
+        this.failures++;
+        this.lastFailure = Date.now();
+        if (this.failures >= this.failureThreshold) {
+            this.circuitState = "open";
+            logger.warn(`[${this.name}] Circuit opened after ${this.failures} failures`);
+        }
+    }
+    recordSuccess() {
+        if (this.circuitState === "half-open") {
+            logger.info(`[${this.name}] Circuit closed after successful request`);
+        }
+        this.failures = 0;
+        this.circuitState = "closed";
+    }
+    getCircuitState() {
+        return this.circuitState;
+    }
+    reset() {
+        this.failures = 0;
+        this.circuitState = "closed";
+        this.lastFailure = 0;
+    }
+}
+/**
+ * Retry executor - executes operations with retry policy
+ */
+export class RetryExecutor {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /**
+     * Execute an operation with retry
+     * @param operation - The async operation to execute
+     * @param operationName - Name for logging
+     * @returns The result of the operation
+     * @throws The last error if all retries fail
+     */
+    async execute(operation, operationName) {
+        const startTime = Date.now();
+        let lastError;
+        let attempt = 0;
+        while (attempt < this.policy.maxAttempts) {
+            try {
+                const result = await operation();
+                // Record success if policy supports it
+                if (this.policy instanceof CircuitBreakerAwarePolicy) {
+                    this.policy.recordSuccess();
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                const elapsed = Date.now() - startTime;
+                const decision = this.policy.shouldRetry({
+                    attempt,
+                    error: lastError,
+                    elapsedMs: elapsed,
+                    operationName,
+                });
+                if (!decision.shouldRetry) {
+                    logger.warn(`[RetryExecutor] ${operationName}: ${decision.reason}`);
+                    break;
+                }
+                logger.debug(`[RetryExecutor] ${operationName}: ${decision.reason}`);
+                await this.delay(decision.delayMs);
+                attempt++;
+            }
+        }
+        throw (lastError ??
+            new Error(`${operationName} failed after ${attempt} attempts`));
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Factory for creating retry policies
+ */
+export class RetryPolicyFactory {
+    /**
+     * Create a default policy for production use
+     */
+    static createDefault() {
+        return new ExponentialBackoffPolicy({
+            maxAttempts: 3,
+            baseDelayMs: 1000,
+            maxDelayMs: 30000,
+        });
+    }
+    /**
+     * Create an aggressive policy for critical operations
+     */
+    static createAggressive() {
+        return new ExponentialBackoffPolicy({
+            maxAttempts: 5,
+            maxTotalTimeMs: 120000,
+            baseDelayMs: 500,
+            maxDelayMs: 60000,
+        });
+    }
+    /**
+     * Create a conservative policy for non-critical operations
+     */
+    static createConservative() {
+        return new LinearBackoffPolicy({
+            maxAttempts: 2,
+            maxTotalTimeMs: 10000,
+            initialDelayMs: 500,
+            delayIncrementMs: 500,
+        });
+    }
+    /**
+     * Create a circuit breaker aware policy
+     */
+    static createWithCircuitBreaker(config) {
+        return new CircuitBreakerAwarePolicy({
+            innerPolicy: RetryPolicyFactory.createDefault(),
+            failureThreshold: config?.failureThreshold ?? 5,
+            resetTimeoutMs: config?.resetTimeoutMs ?? 30000,
+        });
+    }
+}

package/dist/observability/sampling/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sampling strategies exports
+ */
+export { AlwaysSampler, AttributeBasedSampler, CompositeSampler, CustomSampler, ErrorOnlySampler, NeverSampler, PrioritySampler, RatioSampler, type Sampler, SamplerFactory, TraceIdRatioSampler, } from "./samplers.js";