@mojaloop/central-ledger 19.14.0 → 20.1.0

package/src/testing/types.ts

@@ -0,0 +1,95 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2026 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>.
+
+ * TigerBeetle
+ - Lewis Daly <lewis@tigerbeetle.com>
+ --------------
+
+ ******/
+
+export type TagTask = 'TEST_UNIT' | 'TEST_COVERAGE' | 'TEST_FUNCTIONAL' | 'TEST_INTEGRATION'
+
+export type RunTask = {
+  tag: 'TEST_UNIT',
+  type: 'TAPE' | 'NATIVE' | 'BOTH',
+  output: 'DEFAULT' | 'XUNIT',
+  /* If set, will write the output to this file. */
+  outputPath?: string
+} | {
+  tag: 'TEST_COVERAGE',
+  type: 'TAPE' | 'NATIVE' | 'BOTH',
+  onlyReport: boolean
+} | {
+  tag: 'TEST_INTEGRATION',
+}
+
+export type RunTaskUnit = Extract<RunTask, { tag: 'TEST_UNIT' }>
+export type RunTaskCoverage = Extract<RunTask, { tag: 'TEST_COVERAGE' }>
+export type RunTaskIntegration = Extract<RunTask, { tag: 'TEST_INTEGRATION' }>
+
+export type ResultTest = {
+  output: string,
+
+  /**
+   * `null` if the process exited early.
+   */
+  exitCode: number | null
+}
+
+/**
+ * Parsed TAP test result
+ */
+export interface TapTest {
+  /** Test number in the sequence. */
+  number: number
+  /** Whether the test passed. */
+  ok: boolean
+  /** Test description. */
+  description: string
+  /** Directive. */
+  directive?: string
+}
+
+/**
+ * Parsed TAP stream
+ */
+export interface ParsedTap {
+  /** TAP version. */
+  version?: number
+  /** Test plan (1..N). */
+  plan: { start: number; end: number } | null
+  /** Individual test results. */
+  tests: TapTest[]
+  /** Whether all tests passed. */
+  ok: boolean
+  /** Total test count. */
+  total: number
+  /** Number of passing tests. */
+  pass: number
+  /** Number of failing tests. */
+  fail: number
+  /** Number of skipped tests. */
+  skip: number
+  /** Number of not implemented tests. */
+  todo: number
+}
+
+

package/src/testing/util.ts

