@hotmeshio/hotmesh 0.5.8 → 0.6.0

package/build/modules/enums.d.ts

@@ -107,3 +107,9 @@ export declare const HMSH_GUID_SIZE: number;
  * Default task queue name used when no task queue is specified
  */
 export declare const DEFAULT_TASK_QUEUE = "default";
+/**
+ * PostgreSQL NOTIFY payload limit. If a job message exceeds this size,
+ * a reference message is sent instead and the subscriber fetches via getState.
+ * PostgreSQL hard limit is 8000 bytes; default 7500 provides safety margin.
+ */
+export declare const HMSH_NOTIFY_PAYLOAD_LIMIT: number;

package/build/modules/enums.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -131,3 +131,9 @@ exports.HMSH_GUID_SIZE = Math.min(parseInt(process.env.HMSH_GUID_SIZE, 10) || 22
  * Default task queue name used when no task queue is specified
  */
 exports.DEFAULT_TASK_QUEUE = 'default';
+/**
+ * PostgreSQL NOTIFY payload limit. If a job message exceeds this size,
+ * a reference message is sent instead and the subscriber fetches via getState.
+ * PostgreSQL hard limit is 8000 bytes; default 7500 provides safety margin.
+ */
+exports.HMSH_NOTIFY_PAYLOAD_LIMIT = parseInt(process.env.HMSH_NOTIFY_PAYLOAD_LIMIT, 10) || 7500;

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.5.8",
+    "version": "0.6.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/engine/index.js

@@ -547,7 +547,12 @@ class EngineService {
      */
     async sub(topic, callback) {
         const subscriptionCallback = async (topic, message) => {
-            callback(message.topic, message.job);
+            let jobOutput = message.job;
+            // If _ref is true, payload was too large - fetch full job data via getState
+            if (message._ref && message.job?.metadata) {
+                jobOutput = await this.getState(message.job.metadata.tpc, message.job.metadata.jid);
+            }
+            callback(message.topic, jobOutput);
         };
         return await this.subscribe.subscribe(key_1.KeyType.QUORUM, subscriptionCallback, this.appId, topic);
     }
@@ -562,7 +567,12 @@ class EngineService {
      */
     async psub(wild, callback) {
         const subscriptionCallback = async (topic, message) => {
-            callback(message.topic, message.job);
+            let jobOutput = message.job;
+            // If _ref is true, payload was too large - fetch full job data via getState
+            if (message._ref && message.job?.metadata) {
+                jobOutput = await this.getState(message.job.metadata.tpc, message.job.metadata.jid);
+            }
+            callback(message.topic, jobOutput);
         };
         return await this.subscribe.psubscribe(key_1.KeyType.QUORUM, subscriptionCallback, this.appId, wild);
     }

package/build/services/quorum/index.js

@@ -88,7 +88,24 @@ class QuorumService {
                 self.engine.processWebHooks();
             }
             else if (message.type === 'job') {
-                self.engine.routeToSubscribers(message.topic, message.job);
+                let jobOutput = message.job;
+                // If _ref is true, payload was too large - fetch full job data via getState
+                if (message._ref && message.job?.metadata) {
+                    try {
+                        jobOutput = await self.engine.getState(message.job.metadata.tpc, message.job.metadata.jid);
+                        self.logger.debug('quorum-job-ref-resolved', {
+                            jid: message.job.metadata.jid,
+                        });
+                    }
+                    catch (err) {
+                        self.logger.error('quorum-job-ref-error', {
+                            jid: message.job.metadata.jid,
+                            error: err,
+                        });
+                        return; // Can't route without job data
+                    }
+                }
+                self.engine.routeToSubscribers(message.topic, jobOutput);
             }
             else if (message.type === 'cron') {
                 self.engine.processTimeHooks();

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

@@ -33,6 +33,7 @@ const cache_1 = require("../../cache");
 const __1 = require("../..");
 const kvsql_1 = require("./kvsql");
 const kvtables_1 = require("./kvtables");
+const time_notify_1 = require("./time-notify");
 class PostgresStoreService extends __1.StoreService {
     transact() {
         return this.storeClient.transact();
@@ -1039,11 +1040,8 @@ class PostgresStoreService extends __1.StoreService {
         const schemaName = this.kvsql().safeName(appId);
         const client = this.pgClient;
         try {
-            // Read the SQL template and replace schema placeholder
-            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
-            const path = await Promise.resolve().then(() => __importStar(require('path')));
-            const sqlTemplate = fs.readFileSync(path.join(__dirname, 'time-notify.sql'), 'utf8');
-            const sql = sqlTemplate.replace(/{schema}/g, schemaName);
+            // Get the SQL with schema placeholder replaced
+            const sql = (0, time_notify_1.getTimeNotifySql)(schemaName);
             // Execute the entire SQL as one statement (functions contain $$ blocks with semicolons)
             await client.query(sql);
             this.logger.info('postgres-time-notifications-deployed', {

package/build/services/store/providers/postgres/time-notify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Time-aware notification system for PostgreSQL
+ * This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+ *
+ * Exported as a function that returns the SQL with schema placeholder replaced.
+ */
+export declare function getTimeNotifySql(schema: string): string;

package/build/services/store/providers/postgres/time-notify.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTimeNotifySql = void 0;
+/**
+ * Time-aware notification system for PostgreSQL
+ * This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+ *
+ * Exported as a function that returns the SQL with schema placeholder replaced.
+ */
+function getTimeNotifySql(schema) {
+    return `
+-- Time-aware notification system for PostgreSQL
+-- This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+
+-- Function to calculate the next awakening time from the sorted set
+CREATE OR REPLACE FUNCTION ${schema}.get_next_awakening_time(app_key TEXT)
+RETURNS TIMESTAMP WITH TIME ZONE AS $$
+DECLARE
+    next_score DOUBLE PRECISION;
+    next_time TIMESTAMP WITH TIME ZONE;
+BEGIN
+    -- Get the earliest (lowest score) entry from the time range ZSET
+    SELECT score INTO next_score
+    FROM ${schema}.task_schedules
+    WHERE key = app_key
+    AND (expiry IS NULL OR expiry > NOW())
+    ORDER BY score ASC
+    LIMIT 1;
+    
+    IF next_score IS NULL THEN
+        RETURN NULL;
+    END IF;
+    
+    -- Convert epoch milliseconds to timestamp
+    next_time := to_timestamp(next_score / 1000.0);
+    
+    -- Only return if it's in the future
+    IF next_time > NOW() THEN
+        RETURN next_time;
+    END IF;
+    
+    RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to schedule a notification for the next awakening time
+CREATE OR REPLACE FUNCTION ${schema}.schedule_time_notification(
+    app_id TEXT,
+    new_awakening_time TIMESTAMP WITH TIME ZONE DEFAULT NULL
+)
+RETURNS VOID AS $$
+DECLARE
+    channel_name TEXT;
+    current_next_time TIMESTAMP WITH TIME ZONE;
+    app_key TEXT;
+BEGIN
+    -- Build the time range key for this app
+    app_key := app_id || ':time_range';
+    channel_name := 'time_hooks_' || app_id;
+    
+    -- Get the current next awakening time
+    current_next_time := ${schema}.get_next_awakening_time(app_key);
+    
+    -- If we have a specific new awakening time, check if it's earlier
+    IF new_awakening_time IS NOT NULL THEN
+        IF current_next_time IS NULL OR new_awakening_time < current_next_time THEN
+            current_next_time := new_awakening_time;
+        END IF;
+    END IF;
+    
+    -- If there's a next awakening time, schedule immediate notification
+    -- The application will handle the timing logic
+    IF current_next_time IS NOT NULL THEN
+        PERFORM pg_notify(channel_name, json_build_object(
+            'type', 'time_schedule_updated',
+            'app_id', app_id,
+            'next_awakening', extract(epoch from current_next_time) * 1000,
+            'updated_at', extract(epoch from NOW()) * 1000
+        )::text);
+    END IF;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to notify when time hooks are ready
+CREATE OR REPLACE FUNCTION ${schema}.notify_time_hooks_ready(app_id TEXT)
+RETURNS VOID AS $$
+DECLARE
+    channel_name TEXT;
+BEGIN
+    channel_name := 'time_hooks_' || app_id;
+    
+    PERFORM pg_notify(channel_name, json_build_object(
+        'type', 'time_hooks_ready',
+        'app_id', app_id,
+        'ready_at', extract(epoch from NOW()) * 1000
+    )::text);
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger function for when time hooks are added/updated
+CREATE OR REPLACE FUNCTION ${schema}.on_time_hook_change()
+RETURNS TRIGGER AS $$
+DECLARE
+    app_id_extracted TEXT;
+    awakening_time TIMESTAMP WITH TIME ZONE;
+BEGIN
+    -- Extract app_id from the key (assumes format: app_id:time_range)
+    app_id_extracted := split_part(NEW.key, ':time_range', 1);
+    
+    -- Convert the score (epoch milliseconds) to timestamp
+    awakening_time := to_timestamp(NEW.score / 1000.0);
+    
+    -- Schedule notification for this new awakening time
+    PERFORM ${schema}.schedule_time_notification(app_id_extracted, awakening_time);
+    
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger function for when time hooks are removed
+CREATE OR REPLACE FUNCTION ${schema}.on_time_hook_remove()
+RETURNS TRIGGER AS $$
+DECLARE
+    app_id_extracted TEXT;
+BEGIN
+    -- Extract app_id from the key
+    app_id_extracted := split_part(OLD.key, ':time_range', 1);
+    
+    -- Recalculate and notify about the schedule update
+    PERFORM ${schema}.schedule_time_notification(app_id_extracted);
+    
+    RETURN OLD;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create triggers on the sorted_set table for time hooks
+-- Note: These will be created per app schema
+-- Drop existing triggers first to avoid conflicts
+DROP TRIGGER IF EXISTS trg_time_hook_insert ON ${schema}.task_schedules;
+DROP TRIGGER IF EXISTS trg_time_hook_update ON ${schema}.task_schedules;
+DROP TRIGGER IF EXISTS trg_time_hook_delete ON ${schema}.task_schedules;
+
+-- Create new triggers
+CREATE TRIGGER trg_time_hook_insert
+    AFTER INSERT ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (NEW.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_change();
+
+CREATE TRIGGER trg_time_hook_update
+    AFTER UPDATE ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (NEW.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_change();
+
+CREATE TRIGGER trg_time_hook_delete
+    AFTER DELETE ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (OLD.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_remove();
+`;
+}
+exports.getTimeNotifySql = getTimeNotifySql;

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

@@ -1,25 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNotificationChannelName = exports.deploySchema = void 0;
+const enums_1 = require("../../../../modules/enums");
+const utils_1 = require("../../../../modules/utils");
 async function deploySchema(streamClient, appId, logger) {
-    const client = 'connect' in streamClient && 'release' in streamClient
-        ? await streamClient.connect()
-        : streamClient;
-    const releaseClient = 'release' in streamClient;
+    const isPool = streamClient?.totalCount !== undefined &&
+        streamClient?.idleCount !== undefined;
+    const client = isPool ? await streamClient.connect() : streamClient;
+    const releaseClient = isPool;
     try {
+        const schemaName = appId.replace(/[^a-zA-Z0-9_]/g, '_');
+        const tableName = `${schemaName}.streams`;
+        // First, check if tables already exist (no lock needed)
+        const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+        if (tablesExist) {
+            // Tables already exist, no need to acquire lock or create tables
+            return;
+        }
+        // Tables don't exist, need to acquire lock and create them
         const lockId = getAdvisoryLockId(appId);
         const lockResult = await client.query('SELECT pg_try_advisory_lock($1) AS locked', [lockId]);
         if (lockResult.rows[0].locked) {
-            await client.query('BEGIN');
-            const schemaName = appId.replace(/[^a-zA-Z0-9_]/g, '_');
-            const tableName = `${schemaName}.streams`;
-            await createTables(client, schemaName, tableName);
-            await createNotificationTriggers(client, schemaName, tableName);
-            await client.query('COMMIT');
-            await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
+            try {
+                await client.query('BEGIN');
+                // Double-check tables don't exist (race condition safety)
+                const tablesStillMissing = !(await checkIfTablesExist(client, schemaName, tableName));
+                if (tablesStillMissing) {
+                    await createTables(client, schemaName, tableName);
+                    await createNotificationTriggers(client, schemaName, tableName);
+                }
+                await client.query('COMMIT');
+            }
+            finally {
+                await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
+            }
         }
         else {
-            throw new Error('Table deployment in progress by another process.');
+            // Release the client before waiting (if it's a pool connection)
+            if (releaseClient && client.release) {
+                await client.release();
+            }
+            // Wait for the deploy process to complete
+            await waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger);
+            return; // Already released client, don't release again in finally
         }
     }
     catch (error) {
@@ -27,8 +50,13 @@ async function deploySchema(streamClient, appId, logger) {
         throw error;
     }
     finally {
-        if (releaseClient) {
-            await client.release();
+        if (releaseClient && client.release) {
+            try {
+                await client.release();
+            }
+            catch {
+                // Client may have been released already
+            }
         }
     }
 }
@@ -44,6 +72,45 @@ 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;
+}
+async function waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger) {
+    let retries = 0;
+    const maxRetries = Math.round(enums_1.HMSH_DEPLOYMENT_DELAY / enums_1.HMSH_DEPLOYMENT_PAUSE);
+    while (retries < maxRetries) {
+        await (0, utils_1.sleepFor)(enums_1.HMSH_DEPLOYMENT_PAUSE);
+        const isPool = streamClient?.totalCount !== undefined &&
+            streamClient?.idleCount !== undefined;
+        const client = isPool ? await streamClient.connect() : streamClient;
+        try {
+            // Check if tables exist directly (most efficient check)
+            const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+            if (tablesExist) {
+                // Tables now exist, deployment is complete
+                return;
+            }
+            // Fallback: check if the lock has been released (indicates completion)
+            const lockCheck = await client.query("SELECT NOT EXISTS (SELECT 1 FROM pg_locks WHERE locktype = 'advisory' AND objid = $1::bigint) AS unlocked", [lockId]);
+            if (lockCheck.rows[0].unlocked) {
+                // Lock has been released, tables should exist now
+                const tablesExistAfterLock = await checkIfTablesExist(client, schemaName, tableName);
+                if (tablesExistAfterLock) {
+                    return;
+                }
+            }
+        }
+        finally {
+            if (isPool && client.release) {
+                await client.release();
+            }
+        }
+        retries++;
+    }
+    logger.error('stream-table-create-timeout', { schemaName, tableName });
+    throw new Error('Timeout waiting for stream table creation');
+}
 async function createTables(client, schemaName, tableName) {
     await client.query(`CREATE SCHEMA IF NOT EXISTS ${schemaName};`);
     // Main table creation with partitions

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

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresSubService = void 0;
 const crypto_1 = __importDefault(require("crypto"));
+const enums_1 = require("../../../../modules/enums");
 const key_1 = require("../../../../modules/key");
 const index_1 = require("../../index");
 class PostgresSubService extends index_1.SubService {
@@ -180,8 +181,34 @@ class PostgresSubService extends index_1.SubService {
             appId,
             engineId: topic,
         });
+        let messageToPublish = message;
+        let payload = JSON.stringify(message);
+        // PostgreSQL NOTIFY has a payload limit. If job message exceeds limit,
+        // send a reference message instead - subscriber will fetch via getState.
+        if (payload.length > enums_1.HMSH_NOTIFY_PAYLOAD_LIMIT &&
+            message.type === 'job' &&
+            message.job?.metadata) {
+            const { jid, tpc, app, js } = message.job.metadata;
+            messageToPublish = {
+                type: 'job',
+                topic: message.topic,
+                job: {
+                    metadata: { jid, tpc, app, js },
+                    data: null,
+                },
+                _ref: true,
+            };
+            payload = JSON.stringify(messageToPublish);
+            this.logger.debug('postgres-publish-ref', {
+                originalKey,
+                safeKey,
+                originalSize: JSON.stringify(message).length,
+                refSize: payload.length,
+                jid,
+            });
+        }
         // Publish the message using the safe topic
-        const payload = JSON.stringify(message).replace(/'/g, "''");
+        payload = payload.replace(/'/g, "''");
         await this.storeClient.query(`NOTIFY "${safeKey}", '${payload}'`);
         this.logger.debug(`postgres-publish`, { originalKey, safeKey });
         return true;

package/build/types/quorum.d.ts

@@ -94,6 +94,8 @@ export interface JobMessage extends QuorumMessageBase {
     entity?: string;
     topic: string;
     job: JobOutput;
+    /** if true, job.data is null due to payload size - subscriber should fetch via getState */
+    _ref?: boolean;
 }
 export interface ThrottleMessage extends QuorumMessageBase {
     type: 'throttle';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",