comq 0.27.0 → 0.28.0

package/test/shards/name.test.js

@@ -0,0 +1,348 @@
+'use strict'
+
+const { Name } = require('../../source/shards/name')
+
+/** @type {Record<string, comq.shards.Resolution | Error>} */
+let records
+
+/** @type {Record<string, number>} how many times each name has been resolved */
+let resolved
+
+/** @type {Name} */
+let name
+
+/** @type {comq.shards.Follower & Record<string, jest.MockedFunction<any>>} */
+let follower
+
+/** @type {() => void} */
+let leave
+
+const INTERVAL = 1000
+const SETTLE = 5000
+const timing = { interval: INTERVAL, settle: SETTLE }
+
+const tick = (ms = INTERVAL) => jest.advanceTimersByTimeAsync(ms)
+
+/**
+ * @param {boolean} [urgent]
+ * @return {comq.shards.Follower & Record<string, jest.MockedFunction<any>>}
+ */
+const followerOf = (urgent = false) => ({ change: jest.fn(), error: jest.fn(), urgent: jest.fn(() => urgent) })
+
+/**
+ * @param {comq.shards.Timing} [options]
+ * @param {boolean} [urgent]
+ */
+async function start (options = timing, urgent = false) {
+  name = Name.of('two', options)
+  follower = followerOf(urgent)
+  leave = name.follow(follower)
+
+  return await name.start()
+}
+
+beforeEach(() => {
+  jest.useFakeTimers()
+
+  records = { one: { addresses: ['10.0.0.1'], ttl: 5 }, two: { addresses: ['10.0.0.2'], ttl: 5 } }
+  resolved = { one: 0, two: 0 }
+
+  global.COMQ_TESTING_LOOKUP = async (host) => {
+    resolved[host]++
+
+    if (records[host] instanceof Error) throw records[host]
+
+    return records[host]
+  }
+})
+
+afterEach(() => {
+  Name.__lets_pretend_this_method_doesnt_exist()
+  jest.useRealTimers()
+
+  delete global.COMQ_TESTING_LOOKUP
+})
+
+it('should tell the address of the name', async () => {
+  const address = await start()
+
+  expect(address).toStrictEqual('10.0.0.2')
+})
+
+it('should not tell of what has not changed', async () => {
+  await start()
+  await tick(SETTLE * 2)
+
+  expect(follower.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(follower.change).not.toHaveBeenCalled()
+
+  await tick()
+
+  expect(follower.change).toHaveBeenCalledTimes(1)
+  expect(follower.change).toHaveBeenCalledWith('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.two = { addresses: ['10.0.0.4'], ttl: 5 }
+
+  await tick(SETTLE - INTERVAL)
+
+  expect(follower.change).not.toHaveBeenCalled()
+
+  await tick(INTERVAL * 2)
+
+  expect(follower.change).toHaveBeenCalledTimes(1)
+  expect(follower.change).toHaveBeenCalledWith('two', '10.0.0.4')
+})
+
+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(follower.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(follower.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(follower.change).not.toHaveBeenCalled()
+  expect(follower.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(follower.change).not.toHaveBeenCalled()
+  expect(follower.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(follower.change).not.toHaveBeenCalled()
+})
+
+it('should take what an urgent name resolves to at once', async () => {
+  await start(timing, true)
+
+  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+  await tick()
+
+  expect(follower.change).toHaveBeenCalledWith('two', '10.0.0.3')
+  expect(follower.urgent).toHaveBeenCalledWith('two')
+})
+
+it('should look at once when poked', async () => {
+  await start(timing, true)
+
+  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+  name.poke()
+
+  await tick(0)
+
+  expect(follower.change).toHaveBeenCalledTimes(1)
+})
+
+it('should resolve until the name is known', async () => {
+  global.COMQ_TESTING_RESOLVE_BACKOFF = { base: 10, dispersion: 0 }
+
+  records.two = new Error('ENOTFOUND')
+
+  let address
+
+  const starting = start().then((result) => { address = result })
+
+  await tick(100)
+
+  expect(address).toBeUndefined()
+
+  records.two = { addresses: ['10.0.0.2'], ttl: 5 }
+
+  await tick(100)
+  await starting
+
+  expect(address).toStrictEqual('10.0.0.2')
+
+  delete global.COMQ_TESTING_RESOLVE_BACKOFF
+})
+
+it('should stop once nobody follows it', async () => {
+  await start()
+
+  records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+  leave()
+
+  await tick(SETTLE * 2)
+
+  expect(follower.change).not.toHaveBeenCalled()
+  expect(jest.getTimerCount()).toStrictEqual(0)
+  expect(Name.of('two', timing)).not.toBe(name)
+})
+
+describe('shared', () => {
+  it('should be one for everyone with the same timing', async () => {
+    expect(Name.of('two', timing)).toBe(Name.of('two', { ...timing }))
+    expect(Name.of('two', timing)).not.toBe(Name.of('two', { interval: INTERVAL * 2 }))
+    expect(Name.of('two', timing)).not.toBe(Name.of('one', timing))
+  })
+
+  it('should be resolved once however many follow it', async () => {
+    await start()
+
+    const others = Array.from({ length: 10 }, () => followerOf())
+
+    for (const other of others) Name.of('two', timing).follow(other)
+
+    await Promise.all(others.map(() => Name.of('two', timing).start()))
+
+    expect(resolved.two).toStrictEqual(1)
+
+    await tick(INTERVAL * 3)
+
+    expect(resolved.two).toStrictEqual(4)
+  })
+
+  it('should tell everyone who follows it of a change', async () => {
+    await start()
+
+    const other = followerOf()
+
+    Name.of('two', timing).follow(other)
+    records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+    await tick(SETTLE + INTERVAL)
+
+    expect(follower.change).toHaveBeenCalledWith('two', '10.0.0.3')
+    expect(other.change).toHaveBeenCalledWith('two', '10.0.0.3')
+  })
+
+  it('should tell one who comes later what is in effect', async () => {
+    await start()
+
+    records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+    await tick(SETTLE + INTERVAL)
+
+    Name.of('two', timing).follow(followerOf())
+
+    expect(await Name.of('two', timing).start()).toStrictEqual('10.0.0.3')
+  })
+
+  it('should be urgent for everyone when it is for one of them', async () => {
+    await start()
+
+    Name.of('two', timing).follow(followerOf(true))
+    records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+    await tick()
+
+    expect(follower.change).toHaveBeenCalledWith('two', '10.0.0.3')
+  })
+
+  it('should go on while anyone follows it', async () => {
+    await start()
+
+    const other = followerOf()
+
+    Name.of('two', timing).follow(other)
+    leave()
+
+    records.two = { addresses: ['10.0.0.3'], ttl: 5 }
+
+    await tick(SETTLE + INTERVAL)
+
+    expect(other.change).toHaveBeenCalledWith('two', '10.0.0.3')
+    expect(follower.change).not.toHaveBeenCalled()
+  })
+})
+
+describe('timing', () => {
+  it('should settle for the longest TTL seen', async () => {
+    records.two = { addresses: ['10.0.0.2'], ttl: 3600 }
+
+    await start({})
+
+    records.two = { addresses: ['10.0.0.2'], ttl: 10 }
+
+    await tick(300_000)
+
+    expect(name.settle).toStrictEqual(3_600_000)
+    expect(name.period).toStrictEqual(3_600_000)
+  })
+
+  it('should settle for no less than 15 minutes', async () => {
+    await start({})
+
+    expect(name.settle).toStrictEqual(900_000)
+  })
+
+  it('should give a name answered without a TTL 30 minutes', async () => {
+    records.two = { addresses: ['10.0.0.2'] }
+
+    await start({})
+
+    expect(name.settle).toStrictEqual(1_800_000)
+  })
+
+  it('should resolve every 5 minutes unless told otherwise', async () => {
+    await start({})
+
+    expect(name.interval).toStrictEqual(300_000)
+  })
+
+  it('should take what it is told', async () => {
+    await start({ interval: 1, settle: 2 })
+
+    expect([name.interval, name.settle]).toStrictEqual([1, 2])
+  })
+})

package/test/shards/resolve.test.js

@@ -1,6 +1,52 @@
 'use strict'
 
-const { choose, hostOf, locate } = require('../../source/shards/resolve')
+const dns = require('node:dns').promises
+const { resolve, choose, hostOf, locate } = require('../../source/shards/resolve')
+
+describe('resolve', () => {
+  /** @type {Record<string, jest.MockedFunction<any>>} */
+  let spies
+
+  /**
+   * @param {Array<{ address: string, ttl: number }> | Error} v4
+   * @param {Array<{ address: string, ttl: number }> | Error} v6
+   * @param {Array<{ address: string }>} [found]
+   */
+  const answer = (v4, v6, found = []) => {
+    const respond = (value) => async () => { if (value instanceof Error) throw value; return value }
+
+    spies = {
+      resolve4: jest.spyOn(dns, 'resolve4').mockImplementation(respond(v4)),
+      resolve6: jest.spyOn(dns, 'resolve6').mockImplementation(respond(v6)),
+      lookup: jest.spyOn(dns, 'lookup').mockImplementation(respond(found))
+    }
+  }
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('should not ask for IPv6 addresses of a name that has IPv4 ones', async () => {
+    answer([{ address: '10.0.0.1', ttl: 30 }, { address: '10.0.0.2', ttl: 10 }], [{ address: '::1', ttl: 30 }])
+
+    expect(await resolve('rmq.example.com')).toStrictEqual({ addresses: ['10.0.0.1', '10.0.0.2'], ttl: 30 })
+    expect(spies.resolve6).not.toHaveBeenCalled()
+    expect(spies.lookup).not.toHaveBeenCalled()
+  })
+
+  it('should ask for IPv6 addresses of a name that has no IPv4 ones', async () => {
+    answer(Object.assign(new Error('ENODATA'), { code: 'ENODATA' }), [{ address: '::1', ttl: 30 }])
+
+    expect(await resolve('rmq.example.com')).toStrictEqual({ addresses: ['::1'], ttl: 30 })
+    expect(spies.lookup).not.toHaveBeenCalled()
+  })
+
+  it('should look up a name that DNS does not know, with no TTL', async () => {
+    answer(new Error('ENOTFOUND'), new Error('ENOTFOUND'), [{ address: '127.0.0.1' }])
+
+    expect(await resolve('localhost')).toStrictEqual({ addresses: ['127.0.0.1'] })
+  })
+})
 
 describe('choose', () => {
   it('should choose the same address whichever order they came in', async () => {

package/types/shards.d.ts

@@ -5,11 +5,12 @@ declare namespace comq {
   namespace shards {
 
     /**
-     * How the names of the shards are followed, in milliseconds. `settle` and `linger` default
-     * to the longest TTL the names are answered with, and to no less than 30 seconds.
+     * How the names of the shards are followed, in milliseconds. `settle` defaults to the longest
+     * TTL the name is answered with, `linger` to the longest of the names, and both to no less
+     * than 15 minutes.
      */
     type Timing = {
-      /** how often the names are resolved, 10 seconds by default */
+      /** how often the names are resolved, 5 minutes by default */
       interval?: number
 
       /** how long an answer is to hold before a broker is joined or retired on it */
@@ -19,6 +20,18 @@ declare namespace comq {
       linger?: number
     }
 
+    /** Who follows a name, which is shared by everyone in the process who stands on it. */
+    type Follower = {
+      /** what the name stands for has changed for good */
+      change (host: string, address: string): void
+
+      /** the name failed to resolve, and keeps its address */
+      error (exception: Error): void
+
+      /** whether the name is of no use as it is resolved now, so that its next answer is taken at once */
+      urgent (host: string): boolean
+    }
+
     type Resolution = {
       addresses: string[]
 

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