@@ -0,0 +1,333 @@
+
+import assert from 'node:assert'
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { createServer } from 'node:net';
+import { Request, ReqRefDefaults } from '@hapi/hapi';
+import { Snapshot } from './snapshot';
+
+export const PROJECT_ROOT = path.resolve(__dirname, '../..')
+
+export const TAP_XUNIT_BIN = path.join(PROJECT_ROOT, 'node_modules/.bin/tap-xunit')
+/**
+ * @function enumeratePaths
+ * @description Iterate through a nested object and return the paths as a list of `|` delimited path
+ *   strings.
+ * @example
+ *  
+ * enumeratePaths({a:{b:{c: 123}}}) => ['a', 'a|b', 'a|b|c']
+ */
+export function enumeratePaths(input: any): Array<string> {
+  const paths: Array<string> = []
+  const _enumerateNode = (input: any, path: string) => {
+    if (input === null || input === undefined) {
+      paths.push(path.replace(/\|$/, ''))
+      return
+    }
+    if (typeof input === 'string'
+      || typeof input === 'number'
+      || typeof input === 'boolean'
+      || typeof input === 'bigint'
+    ) {
+      paths.push(path.replace(/\|$/, ''))
+      return
+    }
+
+    assert(typeof input === 'object')
+
+    for (const leaf of Object.keys(input)) {
+      const node = input[leaf]
+      paths.push(path.replace(/\|$/, ''))
+      _enumerateNode(node, `${path}${leaf}|`)
+    }
+    return []
+  }
+
+  _enumerateNode(input, '')
+
+  // Deduplicate the intermediate paths.
+  return Object.keys(paths.reduce((acc: Record<string, true>, curr) => {
+    if (curr === '') return acc
+    acc[curr] = true
+    return acc
+  }, {}))
+}
+
+/**
+ * @function deleteAtPath
+ * @description Delete an element from a complex object. Replaces the object in place.
+ * @param path: `|` delimited path string
+ */
+export function deleteAtPath(input: any, path: string): void {
+  const pathComponents = path.split('|')
+  assert(pathComponents.length > 0)
+  for (let pathComponent of pathComponents) {
+    if (pathComponent === pathComponents.at(-1)) {
+      delete input[pathComponent]
+      return
+    }
+    input = input[pathComponent]
+  }
+}
+
+/**
+ * @function replaceAtPath
+ * @description Replace an element with a new value from a complex object. Replaces the object in 
+ *  place.
+ * @param path: `|` delimited path string
+ */
+export function replaceAtPath(input: any, path: string, newValue: any): void {
+  const pathComponents = path.split('|')
+  assert(pathComponents.length > 0)
+  for (let pathComponent of pathComponents) {
+    if (pathComponent === pathComponents.at(-1)) {
+      input[pathComponent] = newValue
+      return
+    }
+    input = input[pathComponent]
+  }
+}
+
+/**
+ * @function findFiles
+ * @description Find all files matching a glob pattern.
+ */
+export function findFiles(baseDir: string, pattern: string): string[] {
+  const results: string[] = []
+
+  // Convert glob pattern to regex.
+  const regexPattern = pattern
+    .replaceAll('.', String.raw`\.`)
+    .replaceAll('**', '{{DOUBLESTAR}}')
+    .replaceAll('*', String.raw`[^/]*`)
+    .replaceAll('{{DOUBLESTAR}}', '.*')
+
+  const regex = new RegExp(`^${regexPattern}$`)
+
+  function walkDir(dir: string, relativePath: string = '') {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name)
+        const relPath = relativePath ? `${relativePath}/${entry.name}` : entry.name
+
+        if (entry.isDirectory()) {
+          if (entry.name !== 'node_modules' && entry.name !== '.git') {
+            walkDir(fullPath, relPath)
+          }
+        } else if (entry.isFile()) {
+          if (regex.test(relPath)) {
+            results.push(relPath)
+          }
+        }
+      }
+    } catch (err: any) {
+      // Ignore permission errors.
+      console.error('findFiles() - ignoring err', err.message)
+    }
+  }
+
+  walkDir(baseDir)
+  return results
+}
+
+/**
+ * @function convertToXunit
+ * @description Convert TAP output to xunit XML format.
+ */
+export async function convertToXunit(output: string, outputFile: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(TAP_XUNIT_BIN, [], {
+      cwd: PROJECT_ROOT,
+      stdio: ['pipe', 'pipe', 'pipe']
+    })
+
+    let xml = ''
+    let stderr = ''
+
+    proc.stdout.on('data', (data: Buffer) => {
+      xml += data.toString()
+    })
+
+    proc.stderr.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    proc.on('close', (code) => {
+      if (code !== 0 || !xml) {
+        console.warn('Warning: Could not generate xunit report:', stderr)
+        reject(stderr)
+        return
+      }
+      // Ensure directory exists.
+      const dir = path.dirname(outputFile)
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+      fs.writeFileSync(outputFile, xml)
+      console.log(`\nXUnit report written to: ${outputFile}`)
+      resolve()
+    })
+
+    proc.on('error', () => {
+      console.warn('Warning: tap-xunit not available')
+      resolve()
+    })
+
+    proc.stdin.write(output)
+    proc.stdin.end()
+  })
+}
+
+/**
+ * @function randomAvailablePort
+ * @description Finds a randomly available port by quickly running a server and stopping a server
+ *   on port 0.
+ */
+export async function randomAvailablePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0)
+    server.on('listening', () => {
+      try {
+        const address = server.address() as unknown as { port: number }
+        assert.equal(typeof address, 'object')
+        assert(address.port)
+
+        server.close(() => {
+          resolve(address.port);
+        });
+      } catch (err) {
+        reject(err)
+      }
+    })
+
+    server.on('error', (err) => {
+      reject(err)
+    });
+  });
+}
+
+/** 
+ * @description A hacky method to sleep in JS. For testing purposes only.
+ */
+export async function sleepSeconds(seconds: number) {
+  return new Promise(resolve => setTimeout(resolve, seconds * 1000))
+}
+
+/**
+ * @function createRequest
+ *
+ * @description Create a mock hapi request handler
+ */
+export const createRequest = (
+  { payload, params, query }: { payload: any, params: any, query: any }
+): Request<ReqRefDefaults> => {
+  const requestPayload = payload || {}
+  const requestParams = params || {}
+  const requestQuery = query || {}
+
+  const mock = {
+    payload: requestPayload,
+    params: requestParams,
+    query: requestQuery,
+    server: {
+      log: () => { },
+      methods: {}
+    }
+  } as unknown as Request<ReqRefDefaults>
+
+  return mock
+}
+
+
+/**
+ * @function unwrapResponse
+ *
+ * @description Unwrap the innner response body and code from an async Handler.
+ */
+export const unwrapResponse = async (asyncFunction: (reply: any) => any) => {
+  let responseBody: any
+  let responseCode: number = -1
+  const nestedReply = {
+    response: (response: any) => {
+      responseBody = response
+      return {
+        code: (statusCode: number) => {
+          responseCode = statusCode
+        }
+      }
+    }
+  }
+  await asyncFunction(nestedReply)
+
+  return {
+    responseBody,
+    responseCode
+  }
+}
+
+
+// Re-typing this here so we don't need to import from ParticipantService
+type GetAccountsResponseAccount = {
+  id: number,
+  value: string;
+  reservedValue: string;
+}
+
+/**
+ * Assert that the position account for the DFSP changed as expected.
+ */
+export const assertPositionDiff = (
+  role: 'payer' | 'payee',
+  start: GetAccountsResponseAccount,
+  end: GetAccountsResponseAccount,
+  diff: {
+    pending?: number
+    posted?: number,
+  }
+) => {
+  assert(start)
+  assert(start.value)
+  assert(start.reservedValue)
+  assert(end)
+  assert(end.value)
+  assert(end.reservedValue)
+  assert(start.id === end.id, 'Did you get the accounts mixed up?')
+
+  if (!diff.pending) {
+    diff.pending = 0
+  }
+  if (!diff.posted) {
+    diff.posted = 0
+  }
+
+  const valuePostedStart = Number.parseFloat(start.value)
+  const valuePendingStart = Number.parseFloat(start.reservedValue)
+
+  const endExpected: GetAccountsResponseAccount = {
+    id: start.id,
+    reservedValue: (valuePendingStart + diff.pending).toFixed(4),
+    value: (valuePostedStart + diff.posted).toFixed(4)
+  }
+
+  const expectedStr = prettyPrintPosition(role, start, endExpected)
+  const actualStr = prettyPrintPosition(role, start, end)
+
+  Snapshot.from(expectedStr, { stripWhitespace: false, updateable: false })
+    .checkStringUnwrap(actualStr)
+}
+
+export const prettyPrintPosition = (
+  role: 'payer' | 'payee', 
+  start: GetAccountsResponseAccount,
+  end: GetAccountsResponseAccount,
+) => {
+  const lenColumns = 15
+  return `
+  ${role}   | ${'start'.padEnd(lenColumns)}| ${'end'.padEnd(lenColumns)}
+  pending | ${start.reservedValue.padEnd(lenColumns)}| ${end.reservedValue.padEnd(lenColumns)}
+  posted  | ${start.value.padEnd(lenColumns)}| ${end.value.padEnd(lenColumns)}`
+}

