@natlibfi/melinda-rest-api-commons 6.1.0-alpha.0 → 6.2.0-alpha.1

package/{tests/amqp-error-branches.test.js → test/amqp-error-branches.test.ts}

@@ -3,24 +3,47 @@ import {test} from 'node:test';
 import {execFile} from 'node:child_process';
 import {fileURLToPath} from 'node:url';
 import {Error as ApiError} from '@natlibfi/melinda-commons';
-import createAmqp from '../src/amqp.js';
+import type {Message} from 'amqplib';
+import createAmqp, {type QueueItemMessagePayload, type QueueItemRecordPayload} from '../src/amqp.ts';
 
-const AMQP_MODULE_PATH = fileURLToPath(new URL('../src/amqp.js', import.meta.url));
+const AMQP_MODULE_PATH = fileURLToPath(new URL('../src/amqp.ts', import.meta.url));
 
 const DUMMY_URL = 'amqp://stub:5672/';
 const QUEUE = 'TESTQUEUE';
 
-function makeMessage(correlationId, deliveryTag) {
+/**
+ * A minimal stub for an amqplib message. The fields beyond deliveryTag
+ * match the shape of a real amqplib message (the tests only exercise
+ * deliveryTag, correlationId and the message body).
+ */
+function makeMessage(correlationId: string, deliveryTag: number): Message {
   const data = {leader: '00000nam a22000000i 4500', fields: [{tag: '001', value: '123'}]};
   const content = JSON.stringify({data});
   return {
     content: Buffer.from(content),
-    properties: {correlationId, headers: {from: 'TEST'}},
-    fields: {deliveryTag}
+    // only correlationId and headers are exercised by these tests; the
+    // remaining message properties stay undefined
+    properties: {
+      contentType: undefined,
+      contentEncoding: undefined,
+      headers: {from: 'TEST'},
+      deliveryMode: undefined,
+      priority: undefined,
+      correlationId,
+      replyTo: undefined,
+      expiration: undefined,
+      messageId: undefined,
+      timestamp: undefined,
+      type: undefined,
+      userId: undefined,
+      appId: undefined,
+      clusterId: undefined
+    },
+    fields: {deliveryTag, redelivered: false, exchange: '', routingKey: ''}
   };
 }
 
-function makeChannel(overrides = {}) {
+function makeChannel(overrides: Record<string, unknown> = {}) {
   return {
     assertQueue: async () => ({messageCount: 0}),
     checkQueue: async () => ({messageCount: 0}),
@@ -30,18 +53,22 @@ function makeChannel(overrides = {}) {
     purgeQueue: async () => {},
     close: async () => {},
     sendToQueue: async () => {},
+    on: () => {},
     ...overrides
   };
 }
 
-async function makeOperator(channelOverrides) {
+/**
+ * Create an operator with the given channel stub overrides injected via deps
+ */
+async function makeOperator(channelOverrides?: Record<string, unknown>) {
   const channel = makeChannel(channelOverrides);
-  const connection = {createChannel: async () => channel, close: async () => {}};
+  const connection = {createChannel: async () => channel, close: async () => {}, on: () => {}};
   return createAmqp(DUMMY_URL, false, {connection, channel});
 }
 
 test('consumeChunk returns false when queue drains mid-pump', async () => {
-  // (src/amqp.js, getData/pump):
+  // (src/amqp.ts, getData/pump):
   // FIXED: pump now bails out (returns results) when channel.get -> null,
   // and consumeChunk maps an empty pump result to false, matching the
   // empty-queue contract of checkQueue. Previously this crashed with
@@ -67,14 +94,14 @@ test('consumeChunk returns partial chunk when queue drains after first message',
       return first;
     }
   });
-  const {records, messages} = await amqpOperator.consumeChunk(QUEUE, true);
+  const {records, messages} = (await amqpOperator.consumeChunk(QUEUE, true)) as QueueItemRecordPayload;
   assert.equal(messages.length, 1);
   assert.equal(records.length, 1);
 });
 
 
 test('consumeChunk deduplicates messages with same correlationId + deliveryTag', async () => {
-  // (src/amqp.js, getData/pump):
+  // (src/amqp.ts, getData/pump):
   // FIXED: dedup now compares correlationId + deliveryTag field-by-field,
   // so duplicate messages are filtered out. (Previously the includes()
   // check compared object references and never triggered.)
@@ -83,7 +110,7 @@ test('consumeChunk deduplicates messages with same correlationId + deliveryTag',
     checkQueue: async () => ({messageCount: 2}),
     get: async () => duplicate
   });
-  const {records, messages} = await amqpOperator.consumeChunk(QUEUE, true);
+  const {records, messages} = (await amqpOperator.consumeChunk(QUEUE, true)) as QueueItemRecordPayload;
   assert.equal(messages.length, 1);
   assert.equal(records.length, 1);
 });
@@ -96,26 +123,25 @@ test('same deliveryTag with different correlationIds is NOT deduplicated', async
     checkQueue: async () => ({messageCount: 2}),
     get: async () => messages.shift()
   });
