onjs 2.4.1 → 2.5.1

package/.github/workflows/github-actions.yml

@@ -37,7 +37,7 @@ jobs:
           --health-timeout 5s
           --health-retries 5
       rabbitmq:
-        image: rabbitmq:alpine
+        image: rabbitmq:3.13-alpine
         ports:
           - 5672:5672
         env:
@@ -67,30 +67,3 @@ jobs:
         run: npm test
       
       - run: echo "Job's status is ${{ job.status }}."
-
-  publish:
-    needs: test
-    # This job runs on push to master branch
-    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
-    runs-on: ubuntu-latest
-
-    steps:
-      - run: echo "The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
-      - name: Check out repository code
-        uses: actions/checkout@v4
-      
-      - run: echo "The ${{ github.repository }} repository has been cloned to the runner."
-      - run: echo "The workflow is now ready to build your code on the runner."
-
-      # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-      
-      - run: echo "Job's status is ${{ job.status }}."
-      
-      - name: Publishing to NPM
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to npm
+run-name: Publishing onjs ${{ github.ref_name }} to npm
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+
+# npm Trusted Publishing: the package is configured on npmjs.com to trust
+# this repository + workflow filename, so publishing authenticates via OIDC
+# (no NPM_TOKEN required). Requires npm >= 11.5.1 (Node 24 ships it).
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    # The job runs in a container so the services are reachable by their
+    # hostnames ("rabbitmq", "redis") - on VM runners services are only
+    # reachable via localhost:mapped-port. Node 24 ships npm >= 11.5.1,
+    # required for OIDC trusted publishing.
+    container: node:24-bookworm
+    runs-on: ubuntu-latest
+    services:
+      rabbitmq:
+        image: rabbitmq:3.13-alpine
+        ports:
+          - 5672:5672
+        env:
+          RABBITMQ_DEFAULT_USER: rabbitmq
+          RABBITMQ_DEFAULT_PASS: rabbitmq
+          RABBITMQ_DEFAULT_VHOST: /
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+      redis:
+        image: redis:alpine
+        ports:
+          - 19379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Installing dependencies
+        run: npm ci
+      - name: Testing
+        run: npm test
+      - name: Publishing to NPM
+        run: npm publish

package/README.md

