@mojaloop/sdk-scheme-adapter 24.14.0 → 24.15.1

package/modules/api-svc/src/index.js

@@ -27,20 +27,11 @@
 'use strict';
 
 const { hostname } = require('node:os');
-const EventEmitter = require('node:events');
-const http = require('http');
-const https = require('https');
-const _ = require('lodash');
+const { merge } = require('lodash');
 const { name, version } = require('../../../package.json');
 
+const SdkServer = require('./SdkServer');
 const config = require('./config');
-const InboundServer = require('./InboundServer');
-const OutboundServer = require('./OutboundServer');
-const OAuthTestServer = require('./OAuthTestServer');
-const { BackendEventHandler } = require('./BackendEventHandler');
-const { FSPIOPEventHandler } = require('./FSPIOPEventHandler');
-const { MetricsServer, MetricsClient } = require('./lib/metrics');
-const TestServer = require('./TestServer');
 const ControlAgent = require('./ControlAgent');
 
 // import things we want to expose e.g. for unit tests and users who dont want to use the entire
@@ -51,531 +42,19 @@ const Router = require('./lib/router');
 const Validate = require('./lib/validate');
 const Cache = require('./lib/cache');
 const { SDKStateEnum } = require('./lib/model/common');
-const { createAuthClient } = require('./lib/utils');
 const { logger } = require('./lib/logger');
 
