@axinom/mosaic-db-common 0.24.3 → 0.25.0-rc.0

package/dist/common/types.d.ts

@@ -14,6 +14,7 @@ export interface Dict<T> {
  * ```
  */
 export interface DbLogger {
+    trace(message: string): void;
     debug(message: string): void;
     debug(error: Error): void;
     error(message: string): void;

package/dist/common/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,IAAI,GAAG;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;AAClD,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,IAAI,GAAG;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;AAClD,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC"}

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from './messaging';
 export * from './middleware';
 export * from './migrations';
 export * from './monitoring';
+export * from './replication';
 export * from './zapatos';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -22,5 +22,6 @@ __exportStar(require("./messaging"), exports);
 __exportStar(require("./middleware"), exports);
 __exportStar(require("./migrations"), exports);
 __exportStar(require("./monitoring"), exports);
+__exportStar(require("./replication"), exports);
 __exportStar(require("./zapatos"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,wCAAsB;AACtB,2CAAyB;AACzB,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,+CAA6B;AAC7B,+CAA6B;AAC7B,4CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,wCAAsB;AACtB,2CAAyB;AACzB,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,+CAA6B;AAC7B,+CAA6B;AAC7B,gDAA8B;AAC9B,4CAA0B"}

package/dist/replication/create-logical-replication-service.d.ts

@@ -0,0 +1,68 @@
+import { Pgoutput } from 'pg-logical-replication';
+import { DbLogger } from '../common';
+export type LogicalReplicationOperation = 'begin' | 'commit' | 'delete' | 'insert' | 'message' | 'origin' | 'relation' | 'truncate' | 'type' | 'update';
+export interface PgOutputScopedMessage {
+    operation: LogicalReplicationOperation;
+    tableName?: string;
+    schemaName?: string;
+    new?: Record<string, any>;
+    old?: Record<string, any>;
+}
+export interface LogicalReplicatonMessageHandlerParams {
+    scopedMessage: PgOutputScopedMessage;
+    fullMessage: Pgoutput.Message;
+}
+export type LogicalReplicationMessageHandler = (params: LogicalReplicatonMessageHandlerParams) => Promise<void>;
+/**
+ * Configuration object to set up a logical replication service.
+ */
+export interface LogicalReplicationServiceConfig {
+    connectionString: string;
+    /**
+     * Array of publication names for tables which changes would be watched.
+     * Must be defined beforehand on database level, e.g. using `ax_define.define_logical_replication_publication`
+     */
+    publicationNames: string[];
+    /**
+     * Name of the replication slot which will be streaming table changes.
+     * Must be defined beforehand on database level, e.g. using `ax_define.define_logical_replication_slot`
+     */
+    replicationSlotName: string;
+    /**
+     * Decides how to react to detected table changes.
+     */
+    messageHandler: LogicalReplicationMessageHandler;
+    /**
+     * An array of operations that will be handled and redirected to the
+     * `messageHandler`. Other operations will be skipped, each producing a TRACE
+     * log.
+     */
+    operationsToWatch?: LogicalReplicationOperation[];
+    /**
+     * Produces logs during the logical replication service runtime. If not
+     * passed, console logs are used instead.
+     */
+    logger?: DbLogger;
+}
+/**
+ * Creates a logical replication service and keeps it running until stopped.
+ * Watches the table changes based on passed publication names and replication
+ * slot, handling messages based on the passed message handler. By default
+ * watches the "insert", "update", and "delete" operations.
+ *
+ * In case of errors, the service will try to recover for 20 attempts with an
+ * incremental delay between attempts for a total of ~5 minutes. Any success
+ * would reset the error attempts counter. Each failure will be logged with an
+ * attempts counter value. If 5 minutes passes without any errors - the errors
+ * counter is reset. If the counter increases over 20 in
+ * the span of 5 minutes - causing error will be thrown to crash the process
+ * to trigger a service reload that might resolve the issue.
+ *
+ * @param config Connection and processing config for the logical replication
+ * service.
+ * @returns a function to stop the logical replication service.
+ */
+export declare const createLogicalReplicationService: ({ connectionString, publicationNames, replicationSlotName, messageHandler, operationsToWatch, logger: passedLogger, }: LogicalReplicationServiceConfig) => Promise<{
+    (): Promise<void>;
+}>;
+//# sourceMappingURL=create-logical-replication-service.d.ts.map

package/dist/replication/create-logical-replication-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-logical-replication-service.d.ts","sourceRoot":"","sources":["../../src/replication/create-logical-replication-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAET,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAKrC,MAAM,MAAM,2BAA2B,GACnC,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,UAAU,GACV,UAAU,GACV,MAAM,GACN,QAAQ,CAAC;AAEb,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,2BAA2B,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,qCAAqC;IACpD,aAAa,EAAE,qBAAqB,CAAC;IACrC,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC;CAC/B;AAED,MAAM,MAAM,gCAAgC,GAAG,CAC7C,MAAM,EAAE,qCAAqC,KAC1C,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAI9C,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,cAAc,EAAE,gCAAgC,CAAC;IAEjD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,2BAA2B,EAAE,CAAC;IAClD;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAmBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,+BAA+B,0HAOzC,+BAA+B,KAAG,QAAQ;IAAE,IAAI,QAAQ,IAAI,CAAC,CAAA;CAAE,CAmGjE,CAAC"}

package/dist/replication/create-logical-replication-service.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogicalReplicationService = void 0;
+const pg_logical_replication_1 = require("pg-logical-replication");
+const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+const getScopedMessage = (message, operationsToWatch) => {
+    if (!operationsToWatch.includes(message.tag)) {
+        return undefined;
+    }
+    return {
+        operation: message.tag,
+        tableName: 'relation' in message ? message.relation.name : undefined,
+        schemaName: 'relation' in message ? message.relation.schema : undefined,
+        new: 'new' in message ? message.new : undefined,
+        old: 'old' in message && message.old ? message.old : undefined,
+    };
+};
+/**
+ * Creates a logical replication service and keeps it running until stopped.
+ * Watches the table changes based on passed publication names and replication
+ * slot, handling messages based on the passed message handler. By default
+ * watches the "insert", "update", and "delete" operations.
+ *
+ * In case of errors, the service will try to recover for 20 attempts with an
+ * incremental delay between attempts for a total of ~5 minutes. Any success
+ * would reset the error attempts counter. Each failure will be logged with an
+ * attempts counter value. If 5 minutes passes without any errors - the errors
+ * counter is reset. If the counter increases over 20 in
+ * the span of 5 minutes - causing error will be thrown to crash the process
+ * to trigger a service reload that might resolve the issue.
+ *
+ * @param config Connection and processing config for the logical replication
+ * service.
+ * @returns a function to stop the logical replication service.
+ */
+const createLogicalReplicationService = async ({ connectionString, publicationNames, replicationSlotName, messageHandler, operationsToWatch = ['insert', 'update', 'delete'], logger: passedLogger, }) => {
+    if (operationsToWatch.length === 0) {
+        throw new Error('Unable to start the logical replication service when operationsToWatch is an empty array.');
+    }
+    const logger = passedLogger !== null && passedLogger !== void 0 ? passedLogger : console;
+    const plugin = new pg_logical_replication_1.PgoutputPlugin({ protoVersion: 1, publicationNames });
+    let service;
+    let stopped = false;
+    let failedAttempts = 0;
+    let failedAttemptsResetTimer = undefined;
+    // Run the service in an endless background loop until it gets stopped
+    (async () => {
+        while (!stopped) {
+            try {
+                await new Promise((resolve, reject) => {
+                    let heartbeatAckTimer = undefined;
+                    service = new pg_logical_replication_1.LogicalReplicationService({ connectionString }, { acknowledge: { auto: false, timeoutSeconds: 0 } });
+                    service.on('data', async (lsn, message) => {
+                        try {
+                            const scopedMessage = getScopedMessage(message, operationsToWatch);
+                            if (scopedMessage) {
+                                await messageHandler({ scopedMessage, fullMessage: message });
+                            }
+                            failedAttempts = 0;
+                            clearTimeout(failedAttemptsResetTimer);
+                            clearTimeout(heartbeatAckTimer);
+                            await service.acknowledge(lsn);
+                        }
+                        catch (error) {
+                            service.emit('error', error);
+                        }
+                    });
+                    service.on('error', async (err) => {
+                        service.removeAllListeners();
+                        await service.stop();
+                        reject(err);
+                    });
+                    service.on('heartbeat', async (lsn, _timestamp, shouldRespond) => {
+                        if (shouldRespond) {
+                            heartbeatAckTimer = setTimeout(async () => {
+                                logger.trace(`${lsn}: acknowledged heartbeat`);
+                                await service.acknowledge(lsn);
+                            }, 5000);
+                        }
+                    });
+                    service
+                        .subscribe(plugin, replicationSlotName)
+                        .then(() => resolve(true))
+                        .catch(async (err) => {
+                        service.removeAllListeners();
+                        await service.stop();
+                        reject(err);
+                    });
+                });
+            }
+            catch (err) {
+                failedAttempts++;
+                if (failedAttempts > 20) {
+                    throw err;
+                }
+                logger.error(err, `Logical replication service failure has occurred. (Attempt ${failedAttempts})`);
+                await sleep(1500 * failedAttempts);
+                clearTimeout(failedAttemptsResetTimer);
+                failedAttemptsResetTimer = setTimeout(async () => {
+                    logger.trace(`No errors have occurred within 5 minutes. Resetting failures counter after ${failedAttempts} failure(s).`);
+                    failedAttempts = 0;
+                }, 300000);
+            }
+        }
+    })();
+    logger.debug(`Started the logical replication service to watch the database operations (${operationsToWatch.join(', ')}) on table(s) associated with the following publication(s): ${publicationNames.join(', ')}`);
+    return async () => {
+        logger.debug('Shutting down the logical replication service.');
+        stopped = true;
+        service === null || service === void 0 ? void 0 : service.removeAllListeners();
+        service === null || service === void 0 ? void 0 : service.stop().catch((e) => logger.error(e, 'Error on logical replicationservice shutdown.'));
+    };
+};
+exports.createLogicalReplicationService = createLogicalReplicationService;
+//# sourceMappingURL=create-logical-replication-service.js.map

package/dist/replication/create-logical-replication-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-logical-replication-service.js","sourceRoot":"","sources":["../../src/replication/create-logical-replication-service.ts"],"names":[],"mappings":"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"}

package/dist/replication/index.d.ts

@@ -0,0 +1,2 @@
+export * from './create-logical-replication-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/replication/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/replication/index.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC"}

package/dist/replication/index.js

@@ -0,0 +1,18 @@
+"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("./create-logical-replication-service"), exports);
+//# sourceMappingURL=index.js.map

package/dist/replication/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/replication/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uEAAqD"}

package/migrations/define/define-functions.sql

@@ -1104,3 +1104,61 @@ BEGIN
     RETURN counter;
 END;
 $$;
+
+/*-snippet
+{
+  "body": [
+    "BEGIN;",
+    "  SELECT ax_define.define_logical_replication_publication(",
+    "    '${1:publication_name_or_placeholder}',",
+    "    ARRAY['${2:table_name_one}', '${3:table_name_two}', '${4:table_name_three}'],",
+    "    '${5:app_public}');",
+    "COMMIT;"
+  ],
+  "description": [
+    "Defines a publication for multiple tables.\n",
+    "REPLICA IDENTITY FULL is set for each passed table.\n",
+    "By default, sets the publish parameter of publication to `insert,update,delete`, but this can be overridden by the 4-th parameter.\n",
+    "The result of a call is committed right away to enable adding a replication slot in context of the same migration."
+  ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_define.define_logical_replication_publication(
+  publicationName text, 
+  tableNames text[], 
+  schemaName text,
+  publicationOperations TEXT DEFAULT 'insert,update,delete'::text) RETURNS void AS $$
+DECLARE
+  i integer;
+  tableName text;
+BEGIN
+  EXECUTE 'DROP PUBLICATION IF EXISTS ' || publicationName;
+  EXECUTE 'CREATE PUBLICATION ' || publicationName || ' WITH (publish = "' || publicationOperations || '");';
+  FOR i IN 1..array_length(tableNames, 1) LOOP
+    tableName := tableNames[i];
+    EXECUTE 'ALTER PUBLICATION ' || publicationName || ' ADD TABLE ' || schemaName || '.' ||  tableName || ';';
+    EXECUTE 'ALTER TABLE ' || schemaName || '.' ||  tableName || ' REPLICA IDENTITY full;';
+  END LOOP;
+END;
+$$ LANGUAGE plpgsql;
+
+
+/*-snippet
+{
+  "body": [
+    "SELECT ax_define.define_logical_replication_slot('${1:replication_slot_name_or_placeholder}')"
+  ],
+  "description": [
+    "An idempotent wrapper for pg_create_logical_replication_slot.\n",
+    "Plugin used by default is `pgoutput`. It can be overridden using the second parameter."
+  ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_define.define_logical_replication_slot(replicationSlotName text, pluginName TEXT DEFAULT 'pgoutput'::text) RETURNS void AS $$
+BEGIN
+  IF NOT EXISTS(SELECT pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name = replicationSlotName)
+  THEN
+    PERFORM pg_create_logical_replication_slot(replicationSlotName, pluginName);
+  END IF;
+END;
+$$ LANGUAGE plpgsql;

package/migrations/snippets/custom.code-snippets

@@ -251,5 +251,23 @@
       "Make sure the dropped value is not used in other tables.\n",
       "This snippet has a simplified migration sample that might require adjustments."
     ]
+  },
+  "Define Logical Replication For Tables (Ax Custom)": {
+    "prefix": "ax-define-logical-replication-for-tables",
+    "body": [
+      "BEGIN;",
+      "  SELECT ax_define.define_logical_replication_publication(",
+      "    '${1:publication_name_or_placeholder}',",
+      "    ARRAY['${2:table_name_one}', '${3:table_name_two}', '${4:table_name_three}'],",
+      "    '${5:app_public}');",
+      "COMMIT;",
+      "SELECT ax_define.define_logical_replication_slot('${6:replication_slot_name_or_placeholder}')"
+    ],
+    "description": [
+      "Defines a publication and a replication slot for multiple tables.\n",
+      "See snippets for individual define functions for more details.\n",
+      "The publications are committed right away to enable adding a replication slot in context of the same migration."
+    ],
+    "scope": "sql"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axinom/mosaic-db-common",
-  "version": "0.24.3",
+  "version": "0.25.0-rc.0",
   "description": "This library encapsulates database-related functionality to develop Mosaic based services.",
   "author": "Axinom",
   "license": "PROPRIETARY",
@@ -33,6 +33,7 @@
     "express": "^4.17.1",
     "graphile-migrate": "^1.4.0",
     "pg": "^8.5.1",
+    "pg-logical-replication": "^2.0.3",
     "prom-client": "^13.2.0",
     "readdirp": "^3.4.0",
     "yargs": "^16.2.0",
@@ -51,5 +52,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "bfef034fdb70100b54e35c441f75301d2b4585fd"
+  "gitHead": "d99f62328986c3250b0491a0b8b5f55d89b66840"
 }

package/src/common/types.ts

@@ -16,6 +16,7 @@ export interface Dict<T> {
  * ```
  */
 export interface DbLogger {
+  trace(message: string): void;
   debug(message: string): void;
   debug(error: Error): void;
   error(message: string): void;

package/src/index.ts

@@ -6,4 +6,5 @@ export * from './messaging';
 export * from './middleware';
 export * from './migrations';
 export * from './monitoring';
+export * from './replication';
 export * from './zapatos';

package/src/replication/create-logical-replication-service.spec.ts

@@ -0,0 +1,312 @@
+import { Pgoutput } from 'pg-logical-replication';
+import {
+  LogicalReplicationMessageHandler,
+  createLogicalReplicationService,
+} from './create-logical-replication-service';
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((res) => setTimeout(res, ms));
+
+const repService: {
+  // We expose the callback methods that are normally called from the "on"
+  // "data/error/heartbeat" emitted events to be able to manually call them.
+  handleData?: (lsn: string, log: any) => Promise<void> | void;
+  handleError?: (err: Error) => void;
+  handleHeartbeat?: (
+    lsn: string,
+    timestamp: number,
+    shouldRespond: boolean,
+  ) => Promise<void> | void;
+  acknowledge?: jest.Mock<any, any>;
+  stop?: jest.Mock<any, any>;
+} = {};
+
+jest.mock('pg-logical-replication', () => {
+  return {
+    ...jest.requireActual('pg-logical-replication'),
+    LogicalReplicationService: jest.fn().mockImplementation(() => {
+      const lrs = {
+        handleData: undefined,
+        handleError: undefined,
+        handleHeartbeat: undefined,
+        on: (event: 'data' | 'error' | 'heartbeat', listener: any) => {
+          switch (event) {
+            case 'data':
+              repService.handleData = listener;
+              break;
+            case 'error':
+              repService.handleError = listener;
+              break;
+            case 'heartbeat':
+              repService.handleHeartbeat = listener;
+              break;
+          }
+        },
+        acknowledge: jest.fn(),
+        removeAllListeners: jest.fn(),
+        emit: jest.fn(),
+        stop: jest.fn(() => Promise.resolve()),
+        subscribe: () =>
+          new Promise(() => {
+            /** never return */
+          }),
+        isStop: () => false,
+      };
+      repService.acknowledge = lrs.acknowledge;
+      repService.stop = lrs.stop;
+      return lrs;
+    }),
+  };
+});
+
+const relation: Pgoutput.MessageRelation = {
+  tag: 'relation',
+  relationOid: 1,
+  schema: 'test_schema',
+  name: 'test_table',
+  replicaIdentity: 'default',
+  columns: [
+    {
+      name: 'id',
+      flags: 0,
+      typeOid: 23,
+      typeMod: -1,
+      typeSchema: 'pg_catalog',
+      typeName: 'int4',
+      parser: (raw: any) => raw,
+    },
+    {
+      name: 'name',
+      flags: 0,
+      typeOid: 25,
+      typeMod: -1,
+      typeSchema: 'pg_catalog',
+      typeName: 'text',
+      parser: (raw: any) => raw,
+    },
+  ],
+  keyColumns: ['id'],
+};
+
+describe('createLogicalReplicationService', () => {
+  beforeEach(() => {
+    repService.handleData = undefined;
+    repService.handleError = undefined;
+    repService.handleHeartbeat = undefined;
+    repService.acknowledge = undefined;
+    repService.stop = undefined;
+  });
+
+  it('initialization throws an error if empty operations array is passed', async () => {
+    // Act
+    try {
+      await createLogicalReplicationService({
+        connectionString: 'test-valid-connection-string',
+        publicationNames: ['test_publication'],
+        replicationSlotName: 'test_slot',
+        messageHandler: jest.fn(),
+        operationsToWatch: [],
+      });
+    } catch (error) {
+      // Assert
+      // eslint-disable-next-line jest/no-conditional-expect
+      expect((error as Error).message).toBe(
+        'Unable to start the logical replication service when operationsToWatch is an empty array.',
+      );
+    }
+  });
+
+  it('should call messageHandler and acknowledge the message when no errors are thrown', async () => {
+    // Arrange
+    const messageHandler: LogicalReplicationMessageHandler = jest.fn();
+    const cleanup = await createLogicalReplicationService({
+      connectionString: 'test-valid-connection-string',
+      publicationNames: ['test_publication'],
+      replicationSlotName: 'test_slot',
+      messageHandler,
+    });
+    expect(repService.handleData).toBeDefined();
+    const fullMessage = {
+      tag: 'insert',
+      relation,
+      old: {
+        id: 'test_id',
+        aggregate_type: 'test_type_old',
+        aggregate_id: 'test_aggregate_id_old',
+        event_type: 'test_event_type_old',
+        payload: { result: 'in_progress' },
+        created_at: new Date('2023-01-18T21:02:27.000Z'),
+      },
+      new: {
+        id: 'test_id',
+        aggregate_type: 'test_type',
+        aggregate_id: 'test_aggregate_id',
+        event_type: 'test_event_type',
+        payload: { result: 'success' },
+        created_at: new Date('2023-01-18T21:02:27.000Z'),
+      },
+    };
+
+    // Act
+    await repService.handleData!('0/00000001', fullMessage);
+
+    // Assert
+    expect(repService.handleError).toBeDefined();
+    expect(repService.handleHeartbeat).toBeDefined();
+    expect(messageHandler).toHaveBeenCalledWith({
+      scopedMessage: {
+        new: fullMessage.new,
+        old: fullMessage.old,
+        operation: 'insert',
+        schemaName: 'test_schema',
+        tableName: 'test_table',
+      },
+      fullMessage,
+    });
+    expect(repService.acknowledge).toHaveBeenCalledWith('0/00000001');
+    expect(repService.stop).not.toHaveBeenCalled();
+    await cleanup();
+    expect(repService.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('should call messageHandler with minimal scoped message and acknowledge the message when no errors are thrown', async () => {
+    // Arrange
+    const messageHandler: LogicalReplicationMessageHandler = jest.fn();
+    const cleanup = await createLogicalReplicationService({
+      connectionString: 'test-valid-connection-string',
+      publicationNames: ['test_publication'],
+      replicationSlotName: 'test_slot',
+      messageHandler,
+    });
+    expect(repService.handleData).toBeDefined();
+    const fullMessage = {
+      tag: 'insert',
+      relation: {
+        tag: 'relation',
+      },
+      old: null,
+      new: undefined,
+    };
+
+    // Act
+    await repService.handleData!('0/00000001', fullMessage);
+
+    // Assert
+    expect(repService.handleError).toBeDefined();
+    expect(repService.handleHeartbeat).toBeDefined();
+    expect(messageHandler).toHaveBeenCalledWith({
+      scopedMessage: {
+        new: undefined,
+        old: undefined,
+        operation: 'insert',
+        schemaName: undefined,
+        tableName: undefined,
+      },
+      fullMessage,
+    });
+    expect(repService.acknowledge).toHaveBeenCalledWith('0/00000001');
+    expect(repService.stop).not.toHaveBeenCalled();
+    await cleanup();
+    expect(repService.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('should call messageHandler but not acknowledge the message when an error is thrown', async () => {
+    // Arrange
+    const testError = new Error('Transient error');
+    const cleanup = await createLogicalReplicationService({
+      connectionString: 'test-valid-connection-string',
+      publicationNames: ['test_publication'],
+      replicationSlotName: 'test_slot',
+      messageHandler: async () => {
+        throw testError;
+      },
+    });
+
+    expect(repService.handleData).toBeDefined();
+
+    // Act
+    await repService.handleData!('0/00000001', {
+      tag: 'insert',
+      relation,
+      new: {
+        id: 'test_id',
+        aggregate_type: 'test_type',
+        aggregate_id: 'test_aggregate_id',
+        event_type: 'test_event_type',
+        payload: { result: 'success' },
+        created_at: new Date('2023-01-18T21:02:27.000Z'),
+      },
+    });
+
+    // Assert
+    expect(repService.handleError).toBeDefined();
+    expect(repService.handleHeartbeat).toBeDefined();
+    expect(repService.acknowledge).not.toHaveBeenCalled();
+    expect(repService.stop).not.toHaveBeenCalled();
+    await cleanup();
+    expect(repService.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('A heartbeat should be acknowledged after 5 seconds', async () => {
+    // Arrange
+    const cleanup = await createLogicalReplicationService({
+      connectionString: 'test-valid-connection-string',
+      publicationNames: ['test_publication'],
+      replicationSlotName: 'test_slot',
+      messageHandler: jest.fn(),
+    });
+    expect(repService.handleHeartbeat).toBeDefined();
+
+    // Act
+    await repService.handleHeartbeat!('0/00000001', 123, true);
+
+    // Assert
+    expect(repService.handleData).toBeDefined();
+    expect(repService.handleError).toBeDefined();
+    expect(repService.acknowledge).not.toHaveBeenCalled();
+    await sleep(4000);
+    expect(repService.acknowledge).not.toHaveBeenCalled();
+    await sleep(1010);
+    expect(repService.acknowledge).toHaveBeenCalled();
+    expect(repService.stop).not.toHaveBeenCalled();
+    await cleanup();
+    expect(repService.stop).toHaveBeenCalledTimes(1);
+  }, 10_000);
+
+  it('A heartbeat should not be acknowledged after 5 seconds when a message acknowledgement comes in between', async () => {
+    // Arrange
+    const cleanup = await createLogicalReplicationService({
+      connectionString: 'test-valid-connection-string',
+      publicationNames: ['test_publication'],
+      replicationSlotName: 'test_slot',
+      messageHandler: jest.fn(),
+    });
+    expect(repService.handleData).toBeDefined();
+    expect(repService.handleHeartbeat).toBeDefined();
+
+    // Act
+    await repService.handleHeartbeat!('0/00000001', 123, true);
+    await sleep(1000);
+    await repService.handleData!('0/00000002', {
+      tag: 'insert',
+      relation,
+      new: {
+        id: 'test_id',
+        aggregate_type: 'test_type',
+        aggregate_id: 'test_aggregate_id',
+        event_type: 'test_event_type',
+        payload: { result: 'success' },
+        created_at: new Date('2023-01-18T21:02:27.000Z'),
+      },
+    });
+
+    // Assert
+    expect(repService.handleError).toBeDefined();
+    expect(repService.acknowledge).toHaveBeenCalledWith('0/00000002');
+    await sleep(4010);
+    expect(repService.acknowledge).toHaveBeenCalledTimes(1);
+    expect(repService.stop).not.toHaveBeenCalled();
+    await cleanup();
+    expect(repService.stop).toHaveBeenCalledTimes(1);
+  }, 10_000);
+});

package/src/replication/create-logical-replication-service.ts

@@ -0,0 +1,220 @@
+import {
+  LogicalReplicationService,
+  Pgoutput,
+  PgoutputPlugin,
+} from 'pg-logical-replication';
+import { DbLogger } from '../common';
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((res) => setTimeout(res, ms));
+
+export type LogicalReplicationOperation =
+  | 'begin'
+  | 'commit'
+  | 'delete'
+  | 'insert'
+  | 'message'
+  | 'origin'
+  | 'relation'
+  | 'truncate'
+  | 'type'
+  | 'update';
+
+export interface PgOutputScopedMessage {
+  operation: LogicalReplicationOperation;
+  tableName?: string;
+  schemaName?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  new?: Record<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  old?: Record<string, any>;
+}
+
+export interface LogicalReplicatonMessageHandlerParams {
+  scopedMessage: PgOutputScopedMessage;
+  fullMessage: Pgoutput.Message;
+}
+
+export type LogicalReplicationMessageHandler = (
+  params: LogicalReplicatonMessageHandlerParams,
+) => Promise<void>;
+
+/**
+ * Configuration object to set up a logical replication service.
+ */
+export interface LogicalReplicationServiceConfig {
+  /*
+    Database connection string for the user with `REPLICATION` role
+   */
+  connectionString: string;
+  /**
+   * Array of publication names for tables which changes would be watched.
+   * Must be defined beforehand on database level, e.g. using `ax_define.define_logical_replication_publication`
+   */
+  publicationNames: string[];
+  /**
+   * Name of the replication slot which will be streaming table changes.
+   * Must be defined beforehand on database level, e.g. using `ax_define.define_logical_replication_slot`
+   */
+  replicationSlotName: string;
+
+  /**
+   * Decides how to react to detected table changes.
+   */
+  messageHandler: LogicalReplicationMessageHandler;
+
+  /**
+   * An array of operations that will be handled and redirected to the
+   * `messageHandler`. Other operations will be skipped, each producing a TRACE
+   * log.
+   */
+  operationsToWatch?: LogicalReplicationOperation[];
+  /**
+   * Produces logs during the logical replication service runtime. If not
+   * passed, console logs are used instead.
+   */
+  logger?: DbLogger;
+}
+
+const getScopedMessage = (
+  message: Pgoutput.Message,
+  operationsToWatch: string[],
+): PgOutputScopedMessage | undefined => {
+  if (!operationsToWatch.includes(message.tag)) {
+    return undefined;
+  }
+
+  return {
+    operation: message.tag,
+    tableName: 'relation' in message ? message.relation.name : undefined,
+    schemaName: 'relation' in message ? message.relation.schema : undefined,
+    new: 'new' in message ? message.new : undefined,
+    old: 'old' in message && message.old ? message.old : undefined,
+  };
+};
+
+/**
+ * Creates a logical replication service and keeps it running until stopped.
+ * Watches the table changes based on passed publication names and replication
+ * slot, handling messages based on the passed message handler. By default
+ * watches the "insert", "update", and "delete" operations.
+ *
+ * In case of errors, the service will try to recover for 20 attempts with an
+ * incremental delay between attempts for a total of ~5 minutes. Any success
+ * would reset the error attempts counter. Each failure will be logged with an
+ * attempts counter value. If 5 minutes passes without any errors - the errors
+ * counter is reset. If the counter increases over 20 in
+ * the span of 5 minutes - causing error will be thrown to crash the process
+ * to trigger a service reload that might resolve the issue.
+ *
+ * @param config Connection and processing config for the logical replication
+ * service.
+ * @returns a function to stop the logical replication service.
+ */
+export const createLogicalReplicationService = async ({
+  connectionString,
+  publicationNames,
+  replicationSlotName,
+  messageHandler,
+  operationsToWatch = ['insert', 'update', 'delete'],
+  logger: passedLogger,
+}: LogicalReplicationServiceConfig): Promise<{ (): Promise<void> }> => {
+  if (operationsToWatch.length === 0) {
+    throw new Error(
+      'Unable to start the logical replication service when operationsToWatch is an empty array.',
+    );
+  }
+
+  const logger = passedLogger ?? console;
+  const plugin = new PgoutputPlugin({ protoVersion: 1, publicationNames });
+  let service: LogicalReplicationService;
+  let stopped = false;
+  let failedAttempts = 0;
+  let failedAttemptsResetTimer: NodeJS.Timeout | undefined = undefined;
+  // Run the service in an endless background loop until it gets stopped
+  (async () => {
+    while (!stopped) {
+      try {
+        await new Promise((resolve, reject) => {
+          let heartbeatAckTimer: NodeJS.Timeout | undefined = undefined;
+          service = new LogicalReplicationService(
+            { connectionString },
+            { acknowledge: { auto: false, timeoutSeconds: 0 } },
+          );
+          service.on('data', async (lsn: string, message: Pgoutput.Message) => {
+            try {
+              const scopedMessage = getScopedMessage(
+                message,
+                operationsToWatch,
+              );
+              if (scopedMessage) {
+                await messageHandler({ scopedMessage, fullMessage: message });
+              }
+              failedAttempts = 0;
+              clearTimeout(failedAttemptsResetTimer);
+              clearTimeout(heartbeatAckTimer);
+              await service.acknowledge(lsn);
+            } catch (error) {
+              service.emit('error', error);
+            }
+          });
+          service.on('error', async (err: Error) => {
+            service.removeAllListeners();
+            await service.stop();
+            reject(err);
+          });
+          service.on('heartbeat', async (lsn, _timestamp, shouldRespond) => {
+            if (shouldRespond) {
+              heartbeatAckTimer = setTimeout(async () => {
+                logger.trace(`${lsn}: acknowledged heartbeat`);
+                await service.acknowledge(lsn);
+              }, 5000);
+            }
+          });
+          service
+            .subscribe(plugin, replicationSlotName)
+            .then(() => resolve(true))
+            .catch(async (err) => {
+              service.removeAllListeners();
+              await service.stop();
+              reject(err);
+            });
+        });
+      } catch (err) {
+        failedAttempts++;
+        if (failedAttempts > 20) {
+          throw err;
+        }
+        logger.error(
+          err as Error,
+          `Logical replication service failure has occurred. (Attempt ${failedAttempts})`,
+        );
+        await sleep(1500 * failedAttempts);
+        clearTimeout(failedAttemptsResetTimer);
+        failedAttemptsResetTimer = setTimeout(async () => {
+          logger.trace(
+            `No errors have occurred within 5 minutes. Resetting failures counter after ${failedAttempts} failure(s).`,
+          );
+          failedAttempts = 0;
+        }, 300000);
+      }
+    }
+  })();
+  logger.debug(
+    `Started the logical replication service to watch the database operations (${operationsToWatch.join(
+      ', ',
+    )}) on table(s) associated with the following publication(s): ${publicationNames.join(
+      ', ',
+    )}`,
+  );
+  return async () => {
+    logger.debug('Shutting down the logical replication service.');
+    stopped = true;
+    service?.removeAllListeners();
+    service
+      ?.stop()
+      .catch((e) =>
+        logger.error(e, 'Error on logical replicationservice shutdown.'),
+      );
+  };
+};

package/src/replication/index.ts

@@ -0,0 +1 @@
+export * from './create-logical-replication-service';