svelte-adapter-uws-extensions 0.1.9 → 0.4.1

package/README.md

@@ -13,6 +13,7 @@ The core adapter keeps everything in-process memory. That works great for single
 - **Distributed broadcast groups** - named groups with membership and roles that span instances
 - **Shared cursor state** - ephemeral positions (cursors, selections, drawing strokes) visible across instances
 - **Database change notifications** - Postgres LISTEN/NOTIFY forwarded straight to WebSocket clients
+- **Prometheus metrics** - expose extension metrics for scraping, zero overhead when disabled
 
 ---
 
@@ -37,11 +38,19 @@ The core adapter keeps everything in-process memory. That works great for single
 - [Replay buffer (Postgres)](#replay-buffer-postgres)
 - [LISTEN/NOTIFY bridge](#listennotify-bridge)
 
+**Observability**
+- [Prometheus metrics](#prometheus-metrics)
+
+**Reliability**
+- [Failure handling](#failure-handling)
+- [Circuit breaker](#circuit-breaker)
+
 **Operations**
 - [Graceful shutdown](#graceful-shutdown)
 - [Testing](#testing)
 
-**Help**
+**More**
+- [Related projects](#related-projects)
 - [License](#license)
 
 ---
@@ -136,7 +145,9 @@ export const pg = createPgClient({
 
 ## Pub/sub bus
 
-Distributes `platform.publish()` calls across multiple server instances via Redis pub/sub. Each instance publishes locally AND to Redis. Incoming Redis messages are forwarded to the local platform with echo suppression (messages from the same instance are ignored).
+Distributes `platform.publish()` calls across multiple server instances via Redis pub/sub. Each instance publishes locally AND to Redis. Incoming Redis messages are forwarded to the local platform with echo suppression (messages originating from the same instance are dropped on receive, keyed by a per-process instance ID).
+
+Multiple `publish()` calls within the same event-loop tick are coalesced into a single Redis pipeline via microtask batching. This means a form action that publishes to three topics results in one pipelined round trip, not three independent commands.
 
 #### Setup
 
@@ -190,6 +201,10 @@ export function message(ws, { data, platform }) {
 
 Same API as the core `createReplay` plugin, but backed by Redis sorted sets. Messages survive restarts and are shared across instances.
 
+Sequence numbers are incremented atomically via a Lua script (`INCR` + `ZADD` + trim in a single `EVAL`), so concurrent publishes from multiple instances produce strictly ordered, gap-free sequences per topic. When the buffer exceeds `size`, the oldest entries are removed inside the same Lua script -- no second round trip required.
+
+When a client requests replay, the buffer checks whether the client's last-seen sequence is older than the oldest buffered entry. If it is (the buffer was trimmed past the client's position), a `truncated` event fires on `__replay:{topic}` before any `msg` events, so the client knows it missed messages and can do a full reload. This also fires when the buffer is completely empty but the sequence counter has advanced past the client's position (e.g. all entries expired via TTL).
+
 #### Setup
 
 ```js
@@ -261,6 +276,12 @@ All methods are async (they hit Redis). The API otherwise matches the core plugi
 
 Same API as the core `createPresence` plugin, but backed by Redis hashes. Presence state is shared across instances with cross-instance join/leave notifications via Redis pub/sub.
 
+Joins are staged with full rollback on failure: local state is set up first, then the Redis hash field is written, then the WebSocket is subscribed. If any step fails (circuit breaker trips, Redis is down, WebSocket closed during an async gap), all prior steps are undone -- local maps, the Redis field, and any broadcast join event are reversed. This prevents ghost entries that would show a user as online when they never fully connected.
+
+Leaves use an atomic Lua script (`LEAVE_SCRIPT`) that removes this instance's field from the hash and then scans remaining fields for the same user key, ignoring stale entries. Leave is only broadcast when no other instance holds a live entry for that user, preventing premature "user left" notifications in multi-instance deployments.
+
+Zombie cleanup runs on the heartbeat interval. Each tick, every tracked WebSocket is probed via `getBufferedAmount()` -- if the call throws, the socket is dead and its presence is removed synchronously before the heartbeat writes to Redis. The heartbeat then refreshes timestamps on all live entries via a Redis pipeline and runs a server-side Lua cleanup script (`CLEANUP_SCRIPT`) that scans the hash and removes any fields whose timestamp exceeds the TTL. This handles crashed instances whose close handlers never fired.
+
 #### Setup
 
 ```js
@@ -296,7 +317,7 @@ export async function close(ws, { platform }) {
 | Option | Default | Description |
 |---|---|---|
 | `key` | `'id'` | Field for user dedup (multi-tab) |
-| `select` | identity | Extract public fields from userData |
+| `select` | strips `__`-prefixed keys | Extract public fields from userData |
 | `heartbeat` | `30000` | TTL refresh interval in ms |
 | `ttl` | `90` | Per-entry expiry in seconds. Entries from crashed instances expire individually after this period, even if other instances are still active on the same topic. |
 
@@ -500,7 +521,7 @@ export function close(ws, { platform }) {
 | Option | Default | Description |
 |---|---|---|
 | `throttle` | `50` | Minimum ms between broadcasts per user per topic |
-| `select` | identity | Extract user data to broadcast alongside position |
+| `select` | strips `__`-prefixed keys | Extract user data to broadcast alongside position |
 | `ttl` | `30` | Per-entry TTL in seconds (auto-refreshed on each broadcast). Stale entries from crashed instances are filtered out individually, even if other instances are still active on the same topic. |
 
 #### API
@@ -519,7 +540,11 @@ export function close(ws, { platform }) {
 
 ## Replay buffer (Postgres)
 
-Same API as the Redis replay buffer, but backed by a Postgres table. Best suited for durable audit trails or history that needs to survive longer than Redis TTLs. Sequence numbers are generated atomically via a dedicated `_seq` table, so they are safe across multiple server instances.
+Same API as the Redis replay buffer, but backed by a Postgres table. Best suited for durable audit trails or history that needs to survive longer than Redis TTLs. Sequence numbers are generated atomically via a dedicated `_seq` table using `INSERT ... ON CONFLICT DO UPDATE`, so concurrent publishes from multiple instances produce strictly ordered sequences with no duplicates or gaps.
+
+Buffer trimming runs after each publish by deleting rows with `seq <= currentSeq - maxSize`. If the trim query fails, the publish still succeeds -- the periodic background cleanup (configurable via `cleanupInterval`) catches any excess rows later.
+
+Same gap detection behavior as the Redis replay buffer: if the client's last-seen sequence is older than the oldest buffered row, or the buffer is empty but the sequence counter has advanced, a `truncated` event fires before replay.
 
 #### Setup
 
@@ -661,10 +686,248 @@ The client side needs no changes -- the core `crud('messages')` store already ha
 
 #### Limitations
 
-- Payload is limited to 8KB by Postgres. For large rows, send the row ID in the notification and let the client fetch the full row.
+- **Payload is hard-limited to ~8000 bytes by Postgres** (`pg_notify` silently truncates or errors above this). This is a Postgres constraint, not a library limitation. The bridge warns at 7500 bytes. For large rows, send the row ID in the notification and let the client fetch the full row via an API call.
 - Only fires from triggers. Changes made outside your app (manual SQL, migrations) are invisible unless you add triggers for those tables too.
 - This is not logical replication. It is simpler, works on every Postgres provider, and needs no extensions or superuser access.
 
+#### When to use this instead of Redis pub/sub
+
+If your real-time events are driven by database writes and you do not need Redis for other extensions (presence, rate limiting, groups, cursors), the LISTEN/NOTIFY bridge is a simpler deployment: no Redis infrastructure, no separate pub/sub channel management, and your notifications are inherently tied to committed transactions. Use the Redis pub/sub bus when you need to broadcast events that do not originate from database writes, or when you are already running Redis for other extensions.
+
+---
+
+**Observability**
+
+## Prometheus metrics
+
+Exposes extension metrics in Prometheus text exposition format. No external dependencies. Zero overhead when not enabled -- every metric call uses optional chaining on a nullish reference, so V8 short-circuits on a single pointer check.
+
+#### Setup
+
+```js
+// src/lib/server/metrics.js
+import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';
+
+export const metrics = createMetrics({
+  prefix: 'myapp_',
+  mapTopic: (topic) => topic.startsWith('room:') ? 'room:*' : topic
+});
+```
+
+Pass the `metrics` object to any extension via its options:
+
+```js
+import { metrics } from './metrics.js';
+import { redis } from './redis.js';
+import { createPresence } from 'svelte-adapter-uws-extensions/redis/presence';
+import { createPubSubBus } from 'svelte-adapter-uws-extensions/redis/pubsub';
+import { createReplay } from 'svelte-adapter-uws-extensions/redis/replay';
+import { createRateLimit } from 'svelte-adapter-uws-extensions/redis/ratelimit';
+import { createGroup } from 'svelte-adapter-uws-extensions/redis/groups';
+import { createCursor } from 'svelte-adapter-uws-extensions/redis/cursor';
+
+export const bus = createPubSubBus(redis, { metrics });
+export const presence = createPresence(redis, { metrics, key: 'id' });
+export const replay = createReplay(redis, { metrics });
+export const limiter = createRateLimit(redis, { points: 10, interval: 1000, metrics });
+export const lobby = createGroup(redis, 'lobby', { metrics });
+export const cursors = createCursor(redis, { metrics });
+```
+
+#### Mounting the endpoint
+
+With uWebSockets.js:
+
+```js
+app.get('/metrics', metrics.handler);
+```
+
+Or use `metrics.serialize()` to get the raw text and serve it however you like.
+
+#### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `prefix` | `''` | Prefix for all metric names |
+| `mapTopic` | identity | Map topic names to bounded label values for cardinality control |
+| `defaultBuckets` | `[1, 5, 10, 25, 50, 100, 250, 500, 1000]` | Default histogram buckets |
+
+Metric names must match `[a-zA-Z_:][a-zA-Z0-9_:]*` and label names must match `[a-zA-Z_][a-zA-Z0-9_]*` (no `__` prefix). Invalid names throw at registration time. HELP text containing backslashes or newlines is escaped automatically.
+
+#### Cardinality control
+
+If your topics are user-generated (e.g. `room:abc123`), per-topic labels will grow unbounded. Use `mapTopic` to collapse them:
+
+```js
+const metrics = createMetrics({
+  mapTopic: (topic) => {
+    if (topic.startsWith('room:')) return 'room:*';
+    if (topic.startsWith('user:')) return 'user:*';
+    return topic;
+  }
+});
+```
+
+#### Metrics reference
+
+**Pub/sub bus**
+
+| Metric | Type | Description |
+|---|---|---|
+| `pubsub_messages_relayed_total` | counter | Messages relayed to Redis |
+| `pubsub_messages_received_total` | counter | Messages received from Redis |
+| `pubsub_echo_suppressed_total` | counter | Messages dropped by echo suppression |
+| `pubsub_relay_batch_size` | histogram | Relay batch size per flush |
+
+**Presence**
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `presence_joins_total` | counter | `topic` | Join events |
+| `presence_leaves_total` | counter | `topic` | Leave events |
+| `presence_heartbeats_total` | counter | | Heartbeat refresh cycles |
+| `presence_stale_cleaned_total` | counter | | Stale entries removed by cleanup |
+
+**Replay buffer (Redis and Postgres)**
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `replay_publishes_total` | counter | `topic` | Messages published |
+| `replay_messages_replayed_total` | counter | `topic` | Messages replayed to clients |
+| `replay_truncations_total` | counter | `topic` | Truncation events detected |
+
+**Rate limiting**
+
+| Metric | Type | Description |
+|---|---|---|
+| `ratelimit_allowed_total` | counter | Requests allowed |
+| `ratelimit_denied_total` | counter | Requests denied |
+| `ratelimit_bans_total` | counter | Bans applied |
+
+**Broadcast groups**
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `group_joins_total` | counter | `group` | Join events |
+| `group_joins_rejected_total` | counter | `group` | Joins rejected (full) |
+| `group_leaves_total` | counter | `group` | Leave events |
+| `group_publishes_total` | counter | `group` | Publish events |
+
+**Cursor**
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `cursor_updates_total` | counter | `topic` | Cursor update calls |
+| `cursor_broadcasts_total` | counter | `topic` | Broadcasts actually sent |
+| `cursor_throttled_total` | counter | `topic` | Updates deferred by throttle |
+
+**LISTEN/NOTIFY bridge**
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `notify_received_total` | counter | `channel` | Notifications received |
+| `notify_parse_errors_total` | counter | `channel` | Parse failures |
+| `notify_reconnects_total` | counter | | Reconnect attempts |
+
+---
+
+**Reliability**
+
+## Failure handling
+
+Every Redis and Postgres extension accepts an optional `breaker` option -- a shared [circuit breaker](#circuit-breaker) that tracks backend health across all extensions wired to it. When the breaker trips, each extension degrades differently depending on whether the operation is critical or best-effort:
+
+| Extension | Awaited operations (join, consume, publish) | Fire-and-forget operations |
+|---|---|---|
+| **Pub/sub bus** | `wrap().publish()` queues to local platform only; relay to Redis is skipped silently | Microtask relay flush is skipped entirely |
+| **Presence** | `join()` / `leave()` throw `CircuitBrokenError` | Heartbeat refresh and stale cleanup are skipped |
+| **Replay buffer** | `publish()` / `replay()` / `seq()` throw `CircuitBrokenError` | -- |
+| **Rate limiting** | `consume()` throws `CircuitBrokenError` (fail-closed -- requests are blocked, not allowed through) | -- |
+| **Broadcast groups** | `join()` / `leave()` throw `CircuitBrokenError` | Heartbeat refresh is skipped |
+| **Cursor** | -- | Hash writes and cross-instance relay are skipped; local throttle continues |
+| **LISTEN/NOTIFY** | `activate()` throws; auto-reconnect retries on its own interval | -- |
+
+The breaker is a three-state machine: **healthy** (all requests pass through) -> **broken** after N consecutive failures (all requests fail fast via `CircuitBrokenError`) -> **probing** after a timeout (one request is allowed through to test recovery) -> back to **healthy** on success. See [Circuit breaker](#circuit-breaker) for configuration.
+
+---
+
+## Circuit breaker
+
+Prevents thundering herd when a backend goes down. When Redis or Postgres becomes unreachable, every extension that uses the breaker fails fast instead of queueing up timeouts, and fire-and-forget operations (heartbeats, relay flushes, cursor broadcasts) are skipped entirely.
+
+Three states:
+- **healthy** -- everything works, requests go through
+- **broken** -- too many failures, requests fail fast via `CircuitBrokenError`
+- **probing** -- one request is allowed through to test if the backend is back
+
+#### Setup
+
+```js
+// src/lib/server/breaker.js
+import { createCircuitBreaker } from 'svelte-adapter-uws-extensions/breaker';
+
+export const breaker = createCircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 30000,
+  onStateChange: (from, to) => console.log(`circuit: ${from} -> ${to}`)
+});
+```
+
+Pass the same breaker to all extensions that share a backend:
+
+```js
+import { breaker } from './breaker.js';
+
+export const bus = createPubSubBus(redis, { breaker });
+export const presence = createPresence(redis, { breaker, key: 'id' });
+export const replay = createReplay(redis, { breaker });
+export const limiter = createRateLimit(redis, { points: 10, interval: 1000, breaker });
+```
+
+Failures from any extension contribute to the same breaker. When one trips it, all others fail fast.
+
+#### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `failureThreshold` | `5` | Consecutive failures before breaking |
+| `resetTimeout` | `30000` | Ms before transitioning from broken to probing |
+| `onStateChange` | - | Called on state transitions: `(from, to) => void` |
+
+#### API
+
+| Method / Property | Description |
+|---|---|
+| `breaker.state` | `'healthy'`, `'broken'`, or `'probing'` |
+| `breaker.isHealthy` | `true` only when state is `'healthy'` |
+| `breaker.failures` | Current consecutive failure count |
+| `breaker.guard()` | Throws `CircuitBrokenError` if the circuit is broken |
+| `breaker.success()` | Record a successful operation |
+| `breaker.failure()` | Record a failed operation |
+| `breaker.reset()` | Force back to healthy |
+| `breaker.destroy()` | Clear internal timers |
+
+#### How extensions use it
+
+Awaited operations (join, consume, publish) call `guard()` before the Redis/Postgres call, `success()` after, and `failure()` in the catch block. When the circuit is broken, `guard()` throws `CircuitBrokenError` and the operation never reaches the backend.
+
+Fire-and-forget operations (heartbeat refresh, relay flush, cursor broadcast) check `isHealthy` and skip entirely when the circuit is not healthy. This prevents piling up commands on a dead connection.
+
+#### Error handling
+
+```js
+import { CircuitBrokenError } from 'svelte-adapter-uws-extensions/breaker';
+
+try {
+  await replay.publish(platform, 'chat', 'msg', data);
+} catch (err) {
+  if (err instanceof CircuitBrokenError) {
+    // Backend is down -- degrade gracefully
+    platform.publish('chat', 'msg', data); // local-only delivery
+  }
+}
+```
+
 ---
 
 **Operations**
@@ -692,6 +955,14 @@ Tests use in-memory mocks for Redis and Postgres, no running services needed.
 
 ---
 
+## Related projects
+
+- [svelte-adapter-uws](https://github.com/lanteanio/svelte-adapter-uws) -- The core adapter this package extends. Single-process WebSocket pub/sub, presence, replay, and more for SvelteKit on uWebSockets.js.
+- [svelte-realtime](https://github.com/lanteanio/svelte-realtime) -- Opinionated full-stack starter built on the adapter. Auth, database, real-time CRUD, and deployment config out of the box.
+- [svelte-realtime-demo](https://github.com/lanteanio/svelte-realtime-demo) -- Live demo of svelte-realtime. [Try it here.](https://svelte-realtime-demo.lantean.io/)
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,99 +1,110 @@
-{
-  "name": "svelte-adapter-uws-extensions",
-  "version": "0.1.9",
-  "description": "Redis and Postgres extensions for svelte-adapter-uws - distributed pub/sub, replay buffers, presence tracking, rate limiting, groups, and DB change notifications",
-  "author": "Kevin Radziszewski",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lanteanio/svelte-adapter-uws-extensions.git"
-  },
-  "homepage": "https://github.com/lanteanio/svelte-adapter-uws-extensions#readme",
-  "bugs": {
-    "url": "https://github.com/lanteanio/svelte-adapter-uws-extensions/issues"
-  },
-  "type": "module",
-  "exports": {
-    "./redis": {
-      "types": "./redis/index.d.ts",
-      "default": "./redis/index.js"
-    },
-    "./redis/pubsub": {
-      "types": "./redis/pubsub.d.ts",
-      "default": "./redis/pubsub.js"
-    },
-    "./redis/replay": {
-      "types": "./redis/replay.d.ts",
-      "default": "./redis/replay.js"
-    },
-    "./redis/presence": {
-      "types": "./redis/presence.d.ts",
-      "default": "./redis/presence.js"
-    },
-    "./postgres": {
-      "types": "./postgres/index.d.ts",
-      "default": "./postgres/index.js"
-    },
-    "./postgres/replay": {
-      "types": "./postgres/replay.d.ts",
-      "default": "./postgres/replay.js"
-    },
-    "./postgres/notify": {
-      "types": "./postgres/notify.d.ts",
-      "default": "./postgres/notify.js"
-    },
-    "./redis/ratelimit": {
-      "types": "./redis/ratelimit.d.ts",
-      "default": "./redis/ratelimit.js"
-    },
-    "./redis/groups": {
-      "types": "./redis/groups.d.ts",
-      "default": "./redis/groups.js"
-    },
-    "./redis/cursor": {
-      "types": "./redis/cursor.d.ts",
-      "default": "./redis/cursor.js"
-    }
-  },
-  "files": [
-    "redis",
-    "postgres",
-    "shared",
-    "LICENSE",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "peerDependencies": {
-    "svelte-adapter-uws": ">=0.2.0"
-  },
-  "dependencies": {
-    "ioredis": "^5.0.0"
-  },
-  "optionalDependencies": {
-    "pg": "^8.0.0"
-  },
-  "devDependencies": {
-    "vitest": "^4.0.18"
-  },
-  "keywords": [
-    "svelte",
-    "sveltekit",
-    "uwebsockets",
-    "redis",
-    "postgres",
-    "pubsub",
-    "websocket",
-    "presence",
-    "replay",
-    "ratelimit",
-    "groups",
-    "cursor",
-    "notify"
-  ]
-}
+{
+  "name": "svelte-adapter-uws-extensions",
+  "version": "0.4.1",
+  "description": "Redis and Postgres extensions for svelte-adapter-uws - distributed pub/sub, replay buffers, presence tracking, rate limiting, groups, and DB change notifications",
+  "author": "Kevin Radziszewski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lanteanio/svelte-adapter-uws-extensions.git"
+  },
+  "homepage": "https://github.com/lanteanio/svelte-adapter-uws-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/lanteanio/svelte-adapter-uws-extensions/issues"
+  },
+  "type": "module",
+  "exports": {
+    "./redis": {
+      "types": "./redis/index.d.ts",
+      "default": "./redis/index.js"
+    },
+    "./redis/pubsub": {
+      "types": "./redis/pubsub.d.ts",
+      "default": "./redis/pubsub.js"
+    },
+    "./redis/replay": {
+      "types": "./redis/replay.d.ts",
+      "default": "./redis/replay.js"
+    },
+    "./redis/presence": {
+      "types": "./redis/presence.d.ts",
+      "default": "./redis/presence.js"
+    },
+    "./postgres": {
+      "types": "./postgres/index.d.ts",
+      "default": "./postgres/index.js"
+    },
+    "./postgres/replay": {
+      "types": "./postgres/replay.d.ts",
+      "default": "./postgres/replay.js"
+    },
+    "./postgres/notify": {
+      "types": "./postgres/notify.d.ts",
+      "default": "./postgres/notify.js"
+    },
+    "./redis/ratelimit": {
+      "types": "./redis/ratelimit.d.ts",
+      "default": "./redis/ratelimit.js"
+    },
+    "./redis/groups": {
+      "types": "./redis/groups.d.ts",
+      "default": "./redis/groups.js"
+    },
+    "./redis/cursor": {
+      "types": "./redis/cursor.d.ts",
+      "default": "./redis/cursor.js"
+    },
+    "./prometheus": {
+      "types": "./prometheus/index.d.ts",
+      "default": "./prometheus/index.js"
+    },
+    "./breaker": {
+      "types": "./shared/breaker.d.ts",
+      "default": "./shared/breaker.js"
+    }
+  },
+  "files": [
+    "redis",
+    "postgres",
+    "prometheus",
+    "shared",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "svelte-adapter-uws": ">=0.4.0"
+  },
+  "dependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "pg": "^8.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "uwebsockets",
+    "redis",
+    "postgres",
+    "pubsub",
+    "websocket",
+    "presence",
+    "replay",
+    "ratelimit",
+    "groups",
+    "cursor",
+    "notify",
+    "prometheus",
+    "metrics"
+  ]
+}

package/postgres/notify.d.ts

@@ -1,5 +1,7 @@
 import type { Platform } from 'svelte-adapter-uws';
 import type { PgClient } from './index.js';
+import type { MetricsRegistry } from '../prometheus/index.js';
+import type { CircuitBreaker } from '../shared/breaker.js';
 
 export interface NotifyBridgeOptions {
 	/** Postgres LISTEN channel name. Required. */
@@ -17,6 +19,10 @@ export interface NotifyBridgeOptions {
 
 	/** ms between reconnect attempts. @default 3000 */
 	reconnectInterval?: number;
+	/** Prometheus metrics registry. */
+	metrics?: MetricsRegistry;
+	/** Circuit breaker instance. */
+	breaker?: CircuitBreaker;
 }
 
 export interface NotifyBridge {

package/postgres/notify.js

@@ -81,9 +81,22 @@ export function createNotifyBridge(client, options) {
 
 	const channel = options.channel;
 	const autoReconnect = options.autoReconnect !== false;
-	const reconnectInterval = options.reconnectInterval || 3000;
+	const reconnectInterval = options.reconnectInterval ?? 3000;
+	if (typeof reconnectInterval !== 'number' || !Number.isFinite(reconnectInterval) || reconnectInterval < 0) {
+		throw new Error('notify bridge: reconnectInterval must be a non-negative number');
+	}
+	if (options.parse != null && typeof options.parse !== 'function') {
+		throw new Error('notify bridge: parse must be a function');
+	}
+	const isDefaultParser = !options.parse;
 	const parse = options.parse || defaultParse;
 
+	const b = options.breaker;
+	const m = options.metrics;
+	const mReceived = m?.counter('notify_received_total', 'Notifications received', ['channel']);
+	const mParseErrors = m?.counter('notify_parse_errors_total', 'Notification parse failures', ['channel']);
+	const mReconnects = m?.counter('notify_reconnects_total', 'Connection reconnect attempts');
+
 	/** @type {import('pg').Client | null} */
 	let conn = null;
 	/** @type {import('svelte-adapter-uws').Platform | null} */
@@ -104,19 +117,27 @@ export function createNotifyBridge(client, options) {
 
 	function onNotification(msg) {
 		if (msg.channel !== channel) return;
+		mReceived?.inc({ channel });
+		if (msg.payload && msg.payload.length > 7500) {
+			console.warn(
+				`[postgres/notify] payload on "${channel}" is ${msg.payload.length} bytes — ` +
+				'approaching the ~8000 byte Postgres NOTIFY limit'
+			);
+		}
 		try {
 			const result = parse(msg.payload, msg.channel);
 			if (result && activePlatform) {
-				// relay: false -- in clustered mode each worker has its own
-				// LISTEN connection, so relaying would duplicate delivery.
 				activePlatform.publish(result.topic, result.event, result.data, { relay: false });
+			} else if (!result && isDefaultParser) {
+				mParseErrors?.inc({ channel });
 			}
 		} catch {
-			// Parse errors are non-fatal -- skip the notification
+			mParseErrors?.inc({ channel });
 		}
 	}
 
 	async function connect() {
+		b?.guard();
 		try {
 			// Use a standalone Client instead of pool.connect() to avoid
 			// permanently holding a pool connection. LISTEN needs a persistent
@@ -130,7 +151,9 @@ export function createNotifyBridge(client, options) {
 			// pg requires channel name to be a valid identifier or quoted
 			// Use double-quoting to handle any channel name safely
 			await conn.query(`LISTEN "${channel.replace(/"/g, '""')}"`);
+			b?.success();
 		} catch (err) {
+			b?.failure(err);
 			if (conn) {
 				try { await conn.end(); } catch { /* ignore */ }
 			}
@@ -142,7 +165,8 @@ export function createNotifyBridge(client, options) {
 		}
 	}
 
-	function handleError() {
+	function handleError(err) {
+		b?.failure(err);
 		cleanup();
 		if (active && autoReconnect) {
 			scheduleReconnect();
@@ -151,6 +175,7 @@ export function createNotifyBridge(client, options) {
 
 	function scheduleReconnect() {
 		if (reconnectTimer) return;
+		mReconnects?.inc();
 		reconnectTimer = setTimeout(async () => {
 			reconnectTimer = null;
 			if (!active) return;