comq 0.17.1 → 0.19.0

package/test/connect.test.js

@@ -40,7 +40,7 @@ describe('single connection', () => {
   })
 
   it('should pass active connection', async () => {
-    expect(Connection).toHaveBeenCalledWith(url)
+    expect(Connection).toHaveBeenCalledWith(url, {})
 
     /** @type {jest.MockedObject<comq.Connection>} */
     const instance = Connection.mock.instances[0]
@@ -62,10 +62,39 @@ describe('sharded connection', () => {
   })
 
   it('should pass single connection instances', async () => {
-    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url))
+    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, {}))
 
     const instances = Connection.mock.instances
 
     expect(shards.Connection).toHaveBeenCalledWith(instances)
   })
 })
+
+describe('topology overrides', () => {
+  it('should pass the trailing argument to the connection', async () => {
+    const overrides = { event: { delay: 100 } }
+
+    await connect(url, overrides)
+
+    expect(Connection).toHaveBeenCalledWith(url, overrides)
+  })
+
+  it('should pass them to every shard', async () => {
+    const urls = [generate(), generate()]
+    const overrides = { request: { attempts: 1 } }
+
+    await connect(...urls, overrides)
+
+    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, overrides))
+    expect(shards.Connection).toHaveBeenCalled()
+  })
+
+  it('should not take a url as overrides', async () => {
+    const urls = [generate(), generate()]
+
+    await connect(...urls)
+
+    expect(Connection).toHaveBeenCalledTimes(2)
+    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, {}))
+  })
+})

package/test/helpers.js

@@ -4,6 +4,20 @@ const timeout = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
 const immediate = () => new Promise((resolve) => setImmediate(resolve))
 
+/**
+ * Waits for a condition rather than for a duration.
+ *
+ * @param {() => boolean} condition
+ * @param {number} [ms] how long to keep asking
+ */
+const until = async (condition, ms = 5000) => {
+  const deadline = Date.now() + ms
+
+  while (!condition() && Date.now() < deadline) await timeout(20)
+
+  return condition()
+}
+
 const random = (max = 100) => Math.floor(Math.random() * max)
 
 const flip = () => Math.random() < 0.5
