resplite 1.1.12 → 1.2.0

package/README.md

@@ -87,7 +87,7 @@ OK
 
 ### Standalone server script (fixed port)
 
-Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process is killed.
+Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process receives SIGINT (Ctrl+C) or SIGTERM; then it closes the server and exits cleanly.
 
 ```javascript
 // server.js
@@ -95,6 +95,14 @@ import { createRESPlite } from 'resplite/embed';
 
 const srv = await createRESPlite({ port: 6380, db: './data.db' });
 console.log(`RESPLite listening on ${srv.host}:${srv.port}`);
+
+async function shutdown() {
+  await srv.close();
+  process.exit(0);
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
 ```
 
 Then connect from any other script or process:
@@ -142,6 +150,37 @@ await client.quit();
 await srv.close();
 ```
 
+### Observability (event hooks)
+
+When embedding RESPLite you can pass optional hooks to log unknown commands, command errors, or socket errors (e.g. for `warn`/`error` in your logger). The client still receives the same RESP responses; hooks are for observability only.
+
+```javascript
+import pino from 'pino';
+const log = pino(); // or your logger
+
+const srv = await createRESPlite({
+  port: 6380,
+  db: './data.db',
+  hooks: {
+    onUnknownCommand({ command, argsCount, clientAddress }) {
+      log.warn({ command, argsCount, clientAddress }, 'RESPLite: unsupported command');
+    },
+    onCommandError({ command, error, clientAddress }) {
+      log.warn({ command, error, clientAddress }, 'RESPLite: command error');
+    },
+    onSocketError({ error, clientAddress }) {
+      log.error({ err: error, clientAddress }, 'RESPLite: connection error');
+    },
+  },
+});
+```
+
+| Hook | When it is called |
+|------|--------------------|
+| `onUnknownCommand` | Client sent a command not implemented by RESPLite (e.g. `SUBSCRIBE`, `PUBLISH`). |
+| `onCommandError` | A command failed (wrong type, invalid args, or handler threw). |
+| `onSocketError` | The connection socket emitted an error (e.g. `ECONNRESET`). |
+
 ### Strings, TTL, and key operations
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.1.12",
+  "version": "1.2.0",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/src/commands/registry.js

@@ -135,7 +135,7 @@ const HANDLERS = new Map([
  * Dispatch command. Full argv: [commandNameBuf, ...argBuffers].
  * @param {object} engine
  * @param {Buffer[]} argv - first element is command name, rest are arguments
- * @param {object} [context] - optional connection context (connectionId, writeResponse) for blocking commands
+ * @param {object} [context] - optional connection context (connectionId, clientAddress, writeResponse, onUnknownCommand, onCommandError)
  * @returns {{ result: unknown } | { error: string } | { quit: true } | { block: object }}
  */
 export function dispatch(engine, argv, context) {
@@ -146,17 +146,38 @@ export function dispatch(engine, argv, context) {
   const args = argv.slice(1);
   const handler = HANDLERS.get(cmd);
   if (!handler) {
+    context?.onUnknownCommand?.({
+      command: cmd,
+      argsCount: args.length,
+      clientAddress: context.clientAddress ?? '',
+      connectionId: context.connectionId ?? 0,
+    });
     return { error: unsupported() };
   }
   try {
     const result = handler(engine, args, context);
     if (result && result.quit) return result;
-    if (result && result.error) return result;
+    if (result && result.error) {
+      context?.onCommandError?.({
+        command: cmd,
+        error: result.error,
+        clientAddress: context.clientAddress ?? '',
+        connectionId: context.connectionId ?? 0,
+      });
+      return result;
+    }
     if (result && result.block) return result;
     return { result };
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);
-    return { error: msg.startsWith('ERR ') ? msg : 'ERR ' + msg };
+    const errorMsg = msg.startsWith('ERR ') ? msg : 'ERR ' + msg;
+    context?.onCommandError?.({
+      command: cmd,
+      error: errorMsg,
+      clientAddress: context.clientAddress ?? '',
+      connectionId: context.connectionId ?? 0,
+    });
+    return { error: errorMsg };
   }
 }
 

package/src/embed.js

@@ -16,6 +16,16 @@ import { openDb } from './storage/sqlite/db.js';
 
 export { handleConnection, createEngine, openDb };
 
+/**
+ * Optional event hooks for observability (e.g. logging unknown commands or errors).
+ * All hooks are optional. Called with plain objects; do not mutate.
+ *
+ * @typedef {object} RESPliteHooks
+ * @property {(payload: { command: string, argsCount: number, clientAddress: string, connectionId: number }) => void} [onUnknownCommand] Invoked when the client sends a command not implemented by RESPLite.
+ * @property {(payload: { command: string, error: string, clientAddress: string, connectionId: number }) => void} [onCommandError] Invoked when a command handler throws or returns an error (e.g. WRONGTYPE, invalid args).
+ * @property {(payload: { error: Error, clientAddress: string, connectionId: number }) => void} [onSocketError] Invoked when a connection socket emits an error (e.g. ECONNRESET).
+ */
+
 /**
  * Start an embedded RESPLite server.
  *
@@ -24,6 +34,7 @@ export { handleConnection, createEngine, openDb };
  * @param {string} [options.host='127.0.0.1']     Host to listen on.
  * @param {number} [options.port=0]               Port to listen on (0 = OS-assigned).
  * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none).
+ * @param {RESPliteHooks} [options.hooks]         Optional event hooks for observability (onUnknownCommand, onCommandError, onSocketError).
  * @returns {Promise<{ port: number, host: string, close: () => Promise<void> }>}
  */
 export async function createRESPlite({
@@ -31,6 +42,7 @@ export async function createRESPlite({
   host = '127.0.0.1',
   port = 0,
   pragmaTemplate = 'default',
+  hooks = {},
 } = {}) {
   const db = openDb(dbPath, { pragmaTemplate });
   const engine = createEngine({ db });
@@ -39,7 +51,7 @@ export async function createRESPlite({
   const server = net.createServer((socket) => {
     connections.add(socket);
     socket.once('close', () => connections.delete(socket));
-    handleConnection(socket, engine);
+    handleConnection(socket, engine, hooks);
   });
   await new Promise((resolve) => server.listen(port, host, resolve));
 

package/src/server/connection.js

@@ -12,17 +12,22 @@ let nextConnectionId = 0;
 /**
  * @param {import('net').Socket} socket
  * @param {object} engine
+ * @param {object} [hooks] Optional: onUnknownCommand, onCommandError, onSocketError
  */
-export function handleConnection(socket, engine) {
+export function handleConnection(socket, engine, hooks = {}) {
   const reader = new RESPReader();
   const connectionId = ++nextConnectionId;
+  const clientAddress = `${socket.remoteAddress ?? 'unknown'}:${socket.remotePort ?? 0}`;
   const context = {
     connectionId,
+    clientAddress,
     monitorMode: false,
-    clientAddress: `${socket.remoteAddress ?? 'unknown'}:${socket.remotePort ?? 0}`,
     writeResponse(buf) {
       if (socket.writable) socket.write(buf);
     },
+    onUnknownCommand: hooks.onUnknownCommand,
+    onCommandError: hooks.onCommandError,
+    onSocketError: hooks.onSocketError,
   };
 
   function writeResult(out) {
@@ -94,5 +99,7 @@ export function handleConnection(socket, engine) {
     unregisterMonitorClient(connectionId);
   });
 
-  socket.on('error', () => {});
+  socket.on('error', (err) => {
+    context.onSocketError?.({ error: err, clientAddress: context.clientAddress, connectionId: context.connectionId });
+  });
 }

package/test/integration/embed.test.js

@@ -88,4 +88,69 @@ describe('createRESPlite', () => {
     await client.quit();
     await srv.close();
   });
+
+  it('unsupported command still returns ERR command not supported yet to client', async () => {
+    const srv = await createRESPlite();
+    const client = await redisClient(srv.port);
+    try {
+      await client.sendCommand(['SUBSCRIBE', 'ch']);
+      assert.fail('expected error');
+    } catch (e) {
+      assert.ok(e.message.includes('not supported'), e.message);
+    }
+    await client.quit();
+    await srv.close();
+  });
+
+  it('onUnknownCommand hook is called for unsupported commands', async () => {
+    const unknownCalls = [];
+    const srv = await createRESPlite({
+      hooks: {
+        onUnknownCommand(payload) {
+          unknownCalls.push(payload);
+        },
+      },
+    });
+    const client = await redisClient(srv.port);
+    try {
+      await client.sendCommand(['SUBSCRIBE', 'ch']);
+    } catch (_) {}
+    try {
+      await client.sendCommand(['PUBLISH', 'ch', 'x']);
+    } catch (_) {}
+    await client.quit();
+    await srv.close();
+    const commands = unknownCalls.map((c) => c.command);
+    assert.ok(commands.includes('SUBSCRIBE'), 'expected SUBSCRIBE in ' + commands.join(', '));
+    assert.ok(commands.includes('PUBLISH'), 'expected PUBLISH in ' + commands.join(', '));
+    const sub = unknownCalls.find((c) => c.command === 'SUBSCRIBE');
+    const pub = unknownCalls.find((c) => c.command === 'PUBLISH');
+    assert.equal(sub.argsCount, 1);
+    assert.equal(pub.argsCount, 2);
+    assert.equal(typeof sub.connectionId, 'number');
+    assert.ok(sub.clientAddress.length > 0);
+  });
+
+  it('onCommandError hook is called when command returns or throws error', async () => {
+    const errorCalls = [];
+    const srv = await createRESPlite({
+      hooks: {
+        onCommandError(payload) {
+          errorCalls.push(payload);
+        },
+      },
+    });
+    const client = await redisClient(srv.port);
+    await client.set('k', 'str');
+    try {
+      await client.hGet('k', 'f');
+    } catch (_) {}
+    await client.quit();
+    await srv.close();
+    assert.equal(errorCalls.length, 1);
+    assert.equal(errorCalls[0].command, 'HGET');
+    assert.ok(errorCalls[0].error.includes('WRONGTYPE'));
+    assert.equal(typeof errorCalls[0].connectionId, 'number');
+    assert.ok(errorCalls[0].clientAddress.length > 0);
+  });
 });