@heavybit/shared-lib 0.0.0-stage → 1.2.0

package/dist/cjs/messaging/outbox.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxRelay = exports.DEFAULT_OUTBOX_TABLE = void 0;
+exports.outboxRoutingKey = outboxRoutingKey;
+exports.enqueueOutbox = enqueueOutbox;
+const index_js_1 = require("../logging/index.js");
+const publisher_js_1 = require("./publisher.js");
+exports.DEFAULT_OUTBOX_TABLE = 'event_outbox';
+const COMMAND_PREFIX = 'command:';
+/** Outbox `routing_key` column value: the event type, or `command:<name>` for commands. */
+function outboxRoutingKey(envelope, kind = 'event') {
+    return kind === 'command' ? `${COMMAND_PREFIX}${envelope.type}` : envelope.type;
+}
+/**
+ * Transactional outbox: write the domain change and the event in one DB transaction, then a
+ * relay publishes pending rows with broker confirms. Closes the "row committed, event lost"
+ * gap of publish-after-commit. Consumers must be idempotent (they are: see IdempotencyStore).
+ *
+ * Table (see `createOutboxTable` in `@heavybit/shared-lib/knex`):
+ *   id CHAR(26) PK = eventId, routing_key, payload JSON, attempts, last_error, created_at, published_at
+ */
+async function enqueueOutbox(db, envelope, options = {}) {
+    await db(options.table ?? exports.DEFAULT_OUTBOX_TABLE).insert({
+        id: envelope.eventId,
+        routing_key: outboxRoutingKey(envelope, options.kind),
+        payload: JSON.stringify(envelope),
+        attempts: 0,
+        created_at: new Date(),
+    });
+}
+class OutboxRelay {
+    options;
+    timer = null;
+    running = null;
+    rerun = false;
+    logger;
+    table;
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? index_js_1.silentLogger;
+        this.table = options.table ?? exports.DEFAULT_OUTBOX_TABLE;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.trigger(); }, this.options.intervalMs ?? 2000);
+        void this.trigger();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Publishes pending rows now. Concurrent triggers coalesce into one follow-up run. */
+    async trigger() {
+        if (this.running) {
+            this.rerun = true;
+            return;
+        }
+        do {
+            this.rerun = false;
+            this.running = this.flush();
+            try {
+                await this.running;
+            }
+            finally {
+                this.running = null;
+            }
+        } while (this.rerun);
+    }
+    /** One batch. Returns how many rows were published. */
+    async flush() {
+        const { knex, bus } = this.options;
+        let published = 0;
+        try {
+            await knex.transaction(async (trx) => {
+                // SKIP LOCKED lets several replicas relay concurrently without double-publishing.
+                const rows = await trx(this.table)
+                    .select('id', 'routing_key', 'payload', 'attempts')
+                    .whereNull('published_at')
+                    .orderBy('id', 'asc')
+                    .limit(this.options.batchSize ?? 100)
+                    .forUpdate()
+                    .skipLocked();
+                for (const row of rows) {
+                    const envelope = (typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload);
+                    try {
+                        if (row.routing_key.startsWith(COMMAND_PREFIX))
+                            await bus.sendEnvelope(envelope);
+                        else
+                            await bus.publishEnvelope(envelope);
+                        await trx(this.table).where({ id: row.id }).update({ published_at: new Date(), last_error: null });
+                        published += 1;
+                    }
+                    catch (error) {
+                        await trx(this.table).where({ id: row.id }).update({ attempts: knex.raw('attempts + 1'), last_error: String(error.message).slice(0, 500) });
+                        // Unroutable: only this command's owner is missing. Keep the row for the next tick and carry on,
+                        // so one undeclared queue never holds back every other event behind it.
+                        if ((0, publisher_js_1.isUnroutableError)(error)) {
+                            this.reportUnroutable(row, error);
+                            continue;
+                        }
+                        // Broker down: stop this batch; the next tick retries in order.
+                        break;
+                    }
+                }
+            });
+        }
+        catch (error) {
+            this.logger.error('Outbox relay batch failed', { error: error.message });
+        }
+        if (published)
+            this.logger.debug('Outbox relayed', { published });
+        return published;
+    }
+    /**
+     * Logged on the 1st, 2nd, 4th, 8th… failure of a row (the attempt count before this one is in `attempts`),
+     * so a queue that stays missing for hours is still visible without a line every tick.
+     */
+    reportUnroutable(row, error) {
+        const attempt = Number(row.attempts ?? 0) + 1;
+        if ((attempt & (attempt - 1)) !== 0)
+            return;
+        this.logger.error('Outbox command is unroutable: its consumer queue is not declared; will retry', {
+            eventId: row.id, routingKey: row.routing_key, target: error.routingKey, attempt,
+        });
+    }
+    /** Deletes published rows older than `olderThanDays`. */
+    async prune(olderThanDays = 7) {
+        const cutoff = new Date(Date.now() - olderThanDays * 86_400_000);
+        return this.options.knex(this.table).whereNotNull('published_at').andWhere('published_at', '<', cutoff).delete();
+    }
+}
+exports.OutboxRelay = OutboxRelay;
+//# sourceMappingURL=outbox.js.map