package/src/types/central-services-error-handling.d.ts

@@ -0,0 +1,72 @@
+// Type definitions for @mojaloop/central-services-error-handling.
+
+declare module '@mojaloop/central-services-error-handling' {
+  export interface FSPIOPApiErrorObject {
+    errorInformation: {
+      errorCode: string;
+      errorDescription: string;
+      extensionList?: {
+        extension: Array<{
+          key: string;
+          value: string;
+        }>;
+      };
+    };
+  }
+  export class FSPIOPError extends Error {
+    apiErrorCode: any
+    message: string
+    cause: any
+    extensions: any
+    replyTo: string
+    useMessageAsDescription: boolean
+    
+    constructor(cause: any, message: string, replyTo: string, apiErrorCode: any, extensions?: any, useMessageAsDescription?: boolean);
+    
+    toApiErrorObject(options?: { includeCauseExtension?: boolean; truncateExtensions?: boolean }): FSPIOPApiErrorObject;
+    
+    toFullErrorObject(): any;
+  }
+
+  export namespace Factory {
+    export function createFSPIOPError(
+      apiErrorCode: any,
+      message?: string,
+      cause?: any,
+      replyTo?: string,
+      extensions?: any,
+      useDescriptionAsMessage?: boolean
+    ): FSPIOPError;
+
+    export function createInternalServerFSPIOPError(
+      message: string,
+      cause?: any,
+      replyTo?: string,
+      extensions?: any
+    ): FSPIOPError;
+
+    export function reformatFSPIOPError(
+      error: any,
+      apiErrorCode?: any,
+      replyTo?: string,
+      extensions?: any
+    ): FSPIOPError;
+
+    export function createFSPIOPErrorFromJoiError(error: any, cause?: any, replyTo?: string): FSPIOPError;
+    export function createFSPIOPErrorFromOpenapiError(error: any, replyTo?: string): FSPIOPError;
+    export function createFSPIOPErrorFromErrorInformation(errorInformation: any, cause?: any, replyTo?: string): FSPIOPError;
+    export function createFSPIOPErrorFromErrorCode(code: any, message?: string, cause?: any, replyTo?: string, extensions?: any): FSPIOPError;
+    export function validateFSPIOPErrorCode(code: any): any;
+    export function validateFSPIOPErrorGroups(code: any): boolean;
+  }
+
+  export namespace Enums {
+    export const FSPIOPErrorCodes: any
+    export function findFSPIOPErrorCode(code: any): any;
+    export function findErrorType(code: any): any;
+  }
+
+  export function validateRoutes(options?: any): any;
+  export const Handler: any
+  export const plugin: any
+}

