@diia-inhouse/diia-queue 13.3.1 → 13.3.3

package/dist/services/externalCommunicator.js

@@ -12,10 +12,109 @@ class ExternalCommunicator {
         this.eventMessageValidator = eventMessageValidator;
         this.logger = logger;
     }
+    /**
+     * Synchronous request/response over the external event bus.
+     *
+     * Publishes `event` to the configured external exchange wrapped as
+     * `{ uuid, request }` and awaits the subscriber's response on the same call.
+     * The response envelope is validated against `ops.validationRules`, and any embedded error is rethrown as
+     * {@link ExternalCommunicatorError}.
+     *
+     * Use this when the caller needs the response inline (e.g. a user-facing
+     * request that must block on `AGateway`). For fire-and-forget or fan-out
+     * flows, use the `default` publish + listener pattern instead.
+     *
+     * ### Transport
+     *
+     * Implemented on top of RabbitMQ's
+     * [direct reply-to](https://www.rabbitmq.com/docs/direct-reply-to)
+     * feature: the publisher consumes the pseudo-queue
+     * `amq.rabbitmq.reply-to` and stamps each request with `replyTo` +
+     * `correlationId`. The subscriber publishes its response back to that
+     * `replyTo` on the default exchange, and this call resolves when the
+     * matching `correlationId` arrives. No reply queue is declared per
+     * request, so there is no per-call broker setup overhead.
+     *
+     * ### Response contract
+     *
+     * The subscriber must respond with an
+     * {@link ExternalCommunicatorResponse} envelope:
+     *
+     * ```ts
+     * { uuid: string, response: T, error?: { http_code, message?, data? } }
+     * ```
+     *
+     * On success this method returns **only the `response` field** typed as
+     * `T` — the wrapping `uuid` and the envelope itself are not exposed to
+     * the caller. Therefore `T` should describe the shape of `response`, not
+     * of the full envelope.
+     *
+     * ### Error contract
+     *
+     * Errors travel through the same envelope (`error` field on the
+     * subscriber's response — this is **not** a transport-level failure),
+     * but on the caller side they are surfaced as a thrown
+     * {@link ExternalCommunicatorError} instead of being returned. The
+     * envelope's `error` payload is mapped onto the exception so no data is
+     * lost:
+     *
+     * - `error.message` → `Error.message` (falls back to `'unknown error'`
+     *   when missing).
+     * - `error.http_code` → exception's status code (read via `getCode()`).
+     * - `error.data` → exception's data bag (read via `getData()`), spread
+     *   alongside `event` (the event name) and `httpCode` (a duplicate of
+     *   the status code, kept on `data` for downstream consumers).
+     *
+     * Callers that need to inspect the original status or payload should
+     * `catch` the error and read those fields:
+     *
+     * ```ts
+     * try {
+     *     await externalCommunicator.receiveDirect<T>(event, req, ops)
+     * } catch (err) {
+     *     if (err instanceof ExternalCommunicatorError) {
+     *         err.getCode() // original error.http_code
+     *         err.getData() // { event, httpCode, ...error.data }
+     *         err.message   // error.message || 'unknown error'
+     *     }
+     *     throw err
+     * }
+     * ```
+     *
+     * @typeParam T - shape of the successful `response` payload returned by the subscriber.
+     * @param event - external event name. Must be declared in
+     *     `serviceRulesConfig.topicsConfig[QueueConfigType.External][topicName].events[]`
+     *     so the event resolves to an exchange (or pass `ops.exchangeName`
+     *     to override the lookup).
+     * @param request - payload forwarded to the subscriber. Defaults to `{}`.
+     * @param ops - direct-call options. See {@link ReceiveDirectOps}.
+     * @returns the subscriber's `response` field, typed as `T`. The envelope's
+     *     `uuid` and `error` fields are not returned.
+     *
+     * @throws {ExternalCommunicatorError} when the subscriber responds with an
+     *     `error` envelope. The original `http_code`, `message`, and `data`
+     *     fields are preserved on the thrown error.
+     * @throws {Error} `'Message in a wrong format was received from a direct channel'`
+     *     when `validationRules` are provided and the response fails validation.
+     *
+     * @example
+     * ```ts
+     * const result = await externalCommunicator.receiveDirect<{ data: string }>(
+     *     'notary.lookup',
+     *     { notaryCertificateNumber: '1234', requestId: '-0' },
+     *     {
+     *         // Describes the inner `response` only; the envelope (uuid,
+     *         // error, meta, ...) is wrapped by the validator.
+     *         validationRules: { data: { type: 'string' } },
+     *         timeout: DurationMs.Second * 5,
+     *     },
+     * )
+     * ```
+     */
     async receiveDirect(event, request = {}, ops) {
-        const { exchangeName, validationRules, ignoreCache, retry, timeout, registryApiVersion, requestUuid = (0, node_crypto_1.randomUUID)() } = ops;
+        const { exchangeName, validationRules, ignoreCache, timeout, registryApiVersion, requestUuid = (0, node_crypto_1.randomUUID)() } = ops;
         const payload = { uuid: requestUuid, request };
-        const options = { ignoreCache, retry, timeout, exchangeName, registryApiVersion };
+        const options = { ignoreCache, timeout, exchangeName, registryApiVersion };
         const externalResponse = await this.externalEventBus.publishDirect(event, payload, options);
         this.logger.debug('External direct response', externalResponse);
         if (validationRules) {

package/dist/services/externalCommunicator.js.map

@@ -1 +1 @@
-{"version":3,"file":"externalCommunicator.js","sourceRoot":"","sources":["../../src/services/externalCommunicator.ts"],"names":[],"mappings":";;;AAAA,6CAAwC;AAGxC,iDAAgE;AAMhE,MAAa,oBAAoB;IAER;IACA;IACA;IAHrB,YACqB,gBAAuC,EACvC,qBAA4C,EAC5C,MAAc;QAFd,qBAAgB,GAAhB,gBAAgB,CAAuB;QACvC,0BAAqB,GAArB,qBAAqB,CAAuB;QAC5C,WAAM,GAAN,MAAM,CAAQ;IAChC,CAAC;IAEJ,KAAK,CAAC,aAAa,CAAI,KAAa,EAAE,UAAmB,EAAE,EAAE,GAAqB;QAC9E,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,GAAG,IAAA,wBAAU,GAAE,EAAE,GAAG,GAAG,CAAA;QAE1H,MAAM,OAAO,GAAmB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAA;QAE9D,MAAM,OAAO,GAAyB,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAA;QACvG,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,CAC9D,KAAK,EACL,OAAO,EACP,OAAO,CACV,CAAA;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,gBAAgB,CAAC,CAAA;QAC/D,IAAI,eAAe,EAAE,CAAC;YAClB,IAAI,CAAC;gBACD,IAAI,CAAC,qBAAqB,CAAC,0BAA0B,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAA;YAC5F,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,MAAM,QAAQ,GAAG,8DAA8D,CAAA;gBAE/E,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,CAAA;gBACtD,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAA;YAC7B,CAAC;QACL,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAA;QAEpD,IAAI,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,KAAK,KAAK,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;YAEvH,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,IAAI,eAAe,CAAA;YAE/C,MAAM,IAAI,kCAAyB,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;QACrH,CAAC;QAED,OAAO,QAAQ,CAAA;IACnB,CAAC;CACJ;AA3CD,oDA2CC"}
+{"version":3,"file":"externalCommunicator.js","sourceRoot":"","sources":["../../src/services/externalCommunicator.ts"],"names":[],"mappings":";;;AAAA,6CAAwC;AAGxC,iDAAgE;AAMhE,MAAa,oBAAoB;IAER;IACA;IACA;IAHrB,YACqB,gBAAuC,EACvC,qBAA4C,EAC5C,MAAc;QAFd,qBAAgB,GAAhB,gBAAgB,CAAuB;QACvC,0BAAqB,GAArB,qBAAqB,CAAuB;QAC5C,WAAM,GAAN,MAAM,CAAQ;IAChC,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkGG;IACH,KAAK,CAAC,aAAa,CAAI,KAAa,EAAE,UAAmB,EAAE,EAAE,GAAqB;QAC9E,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,GAAG,IAAA,wBAAU,GAAE,EAAE,GAAG,GAAG,CAAA;QAEnH,MAAM,OAAO,GAAmB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAA;QAE9D,MAAM,OAAO,GAAyB,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAA;QAChG,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,aAAa,CAC9D,KAAK,EACL,OAAO,EACP,OAAO,CACV,CAAA;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,gBAAgB,CAAC,CAAA;QAC/D,IAAI,eAAe,EAAE,CAAC;YAClB,IAAI,CAAC;gBACD,IAAI,CAAC,qBAAqB,CAAC,0BAA0B,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAA;YAC5F,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,MAAM,QAAQ,GAAG,8DAA8D,CAAA;gBAE/E,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,gBAAgB,EAAE,CAAC,CAAA;gBACtD,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAA;YAC7B,CAAC;QACL,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAA;QAEpD,IAAI,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,KAAK,KAAK,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAA;YAEvH,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,IAAI,eAAe,CAAA;YAE/C,MAAM,IAAI,kCAAyB,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;QACrH,CAAC;QAED,OAAO,QAAQ,CAAA;IACnB,CAAC;CACJ;AA9ID,oDA8IC"}

package/dist/types/interfaces/externalCommunicator.d.ts

@@ -1,13 +1,39 @@
 import { HttpStatusCode } from '@diia-inhouse/types';
 import { ValidationSchema } from '@diia-inhouse/validators';
 import { ExchangeName } from './messageBrokerServiceConfig';
+/**
+ * Options for {@link ExternalCommunicator.receiveDirect}.
+ */
 export interface ReceiveDirectOps {
+    /**
+     * Forwarded in the message meta; consumed by `AGateway` to route the
+     * request to a specific registry API version.
+     */
     registryApiVersion?: string;
+    /**
+     * Override the target exchange. Defaults to the exchange resolved from the
+     * external queue configuration for the given event.
+     */
     exchangeName?: ExchangeName;
+    /**
+     * Schema describing the **inner** `response` payload. The validator wraps
+     * it with the envelope shape (`event`, `payload.uuid`, `payload.error`,
+     * `meta.date`, etc.) automatically — so pass just the fields you expect
+     * inside `response`, not the envelope itself.
+     *
+     * Null is acceptable only for legacy use cases.
+     */
     validationRules: ValidationSchema | null;
+    /** Bypass response caching on the subscriber side if configured. */
     ignoreCache?: boolean;
-    retry?: boolean;
+    /**
+     * Override the default direct-response timeout (ms). Falls back to the
+     * publisher's configured `directResponseTimeout` (10s by default).
+     */
     timeout?: number;
+    /**
+     * Defaults to a freshly generated `randomUUID()` when omitted.
+     */
     requestUuid?: string;
 }
 export interface ExternalCommunicatorResponseError {

package/dist/types/interfaces/options.d.ts

@@ -13,7 +13,6 @@ export interface PublishDirectOptions {
     exchangeName?: string;
     timeout?: number;
     ignoreCache?: boolean;
-    retry?: boolean;
     registryApiVersion?: string;
 }
 export interface PublishOptions {

package/dist/types/services/externalCommunicator.d.ts

@@ -7,5 +7,104 @@ export declare class ExternalCommunicator {
     private readonly eventMessageValidator;
     private readonly logger;
     constructor(externalEventBus: ExternalEventBusQueue, eventMessageValidator: EventMessageValidator, logger: Logger);
+    /**
+     * Synchronous request/response over the external event bus.
+     *
+     * Publishes `event` to the configured external exchange wrapped as
+     * `{ uuid, request }` and awaits the subscriber's response on the same call.
+     * The response envelope is validated against `ops.validationRules`, and any embedded error is rethrown as
+     * {@link ExternalCommunicatorError}.
+     *
+     * Use this when the caller needs the response inline (e.g. a user-facing
+     * request that must block on `AGateway`). For fire-and-forget or fan-out
+     * flows, use the `default` publish + listener pattern instead.
+     *
+     * ### Transport
+     *
+     * Implemented on top of RabbitMQ's
+     * [direct reply-to](https://www.rabbitmq.com/docs/direct-reply-to)
+     * feature: the publisher consumes the pseudo-queue
+     * `amq.rabbitmq.reply-to` and stamps each request with `replyTo` +
+     * `correlationId`. The subscriber publishes its response back to that
+     * `replyTo` on the default exchange, and this call resolves when the
+     * matching `correlationId` arrives. No reply queue is declared per
+     * request, so there is no per-call broker setup overhead.
+     *
+     * ### Response contract
+     *
+     * The subscriber must respond with an
+     * {@link ExternalCommunicatorResponse} envelope:
+     *
+     * ```ts
+     * { uuid: string, response: T, error?: { http_code, message?, data? } }
+     * ```
+     *
+     * On success this method returns **only the `response` field** typed as
+     * `T` — the wrapping `uuid` and the envelope itself are not exposed to
+     * the caller. Therefore `T` should describe the shape of `response`, not
+     * of the full envelope.
+     *
+     * ### Error contract
+     *
+     * Errors travel through the same envelope (`error` field on the
+     * subscriber's response — this is **not** a transport-level failure),
+     * but on the caller side they are surfaced as a thrown
+     * {@link ExternalCommunicatorError} instead of being returned. The
+     * envelope's `error` payload is mapped onto the exception so no data is
+     * lost:
+     *
+     * - `error.message` → `Error.message` (falls back to `'unknown error'`
+     *   when missing).
+     * - `error.http_code` → exception's status code (read via `getCode()`).
+     * - `error.data` → exception's data bag (read via `getData()`), spread
+     *   alongside `event` (the event name) and `httpCode` (a duplicate of
+     *   the status code, kept on `data` for downstream consumers).
+     *
+     * Callers that need to inspect the original status or payload should
+     * `catch` the error and read those fields:
+     *
+     * ```ts
+     * try {
+     *     await externalCommunicator.receiveDirect<T>(event, req, ops)
+     * } catch (err) {
+     *     if (err instanceof ExternalCommunicatorError) {
+     *         err.getCode() // original error.http_code
+     *         err.getData() // { event, httpCode, ...error.data }
+     *         err.message   // error.message || 'unknown error'
+     *     }
+     *     throw err
+     * }
+     * ```
+     *
+     * @typeParam T - shape of the successful `response` payload returned by the subscriber.
+     * @param event - external event name. Must be declared in
+     *     `serviceRulesConfig.topicsConfig[QueueConfigType.External][topicName].events[]`
+     *     so the event resolves to an exchange (or pass `ops.exchangeName`
+     *     to override the lookup).
+     * @param request - payload forwarded to the subscriber. Defaults to `{}`.
+     * @param ops - direct-call options. See {@link ReceiveDirectOps}.
+     * @returns the subscriber's `response` field, typed as `T`. The envelope's
+     *     `uuid` and `error` fields are not returned.
+     *
+     * @throws {ExternalCommunicatorError} when the subscriber responds with an
+     *     `error` envelope. The original `http_code`, `message`, and `data`
+     *     fields are preserved on the thrown error.
+     * @throws {Error} `'Message in a wrong format was received from a direct channel'`
+     *     when `validationRules` are provided and the response fails validation.
+     *
+     * @example
+     * ```ts
+     * const result = await externalCommunicator.receiveDirect<{ data: string }>(
+     *     'notary.lookup',
+     *     { notaryCertificateNumber: '1234', requestId: '-0' },
+     *     {
+     *         // Describes the inner `response` only; the envelope (uuid,
+     *         // error, meta, ...) is wrapped by the validator.
+     *         validationRules: { data: { type: 'string' } },
+     *         timeout: DurationMs.Second * 5,
+     *     },
+     * )
+     * ```
+     */
     receiveDirect<T>(event: string, request: unknown | undefined, ops: ReceiveDirectOps): Promise<T>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@diia-inhouse/diia-queue",
-    "version": "13.3.1",
+    "version": "13.3.3",
     "description": "Package provide queue functionality",
     "main": "dist/index.js",
     "types": "dist/types/index.d.ts",
@@ -44,15 +44,15 @@
     },
     "devDependencies": {
         "@diia-inhouse/configs": "6.1.1",
-        "@diia-inhouse/diia-logger": "3.20.6",
-        "@diia-inhouse/diia-metrics": "6.5.29",
-        "@diia-inhouse/errors": "1.18.19",
-        "@diia-inhouse/eslint-config": "8.8.0",
-        "@diia-inhouse/eslint-plugin": "1.9.5",
-        "@diia-inhouse/test": "7.3.18",
-        "@diia-inhouse/types": "12.0.1",
-        "@diia-inhouse/utils": "5.3.23",
-        "@diia-inhouse/validators": "1.28.30",
+        "@diia-inhouse/diia-logger": "3.20.12",
+        "@diia-inhouse/diia-metrics": "6.5.38",
+        "@diia-inhouse/errors": "1.18.23",
+        "@diia-inhouse/eslint-config": "8.8.2",
+        "@diia-inhouse/eslint-plugin": "1.9.6",
+        "@diia-inhouse/test": "7.3.23",
+        "@diia-inhouse/types": "12.0.4",
+        "@diia-inhouse/utils": "5.3.28",
+        "@diia-inhouse/validators": "1.28.34",
         "@opentelemetry/api": "1.9.0",
         "@types/lodash": "4.17.24",
         "@types/node": "24.11.0",