@palmetto/pubsub 3.1.0 → 3.2.0

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palmetto/pubsub",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/palmetto/galaxy"
@@ -24,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",
@@ -49,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