@hotmeshio/hotmesh 0.6.1 → 0.7.0

package/build/services/stream/providers/postgres/postgres.js

@@ -1,139 +1,171 @@
 "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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresStreamService = void 0;
 const key_1 = require("../../../../modules/key");
-const utils_1 = require("../../../../modules/utils");
 const index_1 = require("../../index");
 const kvtables_1 = require("./kvtables");
+const Stats = __importStar(require("./stats"));
+const Messages = __importStar(require("./messages"));
+const scout_1 = require("./scout");
+const notifications_1 = require("./notifications");
+const Lifecycle = __importStar(require("./lifecycle"));
+/**
+ * PostgreSQL Stream Service
+ *
+ * High-performance stream message provider using PostgreSQL with LISTEN/NOTIFY.
+ *
+ * ## Module Organization
+ *
+ * This service is organized into focused modules following KISS principles:
+ * - `postgres.ts` (this file) - Main orchestrator and service interface
+ * - `kvtables.ts` - Schema deployment and table management
+ * - `messages.ts` - Message CRUD operations (publish, fetch, ack, delete)
+ * - `stats.ts` - Statistics and query operations
+ * - `scout.ts` - Scout role coordination for polling visible messages
+ * - `notifications.ts` - LISTEN/NOTIFY notification system with static state management
+ * - `lifecycle.ts` - Stream and consumer group lifecycle operations
+ *
+ * ## Lifecycle
+ *
+ * ### Initialization (`init`)
+ * 1. Deploy PostgreSQL schema (tables, indexes, triggers, functions)
+ * 2. Create ScoutManager for coordinating visibility timeout polling
+ * 3. Create NotificationManager for LISTEN/NOTIFY event handling
+ * 4. Set up notification handler (once per client, shared across instances)
+ * 5. Start fallback poller (backup for missed notifications)
+ * 6. Start router scout poller (for visibility timeout processing)
+ *
+ * ### Shutdown (`cleanup`)
+ * 1. Stop router scout polling loop
+ * 2. Release scout role if held
+ * 3. Stop notification consumers for this instance
+ * 4. UNLISTEN from channels when last instance disconnects
+ * 5. Clean up fallback poller when last instance disconnects
+ * 6. Remove notification handlers when last instance disconnects
+ *
+ * ## Notification System (LISTEN/NOTIFY)
+ *
+ * ### Real-time Message Delivery
+ * - PostgreSQL trigger on INSERT sends NOTIFY when messages are immediately visible
+ * - Messages with visibility timeout are NOT notified on INSERT
+ * - Multiple service instances share the same client and notification handlers
+ * - Static state ensures only ONE LISTEN per channel across all instances
+ *
+ * ### Components
+ * - **Notification Handler**: Listens for PostgreSQL NOTIFY events
+ * - **Fallback Poller**: Polls every 30s (default) for missed messages
+ * - **Router Scout**: Active role-holder polls visible messages frequently (~100ms)
+ * - **Visibility Function**: `notify_visible_messages()` checks for expired timeouts
+ *
+ * ## Scout Role (Visibility Timeout Processing)
+ *
+ * When messages are published with visibility timeouts (delays), they need to be
+ * processed when they become visible. The scout role ensures this happens efficiently:
+ *
+ * 1. **Role Acquisition**: One instance per app acquires "router" scout role
+ * 2. **Fast Polling**: Scout polls `notify_visible_messages()` every ~100ms
+ * 3. **Notification**: Function triggers NOTIFY for streams with visible messages
+ * 4. **Role Rotation**: Role expires after interval, another instance can claim it
+ * 5. **Fallback**: Non-scouts sleep longer, try to acquire role periodically
+ *
+ * ## Message Flow
+ *
+ * ### Publishing
+ * 1. Messages inserted into partitioned table
+ * 2. If immediately visible → INSERT trigger sends NOTIFY
+ * 3. If visibility timeout → no NOTIFY (scout will handle when visible)
+ *
+ * ### Consuming (Event-Driven)
+ * 1. Consumer calls `consumeMessages` with notification callback
+ * 2. Service executes LISTEN on channel `stream_{name}_{group}`
+ * 3. On NOTIFY → fetch messages → invoke callback
+ * 4. Initial fetch done immediately (catch any queued messages)
+ *
+ * ### Consuming (Polling)
+ * 1. Consumer calls `consumeMessages` without callback
+ * 2. Service directly queries and reserves messages
+ * 3. Returns messages synchronously
+ *
+ * ## Reliability Guarantees
+ *
+ * - **Notification Fallback**: Poller catches missed notifications every 30s
+ * - **Visibility Scout**: Ensures delayed messages are processed when visible
+ * - **Graceful Degradation**: Falls back to polling if LISTEN fails
+ * - **Shared State**: Multiple instances coordinate via static maps
+ * - **Race Condition Safe**: SKIP LOCKED prevents message duplication
+ *
+ * @example
+ * ```typescript
+ * // Initialize service
+ * const service = new PostgresStreamService(client, storeClient, config);
+ * await service.init('namespace', 'appId', logger);
+ *
+ * // Event-driven consumption (recommended)
+ * await service.consumeMessages('stream', 'group', 'consumer', {
+ *   notificationCallback: (messages) => {
+ *     // Process messages in real-time
+ *   }
+ * });
+ *
+ * // Polling consumption
+ * const messages = await service.consumeMessages('stream', 'group', 'consumer', {
+ *   batchSize: 10
+ * });
+ *
+ * // Cleanup on shutdown
+ * await service.cleanup();
+ * ```
+ */
 class PostgresStreamService extends index_1.StreamService {
     constructor(streamClient, storeClient, config = {}) {
         super(streamClient, storeClient, config);
-        // Instance-level tracking for cleanup
-        this.instanceNotificationConsumers = new Set();
-        this.notificationHandlerBound = this.handleNotification.bind(this);
     }
     async init(namespace, appId, logger) {
         this.namespace = namespace;
         this.appId = appId;
         this.logger = logger;
         await (0, kvtables_1.deploySchema)(this.streamClient, this.appId, this.logger);
+        // Initialize scout manager
+        this.scoutManager = new scout_1.ScoutManager(this.streamClient, this.appId, this.getTableName.bind(this), this.mintKey.bind(this), this.logger);
+        // Initialize notification manager
+        this.notificationManager = new notifications_1.NotificationManager(this.streamClient, this.getTableName.bind(this), () => (0, notifications_1.getFallbackInterval)(this.config), this.logger);
         // Set up notification handler if supported
         if (this.streamClient.on && this.isNotificationsEnabled()) {
-            this.setupClientNotificationHandler();
-            this.startClientFallbackPoller();
+            this.notificationManager.setupClientNotificationHandler(this);
+            this.notificationManager.startClientFallbackPoller(this.checkForMissedMessages.bind(this));
+            this.scoutManager.startRouterScoutPoller();
         }
     }
-    setupClientNotificationHandler() {
-        // Check if notification handler is already set up for this client
-        if (PostgresStreamService.clientNotificationHandlers.get(this.streamClient)) {
-            return;
-        }
-        // Initialize notification consumer map for this client if it doesn't exist
-        if (!PostgresStreamService.clientNotificationConsumers.has(this.streamClient)) {
-            PostgresStreamService.clientNotificationConsumers.set(this.streamClient, new Map());
-        }
-        // Set up the notification handler for this client
-        this.streamClient.on('notification', this.handleNotification.bind(this));
-        // Mark this client as having a notification handler
-        PostgresStreamService.clientNotificationHandlers.set(this.streamClient, true);
-    }
-    startClientFallbackPoller() {
-        // Check if fallback poller already exists for this client
-        if (PostgresStreamService.clientFallbackPollers.has(this.streamClient)) {
-            return;
-        }
-        const fallbackIntervalId = setInterval(() => {
-            this.checkForMissedMessages();
-        }, this.getFallbackInterval());
-        PostgresStreamService.clientFallbackPollers.set(this.streamClient, fallbackIntervalId);
-    }
     isNotificationsEnabled() {
-        return this.config?.postgres?.enableNotifications !== false; // Default: true
-    }
-    getFallbackInterval() {
-        return this.config?.postgres?.notificationFallbackInterval || 30000; // Default: 30 seconds
-    }
-    getNotificationTimeout() {
-        return this.config?.postgres?.notificationTimeout || 5000; // Default: 5 seconds
+        return Stats.isNotificationsEnabled(this.config);
     }
     async checkForMissedMessages() {
-        const now = Date.now();
-        const clientNotificationConsumers = PostgresStreamService.clientNotificationConsumers.get(this.streamClient);
-        if (!clientNotificationConsumers) {
-            return;
-        }
-        for (const [consumerKey, instanceMap,] of clientNotificationConsumers.entries()) {
-            for (const [instance, consumer] of instanceMap.entries()) {
-                if (consumer.isListening &&
-                    now - consumer.lastFallbackCheck > this.getFallbackInterval()) {
-                    try {
-                        const messages = await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
-                        if (messages.length > 0) {
-                            instance.logger.debug('postgres-stream-fallback-messages', {
-                                streamName: consumer.streamName,
-                                groupName: consumer.groupName,
-                                messageCount: messages.length,
-                            });
-                            consumer.callback(messages);
-                        }
-                        consumer.lastFallbackCheck = now;
-                    }
-                    catch (error) {
-                        instance.logger.error('postgres-stream-fallback-error', {
-                            streamName: consumer.streamName,
-                            groupName: consumer.groupName,
-                            error,
-                        });
-                    }
-                }
-            }
-        }
-    }
-    handleNotification(notification) {
-        try {
-            // Only handle stream notifications (channels starting with "stream_")
-            // Ignore pub/sub notifications from sub provider which use different channel names
-            if (!notification.channel.startsWith('stream_')) {
-                // This is likely a pub/sub notification from the sub provider, ignore it
-                this.logger.debug('postgres-stream-ignoring-sub-notification', {
-                    channel: notification.channel,
-                    payloadPreview: notification.payload.substring(0, 100),
-                });
-                return;
-            }
-            this.logger.debug('postgres-stream-processing-notification', {
-                channel: notification.channel,
-            });
-            const payload = JSON.parse(notification.payload);
-            const { stream_name, group_name } = payload;
-            if (!stream_name || !group_name) {
-                this.logger.warn('postgres-stream-invalid-notification', {
-                    notification,
-                });
-                return;
-            }
-            const consumerKey = this.getConsumerKey(stream_name, group_name);
-            const clientNotificationConsumers = PostgresStreamService.clientNotificationConsumers.get(this.streamClient);
-            if (!clientNotificationConsumers) {
-                return;
-            }
-            const instanceMap = clientNotificationConsumers.get(consumerKey);
-            if (!instanceMap) {
-                return;
-            }
-            // Trigger immediate message fetch for all instances with this consumer
-            for (const [instance, consumer] of instanceMap.entries()) {
-                if (consumer.isListening) {
-                    instance.fetchAndDeliverMessages(consumer);
-                }
-            }
-        }
-        catch (error) {
-            this.logger.error('postgres-stream-notification-parse-error', {
-                notification,
-                error,
-            });
-        }
+        await this.notificationManager.checkForMissedMessages(async (instance, consumer) => {
+            return await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
+        });
     }
     async fetchAndDeliverMessages(consumer) {
         try {
@@ -171,43 +203,16 @@ class PostgresStreamService extends index_1.StreamService {
         return appId.replace(/[^a-zA-Z0-9_]/g, '_');
     }
     async createStream(streamName) {
-        return true;
+        return Lifecycle.createStream(streamName);
     }
     async deleteStream(streamName) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            if (streamName === '*') {
-                await client.query(`DELETE FROM ${tableName}`);
-            }
-            else {
-                await client.query(`DELETE FROM ${tableName} WHERE stream_name = $1`, [
-                    streamName,
-                ]);
-            }
-            return true;
-        }
-        catch (error) {
-            this.logger.error(`postgres-stream-delete-error-${streamName}`, {
-                error,
-            });
-            throw error;
-        }
+        return Lifecycle.deleteStream(this.streamClient, this.getTableName(), streamName, this.logger);
     }
     async createConsumerGroup(streamName, groupName) {
-        return true;
+        return Lifecycle.createConsumerGroup(streamName, groupName);
     }
     async deleteConsumerGroup(streamName, groupName) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            await client.query(`DELETE FROM ${tableName} WHERE stream_name = $1 AND group_name = $2`, [streamName, groupName]);
-            return true;
-        }
-        catch (error) {
-            this.logger.error(`postgres-stream-delete-group-error-${streamName}.${groupName}`, { error });
-            throw error;
-        }
+        return Lifecycle.deleteConsumerGroup(this.streamClient, this.getTableName(), streamName, groupName, this.logger);
     }
     /**
      * `publishMessages` can be roped into a transaction by the `store`
@@ -227,40 +232,10 @@ class PostgresStreamService extends index_1.StreamService {
      * allows calls to the stream to be roped into a single SQL transaction.
      */
     async publishMessages(streamName, messages, options) {
-        const { sql, params } = this._publishMessages(streamName, messages);
-        if (options?.transaction &&
-            typeof options.transaction.addCommand === 'function') {
-            //call addCommand and return the transaction object
-            options.transaction.addCommand(sql, params, 'array', (rows) => rows.map((row) => row.id.toString()));
-            return options.transaction;
-        }
-        else {
-            try {
-                const ids = [];
-                const res = await this.streamClient.query(sql, params);
-                for (const row of res.rows) {
-                    ids.push(row.id.toString());
-                }
-                return ids;
-            }
-            catch (error) {
-                this.logger.error(`postgres-stream-publish-error-${streamName}`, {
-                    error,
-                });
-                throw error;
-            }
-        }
+        return Messages.publishMessages(this.streamClient, this.getTableName(), streamName, messages, options, this.logger);
     }
