comq 0.25.1 → 0.26.0

package/source/shards/channel.js

@@ -11,12 +11,40 @@ const emitter = require('../emitter')
 class Channel {
   sharded = true
 
-  /** @type {comq.Connection[]} */
+  /** @type {Map<number, comq.Connection>} the connection of each shard, by its number */
   #connections
 
+  /** @type {Map<number, comq.Channel>} the channel of each shard, once it has one */
+  #shards = new Map()
+
   /** @type {Set<comq.Channel>} */
   #channels = new Set()
 
+  /** @type {Set<comq.Channel>} the channels of the shards that are joining */
+  #joining = new Set()
+
+  /** @type {WeakSet<comq.Channel>} the channels of the shards that were let go */
+  #gone = new WeakSet()
+
+  /** @type {Set<number>} the shards nothing new is published to */
+  #retiring = new Set()
+
+  /**
+   * What has been consumed, to be consumed from a shard that joins later as well.
+   *
+   * @type {{ apply: (channel: comq.Channel) => Promise<any>, awaited: boolean }[]}
+   */
+  #consumptions = []
+
+  /** @type {Map<number, [comq.Connection, Function, Function]>} */
+  #watchers = new Map()
+
+  /** @type {((index: number) => boolean) | undefined} */
+  #occupied
+
+  /** @type {boolean} */
+  #shut = false
+
   /** @type {comq.Channel[]} */
   #pool
 
@@ -43,34 +71,179 @@ class Channel {
   #diagnostics = emitter.create()
 
   /**
-   * @param {comq.Connection[]} connections
+   * @param {comq.Connection[] | Map<number, comq.Connection>} connections of the shards, which
+   * are numbered by their position unless they are given by number
    * @param {comq.topology.type} type
    */
   constructor (connections, type) {
-    this.#connections = connections
+    this.#connections = new Map(Array.isArray(connections) ? connections.entries() : connections)
     this.#type = type
   }
 
   async create () {
-    const promises = this.#connections.map(this.#create)
+    const promises = Array.from(this.#connections,
+      ([index, connection]) => this.#create(connection, index))
 
     await Promise.any(promises)
   }
 
+  /**
+   * @param {number} index
+   * @return {boolean} whether the shard is one of this channel's
+   */
+  has (index) {
+    return this.#connections.has(index)
+  }
+
+  /**
+   * Takes a shard in. Whatever has been consumed is consumed from it as well, and only then is
+   * anything published through it: a Reply comes back through the shard its Request went, where
+   * somebody must be waiting for it by then.
+   *
+   * @param {comq.Connection} connection
+   * @param {number} index
+   * @return {Promise<void>}
+   */
+  async join (connection, index) {
+    if (this.#shut || this.#connections.has(index)) return
+
+    this.#connections.set(index, connection)
+    this.#watch(connection, index)
+
+    /** @type {comq.Channel} */
+    let channel
+
+    try {
+      channel = await connection.createChannel(this.#type, index)
+    } catch (exception) {
+      // not its shard, so that it may be joined again
+      if (!this.#abandoned(connection, index)) await this.leave(index)
+
+      throw exception
+    }
+
+    if (this.#abandoned(connection, index)) return await channel.close()
+
+    this.#joining.add(channel)
+    this.#attach(channel, index)
+
+    try {
+      // what is consumed while this is under way is consumed here too, as the list grows
+      for (let i = 0; i < this.#consumptions.length; i++) {
+        const { apply, awaited } = this.#consumptions[i]
+        const applied = apply(channel)
+
+        if (awaited) await applied
+        else applied.catch(noop)
+      }
+    } catch (exception) {
+      // a shard that cannot be consumed from is not one to publish through: whoever took the
+      // shard for joined would let go of the one that is consumed from
+      if (!this.#abandoned(connection, index)) await this.leave(index)
+
+      throw exception
+    } finally {
+      this.#joining.delete(channel)
+    }
+
+    // sealed or closed with the rest while it was joining, or let go
+    if (this.#abandoned(connection, index)) return await channel.close()
+
+    this.#add(channel)
+  }
+
+  /**
+   * Stops publishing through a shard, which goes on being consumed from. A Reply still goes
+   * back through it: see `fire`.
+   *
+   * @param {number} index
+   */
+  retire (index) {
+    this.#retiring.add(index)
+    this.#update()
+  }
+
+  /**
+   * @param {number} index
+   */
+  restore (index) {
+    this.#retiring.delete(index)
+    this.#update()
+  }
+
+  /**
+   * @param {number} index
+   * @return {Promise<number>} since when the shard has had nothing to do, which is now while
+   * it has
+   */
+  async quiet (index) {
+    if (this.#occupied?.(index) === true) return Date.now()
+
+    const channel = this.#shards.get(index)
+
+    return channel === undefined ? 0 : await channel.quiet()
+  }
+
+  /**
+   * Whoever publishes through this channel may be waiting for something a shard owes it, which
+   * the channel itself cannot tell.
+   *
+   * @param {(index: number) => boolean} occupied
+   */
+  occupy (occupied) {
+    this.#occupied = occupied
+  }
+
+  /**
+   * Lets a shard go, with the channel it had.
+   *
+   * @param {number} index
+   * @return {Promise<void>}
+   */
+  async leave (index) {
+    const channel = this.#shards.get(index)
+
+    // what it has delivered is done with while it is still the way back for the answers
+    if (channel !== undefined) {
+      await channel.seal().catch(noop)
+      await channel.settled()
+    }
+
+    this.#connections.delete(index)
+    this.#shards.delete(index)
+    this.#retiring.delete(index)
+    this.#unwatch(index)
+
+    if (channel === undefined) return
+
+    this.#gone.add(channel)
+    this.#channels.delete(channel)
+    this.#bench.delete(channel)
+    this.#update()
+
+    await channel.close()
+  }
+
   /**
    * A message is told which shard it arrived on, so that whatever answers it can go back the same
    * way. See `fire`.
    */
   async consume (queue, consumer) {
-    return await this.#every((channel) => channel.consume(queue, arrival(consumer, channel)))
+    return await this.#consumption(
+      (channel) => channel.consume(queue, arrival(consumer, channel)),
+      (apply) => this.#every(apply))
   }
 
   async subscribe (queue, group, consumer) {
-    await this.#every((channel) => channel.subscribe(queue, group, consumer))
+    await this.#consumption(
+      (channel) => channel.subscribe(queue, group, consumer),
+      (apply) => this.#every(apply))
   }
 
   async bound (exchange, queue, key, consumer) {
-    await this.#every((channel) => channel.bound(exchange, queue, key, consumer))
+    await this.#consumption(
+      (channel) => channel.bound(exchange, queue, key, consumer),
+      (apply) => this.#every(apply))
   }
 
   /**
@@ -78,7 +251,10 @@ class Channel {
    * claiming it, and holds it as well once it is let go.
    */
   async held (exchange, queue, key, consumer) {
-    await Promise.any(this.#apply((channel) => channel.held(exchange, queue, key, arrival(consumer, channel))))
+    // a shard that joins is not waited for either: the key may be held there by another
+    await this.#consumption(
+      (channel) => channel.held(exchange, queue, key, arrival(consumer, channel)),
+      (apply) => Promise.any(this.#apply(apply)), false)
   }
 
   /**
@@ -126,7 +302,11 @@ class Channel {
   }
 
   async close () {
+    this.#shut = true
+
     await this.#all((channel) => channel.close())
+
+    for (const index of this.#watchers.keys()) this.#unwatch(index)
   }
 
   get closed () {
@@ -134,6 +314,9 @@ class Channel {
   }
 
   async seal () {
+    // a sealed channel is not going to consume again, from a shard that joins either
+    this.#consumptions = []
+
     await this.#all((channel) => channel.seal())
   }
 
@@ -156,7 +339,18 @@ class Channel {
     const pending = connection.createChannel(this.#type, index)
     const channel = await this.#pend(pending, index)
 
+    if (this.#abandoned(connection, index)) return await channel.close()
+
+    this.#attach(channel, index)
     this.#add(channel)
+  }
+
+  /**
+   * @param {comq.Channel} channel
+   * @param {number} index
+   */
+  #attach (channel, index) {
+    this.#shards.set(index, channel)
     this.#pipe(channel)
 
     channel.diagnose('flow', () => this.#remove((channel)))
@@ -164,6 +358,42 @@ class Channel {
     channel.diagnose('recover', () => this.#recover(channel))
   }
 
+  /**
+   * @param {comq.Connection} connection
+   * @param {number} index
+   * @return {boolean} whether the shard was let go, or the channel closed, while a channel was
+   * being made for it
+   */
+  #abandoned (connection, index) {
+    return this.#shut || this.#connections.get(index) !== connection
+  }
+
+  /**
+   * Consumes from the shards there are, and from the ones that join later. What no shard could
+   * consume is not consumed from those either: it has failed for whoever asked for it.
+   *
+   * @param {(channel: comq.Channel) => Promise<any>} apply
+   * @param {(apply: (channel: comq.Channel) => Promise<any>) => Promise<any>} consume
+   * @param {boolean} [awaited] whether a shard that joins waits for it before it is published to
+   * @return {Promise<any>}
+   */
+  async #consumption (apply, consume, awaited = true) {
+    const consumption = { apply, awaited }
+
+    // before it is applied, for a shard that joins meanwhile
+    this.#consumptions.push(consumption)
+
+    try {
+      return await consume(apply)
+    } catch (exception) {
+      const index = this.#consumptions.indexOf(consumption)
+
+      if (index !== -1) this.#consumptions.splice(index, 1)
+
+      throw exception
+    }
+  }
+
   /**
    * Tracks whether a shard is reachable, so that subscribing does not wait for
    * one that is not. The pool itself is left alone: a channel is only benched
@@ -181,7 +411,7 @@ class Channel {
 
     if (connection.connected === false) this.#down[index].resolve()
 
-    connection.diagnose('close', (error) => {
+    const closed = (error) => {
       this.#alive[index] = false
       this.#down[index].resolve()
 
@@ -191,14 +421,41 @@ class Channel {
       if (error !== undefined && connection.closed !== true) {
         this.#diagnostics.emit(LOST, index)
       }
-    })
+    }
 
-    connection.diagnose('open', () => {
+    const opened = () => {
       this.#alive[index] = true
       this.#down[index] = new Promex()
 
       this.#update()
-    })
+    }
+
+    connection.diagnose('close', closed)
+    connection.diagnose('open', opened)
+
+    this.#watchers.set(index, [connection, closed, opened])
+  }
+
+  /**
+   * @param {number} index
+   */
+  #unwatch (index) {
+    const watcher = this.#watchers.get(index)
+
+    if (watcher === undefined) return
+
+    const [connection, closed, opened] = watcher
+
+    connection.forget('close', closed)
+    connection.forget('open', opened)
+
+    this.#watchers.delete(index)
+
+    // whatever waits for the shard is not to wait for it any longer
+    this.#down[index].resolve()
+
+    delete this.#down[index]
+    delete this.#alive[index]
   }
 
   /**
@@ -248,7 +505,7 @@ class Channel {
     // a failed message waits on an exchange of comq's own, a fanout that is declared as one
     // where it is consumed, and declaring it on another shard as anything else is refused
     const exhausted = exchange.startsWith(RETRY_PREFIX) ||
-      attempt >= this.#connections.length ||
+      attempt >= this.#connections.size ||
       rest.length === 0
 
     if (exhausted) return report()
@@ -313,6 +570,10 @@ class Channel {
    * @param {comq.Channel} channel
    */
   #recover (channel) {
+    // one that is joining is added once it consumes what the rest do, and one that has been
+    // let go is not added at all
+    if (this.#joining.has(channel) || this.#gone.has(channel)) return
+
     if (this.#bench.has(channel)) this.#comeback(channel)
 
     this.#add(channel)
@@ -379,6 +640,9 @@ class Channel {
   async #all (fn) {
     const promises = this.#apply(fn)
 
+    // a shard that is joining is sealed and closed with the rest
+    for (const channel of this.#joining) promises.push(fn(channel))
+
     await Promise.all(promises)
   }
 
@@ -397,14 +661,15 @@ class Channel {
   }
 
   /**
-   * The channels of the shards that are known to be connected.
+   * The channels of the shards that are known to be connected, and are not retiring.
    * An empty result means every shard is down or benched — wait rather than
    * publish: a destroyed socket accepts a write without complaining.
    *
    * @return {comq.Channel[]}
    */
   #reachable () {
-    return this.#pool.filter((channel) => this.#alive[channel.index] !== false)
+    return this.#pool.filter((channel) =>
+      this.#alive[channel.index] !== false && !this.#retiring.has(channel.index))
   }
 
   /**
@@ -419,14 +684,19 @@ class Channel {
     const waiting = this.#recovery
     const pool = this.#reachable()
 
-    if (pool.length === 0) {
+    // a shard that is retiring is still the way back for what arrived on it
+    const preferred = route.prefer === undefined
+      ? undefined
+      : this.#pool.find((channel) =>
+        channel.index === route.prefer && this.#alive[channel.index] !== false)
+
+    if (preferred === undefined && pool.length === 0) {
       await waiting
 
       return this.#one(fn, route)
     }
 
-    const channel = pool.find((channel) => channel.index === route.prefer) ??
-      pool[Math.floor(Math.random() * pool.length)]
+    const channel = preferred ?? pool[Math.floor(Math.random() * pool.length)]
 
     // told before the publish is awaited: a shard lost while it is under way has it on board
     route.via?.(channel.index)
@@ -455,7 +725,7 @@ function arrival (consumer, channel) {
 }
 
 /**
- * @param {comq.Connection[]} connections
+ * @param {comq.Connection[] | Map<number, comq.Connection>} connections
  * @param {comq.topology.type} type
  * @return {comq.Channel}
  */