@mojaloop/central-services-shared 18.26.2 → 18.27.0-snapshot.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/central-services-shared",
-  "version": "18.26.2",
+  "version": "18.27.0-snapshot.0",
   "description": "Shared code for mojaloop central services",
   "license": "Apache-2.0",
   "author": "ModusBox",
@@ -43,6 +43,7 @@
     "test": "npm run test:unit",
     "test:header": "npx tape 'test/unit/util/headerValidation/**/*.test.js'",
     "test:logging": "npx tape 'test/unit/util/hapi/plugins/loggingPlugin.test.js'",
+    "test:mysql": "tape 'test/unit/util/mysql/**/*.test.js'",
     "test:trans": "npx tape 'test/unit/util/headers/transformer.test.js'",
     "test:unit": "npx tape 'test/unit/**/*.test.js' | tap-spec",
     "test:xunit": "npx tape 'test/unit/**/**.test.js' | tap-xunit > ./test/results/xunit.xml",
@@ -65,6 +66,8 @@
     "@hapi/joi-date": "2.0.1",
     "@mojaloop/inter-scheme-proxy-cache-lib": "2.5.0",
     "@opentelemetry/api": "1.9.0",
+    "async-exit-hook": "2.0.1",
+    "async-retry": "1.3.3",
     "axios": "1.9.0",
     "clone": "2.1.2",
     "convict": "^6.2.4",
@@ -143,7 +146,9 @@
     "@mojaloop/event-sdk": "14.5.1",
     "ajv": "8.x.x",
     "ajv-formats": "3.x.x",