@@ -80,6 +80,22 @@ on
 	.withProperties(properties: array)
 	.do(eventName: string)
 ```
+#### Manual Acknowledgement
+
+By default, tasks are acknowledged as soon as they are delivered, so a task that fails (or a container that crashes mid-task) is not redelivered.
+
+Tasks registered with `.ackAfterProcessing()` are consumed with **manual acknowledgement**: the registered actions are awaited and the message is acknowledged only after they succeed. The broker holds the next delivery until then (prefetch 1 across the channel), so the service processes one task at a time and nothing is lost if the container crashes mid-task (unacknowledged messages are redelivered).
+
+If an action fails, the message is dropped without requeueing — the publisher is expected to send the task again when needed (e.g. when the work is requested once more). All tasks sharing the channel share one in-flight message, so registering more than one queue with `.ackAfterProcessing()` keeps a single task in flight across all of them.
+
+```javascript
+on
+	.taskReceived(eventName: string)
+	.withProperties(properties: array)
+	.ackAfterProcessing()
+	.do(eventName: string)
+```
+
 ### Delayed Queues
 
 The pattern of listening to work queues is described at https://www.rabbitmq.com/tutorials/tutorial-two-javascript.html

package/bin/prepare-test-environment

@@ -9,13 +9,12 @@ REDIS_CONTAINER_PORT=19379
 
 function createRabbitContainer() {
 	id=$(docker run -d --name ${RABBIT_CONTAINER_NAME} \
-  -p 5672:5272 \
   -e RABBITMQ_ERLANG_COOKIE=SWQOKODSQALRPCLNMEQG \
   -e RABBITMQ_DEFAULT_USER=rabbitmq \
   -e RABBITMQ_DEFAULT_PASS=rabbitmq \
   -e RABBITMQ_DEFAULT_VHOST=/ \
   --hostname rabbitmq \
-  rabbitmq:alpine)
+  rabbitmq:3.13-alpine)
 	echo $id
 }
 
@@ -88,3 +87,11 @@ else
   createRabbitContainer
   sleep 5
 fi
+
+function installDelayedMessageExchangePlugin() {
+  docker exec ${RABBIT_CONTAINER_NAME} sh -c "wget -q https://github.com/rabbitmq/rabbitmq-delayed-message-exchange/releases/download/v3.13.0/rabbitmq_delayed_message_exchange-3.13.0.ez -O /opt/rabbitmq/plugins/rabbitmq_delayed_message_exchange-3.13.0.ez"
+  docker exec ${RABBIT_CONTAINER_NAME} rabbitmq-plugins enable rabbitmq_delayed_message_exchange
+}
+
+echo "Ensuring the delayed-message exchange plugin is installed"
+installDelayedMessageExchangePlugin

package/bin/test

@@ -1,5 +1,26 @@
 #!/bin/bash
+# Runs the onjs test suite in a container attached to a shared docker network,
+# so the suite can resolve the broker as "rabbitmq" and redis as "redis"
+# (the hostnames the tests are configured with).
 
 $(pwd)/bin/prepare-test-environment
 
-npm test
+docker network create onjs_test > /dev/null 2>&1 || true
+# disconnect first so a re-connect always applies the hostname aliases
+docker network disconnect onjs_test onjs_rabbit_test > /dev/null 2>&1 || true
+docker network disconnect onjs_test onjs_redis_test > /dev/null 2>&1 || true
+docker network connect --alias rabbitmq onjs_test onjs_rabbit_test
+docker network connect --alias redis onjs_test onjs_redis_test
+
+if [ ! -d "node_modules" ]; then
+  echo "Installing dependencies"
+  docker run --rm --network onjs_test -v ${PWD}:/app -w /app rever/node:22 npm install
+fi
+
+echo "Running the test suite in a container (broker: rabbitmq, redis: redis)"
+docker run --rm --name onjs_test_runner \
+  --network onjs_test \
+  -v ${PWD}:/app -w /app \
+  -e "NODE_ENV=test" \
+  -e "ONJS_DELAYED_PLUGIN_TESTS=true" \
+  rever/node:22 npm test

package/lib/on.js

@@ -222,6 +222,70 @@ class On extends EventEmitter {
   // Where it will be processed to avoid duplicate
   // events sent from multiple processes
   async _initQueues (queues) {
+    try {
+      var queueChannel = await this.mqInstance.createChannel()
+      this.queueInstance.setChannel(queueChannel)
+
+      const autoTasks = queues.filter((task) => task.ackMode !== 'manual')
+      const manualTasks = queues.filter((task) => task.ackMode === 'manual')
+      const delayedTasks = this._getEvents('delayedQueue')
+
+      // The legacy dispatcher executes auto-ack and delayed tasks: register it
+      // whenever either exists — _initDelayedQueues consumes through the same
+      // queueEventReceived event, so it must not depend on auto-ack queues.
+      if (autoTasks.length > 0 || delayedTasks.length > 0) {
+        this._registerQueueEventDispatcher()
+      }
+
+      if (autoTasks.length > 0) {
+        this._log('info', 'Initializing queues (auto ack)', autoTasks.map((t) => t.eventName))
+        await this._initQueuesWithAutoAck(autoTasks, queueChannel)
+      }
+
+      // Manual-ack consumers get a DEDICATED channel: their prefetch window
+      // must never throttle legacy auto-ack or delayed consumers sharing the
+      // default channel (per Arturo's review).
+      if (manualTasks.length > 0) {
+        var manualChannel = await this.mqInstance.createChannel()
+        this._log('info', 'Initializing queues (manual ack)', manualTasks.map((t) => t.eventName))
+        await this._initQueuesWithManualAck(manualTasks, manualChannel)
+      }
+
+      return
+    }
+    catch (err) {
+      throw err
+    }
+  }
+
+  _registerQueueEventDispatcher () {
+    this.queueInstance.on('queueEventReceived', async (data) => {
+      try {
+        let taskName = data.name
+        this._eventLog('info', taskName, `Received task on queue ${taskName}`, data.data)
+
+        let task = this._getEventByName(taskName)
+
+        if (hasProperties(task) && !this._validationIsSuccess(task.eventName, data.data)) {
+          this._log('error', `Validation failed for task ${task.eventName} due to missing properties, received data`, data.data)
+          var error = new Error(`Validation failed for task ${task.eventName}`)
+          error.event = task
+
+          this.emit('error', error)
+          throw error
+        }
+
+        return this._onTaskReceived(task, data.data)
+      }
+      catch (err) {
+        throw err
+      }
+    })
+  }
+
+  // Consumes tasks with automatic acknowledgement, the message is acked
+  // as soon as it is received. This is the original (legacy) behavior
+  async _initQueuesWithAutoAck (queues, queueChannel) {
     try {
       var queueNames = queues.map((queue) => {
         return queue.eventName
@@ -229,31 +293,45 @@ class On extends EventEmitter {
 
       this._log('info', 'Listening for queueNames', queueNames)
 
-      this.queueInstance.on('queueEventReceived', async (data) => {
-        try {
-          let taskName = data.name
-          this._eventLog('info', taskName, `Received task on queue ${taskName}`, data.data)
+      var listener = await this.queueInstance.listen(queueNames)
+      return listener
+    }
+    catch (err) {
+      throw err
+    }
+  }
 
-          let task = this._getEventByName(taskName)
+  // Consumes tasks with manual acknowledgement. The broker holds the delivery
+  // until the handler finishes (prefetch 1 across the whole channel), so the
+  // service processes one task at a time and nothing is lost on crash (redelivery)
+  async _initQueuesWithManualAck (tasks, queueChannel) {
+    try {
+      const queueNames = tasks.map((task) => task.eventName)
+      this._log('info', 'Initializing queues (manual ack)', queueNames)
 
-          if (hasProperties(task) && !this._validationIsSuccess(task.eventName, data.data)) {
-            this._log('error', `Validation failed for task ${task.eventName} due to missing properties, received data`, data.data)
-            var error = new Error(`Validation failed for task ${task.eventName}`)
-            error.event = task
+      const tasksByQueueName = {}
+      for (const task of tasks) {
+        tasksByQueueName[task.eventName] = task
+      }
 
-            this.emit('error', error)
-            throw error
+      const handler = async (data, message) => {
+        const taskDef = tasksByQueueName[message.fields.routingKey]
+        try {
+          if (taskDef && hasProperties(taskDef) && !this._validationIsSuccess(taskDef.eventName, data)) {
+            throw new Error(`Validation failed for task ${taskDef.eventName}`)
           }
 
-          return this._onTaskReceived(task, data.data)
-        }
-        catch (err) {
+          await this._onTaskReceived(taskDef, data, { awaitActions: true })
+        } catch (err) {
+          const loggedName = taskDef ? taskDef.eventName : message.fields.routingKey
+          this._log('error', loggedName, 'Task failed, dropping (service-api republishes by demand)', err)
           throw err
         }
-      })
+      }
 
-      var listener = await this.queueInstance.listen(queueNames)
-      return listener
+      await this.queueInstance.listenManual(queueNames, handler, { globalPrefetch: true })
+
+      return
     }
     catch (err) {
       throw err
@@ -267,12 +345,30 @@ class On extends EventEmitter {
     return listener
   }
 
-  _onTaskReceived (task, data) {
+  async _onTaskReceived (task, data, options = {}) {
     this._eventLog('info', task.eventName, 'Executing task callback for task')
 
-    return Promise.allSettled(task.actions.map((action) => {
-      return action.call(task, data)
-    }))
+    const executions = task.actions.map((action) => {
+      try {
+        return action.call(task, data)
+      } catch (err) {
+        // a synchronous throw must not bypass the settle-wait below
+        return Promise.reject(err)
+      }
+    })
+
+    if (options.awaitActions) {
+      // wait for EVERY action before propagating a failure: one rejection
+      // must not release the next delivery while a sibling action still runs
+      const settled = await Promise.allSettled(executions)
+      const firstRejection = settled.find((result) => result.status === 'rejected')
+      if (firstRejection) {
+        throw firstRejection.reason
+      }
+      return
+    }
+
+    return Promise.allSettled(executions)
       .then((results) => {
         this._eventLog('info', task.eventName, 'Results of all executions for task ' + task.eventName, results)
       })
@@ -416,6 +512,18 @@ class On extends EventEmitter {
     return this
   }
 
+  ackAfterProcessing () {
+    if (this.currentEventTypeToRegister !== 'queue') {
+      throw new Error('ackAfterProcessing is only supported for queue events (not delayed queues, topics or RPC)')
+    }
+    if (!eventIsDeclaredBeforeCallingRegisterCallback(this._getEventIndexByNameAndType(this.currentEventNameToRegister, this.currentEventTypeToRegister))) {
+      throw new Error('Call taskReceived before setting the ack mode')
+    }
+    const eventIndex = this._getEventIndexByNameAndType(this.currentEventNameToRegister, this.currentEventTypeToRegister)
+    this.events[eventIndex].ackMode = 'manual'
+    return this
+  }
+
   // Alias method
   do (callback) {
     return this._registerCallback(callback)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onjs",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "description": "On.js is an event library based on RabbitMQ that helps you control events on a microservices arquitecture",
   "main": "index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "mocha": "^5.2.0"
   },
   "dependencies": {
-    "rabbitmq-lib": "^2.3.2",
+    "rabbitmq-lib": "^2.4.0",
     "amqplib": "^0.10.5",
     "bull": "^3.29.3"
   }

package/tests/tests/queues.js

@@ -14,6 +14,7 @@ describe('Queue', function () {
   var config = {
     mq: {
       exchange_name: 'onjs_test',
+      delayed_exchange_name: 'onjs_test_delayed',
       url: 'amqp://rabbitmq:rabbitmq@rabbitmq:5672/',
       connectMaxAttempts: 1,
       delayMS: 10,
@@ -97,4 +98,238 @@ describe('Queue', function () {
       superpower: 'Fly'
     })
   })
+
+  it("Should initialize and process a delayed queue task", async function () {
+    // The delayed round trip needs the delayed-message exchange plugin,
+    // installed by bin/prepare-test-environment. CI runs the stock image
+    // without the plugin: bin/test sets ONJS_DELAYED_PLUGIN_TESTS=true so
+    // this test runs there, and CI skips it (the routing regression test
+    // still guards the delayed path on every broker).
+    if (process.env.ONJS_DELAYED_PLUGIN_TESTS !== 'true') this.skip()
+
+    var executed = null
+
+    function execution(incomingData) {
+      executed = incomingData
+      return
+    }
+
+    on
+    .taskReceived('delayedQueueRegression', { isDelayed: true })
+    .andProcess(execution)
+
+    await on.init()
+
+    await sender.send('delayedQueueRegression', { name: 'Delayed Superman' }, 300)
+
+    var waited = 0
+    while (!executed && waited < 5000) {
+      await new Promise((resolve) => { setTimeout(resolve, 100) })
+      waited += 100
+    }
+
+    executed.should.have.property('name', 'Delayed Superman')
+  })
+})
+
+describe('Queue with manual ack', function () {
+  this.timeout(10000)
+
+  var config = {
+    mq: {
+      exchange_name: 'onjs_test_manual_ack',
+      delayed_exchange_name: 'onjs_test_manual_ack_delayed',
+      url: 'amqp://rabbitmq:rabbitmq@rabbitmq:5672/',
+      connectMaxAttempts: 1,
+      delayMS: 10,
+    },
+    redis: {
+      port: REDIS_PORT,
+      host: 'redis'
+    },
+  }
+
+  // These tests use a stubbed queueInstance and a fake channel,
+  // so they don't need a live broker connection
+  function createFakeChannel () {
+    var fake = {
+      prefetchCalls: [],
+      assertQueueCalls: [],
+      consumeCalls: [],
+      ackCalls: [],
+      nackCalls: [],
+      prefetch: async function (count, globalScope) {
+        fake.prefetchCalls.push([count, globalScope])
+      },
+      assertQueue: async function (queueName, options) {
+        fake.assertQueueCalls.push([queueName, options])
+        return { queue: queueName }
+      },
+      consume: async function (queueName, handler, options) {
+        fake.consumeCalls.push({ queueName: queueName, handler: handler, options: options })
+      },
+      ack: function (message) {
+        fake.ackCalls.push(message)
+      },
+      nack: function (message, allUpTo, requeue) {
+        fake.nackCalls.push([message, allUpTo, requeue])
+      }
+    }
+    return fake
+  }
+
+  function createStubbedOn () {
+    var onInstance = new On(config)
+    var channel = createFakeChannel()
+    var listenCalls = []
+    var listenManualCalls = []
+    var listenManualHandlers = []
+    var listenOptions = []
+
+    onInstance.mqInstance.createChannel = async function () {
+      return channel
+    }
+
+    onInstance.queueInstance = {
+      setChannel: function () {},
+      on: function () {},
+      listen: async function (queueNames, options) {
+        listenCalls.push(queueNames)
+        listenOptions.push(options)
+      },
+      listenManual: async function (queueNames, handler) {
+        listenManualCalls.push(queueNames)
+        listenManualHandlers.push(handler)
+      }
+    }
+
+    return { onInstance: onInstance, channel: channel, listenCalls: listenCalls, listenOptions: listenOptions, listenManualCalls: listenManualCalls, listenManualHandlers: listenManualHandlers }
+  }
+
+  it('Should route auto ack tasks to listen and manual ack tasks to the manual consumer', async function () {
+    var stubs = createStubbedOn()
+
+    function execution (incomingData) {
+      return
+    }
+
+    stubs.onInstance
+    .taskReceived('autoAckQueue')
+    .andProcess(execution)
+
+    stubs.onInstance
+    .taskReceived('manualAckQueue')
+    .ackAfterProcessing()
+    .andProcess(execution)
+
+    await stubs.onInstance._startEventListeners()
+
+    stubs.listenCalls.should.deepEqual([['autoAckQueue']])
+    stubs.listenManualCalls.should.deepEqual([['manualAckQueue']])
+    stubs.listenManualCalls[0].should.not.deepEqual(stubs.listenCalls[0])
+  })
+
+  it('Should route delayed tasks through the auto-ack listen with isDelayed', async function () {
+    var stubs = createStubbedOn()
+
+    function execution (incomingData) {
+      return
+    }
+
+    stubs.onInstance
+    .taskReceived('delayedQueue', { isDelayed: true })
+    .andProcess(execution)
+
+    await stubs.onInstance._startEventListeners()
+
+    stubs.listenCalls.should.deepEqual([['delayedQueue']])
+    stubs.listenOptions[0].should.have.property('isDelayed', true)
+  })
+
+  it('Should await the actions and ack the message after processing', async function () {
+    var stubs = createStubbedOn()
+    var executed = []
+    var actionFinished = false
+
+    stubs.onInstance
+    .taskReceived('manualAckQueue')
+    .ackAfterProcessing()
+    .andProcess(async function (incomingData) {
+      await new Promise((resolve) => { setTimeout(resolve, 25) })
+      executed.push(incomingData)
+      actionFinished = true
+    })
+
+    await stubs.onInstance._initQueuesWithManualAck(stubs.onInstance._getEvents('queue'), stubs.channel)
+
+    var handler = stubs.listenManualHandlers[0]
+
+    await handler({ name: 'Superman' }, { fields: { routingKey: 'manualAckQueue' } })
+
+    actionFinished.should.equal(true)
+    executed.should.deepEqual([{ name: 'Superman' }])
+  })
+
+  it('Should nack and drop the message when the task action fails', async function () {
+    var stubs = createStubbedOn()
+    var executed = false
+
+    stubs.onInstance
+    .taskReceived('failingManualQueue')
+    .ackAfterProcessing()
+    .andProcess(async function () {
+      executed = true
+      throw new Error('action failed')
+    })
+
+    await stubs.onInstance._initQueuesWithManualAck(stubs.onInstance._getEvents('queue'), stubs.channel)
+
+    var handler = stubs.listenManualHandlers[0]
+
+    await handler({ name: 'Superman' }, { fields: { routingKey: 'failingManualQueue' } }).should.be.rejectedWith('action failed')
+
+    executed.should.equal(true)
+  })
+
+  it('Should nack the message when payload validation fails', async function () {
+    var stubs = createStubbedOn()
+    var executed = false
+
+    stubs.onInstance
+    .taskReceived('validatedManualQueue')
+    .withProperties(['name'])
+    .ackAfterProcessing()
+    .andProcess(async function () {
+      executed = true
+    })
+
+    await stubs.onInstance._initQueuesWithManualAck(stubs.onInstance._getEvents('queue'), stubs.channel)
+
+    var handler = stubs.listenManualHandlers[0]
+
+    await handler({ other: 'value' }, { fields: { routingKey: 'validatedManualQueue' } }).should.be.rejectedWith('Validation failed for task validatedManualQueue')
+
+    executed.should.equal(false)
+  })
+
+  it('Should ack the message when payload validation passes', async function () {
+    var stubs = createStubbedOn()
+    var executed = []
+
+    stubs.onInstance
+    .taskReceived('validatedManualQueue')
+    .withProperties(['name'])
+    .ackAfterProcessing()
+    .andProcess(async function (incomingData) {
+      executed.push(incomingData)
+    })
+
+    await stubs.onInstance._initQueuesWithManualAck(stubs.onInstance._getEvents('queue'), stubs.channel)
+
+    var handler = stubs.listenManualHandlers[0]
+
+    await handler({ name: 'Superman' }, { fields: { routingKey: 'validatedManualQueue' } })
+
+    executed.should.deepEqual([{ name: 'Superman' }])
+  })
 })