svelte-realtime 0.6.0-next.71 → 0.6.0-next.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.6.0-next.71",
+  "version": "0.6.0-next.72",
   "publishConfig": {
     "tag": "next"
   },
@@ -97,7 +97,7 @@
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "svelte-adapter-uws": "^0.6.0-next.60"
+    "svelte-adapter-uws": "^0.6.0-next.61"
   },
   "devDependencies": {
     "@playwright/test": "^1.59.1",

package/src/server/state.js

@@ -342,6 +342,12 @@ export const state = {
 	/** @type {any} Dead-letter store for undeliverable outbound webhooks (null = capture off). */
 	webhookDeadLetter: null,
 
+	/** @type {any} Retry budget for outbound webhooks (null = unrationed). */
+	webhookBudget: null,
+
+	/** @type {any} Endpoint-ejection breaker for outbound webhooks (null = no ejection). */
+	webhookBreaker: null,
+
 	/** @type {import('svelte-adapter-uws').Platform | null} Captured platform for dynamic derived recomputation */
 	derivedPlatform: null,
 

package/src/server/webhook-out.js

@@ -11,6 +11,21 @@ import { _IS_DEV } from './env.js';
 /** Re-exported for the registration-time SSRF validation message in webhooks.js. */
 export { redactUrl as _redactUrl };
 
+/**
+ * Assemble the optional delivery-control hooks for one webhook entry: the
+ * configured retry budget + endpoint-ejection breaker (wired via
+ * `configureWebhooks` / `realtime({ webhooks })`), keyed by the webhook's
+ * registration id so one endpoint's failures cannot trip or starve another.
+ * Returns undefined when neither is configured, so an unconfigured delivery is
+ * byte-identical to the bare call.
+ */
+function _webhookHooks(entry) {
+	const budget = state.webhookBudget;
+	const breaker = state.webhookBreaker;
+	if (!budget && !breaker) return undefined;
+	return { budget: budget || undefined, breaker: breaker || undefined, key: entry.id };
+}
+
 function _reportWebhookOutFailure(config, err, event, data, attempts) {
 	if (config.onFailure) {
 		try {
@@ -26,7 +41,7 @@ function _reportWebhookOutFailure(config, err, event, data, attempts) {
 
 export async function _fireWebhookOut(entry, topic, event, data, platform) {
 	void platform; // accepted for call-site parity; delivery reads entry.config
-	const r = await deliverWebhook(entry.config, topic, event, data);
+	const r = await deliverWebhook(entry.config, topic, event, data, _webhookHooks(entry));
 	if (r.ok) return;
 	_reportWebhookOutFailure(entry.config, r.err, event, data, r.attempts);
 	const store = state.webhookDeadLetter;
@@ -47,7 +62,7 @@ export async function _fireWebhookOut(entry, topic, event, data, platform) {
 }
 
 export async function _replayWebhookOut(entry, topic, event, data) {
-	const r = await deliverWebhook(entry.config, topic, event, data);
+	const r = await deliverWebhook(entry.config, topic, event, data, _webhookHooks(entry));
 	if (r.ok) return { ok: true };
 	return { ok: false, error: String((r.err && r.err.message) || r.err || 'unknown') };
 }

package/src/server/webhooks.js

@@ -1,5 +1,6 @@
 // @ts-check
 import { checkUrl } from 'svelte-adapter-uws/safe-url';
+import { createRetryBudget, createWebhookBreaker } from 'svelte-adapter-uws/plugins/webhooks';
 import { _redactUrl, _replayWebhookOut } from './webhook-out.js';
 import { state, _webhookOutById } from './state.js';
 import { createDeadLetterStore } from './dead-letter.js';
@@ -114,17 +115,29 @@ export const _webhooksOutboundRegister = function outbound(sources, config) {
 };
 
 /**
- * Configure the outbound-webhook plane. `deadLetter` enables the dead-letter
- * store that retains UNDELIVERABLE outbound-webhook events (retry-exhausted,
- * SSRF-blocked, etc.) for admin inspection + replay, instead of reporting then
- * dropping them. Off by default - a DLQ retains attacker-influenced event data,
- * so it is opt-in.
+ * Configure the outbound-webhook plane.
  *
- * Pass `true` for the default in-memory store, a store instance (e.g. a
- * Redis/Postgres store for a cluster) for shared durability, or `false`/`null`
- * to disable. Also wired from `realtime({ webhooks: { deadLetter } })`.
+ * `deadLetter` enables the dead-letter store that retains UNDELIVERABLE
+ * outbound-webhook events (retry-exhausted, SSRF-blocked, etc.) for admin
+ * inspection + replay, instead of reporting then dropping them. Off by default -
+ * a DLQ retains attacker-influenced event data, so it is opt-in.
  *
- * @param {{ deadLetter?: boolean | object | null }} [config]
+ * `budget` rations retry AMPLIFICATION so a storm of failing deliveries to one
+ * endpoint cannot launch unbounded retry work (the first attempt of each
+ * delivery always proceeds). `breaker` ejects a persistently-failing endpoint:
+ * an open circuit fast-fails to the dead-letter store without touching the
+ * network, and heals after a probe succeeds. Both are keyed by the webhook's
+ * registration id, so one endpoint cannot trip or starve another. Off by
+ * default.
+ *
+ * Each option takes `true` for the built-in single-instance default (an
+ * in-memory store / an in-process token bucket / an in-process breaker), an
+ * instance for a cluster (e.g. a Redis dead-letter store, or a shared
+ * budget/breaker coordinator) for cross-instance durability, or `false`/`null`
+ * to disable. Also wired from `realtime({ webhooks: { deadLetter, budget,
+ * breaker } })`.
+ *
+ * @param {{ deadLetter?: boolean | object | null, budget?: boolean | object | null, breaker?: boolean | object | null }} [config]
  */
 export function configureWebhooks(config = {}) {
 	if (config.deadLetter !== undefined) {
@@ -136,6 +149,31 @@ export function configureWebhooks(config = {}) {
 			state.webhookDeadLetter = null;
 		}
 	}
+	if (config.budget !== undefined) {
+		if (config.budget === true) {
+			if (!state.webhookBudget) state.webhookBudget = createRetryBudget();
+		} else if (config.budget && typeof config.budget === 'object') {
+			if (typeof config.budget.take !== 'function') {
+				throw new Error('[svelte-realtime] configureWebhooks({ budget }): a budget must have a take(key) method (or pass true for the built-in)');
+			}
+			state.webhookBudget = config.budget;
+		} else {
+			state.webhookBudget = null;
+		}
+	}
+	if (config.breaker !== undefined) {
+		if (config.breaker === true) {
+			if (!state.webhookBreaker) state.webhookBreaker = createWebhookBreaker();
+		} else if (config.breaker && typeof config.breaker === 'object') {
+			const b = config.breaker;
+			if (typeof b.guard !== 'function' || typeof b.success !== 'function' || typeof b.failure !== 'function') {
+				throw new Error('[svelte-realtime] configureWebhooks({ breaker }): a breaker must have guard(key), success(key), and failure(err, key) methods (or pass true for the built-in)');
+			}
+			state.webhookBreaker = b;
+		} else {
+			state.webhookBreaker = null;
+		}
+	}
 }
 
 /**

package/src/server.d.ts

@@ -4263,11 +4263,18 @@ export interface RealtimeConfig {
 	 * that retains UNDELIVERABLE outbound-webhook events (retry-exhausted,
 	 * SSRF-blocked, etc.) for admin inspection and replay, instead of reporting
 	 * then dropping them. Off by default (a DLQ retains attacker-influenced event
-	 * data). `true` uses the default in-memory store; a store instance gives a
-	 * cluster shared durable store; `false`/`null` disables. Equivalent to
-	 * `configureWebhooks({ deadLetter })`.
-	 */
-	webhooks?: { deadLetter?: boolean | DeadLetterStore | null } | null;
+	 * data). `webhooks.budget` rations retry amplification and `webhooks.breaker`
+	 * ejects a persistently-failing endpoint (fast-fail to the DLQ, healing after
+	 * a probe succeeds), both keyed by the webhook's registration id. Each takes
+	 * `true` for the built-in single-instance default, an instance for a cluster
+	 * (a shared store / budget / breaker), or `false`/`null` to disable.
+	 * Equivalent to `configureWebhooks({ deadLetter, budget, breaker })`.
+	 */
+	webhooks?: {
+		deadLetter?: boolean | DeadLetterStore | null;
+		budget?: boolean | import('svelte-adapter-uws/plugins/webhooks').RetryBudget | null;
+		breaker?: boolean | import('svelte-adapter-uws/plugins/webhooks').WebhookBreaker | null;
+	} | null;
 	/**
 	 * Opt-in protocol/contract version, an integer the app bumps only on a BREAKING
 	 * wire/contract change. Declare it identically here and in client `configure({
@@ -4344,12 +4351,19 @@ export interface DeadLetterStore {
 export function createDeadLetterStore(options?: { max?: number; ttlMs?: number }): DeadLetterStore;
 
 /**
- * Configure the outbound-webhook plane. `deadLetter: true` enables the default
- * in-memory dead-letter store; a store instance wires a custom/cluster store;
- * `false`/`null` disables capture (the default). Also wired from
+ * Configure the outbound-webhook plane. `deadLetter` captures undeliverable
+ * events; `budget` rations retry amplification; `breaker` ejects a
+ * persistently-failing endpoint (fast-fail to the DLQ, healing after a probe
+ * succeeds), keyed by the webhook's registration id. Each takes `true` for the
+ * built-in single-instance default, an instance for a cluster (a shared store /
+ * budget / breaker), or `false`/`null` to disable (the default). Also wired from
  * `realtime({ webhooks })`.
  */
-export function configureWebhooks(config?: { deadLetter?: boolean | DeadLetterStore | null }): void;
+export function configureWebhooks(config?: {
+	deadLetter?: boolean | DeadLetterStore | null;
+	budget?: boolean | import('svelte-adapter-uws/plugins/webhooks').RetryBudget | null;
+	breaker?: boolean | import('svelte-adapter-uws/plugins/webhooks').WebhookBreaker | null;
+}): void;
 
 /** The configured dead-letter store, or `null` when capture is off. */
 export function getDeadLetter(): DeadLetterStore | null;

package/src/server.js

@@ -3536,8 +3536,9 @@ export function realtime(config) {
 
 	if (bus !== undefined) _setBus(bus);
 	if (leader !== undefined) configureCron({ leader });
-	// Outbound-webhook plane: `webhooks.deadLetter` enables the dead-letter store
-	// (retain + admin-replay undeliverable webhook events). Off unless configured.
+	// Outbound-webhook plane: `webhooks.deadLetter` retains + admin-replays
+	// undeliverable events; `webhooks.budget`/`webhooks.breaker` ration retries
+	// and eject a failing endpoint. Off unless configured.
 	if (webhooks !== undefined) configureWebhooks(webhooks);
 	// Multi-tenancy opt-in: a resolver mapping the server-trusted authenticated
 	// user (ws.getUserData()) to a tenant id auto-scopes every topic and key.