pg-aequor 0.1.3

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Serikoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+

package/README.md

@@ -0,0 +1,197 @@
+<p align="center">
+  <img src="assets/pg-aequor-banner.png" alt="PG-Aequor banner" width="720" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/dimaq12/pg-aequor/actions/workflows/ci.yml">
+    <img alt="CI" src="https://github.com/dimaq12/pg-aequor/actions/workflows/ci.yml/badge.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/pg-aequor">
+    <img alt="npm" src="https://img.shields.io/npm/v/pg-aequor.svg" />
+  </a>
+  <a href="./LICENSE">
+    <img alt="license" src="https://img.shields.io/npm/l/pg-aequor.svg" />
+  </a>
+</p>
+
+<h1 align="center">pg-aequor</h1>
+
+<p align="center">
+  Crash-safe PostgreSQL client for <strong>Serverless runtimes</strong> (AWS Lambda / similar).
+</p>
+
+Have you ever…
+
+- …had a Lambda “freeze”, then watched Postgres slowly fill up with <strong>idle zombie connections</strong> until you hit <code>max_connections</code>?
+- …seen bursts of <code>sorry, too many clients already</code> during traffic spikes?
+- …debugged <strong>random runtime crashes</strong> where the root cause was a dead PG socket (and the error bubbled out of an event handler)?
+- …felt like you need PgBouncer/RDS Proxy, but you just want a client-side fix?
+
+Standard <code>pg</code> + Lambda scale-outs often end in zombie connections: a Lambda freezes, its TCP socket stays alive on the DB, and a new wave of invocations keeps opening connections until you hit <code>max_connections</code>.
+
+<strong>pg-aequor</strong> prevents this using <strong>Signed Leases</strong> + a lightweight <strong>Distributed Reaper</strong>.
+
+## Use cases
+
+- **Zombie connection storms**: old frozen containers keep sockets around; new invocations create more connections; the DB falls over.
+- **“Unexplained” runtime exits**: some runtimes treat unhandled socket errors as fatal. `pg-aequor` swallows errors in pg event handlers and forces a safe reconnect path.
+- **Spiky cold starts**: retries with decorrelated jitter + SQLSTATE filtering smooth transient network/DB restarts without turning retries into a synchronized stampede.
+
+## Table of contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Use cases](#use-cases)
+- [How it works](#how-it-works-in-one-minute)
+- [Operational rules](#operational-rules-important)
+- [Configuration](#configuration)
+- [Observability (hooks)](#observability-hooks)
+- [Production checklist](#production-checklist)
+- [FAQ](#faq)
+
+## Features
+
+- **Signed leases in `application_name`**: each connection self-identifies with expiration + HMAC.
+- **Distributed reaper**: one request occasionally becomes the “leader” and reaps expired connections.
+- **Advisory locks**: coordination via Postgres locks (no external coordinator).
+- **Crash safety**: socket errors are swallowed from event handlers to prevent runtime crashes.
+- **Safe retries**: decorrelated jitter + SQLSTATE filtering for transient failures.
+- **Hooks**: lightweight observability callbacks (metrics/tracing).
+
+## Install
+
+```bash
+npm install pg-aequor pg
+```
+
+> **Note:** `pg` is a peer dependency. Tested with `pg@^8.11.0`.
+
+## Quick start
+
+```js
+const { AequorClient } = require('pg-aequor')
+
+const client = new AequorClient({
+  host: process.env.DB_HOST,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+
+  // Coordination Secret (distinct from DB password)
+  coordinationSecret: process.env.COORD_SECRET,
+})
+
+await client.connect()
+const res = await client.query('SELECT NOW()')
+await client.clean() // or: await client.end()
+```
+
+## How it works (in one minute)
+
+In standard environments, connections live long. In serverless, containers “freeze”.
+
+We solve this via:
+
+1. **Signed Leases**: each connection stores `expiration + signature` in `application_name`.
+2. **Distributed Reaper**: on connect (probabilistically), one instance scans `pg_stat_activity` and terminates expired connections.
+3. **Advisory Locks**: `pg_try_advisory_lock` ensures only one leader reaps at a time.
+
+## Operational rules (important)
+
+- **Disposable idle**: if a connection is idle longer than its lease TTL, it becomes eligible to be reaped by another instance.
+- **Single-connection architecture**: the reaper runs on the active connection (under lock) to avoid “reaper storms”.
+- **Hooks must be fast**: don’t do heavy work inside hooks; use them for metrics/tracing only.
+
+## Configuration
+
+### Lease / reaper (recommended)
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `coordinationSecret` | `string` | _(required)_ | Shared secret for HMAC signing. **Do not** use DB password. Must be at least 16 bytes. |
+| `leaseMode` | `'required' \| 'optional'` | `'required'` | If `optional` and `coordinationSecret` is missing: lease/reaper/heartbeat are disabled. |
+| `leaseTtlMs` | `number` | `90000` | Lease TTL. |
+| `reaper` | `boolean` | `true` | Enable/disable reaper. |
+| `reaperRunProbability` | `number` | `0.1` | Probability of trying a reaper pass on connect (0..1). |
+| `reaperCooldownMs` | `number` | `30000` | Minimum time between reaper runs per container. |
+| `minConnectionIdleTimeSec` | `number` | `180` | Minimum idle seconds to consider a connection a candidate. |
+| `maxIdleConnectionsToKill` | `number` | `10` | Max zombies to kill in one pass. |
+
+### Retries
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `retries` | `number` | `3` |
+| `minBackoff` | `number` | `100` |
+| `maxBackoff` | `number` | `2000` |
+| `maxConnectRetryTimeMs` | `number` | `15000` |
+| `maxQueryRetryTimeMs` | `number` | `15000` |
+
+We use **decorrelated jitter** and **SQLSTATE-based** retry classification to avoid duplicating non-idempotent writes.
+
+## Observability (hooks)
+
+```js
+const { AequorClient } = require('pg-aequor')
+
+const client = new AequorClient({
+  // ...pg config...
+  coordinationSecret: process.env.COORD_SECRET,
+
+  hooks: {
+    onQueryRetry: ({ retries, err }) => {
+      console.warn(`Retry #${retries} due to ${err.code}`)
+    },
+    onReap: ({ locked, killed, durationMs }) => {
+      // metrics: how often we reap, and how many zombies we killed
+      if (locked && killed > 0) console.log(`Reaped ${killed} zombies in ${durationMs}ms`)
+    },
+    onClientDead: ({ source, meta }) => {
+      // Great place for EMF/X-Ray/etc
+      console.log('Client dead:', source, meta?.sqlstate)
+    },
+    onQueryStart: ({ startedAt }) => {
+      // tracing start
+    },
+    onQueryEnd: ({ duration }) => {
+      // tracing end
+    },
+  },
+})
+```
+
+## Production checklist
+
+### Required Postgres privileges
+
+The reaper reads `pg_stat_activity` and calls `pg_terminate_backend()`.
+
+> **Heads up:** on managed Postgres, this may require elevated privileges (or be restricted by policy).
+> If the reaper can’t terminate backends, you’ll typically see permission errors and zombies will remain.
+
+### Coordination secret hygiene
+
+- Use a **separate secret** (not the DB password).
+- Keep it at least **16 bytes**.
+- Rotate carefully: a safe pattern is “deploy new secret everywhere” during a maintenance window, because old/new secrets won’t verify each other’s leases.
+
+### Recommended defaults
+
+- Start with a conservative `leaseTtlMs` (e.g. `90s`) and `minConnectionIdleTimeSec` (e.g. `180s`) to avoid self-inflicted churn.
+- Keep hooks lightweight (metrics only).
+
+## FAQ
+
+### Will it kill my active connections?
+
+No. The reaper only terminates connections that:
+
+- match this service prefix, and
+- have a **valid signature**, and
+- are **expired**, and
+- are **idle** for longer than your configured threshold.
+
+### Do I still need PgBouncer/RDS Proxy?
+
+If you already have a proxy and it works well for you, keep it. `pg-aequor` is a pure-client approach intended for cases where you can’t or don’t want to add extra infrastructure.

package/index.d.ts

@@ -0,0 +1,206 @@
+import { Client, ClientConfig, QueryResult, QueryResultRow } from 'pg';
+
+export interface AequorClientHooks {
+  /**
+   * Called when a new database connection is successfully established.
+   */
+  onConnect?: (payload: { gen: number }) => void;
+
+  /**
+   * Called when a connection attempt fails and is about to be retried.
+   */
+  onReconnect?: (payload: { gen: number; retries: number; delay: number; err: Error }) => void;
+
+  /**
+   * Called when a query fails with a retryable error and is about to be retried.
+   */
+  onQueryRetry?: (payload: { retries: number; delay: number; err: Error }) => void;
+
+  /**
+   * Called when a heartbeat (lease renewal) succeeds.
+   */
+  onHeartbeat?: (payload: { gen: number }) => void;
+
+  /**
+   * Called when a heartbeat fails (either transiently or permanently).
+   */
+  onHeartbeatFail?: (payload: { gen: number; err: Error }) => void;
+
+  /**
+   * Called when a reaper pass is attempted (best effort).
+   * Useful for metrics: how many zombies were killed and how long it took.
+   */
+  onReap?: (payload: { gen: number; locked: boolean; killed: number; durationMs: number }) => void;
+
+  /**
+   * Called when the underlying pg.Client emits an 'error' event or ends unexpectedly.
+   * This is a critical signal that the connection is dead.
+   */
+  onClientDead?: (payload: { source: 'error' | 'end'; err?: Error; meta?: { sqlstate?: string; [key: string]: any } }) => void;
+
+  /**
+   * Called immediately before a user query is executed. Useful for tracing start time.
+   */
+  onQueryStart?: (payload: { args: any[]; startedAt: number }) => void;
+
+  /**
+   * Called immediately after a user query successfully completes.
+   */
+  onQueryEnd?: (payload: { args: any[]; res: QueryResult<any>; duration: number }) => void;
+
+  /**
+   * Called when a user query fails (before retry logic kicks in).
+   */
+  onQueryError?: (payload: { args: any[]; err: Error; duration: number }) => void;
+}
+
+export interface AequorClientConfig extends ClientConfig {
+  /**
+   * Shared coordination secret for signing leases. Required if leaseMode is 'required'.
+   * Conceptually distinct from DB password. Must be at least 16 bytes.
+   */
+  coordinationSecret?: string;
+
+  /**
+   * Logical name of the service using this client. Used for advisory lock namespace.
+   * Defaults to AWS_LAMBDA_FUNCTION_NAME or 'sls_pg'.
+   */
+  serviceName?: string;
+
+  /**
+   * Coordination mode.
+   * - 'required': throws if coordinationSecret is missing (default).
+   * - 'optional': disables lease/reaper if coordinationSecret is missing.
+   */
+  leaseMode?: 'required' | 'optional';
+
+  /**
+   * Enable/disable the background connection reaper. Default: true.
+   */
+  reaper?: boolean;
+
+  /**
+   * Probability (0.0 - 1.0) of running the reaper on connect.
+   * Alias for legacy 'connUtilization'. Default: 0.1.
+   */
+  reaperRunProbability?: number;
+
+  /**
+   * Minimum time (ms) between reaper runs on this container. Default: 120000 (2m).
+   */
+  reaperCooldownMs?: number;
+
+  /**
+   * How to handle reaper internal errors.
+   * - 'swallow': log and ignore (default).
+   * - 'throw': throw exception to the caller.
+   */
+  reaperErrorMode?: 'swallow' | 'throw';
+
+  /**
+   * Minimum idle time (seconds) before a connection is considered a zombie candidate.
+   * Default: 180 (3m).
+   */
+  minConnectionIdleTimeSec?: number;
+
+  /**
+   * Maximum number of zombie connections to kill in one reaper pass. Default: 1.
+   */
+  maxIdleConnectionsToKill?: number;
+
+  /**
+   * Lease time-to-live in milliseconds. Default: 90000 (90s).
+   */
+  leaseTtlMs?: number;
+
+  /**
+   * Time remaining (ms) where we soft-check lease renewal. Default: 30000.
+   */
+  heartbeatSoftRemainingMs?: number;
+
+  /**
+   * Time remaining (ms) where we force-wait for lease renewal. Default: 5000.
+   */
+  heartbeatHardWaitRemainingMs?: number;
+
+  /**
+   * Time (ms) to wait for set_config heartbeat query before timing out. Default: 2000.
+   */
+  heartbeatTimeoutMs?: number;
+
+  /**
+   * Action on heartbeat failure.
+   * - 'reconnect': mark client dead and reconnect (safest for serverless).
+   * - 'swallow': log and ignore.
+   * - 'throw': throw error.
+   * Default: 'reconnect'.
+   */
+  heartbeatErrorMode?: 'reconnect' | 'swallow' | 'throw';
+
+  /**
+   * Max time (ms) to spend retrying a connect operation. Default: 15000.
+   */
+  maxConnectRetryTimeMs?: number;
+
+  /**
+   * Max time (ms) to spend retrying a query operation. Default: 15000.
+   */
+  maxQueryRetryTimeMs?: number;
+
+  /**
+   * Default query_timeout (ms) passed to pg if not specified in individual query.
+   */
+  defaultQueryTimeoutMs?: number;
+
+  /**
+   * Observability hooks.
+   */
+  hooks?: AequorClientHooks;
+
+  /**
+   * Debug logging (console.log). Default: false.
+   */
+  debug?: boolean;
+
+  /**
+   * Underlying pg driver instance (e.g. for X-Ray capture).
+   */
+  library?: any;
+
+  // Legacy aliases
+  connUtilization?: number;
+  applicationName?: string;
+}
+
+export class AequorClient {
+  constructor(config: AequorClientConfig);
+
+  /**
+   * Establishes a connection (if not already connected) and acquires a lease.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Executes a query with automatic retry and lease management.
+   */
+  query<R extends QueryResultRow = any, I extends any[] = any[]>(
+    queryTextOrConfig: string | import('pg').QueryConfig<I>,
+    values?: I
+  ): Promise<QueryResult<R>>;
+
+  /**
+   * Gracefully closes the connection.
+   */
+  clean(): Promise<void>;
+
+  /**
+   * Alias for clean().
+   */
+  end(): Promise<void>;
+  
+  /**
+   * Returns the underlying pg.Client instance (if connected).
+   * Use with caution.
+   */
+  getClient(): Client | null;
+}

package/index.js

@@ -0,0 +1,7 @@
+const AequorClient = require('./lib/client')
+
+// Canonical export.
+module.exports = {
+  AequorClient,
+}
+

package/lib/client.js

@@ -0,0 +1,418 @@
+const RetryStrategy = require('./retry')
+const LeaseManager = require('./lease')
+const Reaper = require('./reaper')
+const crypto = require('crypto')
+
+class AequorClient {
+  constructor(config = {}) {
+    this._config = config
+    this._library = config.library || require('pg')
+    this._client = null
+    this._isDead = false // Flag to force recreation
+    this._generation = 0
+    this._connectPromise = null
+    
+    // Retry Strategy
+    this._retryStrategy = {
+      retries: config.retries ?? 3,
+      minBackoff: config.minBackoff ?? 100, // ms
+      maxBackoff: config.maxBackoff ?? 2000 // ms
+    }
+
+    // Lease/Reaper mode:
+    // - required: coordinationSecret must be provided (safe distributed coordination)
+    // - optional: if coordinationSecret missing, disable lease/reaper/heartbeat but client still works
+    this._leaseMode = config.leaseMode || 'required' // 'required' | 'optional'
+
+    // Reaper config (can be disabled if lease is disabled)
+    this._reaperEnabled = config.reaper !== false
+    this._strategy = {
+      // Probability of running a reaper pass on connect (0..1). Alias for backwards compatibility.
+      reaperRunProbability: config.reaperRunProbability ?? config.connUtilization ?? 0.1,
+      // Default should be minutes, not seconds, otherwise you create your own outages.
+      minConnIdleTimeSec: config.minConnectionIdleTimeSec || 180, // Default 3m
+      maxIdleConnectionsToKill: config.maxIdleConnectionsToKill || 10,
+      reaperErrorMode: config.reaperErrorMode || 'swallow', // 'swallow' | 'throw'
+    }
+    this._reaperCooldownMs = config.reaperCooldownMs ?? 30000
+    // Jittered Cooldown Base: Add random offset to avoid synchronized reapers
+    this._reaperBaseInterval = this._reaperCooldownMs + Math.random() * (this._reaperCooldownMs / 3)
+    this._reaperCurrentInterval = this._reaperBaseInterval
+    this._reaperNextRunAt = 0
+
+    // Setup Lease Manager
+    const serviceName = config.serviceName || process.env.AWS_LAMBDA_FUNCTION_NAME || 'sls_pg'
+    // 48-bit random instance id => exactly 8 base64url chars (no padding). Good entropy, tight budget.
+    const instanceId = crypto.randomBytes(6).toString('base64url')
+    // Explicit coordination secret (NOT db password).
+    const coordinationSecret = config.coordinationSecret
+    this._baseApplicationName =
+      (typeof config.application_name === 'string' && config.application_name) ||
+      (typeof config.applicationName === 'string' && config.applicationName) ||
+      serviceName
+
+    if (!coordinationSecret) {
+      if (this._leaseMode === 'required') {
+        throw new Error('Missing config.coordinationSecret (required for lease/reaper). Set leaseMode=\"optional\" to disable lease/reaper/heartbeat.')
+      }
+      this._leaseManager = null
+      this._reaperEnabled = false
+    } else {
+      this._leaseManager = new LeaseManager(serviceName, instanceId, coordinationSecret)
+    }
+    
+    // Heartbeat state
+    this._leaseExp = 0
+    this._heartbeatPromise = null
+    this._leaseTtlMs = config.leaseTtlMs ?? 90000
+    this._heartbeatSoftRemainingMs = config.heartbeatSoftRemainingMs ?? 30000
+    this._heartbeatHardWaitRemainingMs = config.heartbeatHardWaitRemainingMs ?? 5000
+    this._heartbeatErrorMode = config.heartbeatErrorMode || 'reconnect' // 'swallow' | 'reconnect' | 'throw'
+    this._heartbeatTimeoutMs = config.heartbeatTimeoutMs ?? 2000
+    this._defaultQueryTimeoutMs = config.defaultQueryTimeoutMs ?? 0
+
+    // Logging
+    this._logger = config.debug ? console.log : () => {}
+    this._hooks = config.hooks || {}
+
+    // Backoff state (decorrelated jitter needs previous delay)
+    this._connectPrevDelay = 0
+    this._queryPrevDelay = 0
+    this._maxConnectRetryTimeMs = config.maxConnectRetryTimeMs ?? 15000
+    this._maxQueryRetryTimeMs = config.maxQueryRetryTimeMs ?? 15000
+  }
+
+  _safeHook(name, payload) {
+    const fn = this._hooks && this._hooks[name]
+    if (typeof fn !== 'function') return
+    try { fn(payload) } catch (_) { /* never throw from hooks */ }
+  }
+
+  async connect() {
+    if (this._client && !this._isDead) return
+    if (this._connectPromise) return this._connectPromise
+    const gen = ++this._generation
+    this._connectPromise = (async () => {
+      try {
+        await this._connectWithRetry(gen)
+      } finally {
+        this._connectPromise = null
+      }
+    })()
+    return this._connectPromise
+  }
+
+  async _connectWithRetry(gen) {
+    const startedAt = Date.now()
+    let retries = 0
+    while (true) {
+      try {
+        await this._connect(gen)
+        this._connectPrevDelay = 0
+        this._safeHook('onConnect', { gen })
+        return // Success
+      } catch (err) {
+        if (this._maxConnectRetryTimeMs > 0 && (Date.now() - startedAt) > this._maxConnectRetryTimeMs) {
+          throw err
+        }
+        if (!RetryStrategy.isRetryable(err) || retries >= this._retryStrategy.retries) {
+          throw err
+        }
+        retries++
+        const delay = RetryStrategy.getBackoff(
+          this._retryStrategy.minBackoff,
+          this._retryStrategy.maxBackoff,
+          this._connectPrevDelay
+        )
+        this._connectPrevDelay = delay
+        this._safeHook('onReconnect', { gen, retries, delay, err })
+        this._logger(`Connect Retry ${retries}/${this._retryStrategy.retries} after ${delay}ms: ${err.message}`)
+        await new Promise(res => setTimeout(res, delay))
+      }
+    }
+  }
+
+  async _connect(gen) {
+    // Internal cleanup before creating a new client should NOT invalidate this generation.
+    await this._disposeClient('reconnect', { bumpGeneration: false })
+
+    // Generate initial lease
+    let appName = String(this._baseApplicationName || 'app').slice(0, 63)
+    if (this._leaseManager) {
+      this._leaseExp = Date.now() + this._leaseTtlMs
+      appName = this._leaseManager.generateAppName(this._leaseExp)
+    } else {
+      this._leaseExp = 0
+    }
+    
+    const clientConfig = this._buildPgClientConfig({ application_name: appName })
+
+    const client = new this._library.Client(clientConfig)
+    
+    // Crash Safety: Swallow errors to prevent Runtime.ExitError
+    client.on('error', (err) => this._markDeadAndDispose(client, err, 'error'))
+    // If connection ends, the client is not reusable.
+    client.on('end', () => this._markDeadAndDispose(client, null, 'end'))
+
+    await client.connect()
+
+    // Generation guard: do not resurrect if a newer generation started while we were connecting.
+    if (this._generation !== gen) {
+      try { await client.end() } catch (_) {}
+      return
+    }
+
+    this._client = client
+    this._isDead = false
+
+    // Run Reaper if enabled (async, best effort)
+    if (this._reaperEnabled) {
+      this._reap().catch(err => this._logger('Reap failed:', err.message))
+    }
+  }
+
+  // Best-effort connection cleanup
+  async _reap() {
+    // 1. Check Lease Manager
+    if (!this._leaseManager) return
+
+    // 2. Jittered Cooldown + Backoff
+    const now = Date.now()
+    if (now < this._reaperNextRunAt) return
+    
+    // 3. Use CURRENT client (Single Connection Architecture)
+    const client = this._client
+    if (!client) return
+
+    try {
+      const startedAt = Date.now()
+      const result = await Reaper.reap(client, this._config, this._leaseManager, this._strategy, this._logger)
+      const durationMs = Date.now() - startedAt
+      // Hook for metrics: how often we attempt, lock status, and how many zombies were killed.
+      this._safeHook('onReap', { gen: this._generation, locked: !!result.locked, killed: Number(result.killed || 0), durationMs })
+      
+      if (!result.locked) {
+        // Lock busy (someone else is reaping) -> Exponential Backoff
+        this._reaperCurrentInterval = Math.min(this._reaperCurrentInterval * 1.5, 600000) // max 10m
+      } else {
+        // Success (or just acquired lock) -> Reset to Base
+        this._reaperCurrentInterval = this._reaperBaseInterval
+      }
+
+      // Schedule next run with jitter
+      const jitter = Math.random() * (this._reaperCurrentInterval / 2)
+      this._reaperNextRunAt = now + this._reaperCurrentInterval + jitter
+      
+      if (result.killed > 0) {
+        this._logger(`Reaper: Killed ${result.killed} zombies`)
+      }
+    } catch (err) {
+      this._logger('Reap failed:', err.message)
+    }
+  }
+
+  async query(...args) {
+    const startedAt = Date.now()
+    this._safeHook('onQueryStart', { args, startedAt })
+    let retries = 0
+    while (true) {
+      try {
+        if (!this._client || this._isDead) {
+          await this.connect()
+        } else {
+          // Check heartbeat. If lease expired -> WAIT. If OK -> async update.
+          await this._heartbeatIfNeeded()
+        }
+
+        const res = await this._client.query(...args)
+        this._queryPrevDelay = 0
+        this._safeHook('onQueryEnd', { args, res, duration: Date.now() - startedAt })
+        return res
+
+      } catch (err) {
+        // If error is NOT retryable, throw immediately
+        if (!RetryStrategy.isRetryable(err) || retries >= this._retryStrategy.retries) {
+          this._safeHook('onQueryError', { args, err, duration: Date.now() - startedAt })
+          throw err
+        }
+        if (this._maxQueryRetryTimeMs > 0 && (Date.now() - startedAt) > this._maxQueryRetryTimeMs) {
+          this._safeHook('onQueryError', { args, err, duration: Date.now() - startedAt })
+          throw err
+        }
+        
+        retries++
+        const delay = RetryStrategy.getBackoff(
+          this._retryStrategy.minBackoff,
+          this._retryStrategy.maxBackoff,
+          this._queryPrevDelay
+        )
+        this._queryPrevDelay = delay
+        this._safeHook('onQueryRetry', { retries, delay, err })
+        this._logger(`Query Retry ${retries}/${this._retryStrategy.retries} after ${delay}ms: ${err.message}`)
+        
+        // Force reconnect on next loop
+        this._isDead = true
+        await this._disposeClient('query_error')
+        
+        await new Promise(res => setTimeout(res, delay))
+      }
+    }
+  }
+
+  async _heartbeatIfNeeded() {
+    if (!this._leaseManager) return
+    const gen = this._generation
+    const client = this._client
+    const now = Date.now()
+    const remaining = this._leaseExp - now
+    
+    // If lease has > 30s remaining, we are safe. Do nothing.
+    if (remaining > this._heartbeatSoftRemainingMs) return
+
+    // If lease is expired or close to expiring (< 30s), we need update.
+    // Use promise deduplication to avoid thundering herd.
+    if (!this._heartbeatPromise) {
+      this._heartbeatPromise = this._performHeartbeat(gen, client).finally(() => {
+        this._heartbeatPromise = null
+      })
+    }
+
+    // If lease is ALREADY expired (or < 5s safety margin), we MUST wait for update.
+    if (remaining < this._heartbeatHardWaitRemainingMs) {
+      await this._heartbeatPromise
+    } else {
+      // Otherwise, let it update in background (fire-and-forget)
+      // This is safe because we still have > 5s lease
+    }
+  }
+
+  async _performHeartbeat(gen, client) {
+    try {
+      if (!this._leaseManager) return
+      if (!client || client !== this._client) return
+      if (this._generation !== gen) return
+      const newExp = Date.now() + this._leaseTtlMs
+      const appName = this._leaseManager.generateAppName(newExp)
+      // Never interpolate appName into SQL. Use bind parameters.
+      const heartbeatQuery = this._client.query(`SELECT set_config('application_name', $1, false)`, [appName])
+      const timeout = new Promise((_, reject) => {
+        const e = new Error(`Heartbeat timed out after ${this._heartbeatTimeoutMs}ms`)
+        e.code = 'ETIMEDOUT'
+        setTimeout(() => reject(e), this._heartbeatTimeoutMs)
+      })
+      const res = await Promise.race([heartbeatQuery, timeout])
+      if (!res) throw new Error('Heartbeat failed: no result')
+      // Only update local lease if DB update succeeded.
+      if (this._generation === gen && client === this._client) {
+        this._leaseExp = newExp
+        this._safeHook('onHeartbeat', { gen })
+      }
+    } catch (err) {
+      this._logger('Heartbeat failed:', err.message)
+      this._safeHook('onHeartbeatFail', { gen, err })
+      // If we're in hard-wait territory and heartbeat fails, do NOT keep a client that
+      // is now invisible to other reapers (lease can expire). Default action: reconnect.
+      if (this._heartbeatErrorMode === 'throw') throw err
+      if (this._heartbeatErrorMode === 'reconnect') {
+        // In soft zone we already decided heartbeat matters. Don't limp along into expiry.
+        // If it's retryable, definitely reconnect. If it's non-retryable, reconnect won't help,
+        // but it's still safer than staying in an inconsistent lease state.
+        this._isDead = true
+        await this._disposeClient('heartbeat_failed')
+      }
+    }
+  }
+
+  _buildPgClientConfig(overrides = {}) {
+    const clientConfig = { ...this._config, ...overrides }
+    if (!clientConfig.query_timeout && this._defaultQueryTimeoutMs > 0) {
+      clientConfig.query_timeout = this._defaultQueryTimeoutMs
+    }
+    // Strip internal fields (keep pg config clean and future-proof)
+    const internalKeys = [
+      'library',
+      'reaper',
+      'reaperRunProbability',
+      'reaperErrorMode',
+      'connUtilization', // legacy alias
+      'minConnectionIdleTimeSec',
+      'maxIdleConnectionsToKill',
+      'retries',
+      'minBackoff',
+      'maxBackoff',
+      'serviceName',
+      'coordinationSecret',
+      'debug',
+      'leaseTtlMs',
+      'heartbeatSoftRemainingMs',
+      'heartbeatHardWaitRemainingMs',
+      'heartbeatErrorMode',
+      'heartbeatTimeoutMs',
+      'reaperCooldownMs',
+      'leaseMode',
+      'applicationName',
+      'defaultQueryTimeoutMs',
+      'hooks',
+      'maxConnectRetryTimeMs',
+      'maxQueryRetryTimeMs',
+    ]
+    for (const k of internalKeys) delete clientConfig[k]
+    return clientConfig
+  }
+
+  async _disposeClient(reason, { bumpGeneration = true } = {}) {
+    if (bumpGeneration) this._generation++
+    const old = this._client
+    this._client = null
+    if (!old) return
+    try {
+      await old.end()
+    } catch (_) {
+      // ignore
+    }
+  }
+
+  _markDeadAndDispose(client, err, source) {
+    // Never throw from event handlers (Lambda crash safety).
+    this._isDead = true
+    // Invalidate any in-flight connect/heartbeat on older generations.
+    this._generation++
+    // Atomically detach the client if it is the current one.
+    if (this._client === client) {
+      this._client = null
+    }
+    if (err) {
+      const meta = {
+        code: err.code,
+        sqlstate: err.sqlstate,
+        errno: err.errno,
+        syscall: err.syscall,
+        address: err.address,
+        port: err.port,
+        severity: err.severity,
+        routine: err.routine,
+      }
+      this._logger(`WARN: pg client ${source} (swallowed):`, err.message || err.code, meta)
+      this._safeHook('onClientDead', { source, err, meta })
+    }
+    // Best-effort close; do not await.
+    try {
+      client.end().catch(() => {})
+    } catch (_) {}
+  }
+
+  async clean() {
+    // Try to close gracefully
+    await this._disposeClient('clean')
+  }
+  
+  async end() {
+    return this.clean()
+  }
+
+  getClient() {
+    return this._client
+  }
+}
+
+module.exports = AequorClient

package/lib/lease.js

@@ -0,0 +1,124 @@
+const crypto = require('crypto')
+
+/**
+ * Lease Manager
+ * Handles generation and verification of signed application_name strings.
+ * Format: "s=SERVICE;i=INSTANCE_ID;e=TIMESTAMP;g=HMAC"
+ * Short keys used to fit within Postgres 63-byte limit.
+ */
+class LeaseManager {
+  static APP_NAME_MAX_LEN = 63
+  static SIG_LEN = 11 // 8 bytes -> base64url w/o padding => 11 chars
+
+  /**
+   * @param {string} serviceName - The logical name of the service
+   * @param {string} instanceId - Unique ID of this client instance
+   * @param {string} secret - Shared secret for HMAC (coordination secret; NOT db password)
+   */
+  constructor(serviceName, instanceId, secret) {
+    // Keep instanceId compact and delimiter-safe.
+    this.instanceId = LeaseManager._sanitizeToken(instanceId || 'inst')
+    if (!secret) {
+      throw new Error('LeaseManager requires a non-empty secret')
+    }
+    if (Buffer.byteLength(String(secret), 'utf8') < 16) {
+      throw new Error('LeaseManager secret is too short; must be at least 16 bytes')
+    }
+    this.secret = secret
+    // Normalize serviceName so application_name ALWAYS fits into 63 bytes and is LIKE-safe.
+    this.serviceName = LeaseManager._normalizeServiceName(serviceName || 'sls_pg', this.instanceId)
+  }
+
+  /**
+   * Generates a signed application_name.
+   * @param {number} expirationTs - Unix timestamp (ms) when lease expires
+   * @returns {string} The formatted application_name
+   * @throws {Error} if generated name exceeds 63 bytes
+   */
+  generateAppName(expirationTs) {
+    // Format: s=...;i=...;e=...
+    const base = `s=${this.serviceName};i=${this.instanceId};e=${expirationTs}`
+    const sig = this._sign(base)
+    const result = `${base};g=${sig}`
+
+    // Hard guarantee: never exceed Postgres 63-byte truncation limit.
+    // If this fires, our normalization math is wrong.
+    if (result.length > LeaseManager.APP_NAME_MAX_LEN) {
+      throw new Error(`BUG: application_name too long (${result.length} > ${LeaseManager.APP_NAME_MAX_LEN}): ${result}`)
+    }
+
+    return result
+  }
+
+  /**
+   * Parses an application_name and verifies its signature and expiration.
+   * @param {string} appNameString
+   * @returns {Object|null} Parsed info if valid format & signature, else null
+   */
+  parseAndVerify(appNameString) {
+    if (!appNameString) return null
+
+    // Regex for: s=...;i=...;e=...;g=...
+    const match = appNameString.match(/^s=([^;]+);i=([^;]+);e=([^;]+);g=([^;]+)$/)
+    if (!match) return null
+
+    const [full, s, i, eStr, g] = match
+    const base = `s=${s};i=${i};e=${eStr}`
+    const expectedSig = this._sign(base)
+
+    // Timing-safe signature comparison
+    const bufG = Buffer.from(g, 'utf8')
+    const bufExpected = Buffer.from(expectedSig, 'utf8')
+    if (bufG.length !== bufExpected.length || !crypto.timingSafeEqual(bufG, bufExpected)) return null
+
+    const exp = parseInt(eStr, 10)
+    if (!Number.isFinite(exp)) return null
+    
+    return {
+      svc: s,
+      inst: i,
+      exp,
+      isExpired: Date.now() > exp,
+      isValidSignature: true
+    }
+  }
+
+  _sign(text) {
+    // Compact signature: take first 8 bytes of HMAC and encode as base64url (11 chars, no padding)
+    const buf = crypto.createHmac('sha256', this.secret).update(text).digest()
+    return buf.subarray(0, 8).toString('base64url')
+  }
+
+  static _sanitizeToken(s) {
+    // Remove delimiter characters used by our format and LIKE wildcards.
+    // Keep it deterministic and log-friendly.
+    return String(s).replace(/[^a-zA-Z0-9:_-]/g, '_')
+  }
+
+  static _normalizeServiceName(serviceName, instanceId) {
+    const original = String(serviceName || 'sls_pg')
+    const raw = LeaseManager._sanitizeToken(original)
+    const inst = LeaseManager._sanitizeToken(instanceId || 'inst')
+
+    // Total format:
+    // s=<svc>;i=<inst>;e=<13digits>;g=<sig>
+    // Fixed overhead excluding <svc>: "s="(2) + ";i="(3) + inst + ";e="(3) + 13 + ";g="(3) + SIG_LEN
+    // => 24 + instLen + SIG_LEN
+    const overhead = 24 + inst.length + LeaseManager.SIG_LEN
+    const maxSvcLen = Math.max(1, LeaseManager.APP_NAME_MAX_LEN - overhead)
+
+    // If sanitization changed the name, we must add a hash suffix to avoid accidental collisions
+    // (different originals mapping to the same sanitized token).
+    const needsHash = raw !== original
+    if (!needsHash && raw.length <= maxSvcLen) return raw
+
+    // Truncate with a short hash suffix to preserve uniqueness.
+    const hash = crypto.createHash('sha1').update(original).digest('hex').slice(0, 8)
+    if (maxSvcLen <= hash.length) return hash.slice(0, maxSvcLen)
+
+    const prefixLen = maxSvcLen - (hash.length + 1)
+    return `${raw.slice(0, prefixLen)}-${hash}`
+  }
+}
+
+module.exports = LeaseManager

package/lib/reaper.js

@@ -0,0 +1,117 @@
+/**
+ * Connection Reaper
+ * Safely kills zombie connections using Advisory Locks and Signed Leases.
+ */
+class Reaper {
+  // Namespace advisory locks to avoid collisions with other apps in same DB.
+  // 0x50474151 corresponds to "PGAQ" (pg-aequor) in ASCII.
+  static LOCK_NS = 0x50474151
+  /**
+   * Runs the reaping process.
+   * @param {Object} client - The connected pg.Client
+   * @param {Object} config - Config including database name
+   * @param {LeaseManager} leaseManager - For verifying leases
+   * @param {Object} strategy - { minConnIdleTimeSec, connUtilization }
+   * @param {Function} logger
+   */
+  static async reap(client, config, leaseManager, strategy, logger) {
+    const serviceName = leaseManager.serviceName
+    let locked = false
+    
+    // 1. Acquire Advisory Lock (Non-blocking)
+    // Use Postgres native hashtext() to get a consistent 64-bit lock ID from the service string.
+    // This avoids JS-side 32-bit hash collisions.
+    
+    try {
+      const lockRes = await client.query(
+        `SELECT pg_try_advisory_lock($1::int, hashtext($2)) as locked`,
+        [Reaper.LOCK_NS, serviceName]
+      )
+      if (lockRes.rows[0].locked !== true) {
+        logger(`Reaper[pid=${process.pid}]: Lock busy, skipping`)
+        return { locked: false, killed: 0 }
+      }
+      locked = true
+
+      // 2. Scan for zombies
+      const minIdle = strategy.minConnIdleTimeSec
+      
+      // Fetch idle connections that look like our service
+      // Exclude self (pg_backend_pid())
+      // Optimization: Filter by application_name prefix in SQL to reduce result set size.
+      const query = `
+        SELECT pid, application_name, extract(epoch from (now() - state_change)) as idle_time
+        FROM pg_stat_activity 
+        WHERE datname = current_database() 
+          AND state = 'idle' 
+          AND pid <> pg_backend_pid()
+          AND application_name LIKE $1 || '%'
+      `
+      
+      // Correctness > optimization: do not prefilter using untrusted application_name.
+      const res = await client.query(query, [`s=${leaseManager.serviceName};`])
+      const candidates = []
+
+      for (const row of res.rows) {
+        if (row.idle_time < minIdle) continue
+
+        const lease = leaseManager.parseAndVerify(row.application_name)
+        
+        if (!lease) {
+          // Invalid format or signature -> Unsafe to touch (could be neighbor with different secret)
+          continue
+        }
+
+        if (lease.isExpired) {
+          // Valid signature, but expired -> ZOMBIE
+          candidates.push({
+            pid: row.pid,
+            idle_time: Number(row.idle_time) || 0,
+            exp: lease.exp,
+          })
+        }
+        // else: Lease valid -> ACTIVE neighbor -> Do not kill
+      }
+
+      // 3. Terminate zombies
+      if (candidates.length > 0) {
+        // Deterministic: kill the "stale-est" first.
+        // Primary: oldest expiration (smallest exp) -> longest expired.
+        // Secondary: largest idle_time.
+        candidates.sort((a, b) => (a.exp - b.exp) || (b.idle_time - a.idle_time) || (a.pid - b.pid))
+
+        const limit = Math.max(1, Number(strategy.maxIdleConnectionsToKill) || 1)
+        const selected = candidates.slice(0, limit)
+        const pidsToKill = selected.map(x => x.pid)
+
+        // Log a compact reason line for debugging.
+        const meta = selected.map(x => `pid=${x.pid},idle=${Math.round(x.idle_time)}s,expDelta=${Math.round((Date.now() - x.exp) / 1000)}s`).join(' | ')
+        logger(`Reaper[pid=${process.pid}]: Killing ${pidsToKill.length} zombies: ${meta}`)
+        // Cast to int[] to be safe
+        await client.query(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = ANY($1::int[])`, [pidsToKill])
+        return { locked: true, killed: pidsToKill.length }
+      }
+      
+      return { locked: true, killed: 0 }
+
+    } catch (err) {
+      logger(`Reaper[pid=${process.pid}] failed:`, err && (err.stack || err.message || err))
+      if (strategy && strategy.reaperErrorMode === 'throw') throw err
+      return { locked: false, killed: 0, error: err }
+    } finally {
+      // 4. Release Lock
+      if (locked) {
+        try {
+          await client.query(
+            `SELECT pg_advisory_unlock($1::int, hashtext($2))`,
+            [Reaper.LOCK_NS, serviceName]
+          )
+        } catch (_) { /* ignore unlock error */ }
+      }
+    }
+  }
+  // Removed _hashString method as we use DB-side hashtext()
+}
+
+module.exports = Reaper
+