-    _publishMessages(streamName, messages) {
-        const tableName = this.getTableName();
-        const groupName = streamName.endsWith(':') ? 'ENGINE' : 'WORKER';
-        const insertValues = messages
-            .map((_, idx) => `($1, $2, $${idx + 3})`)
-            .join(', ');
-        return {
-            sql: `INSERT INTO ${tableName} (stream_name, group_name, message) VALUES ${insertValues} RETURNING id`,
-            params: [streamName, groupName, ...messages],
-        };
+    _publishMessages(streamName, messages, options) {
+        return Messages.buildPublishSQL(this.getTableName(), streamName, messages, options);
     }
     async consumeMessages(streamName, groupName, consumerName, options) {
         // If notification callback is provided and notifications are enabled, set up listener
@@ -279,354 +254,87 @@ class PostgresStreamService extends index_1.StreamService {
         return enabled && this.streamClient.on !== undefined;
     }
     async setupNotificationConsumer(streamName, groupName, consumerName, callback, options) {
-        const startTime = Date.now();
-        const consumerKey = this.getConsumerKey(streamName, groupName);
-        const channelName = (0, kvtables_1.getNotificationChannelName)(streamName, groupName);
-        // Get or create notification consumer map for this client
-        let clientNotificationConsumers = PostgresStreamService.clientNotificationConsumers.get(this.streamClient);
-        if (!clientNotificationConsumers) {
-            clientNotificationConsumers = new Map();
-            PostgresStreamService.clientNotificationConsumers.set(this.streamClient, clientNotificationConsumers);
-        }
-        // Get or create instance map for this consumer key
-        let instanceMap = clientNotificationConsumers.get(consumerKey);
-        if (!instanceMap) {
-            instanceMap = new Map();
-            clientNotificationConsumers.set(consumerKey, instanceMap);
-            // Set up LISTEN for this channel (only once per channel across all instances)
-            try {
-                const listenStart = Date.now();
-                await this.streamClient.query(`LISTEN "${channelName}"`);
-                this.logger.debug('postgres-stream-listen-start', {
-                    streamName,
-                    groupName,
-                    channelName,
-                    listenDuration: Date.now() - listenStart,
-                });
-            }
-            catch (error) {
-                this.logger.error('postgres-stream-listen-error', {
-                    streamName,
-                    groupName,
-                    channelName,
-                    error,
-                });
-                // Fall back to polling if LISTEN fails
-                return this.fetchMessages(streamName, groupName, consumerName, options);
-            }
-        }
-        // Register or update consumer for this instance
-        const consumer = {
-            streamName,
-            groupName,
-            consumerName,
-            callback,
-            isListening: true,
-            lastFallbackCheck: Date.now(),
-        };
-        instanceMap.set(this, consumer);
-        // Track this consumer for cleanup
-        this.instanceNotificationConsumers.add(consumerKey);
-        this.logger.debug('postgres-stream-notification-setup-complete', {
-            streamName,
-            groupName,
-            instanceCount: instanceMap.size,
-            setupDuration: Date.now() - startTime,
-        });
-        // Do an initial fetch asynchronously to avoid blocking setup
-        // This ensures we don't miss any messages that were already in the queue
-        setImmediate(async () => {
-            try {
-                const fetchStart = Date.now();
-                const initialMessages = await this.fetchMessages(streamName, groupName, consumerName, {
-                    ...options,
-                    enableBackoff: false,
-                    maxRetries: 1,
-                });
-                this.logger.debug('postgres-stream-initial-fetch-complete', {
-                    streamName,
-                    groupName,
-                    messageCount: initialMessages.length,
-                    fetchDuration: Date.now() - fetchStart,
-                });
-                // If we got messages, call the callback
-                if (initialMessages.length > 0) {
-                    callback(initialMessages);
-                }
-            }
-            catch (error) {
-                this.logger.error('postgres-stream-initial-fetch-error', {
-                    streamName,
-                    groupName,
-                    error,
-                });
-            }
-        });
-        // Return empty array immediately to avoid blocking
-        return [];
-    }
-    async stopNotificationConsumer(streamName, groupName) {
-        const consumerKey = this.getConsumerKey(streamName, groupName);
-        const clientNotificationConsumers = PostgresStreamService.clientNotificationConsumers.get(this.streamClient);
-        if (!clientNotificationConsumers) {
-            return;
-        }
-        const instanceMap = clientNotificationConsumers.get(consumerKey);
-        if (!instanceMap) {
-            return;
-        }
-        const consumer = instanceMap.get(this);
-        if (consumer) {
-            consumer.isListening = false;
-            instanceMap.delete(this);
-            // Remove from instance tracking
-            this.instanceNotificationConsumers.delete(consumerKey);
-            // If no more instances for this consumer key, stop listening and clean up
-            if (instanceMap.size === 0) {
-                clientNotificationConsumers.delete(consumerKey);
-                const channelName = (0, kvtables_1.getNotificationChannelName)(streamName, groupName);
+        try {
+            await this.notificationManager.setupNotificationConsumer(this, streamName, groupName, consumerName, callback);
+            // Do an initial fetch asynchronously to avoid blocking setup
+            setImmediate(async () => {
                 try {
-                    await this.streamClient.query(`UNLISTEN "${channelName}"`);
-                    this.logger.debug('postgres-stream-unlisten', {
+                    const fetchStart = Date.now();
+                    const initialMessages = await this.fetchMessages(streamName, groupName, consumerName, {
+                        ...options,
+                        enableBackoff: false,
+                        maxRetries: 1,
+                    });
+                    this.logger.debug('postgres-stream-initial-fetch-complete', {
                         streamName,
                         groupName,
-                        channelName,
+                        messageCount: initialMessages.length,
+                        fetchDuration: Date.now() - fetchStart,
                     });
+                    // If we got messages, call the callback
+                    if (initialMessages.length > 0) {
+                        callback(initialMessages);
+                    }
                 }
                 catch (error) {
-                    this.logger.error('postgres-stream-unlisten-error', {
+                    this.logger.error('postgres-stream-initial-fetch-error', {
                         streamName,
                         groupName,
-                        channelName,
                         error,
                     });
                 }
-            }
-        }
-    }
-    async fetchMessages(streamName, groupName, consumerName, options) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        const enableBackoff = options?.enableBackoff ?? false;
-        const initialBackoff = options?.initialBackoff ?? 100; // Default initial backoff: 100ms
-        const maxBackoff = options?.maxBackoff ?? 3000; // Default max backoff: 3 seconds
-        const maxRetries = options?.maxRetries ?? 3; // Set a finite default, e.g., 3 retries
-        let backoff = initialBackoff;
-        let retries = 0;
-        try {
-            while (retries < maxRetries) {
-                retries++;
-                const batchSize = options?.batchSize || 1;
-                const reservationTimeout = options?.reservationTimeout || 30;
-                // Simplified query for better performance - especially for notification-triggered fetches
-                const res = await client.query(`UPDATE ${tableName} 
-           SET reserved_at = NOW(), reserved_by = $4
-           WHERE id IN (
-             SELECT id FROM ${tableName}
-             WHERE stream_name = $1 
-               AND group_name = $2
-               AND (reserved_at IS NULL OR reserved_at < NOW() - INTERVAL '${reservationTimeout} seconds')
-               AND expired_at IS NULL
-             ORDER BY id
-             LIMIT $3
-             FOR UPDATE SKIP LOCKED
-           )
-           RETURNING id, message`, [streamName, groupName, batchSize, consumerName]);
-                const messages = res.rows.map((row) => ({
-                    id: row.id.toString(),
-                    data: (0, utils_1.parseStreamMessage)(row.message),
-                }));
-                if (messages.length > 0 || !enableBackoff) {
-                    return messages;
-                }
-                // Apply backoff if enabled and no messages found
-                await (0, utils_1.sleepFor)(backoff);
-                backoff = Math.min(backoff * 2, maxBackoff); // Exponential backoff
-            }
-            // Return empty array if maxRetries is reached and still no messages
+            });
+            // Return empty array immediately to avoid blocking
             return [];
         }
         catch (error) {
-            this.logger.error(`postgres-stream-consumer-error-${streamName}`, {
-                error,
-            });
-            throw error;
+            // Fall back to polling if setup fails
+            return this.fetchMessages(streamName, groupName, consumerName, options);
         }
     }
+    async stopNotificationConsumer(streamName, groupName) {
+        await this.notificationManager.stopNotificationConsumer(this, streamName, groupName);
+    }
+    async fetchMessages(streamName, groupName, consumerName, options) {
+        return Messages.fetchMessages(this.streamClient, this.getTableName(), streamName, groupName, consumerName, options || {}, this.logger);
+    }
     async ackAndDelete(streamName, groupName, messageIds) {
-        return await this.deleteMessages(streamName, groupName, messageIds);
+        return Messages.ackAndDelete(this.streamClient, this.getTableName(), streamName, groupName, messageIds, this.logger);
     }
     async acknowledgeMessages(streamName, groupName, messageIds, options) {
-        // No-op for this implementation
-        return messageIds.length;
+        return Messages.acknowledgeMessages(messageIds);
     }
     async deleteMessages(streamName, groupName, messageIds, options) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            const ids = messageIds.map((id) => parseInt(id));
-            // Perform a soft delete by setting `expired_at` to the current timestamp
-            await client.query(`UPDATE ${tableName}
-         SET expired_at = NOW()
-         WHERE stream_name = $1 AND id = ANY($2::bigint[]) AND group_name = $3`, [streamName, ids, groupName]);
-            return messageIds.length;
-        }
-        catch (error) {
-            this.logger.error(`postgres-stream-delete-error-${streamName}`, {
-                error,
-            });
-            throw error;
-        }
+        return Messages.deleteMessages(this.streamClient, this.getTableName(), streamName, groupName, messageIds, this.logger);
     }
     async retryMessages(streamName, groupName, options) {
-        // Implement retry logic if needed
-        return [];
+        return Messages.retryMessages(streamName, groupName, options);
     }
     async getStreamStats(streamName) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            const res = await client.query(`SELECT COUNT(*) AS available_count 
-        FROM ${tableName} 
-        WHERE stream_name = $1 AND expired_at IS NULL`, [streamName]);
-            return {
-                messageCount: parseInt(res.rows[0].available_count, 10),
-            };
-        }
-        catch (error) {
-            this.logger.error(`postgres-stream-stats-error-${streamName}`, { error });
-            throw error;
-        }
+        return Stats.getStreamStats(this.streamClient, this.getTableName(), streamName, this.logger);
     }
     async getStreamDepth(streamName) {
-        const stats = await this.getStreamStats(streamName);
-        return stats.messageCount;
+        return Stats.getStreamDepth(this.streamClient, this.getTableName(), streamName, this.logger);
     }
     async getStreamDepths(streamNames) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            const streams = streamNames.map((s) => s.stream);
-            const res = await client.query(`SELECT stream_name, COUNT(*) AS count
-         FROM ${tableName}
-         WHERE stream_name = ANY($1::text[])
-         GROUP BY stream_name`, [streams]);
-            const result = res.rows.map((row) => ({
-                stream: row.stream_name,
-                depth: parseInt(row.count, 10),
-            }));
-            return result;
-        }
-        catch (error) {
-            this.logger.error('postgres-stream-depth-error', { error });
-            throw error;
-        }
+        return Stats.getStreamDepths(this.streamClient, this.getTableName(), streamNames, this.logger);
     }
     async trimStream(streamName, options) {
-        const client = this.streamClient;
-        const tableName = this.getTableName();
-        try {
-            let expiredCount = 0;
-            if (options.maxLen !== undefined) {
-                const res = await client.query(`WITH to_expire AS (
-            SELECT id FROM ${tableName}
-            WHERE stream_name = $1
-            ORDER BY id ASC
-            OFFSET $2
-          )
-          UPDATE ${tableName}
-          SET expired_at = NOW()
-          WHERE id IN (SELECT id FROM to_expire)`, [streamName, options.maxLen]);
-                expiredCount += res.rowCount;
-            }
-            if (options.maxAge !== undefined) {
-                const res = await client.query(`UPDATE ${tableName}
-          SET expired_at = NOW()
-          WHERE stream_name = $1 AND created_at < NOW() - INTERVAL '${options.maxAge} milliseconds'`, [streamName]);
-                expiredCount += res.rowCount;
-            }
-            return expiredCount;
-        }
-        catch (error) {
-            this.logger.error(`postgres-stream-trim-error-${streamName}`, { error });
-            throw error;
-        }
+        return Stats.trimStream(this.streamClient, this.getTableName(), streamName, options, this.logger);
     }
     getProviderSpecificFeatures() {
-        return {
-            supportsBatching: true,
-            supportsDeadLetterQueue: false,
-            supportsOrdering: true,
-            supportsTrimming: true,
-            supportsRetry: false,
-            supportsNotifications: this.isNotificationsEnabled(),
-            maxMessageSize: 1024 * 1024,
-            maxBatchSize: 256,
-        };
+        return Stats.getProviderSpecificFeatures(this.config);
     }
     // Cleanup method to be called when shutting down
     async cleanup() {
-        // Clean up this instance's notification consumers
-        const clientNotificationConsumers = PostgresStreamService.clientNotificationConsumers.get(this.streamClient);
-        if (clientNotificationConsumers) {
-            // Remove this instance from all consumer maps
-            for (const consumerKey of this.instanceNotificationConsumers) {
-                const instanceMap = clientNotificationConsumers.get(consumerKey);
-                if (instanceMap) {
-                    const consumer = instanceMap.get(this);
-                    if (consumer) {
-                        consumer.isListening = false;
-                        instanceMap.delete(this);
-                        // If no more instances for this consumer, stop listening
-                        if (instanceMap.size === 0) {
-                            clientNotificationConsumers.delete(consumerKey);
-                            const channelName = (0, kvtables_1.getNotificationChannelName)(consumer.streamName, consumer.groupName);
-                            try {
-                                await this.streamClient.query(`UNLISTEN "${channelName}"`);
-                                this.logger.debug('postgres-stream-cleanup-unlisten', {
-                                    streamName: consumer.streamName,
-                                    groupName: consumer.groupName,
-                                    channelName,
-                                });
-                            }
-                            catch (error) {
-                                this.logger.error('postgres-stream-cleanup-unlisten-error', {
-                                    streamName: consumer.streamName,
-                                    groupName: consumer.groupName,
-                                    channelName,
-                                    error,
-                                });
-                            }
-                        }
-                    }
-                }
-            }
+        // Stop router scout polling loop
+        if (this.scoutManager) {
+            await this.scoutManager.stopRouterScoutPoller();
         }
-        // Clear instance tracking
-        this.instanceNotificationConsumers.clear();
-        // If no more consumers exist for this client, clean up static resources
-        if (clientNotificationConsumers && clientNotificationConsumers.size === 0) {
-            // Remove client from static maps
-            PostgresStreamService.clientNotificationConsumers.delete(this.streamClient);
-            PostgresStreamService.clientNotificationHandlers.delete(this.streamClient);
-            // Stop fallback poller for this client
-            const fallbackIntervalId = PostgresStreamService.clientFallbackPollers.get(this.streamClient);
-            if (fallbackIntervalId) {
-                clearInterval(fallbackIntervalId);
-                PostgresStreamService.clientFallbackPollers.delete(this.streamClient);
-            }
-            // Remove notification handler
-            if (this.streamClient.removeAllListeners) {
-                this.streamClient.removeAllListeners('notification');
-            }
-            else if (this.streamClient.off && this.notificationHandlerBound) {
-                this.streamClient.off('notification', this.notificationHandlerBound);
-            }
+        // Clean up notification consumers
+        if (this.notificationManager) {
+            await this.notificationManager.cleanup(this);
         }
     }
 }
 exports.PostgresStreamService = PostgresStreamService;
-// Static maps to manage notifications across all instances sharing the same client
-PostgresStreamService.clientNotificationConsumers = new Map();
-PostgresStreamService.clientNotificationHandlers = new Map();
-PostgresStreamService.clientFallbackPollers = new Map();