pg-interleave 0.4.0 → 0.6.0

package/dist/demo.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/demo.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const pg_1 = require("pg");
+const index_1 = require("./index");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runDemo() {
+    const chaos = new index_1.PgInterleaveClient("http://127.0.0.1:9090");
+    const connStr = "postgres://postgres:postgres@127.0.0.1:5433/postgres";
+    console.log("\x1b[36m[pg-interleave]\x1b[0m Resetting proxy control plane...");
+    await chaos.reset();
+    const observer = new pg_1.Client({ connectionString: connStr });
+    const workerA = new pg_1.Client({ connectionString: connStr });
+    await observer.connect();
+    await workerA.connect();
+    console.log("\x1b[36m[setup]\x1b[0m Initializing accounts (id=1, balance=100)...");
+    await observer.query(`
+    DROP TABLE IF EXISTS accounts CASCADE;
+    CREATE TABLE accounts (id int PRIMARY KEY, balance int NOT NULL);
+    INSERT INTO accounts VALUES (1, 100);
+  `);
+    console.log("\x1b[33m[barrier]\x1b[0m Arming barrier on: \x1b[1mUPDATE accounts\x1b[0m");
+    const barrier = await chaos.intercept({
+        client: workerA,
+        onQueryMatch: /UPDATE accounts/,
+    });
+    console.log("\x1b[32m[workerA]\x1b[0m Dispatching: UPDATE accounts SET balance = balance - 50 WHERE id = 1");
+    const pendingUpdate = workerA.query("UPDATE accounts SET balance = balance - 50 WHERE id = 1");
+    console.log("\x1b[33m[barrier]\x1b[0m Waiting for query to freeze in proxy pipeline...");
+    await barrier.wait();
+    console.log("\x1b[31m[proxy]\x1b[0m \x1b[1mPAUSED!\x1b[0m PostgreSQL has NOT seen the query yet.");
+    await sleep(1500);
+    const beforeResume = await observer.query("SELECT balance FROM accounts WHERE id = 1");
+    console.log(`\x1b[35m[observer]\x1b[0m Reading balance during freeze: \x1b[1m$${beforeResume.rows[0].balance}\x1b[0m`);
+    await sleep(1500);
+    console.log("\x1b[33m[barrier]\x1b[0m Releasing barrier: barrier.resume()...");
+    await barrier.resume();
+    await pendingUpdate;
+    console.log("\x1b[32m[workerA]\x1b[0m UPDATE finished successfully.");
+    const afterResume = await observer.query("SELECT balance FROM accounts WHERE id = 1");
+    console.log(`\x1b[35m[observer]\x1b[0m Final balance: \x1b[1m$${afterResume.rows[0].balance}\x1b[0m`);
+    await observer.end();
+    await workerA.end();
+}
+runDemo().catch(console.error);

package/dist/index.d.ts

@@ -1,11 +1,19 @@
 import type { Client } from "pg";
+export type SqlOperation = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "select" | "insert" | "update" | "delete";
+export interface AstSelector {
+    operation?: SqlOperation;
+    table?: string;
+}
+export type BarrierAction = "PAUSE_BEFORE_QUERY" | "PAUSE_AFTER_RESPONSE" | "pause_before_query" | "pause_after_response";
+export type ParamValue = string | number | boolean | null;
 export interface InterceptOptions {
     client?: Client;
     clientPid?: number;
     sessionTag?: string;
-    onQueryMatch: string | RegExp;
-    withParams?: Array<string | number | boolean | null>;
-    action?: "PAUSE_BEFORE_QUERY" | "PAUSE_AFTER_RESPONSE" | "pause_before_query" | "pause_after_response";
+    onQueryMatch?: RegExp | string;
+    ast?: AstSelector;
+    withParams?: (ParamValue | "*")[];
+    action?: BarrierAction;
     times?: number;
 }
 export declare class BarrierHandle {
@@ -18,9 +26,6 @@ export declare class BarrierHandle {
 export declare class PgInterleaveClient {
     private readonly controlUrl;
     constructor(controlUrl?: string);
-    /**
-     * Appends session routing comment to an SQL query for connection pool compatibility
-     */
     static tag(sql: string, sessionTag: string): string;
     reset(): Promise<void>;
     resumeNext(): Promise<{
@@ -32,6 +37,7 @@ export declare class PgInterleaveClient {
     getPid(client: Client): Promise<number>;
     intercept(options: InterceptOptions): Promise<BarrierHandle>;
     injectTornCommit(client: Client, times?: number): Promise<void>;
+    flushTrace(): Promise<void>;
     injectDeadlock(options: {
         client?: Client;
         clientPid?: number;

package/dist/index.js

@@ -42,9 +42,6 @@ class PgInterleaveClient {
     constructor(controlUrl = "http://127.0.0.1:9090") {
         this.controlUrl = controlUrl;
     }
-    /**
-     * Appends session routing comment to an SQL query for connection pool compatibility
-     */
     static tag(sql, sessionTag) {
         return `/* interleave: session=${sessionTag} */ ${sql}`;
     }
@@ -83,34 +80,35 @@ class PgInterleaveClient {
         return res.rows[0].pid;
     }
     async intercept(options) {
+        if (!options.onQueryMatch && !options.ast) {
+            throw new Error("Either 'onQueryMatch' or 'ast' selector must be provided");
+        }
         let pid = options.clientPid;
         if (!pid && options.client) {
             pid = await this.getPid(options.client);
         }
-        const pattern = typeof options.onQueryMatch === "string"
-            ? options.onQueryMatch
-            : options.onQueryMatch.source;
-        const action = options.action
-            ? options.action.toLowerCase()
-            : "pause_before_query";
-        const serializedParams = options.withParams !== undefined
-            ? options.withParams.map((p) => (p === null || p === undefined ? null : String(p)))
-            : undefined;
-        const body = {
-            query_pattern: pattern,
-            action,
+        const payload = {
+            targetPid: pid,
+            sessionTag: options.sessionTag,
+            action: options.action ?? "pause_before_query",
             times: options.times ?? 1,
         };
-        if (pid !== undefined)
-            body.target_pid = pid;
-        if (options.sessionTag !== undefined)
-            body.session_tag = options.sessionTag;
-        if (serializedParams !== undefined)
-            body.with_params = serializedParams;
+        if (options.onQueryMatch) {
+            payload.queryPattern =
+                typeof options.onQueryMatch === "string"
+                    ? options.onQueryMatch
+                    : options.onQueryMatch.source;
+        }
+        if (options.ast) {
+            payload.ast = options.ast;
+        }
+        if (options.withParams) {
+            payload.withParams = options.withParams.map((p) => typeof p === "number" ? String(p) : p);
+        }
         const res = await fetch(`${this.controlUrl}/intercept`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
+            body: JSON.stringify(payload),
         });
         if (!res.ok) {
             const errBody = await res.text();
@@ -134,6 +132,14 @@ class PgInterleaveClient {
             throw new Error(`Failed to inject torn commit: HTTP ${res.status}`);
         }
     }
+    async flushTrace() {
+        const res = await fetch(`${this.controlUrl}/flush-trace`, {
+            method: "POST",
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to flush trace: HTTP ${res.status}`);
+        }
+    }
     async injectDeadlock(options) {
         let pid = options.clientPid;
         if (!pid && options.client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-interleave",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Deterministic PostgreSQL wire-protocol proxy client for concurrency and chaos testing",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",