comq 0.25.1 → 0.26.0

package/test/shards/watch.test.js

@@ -0,0 +1,264 @@
+'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])
+  })
+})

package/test/singleton.test.js

@@ -27,7 +27,7 @@ beforeEach(() => {
 
 it('should extend Connection', async () => {
   expect(connection).toBeInstanceOf(mock.Connection)
-  expect(mock.Connection.ctor).toHaveBeenCalledWith(url, {})
+  expect(mock.Connection.ctor).toHaveBeenCalledWith(url, {}, undefined)
 })
 
 describe('connection', () => {

package/types/channel.d.ts

@@ -44,6 +44,29 @@ declare namespace comq {
 
     seal (): Promise<void>
 
+    /** resolves once what was delivered and what was published is done with */
+    settled? (): Promise<void>
+
+    /** since when there has been nothing to do, which is now while there is */
+    quiet? (): Promise<number>
+
+    /** over a sharded connection: whether a shard is one of the channel's */
+    has? (index: number): boolean
+
+    /** takes a shard in, consuming from it what is consumed from the rest */
+    join? (connection: any, index: number): Promise<void>
+
+    /** stops publishing through a shard, which goes on being consumed from */
+    retire? (index: number): void
+
+    restore? (index: number): void
+
+    /** lets a shard go, once what it has delivered is done with */
+    leave? (index: number): Promise<void>
+
+    /** told by whoever publishes whether a shard owes it something */
+    occupy? (occupied: (index: number) => boolean): void
+
     close (): Promise<void>
 
     readonly closed: boolean

package/types/connection.d.ts

@@ -2,6 +2,7 @@ import * as _channel from './channel'
 import * as _io from './io'
 import * as _diagnostics from './diagnostic'
 import * as _topology from './topology'
+import * as _shards from './shards'
 
 declare namespace comq {
 
@@ -22,13 +23,23 @@ declare namespace comq {
     forget(event: _diagnostics.Event, listener: Function): void
   }
 
+  /** The topology presets overridden per channel type, and how the names of the shards are followed. */
+  type Options = _topology.Overrides & {
+    resolution?: _shards.Timing
+  }
+
   type Connect = {
+    /**
+     * A range in a host is as many URLs: `amqp://rmq[0..32].example.com` is `rmq0` to `rmq31`.
+     * Several URLs are the names of the shards, and a connection is made to each broker they
+     * stand for.
+     */
     (...urls: string[]): Promise<_io.IO>
 
-    /** The trailing argument overrides the topology presets, per channel type. */
-    (...args: [...urls: string[], overrides: _topology.Overrides]): Promise<_io.IO>
+    (...args: [...urls: string[], options: Options]): Promise<_io.IO>
   }
 
 }
 
 export type Connect = comq.Connect
+export type Options = comq.Options

package/types/diagnostic.d.ts

@@ -1,7 +1,8 @@
 declare namespace comq.diagnostics {
 
   type Event = 'open' | 'close' | 'error' | 'reconnect' | 'exhausted' | 'flow' | 'drain' |
-    'remove' | 'lost' | 'recover' | 'discard' | 'retry' | 'pause' | 'resume' | 'return' | 'taken'
+    'remove' | 'lost' | 'recover' | 'discard' | 'retry' | 'pause' | 'resume' | 'return' | 'taken' |
+    'join' | 'retire' | 'leave'
 
   interface Diagnosable {
     diagnose(event: Event, listener: Function): void

package/types/io.d.ts

@@ -7,7 +7,7 @@ import * as _amqp from './amqp'
 
 declare namespace comq {
 
-  type Producer<Input = any, Output = any> = (message: Input) => Output | Promise<Output>
+  type Producer<Input = any, Output = any> = (message: Input, properties?: _amqp.Properties) => Output | Promise<Output>
   type Consumer<T = any> = (message: T, headers?: _amqp.Properties) => void | Promise<void>
 
   type ReplyHandler = (payload: any, properties: _amqp.Properties, size?: number) => void
@@ -66,6 +66,9 @@ declare namespace comq {
   /** The options of a Request, settled once for all its attempts. */
   interface Terms {
     encoding?: _encoding.Encoding
+
+    /** What a Request is sent with besides what makes it one. */
+    properties?: _amqp.Properties
     expires?: number
     signal?: AbortSignal
   }
@@ -76,8 +79,12 @@ declare namespace comq {
     /** Waits for the Reply for as long as it takes. */
     request<Reply = any, Request = any>(queue: string, payload: Request, encoding?: _encoding.Encoding): Promise<Reply> | Promise<Readable>
 
+    request<Reply = any, Request = any>(queue: string, payload: Request, properties?: _amqp.Properties): Promise<Reply> | Promise<Readable>
+
     request(queue: string, stream: Readable, encoding?: _encoding.Encoding): Promise<Readable>
 
+    request(queue: string, stream: Readable, properties?: _amqp.Properties): Promise<Readable>
+
     /**
      * Sends a Request to whoever holds `key` on the routed `exchange`, through `back`. One that
      * nobody holds is refused with `Unroutable`.
@@ -157,6 +164,15 @@ declare namespace comq {
 
     diagnose(event: 'taken', listener: (channel: _topology.type, queue: string, index?: number) => void): void
 
+    /** a broker the names of the shards stand for has joined the pool, or is back in it */
+    diagnose(event: 'join', listener: (index: number, address: string) => void): void
+
+    /** no name stands for the broker any longer: nothing new is published to it */
+    diagnose(event: 'retire', listener: (index: number, address: string) => void): void
+
+    /** a retired broker has had nothing more to give, and is disconnected */
+    diagnose(event: 'leave', listener: (index: number, address: string) => void): void
+
     diagnose(event: 'pause', listener: (channel: _topology.type) => void): void
 
     diagnose(event: 'resume', listener: (channel: _topology.type) => void): void

package/types/shards.d.ts

@@ -0,0 +1,58 @@
+import * as _connection from './connection'
+
+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.
+     */
+    type Timing = {
+      /** how often the names are resolved, 10 seconds by default */
+      interval?: number
+
+      /** how long an answer is to hold before a broker is joined or retired on it */
+      settle?: number
+
+      /** how long a retired broker is to stay idle before it is left */
+      linger?: number
+    }
+
+    type Resolution = {
+      addresses: string[]
+
+      /** in seconds, when the answer tells */
+      ttl?: number
+    }
+
+    type Location = {
+      /** the URL of the address, which is what tells one broker from another */
+      url: string
+      address: string
+
+      /** the name the broker is verified by */
+      servername?: string
+    }
+
+    type Shard = Location & {
+      index: number
+      connection: _connection.Connection
+      state: 'joining' | 'active' | 'retiring' | 'leaving'
+
+      /** whether channels are made over it */
+      joined: boolean
+
+      /** when it was retired */
+      since: number
+
+      /** since when it has been out of reach, while retiring */
+      down?: number
+      listeners: [string, Function][]
+    }
+
+  }
+
+}
+
+export type Timing = comq.shards.Timing