@agentuity/postgres 1.0.15 → 1.0.16

package/dist/mutation.js

@@ -0,0 +1,241 @@
+/**
+ * Strips leading whitespace and SQL comments (block and line) from a query string.
+ * Returns the remaining query text starting at the first non-comment token.
+ *
+ * Note: This regex does NOT support nested block comments. Use
+ * {@link stripLeadingComments} for full nested comment support.
+ */
+export const LEADING_COMMENTS_RE = /^(?:\s+|\/\*[\s\S]*?\*\/|--[^\n]*\n)*/;
+/**
+ * Strips leading whitespace and SQL comments from a query string.
+ * Supports nested block comments.
+ * Returns the remaining query text starting at the first non-comment token.
+ */
+function stripLeadingComments(query) {
+    let i = 0;
+    const len = query.length;
+    while (i < len) {
+        const ch = query[i];
+        // Skip whitespace
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            i++;
+            continue;
+        }
+        // Skip line comment: -- ...\n
+        if (ch === '-' && i + 1 < len && query[i + 1] === '-') {
+            i += 2;
+            while (i < len && query[i] !== '\n')
+                i++;
+            if (i < len)
+                i++; // skip newline
+            continue;
+        }
+        // Skip block comment with nesting: /* ... /* ... */ ... */
+        if (ch === '/' && i + 1 < len && query[i + 1] === '*') {
+            let commentDepth = 1;
+            i += 2;
+            while (i < len && commentDepth > 0) {
+                if (query[i] === '/' && i + 1 < len && query[i + 1] === '*') {
+                    commentDepth++;
+                    i += 2;
+                }
+                else if (query[i] === '*' && i + 1 < len && query[i + 1] === '/') {
+                    commentDepth--;
+                    i += 2;
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        break;
+    }
+    return query.substring(i);
+}
+/** Regex matching the first keyword of a mutation statement. */
+const MUTATION_KEYWORD_RE = /^(INSERT|UPDATE|DELETE|COPY|TRUNCATE|MERGE|CALL|DO)\b/i;
+/**
+ * Determines whether a SQL query is a mutation that requires transaction
+ * wrapping for safe retry.
+ *
+ * Detected mutation types: INSERT, UPDATE, DELETE, COPY, TRUNCATE, MERGE,
+ * CALL, DO. EXPLAIN queries are never wrapped (read-only analysis, even
+ * when the explained statement is a mutation like `EXPLAIN INSERT INTO ...`).
+ *
+ * Mutation statements wrapped in a transaction can be safely retried because
+ * PostgreSQL guarantees that uncommitted transactions are rolled back when
+ * the connection drops. This prevents:
+ * - Duplicate rows from retried INSERTs
+ * - Double-applied changes from retried UPDATEs (e.g., counter increments)
+ * - Repeated side effects from retried DELETEs (e.g., cascade triggers)
+ *
+ * Handles three patterns:
+ * 1. Direct mutations: `INSERT INTO ...`, `UPDATE ... SET`, `DELETE FROM ...`,
+ *    `COPY ...`, `TRUNCATE ...`, `MERGE ...`, `CALL ...`, `DO ...`
+ *    (with optional leading comments/whitespace)
+ * 2. CTE mutations: `WITH cte AS (...) INSERT|UPDATE|DELETE|... ...` — scans
+ *    past the WITH clause by tracking parenthesis depth to skip CTE
+ *    subexpressions, then checks if the first top-level DML keyword is a
+ *    mutation. The scanner treats single-quoted strings, double-quoted
+ *    identifiers, dollar-quoted strings, line comments (--), and block
+ *    comments (including nested) as atomic regions so parentheses inside
+ *    them do not corrupt depth tracking.
+ * 3. Multi-statement queries: `SELECT 1; INSERT INTO items VALUES (1)` —
+ *    scans past semicolons at depth 0 to find mutation keywords in
+ *    subsequent statements.
+ *
+ * @see https://github.com/agentuity/sdk/issues/911
+ */
+export function isMutationStatement(query) {
+    // Strip leading whitespace and SQL comments (supports nested block comments)
+    const stripped = stripLeadingComments(query);
+    // EXPLAIN never mutates (even EXPLAIN INSERT INTO...)
+    if (/^EXPLAIN\b/i.test(stripped))
+        return false;
+    // Fast path: direct mutation statement
+    if (MUTATION_KEYWORD_RE.test(stripped)) {
+        return true;
+    }
+    // Fast path: no CTE prefix and no multi-statement separator → not a mutation
+    if (!/^WITH\s/i.test(stripped) && !stripped.includes(';')) {
+        return false;
+    }
+    // Full scan: walk the entire query character-by-character.
+    // Track parenthesis depth and check for mutation keywords at depth 0.
+    // This handles both CTE queries (WITH ... AS (...) DML ...) and
+    // multi-statement queries (SELECT ...; INSERT ...).
+    let depth = 0;
+    let i = 0;
+    const len = stripped.length;
+    while (i < len) {
+        const ch = stripped[i];
+        // ── Skip atomic regions (at any depth) ──────────────────────
+        // These regions may contain parentheses that must not affect depth.
+        // Single-quoted string: 'it''s a (test)'
+        if (ch === "'") {
+            i++;
+            while (i < len) {
+                if (stripped[i] === "'") {
+                    i++;
+                    if (i < len && stripped[i] === "'") {
+                        i++; // escaped '' → still inside string
+                    }
+                    else {
+                        break; // end of string
+                    }
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        // Double-quoted identifier: "col(1)"
+        if (ch === '"') {
+            i++;
+            while (i < len) {
+                if (stripped[i] === '"') {
+                    i++;
+                    if (i < len && stripped[i] === '"') {
+                        i++; // escaped "" → still inside identifier
+                    }
+                    else {
+                        break;
+                    }
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        // Line comment: -- has (parens)\n
+        if (ch === '-' && i + 1 < len && stripped[i + 1] === '-') {
+            i += 2;
+            while (i < len && stripped[i] !== '\n')
+                i++;
+            if (i < len)
+                i++; // skip newline
+            continue;
+        }
+        // Block comment: /* has (parens) */ — supports nesting
+        if (ch === '/' && i + 1 < len && stripped[i + 1] === '*') {
+            let commentDepth = 1;
+            i += 2;
+            while (i < len && commentDepth > 0) {
+                if (stripped[i] === '/' && i + 1 < len && stripped[i + 1] === '*') {
+                    commentDepth++;
+                    i += 2;
+                }
+                else if (stripped[i] === '*' && i + 1 < len && stripped[i + 1] === '/') {
+                    commentDepth--;
+                    i += 2;
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        // Dollar-quoted string: $$has (parens)$$ or $tag$...$tag$
+        if (ch === '$') {
+            let tagEnd = i + 1;
+            while (tagEnd < len && /[a-zA-Z0-9_]/.test(stripped[tagEnd]))
+                tagEnd++;
+            if (tagEnd < len && stripped[tagEnd] === '$') {
+                const tag = stripped.substring(i, tagEnd + 1);
+                i = tagEnd + 1;
+                const closeIdx = stripped.indexOf(tag, i);
+                if (closeIdx !== -1) {
+                    i = closeIdx + tag.length;
+                }
+                else {
+                    i = len; // unterminated — skip to end
+                }
+                continue;
+            }
+            // Not a dollar-quote tag, fall through
+        }
+        // ── Track parenthesis depth ─────────────────────────────────
+        if (ch === '(') {
+            depth++;
+            i++;
+            continue;
+        }
+        if (ch === ')') {
+            depth--;
+            i++;
+            continue;
+        }
+        // Only inspect keywords at top level (depth === 0)
+        if (depth === 0) {
+            // Skip whitespace at top level
+            if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+                i++;
+                continue;
+            }
+            // Skip semicolons and commas between CTEs or statements
+            if (ch === ';' || ch === ',') {
+                i++;
+                continue;
+            }
+            // Check for mutation keyword or skip other words
+            // (CTE names, AS, RECURSIVE, SELECT, WITH, etc.)
+            if (/\w/.test(ch)) {
+                const rest = stripped.substring(i);
+                if (MUTATION_KEYWORD_RE.test(rest)) {
+                    return true;
+                }
+                // Skip past this word
+                while (i < len && /\w/.test(stripped[i])) {
+                    i++;
+                }
+                continue;
+            }
+        }
+        i++;
+    }
+    return false;
+}
+//# sourceMappingURL=mutation.js.map

package/dist/mutation.js.map

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

package/dist/types.d.ts

@@ -1,4 +1,10 @@
 import type pg from 'pg';
+export type UnsafeQueryResult = {
+    then: Promise<unknown>['then'];
+    catch: Promise<unknown>['catch'];
+    finally: Promise<unknown>['finally'];
+    values: () => Promise<unknown>;
+};
 /**
  * TLS configuration options for PostgreSQL connections.
  */
@@ -125,17 +131,46 @@ export interface PostgresConfig {
      */
     username?: string;
     /**
-     * Database password.
+     * Database password for authentication.
+     * Can be a string or a function that returns the password (sync or async).
+     * Using a function enables rotating credentials (e.g., AWS RDS IAM tokens,
+     * GCP Cloud SQL IAM authentication).
      */
-    password?: string;
+    password?: string | (() => string | Promise<string>);
     /**
      * Database name.
      */
     database?: string;
+    /**
+     * Unix domain socket path for local PostgreSQL connections.
+     * Alternative to hostname/port for same-machine connections.
+     *
+     * @example '/var/run/postgresql/.s.PGSQL.5432'
+     */
+    path?: string;
     /**
      * TLS configuration.
      */
     tls?: TLSConfig | boolean;
+    /**
+     * PostgreSQL client runtime configuration parameters sent during
+     * connection startup.
+     *
+     * These correspond to PostgreSQL runtime configuration settings.
+     *
+     * @see https://www.postgresql.org/docs/current/runtime-config-client.html
+     *
+     * @example
+     * ```typescript
+     * {
+     *   search_path: 'myapp,public',
+     *   statement_timeout: '30s',
+     *   application_name: 'my-service',
+     *   timezone: 'UTC',
+     * }
+     * ```
+     */
+    connection?: Record<string, string | boolean | number>;
     /**
      * Maximum number of connections in the pool.
      * @default 10
@@ -151,6 +186,40 @@ export interface PostgresConfig {
      * @default 0 (no timeout)
      */
     idleTimeout?: number;
+    /**
+     * Maximum lifetime of a connection in seconds.
+     * After this time, the connection is closed and a new one is created.
+     * Set to `0` for no maximum lifetime.
+     *
+     * This is useful in pooled environments to prevent stale connections
+     * and coordinate with connection pooler behavior.
+     *
+     * @default 0 (no maximum lifetime)
+     */
+    maxLifetime?: number;
+    /**
+     * Whether to use named prepared statements.
+     *
+     * When `true`, Bun's SQL driver caches named prepared statements on the
+     * server for better performance with repeated queries.
+     *
+     * When `false`, queries use unnamed prepared statements that are parsed
+     * fresh each time. This is required when using connection poolers like
+     * PGBouncer (in transaction mode) or Supavisor, where the backend
+     * connection may change between queries, invalidating cached statements.
+     *
+     * @default false
+     */
+    prepare?: boolean;
+    /**
+     * Whether to return large integers as BigInt instead of strings.
+     *
+     * When `true`, integers outside the i32 range are returned as `BigInt`.
+     * When `false`, they are returned as strings.
+     *
+     * @default false
+     */
+    bigint?: boolean;
     /**
      * Reconnection configuration.
      */
@@ -167,6 +236,11 @@ export interface PostgresConfig {
      * @default false
      */
     preconnect?: boolean;
+    /**
+     * Callback invoked when a connection attempt completes.
+     * Receives an Error on failure, or null on success.
+     */
+    onconnect?: (error: Error | null) => void;
     /**
      * Callback invoked when the connection is closed.
      */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/postgres",
-	"version": "1.0.15",
+	"version": "1.0.16",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -31,11 +31,11 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "1.0.15",
+		"@agentuity/core": "1.0.16",
 		"pg": "^8.13.1"
 	},
 	"peerDependencies": {
-		"@agentuity/runtime": "1.0.15"
+		"@agentuity/runtime": "1.0.16"
 	},
 	"peerDependenciesMeta": {
 		"@agentuity/runtime": {
@@ -43,8 +43,8 @@
 		}
 	},
 	"devDependencies": {
-		"@agentuity/runtime": "1.0.15",
-		"@agentuity/test-utils": "1.0.15",
+		"@agentuity/runtime": "1.0.16",
+		"@agentuity/test-utils": "1.0.16",
 		"@types/bun": "latest",
 		"@types/pg": "^8.11.14",
 		"bun-types": "latest",

package/src/client.ts

@@ -1,5 +1,11 @@
 import { SQL as BunSQL, type SQLQuery, type SQL } from 'bun';
-import type { PostgresConfig, ConnectionStats, TransactionOptions, ReserveOptions } from './types';
+import type {
+	PostgresConfig,
+	ConnectionStats,
+	TransactionOptions,
+	ReserveOptions,
+	UnsafeQueryResult,
+} from './types';
 import {
 	ConnectionClosedError,
 	PostgresError,
@@ -12,6 +18,73 @@ import { computeBackoff, sleep, mergeReconnectConfig } from './reconnect';
 import { Transaction, ReservedConnection } from './transaction';
 import { registerClient, unregisterClient } from './registry';
 import { injectSslMode } from './tls';
+import { isMutationStatement } from './mutation';
+
+/**
+ * Creates a lazy thenable with format locking for safe query execution.
+ *
+ * The returned object implements the {@link UnsafeQueryResult} interface: it is
+ * thenable (`.then()`, `.catch()`, `.finally()`) and exposes a `.values()`
+ * method for array-format results. Execution is deferred until the first
+ * consumption method is called.
+ *
+ * **Format locking:** The first access (`.then()` or `.values()`) determines
+ * the result format for the lifetime of the thenable. Attempting the other
+ * format afterwards throws an error, preventing accidental duplicate execution.
+ *
+ * @param makeExecutor - Factory that creates the execution promise.
+ *   Called with `true` for array format (`.values()`) or `false` for row-object
+ *   format (`.then()`).
+ * @returns A lazy thenable with `.values()` support
+ *
+ * @internal Exported for use by `@agentuity/drizzle` — not part of the public API.
+ */
+export function createThenable(
+	makeExecutor: (useValues: boolean) => Promise<unknown>
+): UnsafeQueryResult {
+	let started: Promise<unknown> | null = null;
+	let executionMode: boolean | null = null; // tracks useValues for first call
+
+	const startExecution = (useValues: boolean): Promise<unknown> => {
+		if (started) {
+			if (executionMode !== useValues) {
+				throw new Error(
+					`Cannot access .${useValues ? 'values()' : 'then()'} after .${!useValues ? 'values()' : 'then()'} ` +
+						'on the same query result. The result format is locked to the first access mode ' +
+						'to prevent duplicate query execution. Create a new unsafeQuery() call for a different format.'
+				);
+			}
+			return started;
+		}
+		executionMode = useValues;
+		started = makeExecutor(useValues);
+		return started;
+	};
+
+	return new Proxy({} as UnsafeQueryResult, {
+		get(_target, prop) {
+			if (prop === 'then') {
+				return <TResult1 = unknown, TResult2 = never>(
+					onfulfilled?: ((value: unknown) => TResult1 | PromiseLike<TResult1>) | null,
+					onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null
+				): Promise<TResult1 | TResult2> => startExecution(false).then(onfulfilled, onrejected);
+			}
+			if (prop === 'catch') {
+				return <TResult = never>(
+					onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null
+				): Promise<unknown | TResult> => startExecution(false).catch(onrejected);
+			}
+			if (prop === 'finally') {
+				return (onfinally?: (() => void) | null): Promise<unknown> =>
+					startExecution(false).finally(onfinally ?? undefined);
+			}
+			if (prop === 'values') {
+				return () => startExecution(true);
+			}
+			return undefined;
+		},
+	});
+}
 
 /**
  * Bun SQL options for PostgreSQL connections.
@@ -149,8 +222,29 @@ export class PostgresClient {
 	 * ```
 	 */
 	query(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]> {
+		// Reconstruct query shape for mutation detection.
+		// Space as separator is safe — doesn't affect SQL keyword detection.
+		const queryShape = strings.join(' ');
+		const mutation = isMutationStatement(queryShape);
+
 		return this._executeWithRetry(async () => {
 			const sql = await this._ensureConnectedAsync();
+			if (mutation) {
+				await sql.unsafe('BEGIN');
+				try {
+					const result = await sql(strings, ...values);
+					await sql.unsafe('COMMIT');
+					return result as unknown[];
+				} catch (error) {
+					try {
+						await sql.unsafe('ROLLBACK');
+					} catch {
+						// Connection may already be dead; Postgres auto-rolls
+						// back uncommitted transactions on connection close.
+					}
+					throw error;
+				}
+			}
 			return sql(strings, ...values);
 		});
 	}
@@ -278,6 +372,87 @@ export class PostgresClient {
 		return sql.unsafe(query);
 	}
 
+	/**
+	 * Execute a raw SQL query with automatic retry and transaction wrapping for mutations.
+	 *
+	 * Unlike {@link unsafe}, this method:
+	 * - Automatically retries on retryable errors (connection drops, resets)
+	 * - Wraps mutation statements in transactions for safe retry
+	 * - Returns a thenable with `.values()` support matching Bun's SQLQuery interface
+	 *
+	 * Detected mutation types: INSERT, UPDATE, DELETE, COPY, TRUNCATE, MERGE, CALL, DO.
+	 * EXPLAIN queries are never wrapped (read-only analysis).
+	 *
+	 * For SELECT queries, retries without transaction wrapping (idempotent).
+	 * For mutations, wraps in BEGIN/COMMIT so PostgreSQL auto-rolls back
+	 * uncommitted transactions on connection drop, making retry safe.
+	 *
+	 * **⚠️ COMMIT Uncertainty Window:**
+	 * If the connection drops after the server processes COMMIT but before the client
+	 * receives confirmation (~<1ms window), changes ARE committed but the client sees
+	 * a failure. Retry will then duplicate the mutation. This is an inherent limitation
+	 * of retry-based approaches. Use application-level idempotency (e.g., unique
+	 * constraints with ON CONFLICT) for critical operations.
+	 *
+	 * **⚠️ Result Format Locking:**
+	 * Each unsafeQuery() result can only be consumed via ONE access pattern — either
+	 * `await result` (row objects) or `await result.values()` (arrays), not both.
+	 * Attempting the second pattern throws an error to prevent accidental duplicate execution.
+	 *
+	 * @param query - The raw SQL query string
+	 * @param params - Optional query parameters
+	 * @returns A thenable that resolves to rows (objects) or arrays via `.values()`
+	 *
+	 * @see https://github.com/agentuity/sdk/issues/911
+	 *
+	 * @example
+	 * ```typescript
+	 * // INSERT with safe retry
+	 * const rows = await client.unsafeQuery('INSERT INTO items (name) VALUES ($1) RETURNING *', ['test']);
+	 *
+	 * // SELECT with retry (no transaction overhead)
+	 * const items = await client.unsafeQuery('SELECT * FROM items WHERE id = $1', [42]);
+	 *
+	 * // Get raw arrays via .values()
+	 * const arrays = await client.unsafeQuery('SELECT id, name FROM items').values();
+	 * ```
+	 */
+	unsafeQuery(query: string, params?: unknown[]): UnsafeQueryResult {
+		if (isMutationStatement(query)) {
+			const makeTransactionalExecutor = (useValues: boolean) =>
+				this._executeWithRetry(async () => {
+					const raw = this._ensureConnected();
+					await raw.unsafe('BEGIN');
+					try {
+						const q = params ? raw.unsafe(query, params) : raw.unsafe(query);
+						const result = useValues ? await q.values() : await q;
+						await raw.unsafe('COMMIT');
+						return result;
+					} catch (error) {
+						try {
+							await raw.unsafe('ROLLBACK');
+						} catch {
+							// Connection may already be dead; Postgres auto-rolls
+							// back uncommitted transactions on connection close.
+						}
+						throw error;
+					}
+				});
+
+			return createThenable(makeTransactionalExecutor);
+		}
+
+		// Non-mutation: plain retry without transaction overhead
+		const makeExecutor = (useValues: boolean) =>
+			this._executeWithRetry(async () => {
+				const raw = this._ensureConnected();
+				const q = params ? raw.unsafe(query, params) : raw.unsafe(query);
+				return useValues ? q.values() : q;
+			});
+
+		return createThenable(makeExecutor);
+	}
+
 	/**
 	 * Registers signal handlers to detect application shutdown.
 	 * When shutdown is detected, reconnection is disabled.
@@ -335,10 +510,12 @@ export class PostgresClient {
 		if (this._config.username) bunOptions.username = this._config.username;
 		if (this._config.password) bunOptions.password = this._config.password;
 		if (this._config.database) bunOptions.database = this._config.database;
+		if (this._config.path) bunOptions.path = this._config.path;
 		if (this._config.max) bunOptions.max = this._config.max;
 		if (this._config.idleTimeout !== undefined) bunOptions.idleTimeout = this._config.idleTimeout;
 		if (this._config.connectionTimeout !== undefined)
 			bunOptions.connectionTimeout = this._config.connectionTimeout;
+		if (this._config.maxLifetime !== undefined) bunOptions.maxLifetime = this._config.maxLifetime;
 
 		// Handle TLS configuration
 		if (this._config.tls !== undefined) {
@@ -349,6 +526,23 @@ export class PostgresClient {
 			}
 		}
 
+		// Postgres client runtime configuration (search_path, statement_timeout, etc.)
+		if (this._config.connection) bunOptions.connection = this._config.connection;
+
+		// Default to unnamed prepared statements (prepare: false) to prevent
+		// "prepared statement did not exist" errors when backend connections
+		// rotate (e.g., connection poolers, hot reloads, server restarts).
+		// See: https://github.com/agentuity/sdk/issues/1005
+		bunOptions.prepare = this._config.prepare ?? false;
+
+		// BigInt handling for integers outside i32 range
+		if (this._config.bigint !== undefined) bunOptions.bigint = this._config.bigint;
+
+		// Set up onconnect handler
+		if (this._config.onconnect) {
+			bunOptions.onconnect = this._config.onconnect;
+		}
+
 		// Set up onclose handler for reconnection
 		bunOptions.onclose = (err: Error | null) => {
 			this._handleClose(err ?? undefined);
@@ -735,6 +929,7 @@ export class PostgresClient {
  */
 export type CallablePostgresClient = PostgresClient & {
 	(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+	unsafeQuery(query: string, params?: unknown[]): UnsafeQueryResult;
 };
 
 /**
@@ -790,6 +985,7 @@ export function createCallableClient(config?: string | PostgresConfig): Callable
 	callable.close = client.close.bind(client);
 	callable.shutdown = client.shutdown.bind(client);
 	callable.unsafe = client.unsafe.bind(client);
+	callable.unsafeQuery = client.unsafeQuery.bind(client);
 	callable.waitForConnection = client.waitForConnection.bind(client);
 	callable.executeWithRetry = client.executeWithRetry.bind(client);