bazis 0.96.1

package/core/websocket/WsRateLimiter.ts

@@ -0,0 +1,101 @@
+/**
+ * Minimal in-process fixed-window limiter for WebSocket admission and traffic.
+ * Single-node; a clustered deployment would track windows in the adapter.
+ */
+export interface WsRateLimiterOptions {
+  readonly maxBuckets?: number;
+  readonly purgeIntervalMs?: number;
+}
+
+export interface WsRateLimiterStats {
+  readonly buckets: number;
+}
+
+export class WsRateLimiter {
+  private readonly buckets = new Map<string, { count: number; resetAt: number }>();
+  private readonly maxBuckets: number;
+  private readonly purgeIntervalMs: number;
+  private nextPurgeAt = 0;
+
+  public constructor(options: WsRateLimiterOptions = {}) {
+    this.maxBuckets = positiveInteger(options.maxBuckets, 10_000);
+    this.purgeIntervalMs = nonNegativeInteger(options.purgeIntervalMs, 60_000);
+  }
+
+  /** Returns true if the call is allowed; false when the window is exhausted. */
+  public check(key: string, limit: number, windowMs: number): boolean {
+    const now = Date.now();
+    if (now >= this.nextPurgeAt || this.buckets.size >= this.maxBuckets) {
+      this.purgeExpired(now);
+    }
+    const bucket = this.buckets.get(key);
+    if (!bucket || now >= bucket.resetAt) {
+      this.ensureCapacity();
+      this.buckets.set(key, { count: 1, resetAt: now + windowMs });
+      return true;
+    }
+    if (bucket.count >= limit) {
+      return false;
+    }
+    bucket.count += 1;
+    return true;
+  }
+
+  /** Drops a key's window (e.g. on disconnect). */
+  public forget(key: string): void {
+    this.buckets.delete(key);
+  }
+
+  public forgetMany(keys: Iterable<string>): void {
+    for (const key of keys) {
+      this.buckets.delete(key);
+    }
+  }
+
+  public clear(): void {
+    this.buckets.clear();
+    this.nextPurgeAt = 0;
+  }
+
+  public purgeExpired(now = Date.now()): number {
+    let purged = 0;
+    for (const [key, bucket] of this.buckets) {
+      if (now >= bucket.resetAt) {
+        this.buckets.delete(key);
+        purged += 1;
+      }
+    }
+    this.nextPurgeAt = now + this.purgeIntervalMs;
+    return purged;
+  }
+
+  public getStats(): WsRateLimiterStats {
+    this.purgeExpired();
+    return { buckets: this.buckets.size };
+  }
+
+  private ensureCapacity(): void {
+    if (this.buckets.size < this.maxBuckets) {
+      return;
+    }
+    let oldestKey: string | undefined;
+    let oldestReset = Number.POSITIVE_INFINITY;
+    for (const [key, bucket] of this.buckets) {
+      if (bucket.resetAt < oldestReset) {
+        oldestKey = key;
+        oldestReset = bucket.resetAt;
+      }
+    }
+    if (oldestKey !== undefined) {
+      this.buckets.delete(oldestKey);
+    }
+  }
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+function nonNegativeInteger(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
+}

package/core/websocket/adapter/adapter.interface.ts

@@ -0,0 +1,45 @@
+import type { SessionState } from "../session-manager";
+import type { ReliableRoomDelivery } from "../reliable-delivery";
+
+export interface WebSocketAdapterHooks {
+  /** Deliver payload to all local subscribers of topic (Bun server.publish). */
+  localPublish: (topic: string, payload: Uint8Array) => void;
+  /** Advisory wake-up only; persisted mailboxes are also polled. */
+  deliveriesReady?: (sids: readonly string[]) => void;
+}
+
+export interface WebSocketAdapter {
+  readonly name: string;
+  readonly instanceId: string;
+  readonly reliableRooms?: ReliableRoomDelivery;
+  /** Readiness of the backing store; rejection means unavailable. */
+  healthCheck?(): Promise<void>;
+
+  initialize(hooks: WebSocketAdapterHooks): Promise<void>;
+
+  /** Fan-out to all nodes; each node calls localPublish for local subscribers. */
+  publish(topic: string, payload: Uint8Array): Promise<void>;
+
+  /** Persist only when `state.revision` is newer than the stored revision. */
+  saveSession(state: SessionState): Promise<void>;
+  /**
+   * Optional optimistic claim used by distributed adapters when a physical
+   * connection takes ownership of a session. Implementations must only store
+   * `state` when the currently persisted revision equals `expectedRevision`.
+   * Returning `false` keeps the existing owner. Older adapters remain valid;
+   * the runtime falls back to ordered `saveSession` calls on one node.
+   */
+  compareAndSwapSession?(state: SessionState, expectedRevision: number): Promise<boolean>;
+  loadSession(sid: string): Promise<SessionState | null>;
+  /**
+   * Deletes a session. Version-aware distributed adapters should retain a
+   * tombstone at `revision` so a delayed older save cannot resurrect it.
+   */
+  deleteSession(sid: string, revision?: number): Promise<void>;
+
+  close(): Promise<void>;
+}
+
+export function createInstanceId(prefix = "bazis"): string {
+  return `${prefix}-${process.pid}-${crypto.randomUUID()}`;
+}

package/core/websocket/adapter/in-memory.adapter.ts

@@ -0,0 +1,190 @@
+import { SessionCapacityError, type SessionState } from "../session-manager";
+import { localSessionCreationOrder } from "../session-creation";
+import {
+  createInstanceId,
+  type WebSocketAdapter,
+  type WebSocketAdapterHooks,
+} from "./adapter.interface";
+
+export interface InMemoryWebSocketAdapterOptions {
+  /** Bound for live sessions. Default 10,000. Deletion history has its own cap. */
+  readonly maxEntries?: number;
+  /** Maximum deletion markers before conservative compaction. Default maxEntries. */
+  readonly maxTombstones?: number;
+  /** Initial-write/deletion protection window. Default 60 seconds. */
+  readonly tombstoneTtlMs?: number;
+}
+
+export class InMemoryWebSocketAdapter implements WebSocketAdapter {
+  readonly name = "in-memory";
+  readonly instanceId = createInstanceId();
+
+  private hooks: WebSocketAdapterHooks | null = null;
+  private readonly sessions = new Map<string, SessionState>();
+  private readonly tombstones = new Map<string, { revision: number; expiresAt: number; createdAt: number; creationToken?: string }>();
+  private readonly maxEntries: number;
+  private readonly maxTombstones: number;
+  private readonly tombstoneTtlMs: number;
+  private creationFloor = 0;
+  private legacyCreationFloor = Number.NEGATIVE_INFINITY;
+  private closed = false;
+
+  constructor(options: InMemoryWebSocketAdapterOptions = {}) {
+    this.maxEntries = positiveInteger(options.maxEntries, 10_000, "maxEntries");
+    this.maxTombstones = positiveInteger(options.maxTombstones, this.maxEntries, "maxTombstones");
+    this.tombstoneTtlMs = positiveInteger(options.tombstoneTtlMs, 60_000, "tombstoneTtlMs");
+  }
+
+  async initialize(hooks: WebSocketAdapterHooks): Promise<void> {
+    this.closed = false;
+    this.hooks = hooks;
+  }
+
+  /**
+   * Single-node: room fan-out is already delivered locally by the originating
+   * socket's `ws.publish`, so cross-node publish is a no-op. (`localPublish`
+   * exists for real multi-node adapters that receive off a bus.)
+   */
+  async publish(_topic: string, _payload: Uint8Array): Promise<void> {
+    void this.hooks;
+  }
+
+  async saveSession(state: SessionState): Promise<void> {
+    if (this.closed) return;
+    this.purgeTombstones();
+    const current = this.sessions.get(state.sid);
+    const revision = state.revision ?? 0;
+    if (
+      (!current && !this.canCreate(state))
+      || (current && (current.createdAt !== state.createdAt || current.creationToken !== state.creationToken))
+      || (current?.revision ?? 0) >= revision
+      || (this.tombstones.get(state.sid)?.revision ?? -1) >= revision
+    ) {
+      return;
+    }
+    this.ensureCapacity(state.sid);
+    this.sessions.set(state.sid, structuredClone(state));
+    this.tombstones.delete(state.sid);
+  }
+
+  async compareAndSwapSession(state: SessionState, expectedRevision: number): Promise<boolean> {
+    if (this.closed) return false;
+    this.purgeTombstones();
+    const current = this.sessions.get(state.sid);
+    const currentRevision = current?.revision ?? this.tombstones.get(state.sid)?.revision ?? 0;
+    if (
+      currentRevision !== expectedRevision
+      || (state.revision ?? 0) <= expectedRevision
+      || (!current && !this.canCreate(state))
+      || (current && (current.createdAt !== state.createdAt || current.creationToken !== state.creationToken))
+    ) {
+      return false;
+    }
+    this.ensureCapacity(state.sid);
+    this.sessions.set(state.sid, structuredClone(state));
+    this.tombstones.delete(state.sid);
+    return true;
+  }
+
+  async loadSession(sid: string): Promise<SessionState | null> {
+    this.purgeTombstones();
+    const state = this.sessions.get(sid);
+    return state ? structuredClone(state) : null;
+  }
+
+  async deleteSession(sid: string, revision?: number): Promise<void> {
+    if (this.closed) return;
+    this.purgeTombstones();
+    const current = this.sessions.get(sid);
+    const currentRevision = current?.revision ?? 0;
+    if (revision !== undefined && revision < currentRevision) {
+      return;
+    }
+    const previous = this.tombstones.get(sid);
+    const tombstoneRevision = Math.max(
+      previous?.revision ?? 0,
+      revision ?? currentRevision + 1,
+    );
+    // Once a session's creation window is over, an absent SID cannot be
+    // restored by its old snapshots. No per-SID marker is needed beyond it.
+    const expiresAt = current
+      ? current.createdAt + this.tombstoneTtlMs
+      : previous?.expiresAt ?? Date.now() + this.tombstoneTtlMs;
+    const marker = { revision: tombstoneRevision, expiresAt,
+      createdAt: current?.createdAt ?? previous?.createdAt ?? Date.now(),
+      creationToken: current?.creationToken ?? previous?.creationToken };
+    if (expiresAt <= Date.now()) {
+      this.sessions.delete(sid);
+      this.tombstones.delete(sid);
+      this.compact(marker);
+      return;
+    }
+    this.sessions.delete(sid);
+    this.tombstones.set(sid, marker);
+    while (this.tombstones.size > this.maxTombstones) {
+      const [oldestSid, oldest] = this.tombstones.entries().next().value!;
+      this.compact(oldest);
+      this.tombstones.delete(oldestSid);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    this.hooks = null;
+    for (const state of this.sessions.values()) this.compact(state);
+    for (const marker of this.tombstones.values()) this.compact(marker);
+    this.sessions.clear();
+    this.tombstones.clear();
+  }
+
+  /** DevTools: count of sessions stored in adapter. */
+  sessionCount(): number {
+    return this.sessions.size;
+  }
+
+  private canCreate(state: SessionState): boolean {
+    // A deleted SID is never reused, including by a snapshot with a larger
+    // revision. Once the marker is compacted, the creation floor takes over.
+    if (this.tombstones.has(state.sid)) return false;
+    const order = localSessionCreationOrder(state.creationToken);
+    if (order !== undefined) return order > this.creationFloor;
+    return Number.isFinite(state.createdAt)
+      && state.createdAt > this.legacyCreationFloor
+      && state.createdAt > Date.now() - this.tombstoneTtlMs;
+  }
+
+  private compact(state: { createdAt: number; creationToken?: string }): void {
+    const order = localSessionCreationOrder(state.creationToken);
+    if (order !== undefined) this.creationFloor = Math.max(this.creationFloor, order);
+    this.legacyCreationFloor = Math.max(this.legacyCreationFloor, state.createdAt);
+  }
+
+  private purgeTombstones(): void {
+    const now = Date.now();
+    for (const [sid, tombstone] of this.tombstones) {
+      if (tombstone.expiresAt <= now) {
+        this.compact(tombstone);
+        this.tombstones.delete(sid);
+      }
+    }
+  }
+
+  private ensureCapacity(sid: string): void {
+    if (
+      !this.sessions.has(sid)
+      && this.sessions.size >= this.maxEntries
+    ) {
+      throw new SessionCapacityError(this.maxEntries);
+    }
+  }
+}
+
+function positiveInteger(value: number | undefined, fallback: number, field: string): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`WebSocket in-memory ${field} must be a positive integer.`);
+  }
+  return value;
+}
+
+export const inMemoryWebSocketAdapter = new InMemoryWebSocketAdapter();

