@hotmeshio/hotmesh 0.6.1 → 0.7.0

package/build/services/store/providers/postgres/postgres.d.ts

@@ -3,7 +3,7 @@ import { ILogger } from '../../../logger';
 import { ActivityType, Consumes } from '../../../../types/activity';
 import { AppVID } from '../../../../types/app';
 import { HookRule, HookSignal } from '../../../../types/hook';
-import { HotMeshApp, HotMeshApps, HotMeshSettings } from '../../../../types/hotmesh';
+import { HotMeshApp, HotMeshApps, HotMeshSettings, ScoutType } from '../../../../types/hotmesh';
 import { ProviderClient, ProviderTransaction } from '../../../../types/provider';
 import { SymbolSets, StringStringType, StringAnyType, Symbols } from '../../../../types/serializer';
 import { IdsData, JobStatsRange, StatsType } from '../../../../types/stats';
@@ -38,8 +38,8 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
      * check for and process work items in the
      * time and signal task queues.
      */
-    reserveScoutRole(scoutType: 'time' | 'signal' | 'activate', delay?: number): Promise<boolean>;
-    releaseScoutRole(scoutType: 'time' | 'signal' | 'activate'): Promise<boolean>;
+    reserveScoutRole(scoutType: ScoutType, delay?: number): Promise<boolean>;
+    releaseScoutRole(scoutType: ScoutType): Promise<boolean>;
     getSettings(bCreate?: boolean): Promise<HotMeshSettings>;
     setSettings(manifest: HotMeshSettings): Promise<any>;
     reserveSymbolRange(target: string, size: number, type: 'JOB' | 'ACTIVITY', tryCount?: number): Promise<[number, number, Symbols]>;

package/build/services/store/providers/redis/_base.d.ts

@@ -3,7 +3,7 @@ import { ILogger } from '../../../logger';
 import { ActivityType, Consumes } from '../../../../types/activity';
 import { AppVID } from '../../../../types/app';
 import { HookRule, HookSignal } from '../../../../types/hook';
-import { HotMeshApp, HotMeshApps, HotMeshSettings } from '../../../../types/hotmesh';
+import { HotMeshApp, HotMeshApps, HotMeshSettings, ScoutType } from '../../../../types/hotmesh';
 import { ProviderClient, ProviderTransaction } from '../../../../types/provider';
 import { SymbolSets, StringStringType, StringAnyType, Symbols } from '../../../../types/serializer';
 import { IdsData, JobStatsRange, StatsType } from '../../../../types/stats';
@@ -30,8 +30,8 @@ declare abstract class RedisStoreBase<ClientProvider extends ProviderClient, Tra
      * check for and process work items in the
      * time and signal task queues.
      */
-    reserveScoutRole(scoutType: 'time' | 'signal' | 'activate', delay?: number): Promise<boolean>;
-    releaseScoutRole(scoutType: 'time' | 'signal' | 'activate'): Promise<boolean>;
+    reserveScoutRole(scoutType: ScoutType, delay?: number): Promise<boolean>;
+    releaseScoutRole(scoutType: ScoutType): Promise<boolean>;
     getSettings(bCreate?: boolean): Promise<HotMeshSettings>;
     setSettings(manifest: HotMeshSettings): Promise<any>;
     reserveSymbolRange(target: string, size: number, type: 'JOB' | 'ACTIVITY', tryCount?: number): Promise<[number, number, Symbols]>;

package/build/services/store/providers/redis/ioredis.js