package/lib/retry.js

@@ -0,0 +1,59 @@
+/**
+ * Retry Strategy & Error Classification
+ * Implements "Decorrelated Jitter" and safe error analysis.
+ */
+
+class RetryStrategy {
+  /**
+   * Determines if an error is a "dead connection" error that warrants a retry/reconnect.
+   * @param {Error} err
+   * @returns {boolean}
+   */
+  static isRetryable(err) {
+    const code = err && err.code
+    const msg = (err && err.message) || ''
+    const sqlstate = (err && (err.code || err.sqlstate)) || null
+
+    // 1) Node.js socket / transport codes (not SQLSTATE)
+    if (code === 'ECONNRESET' || code === 'EPIPE' || code === 'ETIMEDOUT' || code === 'ECONNREFUSED') return true
+    if (code === 'ENETUNREACH' || code === 'EHOSTUNREACH' || code === 'EAI_AGAIN') return true
+    if (code === 'ECONNABORTED' || code === 'EADDRINUSE') return true
+
+    // 2) SQLSTATE-first (stable)
+    // Class 08 — connection exception
+    if (typeof sqlstate === 'string' && sqlstate.length === 5 && sqlstate.startsWith('08')) return true
+
+    // Admin / crash / cannot continue
+    if (sqlstate === '57P01' || sqlstate === '57P02' || sqlstate === '57P03') return true
+
+    // Too many connections (can be transient under spiky concurrency)
+    if (sqlstate === '53300') return true
+
+    // Optional: transient concurrency failures (only safe if queries are idempotent)
+    // Keep disabled for now to avoid duplicating non-idempotent writes.
+    // if (sqlstate === '40001' || sqlstate === '40P01') return true
+
+    // 3) LAST-RESORT message fallbacks (keep minimal; remove over time)
+    if (msg.includes('Connection terminated unexpectedly')) return true
+    if (msg.includes('sorry, too many clients already')) return true
+
+    return false
+  }
+
+  /**
+   * Calculates backoff delay using "Decorrelated Jitter".
+   * sleep = min(cap, random(base, sleep * 3))
+   * @param {number} baseMs - Minimum wait
+   * @param {number} capMs - Maximum wait
+   * @param {number} previousDelay - The delay used in the previous attempt (or 0)
+   * @returns {number} ms to sleep
+   */
+  static getBackoff(baseMs, capMs, previousDelay) {
+    const prev = previousDelay || baseMs
+    const randRange = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min
+    return Math.min(capMs, randRange(baseMs, prev * 3))
+  }
+}
+
+module.exports = RetryStrategy
+

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pg-aequor",
+  "version": "0.1.3",
+  "description": "Crash-safe, coordination-aware PostgreSQL client for Serverless environments",
+  "main": "./index.js",
+  "types": "index.d.ts",
+  "author": "dimaq12",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/dimaq12/pg-aequor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dimaq12/pg-aequor/issues"
+  },
+  "homepage": "https://github.com/dimaq12/pg-aequor#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "pg": "^8.11.0"
+  },
+  "devDependencies": {
+    "pg": "^8.11.0"
+  }
+}