node-red-context-s3 0.0.1

package/README.md

@@ -0,0 +1,118 @@
+# Node-RED S3 Context Storage
+
+A Node-RED context storage implementation that uses AWS S3 as the backend storage for persistent context data.
+
+## Overview
+
+This module provides a context storage implementation for Node-RED that stores context data in AWS S3 buckets. It implements the Node-RED context API and allows you to persist context data across Node-RED restarts using Amazon S3 as the storage backend.
+
+## Features
+
+- **Persistent Storage**: Context data is stored in AWS S3, ensuring data persistence
+- **Scope Support**: Supports different context scopes (global, flow, node)
+- **JSON Storage**: Data is stored as JSON objects in S3
+- **AWS SDK Integration**: Uses the official AWS SDK for JavaScript v3
+- **Error Handling**: Proper error handling for S3 operations
+
+## Installation
+
+```bash
+npm install node-red-context-s3
+```
+
+## Configuration
+
+To use this context storage in your Node-RED application, add the following to your `settings.js` file:
+
+```javascript
+module.exports = {
+    // ... other settings ...
+    
+    contextStorage: {
+        s3: {
+            module: "node-red-context-s3",
+            config: {
+                bucket: "your-s3-bucket-name",
+                prefix: "node-red", // optional prefix for S3 keys
+                flushInterval: 5,    // optional flush interval in seconds
+                // AWS credentials configuration
+                region: "us-east-1",
+                credentials: {
+                    accessKeyId: "your-access-key",
+                    secretAccessKey: "your-secret-key"
+                }
+            }
+        }
+    },
+    
+    // Set S3 as the default context storage
+    defaultContextStorage: "s3"
+};
+```
+
+### AWS Credentials
+
+The module uses the AWS SDK for JavaScript v3. You can provide credentials in several ways:
+
+1. **Direct configuration** (as shown above)
+2. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+3. **AWS credentials file**: `~/.aws/credentials`
+4. **IAM roles** (when running on EC2 or ECS)
+
+## API Methods
+
+This module implements the standard Node-RED context API:
+
+### `get(scope, keys, callback)`
+Retrieves context values for the specified scope and keys.
+
+### `set(scope, keys, values, callback)`
+Sets context values for the specified scope and keys.
+
+### `keys(scope, callback)`
+Returns all keys available in the specified scope.
+
+### `delete(scope)`
+Deletes all context data for the specified scope.
+
+### `clean(scopes)`
+Cleans context data for multiple scopes.
+
+## S3 Storage Structure
+
+Context data is stored in S3 with the following key structure:
+
+```
+{prefix}/context/{scope}.json
+```
+
+Example:
+- `node-red/context/global.json`
+- `node-red/context/flow:abc123.json`
+- `node-red/context/node:xyz789.json`
+
+Each scope is stored as a separate JSON object in the S3 bucket.
+
+## Testing
+
+To run the tests:
+
+```bash
+npm test
+```
+
+Make sure to set up your AWS credentials and configure a test S3 bucket before running tests.
+
+## Dependencies
+
+- `@aws-sdk/client-s3`: AWS SDK for S3 operations
+- `jest`: Testing framework
+- `dotenv`: Environment variable management for tests
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.

package/context.js