@@ -148,17 +148,27 @@ class IORedisStoreService extends _base_1.RedisStoreBase {
         return this.storeClient.multi();
     }
     async exec(...args) {
-        const response = await this.storeClient.call.apply(this.storeClient, args);
-        if (typeof response === 'string') {
-            return response;
-        }
-        else if (Array.isArray(response)) {
-            if (Array.isArray(response[0])) {
+        try {
+            const response = await this.storeClient.call.apply(this.storeClient, args);
+            if (typeof response === 'string') {
+                return response;
+            }
+            else if (Array.isArray(response)) {
+                if (Array.isArray(response[0])) {
+                    return response;
+                }
                 return response;
             }
             return response;
         }
-        return response;
+        catch (error) {
+            // Connection closed during test cleanup - log and return empty response
+            if (error?.message?.includes('Connection is closed')) {
+                return [];
+            }
+            // Re-throw unexpected errors
+            throw error;
+        }
     }
     async setnxex(key, value, expireSeconds) {
         const status = await this.storeClient[this.commands.set](key, value, 'NX', 'EX', expireSeconds.toString());

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

@@ -73,8 +73,13 @@ function hashStringToInt(str) {
     return Math.abs(hash);
 }
 async function checkIfTablesExist(client, schemaName, tableName) {
-    const result = await client.query(`SELECT to_regclass('${tableName}') AS t`);
-    return result.rows[0].t !== null;
+    // Check both streams table exists AND roles table (from store provider)
+    // The roles table is created by the store provider and is used for scout role coordination
+    const result = await client.query(`SELECT 
+       to_regclass($1) AS streams_table,
+       to_regclass($2) AS roles_table`, [tableName, `${schemaName}.roles`]);
+    return result.rows[0].streams_table !== null &&
+        result.rows[0].roles_table !== null;
 }
 async function waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger) {
     let retries = 0;
@@ -124,6 +129,11 @@ async function createTables(client, schemaName, tableName) {
       reserved_at TIMESTAMPTZ,
       reserved_by TEXT,
       expired_at TIMESTAMPTZ,
+      max_retry_attempts INT DEFAULT 3,
+      backoff_coefficient NUMERIC DEFAULT 10,
+      maximum_interval_seconds INT DEFAULT 120,
+      visible_at TIMESTAMPTZ DEFAULT NOW(),
+      retry_attempt INT DEFAULT 0,
       PRIMARY KEY (stream_name, id)
     ) PARTITION BY HASH (stream_name);
   `);
@@ -135,16 +145,16 @@ async function createTables(client, schemaName, tableName) {
       FOR VALUES WITH (modulus 8, remainder ${i});
     `);
     }
-    // Index for active messages
+    // Index for active messages (includes visible_at for visibility timeout support)
     await client.query(`
     CREATE INDEX IF NOT EXISTS idx_streams_active_messages 
-    ON ${tableName} (group_name, stream_name, reserved_at, id)
+    ON ${tableName} (group_name, stream_name, reserved_at, visible_at, id)
     WHERE reserved_at IS NULL AND expired_at IS NULL;
   `);
-    // Optimized index for the simplified fetchMessages query
+    // Optimized index for the simplified fetchMessages query (includes visible_at)
     await client.query(`
     CREATE INDEX IF NOT EXISTS idx_streams_message_fetch 
-    ON ${tableName} (stream_name, group_name, id)
+    ON ${tableName} (stream_name, group_name, visible_at, id)
     WHERE expired_at IS NULL;
   `);
     // Index for expired messages
@@ -166,7 +176,7 @@ async function createTables(client, schemaName, tableName) {
     // `);
 }
 async function createNotificationTriggers(client, schemaName, tableName) {
-    // Create the notification function
+    // Create the notification function for INSERT events
     await client.query(`
     CREATE OR REPLACE FUNCTION ${schemaName}.notify_new_stream_message()
     RETURNS TRIGGER AS $$
@@ -174,24 +184,26 @@ async function createNotificationTriggers(client, schemaName, tableName) {
       channel_name TEXT;
       payload JSON;
     BEGIN
-      -- Create channel name: stream_{stream_name}_{group_name}
-      -- Truncate if too long (PostgreSQL channel names limited to 63 chars)
-      channel_name := 'stream_' || NEW.stream_name || '_' || NEW.group_name;
-      IF length(channel_name) > 63 THEN
-        channel_name := left(channel_name, 63);
+      -- Only notify if message is immediately visible
+      -- Messages with visibility timeout will be notified when they become visible
+      IF NEW.visible_at <= NOW() THEN
+        -- Create channel name: stream_{stream_name}_{group_name}
+        -- Truncate if too long (PostgreSQL channel names limited to 63 chars)
+        channel_name := 'stream_' || NEW.stream_name || '_' || NEW.group_name;
+        IF length(channel_name) > 63 THEN
+          channel_name := left(channel_name, 63);
+        END IF;
+        
+        -- Create minimal payload with only required fields
+        payload := json_build_object(
+          'stream_name', NEW.stream_name,
+          'group_name', NEW.group_name
+        );
+        
+        -- Send notification
+        PERFORM pg_notify(channel_name, payload::text);
       END IF;
       
-      -- Create payload with message details
-      payload := json_build_object(
-        'id', NEW.id,
-        'stream_name', NEW.stream_name,
-        'group_name', NEW.group_name,
-        'created_at', extract(epoch from NEW.created_at)
-      );
-      
-      -- Send notification
-      PERFORM pg_notify(channel_name, payload::text);
-      
       RETURN NEW;
     END;
     $$ LANGUAGE plpgsql;
@@ -204,6 +216,47 @@ async function createNotificationTriggers(client, schemaName, tableName) {
       FOR EACH ROW
       EXECUTE FUNCTION ${schemaName}.notify_new_stream_message();
   `);
+    // Create helper function to notify about messages with expired visibility timeouts
+    // This is called periodically by the router scout for responsive retry processing
+    await client.query(`
+    CREATE OR REPLACE FUNCTION ${schemaName}.notify_visible_messages()
+    RETURNS INTEGER AS $$
+    DECLARE
+      msg RECORD;
+      channel_name TEXT;
+      payload JSON;
+      notification_count INTEGER := 0;
+    BEGIN
+      -- Find all distinct streams with messages that are now visible
+      -- Router will drain all messages when notified, so we just notify each channel once
+      FOR msg IN 
+        SELECT DISTINCT stream_name, group_name
+        FROM ${tableName}
+        WHERE visible_at <= NOW()
+          AND reserved_at IS NULL
+          AND expired_at IS NULL
+        LIMIT 100  -- Prevent overwhelming the system
+      LOOP
+        -- Create channel name (same logic as INSERT trigger)
+        channel_name := 'stream_' || msg.stream_name || '_' || msg.group_name;
+        IF length(channel_name) > 63 THEN
+          channel_name := left(channel_name, 63);
+        END IF;
+        
+        -- Send minimal notification with only required fields
+        payload := json_build_object(
+          'stream_name', msg.stream_name,
+          'group_name', msg.group_name
+        );
+        
+        PERFORM pg_notify(channel_name, payload::text);
+        notification_count := notification_count + 1;
+      END LOOP;
+      
+      RETURN notification_count;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
 }
 function getNotificationChannelName(streamName, groupName) {
     const channelName = `stream_${streamName}_${groupName}`;

package/build/services/stream/providers/postgres/lifecycle.d.ts

@@ -0,0 +1,19 @@
+import { ILogger } from '../../../logger';
+import { PostgresClientType } from '../../../../types/postgres';
+import { ProviderClient } from '../../../../types/provider';
+/**
+ * Create a stream (no-op for PostgreSQL - streams are created implicitly).
+ */
+export declare function createStream(streamName: string): Promise<boolean>;
+/**
+ * Delete a stream or all streams.
+ */
+export declare function deleteStream(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, logger: ILogger): Promise<boolean>;
+/**
+ * Create a consumer group (no-op for PostgreSQL - groups are created implicitly).
+ */
+export declare function createConsumerGroup(streamName: string, groupName: string): Promise<boolean>;
+/**
+ * Delete a consumer group (removes all messages for that group).
+ */
+export declare function deleteConsumerGroup(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, logger: ILogger): Promise<boolean>;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteConsumerGroup = exports.createConsumerGroup = exports.deleteStream = exports.createStream = void 0;
+/**
+ * Create a stream (no-op for PostgreSQL - streams are created implicitly).
+ */
+async function createStream(streamName) {
+    return true;
+}
+exports.createStream = createStream;
+/**
+ * Delete a stream or all streams.
+ */
+async function deleteStream(client, tableName, streamName, logger) {
+    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) {
+        logger.error(`postgres-stream-delete-error-${streamName}`, {
+            error,
+        });
+        throw error;
+    }
+}
+exports.deleteStream = deleteStream;
+/**
+ * Create a consumer group (no-op for PostgreSQL - groups are created implicitly).
+ */
+async function createConsumerGroup(streamName, groupName) {
+    return true;
+}
+exports.createConsumerGroup = createConsumerGroup;
+/**
+ * Delete a consumer group (removes all messages for that group).
+ */
+async function deleteConsumerGroup(client, tableName, streamName, groupName, logger) {
+    try {
+        await client.query(`DELETE FROM ${tableName} WHERE stream_name = $1 AND group_name = $2`, [streamName, groupName]);
+        return true;
+    }
+    catch (error) {
+        logger.error(`postgres-stream-delete-group-error-${streamName}.${groupName}`, { error });
+        throw error;
+    }
+}
+exports.deleteConsumerGroup = deleteConsumerGroup;

package/build/services/stream/providers/postgres/messages.d.ts

@@ -0,0 +1,56 @@
+import { ILogger } from '../../../logger';
+import { PostgresClientType } from '../../../../types/postgres';
+import { PublishMessageConfig, StreamMessage } from '../../../../types/stream';
+import { ProviderClient, ProviderTransaction } from '../../../../types/provider';
+/**
+ * Publish messages to a stream. Can be used within a transaction.
+ *
+ * When a transaction is provided, the SQL is added to the transaction
+ * and executed atomically with other operations.
+ */
+export declare function publishMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, messages: string[], options: PublishMessageConfig | undefined, logger: ILogger): Promise<string[] | ProviderTransaction>;
+/**
+ * Build SQL for publishing messages with retry policies and visibility delays.
+ * Optimizes the INSERT statement based on whether retry config is present.
+ */
+export declare function buildPublishSQL(tableName: string, streamName: string, messages: string[], options?: PublishMessageConfig): {
+    sql: string;
+    params: any[];
+};
+/**
+ * Fetch messages from the stream with optional exponential backoff.
+ * Uses SKIP LOCKED for high-concurrency consumption.
+ */
+export declare function fetchMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, consumerName: string, options: {
+    batchSize?: number;
+    blockTimeout?: number;
+    autoAck?: boolean;
+    reservationTimeout?: number;
+    enableBackoff?: boolean;
+    initialBackoff?: number;
+    maxBackoff?: number;
+    maxRetries?: number;
+}, logger: ILogger): Promise<StreamMessage[]>;
+/**
+ * Acknowledge messages (no-op for PostgreSQL - uses soft delete pattern).
+ */
+export declare function acknowledgeMessages(messageIds: string[]): Promise<number>;
+/**
+ * Delete messages by soft-deleting them (setting expired_at).
+ */
+export declare function deleteMessages(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, messageIds: string[], logger: ILogger): Promise<number>;
+/**
+ * Acknowledge and delete messages in one operation.
+ */
+export declare function ackAndDelete(client: PostgresClientType & ProviderClient, tableName: string, streamName: string, groupName: string, messageIds: string[], logger: ILogger): Promise<number>;
+/**
+ * Retry messages (placeholder for future implementation).
+ */
+export declare function retryMessages(streamName: string, groupName: string, options?: {
+    consumerName?: string;
+    minIdleTime?: number;
+    messageIds?: string[];
+    delay?: number;
+    maxRetries?: number;
+    limit?: number;
+}): Promise<StreamMessage[]>;

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

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryMessages = exports.ackAndDelete = exports.deleteMessages = exports.acknowledgeMessages = exports.fetchMessages = exports.buildPublishSQL = exports.publishMessages = void 0;
+const utils_1 = require("../../../../modules/utils");
+/**
+ * Publish messages to a stream. Can be used within a transaction.
+ *
+ * When a transaction is provided, the SQL is added to the transaction
+ * and executed atomically with other operations.
+ */
+async function publishMessages(client, tableName, streamName, messages, options, logger) {
+    const { sql, params } = buildPublishSQL(tableName, streamName, messages, options);
+    if (options?.transaction &&
+        typeof options.transaction.addCommand === 'function') {
+        // Add to transaction 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 client.query(sql, params);
+            for (const row of res.rows) {
+                ids.push(row.id.toString());
+            }
+            return ids;
+        }
+        catch (error) {
+            logger.error(`postgres-stream-publish-error-${streamName}`, {
+                error,
+            });
+            throw error;
+        }
+    }
+}
+exports.publishMessages = publishMessages;
+/**
+ * Build SQL for publishing messages with retry policies and visibility delays.
+ * Optimizes the INSERT statement based on whether retry config is present.
+ */
+function buildPublishSQL(tableName, streamName, messages, options) {
+    const groupName = streamName.endsWith(':') ? 'ENGINE' : 'WORKER';
+    // Parse messages to extract retry config and visibility options
+    const parsedMessages = messages.map(msg => {
+        const data = JSON.parse(msg);
+        const retryConfig = data._streamRetryConfig;
+        const visibilityDelayMs = data._visibilityDelayMs;
+        const retryAttempt = data._retryAttempt;
+        // Remove internal fields from message payload
+        delete data._streamRetryConfig;
+        delete data._visibilityDelayMs;
+        delete data._retryAttempt;
+        // Determine if this message has explicit retry config
+        const hasExplicitConfig = (retryConfig && 'max_retry_attempts' in retryConfig) || options?.retryPolicy;
+        let normalizedPolicy = null;
+        if (retryConfig && 'max_retry_attempts' in retryConfig) {
+            normalizedPolicy = retryConfig;
+        }
+        else if (options?.retryPolicy) {
+            normalizedPolicy = (0, utils_1.normalizeRetryPolicy)(options.retryPolicy, {
+                maximumAttempts: 3,
+                backoffCoefficient: 10,
+                maximumInterval: 120,
+            });
+        }
+        return {
+            message: JSON.stringify(data),
+            hasExplicitConfig,
+            retryPolicy: normalizedPolicy,
+            visibilityDelayMs: visibilityDelayMs || 0,
+            retryAttempt: retryAttempt || 0,
+        };
+    });
+    const params = [streamName, groupName];
+    let valuesClauses = [];
+    let insertColumns;
+    // Check if ALL messages have explicit config or ALL don't
+    const allHaveConfig = parsedMessages.every(pm => pm.hasExplicitConfig);
+    const noneHaveConfig = parsedMessages.every(pm => !pm.hasExplicitConfig);
+    const hasVisibilityDelays = parsedMessages.some(pm => pm.visibilityDelayMs > 0);
+    if (noneHaveConfig && !hasVisibilityDelays) {
+        // Omit retry columns entirely - let DB defaults apply
+        insertColumns = '(stream_name, group_name, message)';
+        parsedMessages.forEach((pm, idx) => {
+            const base = idx * 1;
+            valuesClauses.push(`($1, $2, $${base + 3})`);
+            params.push(pm.message);
+        });
+    }
+    else if (noneHaveConfig && hasVisibilityDelays) {
+        // Only visibility delays, no retry config
+        insertColumns = '(stream_name, group_name, message, visible_at, retry_attempt)';
+        parsedMessages.forEach((pm, idx) => {
+            const base = idx * 2;
+            if (pm.visibilityDelayMs > 0) {
+                const visibleAtSQL = `NOW() + INTERVAL '${pm.visibilityDelayMs} milliseconds'`;
+                valuesClauses.push(`($1, $2, $${base + 3}, ${visibleAtSQL}, $${base + 4})`);
+                params.push(pm.message, pm.retryAttempt);
+            }
+            else {
+                valuesClauses.push(`($1, $2, $${base + 3}, DEFAULT, $${base + 4})`);
+                params.push(pm.message, pm.retryAttempt);
+            }
+        });
+    }
+    else {
+        // Include retry columns and optionally visibility
+        insertColumns = '(stream_name, group_name, message, max_retry_attempts, backoff_coefficient, maximum_interval_seconds, visible_at, retry_attempt)';
+        parsedMessages.forEach((pm, idx) => {
+            const visibleAtClause = pm.visibilityDelayMs > 0
+                ? `NOW() + INTERVAL '${pm.visibilityDelayMs} milliseconds'`
+                : 'DEFAULT';
+            if (pm.hasExplicitConfig) {
+                const paramOffset = params.length + 1; // Current param count + 1 for next param
+                valuesClauses.push(`($1, $2, $${paramOffset}, $${paramOffset + 1}, $${paramOffset + 2}, $${paramOffset + 3}, ${visibleAtClause}, $${paramOffset + 4})`);
+                params.push(pm.message, pm.retryPolicy.max_retry_attempts, pm.retryPolicy.backoff_coefficient, pm.retryPolicy.maximum_interval_seconds, pm.retryAttempt);
+            }
+            else {
+                // This message doesn't have config but others do - use DEFAULT keyword
+                const paramOffset = params.length + 1;
+                valuesClauses.push(`($1, $2, $${paramOffset}, DEFAULT, DEFAULT, DEFAULT, ${visibleAtClause}, $${paramOffset + 1})`);
+                params.push(pm.message, pm.retryAttempt);
+            }
+        });
+    }
+    return {
+        sql: `INSERT INTO ${tableName} ${insertColumns}
+      VALUES ${valuesClauses.join(', ')} 
+      RETURNING id`,
+        params,
+    };
+}
+exports.buildPublishSQL = buildPublishSQL;
+/**
+ * Fetch messages from the stream with optional exponential backoff.
+ * Uses SKIP LOCKED for high-concurrency consumption.
+ */
+async function fetchMessages(client, tableName, streamName, groupName, consumerName, options = {}, logger) {
+    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
+             AND visible_at <= NOW()
+           ORDER BY id
+           LIMIT $3
+           FOR UPDATE SKIP LOCKED
+         )
+         RETURNING id, message, max_retry_attempts, backoff_coefficient, maximum_interval_seconds, retry_attempt`, [streamName, groupName, batchSize, consumerName]);
+            const messages = res.rows.map((row) => {
+                const data = (0, utils_1.parseStreamMessage)(row.message);
+                // Inject retry policy only if not using default values
+                // Default values indicate old retry mechanism should be used (policies.retry)
+                const hasDefaultRetryPolicy = (row.max_retry_attempts === 3 || row.max_retry_attempts === 5) &&
+                    parseFloat(row.backoff_coefficient) === 10 &&
+                    row.maximum_interval_seconds === 120;
+                if (row.max_retry_attempts !== null && !hasDefaultRetryPolicy) {
+                    data._streamRetryConfig = {
+                        max_retry_attempts: row.max_retry_attempts,
+                        backoff_coefficient: parseFloat(row.backoff_coefficient),
+                        maximum_interval_seconds: row.maximum_interval_seconds,
+                    };
+                }
+                // Inject retry_attempt from database
+                if (row.retry_attempt !== undefined && row.retry_attempt !== null) {
+                    data._retryAttempt = row.retry_attempt;
+                }
+                return {
+                    id: row.id.toString(),
+                    data,
+                    retryPolicy: (row.max_retry_attempts !== null && !hasDefaultRetryPolicy) ? {
+                        maximumAttempts: row.max_retry_attempts,
+                        backoffCoefficient: parseFloat(row.backoff_coefficient),
+                        maximumInterval: row.maximum_interval_seconds,
+                    } : undefined,
+                };
+            });
+            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 [];
+    }
+    catch (error) {
+        logger.error(`postgres-stream-consumer-error-${streamName}`, {
+            error,
+        });
+        throw error;
+    }
+}
+exports.fetchMessages = fetchMessages;
+/**
+ * Acknowledge messages (no-op for PostgreSQL - uses soft delete pattern).
+ */
+async function acknowledgeMessages(messageIds) {
+    // No-op for this implementation
+    return messageIds.length;
+}
+exports.acknowledgeMessages = acknowledgeMessages;
+/**
+ * Delete messages by soft-deleting them (setting expired_at).
+ */
+async function deleteMessages(client, tableName, streamName, groupName, messageIds, logger) {
+    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) {
+        logger.error(`postgres-stream-delete-error-${streamName}`, {
+            error,
+        });
+        throw error;
+    }
+}
+exports.deleteMessages = deleteMessages;
+/**
+ * Acknowledge and delete messages in one operation.
+ */
+async function ackAndDelete(client, tableName, streamName, groupName, messageIds, logger) {
+    return await deleteMessages(client, tableName, streamName, groupName, messageIds, logger);
+}
+exports.ackAndDelete = ackAndDelete;
+/**
+ * Retry messages (placeholder for future implementation).
+ */
+async function retryMessages(streamName, groupName, options) {
+    // Implement retry logic if needed
+    return [];
+}
+exports.retryMessages = retryMessages;

