eip-cloud-services 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.5] - 2026-03-02
+
+### Fixed
+- Hardened Redis error handling to avoid throwing from client error events, reducing process instability during transient disconnects.
+- Reworked pub/sub client usage to use shared publisher/subscriber clients instead of per-channel client fan-out.
+- Improved subscription lifecycle management by tracking channel handlers and unsubscribing only when no handlers remain.
+- Improved Redis client cleanup and stale-client recovery behavior.
+
 ## [1.1.0] - 2023-11-18
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-The EIP Cloud Services Module is a comprehensive Node.js package that provides seamless integration with various cloud services, including Redis, AWS S3, CDN, AWS Lambda, and MySQL. This module is designed to simplify the complexities of interacting with these cloud services, offering a range of functionalities from data caching and storage to content delivery and serverless computing.
+The EIP Cloud Services Module is a comprehensive Node.js package that provides seamless integration with various cloud services, including Redis, AWS S3, CDN, AWS Lambda, AWS SQS, and MySQL. This module is designed to simplify the complexities of interacting with these cloud services, offering a range of functionalities from data caching and storage to content delivery and serverless computing.
 
 ## Installation and Import
 
@@ -58,6 +58,10 @@ module.exports = {
         logs: "verbose", // "verbose" or "outputs", any other value will not log. verbose will log all activity. outputs will only log when there is a file updated.
         logsFunction: ( message ) => { ... } // Optional, if nothing is provided console.log will be used.
     },
