@falkordb/mcpserver 1.1.0 → 1.2.0

package/.env.example

@@ -10,17 +10,15 @@ MCP_TRANSPORT=stdio
 # MCP_API_KEY=
 
 # FalkorDB Configuration
+# When using Docker Compose, set FALKORDB_HOST=falkordb (the service name)
 FALKORDB_HOST=localhost
 FALKORDB_PORT=6379
 FALKORDB_USERNAME=
 FALKORDB_PASSWORD=
 # Set to 'true' to use read-only queries by default (useful for replica instances)
 FALKORDB_DEFAULT_READONLY=false
-
-# Redis Configuration (for key-value operations)
-REDIS_URL=redis://localhost:6379
-REDIS_USERNAME=
-REDIS_PASSWORD=
+# Set to 'true' to enforce strict read-only mode - blocks all write operations (queries, graph deletions, key modifications)
+FALKORDB_STRICT_READONLY=false
 
 # Logging Configuration (optional)
 ENABLE_FILE_LOGGING=false

package/README.md

@@ -17,7 +17,6 @@ FalkorDB MCP Server enables AI assistants like Claude to interact with FalkorDB
 This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing AI models to:
 - **Query graph databases** using OpenCypher (with read-only mode support)
 - **Create and manage** nodes and relationships
-- **Store and retrieve** key-value data
 - **List and explore** multiple graphs
 - **Delete graphs** when needed
 - **Read-only queries** for replica instances or to prevent accidental writes
@@ -54,6 +53,53 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
+### Running with npx
+
+You can run the server directly from the command line using npx:
+
+**Using inline environment variables:**
+
+```bash
+# Run with stdio transport (default)
+FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver
+
+# Run with HTTP transport
+MCP_TRANSPORT=http MCP_PORT=3005 FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver
+```
+
+**Using a .env file:**
+
+```bash
+# Using dotenv-cli to load environment variables from .env
+npx dotenv-cli -e .env -- npx @falkordb/mcpserver
+```
+
+This is useful for:
+- Quick testing and development
+- Running the server standalone without Claude Desktop
+- Custom integrations and scripting
+
+### Docker Compose
+
+Run FalkorDB and the MCP server together:
+
+```bash
+cp .env.example .env   # create env file; edit to set MCP_API_KEY, FALKORDB_PASSWORD, etc.
+docker compose up -d
+```
+
+> **Note:** Skipping the `.env` file leaves variables like `MCP_API_KEY` and `FALKORDB_PASSWORD` empty, which disables API key authentication and uses no database password.
+
+This starts FalkorDB with health checks and persistent volumes, plus the MCP server pre-configured to connect to it.
+
+The MCP server runs in **HTTP transport** mode and is exposed on `localhost:3000` by default. To connect a client, configure it to use:
+
+- **Transport:** `http`
+- **URL:** `http://localhost:3000`
+- **API Key:** Set via the `MCP_API_KEY` environment variable (optional)
+
+See `docker-compose.yml` for the exact port and configuration values.
+
 ### Installation
 
 1. **Clone and install:**
@@ -72,19 +118,14 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
    ```env
    # Environment Configuration
    NODE_ENV=development
-   
+
    # FalkorDB Configuration
    FALKORDB_HOST=localhost
    FALKORDB_PORT=6379
    FALKORDB_USERNAME=    # Optional
    FALKORDB_PASSWORD=    # Optional
    FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode (useful for replicas)
-   
-   # Redis Configuration (for key-value operations)
-   REDIS_URL=redis://localhost:6379
-   REDIS_USERNAME=       # Optional
-   REDIS_PASSWORD=       # Optional
-   
+
    # Logging Configuration (optional)
    ENABLE_FILE_LOGGING=false
    ```
@@ -136,7 +177,6 @@ There's also a dedicated `query_graph_readonly` tool that always executes querie
 ```text
 "Create a new person named Alice who knows Bob"
 "Add a 'WORKS_AT' relationship between Alice and TechCorp"
-"Store my API key in the database"
 ```
 
 ### 📊 Explore Structure
@@ -195,7 +235,6 @@ src/
 ├── index.ts                   # MCP server entry point
 ├── services/                  # Core business logic
 │   ├── falkordb.service.ts   # FalkorDB operations
-│   ├── redis.service.ts      # Key-value operations
 │   └── logger.service.ts     # Logging and MCP notifications
 ├── mcp/                      # MCP protocol implementations
 │   ├── tools.ts             # MCP tool definitions
@@ -268,7 +307,25 @@ Requests without a valid key receive a `401 Unauthorized` response. Auth is only
 
 ### Using with Docker
 
