@diia-inhouse/diia-queue 13.3.4 → 14.0.11

package/dist/services/eventMessageHandler.d.ts

@@ -0,0 +1,27 @@
+import { QueueMessage } from "../interfaces/providers/rabbitmq/index.js";
+import { QueueContext } from "../interfaces/queueContext.js";
+import { EventBusListener, EventListeners, TaskListener } from "../interfaces/index.js";
+import { EventMessageValidator } from "./eventMessageValidator.js";
+import Logger from "@diia-inhouse/diia-logger";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/services/eventMessageHandler.d.ts
+declare class EventMessageHandler {
+  private readonly eventMessageValidator;
+  private readonly asyncLocalStorage;
+  private readonly logger;
+  private readonly noRequeueNackOptions;
+  constructor(eventMessageValidator: EventMessageValidator, asyncLocalStorage: AsyncLocalStorage<QueueContext>, logger: Logger);
+  eventListenersMessageHandler(this: this, eventListeners: EventListeners, message: QueueMessage | null): Promise<void>;
+  eventListenerMessageHandler(listener: EventBusListener | TaskListener | undefined, message: QueueMessage): Promise<void>;
+  private prepareAsyncContext;
+  private handleMessage;
+  private validateData;
+  private directReplyDone;
+  private getServiceCode;
+  private prepareQueueMessageError;
+  private resolveTraceId;
+  private extractTraceparentTraceId;
+}
+//#endregion
+export { EventMessageHandler };

package/dist/services/eventMessageHandler.js