-    "ajv-keywords": "5.x.x"
+    "ajv-keywords": "5.x.x",
+    "knex": "3.x",
+    "mysql2": "3.x"
   },
   "peerDependenciesMeta": {
     "@mojaloop/central-services-error-handling": {
@@ -163,6 +168,12 @@
     },
     "ajv-keyboards": {
       "optional": false
+    },
+    "knex": {
+      "optional": false
+    },
+    "mysql2": {
+      "optional": false
     }
   },
   "standard": {

package/src/index.d.ts

@@ -1,7 +1,18 @@
 import { Utils as HapiUtil, Server } from '@hapi/hapi'
 import { ILogger } from '@mojaloop/central-services-logger/src/contextLogger'
+import { Knex } from 'knex';
 import IORedis from 'ioredis';
 
+declare class KnexWrapper {
+  constructor(deps: KnexWrapperDeps);
+  knex: Knex;
+  isConnected: boolean;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  executeWithErrorCount(queryFn: Function, operation?: string, step?: string): Promise<unknown>;
+  handleError(error: unknown, operation?: string, step?: string, needRethrow?: boolean): void;
+}
+
 declare namespace CentralServicesShared {
   interface ReturnCode {
     CODE: number;
@@ -422,6 +433,7 @@ declare namespace CentralServicesShared {
   enum AdminNotificationActionsEnum {
     LIMIT_ADJUSTMENT = 'limit-adjustment'
   }
+
   interface Enum {
     Http: HttpEnum;
     EndPoints: EndPointsEnum;
@@ -778,6 +790,9 @@ declare namespace CentralServicesShared {
     StreamingProtocol: StreamingProtocol;
     HeaderValidation: HeaderValidation;
     Redis: Redis;
+    mysql: {
+      KnexWrapper: KnexWrapper
+    };
   }
 
   const Enum: Enum
@@ -785,4 +800,27 @@ declare namespace CentralServicesShared {
   const HealthCheck: any
 }
 
+type KnexWrapperDeps = {
+  knexOptions: Knex.Config;
+  metrics: MetricsClient;
+  logger: ILogger;
+  retryOptions?: RetryConnOptions;
+  context?: string;
+}
+
+type MetricsClient = { // Wrapper for prom-client from @mojaloop/central-services-metrics
+  getCounter(name: string): {
+    inc(details: Record<string, unknown>): void;
+  };
+}
+
+interface RetryConnOptions { // see opts from https://www.npmjs.com/package/async-retry#api
+  retries?: number;
+  factor?: number;
+  minTimeout?: number;
+  maxTimeout?: number;
+  randomize?: boolean;
+  onRetry?: (error: Error) => void;
+}
+
 export = CentralServicesShared

package/src/util/mysql/KnexWrapper.js

@@ -0,0 +1,146 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+/* istanbul ignore file */
+// todo: improve test coverage
+
+const knex = require('knex')
+const retry = require('async-retry')
+const exitHook = require('async-exit-hook')
+
+const defaultRetryOptionsDto = (logger) => ({
+  retries: 10,
+  minTimeout: 1000,
+  factor: 2,
+  onRetry: (err) => { logger.info('Database connection attempt: ', err) }
+})
+
+/**
+ * @typedef {Object} KnexWrapperDeps
+ * @prop {Object} knexOptions - Configuration for
+ * @prop {Object} [retryOptions] - Configuration for async-retry package
+ * @prop {Metrics} metrics - Wrapper for prom-client from @mojaloop/central-services-metrics
+ * @prop {ILogger} logger - Logger instance
+ * @prop {string} [context] - Context string for errorCunter
+ */
+
+class KnexWrapper {
+  #isConnected = false
+
+  /** @param {KnexWrapperDeps} deps */
+  constructor (deps) {
+    this.knex = knex(deps.knexOptions)
+    this.metrics = deps.metrics
+    this.log = deps.logger.child({ component: this.constructor.name })
+    this.retryOptions = Object.assign(defaultRetryOptionsDto(this.log), deps.retryOptions)
+    this.context = deps.context || 'Knex'
+  }
+
+  get isConnected () { return this.#isConnected }
+
+  async connect () {
+    try {
+      const opts = this.retryOptions
+      await retry(async (_, attempt) => {
+        this.log.verbose(`Attempting database connection. Attempt ${attempt} of ${opts.retries + 1}`)
+        await this.knex.raw('SELECT 1')
+        exitHook(callback => {
+          this.knex.destroy().finally(callback)
+        })
+        this.#isConnected = true
+        this.log.info('Database connected')
+      }, opts)
+    } catch (err) {
+      this.log.error('error connecting to DB: ', err)
+      this.handleError(err, 'connect')
+    }
+  }
+
+  async disconnect () {
+    await this.knex.destroy()
+    this.#isConnected = false
+    this.log.info('Database disconnected')
+  }
+
+  async executeWithErrorCount (queryFn, operation = queryFn.name || 'runQuery', step = '') {
+    try {
+      if (!this.isConnected) this.log.warn('Database is not connected')
+      const result = await queryFn(this.knex)
+      this.log.debug('executeWithErrorCount is done: ', { result })
+      return result
+    } catch (err) {
+      this.log.error('error in executeWithErrorCount: ', err)
+      this.handleError(err, operation, step)
+    }
+  }
+
+  handleError (error, operation, step = '', needRethrow = true) {
+    const code = this.#defineErrorCode(error)
+    this.#incrementErrorCounter({ code, operation, step })
+    if (needRethrow) throw error
+    else return null
+  }
+
+  #defineErrorCode (error) {
+    if (error instanceof knex.KnexTimeoutError) {
+      return 'conn_timeout'
+    }
+    if (error.code === 'ECONNREFUSED') {
+      return 'conn_failed'
+    }
+    if (error.code === 'ER_LOCK_DEADLOCK') {
+      return 'deadlock'
+    }
+    if (error.code === 'ER_DUP_ENTRY') {
+      return 'dup_entry'
+    }
+    if (!this.isConnected) {
+      return 'not_connected'
+    }
+    return 'unknown_db_error'
+  }
+
+  #incrementErrorCounter ({ code, operation = 'db_query', step = '' }) {
+    const { log, context } = this
+    try {
+      const errorCounter = this.metrics.getCounter('errorCount')
+      const errDetails = {
+        system: 'mysql',
+        code,
+        context,
+        operation,
+        ...(step && { step })
+      }
+      errorCounter.inc(errDetails)
+      log.info('incrementErrorCounter is called:', { errDetails })
+    } catch (error) {
+      log.warn('error in incrementErrorCounter: ', error)
+    }
+  }
+}
+
+module.exports = KnexWrapper

package/src/util/mysql/index.js

@@ -0,0 +1,32 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const KnexWrapper = require('./KnexWrapper')
+
+module.exports = {
+  KnexWrapper
+}

package/test/unit/util/mysql/KnexWrapper.test.js

@@ -0,0 +1,74 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const Tape = require('tapes')(require('tape'))
+// const sinon = require('sinon')
+
+const { KnexWrapper } = require('#src/util/mysql/index')
+const { logger } = require('#src/logger')
+const { tryCatchEndTest } = require('#test/util/helper')
+
+const mockDeps = ({
+  knexOptions = mockKnexOptions(),
+  retryOptions = mockRetryOptions(),
+  metrics = {
+    getCounter: () => ({
+      inc: () => {} // todo: use stub
+    })
+  },
+  context = 'testKnexWrapper'
+} = {}) => ({
+  logger,
+  knexOptions,
+  metrics,
+  retryOptions,
+  context
+})
+
+const mockKnexOptions = () => ({
+  client: 'mysql2',
+  connection: {
+    host: '127.0.0.1',
+    user: 'root',
+    password: '<PASSWORD>',
+    database: 'test'
+  }
+})
+
+const mockRetryOptions = ({
+  retries = 1,
+  minTimeout = 100
+} = {}) => ({ retries, minTimeout })
+
+Tape('KnexWrapper Tests -->', (wrapperTests) => {
+  wrapperTests.test('should create an instance', tryCatchEndTest(t => {
+    const wrapper = new KnexWrapper(mockDeps())
+    t.false(wrapper.isConnected, 'wrapper is not connected')
+  }))
+
+  wrapperTests.end()
+})