@hff-ai/media-processor-client 1.0.0

package/dist/MediaProcessor.js

@@ -0,0 +1,731 @@
+"use strict";
+/**
+ * MediaProcessor - Main client class for communicating with the Media Processor service
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaProcessor = void 0;
+const events_1 = require("events");
+const amqplib_1 = __importDefault(require("amqplib"));
+const axios_1 = __importDefault(require("axios"));
+const uuid_1 = require("uuid");
+const types_1 = require("./types");
+const errors_1 = require("./errors");
+/**
+ * Default options for the processor
+ */
+const DEFAULT_OPTIONS = {
+    maxConcurrentJobs: 5,
+    defaultUserId: 'anonymous',
+    autoReconnect: true,
+    reconnectDelay: 5000,
+    maxReconnectAttempts: 10,
+    requestTimeout: 30000,
+};
+/**
+ * MIME type mappings for common extensions
+ */
+const MIME_TYPES = {
+    // Images
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.bmp': 'image/bmp',
+    '.tiff': 'image/tiff',
+    '.tif': 'image/tiff',
+    // Videos
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.avi': 'video/x-msvideo',
+    '.mkv': 'video/x-matroska',
+    '.webm': 'video/webm',
+    '.wmv': 'video/x-ms-wmv',
+    '.flv': 'video/x-flv',
+    // Archives
+    '.zip': 'application/zip',
+};
+/**
+ * MediaProcessor client class
+ *
+ * Provides a stream-like interface for communicating with the Media Processor service.
+ * Handles AMQP connections, message publishing, and event emission for processing updates.
+ */
+class MediaProcessor extends events_1.EventEmitter {
+    /**
+     * Create a new MediaProcessor instance
+     *
+     * @param config - Configuration for the media processor connection
+     */
+    constructor(config) {
+        super();
+        this.connection = null;
+        this.channel = null;
+        this.consumerTag = null;
+        this._isConnected = false;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.isShuttingDown = false;
+        /** Map of pending async requests, keyed by correlation ID */
+        this.pendingRequests = new Map();
+        // Validate configuration
+        this.validateConfig(config);
+        this.config = config;
+        this.options = { ...DEFAULT_OPTIONS, ...config.options };
+        // Set up queue names based on system
+        this.requestQueue = `${config.system}.media.processing.requests`;
+        this.updatesQueue = `${config.system}.media.processing.updates`;
+        // Create HTTP client
+        this.httpClient = axios_1.default.create({
+            baseURL: config.processorUrl,
+            timeout: this.options.requestTimeout,
+            headers: {
+                'Authorization': `Bearer ${config.token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Validate the configuration object
+     */
+    validateConfig(config) {
+        if (!config.processorUrl) {
+            throw errors_1.ConfigurationError.missingField('processorUrl');
+        }
+        if (!config.processorAmqp) {
+            throw errors_1.ConfigurationError.missingField('processorAmqp');
+        }
+        if (!config.token) {
+            throw errors_1.ConfigurationError.missingField('token');
+        }
+        if (!config.system) {
+            throw errors_1.ConfigurationError.missingField('system');
+        }
+        if (!config.s3Details) {
+            throw errors_1.ConfigurationError.missingField('s3Details');
+        }
+        // Validate S3 config
+        const s3 = config.s3Details;
+        if (!s3.endpoint) {
+            throw errors_1.ConfigurationError.invalidS3Config('missing endpoint');
+        }
+        if (!s3.accessKey) {
+            throw errors_1.ConfigurationError.invalidS3Config('missing accessKey');
+        }
+        if (!s3.secretAccessKey) {
+            throw errors_1.ConfigurationError.invalidS3Config('missing secretAccessKey');
+        }
+        if (!s3.bucketName) {
+            throw errors_1.ConfigurationError.invalidS3Config('missing bucketName');
+        }
+        // Validate URLs
+        try {
+            new URL(config.processorUrl);
+        }
+        catch {
+            throw errors_1.ConfigurationError.invalidUrl('processorUrl', config.processorUrl);
+        }
+    }
+    /**
+     * Connect to the media processor service
+     *
+     * This will:
+     * 1. Set up the system configuration via REST API
+     * 2. Establish AMQP connection
+     * 3. Start consuming update messages
+     */
+    async connect() {
+        if (this._isConnected) {
+            return;
+        }
+        this.isShuttingDown = false;
+        try {
+            // Step 1: Set up system via REST API
+            await this.setupSystem();
+            // Step 2: Connect to AMQP
+            await this.connectAmqp();
+            // Step 3: Set up consumer for updates
+            await this.setupConsumer();
+            this._isConnected = true;
+            this.reconnectAttempts = 0;
+            this.emit('connected');
+        }
+        catch (error) {
+            this._isConnected = false;
+            if (error instanceof errors_1.ConnectionError || error instanceof errors_1.ConfigurationError) {
+                throw error;
+            }
+            if (axios_1.default.isAxiosError(error)) {
+                if (error.response?.status === 401 || error.response?.status === 403) {
+                    throw errors_1.ConnectionError.authFailed();
+                }
+                throw errors_1.ConnectionError.restApiError(error.message, error.response?.status, error.response?.data);
+            }
+            throw errors_1.ConnectionError.connectionFailed('media processor', error);
+        }
+    }
+    /**
+     * Set up the system configuration via REST API
+     */
+    async setupSystem() {
+        const systemConfig = {
+            bucket: {
+                provider: this.config.s3Details.provider,
+                endpoint: this.config.s3Details.endpoint,
+                access_key: this.config.s3Details.accessKey,
+                secret_access_key: this.config.s3Details.secretAccessKey,
+                region: this.config.s3Details.region,
+                bucket_name: this.config.s3Details.bucketName,
+            },
+            max_concurrent_jobs: this.options.maxConcurrentJobs,
+        };
+        await this.httpClient.post(`/api/v1/systems/${this.config.system}`, systemConfig);
+    }
+    /**
+     * Connect to RabbitMQ
+     */
+    async connectAmqp() {
+        try {
+            this.connection = await amqplib_1.default.connect(this.config.processorAmqp);
+            // Handle connection events
+            this.connection.on('error', (err) => {
+                this.handleConnectionError(err);
+            });
+            this.connection.on('close', () => {
+                if (!this.isShuttingDown) {
+                    this.handleConnectionClose();
+                }
+            });
+            this.channel = await this.connection.createChannel();
+            // Ensure queues exist
+            await this.channel.assertQueue(this.requestQueue, { durable: true });
+            await this.channel.assertQueue(this.updatesQueue, { durable: true });
+        }
+        catch (error) {
+            throw errors_1.ConnectionError.amqpError('Failed to connect to RabbitMQ', error);
+        }
+    }
+    /**
+     * Set up the consumer for update messages
+     */
+    async setupConsumer() {
+        if (!this.channel) {
+            throw errors_1.ConnectionError.amqpError('Channel not available');
+        }
+        const { consumerTag } = await this.channel.consume(this.updatesQueue, (msg) => this.handleMessage(msg), { noAck: false });
+        this.consumerTag = consumerTag;
+    }
+    /**
+     * Handle incoming messages from the updates queue
+     *
+     * Messages are routed based on their correlationId:
+     *
+     * 1. Has correlationId AND matches pending request → handle via Promise
+     * 2. Has correlationId but NO match → orphaned async message → unhandled_message only
+     * 3. No correlationId → queue-based message → emit events
+     *
+     * This ensures:
+     * - Clean separation between async and queue API styles
+     * - Orphaned async messages (from dead processes) don't pollute event handlers
+     * - Queue messages are properly routed to event listeners
+     */
+    handleMessage(msg) {
+        if (!msg || !this.channel) {
+            return;
+        }
+        try {
+            const content = msg.content.toString();
+            const update = JSON.parse(content);
+            // Extract correlation ID from message details
+            const correlationId = this.extractCorrelationId(update);
+            // CASE 1 & 2: Message has a correlationId (was created by processS3*() async method)
+            if (correlationId) {
+                const pending = this.pendingRequests.get(correlationId);
+                if (pending) {
+                    // CASE 1: Matching pending request - handle via Promise
+                    if ((0, types_1.isProgressMessage)(update)) {
+                        if (pending.onProgress) {
+                            pending.onProgress(update);
+                        }
+                    }
+                    else if ((0, types_1.isResultMessage)(update)) {
+                        if (pending.timeoutId) {
+                            clearTimeout(pending.timeoutId);
+                        }
+                        this.pendingRequests.delete(correlationId);
+                        pending.resolve(update);
+                    }
+                    else if ((0, types_1.isErrorMessage)(update)) {
+                        if (pending.timeoutId) {
+                            clearTimeout(pending.timeoutId);
+                        }
+                        this.pendingRequests.delete(correlationId);
+                        pending.reject(errors_1.ProcessingError.fromErrorMessage(update));
+                    }
+                }
+                else {
+                    // CASE 2: Orphaned async message (process that awaited it is gone)
+                    // Do NOT emit to event handlers - only notify via unhandled_message
+                    if ((0, types_1.isResultMessage)(update) || (0, types_1.isErrorMessage)(update)) {
+                        this.emit('unhandled_message', {
+                            type: (0, types_1.isResultMessage)(update) ? 'completed' : 'error',
+                            mediaType: update.mediaType,
+                            mediaId: update.mediaId,
+                            message: `Orphaned async response (correlationId: ${correlationId}) - awaiting process no longer exists`,
+                        });
+                    }
+                    // Progress messages for orphaned requests are silently dropped
+                }
+                // Acknowledge and return - messages with correlationId never go to event handlers
+                this.channel.ack(msg);
+                return;
+            }
+            // CASE 3: No correlationId - this is a queue-based message (from queueS3*())
+            // Route to event handlers
+            if ((0, types_1.isProgressMessage)(update)) {
+                this.emitProgressEvent(update);
+            }
+            else if ((0, types_1.isResultMessage)(update)) {
+                this.emitResultEvent(update);
+                this.warnIfNoListeners(update, 'completed');
+            }
+            else if ((0, types_1.isErrorMessage)(update)) {
+                this.emitErrorEvent(update);
+                this.warnIfNoListeners(update, 'error');
+            }
+            // Acknowledge the message
+            this.channel.ack(msg);
+        }
+        catch (error) {
+            // Reject malformed messages
+            this.channel.nack(msg, false, false);
+            this.emit('error', new Error(`Failed to process message: ${error.message}`));
+        }
+    }
+    /**
+     * Extract correlation ID from an update message
+     */
+    extractCorrelationId(update) {
+        if ('details' in update && update.details?.correlationId) {
+            return update.details.correlationId;
+        }
+        return undefined;
+    }
+    /**
+     * Warn if there are no listeners for a message type
+     * Helps detect orphaned messages that would otherwise be silently lost
+     */
+    warnIfNoListeners(update, eventSuffix) {
+        const genericEvent = eventSuffix === 'error' ? 'processing_error' : 'completed';
+        const specificEvent = `${update.mediaType}_${eventSuffix}`;
+        const hasGenericListener = this.listenerCount(genericEvent) > 0;
+        const hasSpecificListener = this.listenerCount(specificEvent) > 0;
+        if (!hasGenericListener && !hasSpecificListener) {
+            // Emit a warning event that users can optionally listen to
+            this.emit('unhandled_message', {
+                type: eventSuffix,
+                mediaType: update.mediaType,
+                mediaId: update.mediaId,
+                message: `No listeners for '${specificEvent}' or '${genericEvent}' - message will be dropped`,
+            });
+        }
+    }
+    /**
+     * Emit progress events
+     */
+    emitProgressEvent(msg) {
+        this.emit('progress', msg);
+        this.emit(`${msg.mediaType}_progress`, msg);
+    }
+    /**
+     * Emit result events
+     */
+    emitResultEvent(msg) {
+        this.emit('completed', msg);
+        this.emit(`${msg.mediaType}_completed`, msg);
+    }
+    /**
+     * Emit error events
+     */
+    emitErrorEvent(msg) {
+        this.emit('processing_error', msg);
+        this.emit(`${msg.mediaType}_error`, msg);
+    }
+    /**
+     * Handle connection errors
+     */
+    handleConnectionError(error) {
+        this._isConnected = false;
+        this.emit('error', errors_1.ConnectionError.connectionLost(error.message));
+        this.scheduleReconnect();
+    }
+    /**
+     * Handle connection close
+     */
+    handleConnectionClose() {
+        this._isConnected = false;
+        this.emit('disconnected', { reason: 'Connection closed' });
+        this.scheduleReconnect();
+    }
+    /**
+     * Schedule a reconnection attempt
+     */
+    scheduleReconnect() {
+        if (!this.options.autoReconnect || this.isShuttingDown) {
+            return;
+        }
+        if (this.options.maxReconnectAttempts > 0 &&
+            this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+            this.emit('error', errors_1.ConnectionError.reconnectFailed(this.reconnectAttempts));
+            return;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+        }
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectAttempts++;
+            this.emit('reconnecting', { attempt: this.reconnectAttempts });
+            try {
+                await this.reconnect();
+            }
+            catch {
+                // Reconnect failed, will try again
+                this.scheduleReconnect();
+            }
+        }, this.options.reconnectDelay);
+    }
+    /**
+     * Manually trigger a reconnection
+     */
+    async reconnect() {
+        // Clean up existing connections
+        await this.cleanupConnections();
+        // Reconnect
+        await this.connect();
+    }
+    /**
+     * Clean up AMQP connections
+     */
+    async cleanupConnections() {
+        try {
+            if (this.channel && this.consumerTag) {
+                await this.channel.cancel(this.consumerTag);
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        try {
+            if (this.channel) {
+                await this.channel.close();
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        try {
+            if (this.connection) {
+                await this.connection.close();
+            }
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        this.channel = null;
+        this.connection = null;
+        this.consumerTag = null;
+    }
+    /**
+     * Disconnect from the media processor service
+     */
+    async disconnect() {
+        this.isShuttingDown = true;
+        this._isConnected = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Reject all pending async requests
+        this.rejectAllPendingRequests('Connection closed');
+        await this.cleanupConnections();
+    }
+    /**
+     * Reject all pending async requests (called on disconnect)
+     */
+    rejectAllPendingRequests(reason) {
+        for (const [correlationId, pending] of this.pendingRequests) {
+            if (pending.timeoutId) {
+                clearTimeout(pending.timeoutId);
+            }
+            pending.reject(new errors_1.ProcessingError(`Processing aborted: ${reason}`, 'DISCONNECTED', correlationId, // Use correlationId as placeholder
+            'unknown'));
+        }
+        this.pendingRequests.clear();
+    }
+    /**
+     * Check if connected to the media processor
+     */
+    isConnected() {
+        return this._isConnected;
+    }
+    /**
+     * Update the authentication token
+     */
+    updateToken(token) {
+        this.config.token = token;
+        this.httpClient.defaults.headers['Authorization'] = `Bearer ${token}`;
+    }
+    /**
+     * Get the current system status
+     */
+    async getSystemStatus() {
+        try {
+            const response = await this.httpClient.get(`/api/v1/systems/${this.config.system}`);
+            return response.data;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw errors_1.ConnectionError.restApiError(error.message, error.response?.status, error.response?.data);
+            }
+            throw error;
+        }
+    }
+    // ===========================================================================
+    // Queue Methods (fire-and-forget, event-based)
+    // ===========================================================================
+    /**
+     * Queue an image for processing (fire-and-forget)
+     *
+     * Use this when you want to handle results via events.
+     *
+     * @param s3Key - S3 object key of the image to process
+     * @param options - Optional processing parameters
+     * @returns mediaId - Unique identifier for tracking this job
+     */
+    queueS3Image(s3Key, options) {
+        return this.submitProcessingRequest('image', s3Key, options);
+    }
+    /**
+     * Queue a video for processing (fire-and-forget)
+     *
+     * Use this when you want to handle results via events.
+     *
+     * @param s3Key - S3 object key of the video to process
+     * @param options - Optional processing parameters
+     * @returns mediaId - Unique identifier for tracking this job
+     */
+    queueS3Video(s3Key, options) {
+        return this.submitProcessingRequest('video', s3Key, options);
+    }
+    /**
+     * Queue a zip archive for processing (fire-and-forget)
+     *
+     * Use this when you want to handle results via events.
+     *
+     * @param s3Key - S3 object key of the zip file
+     * @param options - Optional processing parameters
+     * @returns mediaId - Unique identifier for tracking this job
+     */
+    queueS3Zip(s3Key, options) {
+        return this.submitProcessingRequest('zip', s3Key, options);
+    }
+    // ===========================================================================
+    // Process Methods (async/await, Promise-based)
+    // ===========================================================================
+    /**
+     * Process an image and wait for the result
+     *
+     * @param s3Key - S3 object key of the image to process
+     * @param options - Optional processing parameters including timeout and progress callback
+     * @returns Promise that resolves with the processing result
+     * @throws ProcessingError if processing fails
+     * @throws ProcessingError with code 'PROCESSING_TIMEOUT' if timeout is exceeded
+     */
+    processS3Image(s3Key, options) {
+        return this.submitAsyncProcessingRequest('image', s3Key, options);
+    }
+    /**
+     * Process a video and wait for the result
+     *
+     * @param s3Key - S3 object key of the video to process
+     * @param options - Optional processing parameters including timeout and progress callback
+     * @returns Promise that resolves with the processing result
+     * @throws ProcessingError if processing fails
+     * @throws ProcessingError with code 'PROCESSING_TIMEOUT' if timeout is exceeded
+     */
+    processS3Video(s3Key, options) {
+        return this.submitAsyncProcessingRequest('video', s3Key, options);
+    }
+    /**
+     * Process a zip archive and wait for the result
+     *
+     * @param s3Key - S3 object key of the zip file
+     * @param options - Optional processing parameters including timeout and progress callback
+     * @returns Promise that resolves with the processing result
+     * @throws ProcessingError if processing fails
+     * @throws ProcessingError with code 'PROCESSING_TIMEOUT' if timeout is exceeded
+     */
+    processS3Zip(s3Key, options) {
+        return this.submitAsyncProcessingRequest('zip', s3Key, options);
+    }
+    /**
+     * Submit an async processing request and return a Promise
+     */
+    submitAsyncProcessingRequest(mediaType, s3Key, options) {
+        // Generate a unique correlation ID for this request
+        const correlationId = this.generateCorrelationId();
+        // Create the promise that will be resolved/rejected when result arrives
+        return new Promise((resolve, reject) => {
+            // Set up the pending request entry
+            const pendingRequest = {
+                resolve,
+                reject,
+                onProgress: options?.onProgress,
+            };
+            // Set up timeout if specified
+            if (options?.timeout) {
+                pendingRequest.timeoutId = setTimeout(() => {
+                    this.pendingRequests.delete(correlationId);
+                    reject(errors_1.ProcessingError.timeout(options.mediaId || correlationId, mediaType, options.timeout));
+                }, options.timeout);
+            }
+            // Store the pending request
+            this.pendingRequests.set(correlationId, pendingRequest);
+            // Submit the request with correlation ID in metadata
+            try {
+                this.submitProcessingRequest(mediaType, s3Key, {
+                    ...options,
+                    metadata: {
+                        ...options?.metadata,
+                        correlationId,
+                    },
+                });
+            }
+            catch (error) {
+                // Clean up on submission failure
+                if (pendingRequest.timeoutId) {
+                    clearTimeout(pendingRequest.timeoutId);
+                }
+                this.pendingRequests.delete(correlationId);
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Generate a unique correlation ID for request tracking
+     *
+     * Uses UUID to ensure uniqueness even across process restarts,
+     * preventing any possibility of ID collision with orphaned responses.
+     */
+    generateCorrelationId() {
+        return `req-${(0, uuid_1.v4)()}`;
+    }
+    /**
+     * Submit a processing request
+     */
+    submitProcessingRequest(mediaType, s3Key, options) {
+        if (!this._isConnected || !this.channel) {
+            throw errors_1.RequestError.notConnected();
+        }
+        if (!s3Key || typeof s3Key !== 'string') {
+            throw errors_1.RequestError.invalidS3Key(s3Key, 'S3 key must be a non-empty string');
+        }
+        const mediaId = options?.mediaId || (0, uuid_1.v4)();
+        const userId = options?.userId || this.options.defaultUserId;
+        const mimeType = options?.mimeType || this.guessMimeType(s3Key, mediaType);
+        const originalFilename = options?.originalFilename || this.extractFilename(s3Key);
+        const message = {
+            messageType: 'request',
+            mediaType,
+            mediaId,
+            userId,
+            timestamp: new Date().toISOString(),
+            s3Key,
+            originalFilename,
+            mimeType,
+            fileSize: options?.fileSize || 0,
+            metadata: {
+                jobId: `job-${mediaId}`,
+                ...options?.metadata,
+            },
+        };
+        // Add video-specific options to metadata
+        if (mediaType === 'video' && options) {
+            const videoOptions = options;
+            if (videoOptions.targetQualities) {
+                message.metadata = {
+                    ...message.metadata,
+                    targetQualities: videoOptions.targetQualities,
+                };
+            }
+            if (videoOptions.thumbnailTimestamps) {
+                message.metadata = {
+                    ...message.metadata,
+                    thumbnailTimestamps: videoOptions.thumbnailTimestamps,
+                };
+            }
+        }
+        // Add zip-specific options to metadata
+        if (mediaType === 'zip' && options) {
+            const zipOptions = options;
+            message.metadata = {
+                ...message.metadata,
+                processImages: zipOptions.processImages ?? true,
+                processVideos: zipOptions.processVideos ?? true,
+            };
+        }
+        try {
+            const sent = this.channel.sendToQueue(this.requestQueue, Buffer.from(JSON.stringify(message)), { persistent: true });
+            if (!sent) {
+                throw errors_1.RequestError.queuePublishFailed(this.requestQueue);
+            }
+            return mediaId;
+        }
+        catch (error) {
+            if (error instanceof errors_1.RequestError) {
+                throw error;
+            }
+            throw errors_1.RequestError.queuePublishFailed(this.requestQueue, error);
+        }
+    }
+    /**
+     * Guess MIME type from file extension
+     */
+    guessMimeType(s3Key, mediaType) {
+        const ext = this.extractExtension(s3Key).toLowerCase();
+        if (ext && MIME_TYPES[ext]) {
+            return MIME_TYPES[ext];
+        }
+        // Fallback based on media type
+        switch (mediaType) {
+            case 'image':
+                return 'image/jpeg';
+            case 'video':
+                return 'video/mp4';
+            case 'zip':
+                return 'application/zip';
+            default:
+                return 'application/octet-stream';
+        }
+    }
+    /**
+     * Extract filename from S3 key
+     */
+    extractFilename(s3Key) {
+        const parts = s3Key.split('/');
+        return parts[parts.length - 1] || s3Key;
+    }
+    /**
+     * Extract file extension from S3 key
+     */
+    extractExtension(s3Key) {
+        const filename = this.extractFilename(s3Key);
+        const dotIndex = filename.lastIndexOf('.');
+        return dotIndex >= 0 ? filename.substring(dotIndex) : '';
+    }
+}
+exports.MediaProcessor = MediaProcessor;
+//# sourceMappingURL=MediaProcessor.js.map