comq 0.9.0 → 0.10.1

package/source/.io/ReplyPipe.js

@@ -0,0 +1,158 @@
+'use strict'
+
+const { EventEmitter } = require('node:events')
+const { control, HEARTBEAT_INTERVAL } = require('./const')
+
+/** @typedef {(message: any, properties?: comq.amqp.options.Publish) => Promise<void>} Reply */
+
+class ReplyPipe extends EventEmitter {
+  #index = -1
+  #interrupted = false
+  #heartbeatInterval = global['COMQ_TESTING_HEARTBEAT_INTERVAL'] || HEARTBEAT_INTERVAL
+
+  /** @type {ReturnType<setInterval> | null} */
+  #interval = null
+
+  /** @type {string} */
+  #replyTo
+
+  /** @type {Record<string, comq.amqp.options.Publish>} */
+  #properties
+
+  /** @type {import('node:stream').Readable} */
+  #stream
+
+  /** @type {comq.Channel} */
+  #channel
+
+  /** @type {comq.ReplyEmitter} */
+  #feedback
+
+  /** @type {Reply} */
+  #reply
+
+  /**
+   * @param {comq.amqp.Message} request
+   * @param {stream.Readable} stream
+   * @param {comq.Channel} channel
+   * @param {comq.ReplyEmitter} feedback
+   * @param {Reply} reply
+   */
+  constructor (request, stream, channel, feedback, reply) {
+    super()
+
+    const { correlationId, replyTo } = request.properties
+
+    this.#stream = stream
+    this.#channel = channel
+    this.#feedback = feedback
+    this.#reply = reply
+    this.#replyTo = replyTo
+
+    this.#properties = {
+      chunk: { correlationId, ...CHUNK },
+      control: { correlationId, replyTo: feedback.queue, ...CONTROL }
+    }
+
+    channel.diagnose('return', this.#onReturn)
+    feedback.on(correlationId, this.#control)
+  }
+
+  async pipe () {
+    await this.#transmit(control.ok, this.#properties.control)
+
+    this.#stream.on('data', this.#onData)
+    this.#stream.on('close', this.#close)
+    this.#heartbeat()
+  }
+
+  destroy () {
+    this.#close()
+    this.#stream.destroy()
+  }
+
+  async #transmit (data, properties) {
+    this.#index++
+
+    const ok = await this.#reply(data,
+      { ...properties, headers: { index: this.#index } })
+
+    if (!ok) this.#interrupt()
+  }
+
+  #heartbeat () {
+    if (this.#interval !== null) clearInterval(this.#interval)
+
+    this.#interval = setInterval(
+      () => this.#transmit(control.heartbeat, this.#properties.control),
+      this.#heartbeatInterval
+    )
+  }
+
+  #interrupt () {
+    this.#interrupted = true
+    this.destroy()
+  }
+
+  #clear () {
+    clearInterval(this.#interval)
+
+    this.#stream.removeAllListeners()
+    this.#channel.forget('return', this.#onReturn)
+    this.#feedback.off(this.#properties.control.correlationId, this.#control)
+  }
+
+  #close = () => {
+    this.emit('close')
+    this.#clear()
+
+    if (!this.#interrupted) {
+      void this.#transmit(control.end, this.#properties.control)
+    }
+  }
+
+  #onData = async (chunk) => {
+    await this.#transmit(chunk, this.#properties.chunk)
+
+    this.#heartbeat()
+  }
+
+  #onReturn = (message) => {
+    if (message.fields.routingKey === this.#replyTo)
+      this.#interrupt()
+  }
+
+  #control = (message) => {
+    switch (message) {
+      case control.end:
+        this.#interrupt()
+        break
+      default:
+        throw new Error(`Unknown control message: ${message}`)
+    }
+  }
+
+  /**
+   * @param {comq.amqp.Message} request
+   * @param {stream.Readable} stream
+   * @param {comq.Channel} channel
+   * @param {comq.ReplyEmitter} control
+   * @param {Reply} reply
+   * @return {Promise<comq.Destroyable>}
+   */
+  static async create (request, stream, channel, control, reply) {
+    const pipe = new ReplyPipe(request, stream, channel, control, reply)
+
+    await pipe.pipe()
+
+    return /** @type {comq.Destroyable} */ pipe
+  }
+}
+
+/** @type {comq.amqp.options.Publish} */
+const CHUNK = { mandatory: true }
+
+/** @type {comq.amqp.options.Publish} */
+const CONTROL = { type: 'control', mandatory: true }
+
+exports.ReplyPipe = ReplyPipe

