@juspay/neurolink 7.7.0 → 7.8.0

package/dist/lib/providers/sagemaker/adaptive-semaphore.js

@@ -0,0 +1,212 @@
+/**
+ * Adaptive Semaphore Utility
+ *
+ * Provides a sophisticated semaphore implementation with dynamic concurrency adjustment
+ * for optimal resource utilization and performance tuning based on response times and error rates.
+ */
+import { logger } from "../../utils/logger.js";
+/**
+ * Adaptive semaphore that automatically adjusts concurrency based on performance metrics
+ */
+export class AdaptiveSemaphore {
+    count;
+    waiters = [];
+    currentConcurrency;
+    activeRequests = 0;
+    completedCount = 0;
+    errorCount = 0;
+    responseTimes = [];
+    maxConcurrency;
+    minConcurrency;
+    constructor(config) {
+        this.currentConcurrency = config.initialConcurrency;
+        this.count = config.initialConcurrency;
+        this.maxConcurrency = config.maxConcurrency;
+        this.minConcurrency = config.minConcurrency;
+        logger.debug("AdaptiveSemaphore initialized", {
+            initialConcurrency: config.initialConcurrency,
+            maxConcurrency: config.maxConcurrency,
+            minConcurrency: config.minConcurrency,
+        });
+    }
+    /**
+     * Acquire a semaphore permit, waiting if necessary
+     */
+    async acquire() {
+        return new Promise((resolve) => {
+            if (this.count > 0) {
+                this.count--;
+                this.activeRequests++;
+                resolve();
+            }
+            else {
+                this.waiters.push(() => {
+                    this.count--;
+                    this.activeRequests++;
+                    resolve();
+                });
+            }
+        });
+    }
+    /**
+     * Release a semaphore permit and wake up waiting requests
+     */
+    release() {
+        this.activeRequests--;
+        if (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter();
+        }
+        else {
+            this.count++;
+        }
+    }
+    /**
+     * Record successful completion with response time for adaptive adjustment
+     */
+    recordSuccess(responseTimeMs) {
+        this.completedCount++;
+        this.responseTimes.push(responseTimeMs);
+        // Keep only recent response times for calculation (last 10 responses)
+        if (this.responseTimes.length > 10) {
+            this.responseTimes.shift();
+        }
+        this.adjustConcurrencyBasedOnPerformance(responseTimeMs, false);
+    }
+    /**
+     * Record error for adaptive adjustment
+     */
+    recordError(responseTimeMs) {
+        this.errorCount++;
+        if (responseTimeMs) {
+            this.responseTimes.push(responseTimeMs);
+            if (this.responseTimes.length > 10) {
+                this.responseTimes.shift();
+            }
+        }
+        this.adjustConcurrencyBasedOnPerformance(responseTimeMs || 0, true);
+    }
+    /**
+     * Manually adjust concurrency level
+     */
+    adjustConcurrency(newLimit) {
+        const clampedLimit = Math.max(this.minConcurrency, Math.min(this.maxConcurrency, newLimit));
+        const diff = clampedLimit - (this.currentConcurrency - this.count);
+        this.count += diff;
+        this.currentConcurrency = clampedLimit;
+        logger.debug("Concurrency adjusted", {
+            newConcurrency: clampedLimit,
+            previousConcurrency: this.currentConcurrency - diff,
+            availableCount: this.count,
+            activeRequests: this.activeRequests,
+        });
+        // Wake up waiting requests if we increased concurrency
+        while (this.count > 0 && this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            this.count--;
+            this.activeRequests++;
+            waiter();
+        }
+    }
+    /**
+     * Get current performance metrics
+     */
+    getMetrics() {
+        const averageResponseTime = this.responseTimes.length > 0
+            ? this.responseTimes.reduce((sum, time) => sum + time, 0) /
+                this.responseTimes.length
+            : 0;
+        return {
+            activeRequests: this.activeRequests,
+            currentConcurrency: this.currentConcurrency,
+            completedCount: this.completedCount,
+            errorCount: this.errorCount,
+            averageResponseTime,
+            waitingCount: this.waiters.length,
+        };
+    }
+    /**
+     * Reset metrics for new batch or session
+     */
+    resetMetrics() {
+        this.completedCount = 0;
+        this.errorCount = 0;
+        this.responseTimes = [];
+    }
+    /**
+     * Automatically adjust concurrency based on performance indicators
+     */
+    adjustConcurrencyBasedOnPerformance(responseTimeMs, isError) {
+        const metrics = this.getMetrics();
+        if (isError) {
+            // On error, reduce concurrency to be more conservative
+            if (this.currentConcurrency > this.minConcurrency) {
+                this.adjustConcurrency(Math.max(this.minConcurrency, this.currentConcurrency - 1));
+                logger.warn("Reduced concurrency due to error", {
+                    newConcurrency: this.currentConcurrency,
+                    errorCount: this.errorCount,
+                });
+            }
+            return;
+        }
+        // Only adjust after we have some data to work with
+        if (this.completedCount < 3) {
+            return;
+        }
+        const fastResponseThreshold = 2000; // 2 seconds
+        const slowResponseThreshold = 5000; // 5 seconds
+        if (responseTimeMs < fastResponseThreshold &&
+            metrics.averageResponseTime < fastResponseThreshold &&
+            this.currentConcurrency < this.maxConcurrency) {
+            // Fast responses and no bottleneck - increase concurrency
+            this.adjustConcurrency(Math.min(this.maxConcurrency, this.currentConcurrency + 1));
+            logger.debug("Increased concurrency due to fast responses", {
+                newConcurrency: this.currentConcurrency,
+                averageResponseTime: metrics.averageResponseTime,
+            });
+        }
+        else if (responseTimeMs > slowResponseThreshold &&
+            this.currentConcurrency > this.minConcurrency) {
+            // Slow responses - decrease concurrency
+            this.adjustConcurrency(Math.max(this.minConcurrency, this.currentConcurrency - 1));
+            logger.debug("Decreased concurrency due to slow responses", {
+                newConcurrency: this.currentConcurrency,
+                responseTime: responseTimeMs,
+            });
+        }
+    }
+    /**
+     * Check if semaphore is idle (no active or waiting requests)
+     */
+    isIdle() {
+        return this.activeRequests === 0 && this.waiters.length === 0;
+    }
+    /**
+     * Get current concurrency limit
+     */
+    getCurrentConcurrency() {
+        return this.currentConcurrency;
+    }
+    /**
+     * Get number of active requests
+     */
+    getActiveRequestCount() {
+        return this.activeRequests;
+    }
+    /**
+     * Get number of waiting requests
+     */
+    getWaitingRequestCount() {
+        return this.waiters.length;
+    }
+}
+/**
+ * Factory function to create an adaptive semaphore with default configuration
+ */
+export function createAdaptiveSemaphore(initialConcurrency, maxConcurrency = 10, minConcurrency = 1) {
+    return new AdaptiveSemaphore({
+        initialConcurrency,
+        maxConcurrency,
+        minConcurrency,
+    });
+}

