comq 0.25.1 → 0.26.0

package/source/shards/connection.js

@@ -3,43 +3,127 @@
 const events = require('../events')
 const channel = require('./channel')
 const emitter = require('../emitter')
+const { Watch } = require('./watch')
+const { hostOf, locate } = require('./resolve')
 
 /**
+ * The URLs it is given are virtual shards: names, of which several may stand for one broker.
+ * A connection is made to each broker rather than to each name, and the brokers are followed
+ * as the names move from one to another.
+ *
+ * A broker is joined before another is retired, and a retired one is left only once it has
+ * nothing more to give: see `#reconcile` and `#idle`.
+ *
  * @implements {comq.Connection}
  */
 class Connection {
-  /** @type {comq.Connection[]} */
-  #connections
+  /** @type {string[]} */
+  #urls
+
+  /** @type {(url: string, servername?: string) => comq.Connection} */
+  #create
+
+  /** @type {Watch} */
+  #watch
+
+  /** @type {Map<string, string>} the address of each name */
+  #addresses = new Map()
+
+  /** @type {Map<string, comq.shards.Location>} the brokers the names stand for, by URL */
+  #wanted = new Map()
+
+  /** @type {Map<number, comq.shards.Shard>} */
+  #shards = new Map()
+
+  /** @type {number} the number the next shard gets: one is never given twice */
+  #next = 0
+
+  /** @type {Set<comq.Channel>} */
+  #channels = new Set()
+
+  /** @type {ReturnType<setTimeout> | undefined} */
+  #inspection
+
+  #opened = false
+  #closed = false
 
   #diagnostics = emitter.create()
 
   /**
-   * @param {comq.Connection[]} connections
+   * @param {string[]} urls
+   * @param {(url: string, servername?: string) => comq.Connection} create
+   * @param {comq.shards.Timing} [timing]
    */
-  constructor (connections) {
-    this.#connections = connections
+  constructor (urls, create, timing) {
+    this.#urls = urls
+    this.#create = create
+
+    const hosts = urls.map(hostOf).filter((host) => host !== undefined)
 
-    connections.map(this.#pipe)
+    this.#watch = new Watch(hosts, timing, this.#urgent)
+    this.#watch.on('change', (addresses) => this.#follow(addresses))
+    this.#watch.on('error', (exception) => this.#diagnostics.emit('error', exception))
   }
 
   async open () {
-    const openings = this.#connections.map((connection) => connection.open())
+    this.#closed = false
+
+    const addresses = await this.#watch.start()
+
+    if (this.#closed) return
+
+    this.#addresses = addresses
+    this.#wanted = this.#locations(addresses)
+
+    const shards = Array.from(this.#wanted.values(), (location) => this.#shard(location))
+    const openings = shards.map((shard) => shard.connection.open())
 
     try {
       await Promise.all(openings)
     } catch (exception) {
-      await this.#cancel(openings, exception)
+      await this.#cancel(openings, shards, exception)
     }
+
+    for (const shard of shards) shard.state = ACTIVE
+
+    this.#opened = true
+
+    // the names may have moved while the connections were being made
+    this.#reconcile()
   }
 
   async close () {
-    const closing = this.#connections.map((connection) => connection.close())
+    this.#closed = true
+    this.#opened = false
+    this.#watch.stop()
+
+    clearTimeout(this.#inspection)
+
+    const closing = Array.from(this.#shards.values(), (shard) => shard.connection.close())
 
     await Promise.all(closing)
   }
 
   async createChannel (type) {
-    return channel.create(this.#connections, type)
+    const members = this.#members()
+    const created = await channel.create(members, type)
+
+    this.#channels.add(created)
+
+    // what left, joined or retired while the channel was being made
+    for (const index of members.keys()) {
+      if (this.#member(this.#shards.get(index)) === false) await created.leave(index)
+    }
+
+    for (const shard of this.#shards.values()) {
+      if (!this.#member(shard)) continue
+
+      created.join(shard.connection, shard.index).catch(noop)
+
+      if (shard.state === RETIRING) created.retire(shard.index)
+    }
+
+    return created
   }
 
   async diagnose (event, listener) {
@@ -51,29 +135,331 @@ class Connection {
   }
 
   /**
-   * @param {comq.Connection} connection
-   * @param {number} index
+   * @return {Map<number, comq.Connection>} the connections a channel is made over
+   */
+  #members () {
+    const members = new Map()
+
+    for (const shard of this.#shards.values()) {
+      if (this.#member(shard)) members.set(shard.index, shard.connection)
+    }
+
+    return members
+  }
+
+  /**
+   * @param {comq.shards.Shard} [shard]
+   * @return {boolean} whether channels are made over a shard
+   */
+  #member (shard) {
+    return shard !== undefined && shard.joined && shard.state !== LEAVING
+  }
+
+  /**
+   * @param {Map<string, string>} addresses the address of each name
+   * @return {Map<string, comq.shards.Location>}
    */
-  #pipe = (connection, index) => {
+  #locations (addresses) {
+    const locations = new Map()
+
+    for (const url of this.#urls) {
+      const location = locate(url, addresses.get(hostOf(url)))
+
+      // the first of the names of a broker is the one it is verified by
+      if (!locations.has(location.url)) locations.set(location.url, location)
+    }
+
+    return locations
+  }
+
+  /**
+   * @param {comq.shards.Location} location
+   * @return {comq.shards.Shard}
+   */
+  #shard (location) {
+    const index = this.#next++
+    const connection = this.#create(location.url, location.servername)
+
+    /** @type {comq.shards.Shard} */
+    const shard = { ...location, index, connection, state: JOINING, joined: true, since: 0, listeners: [] }
+
     for (const event of events.connection) {
-      connection.diagnose(event, (...args) => this.#diagnostics.emit(event, ...args, index))
+      const listener = (...args) => this.#diagnostics.emit(event, ...args, index)
+
+      connection.diagnose(event, listener)
+      shard.listeners.push([event, listener])
+    }
+
+    // a connection that is lost may be so because its broker has moved
+    const lost = (error) => { if (error !== undefined) this.#watch.poke() }
+
+    connection.diagnose('close', lost)
+    shard.listeners.push(['close', lost])
+
+    this.#shards.set(index, shard)
+
+    return shard
+  }
+
+  /**
+   * @param {comq.shards.Shard} shard
+   */
+  #dismiss (shard) {
+    for (const [event, listener] of shard.listeners) shard.connection.forget(event, listener)
+
+    this.#shards.delete(shard.index)
+  }
+
+  /**
+   * @param {string} url
+   * @return {comq.shards.Shard | undefined} the shard of a broker, be it on its way out
+   */
+  #shardOf (url) {
+    for (const shard of this.#shards.values()) if (shard.url === url) return shard
+  }
+
+  /**
+   * A name whose broker is out of reach has nothing to wait for: there is nothing to be had
+   * from that broker meanwhile, and a broker that has come back under another address is
+   * found at once, as it is when a connection is restored by name.
+   *
+   * @param {string} host
+   * @return {boolean}
+   */
+  #urgent = (host) => {
+    const address = this.#addresses.get(host)
+
+    for (const url of this.#urls) {
+      if (hostOf(url) !== host) continue
+
+      const shard = this.#shardOf(locate(url, address).url)
+
+      if (shard?.connection.connected === false) return true
+    }
+
+    return false
+  }
+
+  /**
+   * @param {Map<string, string>} addresses
+   */
+  #follow (addresses) {
+    this.#addresses = addresses
+    this.#wanted = this.#locations(addresses)
+    this.#reconcile()
+  }
+
+  /**
+   * Brings the shards in line with the brokers the names stand for, making before breaking:
+   * nothing is retired until every broker that is named has joined, so a name that points at
+   * a broker that is not there yet takes nothing away.
+   */
+  #reconcile () {
+    if (!this.#opened || this.#closed) return
+
+    for (const [url, location] of this.#wanted) {
+      // one that is being left is joined anew once it has been
+      if (this.#shardOf(url) === undefined) this.#join(location).catch(noop)
+    }
+
+    let made = true
+
+    for (const shard of this.#shards.values()) {
+      const named = this.#wanted.has(shard.url)
+
+      if (named && shard.state === RETIRING) this.#restore(shard)
+      if (!named && shard.state === JOINING) this.#leave(shard).catch(noop)
+      if (named && shard.state !== ACTIVE) made = false
+    }
+
+    if (!made) return
+
+    for (const shard of this.#shards.values()) {
+      if (!this.#wanted.has(shard.url) && shard.state === ACTIVE) this.#retire(shard)
+    }
+  }
+
+  /**
+   * @param {comq.shards.Location} location
+   * @return {Promise<void>}
+   */
+  async #join (location) {
+    const shard = this.#shard(location)
+
+    shard.joined = false
+
+    try {
+      await shard.connection.open()
+    } catch (exception) {
+      // a broker that refuses is asked again, as its name keeps pointing at it
+      this.#diagnostics.emit('error', exception, shard.index)
+      this.#dismiss(shard)
+
+      return this.#later(() => this.#reconcile())
     }
+
+    if (shard.state !== JOINING) return
+
+    // a channel made from now on takes the shard in by itself
+    shard.joined = true
+
+    const joining = Array.from(this.#channels,
+      (channel) => channel.join(shard.connection, shard.index))
+
+    const results = await Promise.allSettled(joining)
+    const failures = results.filter((result) => result.status === 'rejected')
+
+    for (const failure of failures) this.#diagnostics.emit('error', failure.reason, shard.index)
+
+    if (shard.state !== JOINING) return
+
+    // a broker that cannot be consumed from has not joined: taken for one that has, it would
+    // let the broker that is consumed from be retired
+    if (failures.length > 0) return await this.#leave(shard, true)
+
+    shard.state = ACTIVE
+
+    this.#diagnostics.emit(JOIN, shard.index, shard.address)
+    this.#reconcile()
+  }
+
+  /**
+   * @param {comq.shards.Shard} shard
+   */
+  #retire (shard) {
+    shard.state = RETIRING
+    shard.since = Date.now()
+    shard.down = undefined
+
+    for (const channel of this.#channels) channel.retire(shard.index)
+
+    this.#diagnostics.emit(RETIRE, shard.index, shard.address)
+    this.#inspect()
+  }
+
+  /**
+   * @param {comq.shards.Shard} shard
+   */
+  #restore (shard) {
+    shard.state = ACTIVE
+
+    for (const channel of this.#channels) channel.restore(shard.index)
+
+    this.#diagnostics.emit(JOIN, shard.index, shard.address)
+  }
+
+  /**
+   * @param {comq.shards.Shard} shard
+   * @param {boolean} [failed] whether it is let go for having failed to join, which is tried
+   * again later rather than at once
+   * @return {Promise<void>}
+   */
+  async #leave (shard, failed = false) {
+    const retired = shard.state === RETIRING
+
+    shard.state = LEAVING
+
+    const leaving = Array.from(this.#channels, (channel) => channel.leave(shard.index))
+
+    await Promise.allSettled(leaving)
+    await shard.connection.close()
+
+    this.#dismiss(shard)
+
+    // one that never joined is not said to have left
+    if (retired) this.#diagnostics.emit(LEAVE, shard.index, shard.address)
+
+    if (failed) this.#later(() => this.#reconcile())
+    else this.#reconcile()
+  }
+
+  /**
+   * Looks at the retiring shards for as long as there are any.
+   */
+  #inspect () {
+    clearTimeout(this.#inspection)
+
+    this.#inspection = this.#later(async () => {
+      for (const shard of Array.from(this.#shards.values())) {
+        if (shard.state !== RETIRING) continue
+
+        const idle = await this.#idle(shard)
+
+        // it may have been named again meanwhile
+        if (idle && shard.state === RETIRING && !this.#closed) this.#leave(shard).catch(noop)
+      }
+
+      for (const shard of this.#shards.values()) if (shard.state === RETIRING) return this.#inspect()
+    })
+  }
+
+  /**
+   * A retiring shard is left once it has had nothing to do for the linger time, counted from
+   * the moment it was retired: what is published to its broker by those who have not seen the
+   * names move yet is consumed meanwhile. One that is out of reach for that long is given up on.
+   *
+   * @param {comq.shards.Shard} shard
+   * @return {Promise<boolean>}
+   */
+  async #idle (shard) {
+    const now = Date.now()
+    const linger = this.#watch.linger
+
+    if (shard.connection.connected === false) {
+      shard.down ??= now
+
+      return now - shard.down >= linger
+    }
+
+    shard.down = undefined
+
+    const asked = Array.from(this.#channels, (channel) => channel.quiet(shard.index))
+    const quiet = await Promise.all(asked)
+
+    return now - Math.max(shard.since, ...quiet) >= linger
+  }
+
+  /**
+   * @param {() => any} fn
+   * @return {ReturnType<setTimeout>}
+   */
+  #later (fn) {
+    const timer = setTimeout(() => Promise.resolve().then(fn).catch(noop), this.#watch.interval)
+
+    timer.unref()
+
+    return timer
   }
 
   /**
    * @param {Promise<any>[]} openings
+   * @param {comq.shards.Shard[]} shards
    * @param {Error} exception
    */
-  async #cancel (openings, exception) {
+  async #cancel (openings, shards, exception) {
+    this.#watch.stop()
+
     const settled = await Promise.allSettled(openings)
-    const indexes = settled.map((result, index) => result.status === 'fulfilled' ? index : -1)
-    const opened = indexes.filter((index) => index !== -1)
-    const closings = opened.map((index) => this.#connections[index].close())
+    const opened = shards.filter((_, index) => settled[index].status === 'fulfilled')
+    const closings = opened.map((shard) => shard.connection.close())
 
     await Promise.all(closings)
 
+    for (const shard of shards) this.#dismiss(shard)
+
     throw exception
   }
 }
 
+const JOINING = 'joining'
+const ACTIVE = 'active'
+const RETIRING = 'retiring'
+const LEAVING = 'leaving'
+
+const JOIN = 'join'
+const RETIRE = 'retire'
+const LEAVE = 'leave'
+
+function noop () {}
+
 exports.Connection = Connection

package/source/shards/expand.js

@@ -0,0 +1,57 @@
+'use strict'
+
+/**
+ * Expands the ranges in the host of a URL into a URL per number: `amqp://rmq[0..3].example.com`
+ * is `rmq0`, `rmq1` and `rmq2`. The end is exclusive, so a range starting at zero names as many
+ * hosts as its end says. A start written with leading zeros pads every number to its width.
+ *
+ * Only the host is looked at: credentials, a path and a query are free to contain anything, and
+ * an IPv6 literal, which is bracketed as well, has no `..` in it.
+ *
+ * @param {string} url
+ * @return {string[]}
+ */
+function expand (url) {
+  const parts = url.match(AUTHORITY)
+
+  if (parts === null) return [url]
+
+  const [, head, host, tail] = parts
+
+  return hosts(host).map((host) => head + host + tail)
+}
+
+/**
+ * @param {string} host
+ * @return {string[]}
+ */
+function hosts (host) {
+  const range = host.match(RANGE)
+
+  if (range === null) return [host]
+
+  const [expression, from, to] = range
+  const start = Number(from)
+  const end = Number(to)
+
+  if (end <= start) throw new RangeError(`Range ${expression} names no hosts: its end is exclusive`)
+
+  const width = from.length > 1 && from.startsWith('0') ? from.length : 0
+  const before = host.slice(0, range.index)
+  const after = host.slice(range.index + expression.length)
+  const expanded = []
+
+  for (let n = start; n < end; n++) {
+    // whatever follows may hold a range of its own
+    for (const rest of hosts(after)) expanded.push(before + String(n).padStart(width, '0') + rest)
+  }
+
+  return expanded
+}
+
+/** What precedes the host, the host with its port, and what follows. */
+const AUTHORITY = /^([a-z][a-z0-9+.-]*:\/\/(?:[^@/?#]*@)?)([^/?#]*)(.*)$/i
+
+const RANGE = /\[(\d+)\.\.(\d+)]/
+
+exports.expand = expand

package/source/shards/index.js

@@ -1,5 +1,7 @@
 'use strict'
 
 const { Connection } = require('./connection')
+const { expand } = require('./expand')
 
 exports.Connection = Connection
+exports.expand = expand

package/source/shards/resolve.js

@@ -0,0 +1,134 @@
+'use strict'
+
+const net = require('node:net')
+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.
+ *
+ * @param {string} host
+ * @return {Promise<comq.shards.Resolution>}
+ */
+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 })
+  ])
+
+  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))
+    }
+  }
+
+  const found = await dns.lookup(host, { all: true })
+
+  return { addresses: found.map((entry) => entry.address) }
+}
+
+/**
+ * The one address a name is connected through. A name is one broker, and several addresses are
+ * as many ways to it: the one in use is kept for as long as it is listed, and the choice is
+ * otherwise the same whichever order they came in, so that the names of one broker agree on it.
+ *
+ * @param {string[]} addresses
+ * @param {string} [current]
+ * @return {string}
+ */
+function choose (addresses, current) {
+  if (current !== undefined && addresses.includes(current)) return current
+
+  return addresses.toSorted(order)[0]
+}
+
+/**
+ * IPv4 first, which is where a broker is found whenever it has both.
+ *
+ * @param {string} one
+ * @param {string} another
+ * @return {number}
+ */
+function order (one, another) {
+  return net.isIP(one) - net.isIP(another) || (one < another ? -1 : Number(one > another))
+}
+
+/**
+ * What a URL names: the host to resolve, or nothing when it is an address already or is not
+ * something that can be told.
+ *
+ * @param {string} url
+ * @return {string | undefined}
+ */
+function hostOf (url) {
+  const parsed = parse(url)
+
+  if (parsed === undefined) return undefined
+
+  const host = unbracketed(parsed.hostname)
+
+  return host === '' || net.isIP(host) !== 0 ? undefined : host
+}
+
+/**
+ * The broker a URL stands for once its name is resolved: the URL of the address, which is what
+ * tells one broker from another, and the name TLS verifies it by.
+ *
+ * @param {string} url
+ * @param {string} [address]
+ * @return {comq.shards.Location}
+ */
+function locate (url, address) {
+  const host = hostOf(url)
+
+  if (host === undefined || address === undefined) return { url, address: addressOf(url) }
+
+  const parsed = parse(url)
+
+  parsed.hostname = net.isIPv6(address) ? '[' + address + ']' : address
+
+  return { url: parsed.href, address, servername: host }
+}
+
+/**
+ * @param {string} url
+ * @return {string}
+ */
+function addressOf (url) {
+  const parsed = parse(url)
+
+  return parsed === undefined ? url : unbracketed(parsed.hostname)
+}
+
+/**
+ * @param {string} url
+ * @return {URL | undefined}
+ */
+function parse (url) {
+  try {
+    return new URL(url)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {string} hostname
+ * @return {string}
+ */
+function unbracketed (hostname) {
+  return hostname.replace(/^\[|]$/g, '')
+}
+
+exports.resolve = resolve
+exports.choose = choose
+exports.hostOf = hostOf
+exports.locate = locate