comq 0.27.0 → 0.28.0

package/source/shards/name.js

@@ -0,0 +1,299 @@
+'use strict'
+
+const { retry } = require('../retry')
+const { resolve, choose } = require('./resolve')
+
+/**
+ * Follows what one name resolves to, for everyone in the process who follows it: a name is
+ * resolved once however many connections stand on it, and tells each of them when 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 Name {
+  /** @type {string} */
+  #host
+
+  /** @type {comq.shards.Timing} */
+  #options
+
+  /** @type {string} what the registry knows it by */
+  #key
+
+  /** @type {Set<comq.shards.Follower>} */
+  #followers = new Set()
+
+  /** @type {string | undefined} what is in effect */
+  #current
+
+  /** @type {string | undefined} what was observed last */
+  #candidate
+
+  /** @type {number} when the candidate was first observed as it is */
+  #since = 0
+
+  /** @type {number} the longest TTL the name has been answered with, in seconds */
+  #ttl = 0
+
+  /** @type {boolean} whether the name was answered without a TTL */
+  #untimed = false
+
+  /** @type {Promise<void> | undefined} */
+  #starting
+
+  /** @type {ReturnType<setTimeout> | undefined} */
+  #timer
+
+  #polling = false
+  #poked = false
+  #stopped = false
+
+  /**
+   * @param {string} host
+   * @param {comq.shards.Timing} options
+   * @param {string} key
+   */
+  constructor (host, options, key) {
+    this.#host = host
+    this.#options = options
+    this.#key = key
+  }
+
+  /**
+   * The name everyone in the process follows `host` by with the same timing: the timing is
+   * part of what a name is, so that nobody is followed at a pace they did not ask for.
+   *
+   * @param {string} host
+   * @param {comq.shards.Timing} [options]
+   * @return {Name}
+   */
+  static of (host, options = {}) {
+    const key = host + ' ' + JSON.stringify([options.interval, options.settle])
+    let name = names.get(key)
+
+    if (name === undefined) {
+      name = new Name(host, options, key)
+      names.set(key, name)
+    }
+
+    return name
+  }
+
+  get host () {
+    return this.#host
+  }
+
+  /** @type {string | undefined} the address in effect, once started */
+  get address () {
+    return this.#current
+  }
+
+  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 what the name was last answered with may be cached. */
+  get period () {
+    return period(this.#ttl, this.#untimed)
+  }
+
+  /**
+   * Follows the name until the returned function is called. The last one to stop following
+   * it stops it.
+   *
+   * @param {comq.shards.Follower} follower
+   * @return {() => void}
+   */
+  follow (follower) {
+    this.#followers.add(follower)
+
+    return () => {
+      this.#followers.delete(follower)
+
+      if (this.#followers.size === 0) this.#stop()
+    }
+  }
+
+  /**
+   * Resolves the 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<string>} the address in effect
+   */
+  async start () {
+    this.#starting ??= this.#begin()
+
+    await this.#starting
+
+    return /** @type {string} */ (this.#current)
+  }
+
+  /**
+   * Looks now rather than when the interval is up.
+   */
+  poke () {
+    if (this.#stopped || this.#starting === undefined) return
+
+    if (this.#polling) {
+      this.#poked = true
+
+      return
+    }
+
+    clearTimeout(this.#timer)
+    this.#poll().catch(noop)
+  }
+
+  async #begin () {
+    await retry(async (again) => {
+      if (this.#stopped) return
+
+      const address = await this.#observe()
+
+      if (address === undefined) return again
+
+      this.#current = address
+      this.#candidate = address
+      this.#since = Date.now()
+    }, global.COMQ_TESTING_RESOLVE_BACKOFF)
+
+    this.#schedule()
+  }
+
+  #stop () {
+    this.#stopped = true
+    clearTimeout(this.#timer)
+
+    if (names.get(this.#key) === this) names.delete(this.#key)
+  }
+
+  #schedule () {
+    if (this.#stopped) return
+
+    this.#timer = setTimeout(() => this.#poll().catch(noop), this.interval)
+    this.#timer.unref()
+  }
+
+  async #poll () {
+    this.#polling = true
+
+    try {
+      const observed = (await this.#observe()) ?? this.#candidate
+
+      if (!this.#stopped) this.#consider(/** @type {string} */ (observed))
+    } finally {
+      this.#polling = false
+    }
+
+    if (this.#poked) {
+      this.#poked = false
+
+      return await this.#poll()
+    }
+
+    this.#schedule()
+  }
+
+  /**
+   * A name whose broker is out of reach for any of those who follow it has nothing to wait for:
+   * the connection to a broker is one for the whole process.
+   *
+   * @param {string} observed
+   */
+  #consider (observed) {
+    const now = Date.now()
+
+    if (observed !== this.#candidate) {
+      this.#candidate = observed
+      this.#since = now
+    }
+
+    if (this.#candidate === this.#current) return
+
+    const settled = now - this.#since >= this.settle
+
+    if (!settled && !this.#urgent()) return
+
+    this.#current = this.#candidate
+
+    for (const follower of this.#followers) follower.change(this.#host, this.#current)
+  }
+
+  /**
+   * @return {boolean}
+   */
+  #urgent () {
+    for (const follower of this.#followers) if (follower.urgent(this.#host)) return true
+
+    return false
+  }
+
+  /**
+   * 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<string | undefined>} the address the name is observed with, unless it is
+   * not known
+   */
+  async #observe () {
+    try {
+      const { addresses, ttl } = await resolve(this.#host)
+
+      if (addresses.length === 0) throw new Error(`${this.#host} resolves to no address`)
+
+      if (ttl === undefined) this.#untimed = true
+      else this.#ttl = Math.max(this.#ttl, ttl)
+
+      return choose(addresses, this.#current)
+    } catch (exception) {
+      for (const follower of this.#followers) follower.error(exception)
+
+      return undefined
+    }
+  }
+
+  // Singletons are evil.
+  static __lets_pretend_this_method_doesnt_exist () {
+    for (const name of names.values()) name.#stop()
+  }
+}
+
+/**
+ * How long an answer may be cached: the longest TTL seen, and no less than the floor.
+ *
+ * @param {number} ttl the longest TTL seen, in seconds
+ * @param {boolean} untimed whether an answer came without a TTL
+ * @return {number}
+ */
+function period (ttl, untimed) {
+  return Math.max(FLOOR_MS, ttl * 1000, untimed ? UNTIMED_MS : 0)
+}
+
+/** @type {Map<string, Name>} */
+const names = new Map()
+
+const INTERVAL_MS = 300_000
+
+/** No TTL is short enough to act on at once. */
+const FLOOR_MS = 900_000
+
+/** What a name answered without a TTL is given. */
+const UNTIMED_MS = 1_800_000
+
+function noop () {}
+
+exports.Name = Name
+exports.INTERVAL_MS = INTERVAL_MS
+exports.FLOOR_MS = FLOOR_MS

package/source/shards/resolve.js

@@ -6,9 +6,11 @@ const dns = require('node:dns').promises
 /**
  * The addresses a name stands for, and for how long the answer may be cached, in seconds.
  *
- * DNS is asked directly, since nothing else tells the TTL. A name it does not know is looked up
- * the way a socket would have, which is how a name from the hosts file or one completed by the
- * search list is found; such an answer carries no TTL.
+ * DNS is asked directly, since nothing else tells the TTL: for IPv4 addresses first, and for
+ * IPv6 ones only when there are none, as an IPv4 address is the one a broker is connected
+ * through whenever it has both. A name DNS does not know is looked up the way a socket would
+ * have, which is how a name from the hosts file or one completed by the search list is found;
+ * such an answer carries no TTL.
  *
  * @param {string} host
  * @return {Promise<comq.shards.Resolution>}
@@ -16,17 +18,14 @@ const dns = require('node:dns').promises
 async function resolve (host) {
   if (global.COMQ_TESTING_LOOKUP !== undefined) return await global.COMQ_TESTING_LOOKUP(host)
 
-  const answers = await Promise.allSettled([
-    dns.resolve4(host, { ttl: true }),
-    dns.resolve6(host, { ttl: true })
-  ])
+  for (const family of [dns.resolve4, dns.resolve6]) {
+    const records = await family.call(dns, host, { ttl: true }).catch(() => [])
 
-  const records = answers.flatMap((answer) => answer.status === 'fulfilled' ? answer.value : [])
-
-  if (records.length > 0) {
-    return {
-      addresses: records.map((record) => record.address),
-      ttl: Math.max(...records.map((record) => record.ttl))
+    if (records.length > 0) {
+      return {
+        addresses: records.map((record) => record.address),
+        ttl: Math.max(...records.map((record) => record.ttl))
+      }
     }
   }
 

package/test/shards/connection.test.js

@@ -221,6 +221,9 @@ describe('names', () => {
   /** @type {Record<string, jest.MockedFunction<Function>>} */
   let heard
 
+  /** @type {string[]} the names resolved, in the order they were */
+  let lookups
+
   const tick = (ms = INTERVAL) => jest.advanceTimersByTimeAsync(ms)
 
   /**
@@ -237,7 +240,13 @@ describe('names', () => {
 
     addresses = { one: '10.0.0.1', two: '10.0.0.1', three: '10.0.0.2', four: '10.0.0.2' }
 
-    global.COMQ_TESTING_LOOKUP = async (host) => ({ addresses: [addresses[host]], ttl: 1 })
+    lookups = []
+
+    global.COMQ_TESTING_LOOKUP = async (host) => {
+      lookups.push(host)
+
+      return { addresses: [addresses[host]], ttl: 1 }
+    }
 
     connection = new Connection(names, make, { interval: INTERVAL, settle: SETTLE, linger: LINGER })
     heard = { join: jest.fn(), retire: jest.fn(), leave: jest.fn() }
@@ -435,6 +444,64 @@ describe('names', () => {
     expect(heard.join).toHaveBeenCalledWith(2, '10.0.0.3')
   })
 
+  it('should resolve a name once for every connection that stands on it', async () => {
+    const other = new Connection(names, make, { interval: INTERVAL, settle: SETTLE, linger: LINGER })
+
+    lookups = []
+
+    await other.open()
+
+    expect(lookups).toStrictEqual([])
+
+    await tick()
+
+    expect(lookups.toSorted()).toStrictEqual(['four', 'one', 'three', 'two'])
+
+    await other.close()
+  })
+
+  it('should follow a name that another connection follows as well', async () => {
+    const other = new Connection(names, make, { interval: INTERVAL, settle: SETTLE, linger: LINGER })
+    const joined = jest.fn()
+
+    other.diagnose('join', joined)
+
+    await other.open()
+    await other.createChannel(generate())
+
+    addresses.four = '10.0.0.3'
+
+    await tick(SETTLE + INTERVAL)
+
+    expect(heard.join).toHaveBeenCalledWith(2, '10.0.0.3')
+    expect(joined).toHaveBeenCalledWith(2, '10.0.0.3')
+
+    await other.close()
+  })
+
+  it('should go on following a name that another connection has stopped following', async () => {
+    const other = new Connection(names, make, { interval: INTERVAL, settle: SETTLE, linger: LINGER })
+
+    await other.open()
+    await other.close()
+
+    addresses.four = '10.0.0.3'
+
+    await tick(SETTLE + INTERVAL)
+
+    expect(heard.join).toHaveBeenCalledWith(2, '10.0.0.3')
+  })
+
+  it('should look again only at the names of a broker that is lost', async () => {
+    lookups = []
+
+    tell(connections[1], 'close', new Error('lost'))
+
+    await tick(0)
+
+    expect(lookups.toSorted()).toStrictEqual(['four', 'three'])
+  })
+
   it('should report a name that fails to resolve', async () => {
     const listener = jest.fn()
     const exception = new Error('ENOTFOUND')