+    sqs: {
+        region: 'eu-west-1',
+        endpoint: 'http://localhost:4566' // Optional (e.g. localstack)
+    },
     mysql: {
         connectionLimit: 10, // Max connections
         host: 'my-database.domain.com',
@@ -76,6 +80,7 @@ module.exports = {
 3. [CDN Module](#cdn-module)
 4. [MySQL Module](#mysql-module)
 5. [AWS Lambda Module](#aws-lambda-module)
+6. [AWS SQS Module](#aws-sqs-module)
 
 # AWS Lambda Module
 
@@ -131,6 +136,30 @@ The module includes error handling to manage issues related to Lambda invocation
 
 Logging is provided to track the start and completion of Lambda invocations, aiding in debugging and monitoring.
 
+# AWS SQS Module
+
+## Overview
+
+This module provides helpers for sending, receiving, and deleting messages in AWS SQS queues.
+
+## Usage
+
+```javascript
+const sqs = require('eip-cloud-services').sqs;
+
+const queueUrl = await sqs.getQueueUrl('my-queue');
+await sqs.sendMessage(queueUrl, { type: 'example', payload: 'hello' });
+
+const messages = await sqs.receiveMessages(queueUrl, { maxMessages: 5, waitTimeSeconds: 10 });
+if (messages.length > 0) {
+    await sqs.deleteMessages(queueUrl, messages);
+}
+```
+
+## Configuration
+
+Set `sqs.region` and optionally `sqs.endpoint` in your config. The module defaults to `eu-west-1` and uses the AWS SDK credential chain.
+
 # MySQL Module
 
 ## Overview

package/index.js

@@ -3,5 +3,6 @@ exports.redis = require ( './src/redis' );
 exports.s3 = require ( './src/s3' );
 exports.cdn = require ( './src/cdn' );
 exports.lambda = require ( './src/lambda' );
+exports.sqs = require ( './src/sqs' );
 exports.mysql = require ( './src/mysql' );
-exports.mysql8 = require ( './src/mysql8' );
+exports.mysql8 = require ( './src/mysql8' );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eip-cloud-services",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Houses a collection of helpers for connecting with Cloud services.",
   "main": "index.js",
   "scripts": {
@@ -17,6 +17,7 @@
     "@aws-sdk/client-cloudfront": "^3.354.0",
     "@aws-sdk/client-lambda": "^3.356.0",
     "@aws-sdk/client-s3": "^3.354.0",
+    "@aws-sdk/client-sqs": "^3.356.0",
     "@aws-sdk/client-secrets-manager": "^3.354.0",
     "config": "^3.3.9",
     "google-auth-library": "^8.8.0",

package/src/redis.js

@@ -8,6 +8,45 @@ if ( fs.existsSync ( configDirPath ) && fs.statSync ( configDirPath ).isDirector
 }
 
 const clients = {};
+const subscriptionHandlers = new Map ();
+let mainSubListenerAttached = false;
+const lastConnectionErrorByClient = new Map ();
+const CONNECTION_ERROR_LOG_WINDOW_MS = 30000;
+
+const logConnectionError = ( clientId, error ) => {
+    const now = Date.now ();
+    const last = lastConnectionErrorByClient.get ( clientId ) || 0;
+    if ( now - last < CONNECTION_ERROR_LOG_WINDOW_MS ) {
+        return;
+    }
+    lastConnectionErrorByClient.set ( clientId, now );
+    console.error ( '\x1b[33mREDIS CONNECTION FAILED: Redis connection failed. If you\'re running locally, is a redis server actually active? Also, check your connection configuration.\x1b[0m', {
+        clientId,
+        error: error?.message || error
+    } );
+};
+
+const attachMainSubscriberListener = ( client ) => {
+    if ( mainSubListenerAttached ) {
+        return;
+    }
+    client.on ( 'message', ( receivedChannel, message ) => {
+        const handlers = subscriptionHandlers.get ( receivedChannel );
+        if ( !handlers || handlers.size === 0 ) {
+            return;
+        }
+        handlers.forEach ( handler => {
+            try {
+                handler ( message );
+            }
+            catch ( error ) {
+                console.error ( 'REDIS LIB ERROR [subscribe handler]', error );
+            }
+        } );
+    } );
+    mainSubListenerAttached = true;
+};
+
 const applyPrefix = (value) => {
     const prefix = config?.redis?.prefix;
     if (!prefix || typeof value !== 'string') return value;
@@ -32,6 +71,20 @@ const applyPrefix = (value) => {
  */
 const getClient = async ( clientId = 'main' ) => {
     try {
+        if ( clients[ clientId ] ) {
+            const status = clients[ clientId ].status;
+            if ( status === 'end' || status === 'close' ) {
+                try {
+                    clients[ clientId ].disconnect ();
+                }
+                catch ( _err ) {}
+                delete clients[ clientId ];
+                if ( clientId === 'main_sub' ) {
+                    mainSubListenerAttached = false;
+                }
+            }
+        }
+
         if ( !clients[ clientId ] ) {
             let redisClient;
 
@@ -52,8 +105,8 @@ const getClient = async ( clientId = 'main' ) => {
                     redisClient.once ( 'error', reject );
                 } );
 
-                redisClient.on ( 'node error', err => {
-                    console.error ( 'Redis cluster node error', err );
+                redisClient.on ( 'node error', error => {
+                    logConnectionError ( clientId, error );
                 } );
             }
             else if ( config?.redis?.clusterEnabled && ( !Array.isArray ( config.redis.cluster ) || config.redis.cluster.length === 0 ) ) {
@@ -66,8 +119,7 @@ const getClient = async ( clientId = 'main' ) => {
                 } );
 
                 redisClient.on ( 'error', error => {
-                    console.error ( '\x1b[33mREDIS CONNECTION FAILED: Redis connection failed. If you\'re running locally, is a redis server actually active? Also, check your connection configuration.\x1b[0m' );
-                    throw error;
+                    logConnectionError ( clientId, error );
                 } );
 
                 await new Promise ( ( resolve, reject ) => {
@@ -77,6 +129,14 @@ const getClient = async ( clientId = 'main' ) => {
             }
 
             clients[ clientId ] = redisClient;
+
+            if ( clientId === 'main_sub' ) {
+                attachMainSubscriberListener ( redisClient );
+                const channels = [ ...subscriptionHandlers.keys () ];
+                if ( channels.length > 0 ) {
+                    await redisClient.subscribe ( ...channels );
+                }
+            }
         }
 
         return clients[ clientId ];
@@ -88,8 +148,19 @@ const getClient = async ( clientId = 'main' ) => {
 
 const deleteClient = async ( clientId ) => {
     if ( clients[ clientId ] ){
-        await clients[ clientId ].quit ();
+        try {
+            await clients[ clientId ].quit ();
+        }
+        catch ( _err ) {
+            try {
+                clients[ clientId ].disconnect ();
+            }
+            catch ( __err ) {}
+        }
         delete clients[ clientId ];
+        if ( clientId === 'main_sub' ) {
+            mainSubListenerAttached = false;
+        }
     }
 };
 
@@ -731,7 +802,7 @@ exports.publish = async ( channel, message ) => {
     try {
         if ( typeof channel === 'string' && typeof message === 'string' ) {
             const fullChannel = applyPrefix ( channel );
-            const client = await getClient ( `${fullChannel}_pub` );
+            const client = await exports.getPubClient ();
 
             return client.publish ( fullChannel, message );
         }
@@ -756,16 +827,21 @@ exports.subscribe = async ( channel, messageHandler ) => {
     try {
         if ( typeof channel === 'string' && typeof messageHandler === 'function' ) {
             const fullChannel = applyPrefix ( channel );
-            const client = await getClient ( `${fullChannel}_sub` );
+            const client = await exports.getSubClient ();
+            attachMainSubscriberListener ( client );
 
-            client.on ( 'message', ( receivedChannel, message ) => {
-                if ( receivedChannel === fullChannel ) {
-                    messageHandler ( message );
+            if ( !subscriptionHandlers.has ( fullChannel ) ) {
+                subscriptionHandlers.set ( fullChannel, new Set () );
+                try {
+                    await client.subscribe ( fullChannel );
                 }
-            } );
+                catch ( error ) {
+                    subscriptionHandlers.delete ( fullChannel );
+                    throw error;
+                }
+            }
+            subscriptionHandlers.get ( fullChannel ).add ( messageHandler );
 
-            await client.subscribe ( fullChannel );
-        
             return;
         }
         else {
@@ -781,21 +857,32 @@ exports.subscribe = async ( channel, messageHandler ) => {
 /**
  * Unsubscribes from a channel.
  * @param {string} channel - The channel to unsubscribe from.
+ * @param {Function} [messageHandler] - Optional specific handler to unsubscribe.
  * @returns {Promise<void>} - A promise that resolves when the unsubscribe is complete.
  *
  * @description This method unsubscribes from the specified channel in Redis for incoming messages. 
  */
-exports.unsubscribe = async ( channel ) => {
+exports.unsubscribe = async ( channel, messageHandler ) => {
     try {
         if ( typeof channel === 'string' ) {
             const fullChannel = applyPrefix ( channel );
-            const client = await getClient ( `${fullChannel}_sub` );
-
-            client.removeAllListeners ( 'message' );
+            const handlers = subscriptionHandlers.get ( fullChannel );
+            if ( !handlers ) {
+                return;
+            }
 
-            await client.unsubscribe ( fullChannel );
-            await deleteClient ( `${fullChannel}_sub` );
+            if ( typeof messageHandler === 'function' ) {
+                handlers.delete ( messageHandler );
+            }
+            else {
+                handlers.clear ();
+            }
 
+            if ( handlers.size === 0 ) {
+                subscriptionHandlers.delete ( fullChannel );
+                const client = await exports.getSubClient ();
+                await client.unsubscribe ( fullChannel );
+            }
             return;
         }
         else {
@@ -833,5 +920,20 @@ exports.info = async () => {
  * @description This method closes the Redis connection using the 'quit' command, ensuring a graceful shutdown of the connection.
  */
 exports.kill = async () => {
-    await Promise.all ( Object.values ( clients ).map ( client => client.quit () ) );
+    await Promise.all (
+        Object.entries ( clients ).map ( async ( [ clientId, client ] ) => {
+            try {
+                await client.quit ();
+            }
+            catch ( _err ) {
+                try {
+                    client.disconnect ();
+                }
+                catch ( __err ) {}
+            }
+            delete clients[ clientId ];
+        } )
+    );
+    subscriptionHandlers.clear ();
+    mainSubListenerAttached = false;
 };

package/src/sqs.js

@@ -0,0 +1,116 @@
+const { SQSClient, SendMessageCommand, ReceiveMessageCommand, DeleteMessageCommand, DeleteMessageBatchCommand, GetQueueUrlCommand, GetQueueAttributesCommand } = require ( '@aws-sdk/client-sqs' );
+const fs = require ( 'fs' );
+let config = {};
+const configDirPath = `${ process.cwd ()}/config`;
+if ( fs.existsSync ( configDirPath ) && fs.statSync ( configDirPath ).isDirectory () ) {
+    config = require ( 'config' ); // require the config directory if it exists
+}
+
+const resolveClientConfig = () => {
+    const region = config?.sqs?.region || process.env.AWS_REGION || 'eu-west-1';
+    const endpoint = config?.sqs?.endpoint;
+    return endpoint ? { region, endpoint } : { region };
+};
+
+const client = new SQSClient ( resolveClientConfig () );
+
+/**
+ * Resolve a queue URL by name.
+ *
+ * @param {string} queueName - The name of the queue.
+ * @returns {Promise<string>} The queue URL.
+ */
+exports.getQueueUrl = async ( queueName ) => {
+    const command = new GetQueueUrlCommand ( { QueueName: queueName } );
+    const response = await client.send ( command );
+    return response.QueueUrl;
+};
+
+/**
+ * Fetch queue attributes.
+ *
+ * @param {string} queueUrl - The queue URL.
+ * @param {string[]} [attributeNames=['All']] - Attribute names to fetch.
+ * @returns {Promise<Record<string, string>>} Attributes map.
+ */
+exports.getQueueAttributes = async ( queueUrl, attributeNames = [ 'All' ] ) => {
+    const command = new GetQueueAttributesCommand ( {
+        QueueUrl: queueUrl,
+        AttributeNames: attributeNames
+    } );
+    const response = await client.send ( command );
+    return response.Attributes || {};
+};
+
+/**
+ * Send a message to an SQS queue.
+ *
+ * @param {string} queueUrl - The queue URL.
+ * @param {string|object} messageBody - The message payload.
+ * @param {object} [options={}] - Additional SQS message options.
+ * @returns {Promise<object>} Send response.
+ */
+exports.sendMessage = async ( queueUrl, messageBody, options = {} ) => {
+    const body = typeof messageBody === 'string' ? messageBody : JSON.stringify ( messageBody );
+    const command = new SendMessageCommand ( {
+        QueueUrl: queueUrl,
+        MessageBody: body,
+        ...options
+    } );
+    return client.send ( command );
+};
+
+/**
+ * Receive messages from an SQS queue.
+ *
+ * @param {string} queueUrl - The queue URL.
+ * @param {object} [options={}] - Receive options.
+ * @returns {Promise<object[]>} Array of messages.
+ */
+exports.receiveMessages = async ( queueUrl, options = {} ) => {
+    const command = new ReceiveMessageCommand ( {
+        QueueUrl: queueUrl,
+        MaxNumberOfMessages: options.maxMessages || options.MaxNumberOfMessages || 1,
+        WaitTimeSeconds: options.waitTimeSeconds || options.WaitTimeSeconds || 10,
+        VisibilityTimeout: options.visibilityTimeout || options.VisibilityTimeout,
+        MessageAttributeNames: options.MessageAttributeNames || [ 'All' ],
+        AttributeNames: options.AttributeNames || [ 'All' ]
+    } );
+    const response = await client.send ( command );
+    return response.Messages || [];
+};
+
+/**
+ * Delete a single message from an SQS queue.
+ *
+ * @param {string} queueUrl - The queue URL.
+ * @param {string} receiptHandle - The receipt handle of the message.
+ * @returns {Promise<object>} Delete response.
+ */
+exports.deleteMessage = async ( queueUrl, receiptHandle ) => {
+    const command = new DeleteMessageCommand ( {
+        QueueUrl: queueUrl,
+        ReceiptHandle: receiptHandle
+    } );
+    return client.send ( command );
+};
+
+/**
+ * Delete multiple messages from an SQS queue.
+ *
+ * @param {string} queueUrl - The queue URL.
+ * @param {Array<{receiptHandle?: string, ReceiptHandle?: string}>} messages - Messages or receipt handles.
+ * @returns {Promise<object>} Batch delete response.
+ */
+exports.deleteMessages = async ( queueUrl, messages ) => {
+    const entries = ( messages || [] ).map ( ( msg, index ) => ( {
+        Id: String ( index ),
+        ReceiptHandle: msg?.ReceiptHandle || msg?.receiptHandle || msg
+    } ) );
+    if ( entries.length === 0 ) return { Successful: [], Failed: [] };
+    const command = new DeleteMessageBatchCommand ( {
+        QueueUrl: queueUrl,
+        Entries: entries
+    } );
+    return client.send ( command );
+};