-  const {messages: got} = await amqpOperator.consumeChunk(QUEUE, true);
+  const {messages: got} = (await amqpOperator.consumeChunk(QUEUE, true)) as QueueItemRecordPayload;
   assert.equal(got.length, 2);
 });
 
 test('removeQueue closes the temp channel even when deleteQueue throws', async () => {
-  // (src/amqp.js, removeQueue):
+  // (src/amqp.ts, removeQueue):
   // FIXED: the throwaway tempChannel is now closed in a finally block, so a
   // missing queue (deleteQueue throws) no longer leaks a channel.
-  const closedChannels = [];
+  const closedChannels: any[] = [];
   const tempChannel = {
     deleteQueue: async () => {
       throw new Error('NOT_FOUND - queue missing');
     },
     close: async () => {
-      // eslint-disable-next-line functional/immutable-data
       closedChannels.push('temp');
     }
   };
   const amqpOperator = await createAmqp(DUMMY_URL, false, {
-    connection: {createChannel: async () => tempChannel, close: async () => {}},
+    connection: {createChannel: async () => tempChannel, close: async () => {}, on: () => {}},
     channel: makeChannel()
   });
   await assert.rejects(() => amqpOperator.removeQueue(QUEUE));
@@ -123,17 +149,17 @@ test('removeQueue closes the temp channel even when deleteQueue throws', async (
 });
 
 test('removeQueue closes the temp channel on success too', async () => {
-  const closedChannels = [];
+  const closedChannels: any[] = [];
   const amqpOperator = await createAmqp(DUMMY_URL, false, {
     connection: {
       createChannel: async () => ({
         deleteQueue: async () => {},
         close: async () => {
-          // eslint-disable-next-line functional/immutable-data
           closedChannels.push('temp');
         }
       }),
-      close: async () => {}
+      close: async () => {},
+      on: () => {}
     },
     channel: makeChannel()
   });
@@ -142,7 +168,7 @@ test('removeQueue closes the temp channel on success too', async () => {
 });
 
 test('healthCheck loop stops after closeChannel and does not keep firing or throw', async () => {
-  // (src/amqp.js, healthCheck):
+  // (src/amqp.ts, healthCheck):
   // FIXED: closeChannel/closeConnection cancel the recursive healthCheck loop,
   // so the ~200 ms chain short-circuits instead of running until the closed
   // channel throws (which used to make graceful shutdown flaky).
@@ -151,9 +177,8 @@ test('healthCheck loop stops after closeChannel and does not keep firing or thro
   let closed = false;
   let healthCheckCalls = 0;
   const channel = {
-    assertQueue: async (name) => {
+    assertQueue: async (name: string) => {
       if (name === 'HEALTHCHECK') {
-        // eslint-disable-next-line functional/immutable-data
         healthCheckCalls += 1;
         if (closed) {
           throw new Error('channel closed');
@@ -167,12 +192,12 @@ test('healthCheck loop stops after closeChannel and does not keep firing or thro
     nack: () => {},
     purgeQueue: async () => {},
     close: async () => {
-      // eslint-disable-next-line functional/immutable-data
       closed = true;
-    }
+    },
+    on: () => {}
   };
   const amqpOperator = await createAmqp(DUMMY_URL, true, {
-    connection: {createChannel: async () => channel, close: async () => {}},
+    connection: {createChannel: async () => channel, close: async () => {}, on: () => {}},
     channel
   });
   // let the health check run at least once, then cancel it
@@ -194,7 +219,7 @@ test('happy path: consumeChunk returns two distinct messages', async () => {
     checkQueue: async () => ({messageCount: messages.length}),
     get: async () => messages.shift()
   });
-  const {headers, records, messages: got} = await amqpOperator.consumeChunk(QUEUE, true);
+  const {headers, records, messages: got} = (await amqpOperator.consumeChunk(QUEUE, true)) as QueueItemRecordPayload;
   assert.equal(got.length, 2);
   assert.equal(records.length, 2);
   assert.deepStrictEqual(headers, {from: 'TEST'});
@@ -218,7 +243,7 @@ test('checkQueue style one returns the {headers, records, messages} form when to
     assertQueue: async () => ({messageCount: 1}),
     get: async () => message
   });
-  const {headers, records, messages} = await amqpOperator.checkQueue({queue: QUEUE, style: 'one', toRecord: true});
+  const {headers, records, messages} = (await amqpOperator.checkQueue({queue: QUEUE, style: 'one', toRecord: true})) as QueueItemRecordPayload;
   assert.deepStrictEqual(headers, {from: 'TEST'});
   assert.equal(records.length, 1);
   assert.strictEqual(messages.length, 1);
@@ -257,7 +282,7 @@ test('checkQueue style basic returns a chunk of records and messages when the qu
     checkQueue: async () => ({messageCount: messages.length}),
     get: async () => messages.shift()
   });
-  const {headers, records, messages: got} = await amqpOperator.checkQueue({queue: QUEUE, style: 'basic', toRecord: true});
+  const {headers, records, messages: got} = (await amqpOperator.checkQueue({queue: QUEUE, style: 'basic', toRecord: true})) as QueueItemRecordPayload;
   assert.deepStrictEqual(headers, {from: 'TEST'});
   assert.equal(records.length, 2);
   assert.equal(got.length, 2);
@@ -276,17 +301,15 @@ test('checkQueue rejects with a 500 ApiError for an unknown style', async () =>
 });
 
 test('checkQueue purges the queue before returning the style result', async () => {
-  const purgeCalls = [];
+  const purgeCalls: any[] = [];
   let assertCalls = 0;
   const amqpOperator = await makeOperator({
     assertQueue: async () => {
-      // eslint-disable-next-line functional/immutable-data
       assertCalls += 1;
       // first call (before the purge) reports 3 pending, after the purge 0
       return assertCalls === 1 ? {messageCount: 3} : {messageCount: 0};
     },
-    purgeQueue: async (name) => {
-      // eslint-disable-next-line functional/immutable-data
+    purgeQueue: async (name: string) => {
       purgeCalls.push(name);
     }
   });
@@ -309,7 +332,7 @@ test('consumeOne returns the plain message when toRecord is false', async () =>
 test('consumeOne returns the {headers, records, messages} form when toRecord is true', async () => {
   const message = makeMessage('c1', 1);
   const amqpOperator = await makeOperator({get: async () => message});
-  const {headers, records, messages} = await amqpOperator.consumeOne(QUEUE, true);
+  const {headers, records, messages} = (await amqpOperator.consumeOne(QUEUE, true)) as QueueItemRecordPayload;
   assert.deepStrictEqual(headers, {from: 'TEST'});
   assert.equal(records.length, 1);
   assert.strictEqual(messages.length, 1);
@@ -341,7 +364,7 @@ test('consumeChunk returns {headers, messages} without records when toRecord is
     checkQueue: async () => ({messageCount: messages.length}),
     get: async () => messages.shift()
   });
-  const {headers, messages: got} = await amqpOperator.consumeChunk(QUEUE, false);
+  const {headers, messages: got} = (await amqpOperator.consumeChunk(QUEUE, false)) as QueueItemMessagePayload;
   assert.deepStrictEqual(headers, {from: 'TEST'});
   assert.equal(got.length, 2);
 });
@@ -360,11 +383,10 @@ test('consumeChunk rejects when the amqplib checkQueue throws a plain Error', as
 // ---------------------------------------------------------------------------
 
 test('ackMessages acks every message on the channel', async () => {
-  const acked = [];
+  const acked: Message[] = [];
   const messages = [makeMessage('c1', 1), makeMessage('c2', 2)];
   const amqpOperator = await makeOperator({
-    ack: (message) => {
-      // eslint-disable-next-line functional/immutable-data
+    ack: (message: Message) => {
       acked.push(message);
     }
   });
@@ -373,11 +395,10 @@ test('ackMessages acks every message on the channel', async () => {
 });
 
 test('nackMessages nacks every message on the channel', async () => {
-  const nacked = [];
+  const nacked: Message[] = [];
   const messages = [makeMessage('c1', 1), makeMessage('c2', 2)];
   const amqpOperator = await makeOperator({
-    nack: (message) => {
-      // eslint-disable-next-line functional/immutable-data
+    nack: (message: Message) => {
       nacked.push(message);
     }
   });
@@ -390,10 +411,9 @@ test('nackMessages nacks every message on the channel', async () => {
 // ---------------------------------------------------------------------------
 
 test('sendToQueue sends the JSON body with correlationId, persistent and headers options', async () => {
-  const sent = [];
+  const sent: {queue: string, content: Buffer, options: Record<string, unknown>}[] = [];
   const amqpOperator = await makeOperator({
-    sendToQueue: async (queue, content, options) => {
-      // eslint-disable-next-line functional/immutable-data
+    sendToQueue: async (queue: string, content: Buffer, options: Record<string, unknown>) => {
       sent.push({queue, content, options});
     }
   });
@@ -405,10 +425,10 @@ test('sendToQueue sends the JSON body with correlationId, persistent and headers
     data
   });
   assert.equal(sent.length, 1);
-  assert.equal(sent[0].queue, QUEUE);
-  assert.ok(Buffer.isBuffer(sent[0].content));
-  assert.deepStrictEqual(JSON.parse(sent[0].content.toString()), {data});
-  assert.deepStrictEqual(sent[0].options, {correlationId: 'cid-1', persistent: true, headers: {h: 1}});
+  assert.equal(sent[0]?.queue, QUEUE);
+  assert.ok(sent[0] && Buffer.isBuffer(sent[0].content));
+  assert.deepStrictEqual(JSON.parse(sent[0]?.content.toString() ?? ''), {data});
+  assert.deepStrictEqual(sent[0]?.options, {correlationId: 'cid-1', persistent: true, headers: {h: 1}});
 });
 
 test('sendToQueue rejects with a 500 ApiError when the queue is undefined', async () => {
@@ -442,15 +462,15 @@ test('checkQueue rejects with a 500 ApiError when the queue is an empty string',
 // ---------------------------------------------------------------------------
 
 test('closeConnection closes the connection and the operator resolves', async () => {
-  const closed = [];
+  const closed: any[] = [];
   const channel = makeChannel();
   const amqpOperator = await createAmqp(DUMMY_URL, false, {
     connection: {
       createChannel: async () => channel,
       close: async () => {
-        // eslint-disable-next-line functional/immutable-data
         closed.push('connection');
-      }
+      },
+      on: () => {}
     },
     channel
   });
@@ -459,16 +479,14 @@ test('closeConnection closes the connection and the operator resolves', async ()
 });
 
 test('healthCheck error arriving after cancel does not rethrow and stops the loop', async () => {
-  let rejectAssert;
+  let rejectAssert: ((reason?: unknown) => void) | undefined;
   const pending = new Promise((_, reject) => {
-    // eslint-disable-next-line functional/immutable-data
     rejectAssert = reject;
   });
   let healthCheckCalls = 0;
   const channel = makeChannel({
-    assertQueue: async (name) => {
+    assertQueue: async (name: string) => {
       if (name === 'HEALTHCHECK') {
-        // eslint-disable-next-line functional/immutable-data
         healthCheckCalls += 1;
         return pending;
       }
@@ -476,13 +494,15 @@ test('healthCheck error arriving after cancel does not rethrow and stops the loo
     }
   });
   const amqpOperator = await createAmqp(DUMMY_URL, true, {
-    connection: {createChannel: async () => channel, close: async () => {}},
+    connection: {createChannel: async () => channel, close: async () => {}, on: () => {}},
     channel
   });
   // by now the loop is suspended on the pending assertQueue call;
   // cancel first, then let the error arrive so the catch sees the flag already cleared
   await amqpOperator.closeChannel();
-  rejectAssert(new Error('amqp down after close'));
+  if (rejectAssert) {
+    rejectAssert(new Error('amqp down after close'));
+  }
   await new Promise((resolve) => setTimeout(resolve, 50));
   assert.equal(healthCheckCalls, 1, 'no further health checks after cancel');
 });
@@ -497,7 +517,7 @@ test('healthCheck error while running rethrows into the un-awaited loop promise'
   const script = `
     import createAmqp from '${AMQP_MODULE_PATH}';
     const channel = {
-      assertQueue: async (name) => {
+      assertQueue: /** @param {*} name */ async (name) => {
         if (name === 'HEALTHCHECK') {
           throw new Error('amqp down');
         }
@@ -509,12 +529,13 @@ test('healthCheck error while running rethrows into the un-awaited loop promise'
       nack: () => {},
       purgeQueue: async () => {},
       close: async () => {},
-      sendToQueue: async () => {}
+      sendToQueue: async () => {},
+      on: () => {}
     };
     const captured = [];
     process.on('unhandledRejection', (err) => captured.push(err));
     await createAmqp('amqp://stub:5672/', true, {
-      connection: {createChannel: async () => channel, close: async () => {}},
+      connection: {createChannel: async () => channel, close: async () => {}, on: () => {}},
       channel
     });
     // the first loop iteration rejects and the error escapes the un-awaited loop promise
@@ -523,7 +544,7 @@ test('healthCheck error while running rethrows into the un-awaited loop promise'
     process.stdout.write(ok ? 'OK' : 'FAIL:' + JSON.stringify(captured.map((e) => String(e && e.message))));
     process.exit(ok ? 0 : 1);
   `;
-  const {code, stdout} = await new Promise((resolve) => {
+  const {code, stdout} = await new Promise<{code: number | string, stdout: string}>((resolve) => {
     const child = execFile(process.execPath, ['--input-type=module', '-e', script], (err, out) => {
       resolve({code: err ? (err.code ?? 1) : 0, stdout: out ?? ''});
     });
@@ -533,3 +554,56 @@ test('healthCheck error while running rethrows into the un-awaited loop promise'
   // handleAmqpErrors logs the error to stdout before the escape, so only the tail matters
   assert.ok(stdout.endsWith('OK'), `expected child output to end with OK, got: ${stdout}`);
 });
+
+test('broker loss (error + close events) logs the error and close cancels the health check', async () => {
+  // Failure-path listeners on the amqplib connection/channel:
+  // - 'error' must only log: without a handler an unhandled EventEmitter
+  //   'error' would become an uncaughtException, and the error alone must
+  //   NOT stop the loop (the fast-fail contract is unchanged)
+  // - 'close' must cancel the health check loop so no iterations keep
+  //   running on a dead link (matters for runHealthCheck: false consumers)
+  const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
+  const makeOn = (target: string) => (event: string, handler: (...args: unknown[]) => void) => {
+    const key = `${target}:${event}`;
+    const list = handlers[key] ?? (handlers[key] = []);
+    list.push(handler);
+    return {off: () => {}};
+  };
+  let healthCheckCalls = 0;
+  const channel = makeChannel({
+    on: makeOn('channel'),
+    assertQueue: async (name: string) => {
+      if (name === 'HEALTHCHECK') {
+        healthCheckCalls += 1;
+      }
+      return {messageCount: 0};
+    }
+  });
+  await createAmqp(DUMMY_URL, true, {
+    connection: {createChannel: async () => channel, close: async () => {}, on: makeOn('connection')},
+    channel
+  });
+  // all four listeners must be attached (connection + channel, error + close)
+  assert.deepStrictEqual(Object.keys(handlers).sort(), [
+    'channel:close',
+    'channel:error',
+    'connection:close',
+    'connection:error'
+  ]);
+  // let the loop run a couple of iterations, then simulate broker loss the
+  // way amqplib signals it: an 'error' event followed by 'close'
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  for (const handler of handlers['channel:error'] ?? []) handler(new Error('socket lost'));
+  for (const handler of handlers['connection:error'] ?? []) handler(new Error('socket lost'));
+  // the 'error' events alone must not cancel the loop
+  const callsAfterError = healthCheckCalls;
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  assert.ok(healthCheckCalls > 0, 'health check should have run before the broker loss');
+  assert.ok(healthCheckCalls > callsAfterError, 'health check keeps running after the error events');
+  for (const handler of handlers['channel:close'] ?? []) handler();
+  for (const handler of handlers['connection:close'] ?? []) handler();
+  const callsAfterClose = healthCheckCalls;
+  // wait longer than the 200 ms loop interval - no further health checks may fire
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  assert.equal(healthCheckCalls, callsAfterClose, 'no health checks after the close events');
+});

package/{tests/amqp.healthtest.js → test/amqp.healthtest.ts}

@@ -1,7 +1,8 @@
 import {describe, it} from 'node:test';
 import assert from 'node:assert';
 import createDebugLogger from 'debug';
-import {amqpFactory} from '../src/index.js';
+import {amqpFactory} from '../src/index.ts';
+import type {AmqpOperator} from '../src/amqp.ts';
 
 
 const debug = createDebugLogger('@natlibfi/melinda-rest-api-commons:amqp:test');
@@ -12,10 +13,17 @@ const setTimeoutPromise = promisify(setTimeout);
 
 describe('HealthCheck: amqpOperator should error if channel or connection fails', () => {
 
-  it('FIX: test healthCheck - this test does not really test anything, but error can be seen in debug!', async () => {
+  it('healthcheck loop stops silently on closeChannel without unhandled rejections', async (t) => {
     debug(`Testing amqp against a local AMQP instance - we'll need some kind of mockup for this`);
     const amqpUrl = 'amqp://127.0.0.1:5672/';
 
+    // pin the contract: the loop must never leak an unhandled rejection,
+    // both while running and after closeChannel cancels it
+    const unhandled: unknown[] = [];
+    const onUnhandledRejection = (error: unknown) => unhandled.push(error);
+    process.on('unhandledRejection', onUnhandledRejection);
+    t.after(() => process.off('unhandledRejection', onUnhandledRejection));
+
     const amqpOperator = await amqpFactory(amqpUrl, true);
     debug(`Connecting to ${amqpUrl}, with healthCheck running`);
     await awaitTime(amqpOperator, false);
@@ -30,20 +38,21 @@ describe('HealthCheck: amqpOperator should error if channel or connection fails'
     await awaitTime(amqpOperator, true);
     // closeChannel() sets the run flag so the loop short-circuits gracefully:
     // it must stop silently without throwing or firing further health checks
-    assert.ok(true, 'healthCheck loop stopped without error');
+    assert.deepStrictEqual(unhandled, [], 'no unhandled rejections while running or after closeChannel');
 
     debug(`Closing connection`);
     await amqpOperator.closeConnection();
 
-    async function awaitTime(amqpOperator, close) {
+    /**
+     * @param amqpOperator
+     * @param close
+     */
+    async function awaitTime(amqpOperator: AmqpOperator, close: boolean): Promise<void> {
       if (close) {
-        // wrap the wait so any error thrown by the (cancelled) loop fails the test
         await amqpOperator.closeChannel();
-        try {
-          await setTimeoutPromise(500);
-        } catch (error) {
-          assert.fail(`healthCheck loop threw after closeChannel: ${error}`);
-        }
+        // note: promisify(setTimeout) never rejects, so a try/catch around it
+        // can never catch; the unhandledRejection assertion above is the pin
+        await setTimeoutPromise(500);
         return;
       }
 
@@ -53,4 +62,3 @@ describe('HealthCheck: amqpOperator should error if channel or connection fails'
 
   });
 });
-