package/source/.io/ReplyStream.js

@@ -0,0 +1,139 @@
+'use strict'
+
+const { Readable } = require('node:stream')
+const { promex } = require('@toa.io/generic')
+const { IDLE_INTERVAL, control } = require('./const')
+
+class ReplyStream extends Readable {
+  confirmation = promex()
+
+  /** @type {ReturnType<setTimeout> | null} */
+  #timeout = null
+
+  /** @type {comq.ReplyEmitter} */
+  #emitter
+
+  /** @type {string} */
+  #correlationId
+
+  #control
+
+  #reply
+
+  #idleInterval
+
+  #index = 0
+
+  #buffered = 0
+
+  /** @type {Record<number, unknown>} */
+  #queue = {}
+
+  /**
+   * @param {comq.Request} request
+   * @param {any} reply
+   */
+  constructor (request, reply) {
+    super({ objectMode: true })
+
+    this.#emitter = request.emitter
+    this.#correlationId = request.properties.correlationId
+    this.#idleInterval = global['COMQ_TESTING_IDLE_INTERVAL'] || IDLE_INTERVAL
+    this.#reply = reply
+
+    this.#emitter.on(this.#correlationId, this.arrange.bind(this))
+  }
+
+  _destroy (error, callback) {
+    this._clear()
+    this.push(null)
+
+    void this.#reply(this.#control, control.end)
+    super._destroy(error, callback)
+  }
+
+  _read (_) {}
+
+  /**
+   * @param {unknown} payload
+   * @param {comq.amqp.Properties} properties
+   */
+  arrange (payload, properties) {
+    if (properties.headers.index !== this.#index) {
+      this._buffer(payload, properties)
+
+      return
+    }
+
+    this._add(payload, properties)
+
+    if (this.#buffered > 0) {
+      let message
+
+      while ((message = this.#queue[this.#index])) {
+        delete this.#queue[this.#index]
+        this._add(message.payload, message.properties)
+      }
+
+      this.#buffered = Object.keys(this.#queue).length
+    }
+  }
+
+  /**
+   * @param {unknown} payload
+   * @param {comq.amqp.Properties} properties
+   * @private
+   */
+  _add (payload, properties) {
+    this._heartbeat()
+    this.#index++
+
+    if (properties.type === 'control')
+      this._control(payload, properties)
+    else if (!this.push(payload))
+      this._clear()
+  }
+
+  _buffer (payload, properties) {
+    if (this.#buffered > MAX_BUFFER_SIZE) this.destroy()
+
+    this.#buffered++
+    this.#queue[properties.headers.index] = { payload, properties }
+  }
+
+  /**
+   * @param {string} message
+   * @param {comq.amqp.Properties} properties
+   * @private
+   */
+  _control (message, properties) {
+    switch (message) {
+      case control.ok:
+        this.#control = { properties }
+        this.confirmation.resolve()
+        break
+      case control.heartbeat:
+        break
+      case control.end:
+        this.push(null)
+        break
+      default:
+        throw new Error(`Unknown reply stream control message: '${message}'`)
+    }
+  }
+
+  _heartbeat () {
+    if (this.#timeout !== null) clearTimeout(this.#timeout)
+
+    this.#timeout = setTimeout(() => this.destroy(), this.#idleInterval)
+  }
+
+  _clear () {
+    clearTimeout(this.#timeout)
+    this.#emitter.removeAllListeners(this.#correlationId)
+  }
+}
+
+const MAX_BUFFER_SIZE = 1000
+
+exports.ReplyStream = ReplyStream

package/source/.io/const.js

@@ -0,0 +1,10 @@
+'use strict'
+
+exports.control = {
+  ok: 'ok',
+  heartbeat: 'heartbeat',
+  end: 'end'
+}
+
+exports.HEARTBEAT_INTERVAL = 5_000
+exports.IDLE_INTERVAL = 12_000

package/source/.io/{replies.js → createReplyEmitter.js}

@@ -2,24 +2,21 @@
 
 const { randomBytes } = require('node:crypto')
 const { EventEmitter } = require('node:events')
-
 const { concat } = require('./concat')
 
 /**
  * @param {string} label
  * @returns {comq.ReplyEmitter}
  */
-const createReplyEmitter = (label) => {
+function createReplyEmitter (label) {
   const id = randomBytes(8).toString('hex')
   const queue = concat(label, id)
   const emitter = new EventEmitter()
-  const once = (name, callback) => emitter.once(name, callback)
-  const emit = (name, value) => emitter.emit(name, value)
-  const clear = () => emitter.removeAllListeners()
 
   emitter.setMaxListeners(0)
+  emitter.queue = queue
 
-  return { queue, once, emit, clear }
+  return /** @type {comq.ReplyEmitter} */ emitter
 }
 
 exports.createReplyEmitter = createReplyEmitter

package/source/.io/index.js

@@ -1,7 +1,11 @@
 'use strict'
 
 const { concat } = require('./concat')
-const { createReplyEmitter } = require('./replies')
+const { createReplyEmitter } = require('./createReplyEmitter')
+const { ReplyStream } = require('./ReplyStream')
+const { ReplyPipe } = require('./ReplyPipe')
 
 exports.concat = concat
 exports.createReplyEmitter = createReplyEmitter
+exports.ReplyStream = ReplyStream
+exports.ReplyPipe = ReplyPipe

package/source/attributes/failsafe.js

@@ -0,0 +1,34 @@
+'use strict'
+
+/**
+ * @param {object} context
+ * @param {(exception: Error) => Promise<unknown>} recover
+ * @param {(...args: unknown[]) => Promise<unknown>} method
+ */
+function failsafe (context, recover, method = undefined) {
+  // two arguments passed
+  if (method === undefined) {
+    method = recover
+    recover = undefined
+  }
+
+  return async function call (...args) {
+    if (call[DISABLED] === true) return await method.apply(context, args)
+
+    try {
+      return await method.apply(context, args)
+    } catch (exception) {
+      if (recover !== undefined && await recover.call(context, exception) === false) throw exception
+
+      return call.apply(this, args)
+    }
+  }
+}
+
+failsafe.disable = (...methods) => {
+  for (const method of methods) method[DISABLED] = true
+}
+
+const DISABLED = Symbol('disabled')
+
+exports.failsafe = failsafe

package/source/attributes/failsafe.test.js

@@ -0,0 +1,133 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { failsafe } = require('./failsafe')
+
+it('should be', async () => {
+  expect(failsafe).toBeDefined()
+})
+
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+
+const fn = /** @type {jest.MockedFunction} */
+  jest.fn(async () => generate())
+const recover = /** @type {jest.MockedFunction<(...args: any[]) => Promise<any>>} */
+  jest.fn(async () => true)
+
+class FailsafeTest {
+  doWithRecovery = failsafe(this, this.#recover, async (...args) => {
+    return fn(...args)
+  })
+
+  doWithoutRecovery = failsafe(this, (...args) => {
+    return fn(...args)
+  })
+
+  async #recover (exception) {
+    return recover(exception)
+  }
+}
+
+/** @type {FailsafeTest} */
+let instance
+
+beforeEach(() => {
+  jest.clearAllMocks()
+
+  instance = new FailsafeTest()
+})
+
+describe.each([
+  ['with', 'doWithRecovery'],
+  ['without', 'doWithoutRecovery']
+])('%s recovery', (_, method) => {
+  it('should run fn', async () => {
+    await instance[method]()
+
+    expect(fn).toHaveBeenCalled()
+  })
+
+  it('should return value', async () => {
+    const value = await instance[method]()
+
+    expect(value).toStrictEqual(await fn.mock.results[0].value)
+  })
+
+  it('should pass arguments', async () => {
+    const args = [generate(), generate()]
+
+    await instance[method](...args)
+
+    expect(fn).toHaveBeenCalledWith(...args)
+  })
+
+  it('should call again', async () => {
+    fn.mockImplementationOnce(async () => { throw new Error() })
+
+    await instance[method]()
+
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('recovery function', () => {
+  it('should recover on exception', async () => {
+    fn.mockImplementationOnce(async () => { throw new Error() })
+
+    const value = await instance.doWithRecovery()
+
+    expect(value).toStrictEqual(await fn.mock.results[1].value)
+  })
+
+  it('should throw on recovery failure', async () => {
+    const exception = generate()
+
+    fn.mockImplementationOnce(async () => { throw exception })
+    recover.mockImplementationOnce(async () => false)
+
+    await expect(instance.doWithRecovery()).rejects.toStrictEqual(exception)
+  })
+
+  it('should pass exception to recover', async () => {
+    const exception = generate()
+
+    fn.mockImplementationOnce(async () => { throw exception })
+
+    await instance.doWithRecovery()
+
+    expect(recover).toHaveBeenCalledWith(exception)
+  })
+
+  it('should call recover within context', async () => {
+    class Test {
+      foo = 1
+
+      do = failsafe(this, this.recover, fn)
+
+      recover () {
+        expect(this.foo).toStrictEqual(1)
+      }
+    }
+
+    const instance = new Test()
+
+    fn.mockImplementationOnce(() => { throw new Error() })
+
+    instance.do()
+  })
+})
+
+describe('disable', () => {
+  it('should throw exception', async () => {
+    const exception = generate()
+
+    failsafe.disable(instance.doWithRecovery, instance.doWithoutRecovery)
+
+    fn.mockImplementation(async () => { throw exception })
+
+    await expect(instance.doWithRecovery()).rejects.toStrictEqual(exception)
+    await expect(instance.doWithoutRecovery()).rejects.toStrictEqual(exception)
+  })
+})

package/source/attributes/index.js

@@ -0,0 +1,13 @@
+'use strict'
+
+const { memo } = require('./memo')
+const { failsafe } = require('./failsafe')
+const { lazy } = require('./lazy')
+const { track } = require('./track')
+const { recall } = require('./recall')
+
+exports.memo = memo
+exports.failsafe = failsafe
+exports.lazy = lazy
+exports.track = track
+exports.recall = recall

package/source/attributes/lazy.js

@@ -0,0 +1,79 @@
+'use strict'
+
+function lazy (context, initializers, method) {
+  if (context[LOCK] === undefined) context[LOCK] = Symbol('methods locking key')
+
+  if (!Array.isArray(initializers)) initializers = [initializers]
+
+  return async function (...args) {
+    const override = await call(context, initializers, args)
+
+    if (override !== undefined) args.splice(0, override.length, ...override)
+
+    return method.apply(this, args)
+  }
+}
+
+/**
+ * @param {object} context
+ * @param {Function[]} initializers
+ * @param {any[]} args
+ * @returns {Promise<any[]>}
+ */
+async function call (context, initializers, args) {
+  let override
+
+  for (const init of initializers) {
+    const result = await resolve(context, init, args)
+
+    if (result !== undefined) override = result
+  }
+
+  return override
+}
+
+/**
+ * @param {object} context
+ * @param {Function} init
+ * @param {any[]} args
+ * @returns {Promise}
+ */
+function resolve (context, init, args) {
+  const key = context[LOCK]
+  const expected = args.slice(0, init.length)
+
+  return lock(context, init, expected, key)
+}
+
+/**
+ * @param {object} context
+ * @param {(...args: unknown[]) => Promise<unknown>} init
+ * @param {unknown[]} args
+ * @param {Symbol} key
+ * @returns {Promise<unknown>}
+ */
+function lock (context, init, args, key) {
+  if (init[key] === undefined) init[key] = []
+
+  const locks = init[key]
+  const found = locks.find((lock) => lock.args.reduce((match, argument, i) => match && argument === args[i], true))
+
+  if (found !== undefined) return found.promise
+
+  const promise = init.apply(context, args)
+  const lock = { args, promise }
+
+  locks.push(lock)
+
+  return promise
+}
+
+function reset (context) {
+  context[LOCK] = context[LOCK] = Symbol('methods locking key')
+}
+
+const LOCK = Symbol('context locking key')
+
+lazy.reset = reset
+
+exports.lazy = lazy