@@ -70,6 +84,7 @@ const MULTIPLIERS = Object.entries({
 
 exports.timeout = timeout
 exports.immediate = immediate
+exports.until = until
 exports.random = random
 exports.flip = flip
 exports.sample = sample

package/test/io.diagnostics.test.js

@@ -28,7 +28,7 @@ describe.each(['request', 'reply', 'event'])('%s channel events',
    * @param {comq.topology.type} type
    */
   (type) => {
-    it.each(['flow', 'drain', 'recover', 'discard', 'pause', 'resume', 'lost', 'remove'])('should re-emit %s',
+    it.each(['flow', 'drain', 'recover', 'discard', 'retry', 'pause', 'resume', 'lost', 'remove'])('should re-emit %s',
       /**
        * @param {comq.diagnostics.Event} event
        */

package/test/io.reply.test.js

@@ -10,6 +10,7 @@ const mock = require('./connection.mock')
 const { encodings } = require('./encodings')
 
 const { IO } = require('../source/io')
+const { Retry, Park } = require('../source/verdicts')
 
 /** @type {comq.IO} */
 let io
@@ -240,3 +241,68 @@ const findChannel = (type) => {
 
   return connection.createChannel.mock.results[index].value
 }
+
+describe('verdicts', () => {
+  /** @type {jest.MockedObject<comq.Channel>} */
+  let requests
+
+  const message = () => /** @type {comq.amqp.Message} */ ({
+    content: randomBytes(10),
+    properties: { replyTo: generate(), contentType: 'text/plain' }
+  })
+
+  const findChannel = async (type) => {
+    const index = connection.createChannel.mock.calls.findIndex(([argument]) => argument === type)
+
+    return await connection.createChannel.mock.results[index].value
+  }
+
+  beforeEach(async () => {
+    await io.reply(queue, produce)
+
+    requests = await findChannel('request')
+  })
+
+  it('should refuse Park from a producer', async () => {
+    // a Request has a caller awaiting a reply, so a verdict is a category error there
+    const park = new Park(generate())
+
+    produce.mockImplementationOnce(async () => { throw park })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toThrow(/not applicable to a reply producer/)
+  })
+
+  it('should keep the Park as the cause of what it throws instead', async () => {
+    const park = new Park(generate())
+
+    produce.mockImplementationOnce(async () => { throw park })
+
+    const consumer = requests.consume.mock.calls[0][1]
+    const exception = await consumer(message()).catch((error) => error)
+
+    // the explanation reaches the parked message as its reason, and this as its cause
+    expect(exception.cause).toStrictEqual(park)
+  })
+
+  it('should pass an ordinary rejection through untouched', async () => {
+    const failure = new Error(generate())
+
+    produce.mockImplementationOnce(async () => { throw failure })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toStrictEqual(failure)
+  })
+
+  it('should pass Retry through untouched', async () => {
+    const retry = new Retry(generate())
+
+    produce.mockImplementationOnce(async () => { throw retry })
+
+    const consumer = requests.consume.mock.calls[0][1]
+
+    await expect(consumer(message())).rejects.toStrictEqual(retry)
+  })
+})

package/test/presets.test.js

@@ -8,7 +8,8 @@ it('should define request preset', async () => {
     confirms: false,
     durable: true,
     acknowledgments: true,
-    persistent: false
+    persistent: false,
+    delay: [1000, 3000, 5000, 10000]
   })
 })
 
@@ -28,6 +29,7 @@ it('should define event preset', async () => {
     confirms: true,
     durable: true,
     acknowledgments: true,
-    persistent: true
+    persistent: true,
+    delay: [1000, 10000, 30000, 90000]
   })
 })

package/test/singleton.test.js

@@ -27,7 +27,7 @@ beforeEach(() => {
 
 it('should extend Connection', async () => {
   expect(connection).toBeInstanceOf(mock.Connection)
-  expect(mock.Connection.ctor).toHaveBeenCalledWith(url)
+  expect(mock.Connection.ctor).toHaveBeenCalledWith(url, {})
 })
 
 describe('connection', () => {

package/test/verdicts.test.js

@@ -0,0 +1,57 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Retry, Park, verdictOf, RETRY, PARK, VERDICT } = require('../source/verdicts')
+
+it('should be', async () => {
+  expect(Retry).toBeDefined()
+  expect(Park).toBeDefined()
+})
+
+describe('verdictOf', () => {
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['a string', 'nope'],
+    ['a plain Error', new Error(generate())],
+    ['an object branded with something else', { [Symbol.for('other.verdict')]: 'park' }],
+    ['an object whose brand is not a verdict', { [VERDICT]: generate() }]
+  ])('should read %s as a retry', async (_, exception) => {
+    expect(verdictOf(exception)).toStrictEqual(RETRY)
+  })
+
+  it('should read Retry as a retry', async () => {
+    expect(verdictOf(new Retry(generate()))).toStrictEqual(RETRY)
+  })
+
+  it('should read Park as a park', async () => {
+    expect(verdictOf(new Park(generate()))).toStrictEqual(PARK)
+  })
+
+  it('should read a Park thrown by another copy of comq', async () => {
+    // a dependency pinning comq while the application resolves its own tree makes two
+    // copies the ordinary outcome, and `instanceof` is silently false across them
+    const foreign = { [Symbol.for('comq.verdict')]: 'park' }
+
+    expect(verdictOf(foreign)).toStrictEqual(PARK)
+    expect(foreign instanceof Park).toStrictEqual(false)
+  })
+})
+
+describe('the classes', () => {
+  it.each([['Retry', Retry], ['Park', Park]])('should make %s an Error', async (name, Verdict) => {
+    const message = generate()
+    const verdict = new Verdict(message)
+
+    expect(verdict).toBeInstanceOf(Error)
+    expect(verdict.message).toStrictEqual(message)
+    expect(verdict.name).toStrictEqual(name)
+    expect(typeof verdict.stack).toStrictEqual('string')
+  })
+
+  it.each([['Retry', Retry], ['Park', Park]])('should let %s carry a cause', async (_, Verdict) => {
+    const cause = new Error(generate())
+
+    expect(new Verdict(generate(), { cause }).cause).toStrictEqual(cause)
+  })
+})

package/types/connection.d.ts

@@ -22,7 +22,12 @@ declare namespace comq {
     forget(event: _diagnostics.Event, listener: Function): void
   }
 
-  type Connect = (...urls: string[]) => Promise<_io.IO>
+  type Connect = {
+    (...urls: string[]): Promise<_io.IO>
+
+    /** The trailing argument overrides the topology presets, per channel type. */
+    (...args: [...urls: string[], overrides: _topology.Overrides]): Promise<_io.IO>
+  }
 
 }
 

package/types/diagnostic.d.ts

@@ -1,7 +1,7 @@
 declare namespace comq.diagnostics {
 
   type Event = 'open' | 'close' | 'error' | 'reconnect' | 'exhausted' | 'flow' | 'drain' |
-    'remove' | 'lost' | 'recover' | 'discard' | 'pause' | 'resume' | 'return'
+    'remove' | 'lost' | 'recover' | 'discard' | 'retry' | 'pause' | 'resume' | 'return'
 
   interface Diagnosable {
     diagnose(event: Event, listener: Function): void

package/types/index.d.ts

@@ -4,3 +4,20 @@ export type { IO, Consumer, Producer } from './io'
 
 export const connect: Connect
 export const assert: Connect
+
+/**
+ * Thrown by a consumer to say that whatever it needed was briefly not there. This is
+ * what an unclassified rejection already means, so throwing it changes nothing but the
+ * reader's certainty.
+ */
+export class Retry extends Error {}
+
+/**
+ * Thrown by a consumer to say that it will never process this message, however many
+ * times it is handed over. The message is kept rather than retried.
+ *
+ * Not applicable to a `Producer` given to `IO.reply`: a Request has a caller awaiting a
+ * reply, so a verdict is a category error there and the message is retried and parked on
+ * the count like any other failure.
+ */
+export class Park extends Error {}

package/types/io.d.ts

@@ -103,7 +103,9 @@ declare namespace comq {
 
     diagnose(event: 'recover', listener: (channel: _topology.type, index?: number) => void): void
 
-    diagnose(event: 'discard', listener: (channel: _topology.type, message: any, index?: number) => void): void
+    diagnose(event: 'discard', listener: (channel: _topology.type, message: any, error: Error, index?: number) => void): void
+
+    diagnose(event: 'retry', listener: (channel: _topology.type, message: any, error: Error, attempt: number, index?: number) => void): void
 
     diagnose(event: 'pause', listener: (channel: _topology.type) => void): void
 

package/types/topology.d.ts

@@ -8,6 +8,11 @@ declare namespace comq {
       [K in type]: Topology
     }
 
+    /** Per channel type overrides of the presets, as passed to `connect`. */
+    type Overrides = {
+      [K in type]?: Partial<Topology>
+    }
+
   }
 
   type Topology = {
@@ -16,8 +21,19 @@ declare namespace comq {
     durable: boolean
     acknowledgments: boolean
     persistent: boolean
+
+    /**
+     * How long a failed message waits before it is delivered again, in milliseconds:
+     * one entry per retry, so **the length of the ladder is the number of retries** and
+     * four rungs is five attempts. A bare number is a ladder of one, hence a single retry.
+     *
+     * Each distinct value is a retry queue of its own, because the wait is the queue's
+     * `x-message-ttl` rather than the message's, and a queue holds one of those.
+     */
+    delay: number | number[]
   }
 
 }
 
 export type type = comq.topology.type
+export type Overrides = comq.topology.Overrides