comq 0.26.0 → 0.28.0

package/source/shards/watch.js

@@ -1,257 +0,0 @@
-'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/test/shards/expand.test.js

@@ -1,58 +0,0 @@
-'use strict'
-
-const { expand } = require('../../source/shards/expand')
-
-it('should leave a url without a range as it is', async () => {
-  expect(expand('amqp://user:secret@rmq.example.com:5672/vhost?heartbeat=5'))
-    .toStrictEqual(['amqp://user:secret@rmq.example.com:5672/vhost?heartbeat=5'])
-})
-
-it('should expand a range, its end being exclusive', async () => {
-  expect(expand('amqp://rmq[0..3].example.com')).toStrictEqual([
-    'amqp://rmq0.example.com',
-    'amqp://rmq1.example.com',
-    'amqp://rmq2.example.com'
-  ])
-})
-
-it('should name as many hosts as the end of a range that starts at zero', async () => {
-  expect(expand('amqp://rmq[0..32].example.com')).toHaveLength(32)
-})
-
-it('should keep what surrounds the host', async () => {
-  expect(expand('amqps://user:secret@rmq-[1..3].example.com:5671/vhost?heartbeat=5')).toStrictEqual([
-    'amqps://user:secret@rmq-1.example.com:5671/vhost?heartbeat=5',
-    'amqps://user:secret@rmq-2.example.com:5671/vhost?heartbeat=5'
-  ])
-})
-
-it('should pad to the width the start is written with', async () => {
-  expect(expand('amqp://rmq[08..11]')).toStrictEqual(['amqp://rmq08', 'amqp://rmq09', 'amqp://rmq10'])
-})
-
-it('should expand every range', async () => {
-  expect(expand('amqp://rmq[0..2].zone[0..2]')).toStrictEqual([
-    'amqp://rmq0.zone0',
-    'amqp://rmq0.zone1',
-    'amqp://rmq1.zone0',
-    'amqp://rmq1.zone1'
-  ])
-})
-
-it('should leave an IPv6 literal alone', async () => {
-  expect(expand('amqp://[::1]:5672')).toStrictEqual(['amqp://[::1]:5672'])
-})
-
-it('should look at the host only', async () => {
-  const url = 'amqp://user:[0..2]@rmq.example.com/[0..2]?name=[0..2]'
-
-  expect(expand(url)).toStrictEqual([url])
-})
-
-it('should leave what is not a url as it is', async () => {
-  expect(expand('whatever')).toStrictEqual(['whatever'])
-})
-
-it.each(['[3..3]', '[3..1]'])('should refuse a range that names no hosts: %s', async (range) => {
-  expect(() => expand(`amqp://rmq${range}`)).toThrow(RangeError)
-})

package/test/shards/watch.test.js

