@mojaloop/sdk-scheme-adapter 12.0.2 → 12.2.1

package/src/ControlServer/index.js

@@ -0,0 +1,294 @@
+/**************************************************************************
+ *  (C) Copyright ModusBox Inc. 2020 - All rights reserved.               *
+ *                                                                        *
+ *  This file is made available under the terms of the license agreement  *
+ *  specified in the corresponding source code repository.                *
+ *                                                                        *
+ *  ORIGINAL AUTHOR:                                                      *
+ *       Matt Kingston - matt.kingston@modusbox.com                       *
+ **************************************************************************/
+
+// This server has deliberately been written separate from any other server in the SDK. There is
+// some reasonable argument that it could be part of the outbound or test server. It has not been
+// incorporated in either as, at the time of writing, it is intended to be maintained in a
+// proprietary fork. Therefore, keeping it independent of other servers will avoid the maintenance
+// burden that would otherwise be associated with incorporating it with those.
+//
+// It inherits from the Server class from the 'ws' websocket library for Node, which in turn
+// inherits from EventEmitter. We exploit this to emit an event when a reconfigure message is sent
+// to this server. Then, when this server's reconfigure method is called, it reconfigures itself
+// and sends a message to all clients notifying them of the new application configuration.
+//
+// It expects new configuration to be supplied as an array of JSON patches. It therefore exposes
+// the current configuration to
+
+const assert = require('assert').strict;
+
+const ws = require('ws');
+const jsonPatch = require('fast-json-patch');
+
+const randomPhrase = require('~/lib/randomphrase');
+
+/**************************************************************************
+ * The message protocol messages, verbs, and errors
+ *************************************************************************/
+const MESSAGE = {
+    CONFIGURATION: 'CONFIGURATION',
+    ERROR: 'ERROR',
+};
+
+const VERB = {
+    READ: 'READ',
+    NOTIFY: 'NOTIFY',
+    PATCH: 'PATCH'
+};
+
+const ERROR = {
+    UNSUPPORTED_MESSAGE: 'UNSUPPORTED_MESSAGE',
+    UNSUPPORTED_VERB: 'UNSUPPORTED_VERB',
+    JSON_PARSE_ERROR: 'JSON_PARSE_ERROR',
+};
+
+/**************************************************************************
+ * Events emitted by the control server
+ *************************************************************************/
+const EVENT = {
+    RECONFIGURE: 'RECONFIGURE',
+};
+
+/**************************************************************************
+ * Private convenience functions
+ *************************************************************************/
+const serialise = JSON.stringify;
+const deserialise = (msg) => {
+    //reviver function
+    return JSON.parse(msg.toString(), (k, v) => {
+        if (
+            v !== null            &&
+          typeof v === 'object' &&
+          'type' in v           &&
+          v.type === 'Buffer'   &&
+          'data' in v           &&
+          Array.isArray(v.data)) {
+            return new Buffer(v.data);
+        }
+        return v;
+    });
+};
+
+const buildMsg = (verb, msg, data, id = randomPhrase()) => serialise({
+    verb,
+    msg,
+    data,
+    id,
+});
+
+const buildPatchConfiguration = (oldConf, newConf, id) => {
+    const patches = jsonPatch.compare(oldConf, newConf);
+    return buildMsg(VERB.PATCH, MESSAGE.CONFIGURATION, patches, id);
+};
+
+const getWsIp = (req) => [
+    req.socket.remoteAddress,
+    ...(
+        req.headers['x-forwarded-for']
+            ? req.headers['x-forwarded-for'].split(/\s*,\s*/)
+            : []
+    )
+];
+
+/**************************************************************************
+ * build
+ *
+ * Public object exposing an API to build valid protocol messages.
+ * It is not the only way to build valid messages within the protocol.
+ *************************************************************************/
+const build = {
+    CONFIGURATION: {
+        PATCH: buildPatchConfiguration,
+        READ: (id) => buildMsg(VERB.READ, MESSAGE.CONFIGURATION, {}, id),
+        NOTIFY: (config, id) => buildMsg(VERB.NOTIFY, MESSAGE.CONFIGURATION, config, id),
+    },
+    ERROR: {
+        NOTIFY: {
+            UNSUPPORTED_MESSAGE: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.UNSUPPORTED_MESSAGE, id),
+            UNSUPPORTED_VERB: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.UNSUPPORTED_VERB, id),
+            JSON_PARSE_ERROR: (id) => buildMsg(VERB.NOTIFY, MESSAGE.ERROR, ERROR.JSON_PARSE_ERROR, id),
+        }
+    },
+};
+
+/**************************************************************************
+ * Client
+ *
+ * The Control Client. Client for the websocket control API.
+ * Used to hot-restart the SDK.
+ *
+ * logger    - Logger- see SDK logger used elsewhere
+ * address   - address of control server
+ * port      - port of control server
+ *************************************************************************/
+class Client extends ws {
+    constructor({ address = 'localhost', port, logger }) {
+        super(`ws://${address}:${port}`);
+        this._logger = logger;
+    }
+
+    // Really only exposed so that a user can import only the client for convenience
+    get Build() {
+        return build;
+    }
+
+    static async Create(...args) {
+        const result = new Client(...args);
+        await new Promise((resolve, reject) => {
+            result.on('open', resolve);
+            result.on('error', reject);
+        });
+        return result;
+    }
+
+    async send(msg) {
+        const data = typeof msg === 'string' ? msg : serialise(msg);
+        this._logger.push({ data }).log('Sending message');
+        return new Promise((resolve) => super.send.call(this, data, resolve));
+    }
+
+    // Receive a single message
+    async receive() {
+        return new Promise((resolve) => this.once('message', (data) => {
+            const msg = deserialise(data);
+            this._logger.push({ msg }).log('Received');
+            resolve(msg);
+        }));
+    }
+}
+
+/**************************************************************************
+ * Server
+ *
+ * The Control Server. Exposes a websocket control API.
+ * Used to hot-restart the SDK.
+ *
+ * logger    - Logger- see SDK logger used elsewhere
+ * port      - HTTP port to host on
+ * appConfig - The configuration for the entire application- supplied here as this class uses it to
+ *             validate reconfiguration requests- it is not used for configuration here, however
+ * server    - optional HTTP/S server on which to serve the websocket
+ *************************************************************************/
+class Server extends ws.Server {
+    constructor({ logger, port = 0, appConfig = {} }) {
+        super({ clientTracking: true, port });
+
+        this._logger = logger;
+        this._port = port;
+        this._appConfig = appConfig;
+        this._clientData = new Map();
+
+        this.on('error', err => {
+            this._logger.push({ err })
+                .log('Unhandled websocket error occurred. Shutting down.');
+            process.exit(1);
+        });
+
+        this.on('connection', (socket, req) => {
+            const logger = this._logger.push({
+                url: req.url,
+                ip: getWsIp(req),
+                remoteAddress: req.socket.remoteAddress,
+            });
+            logger.log('Websocket connection received');
+            this._clientData.set(socket, { ip: req.connection.remoteAddress, logger });
+
+            socket.on('close', (code, reason) => {
+                logger.push({ code, reason }).log('Websocket connection closed');
+                this._clientData.delete(socket);
+            });
+
+            socket.on('message', this._handle(socket, logger));
+        });
+
+        this._logger.push(this.address()).log('running on');
+    }
+
+    // Close the server then wait for all the client sockets to close
+    async stop() {
+        await new Promise(this.close.bind(this));
+        this._logger.log('Control server shutdown complete');
+    }
+
+    reconfigure({ logger = this._logger, port = 0, appConfig = this._appConfig }) {
+        assert(port === this._port, 'Cannot reconfigure running port');
+        return () => {
+            const reconfigureClientLogger =
+                ({ logger: clientLogger }) => clientLogger.configure(logger);
+            this._clientData.values(reconfigureClientLogger);
+            this._logger = logger;
+            this._appConfig = appConfig;
+            this._logger.log('restarted');
+        };
+    }
+
+    async notifyClientsOfCurrentConfig() {
+        const updateConfMsg = build.CONFIGURATION.NOTIFY(this._appConfig);
+        const logError = (socket, message) => (err) =>
+            this._logger
+                .push({ message, ip: this._clientData.get(socket).ip, err })
+                .log('Error sending reconfigure notification to client');
+        const sendToAllClients = (msg) => Promise.all(
+            [...this.clients.values()].map((socket) =>
+                (new Promise((resolve) => socket.send(msg, resolve))).catch(logError(socket, msg))
+            )
+        );
+        return await sendToAllClients(updateConfMsg);
+    }
+
+    _handle(client, logger) {
+        return (data) => {
+            // TODO: json-schema validation of received message- should be pretty straight-forward
+            // and will allow better documentation of the API
+            let msg;
+            try {
+                msg = deserialise(data);
+            } catch (err) {
+                logger.push({ data }).log('Couldn\'t parse received message');
+                client.send(build.ERROR.NOTIFY.JSON_PARSE_ERROR());
+            }
+            logger.push({ msg }).log('Handling received message');
+            switch (msg.msg) {
+                case MESSAGE.CONFIGURATION:
+                    switch (msg.verb) {
+                        case VERB.READ:
+                            client.send(build.CONFIGURATION.NOTIFY(this._appConfig, msg.id));
+                            break;
+                        case VERB.PATCH: {
+                            // TODO: validate the incoming patch? Or assume clients have used the
+                            // client library?
+                            const dup = JSON.parse(JSON.stringify(this._appConfig)); // fast-json-patch explicitly mutates
+                            jsonPatch.applyPatch(dup, msg.data);
+                            logger.push({ oldConf: this._appConfig, newConf: dup }).log('Emitting new configuration');
+                            this.emit(EVENT.RECONFIGURE, dup);
+                            break;
+                        }
+                        default:
+                            client.send(build.ERROR.NOTIFY.UNSUPPORTED_VERB(msg.id));
+                            break;
+                    }
+                    break;
+                default:
+                    client.send(build.ERROR.NOTIFY.UNSUPPORTED_MESSAGE(msg.id));
+                    break;
+            }
+        };
+    }
+}
+
+module.exports = {
+    Client,
+    Server,
+    build,
+    MESSAGE,
+    VERB,
+    ERROR,
+    EVENT,
+};