-Build and run the MCP server in a Docker container (defaults to HTTP transport):
+**Using pre-built images from Docker Hub:**
+
+```bash
+# Use the latest stable release
+docker pull falkordb/mcpserver:latest
+docker run -p 3000:3000 \
+  -e FALKORDB_HOST=host.docker.internal \
+  -e FALKORDB_PORT=6379 \
+  -e MCP_API_KEY=your-secret-key \
+  falkordb/mcpserver:latest
+
+# Or use the edge version (latest main branch)
+docker pull falkordb/mcpserver:edge
+
+# Or pin to a specific version
+docker pull falkordb/mcpserver:1.0.0
+```
+
+**Building locally:**
 
 ```bash
 docker build -t falkordb-mcpserver .
@@ -289,7 +346,7 @@ services:
       - "6379:6379"
 
   mcp-server:
-    build: .
+    image: falkordb/mcpserver:latest  # or use 'build: .' to build locally
     ports:
       - "3000:3000"
     environment:

package/dist/config/index.js

@@ -14,11 +14,7 @@ export const config = {
         username: process.env.FALKORDB_USERNAME || '',
         password: process.env.FALKORDB_PASSWORD || '',
         defaultReadOnly: process.env.FALKORDB_DEFAULT_READONLY === 'true',
-    },
-    redis: {
-        url: process.env.REDIS_URL || 'redis://localhost:6379',
-        username: process.env.REDIS_USERNAME || '',
-        password: process.env.REDIS_PASSWORD || '',
+        strictReadOnly: process.env.FALKORDB_STRICT_READONLY === 'true',
     },
     mcp: {
         transport: (process.env.MCP_TRANSPORT || 'stdio'),

package/dist/config/index.test.js

@@ -13,6 +13,8 @@ describe('Config', () => {
         expect(config.falkorDB).toHaveProperty('password');
         expect(config.falkorDB).toHaveProperty('defaultReadOnly');
         expect(typeof config.falkorDB.defaultReadOnly).toBe('boolean');
+        expect(config.falkorDB).toHaveProperty('strictReadOnly');
+        expect(typeof config.falkorDB.strictReadOnly).toBe('boolean');
     });
     test('should have MCP configuration', () => {
         expect(config).toHaveProperty('mcp');

package/dist/index.js

@@ -6,7 +6,6 @@ import { falkorDBService } from './services/falkordb.service.js';
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { redisService } from './services/redis.service.js';
 import { errorHandler } from './errors/ErrorHandler.js';
 import { logger } from './services/logger.service.js';
 import { config } from './config/index.js';
@@ -39,7 +38,6 @@ const gracefulShutdown = async (signal) => {
             });
         }
         await falkorDBService.close();
-        await redisService.close();
         await logger.info('All services closed successfully');
         process.exit(0);
     }
@@ -81,7 +79,6 @@ async function initializeServices() {
     await logger.info('Initializing FalkorDB MCP server...');
     try {
         await falkorDBService.initialize();
-        await redisService.initialize();
         await logger.info('All services initialized successfully');
     }
     catch (error) {

package/dist/mcp/tools.js

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import { falkorDBService } from '../services/falkordb.service.js';
-import { redisService } from '../services/redis.service.js';
 import { logger } from '../services/logger.service.js';
 import { AppError, CommonErrors } from '../errors/AppError.js';
 import { config } from '../config/index.js';
@@ -18,17 +17,6 @@ const deleteGraphSchema = {
     graphName: z.string().describe("The name of the graph to delete"),
     confirmDelete: z.literal(true).describe("Must be set to true to confirm deletion. This is a safety measure to prevent accidental data loss."),
 };
-const setKeySchema = {
-    key: z.string().describe("The key to set"),
-    value: z.string().describe("The value to set"),
-};
-const getKeySchema = {
-    key: z.string().describe("The key to get."),
-};
-const deleteKeySchema = {
-    key: z.string().describe("The key to delete"),
-    confirmDelete: z.literal(true).describe("Must be set to true to confirm deletion. This is a safety measure to prevent accidental data loss."),
-};
 function registerQueryGraphTool(server) {
     server.registerTool("query_graph", {
         title: "Query Graph",
@@ -46,6 +34,10 @@ function registerQueryGraphTool(server) {
             }
             // Use the provided readOnly flag, or fall back to the default from config
             const isReadOnly = readOnly !== undefined ? readOnly : config.falkorDB.defaultReadOnly;
+            // Enforce strict read-only mode if enabled
+            if (config.falkorDB.strictReadOnly && !isReadOnly) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Cannot execute write queries: server is in strict read-only mode (FALKORDB_STRICT_READONLY=true)', true);
+            }
             const result = await falkorDBService.executeQuery(graphName, query, undefined, isReadOnly);
             await logger.debug('Query tool executed successfully', { graphName, readOnly: isReadOnly });
             return {
@@ -125,6 +117,10 @@ function registerDeleteGraphTool(server) {
             if (!graphName?.trim()) {
                 throw new AppError(CommonErrors.INVALID_INPUT, 'Graph name is required and cannot be empty', true);
             }
+            // Enforce strict read-only mode if enabled
+            if (config.falkorDB.strictReadOnly) {
+                throw new AppError(CommonErrors.INVALID_INPUT, 'Cannot delete graphs: server is in strict read-only mode (FALKORDB_STRICT_READONLY=true)', true);
+            }
             await falkorDBService.deleteGraph(graphName);
             await logger.info('Delete graph tool executed successfully', { graphName });
             return {
@@ -140,119 +136,10 @@ function registerDeleteGraphTool(server) {
         }
     });
 }
-function registerListKeysTool(server) {
-    server.registerTool("list_keys", {
-        title: "List Keys",
-        description: "List all keys in Redis",
-        inputSchema: {},
-    }, async () => {
-        try {
-            const keys = await redisService.listKeys();
-            await logger.debug('List keys tool executed', { count: keys.length });
-            return {
-                content: [{
-                        type: "text",
-                        text: keys.join("\n"),
-                    }]
-            };
-        }
-        catch (error) {
-            await logger.error('List keys tool execution failed', error instanceof Error ? error : new Error(String(error)));
-            throw error;
-        }
-    });
-}
-function registerSetKeyTool(server) {
-    // Register set_key tool
-    server.registerTool("set_key", {
-        title: "Set Key",
-        description: "Set a key in Redis",
-        inputSchema: setKeySchema,
-    }, async (args) => {
-        const { key, value } = z.object(setKeySchema).parse(args);
-        try {
-            if (!key?.trim()) {
-                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
-            }
-            if (value === undefined || value === null) {
-                throw new AppError(CommonErrors.INVALID_INPUT, 'Value is required', true);
-            }
-            await redisService.set(key, value);
-            await logger.debug('Set key tool executed successfully', { key });
-            return {
-                content: [{
-                        type: "text",
-                        text: `Key ${key} set successfully`
-                    }]
-            };
-        }
-        catch (error) {
-            await logger.error('Set key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
-            throw error;
-        }
-    });
-}
-function registerGetKeyTool(server) {
-    // Register get_key tool
-    server.registerTool("get_key", {
-        title: "Get Key",
-        description: "Get a key from Redis",
-        inputSchema: getKeySchema,
-    }, async (args) => {
-        const { key } = z.object(getKeySchema).parse(args);
-        try {
-            if (!key?.trim()) {
-                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
-            }
-            const value = await redisService.get(key);
-            await logger.debug('Get key tool executed successfully', { key, hasValue: value !== null });
-            return {
-                content: [{
-                        type: "text",
-                        text: `Key ${key} is ${value ?? 'null (not found)'}`
-                    }]
-            };
-        }
-        catch (error) {
-            await logger.error('Get key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
-            throw error;
-        }
-    });
-}
-function registerDeleteKeyTool(server) {
-    server.registerTool("delete_key", {
-        title: "Delete Key",
-        description: "Permanently delete a key from Redis. WARNING: This action is irreversible. You must set confirmDelete to true to proceed.",
-        inputSchema: deleteKeySchema,
-    }, async (args) => {
-        const { key } = z.object(deleteKeySchema).parse(args);
-        try {
-            if (!key?.trim()) {
-                throw new AppError(CommonErrors.INVALID_INPUT, 'Key is required and cannot be empty', true);
-            }
-            await redisService.delete(key);
-            await logger.debug('Delete key tool executed successfully', { key });
-            return {
-                content: [{
-                        type: "text",
-                        text: `Key ${key} deleted`
-                    }]
-            };
-        }
-        catch (error) {
-            await logger.error('Delete key tool execution failed', error instanceof Error ? error : new Error(String(error)), { key });
-            throw error;
-        }
-    });
-}
 export default function registerAllTools(server) {
     // Register query_graph tools
     registerQueryGraphTool(server);
     registerQueryGraphReadOnlyTool(server);
     registerListGraphsTool(server);
     registerDeleteGraphTool(server);
-    registerSetKeyTool(server);
-    registerGetKeyTool(server);
-    registerDeleteKeyTool(server);
-    registerListKeysTool(server);
 }

package/dist/mcp/tools.test.js

@@ -0,0 +1,172 @@
+import { AppError, CommonErrors } from '../errors/AppError.js';
+// Mock the logger service
+jest.mock('../services/logger.service.js', () => ({
+    logger: {
+        info: jest.fn().mockResolvedValue(undefined),
+        warn: jest.fn().mockResolvedValue(undefined),
+        error: jest.fn().mockResolvedValue(undefined),
+        debug: jest.fn().mockResolvedValue(undefined),
+    }
+}));
+// Mock the FalkorDB service
+jest.mock('../services/falkordb.service.js', () => ({
+    falkorDBService: {
+        executeQuery: jest.fn(),
+        executeReadOnlyQuery: jest.fn(),
+        listGraphs: jest.fn(),
+        deleteGraph: jest.fn(),
+    }
+}));
+// Mock config with different scenarios
+let mockConfig = {
+    falkorDB: {
+        defaultReadOnly: false,
+        strictReadOnly: false,
+    }
+};
+jest.mock('../config/index.js', () => ({
+    get config() {
+        return mockConfig;
+    }
+}));
+// Import after mocks are set up
+import registerAllTools from './tools.js';
+import { falkorDBService } from '../services/falkordb.service.js';
+describe('MCP Tools - Strict Read-Only Mode', () => {
+    let server;
+    let queryGraphHandler;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Reset mock config
+        mockConfig = {
+            falkorDB: {
+                defaultReadOnly: false,
+                strictReadOnly: false,
+            }
+        };
+        // Create a minimal mock server that captures tool handlers
+        server = {
+            registerTool: jest.fn((name, schema, handler) => {
+                if (name === 'query_graph') {
+                    queryGraphHandler = handler;
+                }
+            }),
+        };
+        registerAllTools(server);
+    });
+    describe('query_graph tool with strictReadOnly=false', () => {
+        beforeEach(() => {
+            mockConfig.falkorDB.strictReadOnly = false;
+            mockConfig.falkorDB.defaultReadOnly = false;
+        });
+        it('should allow readOnly=false when strictReadOnly is disabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'CREATE (n:Test) RETURN n', undefined, false);
+        });
+        it('should allow readOnly=true when strictReadOnly is disabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+                readOnly: true,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should use default when readOnly is not specified', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, false);
+        });
+    });
+    describe('query_graph tool with strictReadOnly=true', () => {
+        beforeEach(() => {
+            mockConfig.falkorDB.strictReadOnly = true;
+            mockConfig.falkorDB.defaultReadOnly = true;
+        });
+        it('should reject readOnly=false when strictReadOnly is enabled', async () => {
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            })).rejects.toThrow(AppError);
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+                readOnly: false,
+            })).rejects.toThrow('strict read-only mode');
+            expect(falkorDBService.executeQuery).not.toHaveBeenCalled();
+        });
+        it('should allow readOnly=true when strictReadOnly is enabled', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+                readOnly: true,
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should use defaultReadOnly when readOnly is not specified in strict mode', async () => {
+            const mockResult = { records: [] };
+            falkorDBService.executeQuery.mockResolvedValue(mockResult);
+            await queryGraphHandler({
+                graphName: 'test',
+                query: 'MATCH (n) RETURN n',
+            });
+            expect(falkorDBService.executeQuery).toHaveBeenCalledWith('test', 'MATCH (n) RETURN n', undefined, true);
+        });
+        it('should include proper error information when rejecting write queries', async () => {
+            try {
+                await queryGraphHandler({
+                    graphName: 'test',
+                    query: 'CREATE (n:Test) RETURN n',
+                    readOnly: false,
+                });
+                fail('Expected error to be thrown');
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(AppError);
+                expect(error.name).toBe(CommonErrors.INVALID_INPUT);
+                expect(error.message).toContain('FALKORDB_STRICT_READONLY=true');
+            }
+        });
+        it('should reject write queries when strictReadOnly is enabled and defaultReadOnly=false and readOnly is not specified', async () => {
+            // Override defaultReadOnly for this specific test case
+            mockConfig.falkorDB.defaultReadOnly = false;
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+            })).rejects.toThrow(AppError);
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: 'CREATE (n:Test) RETURN n',
+            })).rejects.toThrow('strict read-only mode');
+            expect(falkorDBService.executeQuery).not.toHaveBeenCalled();
+        });
+    });
+    describe('query_graph tool input validation', () => {
+        it('should reject empty graph name', async () => {
+            await expect(queryGraphHandler({
+                graphName: '',
+                query: 'MATCH (n) RETURN n',
+            })).rejects.toThrow('Graph name is required and cannot be empty');
+        });
+        it('should reject empty query', async () => {
+            await expect(queryGraphHandler({
+                graphName: 'test',
+                query: '',
+            })).rejects.toThrow('Query is required and cannot be empty');
+        });
+    });
+});

package/dist/services/falkordb.service.js

@@ -41,8 +41,8 @@ class FalkorDBService {
                         host: config.falkorDB.host,
                         port: config.falkorDB.port,
                     },
-                    password: config.falkorDB.password,
-                    username: config.falkorDB.username,
+                    ...(config.falkorDB.username && { username: config.falkorDB.username }),
+                    ...(config.falkorDB.password && { password: config.falkorDB.password }),
                 });
                 // Test connection
                 const connection = await this.client.connection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkordb/mcpserver",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Model Context Protocol server for FalkorDB graph databases - enables AI assistants to query and manage graph data using natural language",
   "main": "dist/index.js",
   "type": "module",
@@ -32,7 +32,6 @@
     "claude",
     "opencypher",
     "cypher",
-    "redis",
     "graph",
     "database",
     "typescript",
@@ -65,15 +64,14 @@
     "test:ci": "jest --coverage --ci --watchAll=false",
     "inspect": "npm run build && npx -y @modelcontextprotocol/inspector node $PWD/dist/index.js",
     "clean": "rm -rf dist coverage",
-    "prepublish": "npm run test:ci && npm run lint && npm run build",
     "prepublishOnly": "npm run clean && npm run test:ci && npm run lint && npm run build"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",
-    "eslint": "^9.31.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
     "jest": "^30.0.5",
     "nodemon": "^3.1.10",
     "ts-jest": "^29.4.0",
@@ -85,13 +83,16 @@
     "dotenv": "^17.2.1",
     "falkordb": "^6.3.0",
     "platformdirs": "^4.3.8-rc3",
-    "redis": "^4.0.0",
     "zod": "^3.23.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "overrides": {
+    "minimatch": "^10.2.1",
+    "test-exclude": "^7.0.2"
+  },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/SecKatie"

package/dist/services/redis.service.js

@@ -1,179 +0,0 @@
-import { createClient } from 'redis';
-import { config } from '../config/index.js';
-import { AppError, CommonErrors } from '../errors/AppError.js';
-import { logger } from './logger.service.js';
-class RedisService {
-    client = null;
-    maxRetries = 5;
-    retryCount = 0;
-    initializingPromise = null;
-    constructor() {
-        // Don't initialize in constructor - use explicit initialization
-    }
-    sanitizeUrl(url) {
-        try {
-            const parsed = new URL(url);
-            if (parsed.username || parsed.password) {
-                parsed.username = parsed.username ? '***' : '';
-                parsed.password = parsed.password ? '***' : '';
-            }
-            return parsed.toString();
-        }
-        catch {
-            return '<invalid-url>';
-        }
-    }
-    async initialize() {
-        // Idempotency guard: don't overwrite an already-connected client
-        if (this.client) {
-            return;
-        }
-        if (this.initializingPromise) {
-            return this.initializingPromise;
-        }
-        this.retryCount = 0;
-        this.initializingPromise = this._initialize();
-        try {
-            await this.initializingPromise;
-        }
-        finally {
-            this.initializingPromise = null;
-        }
-    }
-    async _initialize() {
-        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-            try {
-                // Fire-and-forget: non-critical connection attempt log
-                logger.info('Attempting to connect to Redis', {
-                    url: this.sanitizeUrl(config.redis.url),
-                    attempt: attempt + 1
-                });
-                this.client = createClient({
-                    url: config.redis.url,
-                    username: config.redis.username,
-                    password: config.redis.password,
-                });
-                await this.client.connect();
-                await this.client.ping();
-                // Fire-and-forget: non-critical success log
-                logger.info('Successfully connected to Redis');
-                this.retryCount = 0;
-                return;
-            }
-            catch (error) {
-                // Clean up failed client before retrying or throwing
-                if (this.client) {
-                    try {
-                        await this.client.disconnect();
-                    }
-                    catch {
-                        // Ignore disconnect errors
-                    }
-                    this.client = null;
-                }
-                if (attempt < this.maxRetries) {
-                    this.retryCount = attempt + 1;
-                    const delay = Math.min(5000 * 2 ** attempt, 30000) + Math.random() * 1000;
-                    // Fire-and-forget: non-critical retry log
-                    logger.warn('Failed to connect to Redis, retrying...', {
-                        attempt: this.retryCount,
-                        maxRetries: this.maxRetries,
-                        nextRetryMs: Math.round(delay),
-                        error: error instanceof Error ? error.message : String(error)
-                    });
-                    await new Promise(resolve => setTimeout(resolve, delay));
-                }
-                else {
-                    const appError = new AppError(CommonErrors.CONNECTION_FAILED, `Failed to connect to Redis after ${this.maxRetries} attempts: ${error instanceof Error ? error.message : String(error)}`, true);
-                    await logger.error('Redis connection failed permanently', appError);
-                    throw appError;
-                }
-            }
-        }
-    }
-    async get(key) {
-        if (!this.client) {
-            throw new AppError(CommonErrors.CONNECTION_FAILED, 'Redis client not initialized. Call initialize() first.', true);
-        }
-        try {
-            const value = await this.client.get(key);
-            logger.debug('Redis GET operation completed', { key, hasValue: value !== null });
-            return value;
-        }
-        catch (error) {
-            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to get key '${key}' from Redis: ${error instanceof Error ? error.message : String(error)}`, true);
-            await logger.error('Redis GET operation failed', appError, { key });
-            throw appError;
-        }
-    }
-    async set(key, value) {
-        if (!this.client) {
-            throw new AppError(CommonErrors.CONNECTION_FAILED, 'Redis client not initialized. Call initialize() first.', true);
-        }
-        try {
-            await this.client.set(key, value);
-            logger.debug('Redis SET operation completed', { key });
-        }
-        catch (error) {
-            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to set key '${key}' in Redis: ${error instanceof Error ? error.message : String(error)}`, true);
-            await logger.error('Redis SET operation failed', appError, { key });
-            throw appError;
-        }
-    }
-    async delete(key) {
-        if (!this.client) {
-            throw new AppError(CommonErrors.CONNECTION_FAILED, 'Redis client not initialized. Call initialize() first.', true);
-        }
-        try {
-            await this.client.del(key);
-            logger.debug('Redis DEL operation completed', { key });
-        }
-        catch (error) {
-            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to delete key '${key}' from Redis: ${error instanceof Error ? error.message : String(error)}`, true);
-            await logger.error('Redis DEL operation failed', appError, { key });
-            throw appError;
-        }
-    }
-    async listKeys() {
-        if (!this.client) {
-            throw new AppError(CommonErrors.CONNECTION_FAILED, 'Redis client not initialized. Call initialize() first.', true);
-        }
-        try {
-            let cursor = 0;
-            const allKeys = [];
-            do {
-                const result = await this.client.scan(cursor, {
-                    MATCH: '*',
-                    COUNT: 1000
-                });
-                allKeys.push(...result.keys);
-                // Depending on the redis client, cursor may be a string; normalize to number
-                cursor = typeof result.cursor === 'string' ? Number(result.cursor) : result.cursor;
-            } while (cursor !== 0);
-            logger.debug('Redis KEYS operation completed', { count: allKeys.length });
-            return allKeys;
-        }
-        catch (error) {
-            const appError = new AppError(CommonErrors.OPERATION_FAILED, `Failed to list keys in Redis: ${error instanceof Error ? error.message : String(error)}`, true);
-            await logger.error('Redis KEYS operation failed', appError);
-            throw appError;
-        }
-    }
-    async close() {
-        if (this.client) {
-            try {
-                await this.client.quit();
-                logger.info('Redis connection closed successfully');
-            }
-            catch (error) {
-                // Fire-and-forget: best-effort log during cleanup
-                logger.error('Error closing Redis connection', error instanceof Error ? error : new Error(String(error)));
-            }
-            finally {
-                this.client = null;
-                this.retryCount = 0;
-            }
-        }
-    }
-}
-export const redisService = new RedisService();