package/build/services/stream/providers/postgres/notifications.d.ts

@@ -0,0 +1,59 @@
+import { ILogger } from '../../../logger';
+import { PostgresClientType } from '../../../../types/postgres';
+import { NotificationConsumer, StreamMessage } from '../../../../types/stream';
+import { ProviderClient } from '../../../../types/provider';
+/**
+ * Manages PostgreSQL LISTEN/NOTIFY for stream message notifications.
+ * Handles static state shared across all service instances using the same client.
+ */
+export declare class NotificationManager<TService> {
+    private client;
+    private getTableName;
+    private getFallbackInterval;
+    private logger;
+    private static clientNotificationConsumers;
+    private static clientNotificationHandlers;
+    private static clientFallbackPollers;
+    private instanceNotificationConsumers;
+    private notificationHandlerBound;
+    constructor(client: PostgresClientType & ProviderClient, getTableName: () => string, getFallbackInterval: () => number, logger: ILogger);
+    /**
+     * Set up notification handler for this client (once per client).
+     */
+    setupClientNotificationHandler(serviceInstance: TService): void;
+    /**
+     * Start fallback poller for missed notifications (once per client).
+     */
+    startClientFallbackPoller(checkForMissedMessages: () => Promise<void>): void;
+    /**
+     * Check for missed messages (fallback polling).
+     * Handles errors gracefully to avoid noise during shutdown.
+     */
+    checkForMissedMessages(fetchMessages: (instance: TService, consumer: NotificationConsumer) => Promise<StreamMessage[]>): Promise<void>;
+    /**
+     * Handle incoming PostgreSQL notification.
+     */
+    private handleNotification;
+    /**
+     * Set up notification consumer for a stream/group.
+     */
+    setupNotificationConsumer(serviceInstance: TService, streamName: string, groupName: string, consumerName: string, callback: (messages: StreamMessage[]) => void): Promise<void>;
+    /**
+     * Stop notification consumer for a stream/group.
+     */
+    stopNotificationConsumer(serviceInstance: TService, streamName: string, groupName: string): Promise<void>;
+    /**
+     * Clean up notification consumers for this instance.
+     * Stops fallback poller FIRST to prevent race conditions during shutdown.
+     */
+    cleanup(serviceInstance: TService): Promise<void>;
+    /**
+     * Get consumer key from stream and group names.
+     */
+    private getConsumerKey;
+}
+/**
+ * Get configuration values for notification settings.
+ */
+export declare function getFallbackInterval(config: any): number;
+export declare function getNotificationTimeout(config: any): number;