pg-interleave 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { Client } from "pg";
+export interface InterceptOptions {
+    client?: Client;
+    clientPid?: number;
+    sessionTag?: string;
+    onQueryMatch: string | RegExp;
+    action?: "PAUSE_BEFORE_QUERY" | "PAUSE_AFTER_RESPONSE" | "pause_before_query" | "pause_after_response";
+    times?: number;
+}
+export declare class BarrierHandle {
+    private readonly controlUrl;
+    readonly barrierId?: string | undefined;
+    constructor(controlUrl: string, barrierId?: string | undefined);
+    wait(timeoutMs?: number): Promise<void>;
+    resume(): Promise<void>;
+}
+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>;
+    hasTimeouts(): Promise<boolean>;
+    getPid(client: Client): Promise<number>;
+    intercept(options: InterceptOptions): Promise<BarrierHandle>;
+    injectTornCommit(client: Client, times?: number): Promise<void>;
+    injectDeadlock(options: {
+        client?: Client;
+        clientPid?: number;
+        onQueryMatch: string | RegExp;
+        times?: number;
+    }): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgInterleaveClient = exports.BarrierHandle = void 0;
+class BarrierHandle {
+    controlUrl;
+    barrierId;
+    constructor(controlUrl, barrierId) {
+        this.controlUrl = controlUrl;
+        this.barrierId = barrierId;
+    }
+    async wait(timeoutMs = 5000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const res = await fetch(`${this.controlUrl}/barriers`);
+            if (res.ok) {
+                const barriers = (await res.json());
+                if (this.barrierId) {
+                    if (barriers.includes(this.barrierId))
+                        return;
+                }
+                else if (barriers.length > 0) {
+                    return;
+                }
+            }
+            await new Promise((r) => setTimeout(r, 20));
+        }
+        throw new Error(`Timeout waiting for barrier to be reached (${timeoutMs}ms)`);
+    }
+    async resume() {
+        const url = this.barrierId
+            ? `${this.controlUrl}/resume/${this.barrierId}`
+            : `${this.controlUrl}/resume-next`;
+        const res = await fetch(url, { method: "POST" });
+        if (!res.ok) {
+            throw new Error(`Failed to resume barrier: HTTP ${res.status}`);
+        }
+    }
+}
+exports.BarrierHandle = BarrierHandle;
+class PgInterleaveClient {
+    controlUrl;
+    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}`;
+    }
+    async reset() {
+        const res = await fetch(`${this.controlUrl}/reset`, { method: "POST" });
+        if (!res.ok) {
+            throw new Error(`Failed to reset proxy: HTTP ${res.status}`);
+        }
+    }
+    async hasTimeouts() {
+        const res = await fetch(`${this.controlUrl}/events`);
+        if (!res.ok) {
+            throw new Error(`Failed to fetch events: HTTP ${res.status}`);
+        }
+        const data = (await res.json());
+        return data.had_timeouts;
+    }
+    async getPid(client) {
+        const res = await client.query("SELECT pg_backend_pid() AS pid;");
+        return res.rows[0].pid;
+    }
+    async intercept(options) {
+        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 res = await fetch(`${this.controlUrl}/intercept`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                target_pid: pid ?? null,
+                session_tag: options.sessionTag ?? null,
+                query_pattern: pattern,
+                action,
+                times: options.times ?? 1,
+            }),
+        });
+        if (!res.ok) {
+            const errBody = await res.text();
+            throw new Error(`Failed to register interceptor: HTTP ${res.status} - ${errBody}`);
+        }
+        return new BarrierHandle(this.controlUrl);
+    }
+    async injectTornCommit(client, times = 1) {
+        const pid = await this.getPid(client);
+        const res = await fetch(`${this.controlUrl}/intercept`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                target_pid: pid,
+                query_pattern: "COMMIT",
+                action: "drop_connection_on_commit",
+                times,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to inject torn commit: HTTP ${res.status}`);
+        }
+    }
+    async injectDeadlock(options) {
+        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 res = await fetch(`${this.controlUrl}/intercept`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                target_pid: pid ?? null,
+                query_pattern: pattern,
+                action: "synthetic_deadlock",
+                times: options.times ?? 1,
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to inject deadlock rule: HTTP ${res.status}`);
+        }
+    }
+}
+exports.PgInterleaveClient = PgInterleaveClient;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "pg-interleave",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Deterministic PostgreSQL wire-protocol proxy client for concurrency and chaos testing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --fileParallelism=false"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "concurrency",
+    "testing",
+    "chaos-engineering",
+    "race-condition",
+    "deadlock",
+    "proxy",
+    "wire-protocol"
+  ],
+  "author": "alt-f6",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alt-f6/pg-interleave.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alt-f6/pg-interleave/issues"
+  },
+  "homepage": "https://github.com/alt-f6/pg-interleave#readme",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/pg": "^8.11.0",
+    "pg": "^8.11.3",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.