package/src/types/central-services-stream.d.ts

@@ -0,0 +1,148 @@
+declare module '@mojaloop/central-services-stream' {
+  import { EventEmitter } from 'events'
+
+  export namespace Kafka {
+    interface ConsumerConfig {
+      rdkafkaConf?: Record<string, any>;
+      options?: {
+        mode?: 'consumer' | 'flow' | 'poll' | 'recursive';
+        messageCharset?: string;
+        messageAsJSON?: boolean;
+        sync?: boolean;
+        consumeTimeout?: number;
+        batchSize?: number;
+        concurrency?: number;
+        commitOffsetsOnFirstJoin?: boolean;
+        autoCommitEnable?: boolean;
+        autoCommitIntervalMs?: number;
+        eosCommit?: boolean;
+        consumeLoopTimeoutMs?: number;
+      };
+    }
+
+    interface ProducerConfig {
+      rdkafkaConf?: Record<string, any>;
+      options?: {
+        messageCharset?: string;
+        messageAsJSON?: boolean;
+        sync?: boolean;
+        pollIntervalMs?: number;
+        queueBufferingMaxMs?: number;
+      };
+    }
+
+    interface Message {
+      topic: string;
+      key?: string | Buffer;
+      value: string | Buffer;
+      partition?: number;
+      offset?: number;
+      timestamp?: number;
+      headers?: Record<string, string | Buffer>;
+    }
+
+    interface MessageProtocol {
+      content: any,
+      id: string,
+      from: string,
+      to: string,
+      metadata: any,
+      type: string,
+      pp?: string
+    }
+
+    interface MessageHandler {
+      (error: Error | null, message: Message): Promise<void> | void;
+    }
+
+    interface TopicConfiguration {
+      opaqueKey: any
+      topicName: string,
+      key?: string
+      partition?: number
+    }
+
+    class Consumer extends EventEmitter {
+      constructor(topics: string[], config: ConsumerConfig);
+      
+      connect(): Promise<void>;
+      disconnect(callback?: () => void): void;
+      consume(handler: MessageHandler): Promise<any>;
+      commitMessageSync(message: Message): void;
+      commitMessage(message: Message): Promise<void>;
+      isConnected(): boolean;
+      
+      on(event: 'error', listener: (error: Error) => void): this;
+      on(event: 'ready', listener: () => void): this;
+      on(event: 'disconnected', listener: () => void): this;
+      on(event: 'rebalance', listener: (assignment: any) => void): this;
+      on(event: string, listener: (...args: any[]) => void): this;
+      
+      static createHandler(
+        topicName: string, 
+        config: ConsumerConfig, 
+        handler: MessageHandler
+      ): Promise<Consumer>;
+      
+      static ENUMS: {
+        CONSUMER_MODES: {
+          consumer: 'consumer';
+          flow: 'flow'; 
+          poll: 'poll';
+          recursive: 'recursive';
+        };
+      }
+    }
+
+    class Producer extends EventEmitter {
+      constructor(config: ProducerConfig);
+      
+      connect(): Promise<void>;
+      disconnect(callback?: () => void): void;
+      sendMessage(
+        message: MessageProtocol, 
+        topicConf: TopicConfiguration, 
+        customHeaders?: Array<{ [key: string]: string | Buffer }>
+      ): Promise<void>;
+      isConnected(): boolean;
+      
+      on(event: 'error', listener: (error: Error) => void): this;
+      on(event: 'ready', listener: () => void): this;
+      on(event: 'disconnected', listener: () => void): this;
+      on(event: string, listener: (...args: any[]) => void): this;
+      
+      static ENUMS: {
+        COMPRESSION_TYPES: {
+          none: 'none';
+          gzip: 'gzip';
+          snappy: 'snappy';
+          lz4: 'lz4';
+        };
+      }
+    }
+
+    namespace Protocol {
+      interface ProtocolMessage {
+        id: string;
+        from: string;
+        to: string;
+        type: string;
+        content: any;
+        metadata?: Record<string, any>;
+      }
+
+      function encode(message: ProtocolMessage): Buffer;
+      function decode(buffer: Buffer): ProtocolMessage;
+    }
+  }
+
+  export namespace Util {
+    namespace Consumer {
+      function getConsumerModeMap(): Record<string, any>;
+    }
+
+    namespace Producer {
+      function getCompressionMap(): Record<string, any>;
+    }
+  }
+}

