@palmetto/pubsub 3.0.2 → 3.2.0

package/dist/bullmq/publisher.js

@@ -41,18 +41,19 @@ class BullMqPublisher {
             var _a, _b;
             const queue = yield this.getQueue(config);
             (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `Publishing ${messages.length} messages to ${queue.name}`);
+            const opts = {
+                delay: (options === null || options === void 0 ? void 0 : options.scheduledAt)
+                    ? Math.max(0, options.scheduledAt.getTime() - Date.now())
+                    : undefined,
+                attempts: config.retries !== undefined ? config.retries + 1 : undefined,
+                backoff: {
+                    type: "fixed",
+                    delay: config.retryDelay || 30000,
+                },
+            };
             const job = {
                 name: config.job || connection_js_1.BULLMQ_DEFAULTJOB,
-                opts: {
-                    delay: (options === null || options === void 0 ? void 0 : options.scheduledAt)
-                        ? Math.max(0, options.scheduledAt.getTime() - Date.now())
-                        : undefined,
-                    attempts: config.retries,
-                    backoff: {
-                        type: "fixed",
-                        delay: config.retryDelay || 30000,
-                    },
-                },
+                opts,
             };
             const jobs = messages.map((data) => {
                 return Object.assign(Object.assign({}, job), { data });

package/dist/bullmq/subscriber.d.ts

@@ -9,9 +9,11 @@ declare class SubscribedMessage {
     stopSubscribe(): Promise<void>;
 }
 export declare class MessageFailError extends Error {
+    static readonly failedReason = "Handler asked to fail this job";
     constructor();
 }
 export declare class MessageRetryError extends Error {
+    static readonly failedReason = "Handler asked to retry this job";
     constructor();
 }
 export declare class BullMqSubscriber implements SubscriberProvider {
@@ -24,5 +26,6 @@ export declare class BullMqSubscriber implements SubscriberProvider {
     startSubscribe(config: BullMqQueueConfiguration, onMessage: (s: string, context: BullMqMessageContext) => Promise<MessageResult> | MessageResult): Promise<StopSubscribe>;
     close(): Promise<void>;
     enrichHandledMesssageLog(config: BullMqQueueConfiguration): Record<string, unknown>;
+    willRetryJobOnFailure(job: bullmq.Job<string>): boolean;
 }
 export {};

package/dist/bullmq/subscriber.js

@@ -32,16 +32,18 @@ class SubscribedMessage {
 }
 class MessageFailError extends Error {
     constructor() {
-        super("Handler asked to fail this job");
+        super(MessageFailError.failedReason);
     }
 }
 exports.MessageFailError = MessageFailError;
+MessageFailError.failedReason = "Handler asked to fail this job";
 class MessageRetryError extends Error {
     constructor() {
-        super("Handler asked to retry this job");
+        super(MessageRetryError.failedReason);
     }
 }
 exports.MessageRetryError = MessageRetryError;
+MessageRetryError.failedReason = "Handler asked to retry this job";
 class BullMqSubscriber {
     constructor(connection, logger) {
         this.connection = connection;
@@ -70,9 +72,10 @@ class BullMqSubscriber {
                 }, () => __awaiter(this, void 0, void 0, function* () {
                     const context = {
                         job: job.name,
-                        retries: job.attemptsMade,
+                        attemptsMade: job.attemptsMade,
                         firstSent: new Date(job.timestamp),
-                        // lastSent: new Date(job.attemptsStarted),
+                        lastSent: undefined,
+                        willRetryOnFailure: this.willRetryJobOnFailure(job),
                     };
                     const result = yield onMessage(job.data, context);
                     if (result === interfaces_js_1.MessageResult.Ok) {
@@ -81,7 +84,8 @@ class BullMqSubscriber {
                     if (result === interfaces_js_1.MessageResult.Retry) {
                         throw new MessageRetryError();
                     }
-                    throw new BullMqPackage.UnrecoverableError("Handler asked to fail this job");
+                    // result === MessageResult.Fail
+                    throw new BullMqPackage.UnrecoverableError(MessageFailError.failedReason);
                 }));
             }), {
                 connection: this.connection,
@@ -91,10 +95,30 @@ class BullMqSubscriber {
                 if (!job) {
                     return;
                 }
-                this.logger.log(`Job failed ${err}`);
+                if (job.failedReason !== MessageRetryError.failedReason &&
+                    job.failedReason !== MessageFailError.failedReason) {
+                    const log = {
+                        message: "BullMq PubSub job failed",
+                        error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
+                        extra: {
+                            job: config.name,
+                            message: job.data,
+                            attemptsMade: job.attemptsMade,
+                            failedReason: job.failedReason,
+                        },
+                    };
+                    this.logger.error(log);
+                }
             });
             worker.on("error", (err) => {
-                this.logger.error(`BullMq PubSub handler exception: ${err}`);
+                const log = {
+                    message: "BullMq PubSub handler exception",
+                    error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
+                    extra: {
+                        job: config.name,
+                    },
+                };
+                this.logger.error(log);
             });
             (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `BullMq PubSub subscriber starting for ${worker.name}`);
             worker
@@ -128,5 +152,9 @@ class BullMqSubscriber {
             job: config.job,
         };
     }
+    willRetryJobOnFailure(job) {
+        var _a;
+        return job.attemptsMade + 1 < ((_a = job.opts.attempts) !== null && _a !== void 0 ? _a : 1);
+    }
 }
 exports.BullMqSubscriber = BullMqSubscriber;

package/dist/gcppubsub/config.d.ts

@@ -0,0 +1,34 @@
+import { type PubSub } from "@google-cloud/pubsub";
+import { MessageContext, PubSubConfiguration } from "../interfaces.js";
+import { GCP_PUBSUB_TRANSPORT } from "./connection.js";
+export interface GcpPubSubConfiguration extends PubSubConfiguration {
+    /**
+     * Transport is always GCP_PUBSUB_TRANSPORT
+     */
+    transport: typeof GCP_PUBSUB_TRANSPORT;
+    /**
+     * The Pub/Sub topic name. Defaults to `name` if omitted.
+     */
+    topicName?: string;
+    /**
+     * The Pub/Sub subscription name. Required for subscribers. Defaults to `name` if omitted.
+     */
+    subscriptionName?: string;
+    /**
+     * Flow control: max outstanding messages (default: 5)
+     */
+    maxMessages?: number;
+}
+export type TopicType = "default" | "dead-letter";
+export declare const TopicNameExtensions: Record<TopicType, string | undefined>;
+export interface GcpPubSubMessageContext extends MessageContext {
+    messageId: string;
+    subscriptionName: string;
+    topicName: string;
+    orderingKey?: string;
+}
+export declare function getTopicName(config: GcpPubSubConfiguration, topicType: TopicType): string;
+export declare function getSubscriptionName(config: GcpPubSubConfiguration): string;
+export declare function isGcpPubSubConfiguration(config: PubSubConfiguration): config is GcpPubSubConfiguration;
+export declare function ensureTopic(client: PubSub, topicName: string): Promise<void>;
+export declare function ensureSubscription(client: PubSub, topicName: string, subscriptionName: string, retryDelay: number): Promise<void>;

package/dist/gcppubsub/config.js

@@ -0,0 +1,59 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopicNameExtensions = void 0;
+exports.getTopicName = getTopicName;
+exports.getSubscriptionName = getSubscriptionName;
+exports.isGcpPubSubConfiguration = isGcpPubSubConfiguration;
+exports.ensureTopic = ensureTopic;
+exports.ensureSubscription = ensureSubscription;
+const connection_js_1 = require("./connection.js");
+exports.TopicNameExtensions = {
+    "dead-letter": ".dl",
+    default: undefined,
+};
+function getTopicName(config, topicType) {
+    var _a, _b;
+    const baseName = (_a = config.topicName) !== null && _a !== void 0 ? _a : config.name;
+    const extension = (_b = exports.TopicNameExtensions[topicType]) !== null && _b !== void 0 ? _b : "";
+    return `${baseName}${extension}`;
+}
+function getSubscriptionName(config) {
+    var _a;
+    return (_a = config.subscriptionName) !== null && _a !== void 0 ? _a : getTopicName(config, "default");
+}
+function isGcpPubSubConfiguration(config) {
+    return config.transport === connection_js_1.GCP_PUBSUB_TRANSPORT;
+}
+function ensureTopic(client, topicName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const topics = (yield client.getTopics())[0];
+        if (!topics.some((t) => t.name.endsWith(`/${topicName}`))) {
+            yield client.createTopic(topicName);
+        }
+    });
+}
+function ensureSubscription(client, topicName, subscriptionName, retryDelay) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield ensureTopic(client, topicName);
+        const subscriptions = (yield client.getSubscriptions())[0];
+        if (!subscriptions.some((s) => s.name.endsWith(`/${subscriptionName}`))) {
+            yield client.createSubscription(topicName, subscriptionName, {
+                retryPolicy: {
+                    minimumBackoff: {
+                        nanos: (retryDelay % 1000) * 1000000,
+                        seconds: Math.floor(retryDelay / 1000),
+                    },
+                },
+            });
+        }
+    });
+}