@@ -1,129 +1,124 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventMessageHandler = void 0;
-const node_crypto_1 = require("node:crypto");
-const api_1 = require("@opentelemetry/api");
-const errors_1 = require("@diia-inhouse/errors");
-const utils_1 = require("@diia-inhouse/utils");
-const interfaces_1 = require("../interfaces");
-class EventMessageHandler {
-    eventMessageValidator;
-    asyncLocalStorage;
-    logger;
-    noRequeueNackOptions = new interfaces_1.NackOptions(false, false);
-    constructor(eventMessageValidator, asyncLocalStorage, logger) {
-        this.eventMessageValidator = eventMessageValidator;
-        this.asyncLocalStorage = asyncLocalStorage;
-        this.logger = logger;
-    }
-    async eventListenersMessageHandler(eventListeners, message) {
-        if (!message) {
-            return;
-        }
-        const listener = eventListeners[message.data.event];
-        await this.eventListenerMessageHandler(listener, message);
-    }
-    async eventListenerMessageHandler(listener, message) {
-        const { done, properties, data: { event, payload }, } = message;
-        const serviceCode = this.getServiceCode(listener, payload);
-        const context = this.prepareAsyncContext(properties, serviceCode);
-        await this.asyncLocalStorage.run(context, async () => {
-            this.logger.info(`Handling event [${event}] with payload`, { payload });
-            if (!listener) {
-                this.logger.info(`Not found listener for the event [${event}]`);
-                return done();
-            }
-            return await this.handleMessage(listener, message);
-        });
-    }
-    prepareAsyncContext(properties, serviceCode) {
-        const activeSpanTraceId = api_1.trace.getActiveSpan()?.spanContext().traceId ?? '';
-        const traceId = (0, api_1.isValidTraceId)(activeSpanTraceId) ? activeSpanTraceId : properties.headers?.traceId || (0, node_crypto_1.randomUUID)();
-        return {
-            logData: {
-                traceId,
-                serviceCode,
-            },
-        };
-    }
-    async handleMessage(listener, message) {
-        const { data, done, reject, properties: { replyTo, correlationId }, } = message;
-        const { event, payload, meta } = data;
-        const useDirectReply = replyTo && correlationId;
-        let hasErrorOccurred = false;
-        let result;
-        const { isValid, error } = await this.validateData(data, listener);
-        if (!isValid) {
-            if (useDirectReply && error) {
-                return this.directReplyDone(message, error, true);
-            }
-            return reject(this.noRequeueNackOptions);
-        }
-        try {
-            result = await listener.handler?.(payload, meta);
-        }
-        catch (err) {
-            result = err;
-            hasErrorOccurred = true;
-            this.logger.error(`Failed to handle event ${event}`, { err });
-        }
-        if (useDirectReply) {
-            return this.directReplyDone(message, result, hasErrorOccurred);
-        }
-        if (result instanceof interfaces_1.NackOptions) {
-            return reject(result);
-        }
-        else if (hasErrorOccurred && listener.nackOptions) {
-            return reject(listener.nackOptions);
-        }
-        return done();
-    }
-    async validateData(data, listener) {
-        const { payload } = data;
-        const { validationRules } = listener;
-        try {
-            this.eventMessageValidator.validateEventMessage(data, validationRules);
-            return { isValid: true };
-        }
-        catch (err) {
-            this.logger.error('Failed to validate event message', { err });
-            if (err instanceof errors_1.ValidationError && 'validationErrorHandler' in listener && payload?.uuid) {
-                const eventBusListener = listener;
-                await eventBusListener.validationErrorHandler?.(err, payload.uuid).catch((err_) => err_);
-            }
-            return err instanceof errors_1.ValidationError ? { isValid: false, error: err } : { isValid: false };
-        }
-    }
-    directReplyDone(receivedMessage, response, error) {
-        const { done, data: { event, payload: { uuid }, }, } = receivedMessage;
-        const data = error ? utils_1.utils.handleError(response, (err) => err) : response;
-        const messageData = {
-            event,
-            meta: {
-                date: new Date(),
-            },
-            payload: {
-                uuid,
-                ...(data instanceof errors_1.ApiError ? { error: this.prepareQueueMessageError(data) } : { response: data }),
-            },
-        };
-        done(messageData);
-    }
-    getServiceCode(listener, payload) {
-        try {
-            return listener?.getServiceCode?.(payload);
-        }
-        catch (err) {
-            this.logger.error('Failed to get event listener service code', { err, listener });
-        }
-    }
-    prepareQueueMessageError(err) {
-        return {
-            data: err.getData(),
-            message: err.message,
-            http_code: err.getCode(),
-        };
-    }
-}
-exports.EventMessageHandler = EventMessageHandler;
-//# sourceMappingURL=eventMessageHandler.js.map
+import { NackOptions } from "../interfaces/providers/rabbitmq/index.js";
+import "../interfaces/index.js";
+import { ApiError, ValidationError } from "@diia-inhouse/errors";
+import { randomBytes } from "node:crypto";
+import { isValidTraceId, trace } from "@opentelemetry/api";
+import { utils } from "@diia-inhouse/utils";
+//#region src/services/eventMessageHandler.ts
+var EventMessageHandler = class {
+	eventMessageValidator;
+	asyncLocalStorage;
+	logger;
+	noRequeueNackOptions = new NackOptions(false, false);
+	constructor(eventMessageValidator, asyncLocalStorage, logger) {
+		this.eventMessageValidator = eventMessageValidator;
+		this.asyncLocalStorage = asyncLocalStorage;
+		this.logger = logger;
+	}
+	async eventListenersMessageHandler(eventListeners, message) {
+		if (!message) return;
+		const listener = eventListeners[message.data.event];
+		await this.eventListenerMessageHandler(listener, message);
+	}
+	async eventListenerMessageHandler(listener, message) {
+		const { done, properties, data: { event, payload } } = message;
+		const serviceCode = this.getServiceCode(listener, payload);
+		const context = this.prepareAsyncContext(properties, serviceCode);
+		await this.asyncLocalStorage.run(context, async () => {
+			this.logger.info(`Handling event [${event}] with payload`, { payload });
+			if (!listener) {
+				this.logger.info(`Not found listener for the event [${event}]`);
+				return done();
+			}
+			return await this.handleMessage(listener, message);
+		});
+	}
+	prepareAsyncContext(properties, serviceCode) {
+		return { logData: {
+			traceId: this.resolveTraceId(properties),
+			serviceCode
+		} };
+	}
+	async handleMessage(listener, message) {
+		const { data, done, reject, properties: { replyTo, correlationId } } = message;
+		const { event, payload, meta } = data;
+		const useDirectReply = replyTo && correlationId;
+		let hasErrorOccurred = false;
+		let result;
+		const { isValid, error } = await this.validateData(data, listener);
+		if (!isValid) {
+			if (useDirectReply && error) return this.directReplyDone(message, error, true);
+			return reject(this.noRequeueNackOptions);
+		}
+		try {
+			result = await listener.handler?.(payload, meta);
+		} catch (err) {
+			result = err;
+			hasErrorOccurred = true;
+			this.logger.error(`Failed to handle event ${event}`, { err });
+		}
+		if (useDirectReply) return this.directReplyDone(message, result, hasErrorOccurred);
+		if (result instanceof NackOptions) return reject(result);
+		else if (hasErrorOccurred && listener.nackOptions) return reject(listener.nackOptions);
+		return done();
+	}
+	async validateData(data, listener) {
+		const { payload } = data;
+		const { validationRules } = listener;
+		try {
+			this.eventMessageValidator.validateEventMessage(data, validationRules);
+			return { isValid: true };
+		} catch (err) {
+			this.logger.error("Failed to validate event message", { err });
+			if (err instanceof ValidationError && "validationErrorHandler" in listener && payload?.uuid) await listener.validationErrorHandler?.(err, payload.uuid).catch((err_) => err_);
+			return err instanceof ValidationError ? {
+				isValid: false,
+				error: err
+			} : { isValid: false };
+		}
+	}
+	directReplyDone(receivedMessage, response, error) {
+		const { done, data: { event, payload: { uuid } } } = receivedMessage;
+		const data = error ? utils.handleError(response, (err) => err) : response;
+		done({
+			event,
+			meta: { date: /* @__PURE__ */ new Date() },
+			payload: {
+				uuid,
+				...data instanceof ApiError ? { error: this.prepareQueueMessageError(data) } : { response: data }
+			}
+		});
+	}
+	getServiceCode(listener, payload) {
+		try {
+			return listener?.getServiceCode?.(payload);
+		} catch (err) {
+			this.logger.error("Failed to get event listener service code", {
+				err,
+				listener
+			});
+		}
+	}
+	prepareQueueMessageError(err) {
+		return {
+			data: err.getData(),
+			message: err.message,
+			http_code: err.getCode()
+		};
+	}
+	resolveTraceId(properties) {
+		const extractedTraceId = this.extractTraceparentTraceId(properties.headers?.traceparent);
+		if (isValidTraceId(extractedTraceId)) return extractedTraceId;
+		const activeSpanTraceId = trace.getActiveSpan()?.spanContext().traceId ?? "";
+		if (isValidTraceId(activeSpanTraceId)) return activeSpanTraceId;
+		return properties.headers?.traceId || randomBytes(16).toString("hex");
+	}
+	extractTraceparentTraceId(raw) {
+		if (raw === void 0 || raw === null) return "";
+		const [version, traceId] = (Buffer.isBuffer(raw) ? raw.toString("utf8") : raw).split("-");
+		if (version !== "00" || !traceId) return "";
+		return isValidTraceId(traceId) ? traceId : "";
+	}
+};
+//#endregion
+export { EventMessageHandler };