package/test-integration.Dockerfile

@@ -20,8 +20,6 @@ RUN apk del build-dependencies
 
 COPY src /opt/app/src
 COPY config /opt/app/config
-COPY migrations /opt/app/migrations
-COPY seeds /opt/app/seeds
 COPY test /opt/app/test
 
 # overwrite default.json with integration environment specific config

package/test.Dockerfile

@@ -20,8 +20,6 @@ RUN apk del build-dependencies
 
 COPY src /opt/app/src
 COPY config /opt/app/config
-COPY migrations /opt/app/migrations
-COPY seeds /opt/app/seeds
 COPY test /opt/app/test
 
 EXPOSE 3001

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "compilerOptions": {
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "lib": [
+      "es2020",
+      "esnext",
+    ],
+    "types": [
+      "node"
+    ],
+    "module": "commonjs",
+    "target": "es2020",
+    "allowJs": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.js",
+  ],
+  "exclude": [
+    "node_modules",
+    "src/**/*.d.ts"
+  ],
+  "ts-node": {
+    "compilerOptions": {
+      "sourceMap": true
+    },
+    "transpileOnly": true,
+    "experimentalResolver": false,
+    "files": true,
+    "ignore": [
+      "(?:^|/)node_modules/",
+      // We ignore .d.ts files as ts-node fails if it tries to execute them.
+      "\\.d\\.ts$"
+    ]
+  }
+}