package/dist/gcppubsub/connection.d.ts

@@ -0,0 +1,14 @@
+import type * as gcppubsub from "@google-cloud/pubsub";
+import { Logger } from "../interfaces.js";
+export declare const GCP_PUBSUB_TRANSPORT = "gcp-pubsub";
+export interface GcpPubSubConnectionConfig {
+    projectId?: string;
+    clientConfig?: gcppubsub.ClientConfig;
+}
+export declare class GcpPubSubConnection {
+    readonly client: gcppubsub.PubSub;
+    private readonly logger;
+    static create(config: GcpPubSubConnectionConfig, logger: Logger): Promise<GcpPubSubConnection>;
+    private constructor();
+    close(): Promise<void>;
+}

package/dist/gcppubsub/connection.js

@@ -0,0 +1,38 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpPubSubConnection = exports.GCP_PUBSUB_TRANSPORT = void 0;
+const lazy_load_js_1 = require("../lazy-load.js");
+exports.GCP_PUBSUB_TRANSPORT = "gcp-pubsub";
+class GcpPubSubConnection {
+    static create(config, logger) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const GcpPubSubPackage = yield (0, lazy_load_js_1.lazyLoad)({
+                packageName: "@google-cloud/pubsub",
+                context: "GcpPubSubConnection",
+            });
+            const client = new GcpPubSubPackage.PubSub(Object.assign({ projectId: config.projectId }, config.clientConfig));
+            return new GcpPubSubConnection(client, logger);
+        });
+    }
+    constructor(client, logger) {
+        this.client = client;
+        this.logger = logger;
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, "GCP Pub/Sub closing connection");
+            yield this.client.close();
+        });
+    }
+}
+exports.GcpPubSubConnection = GcpPubSubConnection;

package/dist/gcppubsub/main.d.ts

@@ -0,0 +1,5 @@
+export * from "./config.js";
+export * from "./connection.js";
+export * from "./publisher.js";
+export * from "./subscriber.js";
+export * from "./pubsub.js";

package/dist/gcppubsub/main.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config.js"), exports);
+__exportStar(require("./connection.js"), exports);
+__exportStar(require("./publisher.js"), exports);
+__exportStar(require("./subscriber.js"), exports);
+__exportStar(require("./pubsub.js"), exports);

package/dist/gcppubsub/publisher.d.ts

@@ -0,0 +1,14 @@
+import { Logger, PublisherProvider, PublishMessageOptions } from "../interfaces.js";
+import { GcpPubSubConnection } from "./connection.js";
+import { GcpPubSubConfiguration } from "./config.js";
+export declare class GcpPubSubPublisher implements PublisherProvider {
+    private readonly connection;
+    private readonly logger;
+    private readonly topics;
+    constructor(connection: GcpPubSubConnection, logger: Logger);
+    readonly transport: string;
+    init(config: GcpPubSubConfiguration): Promise<void>;
+    publish(config: GcpPubSubConfiguration, messages: string[], options?: PublishMessageOptions): Promise<void>;
+    enrichPublishedMesssageLog(config: GcpPubSubConfiguration): Record<string, unknown>;
+    close(): void;
+}