@@ -1,264 +0,0 @@
-'use strict'
-
-const { Watch } = require('../../source/shards/watch')
-
-/** @type {Record<string, comq.shards.Resolution | Error>} */
-let records
-
-/** @type {Watch} */
-let watch
-
-/** @type {jest.MockedFunction<Function>} */
-let change
-
-/** @type {jest.MockedFunction<Function>} */
-let error
-
-const INTERVAL = 1000
-const SETTLE = 5000
-const hosts = ['one', 'two']
-
-const tick = (ms = INTERVAL) => jest.advanceTimersByTimeAsync(ms)
-
-/**
- * @param {comq.shards.Timing} [timing]
- * @param {(host: string) => boolean} [urgent]
- */
-async function start (timing = { interval: INTERVAL, settle: SETTLE }, urgent) {
-  watch = new Watch(hosts, timing, urgent)
-  change = jest.fn()
-  error = jest.fn()
-
-  watch.on('change', change)
-  watch.on('error', error)
-
-  return await watch.start()
-}
-
-beforeEach(() => {
-  jest.useFakeTimers()
-
-  records = { one: { addresses: ['10.0.0.1'], ttl: 5 }, two: { addresses: ['10.0.0.2'], ttl: 5 } }
-
-  global.COMQ_TESTING_LOOKUP = async (host) => {
-    if (records[host] instanceof Error) throw records[host]
-
-    return records[host]
-  }
-})
-
-afterEach(() => {
-  watch?.stop()
-  jest.useRealTimers()
-
-  delete global.COMQ_TESTING_LOOKUP
-})
-
-it('should tell the address of each name', async () => {
-  const addresses = await start()
-
-  expect(Object.fromEntries(addresses)).toStrictEqual({ one: '10.0.0.1', two: '10.0.0.2' })
-})
-
-it('should not tell of what has not changed', async () => {
-  await start()
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-})
-
-it('should tell of a change once it has held for the settle time', async () => {
-  await start()
-
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  await tick(SETTLE)
-
-  expect(change).not.toHaveBeenCalled()
-
-  await tick()
-
-  expect(change).toHaveBeenCalledTimes(1)
-  expect(Object.fromEntries(change.mock.calls[0][0])).toStrictEqual({ one: '10.0.0.1', two: '10.0.0.3' })
-})
-
-it('should start the settle time anew whenever the answer changes', async () => {
-  await start()
-
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  await tick(SETTLE - INTERVAL)
-
-  records.one = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  await tick(SETTLE - INTERVAL)
-
-  expect(change).not.toHaveBeenCalled()
-
-  await tick(INTERVAL * 2)
-
-  expect(change).toHaveBeenCalledTimes(1)
-  expect(Object.fromEntries(change.mock.calls[0][0])).toStrictEqual({ one: '10.0.0.3', two: '10.0.0.3' })
-})
-
-it('should not act on an answer that goes back and forth', async () => {
-  await start()
-
-  for (let i = 0; i < 20; i++) {
-    records.two = { addresses: [i % 2 === 0 ? '10.0.0.3' : '10.0.0.2'], ttl: 5 }
-
-    await tick()
-  }
-
-  expect(change).not.toHaveBeenCalled()
-})
-
-it('should forget a change that was taken back', async () => {
-  await start()
-
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  await tick(INTERVAL * 2)
-
-  records.two = { addresses: ['10.0.0.2'], ttl: 5 }
-
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-})
-
-it('should keep the address of a name that fails to resolve', async () => {
-  await start()
-
-  const exception = new Error('ENOTFOUND')
-
-  records.two = exception
-
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-  expect(error).toHaveBeenCalledWith(exception)
-})
-
-it('should keep the address of a name that resolves to nothing', async () => {
-  await start()
-
-  records.two = { addresses: [] }
-
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-  expect(error).toHaveBeenCalled()
-})
-
-it('should keep the address in use while it is listed', async () => {
-  await start()
-
-  records.two = { addresses: ['10.0.0.1', '10.0.0.2'], ttl: 5 }
-
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-})
-
-it('should take what an urgent name resolves to at once', async () => {
-  await start(undefined, (host) => host === 'two')
-
-  records.one = { addresses: ['10.0.0.4'], ttl: 5 }
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  await tick()
-
-  expect(change).toHaveBeenCalledTimes(1)
-  expect(Object.fromEntries(change.mock.calls[0][0])).toStrictEqual({ one: '10.0.0.1', two: '10.0.0.3' })
-})
-
-it('should look at once when poked', async () => {
-  await start(undefined, () => true)
-
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-
-  watch.poke()
-
-  await tick(0)
-
-  expect(change).toHaveBeenCalledTimes(1)
-})
-
-it('should resolve until every name is known', async () => {
-  global.COMQ_TESTING_RESOLVE_BACKOFF = { base: 10, dispersion: 0 }
-
-  records.two = new Error('ENOTFOUND')
-
-  let addresses
-
-  const starting = start().then((result) => { addresses = result })
-
-  await tick(100)
-
-  expect(addresses).toBeUndefined()
-
-  records.two = { addresses: ['10.0.0.2'], ttl: 5 }
-
-  await tick(100)
-  await starting
-
-  expect(addresses.get('two')).toStrictEqual('10.0.0.2')
-
-  delete global.COMQ_TESTING_RESOLVE_BACKOFF
-})
-
-it('should stop', async () => {
-  await start()
-
-  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
-  watch.stop()
-
-  await tick(SETTLE * 2)
-
-  expect(change).not.toHaveBeenCalled()
-  expect(jest.getTimerCount()).toStrictEqual(0)
-})
-
-describe('timing', () => {
-  it('should settle and linger for the longest TTL seen', async () => {
-    records.one = { addresses: ['10.0.0.1'], ttl: 300 }
-    records.two = { addresses: ['10.0.0.2'], ttl: 120 }
-
-    await start({})
-
-    records.one = { addresses: ['10.0.0.1'], ttl: 10 }
-
-    await tick(10_000)
-
-    expect(watch.settle).toStrictEqual(300_000)
-    expect(watch.linger).toStrictEqual(300_000)
-  })
-
-  it('should settle for no less than 30 seconds', async () => {
-    await start({})
-
-    expect(watch.settle).toStrictEqual(30_000)
-    expect(watch.linger).toStrictEqual(30_000)
-  })
-
-  it('should give a name answered without a TTL 60 seconds', async () => {
-    records.two = { addresses: ['10.0.0.2'] }
-
-    await start({})
-
-    expect(watch.settle).toStrictEqual(60_000)
-  })
-
-  it('should resolve every 10 seconds unless told otherwise', async () => {
-    await start({})
-
-    expect(watch.interval).toStrictEqual(10_000)
-  })
-
-  it('should take what it is told', async () => {
-    await start({ interval: 1, settle: 2, linger: 3 })
-
-    expect([watch.interval, watch.settle, watch.linger]).toStrictEqual([1, 2, 3])
-  })
-})