@@ -0,0 +1,152 @@
+const S3 = require("@aws-sdk/client-s3").S3;
+
+function Context(settings) {
+    this.settings = Object.assign({
+        bucket: '',
+        prefix: '',
+        flushInterval: 5,
+    }, settings);
+    
+    if (!this.settings.bucket) {
+        throw new Error('S3 bucket name is required');
+    }
+    
+    this.client = new S3(this.settings);
+    this.data = {};
+    this.cache = new Map(); // Use Map for better performance with string keys
+}
+
+Context.prototype.open = async function () {
+    // Implementation can be added later if needed
+}
+
+Context.prototype.close = async function () {
+    // Implementation can be added later if needed
+}
+
+Context.prototype.get = async function (scope, keys, callback) {
+    if (typeof callback !== 'function') {
+        callback = () => {};
+    }
+    
+    try {
+        if (!this.cache.has(scope)) {
+            try {
+                const object = await this.client.getObject({
+                    Bucket: this.settings.bucket,
+                    Key: `${this.settings.prefix}/context/${scope}.json`,
+                });
+                this.data[scope] = JSON.parse(await object.Body.transformToString()) || {};
+                this.cache.set(scope, true);
+            } catch (error) {
+                if (error.name && error.name.indexOf('NoSuch') === 0) {
+                    console.warn(`Scope ${scope} not found in S3:`, error.message);
+                    this.data[scope] = {};
+                    this.cache.set(scope, true);
+                } else {
+                    throw error;
+                }
+            }
+        }
+        
+        const keysArray = Array.isArray(keys) ? keys : [keys];
+        const values = keysArray.map(key => this.data[scope][key]);
+        
+        callback(null, ...values);
+    } catch (error) {
+        callback(error);
+    }
+}
+
+Context.prototype.set = async function (scope, keys, values, callback) {
+    if (typeof callback !== 'function') {
+        callback = () => {};
+    }
+    
+    try {
+        if (!this.data[scope] || typeof this.data[scope] !== 'object') {
+            this.data[scope] = {};
+        }
+        
+        const keysArray = Array.isArray(keys) ? keys : [keys];
+        const valuesArray = Array.isArray(values) ? values : [values];
+        
+        if (keysArray.length !== valuesArray.length) {
+            throw new Error('Keys and values arrays must have the same length');
+        }
+        
+        for (let i = 0; i < keysArray.length; i++) {
+            this.data[scope][keysArray[i]] = valuesArray[i];
+        }
+        
+        await this.client.putObject({
+            Bucket: this.settings.bucket,
+            Key: `${this.settings.prefix}/context/${scope}.json`,
+            Body: JSON.stringify(this.data[scope]),
+            ContentType: 'application/json',
+        });
+        
+        // Invalidate cache after successful write
+        this.cache.delete(scope);
+        
+        callback(null);
+    } catch (error) {
+        callback(error);
+    }
+}
+
+Context.prototype.keys = async function (scope, callback) {
+    if (typeof callback !== 'function') {
+        callback = () => {};
+    }
+    
+    try {
+        if (!this.cache.has(scope)) {
+            await this.get(scope, []);
+        }
+        
+        const keys = Object.keys(this.data[scope] || {});
+        callback(null, keys);
+    } catch (error) {
+        callback(error);
+    }
+}
+
+Context.prototype.delete = async function (scope) {
+    try {
+        await this.client.deleteObject({
+            Bucket: this.settings.bucket,
+            Key: `${this.settings.prefix}/context/${scope}.json`,
+        });
+        
+        // Clean up local cache
+        delete this.data[scope];
+        this.cache.delete(scope);
+    } catch (error) {
+        if (error.name && error.name.indexOf('NoSuch') === 0) {
+            console.warn(`Scope ${scope} not found during deletion:`, error.message);
+        } else {
+            throw error;
+        }
+    }
+}
+
+Context.prototype.clean = async function (scopes) {
+    if (!Array.isArray(scopes)) {
+        scopes = [scopes];
+    }
+    
+    for (const scope of scopes) {
+        await this.delete(scope);
+    }
+}
+
+// Add a method to clear all cached data
+Context.prototype.clearCache = function () {
+    this.data = {};
+    this.cache.clear();
+};
+
+module.exports = function (settings) {
+    return new Context(settings);
+};

package/context.test.js