package/dist/gcppubsub/publisher.js

@@ -0,0 +1,66 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpPubSubPublisher = void 0;
+const errors_js_1 = require("../errors.js");
+const connection_js_1 = require("./connection.js");
+const config_js_1 = require("./config.js");
+class GcpPubSubPublisher {
+    constructor(connection, logger) {
+        this.connection = connection;
+        this.logger = logger;
+        this.topics = new Map();
+        this.transport = connection_js_1.GCP_PUBSUB_TRANSPORT;
+    }
+    init(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const topicName = (0, config_js_1.getTopicName)(config, "default");
+            yield (0, config_js_1.ensureTopic)(this.connection.client, topicName);
+            const topic = this.connection.client.topic(topicName);
+            this.topics.set(topicName, topic);
+            (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `GCP Pub/Sub publisher initialized for topic ${topicName}`);
+        });
+    }
+    publish(config, messages, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (options === null || options === void 0 ? void 0 : options.scheduledAt) {
+                throw new errors_js_1.PublishError("Scheduled publishing is not supported for GCP Pub/Sub", messages);
+            }
+            const topicName = (0, config_js_1.getTopicName)(config, "default");
+            let topic = this.topics.get(topicName);
+            if (!topic) {
+                topic = this.connection.client.topic(topicName);
+                this.topics.set(topicName, topic);
+            }
+            const oks = yield Promise.allSettled(messages.map((message) => topic.publishMessage({
+                data: Buffer.from(message, "utf8"),
+            })));
+            const failedMessages = oks
+                .map((ok, index) => ({ ok, index }))
+                .filter(({ ok }) => ok.status === "rejected")
+                .map(({ index }) => messages[index]);
+            if (failedMessages.length > 0) {
+                const allOrSome = failedMessages.length === messages.length ? "all" : "some";
+                throw new errors_js_1.PublishError(`GCP Pub/Sub publish to topic ${topicName} failed for ${allOrSome} messages`, failedMessages);
+            }
+        });
+    }
+    enrichPublishedMesssageLog(config) {
+        return {
+            topicName: (0, config_js_1.getTopicName)(config, "default"),
+        };
+    }
+    close() {
+        this.topics.clear();
+    }
+}
+exports.GcpPubSubPublisher = GcpPubSubPublisher;

package/dist/gcppubsub/pubsub.d.ts

@@ -0,0 +1,18 @@
+import { Logger, MessageContext, MessageResult, PublishMessageOptions, PubSubProvider, StopSubscribe } from "../interfaces.js";
+import { GcpPubSubConfiguration } from "./config.js";
+import { GcpPubSubConnection } from "./connection.js";
+/**
+ * Combines a GcpPubSubPublisher and GcpPubSubSubscriber into a single instance
+ */
+export declare class GcpPubSubProvider implements PubSubProvider {
+    private readonly publisher;
+    private readonly subscriber;
+    constructor(connection: GcpPubSubConnection, logger: Logger);
+    readonly transport: string;
+    publish(config: GcpPubSubConfiguration, messages: string[], options?: PublishMessageOptions): Promise<void>;
+    startSubscribe(config: GcpPubSubConfiguration, onMessage: (s: string, context: MessageContext) => Promise<MessageResult> | MessageResult): Promise<StopSubscribe>;
+    close(): Promise<void>;
+    init(config: GcpPubSubConfiguration): Promise<void>;
+    enrichPublishedMesssageLog(config: GcpPubSubConfiguration): Record<string, unknown>;
+    enrichHandledMesssageLog(config: GcpPubSubConfiguration): Record<string, unknown>;
+}

package/dist/gcppubsub/pubsub.js

@@ -0,0 +1,49 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpPubSubProvider = void 0;
+const connection_js_1 = require("./connection.js");
+const publisher_js_1 = require("./publisher.js");
+const subscriber_js_1 = require("./subscriber.js");
+/**
+ * Combines a GcpPubSubPublisher and GcpPubSubSubscriber into a single instance
+ */
+class GcpPubSubProvider {
+    constructor(connection, logger) {
+        this.transport = connection_js_1.GCP_PUBSUB_TRANSPORT;
+        this.publisher = new publisher_js_1.GcpPubSubPublisher(connection, logger);
+        this.subscriber = new subscriber_js_1.GcpPubSubSubscriber(connection, logger);
+    }
+    publish(config, messages, options) {
+        return this.publisher.publish(config, messages, options);
+    }
+    startSubscribe(config, onMessage) {
+        return this.subscriber.startSubscribe(config, onMessage);
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.subscriber.close();
+            this.publisher.close();
+        });
+    }
+    init(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.publisher.init(config);
+        });
+    }
+    enrichPublishedMesssageLog(config) {
+        return this.publisher.enrichPublishedMesssageLog(config);
+    }
+    enrichHandledMesssageLog(config) {
+        return this.subscriber.enrichHandledMesssageLog(config);
+    }
+}
+exports.GcpPubSubProvider = GcpPubSubProvider;

package/dist/gcppubsub/subscriber.d.ts

@@ -0,0 +1,19 @@
+import { Logger, MessageResult, StopSubscribe, SubscriberProvider } from "../interfaces.js";
+import { GcpPubSubConfiguration, GcpPubSubMessageContext } from "./config.js";
+import { GcpPubSubConnection } from "./connection.js";
+export declare class GcpPubSubSubscriber implements SubscriberProvider {
+    private readonly connection;
+    private readonly logger;
+    private readonly subscriptions;
+    private lastMessageDate;
+    constructor(connection: GcpPubSubConnection, logger: Logger);
+    readonly transport: string;
+    startSubscribe(config: GcpPubSubConfiguration, onMessage: (s: string, context: GcpPubSubMessageContext) => Promise<MessageResult> | MessageResult): Promise<StopSubscribe>;
+    close(): Promise<void>;
+    enrichHandledMesssageLog(config: GcpPubSubConfiguration): Record<string, unknown>;
+    private consumeMessage;
+    /**
+     * Wait for in-flight message handling to complete before shutting down
+     */
+    private waitForMessagesToComplete;
+}