package/dist/cjs/messaging/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../../src/messaging/outbox.ts"],"names":[],"mappings":"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"}

package/dist/cjs/messaging/publisher.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopMessageBus = exports.MessagePublisher = exports.UnroutableMessageError = void 0;
+exports.isUnroutableError = isUnroutableError;
+const errors_js_1 = require("../common/errors.js");
+const id_js_1 = require("../common/id.js");
+const index_js_1 = require("../logging/index.js");
+const envelope_js_1 = require("./envelope.js");
+/**
+ * The broker accepted a `mandatory` message but no queue was bound to receive it (the consumer has never
+ * started, or its binding is wrong). Retryable: the message is not lost — the caller (or the outbox relay)
+ * keeps it and tries again, and it goes through once the owner declares its queue.
+ */
+class UnroutableMessageError extends errors_js_1.ServiceUnavailableError {
+    exchange;
+    routingKey;
+    constructor(exchange, routingKey) {
+        super(`No queue is bound for ${exchange || '(default exchange)'} → ${routingKey}`, { code: 'UNROUTABLE' });
+        this.exchange = exchange;
+        this.routingKey = routingKey;
+    }
+}
+exports.UnroutableMessageError = UnroutableMessageError;
+function isUnroutableError(error) {
+    return error instanceof UnroutableMessageError;
+}
+const envelopeProps = (envelope, mandatory) => ({
+    mandatory, messageId: envelope.eventId, correlationId: envelope.correlationId, type: envelope.type,
+});
+/**
+ * Event and command publisher on a confirm channel: `publish()` resolves only once the broker
+ * has persisted the message, and rejects with 503 when the broker is unreachable so callers
+ * (or the outbox relay) can retry.
+ *
+ * Commands and direct queue sends are `mandatory`: a command has exactly one owner, so one that no
+ * queue receives is a fault, not a no-op. The broker returns it (`basic.return`, always before its
+ * confirm), and the send rejects with `UnroutableMessageError` instead of resolving as if delivered.
+ * Events stay non-mandatory: a topic event with no subscriber yet is normal fan-out.
+ */
+class MessagePublisher {
+    options;
+    handle = null;
+    logger;
+    /** Message ids the broker returned as unroutable, awaiting their confirm. */
+    returned = new Set();
+    constructor(options) {
+        this.options = options;
+        this.logger = options.logger ?? index_js_1.silentLogger;
+    }
+    async init() {
+        const { topology } = this.options;
+        this.handle = await this.options.connection.registerChannel('publisher', async (channel) => {
+            await channel.assertExchange(topology.eventsExchange, 'topic', { durable: true });
+            await channel.assertExchange(topology.commandsExchange, 'direct', { durable: true });
+            channel.on('return', (message) => {
+                const id = message.properties.messageId;
+                if (typeof id === 'string')
+                    this.returned.add(id);
+            });
+        }, { confirm: true });
+    }
+    async publish(type, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(type, data, this.options.source, meta);
+        await this.publishEnvelope(envelope);
+        return envelope;
+    }
+    async publishEnvelope(envelope) {
+        await this.write(this.options.topology.eventsExchange, envelope.type, envelope, envelopeProps(envelope, false));
+    }
+    async send(command, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(command, data, this.options.source, meta);
+        await this.sendEnvelope(envelope);
+        return envelope;
+    }
+    async sendEnvelope(envelope) {
+        await this.write(this.options.topology.commandsExchange, this.options.topology.queue(envelope.type), envelope, envelopeProps(envelope, true));
+    }
+    /**
+     * Sends `payload` as-is (no envelope) to `queue` through the default exchange. The queue is the
+     * consumer's to declare, so it is not asserted here; a missing queue rejects as unroutable.
+     */
+    async sendToQueue(queue, payload, options = {}) {
+        await this.write('', queue, payload, { mandatory: true, messageId: options.messageId ?? (0, id_js_1.newId)(), correlationId: options.correlationId });
+    }
+    write(exchange, routingKey, body, props) {
+        const channel = this.handle?.current();
+        if (!channel) {
+            return Promise.reject(new errors_js_1.ServiceUnavailableError('Message broker unavailable'));
+        }
+        const { messageId } = props;
+        return new Promise((resolve, reject) => {
+            channel.publish(exchange, routingKey, Buffer.from(JSON.stringify(body)), {
+                persistent: true,
+                mandatory: props.mandatory,
+                contentType: 'application/json',
+                messageId,
+                correlationId: props.correlationId,
+                type: props.type,
+                timestamp: Math.floor(Date.now() / 1000),
+                appId: this.options.source,
+            }, (error) => {
+                // The broker sends `basic.return` before the confirm, so a returned message is already recorded here.
+                const unroutable = this.returned.delete(messageId);
+                if (error) {
+                    this.logger.error('Broker rejected message', { routingKey, messageId, error: String(error) });
+                    reject(new errors_js_1.ServiceUnavailableError('Message broker rejected the message', { cause: error }));
+                }
+                else if (unroutable) {
+                    this.logger.warn('Broker could not route message: no queue is bound', { exchange, routingKey, messageId });
+                    reject(new UnroutableMessageError(exchange, routingKey));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+}
+exports.MessagePublisher = MessagePublisher;
+/** Stand-in when messaging is disabled (local tooling, tests): logs and drops. */
+class NoopMessageBus {
+    source;
+    logger;
+    constructor(source, logger = index_js_1.silentLogger) {
+        this.source = source;
+        this.logger = logger;
+    }
+    async publish(type, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(type, data, this.source, meta);
+        this.logger.debug('Messaging disabled; event dropped', { type, eventId: envelope.eventId });
+        return envelope;
+    }
+    async publishEnvelope(envelope) {
+        this.logger.debug('Messaging disabled; event dropped', { type: envelope.type, eventId: envelope.eventId });
+    }
+    async send(command, data, meta = {}) {
+        const envelope = (0, envelope_js_1.buildEnvelope)(command, data, this.source, meta);
+        this.logger.debug('Messaging disabled; command dropped', { command, eventId: envelope.eventId });
+        return envelope;
+    }
+    async sendEnvelope(envelope) {
+        this.logger.debug('Messaging disabled; command dropped', { command: envelope.type, eventId: envelope.eventId });
+    }
+    async sendToQueue(queue) {
+        this.logger.debug('Messaging disabled; queue message dropped', { queue });
+    }
+}
+exports.NoopMessageBus = NoopMessageBus;
+//# sourceMappingURL=publisher.js.map

package/dist/cjs/messaging/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../../../src/messaging/publisher.ts"],"names":[],"mappings":"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"}

package/dist/cjs/messaging/rpc.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RpcClient = exports.RpcServer = void 0;
+const errors_js_1 = require("../common/errors.js");
+const id_js_1 = require("../common/id.js");
+const index_js_1 = require("../logging/index.js");
+const REPLY_TO = 'amq.rabbitmq.reply-to';
+/**
+ * Request/response over RabbitMQ for the few synchronous cross-service calls that must fail
+ * cleanly (e.g. "create the profile before committing the account"). Uses direct reply-to, so
+ * no reply queue is declared per call, and sets the request TTL to the caller's timeout so a
+ * request the caller has given up on is never executed late.
+ */
+class RpcServer {
+    connection;
+    topology;
+    handles = [];
+    logger;
+    constructor(connection, topology, logger) {
+        this.connection = connection;
+        this.topology = topology;
+        this.logger = logger ?? index_js_1.silentLogger;
+    }
+    async handle(method, handler, options = {}) {
+        const queue = this.topology.queue(method);
+        this.handles.push(await this.connection.registerChannel(`rpc-server:${queue}`, async (channel) => {
+            await channel.assertQueue(queue, { durable: true });
+            await channel.prefetch(options.prefetch ?? 5);
+            await channel.consume(queue, (msg) => { if (msg)
+                void this.respond(channel, msg, handler); });
+        }));
+        this.logger.info('RPC method registered', { queue });
+    }
+    async respond(channel, msg, handler) {
+        let reply;
+        try {
+            const payload = JSON.parse(msg.content.toString('utf8'));
+            const data = await handler(payload, { correlationId: msg.properties.correlationId, callerService: msg.properties.appId });
+            reply = { ok: true, data };
+        }
+        catch (error) {
+            const status = (0, errors_js_1.isAppError)(error) ? error.statusCode : 500;
+            const message = (0, errors_js_1.isAppError)(error) && status < 500 ? error.message : 'RPC handler failed';
+            if (status >= 500)
+                this.logger.error('RPC handler error', { queue: msg.fields.routingKey, error: error.message });
+            reply = { ok: false, error: { status, code: (0, errors_js_1.isAppError)(error) ? error.code : 'INTERNAL_ERROR', message } };
+        }
+        if (msg.properties.replyTo) {
+            channel.sendToQueue(msg.properties.replyTo, Buffer.from(JSON.stringify(reply)), { correlationId: msg.properties.correlationId, contentType: 'application/json' });
+        }
+        channel.ack(msg);
+    }
+}
+exports.RpcServer = RpcServer;
+class RpcClient {
+    connection;
+    topology;
+    callerService;
+    handle = null;
+    pending = new Map();
+    logger;
+    constructor(connection, topology, callerService, logger) {
+        this.connection = connection;
+        this.topology = topology;
+        this.callerService = callerService;
+        this.logger = logger ?? index_js_1.silentLogger;
+    }
+    async init() {
+        this.handle = await this.connection.registerChannel('rpc-client', async (channel) => {
+            // A reconnect invalidates every in-flight reply.
+            this.failAll(new errors_js_1.ServiceUnavailableError('RPC channel reset'));
+            await channel.consume(REPLY_TO, (msg) => { if (msg)
+                this.onReply(msg); }, { noAck: true });
+        });
+    }
+    call(method, payload, options = {}) {
+        const channel = this.handle?.current();
+        if (!channel)
+            return Promise.reject(new errors_js_1.ServiceUnavailableError('Message broker unavailable'));
+        const timeoutMs = options.timeoutMs ?? 5000;
+        const id = (0, id_js_1.newId)();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                this.logger.warn('RPC timed out', { method, timeoutMs });
+                reject(new errors_js_1.ServiceUnavailableError(`Upstream did not respond in time (${method})`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            channel.sendToQueue(this.topology.queue(method), Buffer.from(JSON.stringify(payload)), {
+                correlationId: id,
+                replyTo: REPLY_TO,
+                contentType: 'application/json',
+                expiration: String(timeoutMs),
+                appId: this.callerService,
+                headers: options.correlationId ? { 'x-correlation-id': options.correlationId } : undefined,
+            });
+        });
+    }
+    onReply(msg) {
+        const entry = this.pending.get(msg.properties.correlationId);
+        if (!entry)
+            return;
+        this.pending.delete(msg.properties.correlationId);
+        clearTimeout(entry.timer);
+        try {
+            const reply = JSON.parse(msg.content.toString('utf8'));
+            if (reply.ok)
+                entry.resolve(reply.data);
+            else
+                entry.reject(new errors_js_1.AppError(reply.error.status, reply.error.message, { code: reply.error.code }));
+        }
+        catch (error) {
+            entry.reject(new errors_js_1.ServiceUnavailableError('Malformed RPC reply', { cause: error }));
+        }
+    }
+    failAll(error) {
+        for (const [id, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+            this.pending.delete(id);
+        }
+    }
+}
+exports.RpcClient = RpcClient;
+//# sourceMappingURL=rpc.js.map

package/dist/cjs/messaging/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../../src/messaging/rpc.ts"],"names":[],"mappings":"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"}

package/dist/cjs/messaging/staff-notifier.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staffEmailListSchema = exports.StaffNotifier = exports.ConfiguredStaffRecipients = void 0;
+const zod_1 = require("zod");
+const notification_dispatch_js_1 = require("../contracts/notification-dispatch.js");
+const index_js_1 = require("../logging/index.js");
+/** Recipients from configuration (env), keyed by the permission an alert targets. */
+class ConfiguredStaffRecipients {
+    byPermission;
+    constructor(byPermission) {
+        this.byPermission = byPermission;
+    }
+    async resolve(permission) {
+        return [...(this.byPermission[permission] ?? [])];
+    }
+}
+exports.ConfiguredStaffRecipients = ConfiguredStaffRecipients;
+/**
+ * Stages one `notification:dispatch` per recipient through the outbox, in the caller's transaction, so an
+ * alert is sent if and only if the state change that raised it commits. Never sends email itself.
+ * An alert that resolves to nobody is logged as a warning (an unconfigured list must not fail silently).
+ */
+class StaffNotifier {
+    outbox;
+    recipients;
+    logger;
+    constructor(outbox, recipients, logger = index_js_1.silentLogger) {
+        this.outbox = outbox;
+        this.recipients = recipients;
+        this.logger = logger;
+    }
+    /** Returns how many commands were staged. */
+    async alert(executor, alert, meta = {}) {
+        const targets = await this.recipients.resolve(alert.permission);
+        if (targets.length === 0) {
+            this.logger.warn('Staff alert not sent: no recipients are configured', { template: alert.template, permission: alert.permission });
+            return 0;
+        }
+        for (const recipient of targets) {
+            const dispatch = {
+                template: alert.template,
+                category: 'staff',
+                recipient,
+                channels: alert.channels ?? ['email'],
+                data: alert.data,
+                bypassPreferences: true,
+                targetPermission: alert.permission,
+            };
+            await this.outbox.command(executor, notification_dispatch_js_1.NOTIFICATION_DISPATCH, dispatch, { ...meta, actorId: null });
+        }
+        return targets.length;
+    }
+}
+exports.StaffNotifier = StaffNotifier;
+const emailSchema = zod_1.z.string().email().max(notification_dispatch_js_1.DISPATCH_LIMITS.email);
+/**
+ * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
+ * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
+ * instead of dead-lettering in notification-service when the alert finally fires.
+ */
+exports.staffEmailListSchema = zod_1.z
+    .string()
+    .optional()
+    .transform((csv) => {
+    const seen = new Set();
+    return (csv ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((email) => email && !seen.has(email.toLowerCase()) && seen.add(email.toLowerCase()));
+})
+    .superRefine((emails, ctx) => {
+    for (const email of emails) {
+        if (!emailSchema.safeParse(email).success)
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: `Not a valid email address: ${email}` });
+    }
+})
+    .transform((emails) => emails.map((email) => ({ email })));
+//# sourceMappingURL=staff-notifier.js.map

package/dist/cjs/messaging/staff-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff-notifier.js","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"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"}

package/dist/cjs/messaging/topology.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deadLetterQueueName = exports.retryQueueName = void 0;
+exports.createTopology = createTopology;
+function createTopology(options) {
+    const app = options.app.trim();
+    const prefix = options.prefix.trim();
+    if (!app || !prefix)
+        throw new Error('Topology requires both app and prefix');
+    return {
+        app,
+        prefix,
+        eventsExchange: `${app}.${prefix}.events`,
+        commandsExchange: `${app}.${prefix}.commands`,
+        queue: (name) => (name.startsWith(`${prefix}.`) ? name : `${prefix}.${name}`),
+    };
+}
+const retryQueueName = (queue, delayMs) => `${queue}.retry.${delayMs}`;
+exports.retryQueueName = retryQueueName;
+const deadLetterQueueName = (queue) => `${queue}.dlq`;
+exports.deadLetterQueueName = deadLetterQueueName;
+//# sourceMappingURL=topology.js.map

package/dist/cjs/messaging/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":";;;AAiBA,wCAWC;AAXD,SAAgB,cAAc,CAAC,OAAwC;IACrE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC9E,OAAO;QACL,GAAG;QACH,MAAM;QACN,cAAc,EAAE,GAAG,GAAG,IAAI,MAAM,SAAS;QACzC,gBAAgB,EAAE,GAAG,GAAG,IAAI,MAAM,WAAW;QAC7C,KAAK,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;KACtF,CAAC;AACJ,CAAC;AAEM,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,OAAe,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,OAAO,EAAE,CAAC;AAAjF,QAAA,cAAc,kBAAmE;AACvF,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC;AAAxD,QAAA,mBAAmB,uBAAqC"}

package/dist/cjs/metrics/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDefaultMetrics = exports.Summary = exports.Registry = exports.Histogram = exports.Gauge = exports.Counter = void 0;
+/**
+ * Prometheus metrics. Re-exports prom-client so every service runs one version of it;
+ * services keep their own metric definitions behind a narrow interface.
+ */
+var prom_client_1 = require("prom-client");
+Object.defineProperty(exports, "Counter", { enumerable: true, get: function () { return prom_client_1.Counter; } });
+Object.defineProperty(exports, "Gauge", { enumerable: true, get: function () { return prom_client_1.Gauge; } });
+Object.defineProperty(exports, "Histogram", { enumerable: true, get: function () { return prom_client_1.Histogram; } });
+Object.defineProperty(exports, "Registry", { enumerable: true, get: function () { return prom_client_1.Registry; } });
+Object.defineProperty(exports, "Summary", { enumerable: true, get: function () { return prom_client_1.Summary; } });
+Object.defineProperty(exports, "collectDefaultMetrics", { enumerable: true, get: function () { return prom_client_1.collectDefaultMetrics; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,2CAAkG;AAAzF,sGAAA,OAAO,OAAA;AAAE,oGAAA,KAAK,OAAA;AAAE,wGAAA,SAAS,OAAA;AAAE,uGAAA,QAAQ,OAAA;AAAE,sGAAA,OAAO,OAAA;AAAE,oHAAA,qBAAqB,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/rate-limit/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLimiter = createLimiter;
+exports.consumeOrThrow = consumeOrThrow;
+exports.rateLimitMiddleware = rateLimitMiddleware;
+const rate_limiter_flexible_1 = require("rate-limiter-flexible");
+const response_js_1 = require("../common/response.js");
+const errors_js_1 = require("../common/errors.js");
+const index_js_1 = require("../logging/index.js");
+/** Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. */
+function createLimiter(options) {
+    const memory = new rate_limiter_flexible_1.RateLimiterMemory({ keyPrefix: options.keyPrefix, points: options.points, duration: options.durationSec, blockDuration: options.blockDurationSec ?? 0 });
+    if (!options.redis)
+        return memory;
+    return new rate_limiter_flexible_1.RateLimiterRedis({
+        storeClient: options.redis,
+        keyPrefix: options.keyPrefix,
+        points: options.points,
+        duration: options.durationSec,
+        blockDuration: options.blockDurationSec ?? 0,
+        insuranceLimiter: memory,
+    });
+}
+/**
+ * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
+ * For in-service checks such as per-identifier login throttling.
+ */
+async function consumeOrThrow(limiter, key, message) {
+    try {
+        await limiter.consume(key);
+    }
+    catch (rejection) {
+        if (typeof rejection?.msBeforeNext === 'number')
+            throw new errors_js_1.TooManyRequestsError(message);
+        throw rejection;
+    }
+}
+function rateLimitMiddleware(options) {
+    const limiter = createLimiter(options);
+    const logger = options.logger ?? index_js_1.silentLogger;
+    const keyOf = options.keyOf ?? ((req) => req.user?.id ?? req.ip ?? 'unknown');
+    return async (req, res, next) => {
+        try {
+            const result = await limiter.consume(keyOf(req));
+            res.setHeader('X-RateLimit-Limit', options.points);
+            res.setHeader('X-RateLimit-Remaining', result.remainingPoints);
+            next();
+        }
+        catch (rejection) {
+            const ms = rejection?.msBeforeNext;
+            if (typeof ms !== 'number') {
+                logger.error('Rate limiter failure; allowing request', { keyPrefix: options.keyPrefix, error: String(rejection) });
+                next();
+                return;
+            }
+            res.setHeader('Retry-After', Math.ceil(ms / 1000));
+            res.status(429).json((0, response_js_1.errorResponse)('Too many requests. Please try again later.', undefined, 'RATE_LIMITED'));
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":";;AAoBA,sCAWC;AAMD,wCAOC;AAOD,kDAsBC;AAvED,iEAAsG;AACtG,uDAAsD;AACtD,mDAA2D;AAC3D,kDAAmD;AAcnD,gGAAgG;AAChG,SAAgB,aAAa,CAAC,OAAyB;IACrD,MAAM,MAAM,GAAG,IAAI,yCAAiB,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5K,IAAI,CAAC,OAAO,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAClC,OAAO,IAAI,wCAAgB,CAAC;QAC1B,WAAW,EAAE,OAAO,CAAC,KAAK;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,WAAW;QAC7B,aAAa,EAAE,OAAO,CAAC,gBAAgB,IAAI,CAAC;QAC5C,gBAAgB,EAAE,MAAM;KACzB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,cAAc,CAAC,OAA4B,EAAE,GAAW,EAAE,OAAgB;IAC9F,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,IAAI,OAAQ,SAAuC,EAAE,YAAY,KAAK,QAAQ;YAAE,MAAM,IAAI,gCAAoB,CAAC,OAAO,CAAC,CAAC;QACxH,MAAM,SAAS,CAAC;IAClB,CAAC;AACH,CAAC;AAOD,SAAgB,mBAAmB,CAAC,OAAmC;IACrE,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,uBAAY,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,SAAS,CAAC,CAAC;IAEvF,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAiB,EAAE;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACnD,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;YAC/D,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,EAAE,GAAI,SAAuC,EAAE,YAAY,CAAC;YAClE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBACnH,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACnD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,2BAAa,EAAC,4CAA4C,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}