package/core/websocket/adapter/redis-delivery-scripts.ts

@@ -0,0 +1,135 @@
+// Shared key encoding matches encodeURIComponent used by the session adapter.
+export const KEYS = `
+local function escape(value)
+  return (value:gsub("[^%w%-_%.!~*'()]", function(c) return string.format('%%%02X', string.byte(c)) end))
+end
+local function sessionKey(prefix, sid) return prefix .. ':session:' .. escape(sid) end
+local function queueKey(prefix, sid) return prefix .. ':delivery:' .. escape(sid) end
+local function roomKey(prefix, ns, room) return prefix .. ':room:' .. ns .. string.char(0) .. room end
+local clock = redis.call('TIME')
+local now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)
+`;
+
+// Called only after a successful session revision/identity check.
+export const UPDATE_ROOMS = `
+local previous = raw and cjson.decode(raw) or nil
+local old = previous and previous.state and cjson.decode(previous.state) or nil
+if old then
+  for _, room in ipairs(old.rooms or {}) do redis.call('ZREM', roomKey(ARGV[4], old.namespace, room), old.sid) end
+end
+for _, room in ipairs(next.rooms or {}) do
+  local key = roomKey(ARGV[4], next.namespace, room)
+  local remaining = redis.call('PTTL', key)
+  redis.call('ZADD', key, next.expiresAt, next.sid)
+  redis.call('PEXPIREAT', key, math.max(next.expiresAt, now + math.max(0, remaining)))
+end
+redis.call('PEXPIREAT', queueKey(ARGV[4], next.sid), next.expiresAt)
+`;
+
+export const DELETE_ROOMS = `
+if current and current.state then
+  local old = cjson.decode(current.state)
+  for _, room in ipairs(old.rooms or {}) do redis.call('ZREM', roomKey(ARGV[3], old.namespace, room), old.sid) end
+end
+redis.call('DEL', queueKey(ARGV[3], ARGV[4]))
+`;
+
+export const PUBLISH = KEYS + `
+local prefix = ARGV[1]
+local request = cjson.decode(ARGV[2])
+local limits = cjson.decode(ARGV[3])
+local op = prefix .. ':operation:' .. request.messageId
+local previous = redis.call('GET', op)
+if previous then
+  local record = cjson.decode(previous)
+  if record.fingerprint ~= ARGV[4] then return {'MESSAGE_ID_CONFLICT'} end
+  return {'OK', tostring(record.recipients), '1'}
+end
+if request.expiresAt <= now or request.expiresAt > now + 60000 then return {'EXPIRED_PUBLICATION'} end
+local ops = prefix .. ':operations'
+redis.call('ZREMRANGEBYSCORE', ops, '-inf', now)
+if redis.call('ZCARD', ops) >= limits.maxOperations then return {'OPERATION_CAPACITY'} end
+local room = roomKey(prefix, request.namespace, request.room)
+redis.call('ZREMRANGEBYSCORE', room, '-inf', now)
+local members = redis.call('ZRANGE', room, 0, limits.maxRecipients + 1)
+local recipients = {}
+local packet = ARGV[5]
+local queues = {}
+for _, sid in ipairs(members) do
+  if sid ~= request.excludeSid then
+    local raw = redis.call('GET', sessionKey(prefix, sid))
+    local record = raw and cjson.decode(raw) or nil
+    local state = record and record.state and cjson.decode(record.state) or nil
+    if state and state.expiresAt > now then
+      if state.replayDelivery ~= 'client-ack' then return {'RECIPIENT_REQUIRES_ACK'} end
+      table.insert(recipients, sid)
+      if #recipients > limits.maxRecipients or #recipients * #packet > limits.maxFanoutBytes then return {'FANOUT_CAPACITY'} end
+      local key = queueKey(prefix, sid)
+      local items = redis.call('LRANGE', key, 0, limits.maxQueueMessages)
+      local bytes = #packet
+      for _, item in ipairs(items) do bytes = bytes + #item end
+      if #items >= limits.maxQueueMessages or bytes > limits.maxQueueBytes then return {'QUEUE_CAPACITY'} end
+      table.insert(queues, { key=key, expiresAt=state.expiresAt })
+    end
+  end
+end
+-- All admission checks precede writes. Once submitted, an I/O failure has an
+-- indeterminate outcome; retry the identical operation, never a fresh ID.
+for _, queue in ipairs(queues) do
+  redis.call('RPUSH', queue.key, packet)
+  redis.call('PEXPIREAT', queue.key, queue.expiresAt)
+end
+redis.call('SET', op, cjson.encode({fingerprint=ARGV[4], recipients=#recipients}), 'PX', request.expiresAt - now)
+redis.call('ZADD', ops, request.expiresAt, request.messageId)
+redis.call('PEXPIRE', ops, 60000)
+if #recipients > 0 then
+  redis.call('PUBLISH', prefix .. ':broadcast', cjson.encode({kind='deliveries', sids=recipients}))
+end
+return {'OK', tostring(#recipients), '0'}
+`;
+
+const OWNER = `
+local function owned(prefix, owner)
+  local raw = redis.call('GET', sessionKey(prefix, owner.sid))
+  local record = raw and cjson.decode(raw) or nil
+  local state = record and record.state and cjson.decode(record.state) or nil
+  return state and state.expiresAt > now and state.activeLeaseExpiresAt and state.activeLeaseExpiresAt > now
+    and state.ownerInstanceId == owner.ownerInstanceId and state.activeConnId == owner.connId
+end
+`;
+
+export const READ = KEYS + OWNER + `
+local result = {}
+local bytes = 0
+local limit = tonumber(ARGV[3])
+for _, owner in ipairs(cjson.decode(ARGV[2])) do
+  if owned(ARGV[1], owner) then
+    local items = redis.call('LRANGE', queueKey(ARGV[1], owner.sid), 0, tonumber(ARGV[4]) - 1)
+    local row = {owner.sid}
+    local issued = {}
+    for _, id in ipairs(owner.issuedIds or {}) do issued[id] = true end
+    for _, item in ipairs(items) do
+      if not issued[cjson.decode(item).deliveryId] then
+        if bytes + #item > limit then break end
+        bytes = bytes + #item
+        table.insert(row, item)
+      end
+    end
+    table.insert(result, row)
+  end
+end
+return result
+`;
+
+export const ACK = KEYS + OWNER + `
+local owner = cjson.decode(ARGV[2])
+if not owned(ARGV[1], owner) then return -1 end
+local ids = {}
+for _, id in ipairs(cjson.decode(ARGV[3])) do ids[id] = true end
+local key = queueKey(ARGV[1], owner.sid)
+local removed = 0
+for _, item in ipairs(redis.call('LRANGE', key, 0, tonumber(ARGV[4]) - 1)) do
+  if ids[cjson.decode(item).deliveryId] then removed = removed + redis.call('LREM', key, 1, item) end
+end
+return removed
+`;