package/dist/gcppubsub/subscriber.js

@@ -0,0 +1,193 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpPubSubSubscriber = void 0;
+const trace_1 = require("@palmetto/trace");
+const interfaces_js_1 = require("../interfaces.js");
+const errors_js_1 = require("../errors.js");
+const create_log_error_payload_js_1 = require("../create-log-error-payload.js");
+const config_js_1 = require("./config.js");
+const connection_js_1 = require("./connection.js");
+const RETRY_COUNT_ATTR = "x-retry-count";
+const FIRST_PUBLISHED_ATTR = "x-first-published";
+const SHUTDOWN_DELAY = 1000;
+class GcpPubSubSubscriber {
+    constructor(connection, logger) {
+        this.connection = connection;
+        this.logger = logger;
+        this.subscriptions = new Map();
+        this.lastMessageDate = 0;
+        this.transport = connection_js_1.GCP_PUBSUB_TRANSPORT;
+    }
+    startSubscribe(config, onMessage) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const subscriptionName = (0, config_js_1.getSubscriptionName)(config);
+            if (this.subscriptions.has(subscriptionName)) {
+                throw new errors_js_1.AlreadySubscribingError(subscriptionName);
+            }
+            const topicName = (0, config_js_1.getTopicName)(config, "default");
+            const dlqTopicName = (0, config_js_1.getTopicName)(config, "dead-letter");
+            const retryDelay = (_a = config.retryDelay) !== null && _a !== void 0 ? _a : 30000;
+            yield (0, config_js_1.ensureSubscription)(this.connection.client, topicName, subscriptionName, retryDelay);
+            yield (0, config_js_1.ensureTopic)(this.connection.client, dlqTopicName);
+            const subscription = this.connection.client.subscription(subscriptionName, {
+                flowControl: {
+                    maxMessages: (_b = config.maxMessages) !== null && _b !== void 0 ? _b : 5,
+                },
+            });
+            const dlTopic = this.connection.client.topic(dlqTopicName);
+            const messageHandler = (message) => {
+                void this.consumeMessage({
+                    config,
+                    message,
+                    onMessage,
+                    subscriptionName,
+                    topicName,
+                    dlTopic,
+                    retryDelay,
+                });
+            };
+            const errorHandler = (err) => {
+                const log = {
+                    message: `GCP Pub/Sub subscriber error for ${subscriptionName}`,
+                    error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
+                };
+                this.logger.error(log);
+            };
+            subscription.on("message", messageHandler);
+            subscription.on("error", errorHandler);
+            this.subscriptions.set(subscriptionName, subscription);
+            this.logger.log(`GCP Pub/Sub consumer started for ${subscriptionName}`);
+            return () => __awaiter(this, void 0, void 0, function* () {
+                subscription.removeListener("message", messageHandler);
+                subscription.removeListener("error", errorHandler);
+                yield this.waitForMessagesToComplete();
+                yield subscription.close();
+                this.subscriptions.delete(subscriptionName);
+                this.logger.log(`GCP Pub/Sub consumer stopped for ${subscriptionName}`);
+            });
+        });
+    }
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all([...this.subscriptions.entries()].map((_a) => __awaiter(this, [_a], void 0, function* ([subscriptionName, sub]) {
+                yield this.waitForMessagesToComplete();
+                yield sub.close();
+                this.logger.log(`GCP Pub/Sub consumer stopped for ${subscriptionName}`);
+            })));
+            this.subscriptions.clear();
+        });
+    }
+    enrichHandledMesssageLog(config) {
+        return {
+            subscriptionName: (0, config_js_1.getSubscriptionName)(config),
+            topicName: (0, config_js_1.getTopicName)(config, "default"),
+        };
+    }
+    consumeMessage(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ config, message, onMessage, subscriptionName, topicName, dlTopic, }) {
+            yield (0, trace_1.getTracer)().trace("pubsub.gcppubsub.consume", {
+                resource: `consume ${config.transport} ${subscriptionName}`,
+            }, (span) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c, _d, _e, _f, _g;
+                try {
+                    const firstPublished = message.publishTime;
+                    let retryCount = message.deliveryAttempt - 1;
+                    let willRetryOnFailure;
+                    if (retryCount < 0) {
+                        retryCount = 0;
+                        willRetryOnFailure = false;
+                    }
+                    else {
+                        willRetryOnFailure = retryCount < ((_a = config.retries) !== null && _a !== void 0 ? _a : 0);
+                    }
+                    const context = {
+                        attemptsMade: retryCount,
+                        firstSent: firstPublished,
+                        lastSent: undefined,
+                        willRetryOnFailure,
+                        messageId: message.id,
+                        subscriptionName,
+                        topicName,
+                        orderingKey: message.orderingKey,
+                    };
+                    let messageResult;
+                    let logPayload;
+                    try {
+                        messageResult = yield onMessage(message.data.toString("utf8"), context);
+                        logPayload = {
+                            message: `GCP Pub/Sub consumer handled message.`,
+                            extra: Object.assign({}, context),
+                        };
+                    }
+                    catch (err) {
+                        messageResult = interfaces_js_1.MessageResult.Retry;
+                        logPayload = {
+                            message: `GCP Pub/Sub consumer unhandled exception.`,
+                            error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
+                            extra: Object.assign({}, context),
+                        };
+                    }
+                    this.lastMessageDate = Date.now();
+                    if (messageResult === interfaces_js_1.MessageResult.Ok) {
+                        (_c = (_b = this.logger).debug) === null || _c === void 0 ? void 0 : _c.call(_b, logPayload);
+                        message.ack();
+                        return;
+                    }
+                    if (messageResult === interfaces_js_1.MessageResult.Retry && willRetryOnFailure) {
+                        message.nack();
+                        logPayload.message += " Retrying message via Pubsub.";
+                        (_e = (_d = this.logger).debug) === null || _e === void 0 ? void 0 : _e.call(_d, logPayload);
+                        return;
+                    }
+                    // Fail: either explicit Fail or Retry with no retries remaining
+                    if (messageResult === interfaces_js_1.MessageResult.Retry) {
+                        logPayload.message += " No more retries.";
+                    }
+                    yield dlTopic.publishMessage({
+                        data: message.data,
+                        attributes: Object.assign(Object.assign({}, message.attributes), { [RETRY_COUNT_ATTR]: retryCount.toString(), [FIRST_PUBLISHED_ATTR]: firstPublished.toISOString() }),
+                    });
+                    logPayload.message += ` Published to dead-letter topic ${dlTopic.name}.`;
+                    (_g = (_f = this.logger).debug) === null || _g === void 0 ? void 0 : _g.call(_f, logPayload);
+                    message.ack();
+                }
+                catch (err) {
+                    const logPayload = {
+                        message: "Unexpected error handling GCP Pub/Sub message",
+                        error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
+                        extra: {
+                            subscriptionName,
+                            message: message.data.toString("utf8"),
+                        },
+                    };
+                    this.logger.error(logPayload);
+                    span === null || span === void 0 ? void 0 : span.setTag("error", err);
+                    message.nack();
+                }
+            }));
+        });
+    }
+    /**
+     * Wait for in-flight message handling to complete before shutting down
+     */
+    waitForMessagesToComplete() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const waitUntil = this.lastMessageDate + SHUTDOWN_DELAY;
+            const waitDuration = waitUntil - Date.now();
+            if (waitDuration > 0) {
+                yield new Promise((resolve) => setTimeout(resolve, waitDuration));
+            }
+        });
+    }
+}
+exports.GcpPubSubSubscriber = GcpPubSubSubscriber;

