@molecule/api-instance-leadership-postgresql 0.0.1-stage → 1.1.0

package/README.md

@@ -1,11 +1,287 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-10-19T22:02:10.972Z
+-->
+
 # @molecule/api-instance-leadership-postgresql
 
-PostgreSQL provider for @molecule/api-instance-leadership: one leader across every API instance via a session advisory lock on a dedicated connection, with demotion when the connection is lost.
+PostgreSQL provider for `@molecule/api-instance-leadership`: elect ONE API
+instance to run platform-wide singleton work, using a PostgreSQL SESSION
+advisory lock held on a dedicated connection.
+
+```typescript
+import { acquireLeadership, setProvider } from '@molecule/api-instance-leadership'
+import { provider } from '@molecule/api-instance-leadership-postgresql'
+
+setProvider(provider) // reads DATABASE_URL lazily; nothing connects here
+acquireLeadership({
+  onAcquired: () => startPoolManager(),
+  onLost: () => stopPoolManager(),
+})
+```
+
+Use this bond whenever the API runs as more than one process or Machine: a
+host-local lock (a loopback port, a file) elects one leader PER HOST, so
+every singleton — pool managers, hibernation, retention sweeps, status
+recorders — runs once per Machine instead of once per platform.
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-instance-leadership-postgresql @molecule/api-bond @molecule/api-instance-leadership pg
+npm install -D @types/pg
+```
+
+## API
+
+### Interfaces
+
+#### `PostgresLeaderLockOptions`
+
+How to open the dedicated leadership connection.
+
+```typescript
+interface PostgresLeaderLockOptions {
+  /**
+   * The lock id to hold. This is an arbitrary 64-bit integer that must be
+   * unique across everything sharing the database: leadership must never
+   * contend with a migration lock or another feature's advisory lock.
+   */
+  lockId: number
+
+  /** Connection string. Defaults to `process.env.DATABASE_URL`. */
+  connectionString?: string
 
+  /**
+   * TLS configuration passed to `pg`. Omit to let the driver decide from the
+   * connection string (`sslmode=require` still enables TLS).
+   */
+  ssl?: pg.ConnectionConfig['ssl']
+
+  /**
+   * Open a connected client. Injected by a host that owns its own connection
+   * settings (e.g. a platform API with a shared SSL derivation helper); the
+   * default creates a `pg.Client` from {@link PostgresLeaderLockOptions.connectionString}.
+   *
+   * @param connectionString - The resolved connection string.
+   * @param ssl - The configured TLS options.
+   * @returns A connected `pg.Client`.
+   */
+  connect?: (connectionString: string, ssl: pg.ConnectionConfig['ssl']) => Promise<pg.Client>
+}
 ```
-npm install @molecule/api-instance-leadership-postgresql
+
+#### `PostgresLeadershipProviderOptions`
+
+How to build a leadership provider.
+
+```typescript
+interface PostgresLeadershipProviderOptions {
+  /**
+   * Opens one dedicated lock session per attempt. Use
+   * {@link createPostgresLockFactory} for the production PostgreSQL session,
+   * or a fake that shares one "held by" flag in tests.
+   */
+  createSession: LeaderLockFactory
+
+  /**
+   * How often a follower retries, in milliseconds. A function keeps the value
+   * lazy so a host can read it from configuration after import. Defaults to
+   * 2000; values below 50 are clamped so a misconfiguration cannot spin.
+   */
+  retryMs?: number | (() => number)
+
+  /**
+   * The advisory lock id, used only in log lines (the factory owns the actual
+   * lock). Defaults to 0 when omitted.
+   */
+  lockId?: number
+}
 ```
 
-Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
+### Classes
+
+#### `PgLeaderLockSession`
+
+The production session: one `pg.Client`, one advisory lock.
+
+Exported so a host that owns its own connection settings (the platform API's
+SSL derivation, a Vault-backed URL resolver) can build a session directly and
+pass it to the provider as its `createSession` factory.
+
+```typescript
+class PgLeaderLockSession implements LeaderLockSession {
+  private lostHandler: (() => void) | null = null
+  private lost = false
+
+  /**
+   * Track the connection's lifecycle so a lost session demotes the leader.
+   *
+   * @param client - A connected client owned exclusively by this session.
+   * @param lockId - The advisory lock id to hold.
+   */
+  constructor(
+    private readonly client: pg.Client,
+    private readonly lockId: number,
+  ) {
+    const lost = (): void => {
+      if (this.lost) return
+      this.lost = true
+      this.lostHandler?.()
+    }
+    // `error` covers a socket/network failure; `end` covers the backend ending
+    // the session (a server restart, an idle-session kill). Either way the lock
+    // is gone.
+    this.client.on('error', (error) => {
+      getLogger().warn('Leadership lock connection error', { error })
+      lost()
+    })
+    this.client.on('end', lost)
+  }
+
+  /** {@inheritDoc LeaderLockSession.tryLock} */
+  async tryLock(): Promise<boolean> {
+    const { rows } = await this.client.query<{ locked: boolean }>(
+      'SELECT pg_try_advisory_lock($1) AS locked',
+      [this.lockId],
+    )
+    return rows[0]?.locked === true
+  }
+
+  /** {@inheritDoc LeaderLockSession.release} */
+  async release(): Promise<void> {
+    if (!this.lost) {
+      try {
+        await this.client.query('SELECT pg_advisory_unlock($1)', [this.lockId])
+      } catch (error) {
+        // The session is ending either way, and a session lock is released by
+        // the backend when it ends — an unlock failure changes nothing.
+        getLogger().debug('Leadership advisory unlock failed; the session end releases it', {
+          error,
+        })
+      }
+    }
+    try {
+      await this.client.end()
+    } catch (_error) {
+      // Already ended.
+    }
+  }
+
+  /** {@inheritDoc LeaderLockSession.onLost} */
+  onLost(handler: () => void): void {
+    this.lostHandler = handler
+  }
+}
+```
+
+### Functions
+
+#### `createPostgresLockFactory(options)`
+
+Builds a {@link LeaderLockFactory} that opens PostgreSQL session locks.
+
+Each call to the factory opens a NEW dedicated connection — a follower
+retries on its own connection, and a leader reconnects on a fresh one after
+losing the old.
+
+```typescript
+function createPostgresLockFactory(options: PostgresLeaderLockOptions): LeaderLockFactory
+```
+
+- `options` — The lock id, connection settings and optional connect hook.
+
+**Returns:** A factory the leadership provider calls to open each session.
+
+#### `createProvider(options)`
+
+Creates an instance-leadership provider.
+
+```typescript
+function createProvider(options: PostgresLeadershipProviderOptions): InstanceLeadershipProvider
+```
+
+- `options` — The lock-session factory and retry interval.
+
+**Returns:** A provider implementing the core `InstanceLeadershipProvider` contract.
+
+### Constants
+
+#### `provider`
+
+A provider that reads its connection settings from `DATABASE_URL`.
+
+Its lock session is opened lazily, so importing (and bonding) this provider
+never connects. The lock id is the same one the API platform API has used
+for its singleton work; an app that shares a database with another
+leadership user must pass its OWN `lockId`.
+
+```typescript
+const provider: InstanceLeadershipProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-instance-leadership` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-instance-leadership'
+import { provider } from '@molecule/api-instance-leadership-postgresql'
+
+export function setupInstanceLeadershipPostgresql(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-instance-leadership` ^1.0.0
+
+### Environment Variables
+
+- `DATABASE_URL` _(required)_ — PostgreSQL connection string
+  - Setup: Use a direct connection or a session-mode pooler; transaction-mode pooling cannot retain advisory locks.
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-instance-leadership`
+- `pg`
 
-License: Apache-2.0
+- **A session lock dies with its connection.** The holder's process exiting,
+  crashing, or losing the network ends the backend session and PostgreSQL
+  releases the lock — no TTL to tune, no lock row left stale.
+- **A leader that loses its connection demotes itself.** The provider stops
+  treating itself as leader and calls `onLost`; a follower retries every
+  `retryMs` (default 2 s) and takes over within seconds.
+- **`prepareThreshold`/pooling caveat.** The lock MUST be taken on a direct
+  client connection, never through a transaction-mode pooler (PgBouncer in
+  transaction mode), which multiplexes statements from many clients onto a
+  session: a lock "held" there is held by an unrelated session. Use a
+  session-mode pooler or a direct connection.
+- **Pick a lock id nobody else uses.** Advisory locks share one namespace per
+  database. The exported `provider` uses `8675310`; a second application
+  sharing the same database must pass its own id to
+  `createPostgresLockFactory`.
+- **This bond runs no singleton work itself.** It only tells the application
+  which instance leads; the loops belong to the app (`onAcquired`/`onLost`).

package/dist/browser-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,CAAA"}
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -1,10 +1,12 @@
 /**
  * Browser guard — `@molecule/api-instance-leadership-postgresql` is SERVER-ONLY.
  *
- * Evaluating a server package in a browser bundle is always an import-graph
- * mistake (node APIs, secrets); without this guard it surfaces as a cryptic
- * downstream crash far from the culprit. Throwing here names the package and
- * the fix at the exact moment the client bundle evaluates it.
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
  */
 const g = globalThis;
 if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {

package/dist/index.d.ts

@@ -40,6 +40,7 @@
  *
  * @module
  */
+export * from './browser-guard.js';
 export * from './lock.js';
 export * from './provider.js';
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -40,5 +40,6 @@
  *
  * @module
  */
+export * from './browser-guard.js';
 export * from './lock.js';
 export * from './provider.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-instance-leadership-postgresql",
-  "version": "0.0.1-stage",
+  "version": "1.1.0",
   "description": "PostgreSQL provider for @molecule/api-instance-leadership: one leader across every API instance via a session advisory lock on a dedicated connection, with demotion when the connection is lost.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
   },
   "devDependencies": {
     "@molecule/api-bond": "1.0.2",
-    "@molecule/api-instance-leadership": "1.0.0",
+    "@molecule/api-instance-leadership": "1.1.0",
     "@types/node": "26.1.2",
     "@types/pg": "8.20.0",
     "typescript": "6.0.3",