comq 0.25.1 → 0.26.0

package/source/shards/watch.js

@@ -0,0 +1,257 @@
+'use strict'
+
+const { retry } = require('../retry')
+const emitter = require('../emitter')
+const { resolve, choose } = require('./resolve')
+
+/**
+ * Watches what a set of names resolve to, and tells once it has changed for good.
+ *
+ * A change is seldom seen whole. Records are updated one after another, and until their TTL has
+ * run out the caches on the way answer with the old address and the new one in turn. So what is
+ * observed is a candidate, and it replaces what is in effect only once it has been observed
+ * unchanged for the settle time; anything else observed in between starts that time anew.
+ */
+class Watch {
+  /** @type {string[]} */
+  #hosts
+
+  /** @type {comq.shards.Timing} */
+  #options
+
+  /** @type {(host: string) => boolean} */
+  #urgent
+
+  /** @type {Map<string, string>} what is in effect */
+  #current = new Map()
+
+  /** @type {Map<string, string>} what was observed last */
+  #candidate = new Map()
+
+  /** @type {number} when the candidate was first observed as it is */
+  #since = 0
+
+  /** @type {number} the longest TTL any name has been answered with, in seconds */
+  #ttl = 0
+
+  /** @type {boolean} whether a name was answered without a TTL */
+  #untimed = false
+
+  /** @type {ReturnType<setTimeout> | undefined} */
+  #timer
+
+  #polling = false
+  #poked = false
+  #stopped = false
+
+  #events = emitter.create()
+
+  /**
+   * @param {string[]} hosts
+   * @param {comq.shards.Timing} [options]
+   * @param {(host: string) => boolean} [urgent] whether a name is of no use as it is resolved
+   * now, so that what it resolves to next is taken at once
+   */
+  constructor (hosts, options = {}, urgent = () => false) {
+    this.#hosts = Array.from(new Set(hosts))
+    this.#options = options
+    this.#urgent = urgent
+  }
+
+  get interval () {
+    return this.#options.interval ?? INTERVAL_MS
+  }
+
+  /**
+   * How long an answer is to hold before it is acted upon. A TTL bounds how long a cache may
+   * answer with what is no longer true, and says nothing about records that are being updated
+   * one by one, hence the floor.
+   */
+  get settle () {
+    return this.#options.settle ?? this.#period()
+  }
+
+  /** How long a broker no name points at is to stay idle before it is left. */
+  get linger () {
+    return this.#options.linger ?? this.#period()
+  }
+
+  /**
+   * Resolves every name, as many times as it takes: a name that does not resolve is no more a
+   * reason to give up than a broker that is not up yet.
+   *
+   * @return {Promise<Map<string, string>>} the address of each name
+   */
+  async start () {
+    this.#stopped = false
+
+    await retry(async (again) => {
+      if (this.#stopped) return
+
+      const [observed, failed] = await this.#observe()
+
+      if (failed) return again
+
+      this.#current = observed
+      this.#candidate = observed
+      this.#since = Date.now()
+    }, global.COMQ_TESTING_RESOLVE_BACKOFF)
+
+    this.#schedule()
+
+    return new Map(this.#current)
+  }
+
+  stop () {
+    this.#stopped = true
+
+    clearTimeout(this.#timer)
+  }
+
+  /**
+   * Looks now rather than when the interval is up.
+   */
+  poke () {
+    if (this.#stopped) return
+
+    if (this.#polling) {
+      this.#poked = true
+
+      return
+    }
+
+    clearTimeout(this.#timer)
+
+    this.#poll().catch(noop)
+  }
+
+  /**
+   * @param {'change' | 'error'} event
+   * @param {Function} listener
+   */
+  on (event, listener) {
+    this.#events.on(event, listener)
+  }
+
+  #schedule () {
+    if (this.#stopped || this.#hosts.length === 0) return
+
+    this.#timer = setTimeout(() => this.#poll().catch(noop), this.interval)
+    this.#timer.unref()
+  }
+
+  async #poll () {
+    this.#polling = true
+
+    try {
+      const [observed] = await this.#observe()
+
+      if (!this.#stopped) this.#consider(observed)
+    } finally {
+      this.#polling = false
+    }
+
+    if (this.#poked) {
+      this.#poked = false
+
+      return await this.#poll()
+    }
+
+    this.#schedule()
+  }
+
+  /**
+   * @param {Map<string, string>} observed
+   */
+  #consider (observed) {
+    const now = Date.now()
+
+    if (!same(observed, this.#candidate)) {
+      this.#candidate = observed
+      this.#since = now
+    }
+
+    const settled = now - this.#since >= this.settle
+
+    let changed = false
+
+    for (const [host, address] of this.#candidate) {
+      if (address === this.#current.get(host)) continue
+      if (!settled && !this.#urgent(host)) continue
+
+      this.#current.set(host, address)
+
+      changed = true
+    }
+
+    if (changed) this.#events.emit('change', new Map(this.#current))
+  }
+
+  /**
+   * A name that fails to resolve keeps the address it was observed with: a resolver that is
+   * briefly out of reach has not said that the name is gone.
+   *
+   * @return {Promise<[Map<string, string>, boolean]>} the address of each name, and whether any
+   * of them is not known
+   */
+  async #observe () {
+    const observed = new Map()
+
+    let failed = false
+
+    await Promise.all(this.#hosts.map(async (host) => {
+      try {
+        const { addresses, ttl } = await resolve(host)
+
+        if (addresses.length === 0) throw new Error(`${host} resolves to no address`)
+
+        if (ttl === undefined) this.#untimed = true
+        else this.#ttl = Math.max(this.#ttl, ttl)
+
+        observed.set(host, choose(addresses, this.#current.get(host)))
+      } catch (exception) {
+        this.#events.emit('error', exception)
+
+        if (this.#candidate.has(host)) observed.set(host, this.#candidate.get(host))
+        else failed = true
+      }
+    }))
+
+    return [observed, failed]
+  }
+
+  /**
+   * A cache answers with the time its record has left, so the longest ever seen is the closest
+   * to what the record was published with.
+   *
+   * @return {number}
+   */
+  #period () {
+    return Math.max(FLOOR_MS, this.#ttl * 1000, this.#untimed ? UNTIMED_MS : 0)
+  }
+}
+
+/**
+ * @param {Map<string, string>} one
+ * @param {Map<string, string>} another
+ * @return {boolean}
+ */
+function same (one, another) {
+  if (one.size !== another.size) return false
+
+  for (const [host, address] of one) if (another.get(host) !== address) return false
+
+  return true
+}
+
+const INTERVAL_MS = 10_000
+
+/** No TTL is short enough to act on at once. */
+const FLOOR_MS = 30_000
+
+/** What a name answered without a TTL is given. */
+const UNTIMED_MS = 60_000
+
+function noop () {}
+
+exports.Watch = Watch

package/source/singleton.js

@@ -19,8 +19,9 @@ class SingletonConnection extends Connection {
    *
    * @param {string} url
    * @param {comq.topology.Overrides} [overrides]
+   * @param {string} [servername]
    */
-  constructor (url, overrides = {}) {
+  constructor (url, overrides = {}, servername = undefined) {
     const instance = instances.get(url)
 
     if (instance !== undefined) {
@@ -31,7 +32,7 @@ class SingletonConnection extends Connection {
       return instance
     }
 
-    super(url, overrides)
+    super(url, overrides, servername)
 
     this.#url = url
     this.#overrides = overrides

package/test/amqplib.mock.js

@@ -13,6 +13,7 @@ class Channel extends EventEmitter {
   nack = jest.fn(() => undefined)
   assertQueue = jest.fn(async (name) => ({ queue: name ?? generate() }))
   assertExchange = jest.fn(async () => undefined)
+  checkQueue = jest.fn(async (name) => ({ queue: name, messageCount: 0 }))
   bindQueue = jest.fn(async () => undefined)
   unbindQueue = jest.fn(async () => undefined)
   publish = jest.fn((_0, _1, _2, _3, resolve) => resolve?.(null))

package/test/assert.test.js

@@ -50,9 +50,14 @@ it('should create sharded connection', async () => {
 
   io = await assert(...urls)
 
-  for (const url of urls) expect(SingletonConnection).toHaveBeenCalledWith(url, {})
+  expect(shards.Connection).toHaveBeenCalledWith(urls, expect.any(Function), undefined)
+
+  // a connection to a broker is shared, as one to a single URL is
+  const make = shards.Connection.mock.calls[0][1]
+
+  for (const url of urls) make(url)
+  for (const url of urls) expect(SingletonConnection).toHaveBeenCalledWith(url, {}, undefined)
 
-  expect(shards.Connection).toHaveBeenCalledWith(SingletonConnection.mock.instances)
   expect(IO).toHaveBeenCalledWith(shards.Connection.mock.instances[0])
   expect(io).toStrictEqual(IO.mock.instances[0])
 })

package/test/channel.quiet.test.js

@@ -0,0 +1,301 @@
+'use strict'
+
+const { randomBytes } = require('node:crypto')
+const { generate } = require('randomstring')
+const { Promex } = require('../source/promex')
+const { immediate } = require('./helpers')
+
+const { amqplib } = require('./amqplib.mock')
+const { create } = require('../source/channel')
+
+/** @type {jest.MockedObject<comq.amqp.Connection>} */
+let connection
+
+/** @type {comq.Channel} */
+let channel
+
+/** @type {jest.MockedObject<comq.amqp.Channel>} */
+let chan
+
+/** @type {jest.MockedObject<comq.amqp.Channel>[]} */
+let probes
+
+const queue = generate()
+const message = () => ({ content: randomBytes(8), properties: {}, fields: {} })
+
+/**
+ * @param {Partial<comq.Topology>} [topology]
+ */
+async function open (topology = {}) {
+  connection = await amqplib.connect()
+
+  channel = await create(connection, {
+    prefetch: 1,
+    confirms: true,
+    durable: true,
+    acknowledgments: true,
+    persistent: true,
+    delay: [1000],
+    ...topology
+  })
+
+  chan = await connection.createConfirmChannel.mock.results[0].value
+}
+
+const deliver = (message) => chan.consume.mock.calls.at(-1)[1](message)
+
+/**
+ * A probe is a channel of its own, the one made last.
+ *
+ * @param {number} messageCount
+ */
+function depth (messageCount) {
+  connection.createChannel.mockImplementation(async () => {
+    const probe = await connection.createConfirmChannel.getMockImplementation()()
+
+    probe.checkQueue.mockImplementation(async (name) => ({ queue: name, messageCount }))
+    probes.push(probe)
+
+    return probe
+  })
+}
+
+const REAL = ['nextTick', 'setImmediate', 'clearImmediate', 'setTimeout', 'clearTimeout',
+  'setInterval', 'clearInterval', 'queueMicrotask']
+
+beforeEach(async () => {
+  jest.clearAllMocks()
+
+  probes = []
+
+  // the clock alone: what is awaited here goes through timers of its own
+  jest.useFakeTimers({ now: 1_000_000, doNotFake: REAL })
+
+  await open()
+})
+
+afterEach(() => {
+  jest.useRealTimers()
+})
+
+describe('quiet', () => {
+  it('should have had nothing to do ever, when nothing happened', async () => {
+    await expect(channel.quiet()).resolves.toStrictEqual(0)
+  })
+
+  it('should have something to do while a delivery is with its consumer', async () => {
+    const consuming = new Promex()
+
+    await channel.consume(queue, () => consuming)
+
+    const delivering = deliver(message())
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+
+    consuming.resolve()
+
+    await delivering
+  })
+
+  it('should tell when the last delivery was done with', async () => {
+    await channel.consume(queue, async () => undefined)
+    await deliver(message())
+
+    const done = Date.now()
+
+    jest.advanceTimersByTime(5000)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(done)
+  })
+
+  it('should count a delivery nothing is acknowledged for', async () => {
+    const consuming = new Promex()
+
+    await open({ acknowledgments: false })
+    await channel.consume(queue, () => consuming)
+
+    deliver(message())
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+
+    consuming.resolve()
+
+    await immediate()
+
+    jest.advanceTimersByTime(5000)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now() - 5000)
+  })
+
+  it('should hand back what a consumer nothing is acknowledged for returns', async () => {
+    await open({ acknowledgments: false })
+
+    const consumer = jest.fn(() => undefined)
+
+    await channel.consume(queue, consumer)
+
+    const one = message()
+
+    expect(deliver(one)).toBeUndefined()
+    expect(consumer).toHaveBeenCalledWith(one)
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+  })
+
+  it('should have something to do while a publication awaits its confirmation', async () => {
+    let confirm
+
+    chan.publish.mockImplementation((_0, _1, _2, _3, callback) => { confirm = callback })
+
+    const sending = channel.send(queue, randomBytes(8))
+
+    await immediate()
+
+    jest.advanceTimersByTime(5000)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+
+    confirm(null)
+
+    await sending
+  })
+
+  it('should tell when a message was last published', async () => {
+    await channel.send(queue, randomBytes(8))
+
+    const published = Date.now()
+
+    jest.advanceTimersByTime(5000)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(published)
+  })
+
+  it('should have something to do until a failed message is delivered again', async () => {
+    await channel.consume(queue, async () => { throw new Error('oops') })
+    await deliver(message())
+
+    const back = Date.now() + 1000
+
+    jest.advanceTimersByTime(999)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+
+    jest.advanceTimersByTime(2)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(back)
+  })
+
+  it('should have something to do while a queue it consumes holds messages', async () => {
+    await channel.consume(queue, async () => undefined)
+
+    depth(3)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+
+    expect(probes[0].checkQueue).toHaveBeenCalledWith(queue)
+  })
+
+  it('should not ask of queues when it consumes none', async () => {
+    await channel.quiet()
+
+    expect(connection.createChannel).not.toHaveBeenCalled()
+  })
+
+  it('should take a queue that is gone for an empty one', async () => {
+    await channel.consume(queue, async () => undefined)
+
+    connection.createChannel.mockImplementation(async () => {
+      const probe = await connection.createConfirmChannel.getMockImplementation()()
+
+      probe.checkQueue.mockImplementation(async () => {
+        probe.emit('error', Object.assign(new Error('NOT_FOUND'), { code: 404 }))
+
+        throw new Error('Channel closed by server')
+      })
+
+      return probe
+    })
+
+    await expect(channel.quiet()).resolves.toStrictEqual(0)
+  })
+
+  it('should have something to do when it cannot be told', async () => {
+    await channel.consume(queue, async () => undefined)
+
+    connection.createChannel.mockImplementation(async () => { throw new Error('Connection closed') })
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+  })
+
+  it('should ask of what is consumed again once the connection is restored', async () => {
+    await channel.consume(queue, async () => undefined)
+
+    const restored = await amqplib.connect()
+
+    await channel.recover(restored)
+
+    connection = restored
+    depth(3)
+
+    await expect(channel.quiet()).resolves.toStrictEqual(Date.now())
+    expect(probes[0].checkQueue).toHaveBeenCalledWith(queue)
+  })
+})
+
+describe('settled', () => {
+  it('should resolve when there is nothing to wait for', async () => {
+    await expect(channel.settled()).resolves.toBeUndefined()
+  })
+
+  it('should wait for the deliveries that are with their consumers', async () => {
+    const consuming = [new Promex(), new Promex()]
+
+    let n = 0
+    let settled = false
+
+    await channel.consume(queue, () => consuming[n++])
+
+    const delivering = [deliver(message()), deliver(message())]
+
+    channel.settled().then(() => { settled = true })
+
+    await immediate()
+
+    consuming[0].resolve()
+
+    await delivering[0]
+    await immediate()
+
+    expect(settled).toStrictEqual(false)
+
+    consuming[1].resolve()
+
+    await delivering[1]
+    await immediate()
+
+    expect(settled).toStrictEqual(true)
+  })
+
+  it('should wait for the publications that await their confirmation', async () => {
+    let confirm
+    let settled = false
+
+    chan.publish.mockImplementation((_0, _1, _2, _3, callback) => { confirm = callback })
+
+    const sending = channel.send(queue, randomBytes(8))
+
+    await immediate()
+
+    channel.settled().then(() => { settled = true })
+
+    await immediate()
+
+    expect(settled).toStrictEqual(false)
+
+    confirm(null)
+
+    await sending
+    await immediate()
+
+    expect(settled).toStrictEqual(true)
+  })
+})

package/test/connect.test.js

@@ -61,12 +61,52 @@ describe('sharded connection', () => {
     expect(shards.Connection).toHaveBeenCalled()
   })
 
-  it('should pass single connection instances', async () => {
-    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, {}))
+  it('should pass the urls, and what makes a connection to a broker', async () => {
+    expect(shards.Connection).toHaveBeenCalledWith(urls, expect.any(Function), undefined)
 
-    const instances = Connection.mock.instances
+    const make = shards.Connection.mock.calls[0][1]
+    const servername = generate()
+    const instance = make(urls[0], servername)
 
-    expect(shards.Connection).toHaveBeenCalledWith(instances)
+    expect(Connection).toHaveBeenCalledWith(urls[0], {}, servername)
+    expect(instance).toStrictEqual(Connection.mock.instances[0])
+  })
+
+  it('should not connect by itself', async () => {
+    expect(Connection).not.toHaveBeenCalled()
+  })
+})
+
+describe('ranges', () => {
+  it('should expand a range into the urls of a sharded connection', async () => {
+    await connect('amqp://rmq[0..3].example.com')
+
+    const expanded = ['amqp://rmq0.example.com', 'amqp://rmq1.example.com', 'amqp://rmq2.example.com']
+
+    expect(shards.Connection).toHaveBeenCalledWith(expanded, expect.any(Function), undefined)
+  })
+
+  it('should connect to a range of one as to a single url', async () => {
+    await connect('amqp://rmq[0..1].example.com')
+
+    expect(Connection).toHaveBeenCalledWith('amqp://rmq0.example.com', {})
+    expect(shards.Connection).not.toHaveBeenCalled()
+  })
+})
+
+describe('resolution', () => {
+  it('should pass how the names are followed, apart from the overrides', async () => {
+    const urls = [generate(), generate()]
+    const resolution = { interval: 1, settle: 2, linger: 3 }
+    const overrides = { event: { delay: 100 } }
+
+    await connect(...urls, { ...overrides, resolution })
+
+    expect(shards.Connection).toHaveBeenCalledWith(urls, expect.any(Function), resolution)
+
+    shards.Connection.mock.calls[0][1](urls[0])
+
+    expect(Connection).toHaveBeenCalledWith(urls[0], overrides, undefined)
   })
 })
 
@@ -85,8 +125,10 @@ describe('topology overrides', () => {
 
     await connect(...urls, overrides)
 
-    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, overrides))
-    expect(shards.Connection).toHaveBeenCalled()
+    const make = shards.Connection.mock.calls[0][1]
+
+    urls.forEach((url) => make(url))
+    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, overrides, undefined))
   })
 
   it('should not take a url as overrides', async () => {
@@ -94,7 +136,6 @@ describe('topology overrides', () => {
 
     await connect(...urls)
 
-    expect(Connection).toHaveBeenCalledTimes(2)
-    urls.forEach((url) => expect(Connection).toHaveBeenCalledWith(url, {}))
+    expect(shards.Connection).toHaveBeenCalledWith(urls, expect.any(Function), undefined)
   })
 })

package/test/connection.mock.js

@@ -17,6 +17,9 @@ const channel = /** @type {jest.MockedFunction<(sharded?: boolean, index?: numbe
     diagnose: jest.fn(async () => undefined),
     forget: jest.fn(() => undefined),
     seal: jest.fn(async () => undefined),
+    settled: jest.fn(async () => undefined),
+    quiet: jest.fn(async () => 0),
+    occupy: jest.fn(() => undefined),
     close: jest.fn(async () => undefined),
     closed: false,
     recover: jest.fn(async () => undefined)