package/dist/interfaces.d.ts

@@ -52,7 +52,7 @@ export interface PubSubConfiguration {
      */
     transport: string;
     /**
-     * Maximum number of times to retry a message
+     * Maximum number of times to retry a message (default: 0, no retries)
      */
     retries?: number;
     /**
@@ -129,7 +129,8 @@ export type PubSubProvider = PublisherProvider & SubscriberProvider;
  */
 export type PubOrSubProvider = PubSubProvider | PublisherProvider | SubscriberProvider;
 export interface MessageContext {
-    firstSent?: Date;
-    lastSent?: Date;
-    retries?: number;
+    firstSent: Date | undefined;
+    lastSent: Date | undefined;
+    attemptsMade: number | undefined;
+    willRetryOnFailure: boolean;
 }

package/dist/main.d.ts

@@ -4,3 +4,4 @@ export * from "./publisher.js";
 export * from "./subscriber.js";
 export * from "./bullmq/main.js";
 export * from "./rabbitmq/main.js";
+export * from "./gcppubsub/main.js";

package/dist/main.js

@@ -20,3 +20,4 @@ __exportStar(require("./publisher.js"), exports);
 __exportStar(require("./subscriber.js"), exports);
 __exportStar(require("./bullmq/main.js"), exports);
 __exportStar(require("./rabbitmq/main.js"), exports);
+__exportStar(require("./gcppubsub/main.js"), exports);

package/dist/rabbitmq/config.d.ts

@@ -84,8 +84,10 @@ export interface RabbitQueueExchangeCustomConfiguration {
     retryQueueExchangeName?: string;
 }
 export interface RabbitMqMessageContext extends MessageContext {
-    exchangeName?: string;
-    routingKey?: string;
+    queueName: string;
+    exchangeName: string;
+    routingKey: string;
+    retryExchangeName: string;
 }
 /**
  * Returns the queue name based on the configuration

package/dist/rabbitmq/subscriber.d.ts

@@ -25,7 +25,7 @@ export declare class RabbitMqSubscriber implements SubscriberProvider {
     startSubscribe(config: RabbitQueueExchangeConfiguration, onMessage: (s: string, context: RabbitMqMessageContext) => Promise<MessageResult> | MessageResult): StopSubscribe;
     close(): Promise<void>;
     enrichHandledMesssageLog(config: RabbitQueueExchangeConfiguration): Record<string, unknown>;
-    static getRetries(msg: ConsumeMessage): number;
+    static getAttemptsMade(msg: ConsumeMessage): number;
     static getSentDates(msg: ConsumeMessage): {
         firstSent: Date | undefined;
         lastSent: Date | undefined;

package/dist/rabbitmq/subscriber.js

@@ -52,7 +52,7 @@ class SubscribedMessage {
     }
 }
 const RETRIES_HEADER = "x-retries";
-const RETRYSENT_HEADER = "x-retry-sent";
+const RETRY_SENT_HEADER = "x-retry-sent";
 class RabbitMqSubscriber {
     constructor(connection, logger) {
         this.connection = connection;
@@ -94,9 +94,10 @@ class RabbitMqSubscriber {
     enrichHandledMesssageLog(config) {
         return {
             queueName: (0, config_js_1.getQueueName)(config),
+            exchangeName: (0, config_js_1.getExchangeName)(config),
         };
     }
-    static getRetries(msg) {
+    static getAttemptsMade(msg) {
         var _a;
         return typeof ((_a = msg.properties.headers) === null || _a === void 0 ? void 0 : _a[RETRIES_HEADER]) === "number"
             ? msg.properties.headers[RETRIES_HEADER]
@@ -109,8 +110,8 @@ class RabbitMqSubscriber {
         const firstSent = typeof msg.properties.timestamp === "number"
             ? new Date(msg.properties.timestamp)
             : undefined;
-        const lastSent = typeof ((_a = msg.properties.headers) === null || _a === void 0 ? void 0 : _a[RETRYSENT_HEADER]) === "number"
-            ? new Date(msg.properties.headers[RETRYSENT_HEADER])
+        const lastSent = typeof ((_a = msg.properties.headers) === null || _a === void 0 ? void 0 : _a[RETRY_SENT_HEADER]) === "number"
+            ? new Date(msg.properties.headers[RETRY_SENT_HEADER])
             : firstSent;
         return { firstSent, lastSent };
     }
@@ -129,22 +130,39 @@ class RabbitMqSubscriber {
                 }, (span) => __awaiter(this, void 0, void 0, function* () {
                     try {
                         subscribedMessage.busy++;
-                        yield this.consumeMessage(msg, channel, subscribedMessage, setupResult.retryExchangeName, retryDelay);
+                        yield this.consumeMessage({
+                            msg,
+                            channel,
+                            subscribedMessage,
+                            retryExchangeName: setupResult.retryExchangeName,
+                            retryDelay,
+                            queueName,
+                        });
                     }
                     catch (err) {
-                        this.logger.error({
+                        const logPayload = {
                             message: "Unexpected error handling RabbitMq message",
                             error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
-                        });
+                            extra: {
+                                queueName,
+                                message: msg.content.toString("utf8"),
+                            },
+                        };
+                        this.logger.error(logPayload);
                         span === null || span === void 0 ? void 0 : span.setTag("error", err);
                         try {
                             channel.nack(msg, undefined, true);
                         }
                         catch (err2) {
-                            this.logger.error({
+                            const logPayload2 = {
                                 message: "Unexpected error handling RabbitMq message during NACK attempt",
                                 error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err2),
-                            });
+                                extra: {
+                                    queueName,
+                                    message: msg.content.toString("utf8"),
+                                },
+                            };
+                            this.logger.error(logPayload2);
                         }
                     }
                     finally {
@@ -171,53 +189,68 @@ class RabbitMqSubscriber {
             });
         });
     }
-    consumeMessage(msg, channel, subscribedMessage, retryExchangeName, retryDelay) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h;
+    consumeMessage(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ msg, channel, subscribedMessage, retryExchangeName, retryDelay, queueName, }) {
+            var _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
             const json = msg.content.toString("utf8");
-            const retries = RabbitMqSubscriber.getRetries(msg);
+            const attemptsMade = RabbitMqSubscriber.getAttemptsMade(msg);
             const sentDates = RabbitMqSubscriber.getSentDates(msg);
-            const context = Object.assign(Object.assign({ retries }, sentDates), { exchangeName: msg.fields.exchange, routingKey: msg.fields.routingKey });
+            const willRetryOnFailure = attemptsMade < ((_b = subscribedMessage.config.retries) !== null && _b !== void 0 ? _b : 0);
+            const context = Object.assign(Object.assign({ attemptsMade }, sentDates), { queueName, exchangeName: msg.fields.exchange, retryExchangeName, routingKey: msg.fields.routingKey, willRetryOnFailure });
             let messageResult;
+            let logPayload;
             try {
                 messageResult = yield subscribedMessage.onMessage(json, context);
+                logPayload = {
+                    message: `RabbitMq consumer handled message.`,
+                    extra: Object.assign({}, context),
+                };
             }
             catch (err) {
                 messageResult = interfaces_js_1.MessageResult.Retry;
-                this.logger.error({
-                    message: `RabbitMq consumer unhandled exception, retrying message to ${retryExchangeName} ${msg.fields.routingKey}`,
+                logPayload = {
+                    message: `RabbitMq consumer unhandled exception.`,
                     error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err),
-                });
+                    extra: Object.assign({}, context),
+                };
             }
             if (messageResult === interfaces_js_1.MessageResult.Ok) {
+                (_d = (_c = this.logger).debug) === null || _d === void 0 ? void 0 : _d.call(_c, logPayload);
                 channel.ack(msg);
                 return;
             }
-            if (messageResult === interfaces_js_1.MessageResult.Retry &&
-                subscribedMessage.config.retries &&
-                retries >= subscribedMessage.config.retries) {
-                messageResult = interfaces_js_1.MessageResult.Fail;
+            if (messageResult === interfaces_js_1.MessageResult.Retry) {
+                if (willRetryOnFailure) {
+                    logPayload.message += " Retrying message.";
+                }
+                else {
+                    messageResult = interfaces_js_1.MessageResult.Fail;
+                    logPayload.message += " No more retries.";
+                }
             }
             if (messageResult === interfaces_js_1.MessageResult.Fail) {
-                (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, `RabbitMq retry count exceeded - sending message to DLQ`);
+                (_f = (_e = this.logger).debug) === null || _f === void 0 ? void 0 : _f.call(_e, logPayload);
                 channel.nack(msg, undefined, false);
                 return;
             }
-            const ok = yield ((_c = subscribedMessage.channel) === null || _c === void 0 ? void 0 : _c.publish(retryExchangeName, msg.fields.routingKey, msg.content, {
+            const ok = yield ((_g = subscribedMessage.channel) === null || _g === void 0 ? void 0 : _g.publish(retryExchangeName, msg.fields.routingKey, msg.content, {
                 contentType: msg.properties.contentType,
                 expiration: retryDelay,
-                timestamp: (_d = sentDates.firstSent) === null || _d === void 0 ? void 0 : _d.valueOf(),
+                timestamp: (_h = sentDates.firstSent) === null || _h === void 0 ? void 0 : _h.valueOf(),
                 headers: {
-                    [RETRIES_HEADER]: retries + 1,
-                    [RETRYSENT_HEADER]: Date.now(),
+                    [RETRIES_HEADER]: attemptsMade + 1,
+                    [RETRY_SENT_HEADER]: Date.now(),
                 },
             }));
             if (ok) {
-                (_f = (_e = this.logger).debug) === null || _f === void 0 ? void 0 : _f.call(_e, `RabbitMq retry queue success`);
+                (_k = (_j = this.logger).debug) === null || _k === void 0 ? void 0 : _k.call(_j, `RabbitMq retry queue success`);
+                (_m = (_l = this.logger).debug) === null || _m === void 0 ? void 0 : _m.call(_l, logPayload);
                 channel.ack(msg);
             }
             else {
-                (_h = (_g = this.logger).debug) === null || _h === void 0 ? void 0 : _h.call(_g, `RabbitMq retry queue failure - nack-ing message instead`);
+                (_p = (_o = this.logger).debug) === null || _p === void 0 ? void 0 : _p.call(_o, `RabbitMq retry queue failure - nack-ing message instead`);
+                logPayload.message += " Retry publish failed.";
+                this.logger.error(logPayload);
                 channel.nack(msg, undefined, true);
             }
         });

package/dist/subscriber.js

@@ -55,18 +55,20 @@ class Subscriber {
             if (!provider) {
                 throw new errors_js_1.MissingPubSubProviderError(`No provider configured for ${config.transport}`);
             }
-            const transform = (jsonStr, context) => __awaiter(this, void 0, void 0, function* () {
+            const enrichedConfig = provider.enrichHandledMesssageLog(config);
+            const handleMessage = (jsonStr, context) => __awaiter(this, void 0, void 0, function* () {
                 const start = (0, message_logger_js_1.startTiming)();
                 const jsonObject = JSON.parse(jsonStr);
-                const r = schema.safeDecode(jsonObject);
-                if (!r.success) {
+                const decodeResult = schema.safeDecode(jsonObject);
+                if (!decodeResult.success) {
                     const durationMs = (0, message_logger_js_1.getDuration)(start);
                     (0, message_logger_js_1.logMessage)({
                         note: "Subscribed message failed schema validation",
                         message: jsonObject,
                         level: "error",
                         logger: this.logger,
-                        extra: Object.assign({ transport: provider.transport, name: config.name, durationMs }, provider.enrichHandledMesssageLog(config)),
+                        extra: Object.assign({ transport: provider.transport, name: config.name, durationMs,
+                            context }, enrichedConfig),
                     });
                     const handledEventContext = {
                         message: jsonStr,
@@ -80,7 +82,7 @@ class Subscriber {
                     return interfaces_js_1.MessageResult.Fail;
                 }
                 try {
-                    const result = yield onMessage(r.data, context);
+                    const result = yield onMessage(decodeResult.data, context);
                     const durationMs = (0, message_logger_js_1.getDuration)(start);
                     const eventContext = {
                         message: jsonStr,
@@ -91,11 +93,12 @@ class Subscriber {
                     };
                     (0, message_logger_js_1.logMessage)({
                         note: "Subscriber processed message",
-                        message: r.data,
+                        message: decodeResult.data,
                         level: config.messageLogLevel,
                         logger: this.logger,
                         extra: Object.assign({ transport: provider.transport, name: config.name, durationMs,
-                            result }, provider.enrichHandledMesssageLog(config)),
+                            result,
+                            context }, enrichedConfig),
                     });
                     this.events.emit("messageHandled", eventContext);
                     return result;
@@ -104,24 +107,31 @@ class Subscriber {
                     const durationMs = (0, message_logger_js_1.getDuration)(start);
                     (0, message_logger_js_1.logMessage)({
                         note: "Subscriber error when processing message",
-                        message: r.data,
-                        level: "error",
+                        message: decodeResult.data,
+                        level: context.willRetryOnFailure ? "warn" : "error",
                         logger: this.logger,
-                        extra: Object.assign(Object.assign({ transport: provider.transport, name: config.name, durationMs }, provider.enrichHandledMesssageLog(config)), { error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err) }),
+                        extra: Object.assign(Object.assign({ transport: provider.transport, name: config.name, durationMs,
+                            context }, enrichedConfig), { error: (0, create_log_error_payload_js_1.createLogErrorPayload)(err) }),
                     });
+                    // in the messageHandled event, we always log as retry or fail based on willRetryOnFailure
+                    const result = context.willRetryOnFailure
+                        ? interfaces_js_1.MessageResult.Retry
+                        : interfaces_js_1.MessageResult.Fail;
                     const eventContext = {
                         message: jsonStr,
+                        result,
                         context,
                         config,
                         durationMs,
                         err,
                     };
                     this.events.emit("messageHandled", eventContext);
-                    throw err;
+                    // but, always return Retry on exception to allow for retry logic to work in the providers
+                    return interfaces_js_1.MessageResult.Retry;
                 }
             });
             this.logger.log(`Starting subscriber for ${config.transport}:${config.name}`);
-            subscribedMessage = new SubscribedMessage(yield provider.startSubscribe(config, transform));
+            subscribedMessage = new SubscribedMessage(yield provider.startSubscribe(config, handleMessage));
             this.subscribedMessages.set(config, subscribedMessage);
             this.logger.log(`Started subscriber for ${config.transport}:${config.name}`);
             return () => __awaiter(this, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@palmetto/pubsub",
-  "version": "3.0.2",
+  "version": "3.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palmetto/galaxy"
+  },
   "main": "./dist/main.js",
   "scripts": {
     "lint": "yarn run -T eslint --fix ./src",
@@ -20,6 +24,7 @@
     "test:watch": "yarn run test-runner vitest watch"
   },
   "devDependencies": {
+    "@google-cloud/pubsub": "^5.2.3",
     "@palmetto/trace": "^0.1.0",
     "@types/amqplib": "^0",
     "@types/node": "^24.2.1",
@@ -45,10 +50,11 @@
     "uuid": "^11.1.0"
   },
   "peerDependencies": {
+    "@google-cloud/pubsub": "^5.2",
     "@palmetto/trace": "^0.1.0",
     "amqp-connection-manager": "^4.1.14",
     "amqplib": "^0.10.8",
     "bullmq": "^5.58.0",
-    "zod": "^4.1.13"
+    "zod": "^4.1"
   }
 }

package/src/gcppubsub/README.md

@@ -0,0 +1,134 @@
+# @palmetto/pubsub
+
+The GoogleCloud pubsub transport provider for @palmetto/pubsub
+
+## Installation
+
+```sh
+yarn add @palmetto/pubsub @google-cloud/pubsub zod
+```
+
+## Usage
+
+1. Define your connection string
+
+   ```ts
+   import { GcpPubSubConnectionConfig } from "@palmetto/pubsub";
+
+   const config: GcpPubSubConnectionConfig = {
+     projectId: "GOOGLE_PROJECT_ID",
+   };
+   ```
+
+2. Create the connection
+
+   ```ts
+   import { GcpPubSubConnection } from "@palmetto/pubsub";
+
+   const connection = await GcpPubSubConnection.create(config, console);
+   ```
+
+3. Create the publisher
+
+   ```ts
+   import { Publisher, GcpPubSubPublisher } from "@palmetto/pubsub";
+
+   const publisher = new Publisher(console, [
+     new GcpPubSubPublisher(connection, console),
+   ]);
+   ```
+
+4. Create the subscriber
+
+   ```ts
+   import { Subscriber, GcpPubSubSubscriber } from "@palmetto/pubsub";
+
+   const subscriber = new Subscriber(console, [
+     new GcpPubSubSubscriber(connection, console),
+   ]);
+   ```
+
+5. Create the queue configuration
+
+   ```ts
+   import {
+     GcpPubSubConfiguration,
+     GCP_PUBSUB_TRANSPORT,
+   } from "@palmetto/pubsub";
+
+   import { z } from "zod";
+
+   const MyModelSchema = z.object({...});
+
+   const config: GcpPubSubConfiguration = {
+     name: "my-name",
+     topicName: "my-topic-name", // default: name
+     subscriptionName: "my-subscription-name", // default: topicName or name
+     schema: MyModelSchema,
+     transport: GCP_PUBSUB_TRANSPORT,
+     retries: 10,
+     retryDelay: 1_000, // Note: retryDelay must be configured as a retry policy of the subscription. pubsub will create the subscription if it does not exist, but won't update an existing subscription.
+   };
+   ```
+
+6. Initialize the publisher
+
+   For performance reasons, it's a good idea to initialize the publisher on your API startup. This can reduce the latency for the first message published.
+
+   ```ts
+   await publisher.init(config);
+   ```
+
+7. Publish a message
+
+   ```ts
+   const message: MyModel = {... };
+
+   await publisher.publish(config, message);
+   ```
+
+8. Subscribe to a queue
+
+   ```ts
+   import { GcpPubSubMessageContext } from "@palmetto/pubsub";
+
+   subscriber.addSubscriber(queue, (message: MyModel, context: GcpPubSubMessageContext) => {
+       ...
+       return MessageResult.Ok;
+   });
+   ```
+
+9. Subscribe to the dead-letter topic if you want to re-process completely failed messages. Pass the dead-letter topicName to the config.
+
+   ```ts
+   import { getTopicName } from "@palmetto/pubsub";
+
+   const dlConfig = {
+     ...config,
+     topicName: getTopicName(config, "dead-letter")
+   };
+
+   subscriber.addSubscriber(dlConfig, (message: MyModel, context: GcpPubSubMessageContext) => {
+      ...
+      return MessageResult.Ok; // returning Ok will remove the message from the dead-letter topic
+   });
+   ```
+
+## Message failures
+
+Message failures in Google Cloud pubsub subscribers are handled by pubsub's retry policies. Messages are `nack()`'ed and retried (or discarded) based on the GCP subscription's retry policy.
+
+### Retrying messages
+
+These properties configure message retries when `@palmetto/pubsub` creates the subscription. If `@palmetto/pubsub` didn't create the subscription, whatever retry policy in place is what will be used (by default there are no retries).
+
+- `retries` : specifies the number of retries after which the message is sent to the dead-letter topic. When this value is undefined, the message will not retry.
+- `retryDelay`: specifies the number of milliseconds between retries.
+
+Failed messages are `nack()`'ed to pubsub and they are retried with the delay configured for the subscription.
+Once the `retries` are exhausted, the message is `ack()`'ed and re-published to the dead-letter topic.
+The dead-letter topic is the same as the subscription topic, but ends in `.dl`.
+
+### Failing messages
+
+A dead-letter topic is created using the topic name and ends with `.dl`. Messages that fail after the configured `retries` are re-published to the dead-letter topic.

package/src/rabbitmq/README.md

@@ -13,6 +13,8 @@ yarn add @palmetto/pubsub amqp-connection-manager amqplib zod
 1. Define your connection string
 
    ```ts
+   import { RabbitMqConnectionConfig } from "@palmetto/pubsub";
+
    const config: RabbitMqConnectionConfig = {
      host: "amqp://guest:guest@localhost:5672/",
    };
@@ -21,20 +23,26 @@ yarn add @palmetto/pubsub amqp-connection-manager amqplib zod
 2. Create the connection
 
    ```ts
-   const connection = new RabbitMqConnection(config, console);
+   import { RabbitMqConnection } from "@palmetto/pubsub";
+
+   const connection = await RabbitMqConnection.create(config, console);
    ```
 
 3. Create the publisher
 
    ```ts
+   import { Publisher, RabbitMqPublisher } from "@palmetto/pubsub";
+
    const publisher = new Publisher(console, [
-     RabbitMqPublisher(connection, console),
+     new RabbitMqPublisher(connection, console),
    ]);
    ```
 
 4. Create the subscriber
 
    ```ts
+   import { Subscriber, RabbitMqSubscriber } from "@palmetto/pubsub";
+
    const subscriber = new Subscriber(console, [
      new RabbitMqSubscriber(connection, console),
    ]);
@@ -43,6 +51,11 @@ yarn add @palmetto/pubsub amqp-connection-manager amqplib zod
 5. Create the queue configuration
 
    ```ts
+   import { RabbitQueueExchangeConfiguration } from "@palmetto/pubsub";
+   import { z } from "zod";
+
+   const MyModelSchema = z.object({...});
+
    const queue: RabbitQueueExchangeConfiguration = {
      name: "my-queue-name",
      schema: MyModelSchema,
@@ -101,7 +114,7 @@ Message failures in RabbitMq subscribers are handled using special queues and ex
 
 These properties configure message retries:
 
-- `retries` : specifies the number of retries after which the message is discarded. When this value is undefined, the message will retry forever.
+- `retries` : specifies the number of retries after which the message is discarded. When this value is undefined, the message will not retry.
 - `retryDelay`: specifies the number of milliseconds between retries.
 
 #### The retry queue