package/dist/services/eventMessageValidator.d.ts

@@ -0,0 +1,13 @@
+import { QueueMessageData } from "../interfaces/providers/rabbitmq/index.js";
+import { AppValidator, ValidationSchema } from "@diia-inhouse/validators";
+
+//#region src/services/eventMessageValidator.d.ts
+declare class EventMessageValidator {
+  private readonly validator;
+  readonly metaValidationSchema: ValidationSchema;
+  constructor(validator: AppValidator);
+  validateEventMessage(data: QueueMessageData, payloadValidationSchema?: ValidationSchema): void | never;
+  validateSyncedEventMessage(data: QueueMessageData, responseValidationSchema?: ValidationSchema): void | never;
+}
+//#endregion
+export { EventMessageValidator };

package/dist/services/eventMessageValidator.js

@@ -1,44 +1,59 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventMessageValidator = void 0;
-class EventMessageValidator {
-    validator;
-    metaValidationSchema = {
-        date: { type: 'date', convert: true },
-        traceId: { type: 'string', optional: true },
-    };
-    constructor(validator) {
-        this.validator = validator;
-    }
-    validateEventMessage(data, payloadValidationSchema = {}) {
-        const validationSchema = {
-            event: { type: 'string' },
-            payload: { type: 'object', props: payloadValidationSchema },
-            meta: {
-                type: 'object',
-                props: this.metaValidationSchema,
-            },
-        };
-        this.validator.validate(data, validationSchema);
-    }
-    validateSyncedEventMessage(data, responseValidationSchema) {
-        const validation = {
-            uuid: { type: 'uuid' },
-            error: {
-                type: 'object',
-                optional: true,
-                props: {
-                    http_code: { type: 'number' },
-                    message: { type: 'string', optional: true },
-                    data: { type: 'object', optional: true },
-                },
-            },
-        };
-        if (responseValidationSchema) {
-            validation.response = { type: 'object', optional: true, props: responseValidationSchema };
-        }
-        this.validateEventMessage(data, validation);
-    }
-}
-exports.EventMessageValidator = EventMessageValidator;
-//# sourceMappingURL=eventMessageValidator.js.map
+//#region src/services/eventMessageValidator.ts
+var EventMessageValidator = class {
+	validator;
+	metaValidationSchema = {
+		date: {
+			type: "date",
+			convert: true
+		},
+		traceId: {
+			type: "string",
+			optional: true
+		}
+	};
+	constructor(validator) {
+		this.validator = validator;
+	}
+	validateEventMessage(data, payloadValidationSchema = {}) {
+		const validationSchema = {
+			event: { type: "string" },
+			payload: {
+				type: "object",
+				props: payloadValidationSchema
+			},
+			meta: {
+				type: "object",
+				props: this.metaValidationSchema
+			}
+		};
+		this.validator.validate(data, validationSchema);
+	}
+	validateSyncedEventMessage(data, responseValidationSchema) {
+		const validation = {
+			uuid: { type: "uuid" },
+			error: {
+				type: "object",
+				optional: true,
+				props: {
+					http_code: { type: "number" },
+					message: {
+						type: "string",
+						optional: true
+					},
+					data: {
+						type: "object",
+						optional: true
+					}
+				}
+			}
+		};
+		if (responseValidationSchema) validation.response = {
+			type: "object",
+			optional: true,
+			props: responseValidationSchema
+		};
+		this.validateEventMessage(data, validation);
+	}
+};
+//#endregion
+export { EventMessageValidator };

package/dist/services/externalCommunicator.d.ts

@@ -0,0 +1,114 @@
+import { ReceiveDirectOps } from "../interfaces/externalCommunicator.js";
+import { ExternalEventBusQueue } from "../interfaces/index.js";
+import { EventMessageValidator } from "./eventMessageValidator.js";
+import Logger from "@diia-inhouse/diia-logger";
+
+//#region src/services/externalCommunicator.d.ts
+declare class ExternalCommunicator {
+  private readonly externalEventBus;
+  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, ops: ReceiveDirectOps): Promise<T>;
+}
+//#endregion
+export { ExternalCommunicator };