feat: pass messageId to handler. allow handler to not reply. closes #11

Author: mikuso

README.md

@@ -521,9 +521,21 @@ When the `handler` function is invoked, it will be passed an object with the fol
 * `method` {String} - The name of the method being invoked (useful for wildcard handlers).
 * `params` {*} - The `params` value passed to the call.
 * `signal` {AbortSignal} - A signal which will abort if the underlying connection is dropped (therefore, the response will never be received by the caller). You may choose whether to ignore the signal or not, but it could save you some time if you use it to abort the call early.
+* `messageId` {String} - The OCPP Message ID used in the call.
 
 If the invocation of the `handler` resolves or returns, the resolved value will be returned to the caller.
 If the invocation of the `handler` rejects or throws, an error will be passed to the caller. By default, the error will be an instance of `RPCGenericError`, although additional error types are possible ([see createRPCError](#createrpcerrortype-message-details)).
+If the `handler` returns a `NOREPLY` symbol then no reply will be sent. It will be your responsibility to send the reply by some other means (such as [`sendRaw()`](#clientsendrawmessage)).
+
+##### Example of NOREPLY
+
+```js
+const {NOREPLY} = require('ocpp-rpc');
+
+client.handle('WontReply', () => {
+    return NOREPLY;
+});
+```
 
 #### client.call(method[, params[, options]])
 

index.js

@@ -1,13 +1,15 @@
 const RPCClient = require('./lib/client');
 const RPCServer = require('./lib/server');
 const errors = require('./lib/errors');
+const symbols = require('./lib/symbols');
 const { createRPCError } = require('./lib/util');
 const { createValidator } = require('./lib/validator');
 
 module.exports = {
     RPCServer,
     RPCClient,
-    ...errors,
     createRPCError,
     createValidator,
+    ...errors,
+    ...symbols,
 };

lib/client.js

@@ -1,9 +1,10 @@
-const {randomUUID} = require('crypto');
-const {EventEmitter, once} = require('events');
-const { setTimeout, setInterval } = require('timers/promises');
+const { randomUUID} = require('crypto');
+const { EventEmitter, once } = require('events');
+const { setTimeout } = require('timers/promises');
 const WebSocket = require('ws');
 const { ExponentialStrategy } = require('backoff');
-const {CONNECTING, OPEN, CLOSING, CLOSED} = WebSocket;
+const { CONNECTING, OPEN, CLOSING, CLOSED } = WebSocket;
+const { NOREPLY } = require('./symbols');
 const { TimeoutError, UnexpectedHttpResponse, RPCFrameworkError, RPCGenericError, RPCMessageTypeNotSupportedError } = require('./errors');
 const { getErrorPlainObject, createRPCError, getPackageIdent } = require('./util');
 const Queue = require('./queue');
@@ -727,11 +728,21 @@ class RPCClient extends EventEmitter {
                 }
 
                 const ac = new AbortController();
-                const callPromise = Promise.resolve(handler({method, params, signal: ac.signal}));
+                const callPromise = Promise.resolve(handler({
+                    messageId: msgId,
+                    method,
+                    params,
+                    signal: ac.signal,
+                }));
+                
                 const pending = {abort: ac.abort.bind(ac), promise: callPromise};
                 this._pendingResponses.set(msgId, pending);
                 const result = await callPromise;
 
+                if (result === NOREPLY) {
+                    return; // don't send a reply
+                }
+
                 payload = [MSG_CALLRESULT, msgId, result];
 
                 if (this._strictProtocols.includes(this._protocol)) {

lib/symbols.js

@@ -0,0 +1,3 @@
+module.exports = {
+    NOREPLY: Symbol("NOREPLY"),
+};

test/client.js

@@ -7,6 +7,7 @@ const RPCServer = require("../lib/server");
 const { setTimeout } = require('timers/promises');
 const { createValidator } = require('../lib/validator');
 const { createRPCError } = require('../lib/util');
+const { NOREPLY } = require('../lib/symbols');
 const {CLOSING, CLOSED, CONNECTING} = RPCClient;
 
 describe('RPCClient', function(){
@@ -1593,6 +1594,27 @@ describe('RPCClient', function(){
 
         });
 
+        it('should not reject when making unhandled noReply call', async () => {
+
+            const {endpoint, close} = await createServer();
+            const cli = new RPCClient({
+                endpoint,
+                identity: 'X',
+            });
+
+            try {
+                await cli.connect();
+                
+                const res = await cli.call('UnrecognisedMethod', 1, {noReply: true});
+                assert.equal(res, undefined);
+
+            } finally {
+                await cli.close();
+                close();
+            }
+
+        });
+
     });
 
 
@@ -1994,6 +2016,72 @@ describe('RPCClient', function(){
 
         });
 
+        
+        it('should not respond to a call that returns NOREPLY symbol', async () => {
+
+            const {endpoint, close} = await createServer({}, {
+                withClient: cli => {
+                    cli.handle('NoReply', () => {
+                        return NOREPLY;
+                    });
+                }
+            });
+            const cli = new RPCClient({
+                endpoint,
+                identity: 'X',
+            });
+
+            try {
+                await cli.connect();
+                
+                await assert.rejects(cli.call('NoReply', 123, {callTimeoutMs: 50}), TimeoutError);
+
+            } finally {
+                await cli.close();
+                close();
+            }
+
+        });
+
+        
+        it('should report the message ID', async () => {
+
+            const {endpoint, close} = await createServer({}, {
+                withClient: cli => {
+                    cli.handle('Manual', async ({messageId}) => {
+                        await cli.sendRaw(JSON.stringify([
+                            3,
+                            messageId,
+                            {messageId}
+                        ]));
+                        return NOREPLY;
+                    });
+                }
+            });
+            const cli = new RPCClient({
+                endpoint,
+                identity: 'X',
+            });
+
+            try {
+                await cli.connect();
+                
+                const callOutProm = once(cli, 'call');
+                const {messageId} = await cli.call('Manual');
+                const [callOut] = await callOutProm;
+                
+                assert.equal(callOut.outbound, true);
+                assert.equal(callOut.payload[0], 2);
+                assert.equal(callOut.payload[1], messageId);
+                assert.equal(callOut.payload[2], 'Manual');
+
+            } finally {
+                await cli.close();
+                close();
+            }
+
+        });
+
     });