package/dist/services/redis.service.test.js

@@ -1,399 +0,0 @@
-import { redisService } from './redis.service';
-import { AppError, CommonErrors } from '../errors/AppError.js';
-// Mock the logger service
-jest.mock('./logger.service.js', () => ({
-    logger: {
-        info: jest.fn().mockResolvedValue(undefined),
-        warn: jest.fn().mockResolvedValue(undefined),
-        error: jest.fn().mockResolvedValue(undefined),
-        debug: jest.fn().mockResolvedValue(undefined),
-    }
-}));
-// Mock the config
-jest.mock('../config/index.js', () => ({
-    config: {
-        redis: {
-            url: 'redis://localhost:6379',
-            username: 'testuser',
-            password: 'testpass'
-        }
-    }
-}));
-// Mock the Redis library
-jest.mock('redis', () => {
-    const mockConnect = jest.fn();
-    const mockPing = jest.fn();
-    const mockGet = jest.fn();
-    const mockSet = jest.fn();
-    const mockDel = jest.fn();
-    const mockScan = jest.fn();
-    const mockQuit = jest.fn();
-    const mockClient = {
-        connect: mockConnect,
-        ping: mockPing,
-        get: mockGet,
-        set: mockSet,
-        del: mockDel,
-        scan: mockScan,
-        quit: mockQuit
-    };
-    return {
-        createClient: jest.fn().mockReturnValue(mockClient),
-        mockConnect,
-        mockPing,
-        mockGet,
-        mockSet,
-        mockDel,
-        mockScan,
-        mockQuit,
-        mockClient
-    };
-});
-describe('Redis Service', () => {
-    let mockRedis;
-    beforeAll(async () => {
-        // Access the mocks
-        mockRedis = await import('redis');
-    });
-    beforeEach(() => {
-        jest.clearAllMocks();
-        // Reset service state
-        redisService.client = null;
-        redisService.retryCount = 0;
-        redisService.initializingPromise = null;
-    });
-    describe('initialize', () => {
-        it('should successfully initialize and connect to Redis', async () => {
-            // Arrange
-            mockRedis.mockConnect.mockResolvedValue(undefined);
-            mockRedis.mockPing.mockResolvedValue('PONG');
-            // Act
-            await redisService.initialize();
-            // Assert
-            expect(mockRedis.createClient).toHaveBeenCalledWith({
-                url: 'redis://localhost:6379',
-                username: 'testuser',
-                password: 'testpass',
-            });
-            expect(mockRedis.mockConnect).toHaveBeenCalled();
-            expect(mockRedis.mockPing).toHaveBeenCalled();
-            expect(redisService.client).not.toBeNull();
-            expect(redisService.retryCount).toBe(0);
-            expect(redisService.initializingPromise).toBeNull();
-        });
-        it('should await ongoing initialization if already initializing', async () => {
-            // Arrange
-            mockRedis.mockConnect.mockResolvedValue(undefined);
-            mockRedis.mockPing.mockResolvedValue('PONG');
-            // Act - start two initializations concurrently
-            const init1 = redisService.initialize();
-            const init2 = redisService.initialize();
-            await Promise.all([init1, init2]);
-            // Assert - createClient should only be called once
-            expect(mockRedis.createClient).toHaveBeenCalledTimes(1);
-            expect(redisService.client).not.toBeNull();
-        });
-        it('should retry connection on failure and eventually succeed', async () => {
-            // Arrange
-            const connectError = new Error('Connection failed');
-            mockRedis.mockConnect
-                .mockRejectedValueOnce(connectError)
-                .mockRejectedValueOnce(connectError)
-                .mockResolvedValueOnce(undefined);
-            mockRedis.mockPing.mockResolvedValue('PONG');
-            // Mock setTimeout to avoid actual delays
-            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
-                setImmediate(callback);
-                return {};
-            });
-            // Act
-            await redisService.initialize();
-            // Assert
-            expect(mockRedis.createClient).toHaveBeenCalledTimes(3);
-            expect(redisService.client).not.toBeNull();
-            expect(redisService.retryCount).toBe(0);
-            // Cleanup
-            setTimeoutSpy.mockRestore();
-        });
-        it('should throw AppError after max retries exceeded', async () => {
-            // Arrange
-            const connectError = new Error('Connection failed');
-            mockRedis.mockConnect.mockRejectedValue(connectError);
-            // Mock setTimeout to avoid actual delays
-            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
-                setImmediate(callback);
-                return {};
-            });
-            // Act & Assert
-            try {
-                await redisService.initialize();
-                fail('Expected initialize to throw AppError');
-            }
-            catch (error) {
-                expect(error).toBeInstanceOf(AppError);
-                expect(error.name).toBe(CommonErrors.CONNECTION_FAILED);
-            }
-            expect(mockRedis.createClient).toHaveBeenCalledTimes(6); // 1 initial + 5 retries
-            // Cleanup
-            setTimeoutSpy.mockRestore();
-        });
-        it('should handle ping failure during connection test', async () => {
-            // Arrange
-            const pingError = new Error('Ping failed');
-            mockRedis.mockConnect.mockResolvedValue(undefined);
-            mockRedis.mockPing.mockRejectedValue(pingError);
-            // Mock setTimeout to avoid actual delays
-            const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation((callback) => {
-                setImmediate(callback);
-                return {};
-            });
-            // Act & Assert
-            await expect(redisService.initialize()).rejects.toThrow(AppError);
-            // Cleanup
-            setTimeoutSpy.mockRestore();
-        });
-    });
-    describe('get', () => {
-        it('should get a value from Redis', async () => {
-            // Arrange
-            const key = 'testKey';
-            const expectedValue = 'testValue';
-            mockRedis.mockGet.mockResolvedValue(expectedValue);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            const result = await redisService.get(key);
-            // Assert
-            expect(mockRedis.mockGet).toHaveBeenCalledWith(key);
-            expect(result).toBe(expectedValue);
-        });
-        it('should return null when key does not exist', async () => {
-            // Arrange
-            const key = 'nonExistentKey';
-            mockRedis.mockGet.mockResolvedValue(null);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            const result = await redisService.get(key);
-            // Assert
-            expect(mockRedis.mockGet).toHaveBeenCalledWith(key);
-            expect(result).toBeNull();
-        });
-        it('should throw AppError if client is not initialized', async () => {
-            // Arrange
-            redisService.client = null;
-            // Act & Assert
-            await expect(redisService.get('testKey'))
-                .rejects
-                .toThrow(AppError);
-            await expect(redisService.get('testKey'))
-                .rejects
-                .toThrow('Redis client not initialized');
-        });
-        it('should throw AppError when get operation fails', async () => {
-            // Arrange
-            const key = 'testKey';
-            const getError = new Error('Redis GET failed');
-            mockRedis.mockGet.mockRejectedValue(getError);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act & Assert
-            try {
-                await redisService.get(key);
-                fail('Expected get to throw AppError');
-            }
-            catch (error) {
-                expect(error).toBeInstanceOf(AppError);
-                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
-            }
-        });
-    });
-    describe('set', () => {
-        it('should set a value in Redis', async () => {
-            // Arrange
-            const key = 'testKey';
-            const value = 'testValue';
-            mockRedis.mockSet.mockResolvedValue('OK');
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            await redisService.set(key, value);
-            // Assert
-            expect(mockRedis.mockSet).toHaveBeenCalledWith(key, value);
-        });
-        it('should throw AppError if client is not initialized', async () => {
-            // Arrange
-            redisService.client = null;
-            // Act & Assert
-            await expect(redisService.set('testKey', 'testValue'))
-                .rejects
-                .toThrow(AppError);
-            await expect(redisService.set('testKey', 'testValue'))
-                .rejects
-                .toThrow('Redis client not initialized');
-        });
-        it('should throw AppError when set operation fails', async () => {
-            // Arrange
-            const key = 'testKey';
-            const value = 'testValue';
-            const setError = new Error('Redis SET failed');
-            mockRedis.mockSet.mockRejectedValue(setError);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act & Assert
-            try {
-                await redisService.set(key, value);
-                fail('Expected set to throw AppError');
-            }
-            catch (error) {
-                expect(error).toBeInstanceOf(AppError);
-                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
-            }
-        });
-    });
-    describe('close', () => {
-        it('should close the client connection successfully', async () => {
-            // Arrange
-            mockRedis.mockQuit.mockResolvedValue('OK');
-            redisService.client = mockRedis.mockClient;
-            redisService.retryCount = 3;
-            // Act
-            await redisService.close();
-            // Assert
-            expect(mockRedis.mockQuit).toHaveBeenCalled();
-            expect(redisService.client).toBeNull();
-            expect(redisService.retryCount).toBe(0);
-        });
-        it('should handle close error gracefully', async () => {
-            // Arrange
-            const closeError = new Error('Close failed');
-            mockRedis.mockQuit.mockRejectedValue(closeError);
-            redisService.client = mockRedis.mockClient;
-            redisService.retryCount = 2;
-            // Act
-            await redisService.close();
-            // Assert
-            expect(mockRedis.mockQuit).toHaveBeenCalled();
-            expect(redisService.client).toBeNull();
-            expect(redisService.retryCount).toBe(0);
-        });
-        it('should not throw if client is already null', async () => {
-            // Arrange
-            redisService.client = null;
-            // Act & Assert
-            await expect(redisService.close()).resolves.not.toThrow();
-            expect(mockRedis.mockQuit).not.toHaveBeenCalled();
-        });
-    });
-    describe('delete', () => {
-        it('should delete a key from Redis', async () => {
-            // Arrange
-            const key = 'testKey';
-            mockRedis.mockDel.mockResolvedValue(1);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            await redisService.delete(key);
-            // Assert
-            expect(mockRedis.mockDel).toHaveBeenCalledWith(key);
-        });
-        it('should throw AppError if client is not initialized', async () => {
-            // Arrange
-            redisService.client = null;
-            // Act & Assert
-            await expect(redisService.delete('testKey'))
-                .rejects
-                .toThrow(AppError);
-            await expect(redisService.delete('testKey'))
-                .rejects
-                .toThrow('Redis client not initialized');
-        });
-        it('should throw AppError when delete operation fails', async () => {
-            // Arrange
-            const key = 'testKey';
-            const delError = new Error('Redis DEL failed');
-            mockRedis.mockDel.mockRejectedValue(delError);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act & Assert
-            try {
-                await redisService.delete(key);
-                fail('Expected delete to throw AppError');
-            }
-            catch (error) {
-                expect(error).toBeInstanceOf(AppError);
-                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
-            }
-        });
-    });
-    describe('listKeys', () => {
-        it('should list all keys from Redis using scan iteration', async () => {
-            // Arrange
-            mockRedis.mockScan
-                .mockResolvedValueOnce({ cursor: 5, keys: ['key1', 'key2'] })
-                .mockResolvedValueOnce({ cursor: 10, keys: ['key3', 'key4'] })
-                .mockResolvedValueOnce({ cursor: 0, keys: ['key5'] });
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            const result = await redisService.listKeys();
-            // Assert
-            expect(mockRedis.mockScan).toHaveBeenCalledTimes(3);
-            expect(mockRedis.mockScan).toHaveBeenCalledWith(0, { MATCH: '*', COUNT: 1000 });
-            expect(mockRedis.mockScan).toHaveBeenCalledWith(5, { MATCH: '*', COUNT: 1000 });
-            expect(mockRedis.mockScan).toHaveBeenCalledWith(10, { MATCH: '*', COUNT: 1000 });
-            expect(result).toEqual(['key1', 'key2', 'key3', 'key4', 'key5']);
-        });
-        it('should handle cursor as string and convert to number', async () => {
-            // Arrange
-            mockRedis.mockScan
-                .mockResolvedValueOnce({ cursor: '5', keys: ['key1'] })
-                .mockResolvedValueOnce({ cursor: '0', keys: ['key2'] });
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            const result = await redisService.listKeys();
-            // Assert
-            expect(mockRedis.mockScan).toHaveBeenCalledTimes(2);
-            expect(result).toEqual(['key1', 'key2']);
-        });
-        it('should return empty array when no keys exist', async () => {
-            // Arrange
-            mockRedis.mockScan.mockResolvedValueOnce({ cursor: 0, keys: [] });
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act
-            const result = await redisService.listKeys();
-            // Assert
-            expect(mockRedis.mockScan).toHaveBeenCalledTimes(1);
-            expect(result).toEqual([]);
-        });
-        it('should throw AppError if client is not initialized', async () => {
-            // Arrange
-            redisService.client = null;
-            // Act & Assert
-            await expect(redisService.listKeys())
-                .rejects
-                .toThrow(AppError);
-            await expect(redisService.listKeys())
-                .rejects
-                .toThrow('Redis client not initialized');
-        });
-        it('should throw AppError when listKeys operation fails', async () => {
-            // Arrange
-            const scanError = new Error('Redis SCAN failed');
-            mockRedis.mockScan.mockRejectedValue(scanError);
-            // Force client to be available
-            redisService.client = mockRedis.mockClient;
-            // Act & Assert
-            try {
-                await redisService.listKeys();
-                fail('Expected listKeys to throw AppError');
-            }
-            catch (error) {
-                expect(error).toBeInstanceOf(AppError);
-                expect(error.name).toBe(CommonErrors.OPERATION_FAILED);
-            }
-        });
-    });
-});