@@ -0,0 +1,159 @@
+require('dotenv').config();
+const context = require('./context');
+
+// Mock AWS S3 client
+jest.mock('@aws-sdk/client-s3', () => {
+    return {
+        S3: jest.fn().mockImplementation(() => ({
+            getObject: jest.fn(),
+            putObject: jest.fn(),
+            deleteObject: jest.fn(),
+        })),
+    };
+});
+
+const { S3 } = require('@aws-sdk/client-s3');
+
+describe('S3 Context Storage', () => {
+    let s3Context;
+    let mockS3Client;
+    
+    beforeEach(() => {
+        mockS3Client = {
+            getObject: jest.fn(),
+            putObject: jest.fn(),
+            deleteObject: jest.fn(),
+        };
+        S3.mockImplementation(() => mockS3Client);
+        
+        s3Context = context({
+            bucket: 'test-bucket',
+            prefix: 'test-prefix',
+            flushInterval: 5,
+        });
+    });
+    
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    
+    test('should throw error when bucket name is not provided', () => {
+        expect(() => context({})).toThrow('S3 bucket name is required');
+    });
+    
+    test('should initialize with default settings', () => {
+        const ctx = context({ bucket: 'test-bucket' });
+        expect(ctx.settings.bucket).toBe('test-bucket');
+        expect(ctx.settings.prefix).toBe('');
+        expect(ctx.settings.flushInterval).toBe(5);
+    });
+    
+    test('should get values from scope', async () => {
+        const mockData = { key1: 'value1', key2: 'value2' };
+        mockS3Client.getObject.mockResolvedValue({
+            Body: {
+                transformToString: jest.fn().mockResolvedValue(JSON.stringify(mockData)),
+            },
+        });
+        
+        const callback = jest.fn();
+        await s3Context.get('test-scope', ['key1', 'key2'], callback);
+        
+        expect(callback).toHaveBeenCalledWith(null, 'value1', 'value2');
+        expect(mockS3Client.getObject).toHaveBeenCalledWith({
+            Bucket: 'test-bucket',
+            Key: 'test-prefix/context/test-scope.json',
+        });
+    });
+    
+    test('should handle missing scope gracefully', async () => {
+        const error = new Error('NoSuchKey');
+        error.name = 'NoSuchKey';
+        mockS3Client.getObject.mockRejectedValue(error);
+        
+        const callback = jest.fn();
+        await s3Context.get('non-existent-scope', ['key1'], callback);
+        
+        expect(callback).toHaveBeenCalledWith(null, undefined);
+    });
+    
+    test('should set values to scope', async () => {
+        const callback = jest.fn();
+        await s3Context.set('test-scope', 'key1', 'value1', callback);
+        
+        expect(callback).toHaveBeenCalledWith(null);
+        expect(mockS3Client.putObject).toHaveBeenCalledWith({
+            Bucket: 'test-bucket',
+            Key: 'test-prefix/context/test-scope.json',
+            Body: JSON.stringify({ key1: 'value1' }),
+            ContentType: 'application/json',
+        });
+    });
+    
+    test('should handle array keys and values', async () => {
+        const callback = jest.fn();
+        await s3Context.set('test-scope', ['key1', 'key2'], ['value1', 'value2'], callback);
+        
+        expect(callback).toHaveBeenCalledWith(null);
+        expect(mockS3Client.putObject).toHaveBeenCalledWith({
+            Bucket: 'test-bucket',
+            Key: 'test-prefix/context/test-scope.json',
+            Body: JSON.stringify({ key1: 'value1', key2: 'value2' }),
+            ContentType: 'application/json',
+        });
+    });
+    
+    test('should validate keys and values array length', async () => {
+        const callback = jest.fn();
+        await expect(
+            s3Context.set('test-scope', ['key1', 'key2'], ['value1'], callback)
+        ).rejects.toThrow('Keys and values arrays must have the same length');
+    });
+    
+    test('should list keys from scope', async () => {
+        const mockData = { key1: 'value1', key2: 'value2' };
+        mockS3Client.getObject.mockResolvedValue({
+            Body: {
+                transformToString: jest.fn().mockResolvedValue(JSON.stringify(mockData)),
+            },
+        });
+        
+        const callback = jest.fn();
+        await s3Context.keys('test-scope', callback);
+        
+        expect(callback).toHaveBeenCalledWith(null, ['key1', 'key2']);
+    });
+    
+    test('should delete scope', async () => {
+        await s3Context.delete('test-scope');
+        
+        expect(mockS3Client.deleteObject).toHaveBeenCalledWith({
+            Bucket: 'test-bucket',
+            Key: 'test-prefix/context/test-scope.json',
+        });
+    });
+    
+    test('should handle deletion of non-existent scope', async () => {
+        const error = new Error('NoSuchKey');
+        error.name = 'NoSuchKey';
+        mockS3Client.deleteObject.mockRejectedValue(error);
+        
+        await expect(s3Context.delete('non-existent-scope')).resolves.not.toThrow();
+    });
+    
+    test('should clean multiple scopes', async () => {
+        await s3Context.clean(['scope1', 'scope2']);
+        
+        expect(mockS3Client.deleteObject).toHaveBeenCalledTimes(2);
+    });
+    
+    test('should clear cache', () => {
+        s3Context.data = { scope1: { key: 'value' } };
+        s3Context.cache.set('scope1', true);
+        
+        s3Context.clearCache();
+        
+        expect(s3Context.data).toEqual({});
+        expect(s3Context.cache.size).toBe(0);
+    });
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "node-red-context-s3",
+  "license": "MIT",
+  "main": "context.js",
+  "scripts": {
+    "test": "jest ./ --runInBand --forceExit --colors --verbose=false --silent=false"
+  },
+  "version": "0.0.1",
+  "author": {
+    "name": "eslizn",
+    "email": "eslizn@gmail.com"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.987.0"
+  },
+  "deprecated": false,
+  "description": "implementation of the node-red context API for S3 Protocol",
+  "keywords": [
+    "node-red",
+    "context",
+    "s3"
+  ],
+  "devDependencies": {
+    "dotenv": "^17.2.4",
+    "jest": "^30.2.0"
+  }
+}