svelte-adapter-uws-extensions 0.6.0-next.21 → 0.6.0-next.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws-extensions",
-  "version": "0.6.0-next.21",
+  "version": "0.6.0-next.22",
   "publishConfig": {
     "tag": "next"
   },

package/src/redis/ratelimit.d.ts

@@ -11,6 +11,14 @@ export interface RedisRateLimitOptions {
 	blockDuration?: number;
 	/** Key extraction mode. @default 'ip' */
 	keyBy?: 'ip' | 'connection' | ((ws: any) => string);
+	/**
+	 * Optional per-connection tenant resolver. When set, the bucket key is scoped by
+	 * the returned tenant id (joined to the key with a NUL, so it stays unambiguous even
+	 * for IPv6 keys), so two tenants sharing an IP / connection / custom key get
+	 * independent buckets. Return null/undefined for an unscoped connection; omit for a
+	 * single-tenant deploy (byte-identical).
+	 */
+	tenant?: (ws: any) => string | null | undefined;
 	/** Prometheus metrics registry. */
 	metrics?: MetricsRegistry;
 	/** Circuit breaker instance. */
@@ -29,14 +37,14 @@ export interface ConsumeResult {
 export interface RedisRateLimiter {
 	/** Attempt to consume tokens. */
 	consume(ws: any, cost?: number): Promise<ConsumeResult>;
-	/** Clear the bucket for a key. */
-	reset(key: string): Promise<void>;
-	/** Manually ban a key. */
-	ban(key: string, duration?: number): Promise<void>;
-	/** Remove a ban. */
-	unban(key: string): Promise<void>;
-	/** Reset all state. */
-	clear(): Promise<void>;
+	/** Clear the bucket for a key (optionally scoped to a tenant). */
+	reset(key: string, tenant?: string | null): Promise<void>;
+	/** Manually ban a key (optionally scoped to a tenant). */
+	ban(key: string, duration?: number, tenant?: string | null): Promise<void>;
+	/** Remove a ban (optionally scoped to a tenant). */
+	unban(key: string, tenant?: string | null): Promise<void>;
+	/** Reset all state, or only one tenant's buckets when a tenant id is given. */
+	clear(tenant?: string | null): Promise<void>;
 }
 
 /**

package/src/redis/ratelimit.js

@@ -42,6 +42,13 @@ return 1
  * @property {number} interval - Refill interval in milliseconds. Must be positive.
  * @property {number} [blockDuration=0] - Auto-ban duration in ms when exhausted. 0 = no ban.
  * @property {'ip' | 'connection' | ((ws: any) => string)} [keyBy='ip'] - Key extraction mode.
+ * @property {(ws: any) => (string | null | undefined)} [tenant] - Optional per-connection
+ *   tenant resolver. When set, the bucket key is scoped by the returned tenant id, so two
+ *   tenants sharing an IP / connection / custom key get independent buckets and a tenant's
+ *   admin ops (`reset` / `ban` / `unban` / `clear`) touch only that tenant. Return
+ *   null/undefined for an unscoped connection. Omit for a single-tenant deploy (byte-identical
+ *   to before). The id should be a delimiter-safe slug - it is joined to the key with a NUL,
+ *   so it stays unambiguous even when the key is an IPv6 address.
  */
 
 /**
@@ -54,10 +61,10 @@ return 1
 /**
  * @typedef {Object} RedisRateLimiter
  * @property {(ws: any, cost?: number) => Promise<ConsumeResult>} consume
- * @property {(key: string) => Promise<void>} reset
- * @property {(key: string, duration?: number) => Promise<void>} ban
- * @property {(key: string) => Promise<void>} unban
- * @property {() => Promise<void>} clear
+ * @property {(key: string, tenant?: string | null) => Promise<void>} reset
+ * @property {(key: string, duration?: number, tenant?: string | null) => Promise<void>} ban
+ * @property {(key: string, tenant?: string | null) => Promise<void>} unban
+ * @property {(tenant?: string | null) => Promise<void>} clear
  */
 
 /**
@@ -72,7 +79,7 @@ export function createRateLimit(client, options) {
 		throw new Error('redis ratelimit: options object is required');
 	}
 
-	const { points, interval, blockDuration = 0, keyBy = 'ip' } = options;
+	const { points, interval, blockDuration = 0, keyBy = 'ip', tenant } = options;
 
 	if (!Number.isInteger(points) || points <= 0) {
 		throw new Error('redis ratelimit: points must be a positive integer');
@@ -86,6 +93,9 @@ export function createRateLimit(client, options) {
 	if (keyBy !== 'ip' && keyBy !== 'connection' && typeof keyBy !== 'function') {
 		throw new Error("redis ratelimit: keyBy must be 'ip', 'connection', or a function");
 	}
+	if (tenant !== undefined && typeof tenant !== 'function') {
+		throw new Error('redis ratelimit: tenant must be a function (ws) => id | null');
+	}
 
 	const redis = client.redis;
 
@@ -96,9 +106,15 @@ export function createRateLimit(client, options) {
 
 	const b = options.breaker;
 	const m = options.metrics;
-	const mAllowed = m?.counter('ratelimit_allowed_total', 'Requests allowed');
-	const mDenied = m?.counter('ratelimit_denied_total', 'Requests denied');
-	const mBans = m?.counter('ratelimit_bans_total', 'Bans applied');
+	// When a tenant resolver is set, label the rate-limit counters by tenant so an
+	// operator can see per-tenant allow/deny/ban rates. Opt-in (no resolver -> no
+	// label, byte-identical series); the label is bounded by the metric's default
+	// max-series cardinality cap, so a tenant burst cannot blow up the registry.
+	const labelTenants = typeof tenant === 'function';
+	const tlabels = labelTenants ? ['tenant_id'] : undefined;
+	const mAllowed = m?.counter('ratelimit_allowed_total', 'Requests allowed', tlabels);
+	const mDenied = m?.counter('ratelimit_denied_total', 'Requests denied', tlabels);
+	const mBans = m?.counter('ratelimit_bans_total', 'Bans applied', tlabels);
 
 	// Per-connection keying uses a WeakMap to avoid leaks
 	const wsKeys = new WeakMap();
@@ -129,8 +145,18 @@ export function createRateLimit(client, options) {
 		return 'unknown';
 	}
 
-	function bucketKey(key) {
-		return client.key(SCRIPT_VERSION + ':ratelimit:' + key);
+	// The tenant segment (when a `tenant` resolver is set) is FIRST and NUL-delimited,
+	// so a validated id stays unambiguous even when the key is an IPv6 address (colons).
+	// Null tenant -> no segment, byte-identical to the single-tenant key space. The id is
+	// rejected if it contains the NUL delimiter (the one char that would let two distinct
+	// tenants collide on one bucket); this is the injection-safety the realtime tier
+	// validates at its own boundary, enforced here too so the property does not silently
+	// depend on the caller's resolver. The check short-circuits on the null (default) path.
+	function bucketKey(key, tenantId) {
+		if (tenantId && tenantId.indexOf('\0') !== -1) {
+			throw new Error('redis ratelimit: tenant id must not contain a NUL byte (it is the bucket-key delimiter)');
+		}
+		return client.key(SCRIPT_VERSION + ':ratelimit:' + (tenantId ? tenantId + '\0' : '') + key);
 	}
 
 	return {
@@ -139,16 +165,18 @@ export function createRateLimit(client, options) {
 				throw new Error('redis ratelimit: cost must be a positive integer');
 			}
 			const key = resolveKey(ws);
+			const tenantId = tenant ? tenant(ws) : null;
 
 			const result = await withBreaker(b, () =>
-				redis.eval(CONSUME_SCRIPT, 1, bucketKey(key), points, interval, cost, blockDuration)
+				redis.eval(CONSUME_SCRIPT, 1, bucketKey(key, tenantId), points, interval, cost, blockDuration)
 			);
 
 			const allowed = result[0] === 1;
+			const labels = labelTenants ? { tenant_id: tenantId || '' } : undefined;
 			if (allowed) {
-				mAllowed?.inc();
+				mAllowed?.inc(labels);
 			} else {
-				mDenied?.inc();
+				mDenied?.inc(labels);
 			}
 
 			return {
@@ -158,24 +186,28 @@ export function createRateLimit(client, options) {
 			};
 		},
 
-		async reset(key) {
-			await withBreaker(b, () => redis.del(bucketKey(key)));
+		async reset(key, tenantId) {
+			await withBreaker(b, () => redis.del(bucketKey(key, tenantId)));
 		},
 
-		async ban(key, duration) {
+		async ban(key, duration, tenantId) {
 			const dur = duration ?? (blockDuration || 60000);
 			if (dur <= 0) throw new Error('redis ratelimit: ban duration must be positive');
-			const bk = bucketKey(key);
+			const bk = bucketKey(key, tenantId);
 			await withBreaker(b, () => redis.eval(BAN_SCRIPT, 1, bk, dur, points, interval));
-			mBans?.inc();
+			mBans?.inc(labelTenants ? { tenant_id: tenantId || '' } : undefined);
 		},
 
-		async unban(key) {
-			await withBreaker(b, () => redis.hset(bucketKey(key), 'bannedUntil', 0));
+		async unban(key, tenantId) {
+			await withBreaker(b, () => redis.hset(bucketKey(key, tenantId), 'bannedUntil', 0));
 		},
 
-		async clear() {
-			await withBreaker(b, () => scanAndUnlink(redis, client.key(SCRIPT_VERSION + ':ratelimit:*')));
+		// No tenant -> clears the whole key space (every tenant's buckets too, since the
+		// glob `*` spans the NUL-delimited tenant segments). Pass a tenant id to clear
+		// only that tenant's buckets.
+		async clear(tenantId) {
+			const suffix = tenantId ? tenantId + '\0*' : '*';
+			await withBreaker(b, () => scanAndUnlink(redis, client.key(SCRIPT_VERSION + ':ratelimit:' + suffix)));
 		}
 	};
 }

package/src/shared/breaker.d.ts

@@ -12,20 +12,29 @@ export interface CircuitBreakerOptions {
 }
 
 export interface CircuitBreaker {
-	/** Current state. */
+	/**
+	 * State is partitioned by an optional string `key`, so one key (e.g. a tenant) can
+	 * break without tripping the others. The default key `''` is the single global
+	 * breaker - every method is byte-identical for callers that pass no key.
+	 */
+	/** State of the default (`''`) key. */
 	readonly state: 'healthy' | 'broken' | 'probing';
-	/** True only when state is healthy. */
+	/** True only when the default key's state is healthy. */
 	readonly isHealthy: boolean;
-	/** Current consecutive failure count. */
+	/** Default key's consecutive failure count. */
 	readonly failures: number;
-	/** Throws CircuitBrokenError if the circuit is broken. */
-	guard(): void;
-	/** Record a successful operation. May transition to healthy. */
-	success(): void;
-	/** Record a failed operation. May transition to broken. */
-	failure(err?: any): void;
-	/** Force back to healthy state. */
-	reset(): void;
+	/** State for a given key (default `''`). */
+	stateOf(key?: string): 'healthy' | 'broken' | 'probing';
+	/** Failure count for a given key (default `''`). */
+	failuresOf(key?: string): number;
+	/** Throws CircuitBrokenError if the circuit for `key` (default `''`) is broken. */
+	guard(key?: string): void;
+	/** Record a successful operation for `key`. May transition to healthy. */
+	success(key?: string): void;
+	/** Record a failed operation for `key`. May transition to broken. */
+	failure(err?: any, key?: string): void;
+	/** Force `key` (default `''`) back to healthy state. */
+	reset(key?: string): void;
 	/**
 	 * Register a state-transition listener. Multiple subscribers are
 	 * supported and the constructor-time `onStateChange` callback (if
@@ -40,9 +49,10 @@ export interface CircuitBreaker {
 
 /**
  * Run an async operation through a breaker. Guards before, records
- * success/failure after. Pass null/undefined breaker to skip.
+ * success/failure after. Pass null/undefined breaker to skip. The optional `key`
+ * partitions the breaker state (default `''` = the global breaker).
  */
-export function withBreaker<T>(breaker: CircuitBreaker | null | undefined, fn: () => Promise<T>): Promise<T>;
+export function withBreaker<T>(breaker: CircuitBreaker | null | undefined, fn: () => Promise<T>, key?: string): Promise<T>;
 
 /**
  * Create a circuit breaker.

package/src/shared/breaker.js

@@ -14,7 +14,7 @@
  * @module svelte-adapter-uws-extensions/breaker
  */
 
-import { MAX_BREAKER_LISTENERS } from './caps.js';
+import { MAX_BREAKER_LISTENERS, MAX_BREAKER_KEYS } from './caps.js';
 import { setTimer, clearTimer } from './runtime.js';
 
 export class CircuitBrokenError extends Error {
@@ -32,16 +32,24 @@ export class CircuitBrokenError extends Error {
  */
 
 /**
+ * Per-KEY circuit breaker. State is partitioned by an optional string key, so one
+ * key (e.g. a tenant) can break without tripping the others. The default key `''`
+ * is the single global breaker - every method is byte-identical for callers that
+ * pass no key, so existing shared-infra call sites are unchanged. A caller
+ * protecting a tenant-specific resource passes the tenant id to isolate its state.
+ *
  * @typedef {Object} CircuitBreaker
- * @property {'healthy' | 'broken' | 'probing'} state
- * @property {boolean} isHealthy - True only when state === 'healthy'
- * @property {number} failures - Current consecutive failure count
- * @property {() => void} guard - Throws CircuitBrokenError if broken
- * @property {() => void} success - Record a successful operation
- * @property {(err?: any) => void} failure - Record a failed operation
- * @property {() => void} reset - Force back to healthy
+ * @property {'healthy' | 'broken' | 'probing'} state - State of the default (`''`) key
+ * @property {boolean} isHealthy - True only when the default key's state === 'healthy'
+ * @property {number} failures - Default key's consecutive failure count
+ * @property {(key?: string) => ('healthy' | 'broken' | 'probing')} stateOf - State for a given key
+ * @property {(key?: string) => number} failuresOf - Failure count for a given key
+ * @property {(key?: string) => void} guard - Throws CircuitBrokenError if that key is broken
+ * @property {(key?: string) => void} success - Record a successful operation for a key
+ * @property {(err?: any, key?: string) => void} failure - Record a failed operation for a key
+ * @property {(key?: string) => void} reset - Force a key back to healthy
  * @property {(handler: (from: string, to: string) => void) => () => void} subscribe - Register a state-transition listener; returns an unsubscribe function
- * @property {() => void} destroy - Clear internal timers
+ * @property {() => void} destroy - Clear internal timers (all keys)
  */
 
 /**
@@ -63,17 +71,20 @@ export class CircuitBrokenError extends Error {
  */
 /**
  * Run an async operation through a breaker. Guards before, records
- * success/failure after. Pass null/undefined breaker to skip.
+ * success/failure after. Pass null/undefined breaker to skip. The optional `key`
+ * partitions the breaker state (default `''` = the global breaker) - shared-infra
+ * call sites pass no key; a caller protecting a tenant-specific resource passes the
+ * tenant id so its failures cannot trip another tenant's breaker.
  */
-export async function withBreaker(b, fn) {
+export async function withBreaker(b, fn, key) {
 	if (!b) return fn();
-	b.guard();
+	b.guard(key);
 	try {
 		const result = await fn();
-		b.success();
+		b.success(key);
 		return result;
 	} catch (err) {
-		b.failure(err);
+		b.failure(err, key);
 		throw err;
 	}
 }
@@ -90,75 +101,105 @@ export function createCircuitBreaker(options = {}) {
 		throw new Error('circuit breaker: resetTimeout must be a non-negative number');
 	}
 
-	let state = 'healthy';
-	let failures = 0;
-	let probeAllowed = false;
-	let resetTimer = null;
+	// Per-key state. The default key '' is the single global breaker - every existing
+	// (no-key) caller hits exactly this one slot, so behavior is byte-identical.
+	/** @type {Map<string, { state: string, failures: number, probeAllowed: boolean, resetTimer: any }>} */
+	const states = new Map();
+	function stateFor(key) {
+		const k = key || '';
+		let s = states.get(k);
+		if (!s) {
+			// Backstop against unbounded key growth: at the cap, evict the oldest
+			// non-default keyed state (the '' global key is never evicted). A healthy
+			// evicted key simply recreates on next access; an evicted broken key is
+			// treated as healthy until it re-breaks - bounded graceful degradation,
+			// the same trade-off as the rate-limiter's maxBuckets.
+			if (states.size >= MAX_BREAKER_KEYS) {
+				for (const existing of states.keys()) {
+					if (existing !== '') {
+						const old = states.get(existing);
+						if (old && old.resetTimer) clearTimer(old.resetTimer);
+						states.delete(existing);
+						break;
+					}
+				}
+			}
+			s = { state: 'healthy', failures: 0, probeAllowed: false, resetTimer: null };
+			states.set(k, s);
+		}
+		return s;
+	}
 
 	const listeners = new Set();
 	if (onStateChange) listeners.add(onStateChange);
 
-	function transition(to) {
-		const from = state;
+	function transition(s, to) {
+		const from = s.state;
 		if (from === to) return;
-		state = to;
+		s.state = to;
 		for (const listener of listeners) {
 			try { listener(from, to); } catch { /* don't let one listener break the others */ }
 		}
 	}
 
-	function scheduleProbe() {
-		clearTimer(resetTimer);
-		resetTimer = setTimer(() => {
-			resetTimer = null;
-			probeAllowed = true;
-			transition('probing');
+	function scheduleProbe(s) {
+		clearTimer(s.resetTimer);
+		s.resetTimer = setTimer(() => {
+			s.resetTimer = null;
+			s.probeAllowed = true;
+			transition(s, 'probing');
 		}, resetTimeout);
-		if (resetTimer.unref) resetTimer.unref();
+		if (s.resetTimer.unref) s.resetTimer.unref();
 	}
 
 	return {
-		get state() { return state; },
-		get isHealthy() { return state === 'healthy'; },
-		get failures() { return failures; },
-
-		guard() {
-			if (state === 'healthy') return;
-			if (state === 'probing' && probeAllowed) {
-				probeAllowed = false;
+		get state() { return stateFor('').state; },
+		get isHealthy() { return stateFor('').state === 'healthy'; },
+		get failures() { return stateFor('').failures; },
+		stateOf(key) { return stateFor(key).state; },
+		failuresOf(key) { return stateFor(key).failures; },
+
+		guard(key) {
+			const s = stateFor(key);
+			if (s.state === 'healthy') return;
+			if (s.state === 'probing' && s.probeAllowed) {
+				s.probeAllowed = false;
 				return;
 			}
 			throw new CircuitBrokenError();
 		},
 
-		success() {
-			if (state === 'probing') {
-				clearTimer(resetTimer);
-				resetTimer = null;
-				failures = 0;
-				transition('healthy');
-			} else if (state === 'healthy') {
-				failures = 0;
+		success(key) {
+			const s = stateFor(key);
+			if (s.state === 'probing') {
+				clearTimer(s.resetTimer);
+				s.resetTimer = null;
+				s.failures = 0;
+				transition(s, 'healthy');
+			} else if (s.state === 'healthy') {
+				s.failures = 0;
 			}
 		},
 
-		failure() {
-			if (failures < failureThreshold) failures++;
-			if (state === 'probing') {
-				transition('broken');
-				scheduleProbe();
-			} else if (state === 'healthy' && failures >= failureThreshold) {
-				transition('broken');
-				scheduleProbe();
+		failure(err, key) {
+			const s = stateFor(key);
+			if (s.failures < failureThreshold) s.failures++;
+			if (s.state === 'probing') {
+				transition(s, 'broken');
+				scheduleProbe(s);
+			} else if (s.state === 'healthy' && s.failures >= failureThreshold) {
+				transition(s, 'broken');
+				scheduleProbe(s);
 			}
 		},
 
-		reset() {
-			clearTimer(resetTimer);
-			resetTimer = null;
-			failures = 0;
-			probeAllowed = false;
-			transition('healthy');
+		reset(key) {
+			const s = stateFor(key);
+			clearTimer(s.resetTimer);
+			s.resetTimer = null;
+			s.failures = 0;
+			s.probeAllowed = false;
+			transition(s, 'healthy');
 		},
 
 		subscribe(handler) {
@@ -176,8 +217,10 @@ export function createCircuitBreaker(options = {}) {
 		},
 
 		destroy() {
-			clearTimer(resetTimer);
-			resetTimer = null;
+			for (const s of states.values()) {
+				clearTimer(s.resetTimer);
+				s.resetTimer = null;
+			}
 		}
 	};
 }

package/src/shared/caps.js

@@ -100,6 +100,14 @@ export const MAX_TASK_HANDLERS = 10_000;
 /** `breaker.subscribe(handler)` listeners on a single breaker. */
 export const MAX_BREAKER_LISTENERS = 10_000;
 
+/**
+ * Distinct per-key state slots on a single breaker (the default `''` global key
+ * plus one per caller-supplied key, e.g. a tenant). A backstop against unbounded
+ * growth if a caller ever keys the breaker by an untrusted/unbounded value; the
+ * intended key sources (tenant ids) are bounded well below this.
+ */
+export const MAX_BREAKER_KEYS = 10_000;
+
 /**
  * Defense-in-depth cap on the idempotency-store key after framework-level
  * namespacing. Matches the worst-case `rpc:<path>:<256-char-user-key>` /