comq 0.18.0 → 0.20.0

package/test/verdicts.test.js

@@ -0,0 +1,57 @@
+'use strict'
+
+const { generate } = require('randomstring')
+const { Retry, Park, verdictOf, RETRY, PARK, VERDICT } = require('../source/verdicts')
+
+it('should be', async () => {
+  expect(Retry).toBeDefined()
+  expect(Park).toBeDefined()
+})
+
+describe('verdictOf', () => {
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['a string', 'nope'],
+    ['a plain Error', new Error(generate())],
+    ['an object branded with something else', { [Symbol.for('other.verdict')]: 'park' }],
+    ['an object whose brand is not a verdict', { [VERDICT]: generate() }]
+  ])('should read %s as a retry', async (_, exception) => {
+    expect(verdictOf(exception)).toStrictEqual(RETRY)
+  })
+
+  it('should read Retry as a retry', async () => {
+    expect(verdictOf(new Retry(generate()))).toStrictEqual(RETRY)
+  })
+
+  it('should read Park as a park', async () => {
+    expect(verdictOf(new Park(generate()))).toStrictEqual(PARK)
+  })
+
+  it('should read a Park thrown by another copy of comq', async () => {
+    // a dependency pinning comq while the application resolves its own tree makes two
+    // copies the ordinary outcome, and `instanceof` is silently false across them
+    const foreign = { [Symbol.for('comq.verdict')]: 'park' }
+
+    expect(verdictOf(foreign)).toStrictEqual(PARK)
+    expect(foreign instanceof Park).toStrictEqual(false)
+  })
+})
+
+describe('the classes', () => {
+  it.each([['Retry', Retry], ['Park', Park]])('should make %s an Error', async (name, Verdict) => {
+    const message = generate()
+    const verdict = new Verdict(message)
+
+    expect(verdict).toBeInstanceOf(Error)
+    expect(verdict.message).toStrictEqual(message)
+    expect(verdict.name).toStrictEqual(name)
+    expect(typeof verdict.stack).toStrictEqual('string')
+  })
+
+  it.each([['Retry', Retry], ['Park', Park]])('should let %s carry a cause', async (_, Verdict) => {
+    const cause = new Error(generate())
+
+    expect(new Verdict(generate(), { cause }).cause).toStrictEqual(cause)
+  })
+})

package/types/channel.d.ts

@@ -22,6 +22,9 @@ declare namespace comq {
     /** consumes `queue`, bound to a routed `exchange` under `key` */
     bound (exchange: string, queue: string, key: string, consumer: channels.Consumer): Promise<void>
 
+    /** consumes `queue`, exclusive to this connection and bound to a routed `exchange` under `key` */
+    held (exchange: string, queue: string, key: string, consumer: channels.Consumer): Promise<void>
+
     send (queue: string, buffer: Buffer, options?: Options.Publish): Promise<void>
 
     publish (exchange: string, buffer: Buffer, options?: Options.Publish): Promise<void>

package/types/diagnostic.d.ts

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

package/types/index.d.ts

@@ -4,3 +4,29 @@ export type { IO, Consumer, Producer } from './io'
 
 export const connect: Connect
 export const assert: Connect
+
+/**
+ * Thrown by a consumer to say that whatever it needed was briefly not there. This is
+ * what an unclassified rejection already means, so throwing it changes nothing but the
+ * reader's certainty.
+ */
+export class Retry extends Error {}
+
+/**
+ * Thrown by a consumer to say that it will never process this message, however many
+ * times it is handed over. The message is kept rather than retried.
+ *
+ * Not applicable to a `Producer` given to `IO.reply`: a Request has a caller awaiting a
+ * reply, so a verdict is a category error there and the message is retried and parked on
+ * the count like any other failure.
+ */
+export class Park extends Error {}
+
+/**
+ * A Request `IO.call` sent under a key nobody holds. The broker returned it, so it reached no
+ * one and was not processed.
+ */
+export class Unroutable extends Error {
+  readonly exchange: string
+  readonly key: string
+}

package/types/io.d.ts

@@ -34,14 +34,52 @@ declare namespace comq {
   interface Request {
     emitter: ReplyEmitter
     properties: _amqp.Properties
+    signal?: AbortSignal
+  }
+
+  /** How long a caller waits for a Reply. */
+  interface RequestOptions {
+    encoding?: _encoding.Encoding
+
+    /**
+     * Milliseconds to wait for the Reply. A Request nobody has taken by then is dropped by the
+     * broker; one already taken may still be processed, and its Reply is discarded.
+     */
+    timeout?: number
+
+    /**
+     * Ends the wait when aborted, within the timeout. The Request stays in its queue until the
+     * timeout passes, or, without one, until a Producer takes it.
+     */
+    signal?: AbortSignal
+  }
+
+  /** The options of a Request, settled once for all its attempts. */
+  interface Terms {
+    encoding?: _encoding.Encoding
+    expires?: number
+    signal?: AbortSignal
   }
 
   interface IO extends _diagnostics.Diagnosable {
     reply(queue: string, produce: Producer): Promise<void>
 
-    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, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
+
+    request(queue: string, stream: Readable, options?: _encoding.Encoding | RequestOptions): Promise<Readable>
+
+    /**
+     * Sends a Request to whoever holds `key` on the routed `exchange`, through `back`. One that
+     * nobody holds is refused with `Unroutable`.
+     */
+    call<Reply = any, Request = any>(exchange: string, key: string, payload: Request, options?: _encoding.Encoding | RequestOptions): Promise<Reply> | Promise<Readable>
 
-    request(queue: string, stream: Readable, encoding?: _encoding.Encoding): Promise<Readable>
+    /**
+     * Answers the Requests `call` sends under `key`, from a queue this connection alone holds.
+     * While another connection holds it on a broker, claims it there again and again, emitting
+     * `taken`. Resolves once a broker holds it.
+     */
+    back(exchange: string, key: string, produce: Producer): Promise<void>
 
     consume<T = any>(exchange: string, group: string, consumer: Consumer<T>): Promise<void>
 
@@ -107,6 +145,8 @@ declare namespace comq {
 
     diagnose(event: 'retry', listener: (channel: _topology.type, message: any, error: Error, attempt: number, index?: number) => void): void
 
+    diagnose(event: 'taken', listener: (channel: _topology.type, queue: string, index?: number) => void): void
+
     diagnose(event: 'pause', listener: (channel: _topology.type) => void): void
 
     diagnose(event: 'resume', listener: (channel: _topology.type) => void): void