package/core/websocket/adapter/redis-delivery-store.ts

@@ -0,0 +1,86 @@
+import { canonicalJsonHashV1 } from "../../../library/boundary";
+import type { ServerPacket } from "../types";
+import { deliveryUuid, WebSocketDeliveryError, type ReliableRoomDelivery, type ReliableRoomPublication, type ReliableSessionOwner, type ReliableDeliveryBatch, type ReliableBroadcastReceipt } from "../reliable-delivery";
+import { RedisWebSocketOperations } from "./redis-operations";
+import { PUBLISH, READ, ACK } from "./redis-delivery-scripts";
+
+export interface RedisReliableDeliveryOptions {
+  readonly requireAof?: boolean;
+  readonly maxQueueMessages?: number;
+  readonly maxQueueBytes?: number;
+  readonly maxRecipients?: number;
+  readonly maxFanoutBytes?: number;
+  readonly maxOperations?: number;
+  readonly maxReadBytes?: number;
+}
+
+export class RedisRoomDeliveryStore implements ReliableRoomDelivery {
+  private readonly limits: Required<Omit<RedisReliableDeliveryOptions, "requireAof">>;
+  private readonly requireAof: boolean;
+  constructor(private readonly operations: Pick<RedisWebSocketOperations, "send">, private readonly prefix: string, options: RedisReliableDeliveryOptions = {}) {
+    if (options.requireAof !== undefined && typeof options.requireAof !== "boolean") throw new Error("Invalid Redis reliable requireAof.");
+    this.requireAof = options.requireAof ?? true;
+    this.limits = { maxQueueMessages: 100, maxQueueBytes: 1024 * 1024, maxRecipients: 1000,
+      maxFanoutBytes: 8 * 1024 * 1024, maxOperations: 10_000, maxReadBytes: 1024 * 1024 };
+    for (const key of Object.keys(this.limits) as (keyof typeof this.limits)[]) {
+      const value = options[key];
+      if (value !== undefined) {
+        if (!Number.isSafeInteger(value) || value < 1) throw new Error(`Invalid Redis reliable ${key}.`);
+        this.limits = { ...this.limits, [key]: value };
+      }
+    }
+    if (this.limits.maxReadBytes < this.limits.maxQueueBytes) throw new Error("Redis reliable maxReadBytes must cover maxQueueBytes.");
+  }
+
+  async initialize(): Promise<void> {
+    await this.healthCheck();
+    const policy = JSON.stringify({ ...this.limits, requireAof: this.requireAof });
+    const key = `${this.prefix}:delivery-policy`;
+    await this.operations.send("SET", [key, policy, "NX"]);
+    if (await this.operations.send("GET", [key]) !== policy) throw new WebSocketDeliveryError("DELIVERY_POLICY_MISMATCH");
+  }
+
+  async healthCheck(): Promise<void> {
+    if (!this.requireAof) return;
+    const settings = await this.operations.send("CONFIG", ["GET", "appendonly", "appendfsync", "no-appendfsync-on-rewrite", "maxmemory-policy"]) as string[] | Record<string, string>;
+    const values = new Map<string, string>();
+    if (Array.isArray(settings)) for (let i = 0; i < settings.length; i += 2) values.set(settings[i]!, settings[i + 1]!);
+    else for (const [key, value] of Object.entries(settings)) values.set(key, value);
+    const info = await this.operations.send("INFO", ["persistence"]) as string;
+    if (values.get("appendonly") !== "yes" || values.get("appendfsync") !== "always" || values.get("maxmemory-policy") !== "noeviction"
+      || values.get("no-appendfsync-on-rewrite") !== "no"
+      || !info.includes("aof_last_write_status:ok") || !info.includes("loading:0")) throw new WebSocketDeliveryError("DURABILITY_CONFIGURATION");
+  }
+
+  async publish(request: ReliableRoomPublication): Promise<ReliableBroadcastReceipt> {
+    if (!deliveryUuid.test(request.messageId) || !Number.isSafeInteger(request.expiresAt)
+      || typeof request.namespace !== "string" || request.namespace.length > 256 || request.namespace.includes("\0")
+      || typeof request.room !== "string" || !request.room.length || request.room.length > 256 || request.room.includes("\0")
+      || typeof request.excludeSid !== "string" || request.excludeSid.length > 128
+      || request.packet.type !== "event" || typeof request.packet.event !== "string" || !request.packet.event.length
+      || request.packet.event.length > 256) throw new WebSocketDeliveryError("INVALID_PUBLICATION");
+    const packet = JSON.stringify({ ...request.packet, v: 1, namespace: request.namespace, deliveryId: request.messageId });
+    if (Buffer.byteLength(packet) > this.limits.maxQueueBytes) throw new WebSocketDeliveryError("QUEUE_CAPACITY");
+    const metadata = JSON.stringify({ messageId: request.messageId, expiresAt: request.expiresAt,
+      namespace: request.namespace, room: request.room, excludeSid: request.excludeSid });
+    const fingerprint = canonicalJsonHashV1("bazis.websocket.publication/v1", { metadata: JSON.parse(metadata), packet: JSON.parse(packet) });
+    const result = await this.operations.send("EVAL", [PUBLISH, "0", this.prefix, metadata, JSON.stringify(this.limits), fingerprint, packet]) as string[];
+    if (result[0] !== "OK") throw new WebSocketDeliveryError(result[0] ?? "STORE_PROTOCOL");
+    return { messageId: request.messageId, recipients: Number(result[1]), duplicate: result[2] === "1" };
+  }
+
+  async readPending(owners: readonly ReliableSessionOwner[]): Promise<readonly ReliableDeliveryBatch[]> {
+    if (owners.length > 128 || owners.some((owner) => (owner.issuedIds?.length ?? 0) > this.limits.maxQueueMessages)) throw new WebSocketDeliveryError("READ_CAPACITY");
+    if (!owners.length) return [];
+    const rows = await this.operations.send("EVAL", [READ, "0", this.prefix, JSON.stringify(owners), String(this.limits.maxReadBytes), String(this.limits.maxQueueMessages)]) as string[][];
+    return rows.map(([sid, ...packets]) => ({ sid: sid!, packets: packets.map((packet) => JSON.parse(packet) as ServerPacket) }));
+  }
+
+  async acknowledge(owner: ReliableSessionOwner, deliveryIds: readonly string[]): Promise<number> {
+    if (!deliveryIds.length) return 0;
+    if (deliveryIds.length > this.limits.maxQueueMessages || deliveryIds.some((id) => !deliveryUuid.test(id))) throw new WebSocketDeliveryError("INVALID_ACK");
+    const count = Number(await this.operations.send("EVAL", [ACK, "0", this.prefix, JSON.stringify(owner), JSON.stringify(deliveryIds), String(this.limits.maxQueueMessages)]));
+    if (count < 0) throw new WebSocketDeliveryError("OWNERSHIP_LOST");
+    return count;
+  }
+}