-const PING_INTERVAL_MS = 30_000;
-
-const createCache = (config) => new Cache({
-    logger,
-    cacheUrl: config.cacheUrl,
-    enableTestFeatures: config.enableTestFeatures,
-    subscribeTimeoutSeconds:  config.requestProcessingTimeoutSeconds,
-});
-
-/**
- * Class that creates and manages http servers that expose the scheme adapter APIs.
- */
-class Server extends EventEmitter {
-    constructor(conf, logger) {
-        super({ captureExceptions: true });
-        this.conf = conf;
-        this.logger = logger;
-        this.cache = createCache(conf);
-
-        this.metricsClient = new MetricsClient();
-        this.metricsServer = new MetricsServer({
-            port: this.conf.metrics.port,
-            logger: this.logger
-        });
-
-        // Create shared Mojaloop agents for switch communication (used by both servers)
-        this.mojaloopSharedAgents = this._createMojaloopSharedAgents(this.conf);
-
-        this.oidc = createAuthClient(conf, logger);
-        this.oidc.auth.on('error', (msg) => {
-            this.emit('error', 'OIDC auth error in InboundApi', msg);
-        });
-
-        this.inboundServer = new InboundServer(
-            this.conf,
-            this.logger,
-            this.cache,
-            this.oidc,
-            this.mojaloopSharedAgents,
-        );
-        this.inboundServer.on('error', (...args) => {
-            this.logger.isErrorEnabled && this.logger.push({ args }).error('Unhandled error in Inbound Server');
-            this.emit('error', 'Unhandled error in Inbound Server');
-        });
-
-        this.outboundServer = new OutboundServer(
-            this.conf,
-            this.logger,
-            this.cache,
-            this.metricsClient,
-            this.oidc,
-            this.mojaloopSharedAgents,
-        );
-        this.outboundServer.on('error', (...args) => {
-            this.logger.isErrorEnabled && this.logger.push({ args }).error('Unhandled error in Outbound Server');
-            this.emit('error', 'Unhandled error in Outbound Server');
-        });
-
-        if (this.conf.oauthTestServer.enabled) {
-            this.oauthTestServer = new OAuthTestServer({
-                clientKey: this.conf.oauthTestServer.clientKey,
-                clientSecret: this.conf.oauthTestServer.clientSecret,
-                port: this.conf.oauthTestServer.listenPort,
-                logger: this.logger,
-            });
-        }
-
-        if (this.conf.enableTestFeatures) {
-            this.testServer = new TestServer({
-                config: this.conf,
-                port: this.conf.test.port,
-                logger: this.logger,
-                cache: this.cache,
-            });
-        }
-
-        if (this.conf.backendEventHandler.enabled) {
-            this.backendEventHandler = new BackendEventHandler({
-                config: this.conf,
-                logger: this.logger,
-            });
-        }
-
-        if (this.conf.fspiopEventHandler.enabled) {
-            this.fspiopEventHandler = new FSPIOPEventHandler({
-                config: this.conf,
-                logger: this.logger,
-                cache: this.cache,
-                oidc: this.oidc,
-            });
-        }
-    }
-
-    _shouldUpdateInboundServer(newConf) {
-        const isInboundDifferent = !_.isEqual(this.conf.inbound, newConf.inbound);
-        const isOutboundDifferent = !_.isEqual(this.conf.outbound, newConf.outbound);
-        const isPeerJWSKeysDifferent = !_.isEqual(this.conf.peerJWSKeys, newConf.peerJWSKeys);
-        const isJwsSigningKeyDifferent = !_.isEqual(this.conf.jwsSigningKey, newConf.jwsSigningKey);
-
-        if (isInboundDifferent) {
-            this.logger.debug('Inbound config is different', {
-                oldInbound: this.conf.inbound,
-                newInbound: newConf.inbound
-            });
-        }
-        if (isOutboundDifferent) {
-            this.logger.debug('Outbound config is different (checked in inbound update)', {
-                oldOutbound: this.conf.outbound,
-                newOutbound: newConf.outbound
-            });
-        }
-
-        if (isPeerJWSKeysDifferent) {
-            this.logger.debug('Peer JWS Keys config is different', {
-                oldPeerJWSKeys: this.conf.peerJWSKeys,
-                newPeerJWSKeys: newConf.peerJWSKeys
-            });
-        }
-
-        if (isJwsSigningKeyDifferent) {
-            this.logger.debug('JWS Signing Key config is different', {
-                oldJwsSigningKey: this.conf.jwsSigningKey,
-                newJwsSigningKey: newConf.jwsSigningKey
-            });
-        }
-
-        return isInboundDifferent || isOutboundDifferent || isPeerJWSKeysDifferent || isJwsSigningKeyDifferent;
-    }
-
-    _shouldUpdateOutboundServer(newConf) {
-        const isOutboundDifferent = !_.isEqual(this.conf.outbound, newConf.outbound);
-        const isJwsSigningKeyDifferent = !_.isEqual(this.conf.jwsSigningKey, newConf.jwsSigningKey);
-
-        if (isOutboundDifferent) {
-            this.logger.debug('Outbound config is different', {
-                oldOutbound: this.conf.outbound,
-                newOutbound: newConf.outbound
-            });
-        }
-
-        if (isJwsSigningKeyDifferent) {
-            this.logger.debug('JWS Signing Key config is different', {
-                oldJwsSigningKey: this.conf.jwsSigningKey,
-                newJwsSigningKey: newConf.jwsSigningKey
-            });
-        }
-
-        return isOutboundDifferent || isJwsSigningKeyDifferent;
-    }
-
-    /**
-     * Starts periodic polling of Management API for configuration updates.
-     * Only runs if PM4ML enabled and a polling interval configured.
-     */
-    _startConfigPolling() {
-        if (!this.conf.pm4mlEnabled || !this.conf.control.mgmtAPIPollIntervalMs) {
-            this.logger.info('No failsafe config polling configured');
-            return;
-        }
-
-        this.logger.info('starting failsafe config polling from Management API...', { intervalMs: this.conf.control.mgmtAPIPollIntervalMs });
-
-        this._configPollInterval = setInterval(
-            () => this._pollConfigFromMgmtAPI(),
-            this.conf.control.mgmtAPIPollIntervalMs
-        );
-
-        // Unref so it doesn't prevent process exit
-        this._configPollInterval.unref();
-    }
-
-    /**
-     * Polls Management API for configuration updates.
-     * Reuses the existing persistent WebSocket client (this.controlClient).
-     * Skips polling if:
-     * - Another config update is in progress
-     * - WebSocket client is not connected
-     */
-    async _pollConfigFromMgmtAPI() {
-        // Race condition prevention: skip if restart in progress
-        if (this._configUpdateInProgress) {
-            this.logger.info('config updating already in progress, skipping poll');
-            return;
-        }
-
-        // WebSocket readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED
-        if (this.controlClient?.readyState !== 1) {
-            this.logger.warn('Control client not ready (not OPEN), skipping poll', { readyState: this.controlClient?.readyState });
-            return;
-        }
-
-        try {
-            const newConfig = await this.controlClient.getUpdatedConfig();
-            if (!newConfig) {
-                this.logger.warn('No config received from polling');
-                return;
-            }
-            this.logger.info('polling config from mgmt-api is done, checking if SDK server restart needed...');
-
-            const mergedConfig = _.merge({}, this.conf, newConfig);
-            await this.restart(mergedConfig, { source: 'polling' });
-        } catch (err) {
-            this.logger.error('error in polling config from Management API: ', err);
-        }
-    }
-
-    /** Stops the config polling interval. */
-    _stopConfigPolling() {
-        if (this._configPollInterval) {
-            this.logger.verbose('stopping config polling');
-            clearInterval(this._configPollInterval);
-            this._configPollInterval = null;
-        }
-    }
-
-    async start() {
-        await this.cache.connect();
-        await this.oidc.auth.start();
-
-        // We only start the control client if we're running within Mojaloop Payment Manager.
-        // The control server is the Payment Manager Management API Service.
-        // We only start the client to connect to and listen to the Management API service for
-        // management protocol messages e.g configuration changes, certificate updates etc.
-        if (this.conf.pm4mlEnabled) {
-            const RESTART_INTERVAL_MS = 10000;
-            this.controlClient = await ControlAgent.createConnectedControlAgentWs(this.conf, this.logger);
-            this.controlClient.on(ControlAgent.EVENT.RECONFIGURE, this.restart.bind(this));
-
-            const schedulePing = () => {
-                clearTimeout(this.pingTimeout);
-                this.pingTimeout = setTimeout(() => {
-                    this.logger.error('Ping timeout, possible broken connection. Restarting server...');
-                    this.restart(_.merge({}, this.conf, {
-                        control: { stopped: Date.now() }
-                    }));
-                }, PING_INTERVAL_MS + this.conf.control.mgmtAPILatencyAssumption);
-            };
-
-            this.controlClient.on('ping', () => {
-                this.logger.debug('Received ping from control server');
-                schedulePing();
-            });
-
-            this.controlClient.on('close', () => {
-                clearTimeout(this.pingTimeout);
-                setTimeout(() => {
-                    this.logger.debug('Control client closed. Restarting server...');
-                    this.restart(_.merge({}, this.conf, {
-                        control: { stopped: Date.now() }
-                    }));
-                }, RESTART_INTERVAL_MS);
-            });
-
-            schedulePing();
-            this._startConfigPolling();
-        }
-
-        await Promise.all([
-            this.inboundServer.start(),
-            this.outboundServer.start(),
-            this.metricsServer.start(),
-            this.testServer?.start(),
-            this.oauthTestServer?.start(),
-            this.backendEventHandler?.start(),
-            this.fspiopEventHandler?.start(),
-        ]);
-    }
-
-    async restart(newConf, options = {}) {
-        const source = options.source || 'websocket'; // Track source of restart call - websocket or polling
-
-        // Race condition prevention
-        if (this._configUpdateInProgress) {
-            this.logger.info('restart already in progress, skipping', { source });
-            return;
-        }
-
-        const restartActionsTaken = {};
-        this.logger.debug('Server is restarting...', { source });
-        this._configUpdateInProgress = true;
-
-        try {
-            let oldCache;
-            const updateCache = !_.isEqual(this.conf.cacheUrl, newConf.cacheUrl)
-            || !_.isEqual(this.conf.enableTestFeatures, newConf.enableTestFeatures);
-            if (updateCache) {
-                oldCache = this.cache;
-                await this.cache.disconnect();
-                this.cache = createCache(newConf);
-                await this.cache.connect();
-                restartActionsTaken.updateCache = true;
-            }
-
-            const updateOIDC = !_.isEqual(this.conf.oidc, newConf.oidc)
-            || !_.isEqual(this.conf.outbound.tls, newConf.outbound.tls);
-            if (updateOIDC) {
-                this.oidc.auth.stop();
-                this.oidc = createAuthClient(newConf, this.logger);
-                this.oidc.auth.on('error', (msg) => {
-                    this.emit('error', 'OIDC auth error in InboundApi', msg);
-                });
-                await this.oidc.auth.start();
-                restartActionsTaken.updateOIDC = true;
-            }
-
-            this.logger.isDebugEnabled && this.logger.push({ oldConf: this.conf.inbound, newConf: newConf.inbound }).debug('Inbound server configuration');
-            const updateInboundServer = this._shouldUpdateInboundServer(newConf);
-            if (updateInboundServer) {
-                const stopStartLabel = 'InboundServer stop/start duration';
-                // eslint-disable-next-line no-console
-                console.time(stopStartLabel); // todo: remove console.time
-                await this.inboundServer.stop();
-
-                this.mojaloopSharedAgents = this._createMojaloopSharedAgents(newConf);
-                this.inboundServer = new InboundServer(
-                    newConf,
-                    this.logger,
-                    this.cache,
-                    this.oidc,
-                    this.mojaloopSharedAgents,
-                );
-                this.inboundServer.on('error', (...args) => {
-                    const errMessage = 'Unhandled error in Inbound Server';
-                    this.logger.push({ args }).error(errMessage);
-                    this.emit('error', errMessage);
-                });
-                await this.inboundServer.start();
-                // eslint-disable-next-line no-console
-                console.timeEnd(stopStartLabel);
-                restartActionsTaken.updateInboundServer = true;
-            }
-
-            this.logger.isDebugEnabled && this.logger.push({ oldConf: this.conf.outbound, newConf: newConf.outbound }).debug('Outbound server configuration');
-            const updateOutboundServer = this._shouldUpdateOutboundServer(newConf);
-            if (updateOutboundServer) {
-                const stopStartLabel = 'OutboundServer stop/start duration';
-                // eslint-disable-next-line no-console
-                console.time(stopStartLabel);
-                await this.outboundServer.stop();
-
-                this.mojaloopSharedAgents = this._createMojaloopSharedAgents(newConf);
-                this.outboundServer = new OutboundServer(
-                    newConf,
-                    this.logger,
-                    this.cache,
-                    this.metricsClient,
-                    this.oidc,
-                    this.mojaloopSharedAgents,
-                );
-                this.outboundServer.on('error', (...args) => {
-                    const errMessage = 'Unhandled error in Outbound Server';
-                    this.logger.push({ args }).error(errMessage);
-                    this.emit('error', errMessage);
-                });
-                await this.outboundServer.start();
-                // eslint-disable-next-line no-console
-                console.timeEnd(stopStartLabel);
-                restartActionsTaken.updateOutboundServer = true;
-            }
-
-            const updateFspiopEventHandler = !_.isEqual(this.conf.outbound, newConf.outbound)
-            && this.conf.fspiopEventHandler.enabled;
-            if (updateFspiopEventHandler) {
-                await this.fspiopEventHandler.stop();
-                this.fspiopEventHandler = new FSPIOPEventHandler({
-                    config: newConf,
-                    logger: this.logger,
-                    cache: this.cache,
-                    oidc: this.oidc,
-                });
-                await this.fspiopEventHandler.start();
-                restartActionsTaken.updateFspiopEventHandler = true;
-            }
-
-            const updateControlClient = !_.isEqual(this.conf.control, newConf.control);
-            if (updateControlClient) {
-                await this.controlClient?.stop();
-                if (this.conf.pm4mlEnabled) {
-                    const RESTART_INTERVAL_MS = 10000;
-
-                    const schedulePing = () => {
-                        clearTimeout(this.pingTimeout);
-                        this.pingTimeout = setTimeout(() => {
-                            this.logger.error('Ping timeout, possible broken connection. Restarting server...');
-                            this.restart(_.merge({}, newConf, {
-                                control: { stopped: Date.now() }
-                            }));
-                        }, PING_INTERVAL_MS + this.conf.control.mgmtAPILatencyAssumption);
-                    };
-
-                    schedulePing();
-
-                    this.controlClient = await ControlAgent.createConnectedControlAgentWs(newConf, this.logger);
-                    this.controlClient.on(ControlAgent.EVENT.RECONFIGURE, this.restart.bind(this));
-
-                    this.controlClient.on('ping', () => {
-                        this.logger.debug('Received ping from control server');
-                        schedulePing();
-                    });
-
-                    this.controlClient.on('close', () => {
-                        clearTimeout(this.pingTimeout);
-                        setTimeout(() => {
-                            this.logger.debug('Control client closed. Restarting server...');
-                            this.restart(_.merge({}, newConf, {
-                                control: { stopped: Date.now() }
-                            }));
-                        }, RESTART_INTERVAL_MS);
-                    });
-
-                    restartActionsTaken.updateControlClient = true;
-                }
-            }
-
-            const updateOAuthTestServer = !_.isEqual(newConf.oauthTestServer, this.conf.oauthTestServer);
-            if (updateOAuthTestServer) {
-                await this.oauthTestServer?.stop();
-                if (this.conf.oauthTestServer.enabled) {
-                    this.oauthTestServer = new OAuthTestServer({
-                        clientKey: newConf.oauthTestServer.clientKey,
-                        clientSecret: newConf.oauthTestServer.clientSecret,
-                        port: newConf.oauthTestServer.listenPort,
-                        logger: this.logger,
-                    });
-                    await this.oauthTestServer.start();
-                    restartActionsTaken.updateOAuthTestServer = true;
-                }
-            }
-
-            const updateTestServer = !_.isEqual(newConf.test.port, this.conf.test.port);
-            if (updateTestServer) {
-                await this.testServer?.stop();
-                if (this.conf.enableTestFeatures) {
-                    this.testServer = new TestServer({
-                        port: newConf.test.port,
-                        logger: this.logger,
-                        cache: this.cache,
-                    });
-                    await this.testServer.start();
-                    restartActionsTaken.updateTestServer = true;
-                }
-            }
-
-            this.conf = newConf;
-
-            await oldCache?.disconnect();
-
-            if (Object.keys(restartActionsTaken).length > 0) {
-                this.logger.info('Server is restarted', { restartActionsTaken, source });
-            } else {
-                this.logger.verbose('Server not restarted, no config changes detected', { source });
-            }
-        } catch (err) {
-            this.logger.error('error in Server restart: ', err);
-        } finally {
-            this._configUpdateInProgress = false;
-        }
-    }
-
-    stop() {
-        this._stopConfigPolling();
-
-        clearTimeout(this.pingTimeout);
-        this.oidc.auth.stop();
-        this.controlClient?.removeAllListeners();
-        this.inboundServer.removeAllListeners();
-        return Promise.all([
-            this.cache.disconnect(),
-            this.inboundServer.stop(),
-            this.outboundServer.stop(),
-            this.metricsServer.stop(),
-            this.oauthTestServer?.stop(),
-            this.testServer?.stop(),
-            this.controlClient?.stop(),
-            this.backendEventHandler?.stop(),
-            this.fspiopEventHandler?.stop(),
-        ]);
-    }
-
-    _createMojaloopSharedAgents(conf) {
-        const httpAgent = new http.Agent({
-            keepAlive: true,
-            maxSockets: conf.outbound?.maxSockets || 256,
-        });
-
-        // Create HTTPS agent based on TLS configuration for Mojaloop switch communication
-        const httpsAgentOptions = {
-            keepAlive: true,
-            maxSockets: conf.outbound?.maxSockets || 256,
-        };
-
-        // Apply TLS configuration if mTLS is enabled for switch communication
-        if (conf.outbound?.tls?.mutualTLS?.enabled && conf.outbound?.tls?.creds) {
-            Object.assign(httpsAgentOptions, conf.outbound.tls.creds);
-        }
-
-        const httpsAgent = new https.Agent(httpsAgentOptions);
-
-        // Prevent accidental logging of agent internals
-        httpAgent.toJSON = () => ({ type: 'HttpAgent', keepAlive: httpAgent.keepAlive });
-        httpsAgent.toJSON = () => ({ type: 'HttpsAgent', keepAlive: httpsAgent.keepAlive });
-
-        this.logger.isInfoEnabled && this.logger.info('Created shared HTTP and HTTPS agents for Mojaloop switch communication');
-
-        return {
-            httpAgent,
-            httpsAgent
-        };
-    }
-}
-
-async function start(config) {
-    if (config.pm4mlEnabled) {
-        const controlClient = await ControlAgent.createConnectedControlAgentWs(config, logger);
+async function start(conf) {
+    if (conf.pm4mlEnabled) {
+        const controlClient = await ControlAgent.createConnectedControlAgentWs(conf, logger);
         const updatedConfigFromMgmtAPI = await controlClient.getUpdatedConfig();
-        _.merge(config, updatedConfigFromMgmtAPI);
+        merge(conf, updatedConfigFromMgmtAPI);
         controlClient.terminate();
         // todo: - clarify, why do we need to terminate the client? (use .stop() method?)
         //       - can we use persistent ws controlClient from Server? (why do we need to establish a brand new ws connection here?)
     }
 
-    const svr = new Server(config, logger);
+    const svr = new SdkServer(conf, logger);
     svr.on('error', (err) => {
         logger.error('Unhandled server error: ', err);
         process.exit(2);
@@ -611,7 +90,7 @@ module.exports = {
     InboundServerMiddleware,
     OutboundServerMiddleware,
     Router,
-    Server,
+    Server: SdkServer,
     Validate,
     SDKStateEnum,
     start,

package/modules/api-svc/src/lib/model/OutboundTransfersModel.js

@@ -76,6 +76,7 @@ class OutboundTransfersModel {
         this._sendFinalNotificationIfRequested = config.sendFinalNotificationIfRequested;
         this._apiType = config.apiType;
         this._supportedCurrencies = config.supportedCurrencies;
+        this._traceFlags = config.traceFlags;
 
         if (this._autoAcceptParty && this._multiplePartiesResponse) {
             throw new Error('Conflicting config options provided: autoAcceptParty and multiplePartiesResponse');
@@ -1512,7 +1513,7 @@ class OutboundTransfersModel {
 
     #createOtelHeaders() {
         return Object.freeze({
-            traceparent: generateTraceparent(this.data.traceId),
+            traceparent: generateTraceparent(this.data.traceId, this._traceFlags),
         });
     }
 }

package/modules/api-svc/src/lib/utils.js

@@ -63,14 +63,38 @@ const transformHeadersIsoToFspiop = (isoHeaders) => {
     return fspiopHeaders;
 };
 
-const generateTraceparent = (traceId = randomBytes(16).toString('hex')) => {
+/**
+ * Validates trace flags according to W3C Trace Context specification
+ * @param {string} flags - The trace flags to validate
+ * @returns {boolean} - True if valid, false otherwise
+ */
+const isValidTraceFlags = (flags) => {
+    // Must be exactly 2 characters
+    if (typeof flags !== 'string' || flags.length !== 2) {
+        return false;
+    }
+    // Must be valid hex characters (0-9, a-f, A-F)
+    return /^[0-9a-fA-F]{2}$/.test(flags);
+};
+
+/**
+ * Generates a W3C Trace Context compliant traceparent header
+ * @param {string} [traceId] - Optional 32-character hex trace ID
+ * @param {string} [traceFlags='01'] - Optional 2-character hex trace flags (defaults to '01' - sampled)
+ * @returns {string} - The traceparent header value in format: version-traceId-spanId-flags
+ * @throws {Error} - If traceFlags is invalid according to W3C specification
+ */
+const generateTraceparent = (traceId = randomBytes(16).toString('hex'), traceFlags = '01') => {
+    if (!isValidTraceFlags(traceFlags)) {
+        throw new Error(`Invalid trace flags: '${traceFlags}'. Must be a two-character hex string (00-ff).`);
+    }
     const spanId = randomBytes(8).toString('hex');
-    const flags = '01';
-    return `00-${traceId}-${spanId}-${flags}`;
+    return `00-${traceId}-${spanId}-${traceFlags.toLowerCase()}`;
 };
 
 module.exports = {
     createAuthClient,
     generateTraceparent,
+    isValidTraceFlags,
     transformHeadersIsoToFspiop
 };