package/src/InboundServer/index.js

@@ -24,6 +24,7 @@ const Validate = require('../lib/validate');
 const router = require('../lib/router');
 const handlers = require('./handlers');
 const middlewares = require('./middlewares');
+const check = require('../lib/check');
 
 class InboundApi extends EventEmitter {
     constructor(conf, logger, cache, validator) {
@@ -43,7 +44,7 @@ class InboundApi extends EventEmitter {
         });
 
         if (conf.validateInboundJws) {
-            this._jwsVerificationKeys = InboundApi._GetJwsKeys(conf.jwsVerificationKeysDirectory);
+            this._jwsVerificationKeys = conf.pm4mlEnabled ? conf.peerJWSKeys :  InboundApi._GetJwsKeys(conf.jwsVerificationKeysDirectory);
         }
         this._api = InboundApi._SetupApi({
             conf,
@@ -187,6 +188,37 @@ class InboundServer extends EventEmitter {
         this._logger.log('inbound shut down complete');
     }
 
+    async reconfigure(conf, logger, cache) {
+        // It may be possible to extract the socket from an existing HTTP/HTTPS server and replace
+        // it in a new server of the other type, as Node's HTTP and HTTPS servers both eventually
+        // are subclasses of net.Server. This wasn't considered as a requirement at the time of
+        // writing.
+        assert(
+            this._conf.mutualTLS.inboundRequests.enabled === conf.mutualTLS.inboundRequests.enabled,
+            'Cannot live-restart an HTTPS server as HTTP or vice versa',
+        );
+        const newApi = new InboundApi(conf, logger, cache, this._validator);
+        await newApi.start();
+        return () => {
+            this._logger = logger;
+            this._cache = cache;
+            // TODO: .tls might be undefined, causing an.. err.. undefined dereference..
+            const tlsCredsChanged = check.notDeepEqual(
+                conf.inbound.tls.creds,
+                this._conf.inbound.tls.creds
+            );
+            if (this._conf.mutualTLS.inboundRequests.enabled && tlsCredsChanged) {
+                this._server.setSecureContext(conf.inbound.tls.creds);
+            }
+            this._server.removeAllListeners('request');
+            this._server.on('request', newApi.callback());
+            this._api.stop();
+            this._api = newApi;
+            this._conf = conf;
+            this._logger.log('restarted');
+        };
+    }
+
     _createServer(tlsEnabled, tlsCreds, handler) {
         if (!tlsEnabled) {
             return http.createServer(handler);

package/src/OutboundServer/index.js

@@ -132,6 +132,21 @@ class OutboundServer extends EventEmitter {
         }
         this._logger.log('Shut down complete');
     }
+
+    async reconfigure(conf, logger, cache, metricsClient) {
+        const newApi = new OutboundApi(conf, logger, cache, this._validator, metricsClient);
+        await newApi.start();
+        return () => {
+            this._logger = logger;
+            this._cache = cache;
+            this._server.removeAllListeners('request');
+            this._server.on('request', newApi.callback());
+            this._api.stop();
+            this._api = newApi;
+            this._conf = conf;
+            this._logger.log('restarted');
+        };
+    }
 }
 
 module.exports = OutboundServer;

package/src/TestServer/index.js

@@ -11,6 +11,7 @@
 const Koa = require('koa');
 const ws = require('ws');
 
+const assert = require('assert').strict;
 const http = require('http');
 const yaml = require('js-yaml');
 const fs = require('fs').promises;
@@ -210,6 +211,36 @@ class TestServer {
         }
         this._logger.log('Test server shutdown complete');
     }
+
+    async reconfigure({ port, logger, cache }) {
+        assert(port === this._port, 'Cannot reconfigure running port');
+        const newApi = new TestApi(logger, cache, this._validator);
+        const newWsApi = new WsServer(logger.push({ component: 'websocket-server' }), cache);
+        await newWsApi.start();
+
+        return () => {
+            const oldWsApi = this._wsapi;
+            this._logger = logger;
+            this._cache = cache;
+            this._wsapi = newWsApi;
+            this._api = newApi;
+            this._server.removeAllListeners('upgrade');
+            this._server.on('upgrade', (req, socket, head) => {
+                this._wsapi.handleUpgrade(req, socket, head, (ws) =>
+                    this._wsapi.emit('connection', ws, req));
+            });
+            this._server.removeAllListeners('request');
+            this._server.on('request', newApi.callback());
+            // TODO: we can't guarantee client implementations. Therefore we can't guarantee
+            // reconnect logic/behaviour. Therefore instead of closing all websocket client
+            // connections as we do below, we should replace handlers.
+            oldWsApi.stop().catch((err) => {
+                this._logger.push({ err }).log('Error stopping websocket server during reconfigure');
+            });
+
+            this._logger.log('restarted');
+        };
+    }
 }
 
 module.exports = TestServer;

package/src/config.js

@@ -58,6 +58,10 @@ const env = from(process.env, {
 
 module.exports = {
     __parseResourceVersion: parseResourceVersions,
+    control: {
+        mgmtAPIWsUrl: env.get('MGMT_API_WS_URL').required().asString(),
+        mgmtAPIWsPort: env.get('MGMT_API_WS_PORT').default('4005').asPortNumber()
+    },
     mutualTLS: {
         inboundRequests: {
             enabled: env.get('INBOUND_MUTUAL_TLS_ENABLED').default('false').asBool(),
@@ -160,4 +164,6 @@ module.exports = {
     // a transactionRequestId. this option decodes the ilp packet for
     // the `transactionId` to retrieve the quote from cache
     allowDifferentTransferTransactionId: env.get('ALLOW_DIFFERENT_TRANSFER_TRANSACTION_ID').default('false').asBool(),
+
+    pm4mlEnabled: env.get('PM4ML_ENABLED').default('false').asBool(),
 };

package/src/lib/model/OutboundBulkQuotesModel.js

@@ -115,7 +115,7 @@ class OutboundBulkQuotesModel {
 
             case 'requestBulkQuote':
                 return this._requestBulkQuote();
-            
+
             case 'getBulkQuote':
                 return this._getBulkQuote(this.data.bulkQuoteId);
 
@@ -266,7 +266,7 @@ class OutboundBulkQuotesModel {
             };
 
             individualQuote.note && (quote.note = individualQuote.note);
-            
+
             if (individualQuote.extensions && individualQuote.extensions.length > 0) {
                 bulkQuoteRequest.extensionList = {
                     extension: individualQuote.extensions
@@ -440,7 +440,7 @@ class OutboundBulkQuotesModel {
                     await this.stateMachine.requestBulkQuote();
                     this._logger.log(`Quotes resolved for bulk quote ${this.data.bulkQuoteId}`);
                     break;
-                
+
                 case 'getBulkQuote':
                     await this.stateMachine.getBulkQuote();
                     this._logger.log(`Get bulk quote ${this.data.bulkQuoteId} has been completed`);

package/src/lib/model/OutboundBulkTransfersModel.js

@@ -257,7 +257,7 @@ class OutboundBulkTransfersModel {
                 ilpPacket: individualTransfer.ilpPacket,
                 condition: individualTransfer.condition,
             };
-            
+
             if (individualTransfer.extensions && individualTransfer.extensions.length > 0) {
                 bulkTransferRequest.extensionList = {
                     extension: individualTransfer.extensions

package/src/lib/model/OutboundRequestToPayModel.js

@@ -297,7 +297,7 @@ class OutboundRequestToPayModel {
                     this._logger.push({ transactionRequestResponse }).log('Transaction Request Response received');
                     this.data.requestToPayState = transactionRequestResponse.transactionRequestState;
 
-                    
+
                     return resolve(transactionRequestResponse);
                 }
                 catch(err) {

package/src/lib/model/OutboundRequestToPayTransferModel.js

@@ -145,7 +145,7 @@ class OutboundRequestToPayTransferModel {
                         }
                     }
                     break;
-                
+
                 case 'otpReceived':
                     // next transition is executeTransfer
                     await this.stateMachine.executeTransfer();
@@ -230,7 +230,7 @@ class OutboundRequestToPayTransferModel {
     }
 
     /**
-     * This method is used to communicate back to the Payee that a rejection is being 
+     * This method is used to communicate back to the Payee that a rejection is being
      * sent because the OTP did not match.
      */
     async rejectRequestToPay() {
@@ -241,7 +241,7 @@ class OutboundRequestToPayTransferModel {
         const response = {
             status : `${this.data.requestToPayTransactionId} has been REJECTED`
         };
-        return JSON.stringify(response);      
+        return JSON.stringify(response);
     }
 
 
@@ -471,7 +471,7 @@ class OutboundRequestToPayTransferModel {
     }
 
     /**
-     * Sends request for 
+     * Sends request for
      * Starts the quote resolution process by sending a POST /quotes request to the switch;
      * then waits for a notification from the cache that the quote response has been received
      */
@@ -480,7 +480,7 @@ class OutboundRequestToPayTransferModel {
         return new Promise(async (resolve, reject) => {
 
             if( this.data.initiatorType && this.data.initiatorType === 'BUSINESS') return resolve();
-            
+
             // listen for events on the quoteId
             const otpKey = `otp_${this.data.requestToPayTransactionId}`;
 
@@ -501,9 +501,9 @@ class OutboundRequestToPayTransferModel {
 
                     const otpResponseBody = otpResponse.data;
                     this._logger.push({ otpResponseBody }).log('OTP response received');
-                    
+
                     this.data.otpResponse = otpResponseBody;
-                    
+
                     return resolve(otpResponse);
                 }
                 catch(err) {
@@ -587,7 +587,7 @@ class OutboundRequestToPayTransferModel {
         return quote;
     }
 
-    
+
     /**
      * Executes a transfer
      * Starts the transfer process by sending a POST /transfers (prepare) request to the switch;
@@ -886,7 +886,7 @@ class OutboundRequestToPayTransferModel {
     }
 
 
-    
+
 }
 
 

package/src/lib/model/OutboundTransfersModel.js

@@ -277,7 +277,7 @@ class OutboundTransfersModel {
             // a GET /parties request to the switch
             try {
                 const res = await this._requests.getParties(this.data.to.idType, this.data.to.idValue,
-                    this.data.to.idSubValue);
+                    this.data.to.idSubValue, this.data.to.fspId);
                 this._logger.push({ peer: res }).log('Party lookup sent to peer');
             }
             catch(err) {

package/src/lib/model/lib/shared.js

@@ -68,7 +68,7 @@ const mojaloopPartyToInternalParty = (external) => {
         internal.idType = external.partyIdInfo.partyIdType;
         internal.idValue = external.partyIdInfo.partyIdentifier;
         internal.idSubValue = external.partyIdInfo.partySubIdOrType;
-        // Note: we dont map fspid to internal transferParty object
+        internal.fspId = external.partyIdInfo.fspId;
         if(external.partyIdInfo.extensionList){
             internal.extensionList = external.partyIdInfo.extensionList.extension;
         }
@@ -109,6 +109,7 @@ const mojaloopPartyIdInfoToInternalPartyIdInfo = (external) => {
     internal.idType = external.partyIdType;
     internal.idValue = external.partyIdentifier;
     internal.idSubValue = external.partySubIdOrType;
+    internal.fspId = external.fspId;
 
     return internal;
 };
@@ -411,19 +412,19 @@ const mojaloopBulkPrepareToInternalBulkTransfer = (external, bulkQuotes, ilp) =>
     if (bulkQuotes) {
         // create a map of internal individual quotes payees indexed by quotedId, for faster lookup
         const internalQuotesPayeesByQuoteId = {};
-        
+
         for (const quote of bulkQuotes.internalRequest.individualQuotes) {
             internalQuotesPayeesByQuoteId[quote.quoteId] = quote.to;
         }
-        
+
         // create a map of external individual transfers indexed by quotedId, for faster lookup
         const externalTransferIdsByQuoteId = {};
-        
+
         for (const transfer of external.individualTransfers) {
             const transactionObject = ilp.getTransactionObject(transfer.ilpPacket);
             externalTransferIdsByQuoteId[transactionObject.quoteId] = transfer.transferId;
         }
-        
+
         internal = {
             bulkTransferId: external.bulkTransferId,
             bulkQuotes: bulkQuotes.response,

package/test/config/integration.env

@@ -131,3 +131,12 @@ TRANSFERS_ENDPOINT=ml-testing-toolkit:5000
 # The incoming transfer request should consists of an ILP packet and a matching condition in this case.
 # The fulfilment will be generated from the provided ILP packet, and must hash to the provided condition.
 ALLOW_TRANSFER_WITHOUT_QUOTE=false
+
+# Management API websocket connection settings.
+# The Management API uses this for exchanging connector management messages.
+MGMT_API_WS_URL=127.0.0.1
+MGMT_API_WS_PORT=4005
+
+# Set to true to enable the use of PM4ML-related services e.g MCM, Management API service
+# when running the scheme-adapter as a mojaloop connector component within Payment Manager for Mojaloop.
+PM4ML_ENABLED=false