feat(pool): emit 'connectionQueueAcquired' event on connection dequeue fixes #3844

[shubhanshu2103]

This PR introduces a new event, 'connectionQueueAcquired', on the connection pool. This event fires whenever a waiting request is pulled from the internal queue (_connectionQueue) and successfully acquires a free connection.

This addresses the request for better observability of connection pool bottlenecks by providing real-time data on the queue state at the exact moment a waiting request is served.

🌟 Key Changes

New Event Emission in lib/base/pool.js:

The BasePool.releaseConnection() method is modified to emit 'connectionQueueAcquired' when this._connectionQueue.length is greater than 0, after shifting the waiting callback but before calling it.

Event Payload:

The event payload provides the essential information needed for diagnostics:

{
connection: connection, // The Connection object being handed to the request
queueDepth: this._connectionQueue.length // The actual size of the queue after the request was dequeued
}

New Integration Test:

A new integration test file, test/integration/test-pool-queue-event.js, was added to fully validate the feature.

The test saturates the pool (limit 2), queues two additional requests (depth 2), and then releases the active connections, asserting that the event fires exactly twice with the correct descending queueDepth values of 1 and 0.

Implementation Details

The implementation in releaseConnection is minimal and targeted to avoid side effects:

} else if (this._connectionQueue.length) {
cb = this._connectionQueue.shift();

// New Event: Fired when request acquires connection from queue
this.emit('connectionQueueAcquired', {
    connection: connection,
    queueDepth: this._connectionQueue.length 
});

process.nextTick(cb.bind(null, null, connection));

} else {
// ...

[shubhanshu2103]

@wellwelwel please let me know the improvements needed.