package/core/websocket/adapter/redis-operations.ts

@@ -0,0 +1,33 @@
+import type { RedisClient } from "bun";
+import { WebSocketDeliveryError } from "../reliable-delivery";
+
+/** Bounds waiting and native in-flight work without closing the host's client. */
+export class RedisWebSocketOperations {
+  private pending = 0;
+  private timedOut = 0;
+  constructor(private readonly client: RedisClient, private readonly timeoutMs: number, private readonly maxPending: number) {}
+
+  async send(command: string, args: string[]): Promise<unknown> {
+    return this.run(() => this.client.send(command, args));
+  }
+
+  async run(operation: () => Promise<unknown>): Promise<unknown> {
+    if (this.timedOut > 0 || this.pending >= this.maxPending) throw new WebSocketDeliveryError("STORE_BUSY");
+    this.pending++;
+    let expired = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const native = Promise.resolve().then(operation);
+    const settled = native.finally(() => {
+      this.pending--;
+      if (expired) this.timedOut--;
+      if (timer !== undefined) clearTimeout(timer);
+    });
+    return Promise.race([settled, new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        expired = true;
+        this.timedOut++;
+        reject(new WebSocketDeliveryError("STORE_TIMEOUT"));
+      }, this.timeoutMs);
+    })]);
+  }
+}