package/dist/lib/providers/sagemaker/client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * AWS SageMaker Runtime Client Wrapper
+ *
+ * This module provides a wrapper around the AWS SDK SageMaker Runtime client
+ * with enhanced error handling, retry logic, and NeuroLink-specific features.
+ */
+import type { SageMakerConfig, InvokeEndpointParams, InvokeEndpointResponse } from "./types.js";
+/**
+ * Enhanced SageMaker Runtime client with retry logic and error handling
+ */
+export declare class SageMakerRuntimeClient {
+    private client;
+    private config;
+    private isDisposed;
+    constructor(config: SageMakerConfig);
+    /**
+     * Invoke a SageMaker endpoint for synchronous inference
+     *
+     * @param params - Endpoint invocation parameters
+     * @returns Promise resolving to the inference response
+     * @throws {SageMakerError} When the request fails
+     */
+    invokeEndpoint(params: InvokeEndpointParams): Promise<InvokeEndpointResponse>;
+    /**
+     * Invoke a SageMaker endpoint with streaming response
+     *
+     * @param params - Endpoint invocation parameters for streaming
+     * @returns Promise resolving to async iterable of response chunks
+     * @throws {SageMakerError} When the request fails
+     */
+    invokeEndpointWithStreaming(params: InvokeEndpointParams): Promise<{
+        Body: AsyncIterable<Uint8Array>;
+        ContentType?: string;
+        InvokedProductionVariant?: string;
+    }>;
+    /**
+     * Execute a request with automatic retry logic
+     *
+     * @param operation - Function that executes the AWS SDK command
+     * @param endpointName - Endpoint name for error context
+     * @param attempt - Current attempt number (for recursive retries)
+     * @returns Promise resolving to the operation result
+     */
+    private executeWithRetry;
+    /**
+     * Validate endpoint connectivity and permissions
+     *
+     * @param endpointName - Name of the endpoint to validate
+     * @returns Promise resolving to validation result
+     */
+    validateEndpoint(endpointName: string): Promise<{
+        isValid: boolean;
+        status?: string;
+        error?: string;
+    }>;
+    /**
+     * Get client configuration summary for debugging
+     *
+     * @returns Configuration summary (with sensitive data masked)
+     */
+    getConfigSummary(): Record<string, unknown>;
+    /**
+     * Check if the client is properly configured
+     *
+     * @returns True if client appears to be properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Convert AWS SDK async iterable stream with payload structure
+     */
+    private convertAsyncIterableStream;
+    /**
+     * Convert Node.js readable stream with reader interface
+     */
+    private convertReadableStream;
+    /**
+     * Convert non-stream data to single Uint8Array chunk as fallback
+     */
+    private convertFallbackData;
+    /**
+     * Convert AWS response stream to async iterable of Uint8Array chunks
+     * Refactored into smaller focused methods for different stream types
+     */
+    private convertAWSStreamToIterable;
+    /**
+     * Check if the client has been disposed
+     */
+    get disposed(): boolean;
+    /**
+     * Dispose of the client and clean up resources using explicit disposed state pattern
+     *
+     * AWS SDK v3 Automatic Resource Management:
+     * ========================================
+     *
+     * The AWS SDK v3 uses automatic resource cleanup and doesn't require explicit disposal
+     * of client instances in most cases. Here's how it works:
+     *
+     * 1. **HTTP Connection Pools**: AWS SDK v3 uses Node.js's built-in HTTP agent with
+     *    connection pooling. These connections are automatically managed and will be
+     *    closed when the Node.js process exits or becomes idle.
+     *
+     * 2. **Memory Management**: SDK clients don't hold significant resources that require
+     *    manual cleanup. The JavaScript garbage collector handles memory deallocation
+     *    when client references are removed.
+     *
+     * 3. **Background Timers**: Any internal timers (for retries, timeouts) are automatically
+     *    cleared when operations complete or the client goes out of scope.
+     *
+     * 4. **Keep-Alive Connections**: HTTP keep-alive connections are managed by the
+     *    underlying HTTP agent and will timeout automatically based on the configured
+     *    keep-alive timeout (typically 15 seconds).
+     *
+     * Why We Still Implement dispose():
+     * =================================
+     *
+     * 1. **Explicit State Management**: Provides clear lifecycle control and prevents
+     *    accidental usage of disposed clients.
+     *
+     * 2. **Resource Tracking**: Allows our application to track when clients are no
+     *    longer needed, which is useful for debugging and monitoring.
+     *
+     * 3. **Defensive Programming**: Ensures we don't rely on automatic cleanup in
+     *    environments where it might not work as expected.
+     *
+     * 4. **Future Compatibility**: If future SDK versions require explicit cleanup,
+     *    we already have the infrastructure in place.
+     *
+     * For more information, see:
+     * - https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/
+     * - https://aws.amazon.com/blogs/developer/node-js-configuring-maxsockets-in-sdk-for-javascript/
+     */
+    dispose(): void;
+    /**
+     * Ensure client is not disposed before operations
+     */
+    private ensureNotDisposed;
+}
+/**
+ * Factory function to create a SageMaker Runtime client
+ *
+ * @param config - SageMaker configuration
+ * @returns Configured SageMakerRuntimeClient instance
+ */
+export declare function createSageMakerRuntimeClient(config: SageMakerConfig): SageMakerRuntimeClient;
+/**
+ * Utility function to test SageMaker connectivity
+ *
+ * @param config - SageMaker configuration
+ * @param endpointName - Endpoint to test
+ * @returns Promise resolving to connectivity test result
+ */
+export declare function testSageMakerConnectivity(config: SageMakerConfig, endpointName: string): Promise<{
+    connected: boolean;
+    latency?: number;
+    error?: string;
+}>;