akanjs 3.0.0-beta.8 → 3.0.0

package/service/predefinedAdaptor/sql/values.ts

@@ -1,7 +1,6 @@
 import type { InArgs, InValue } from "@libsql/client";
 import { dayjs } from "akanjs/base";
 import { encodeDocumentValue, sanitizeJson } from "akanjs/document";
-import { quoteIdent } from "../sqlDescriptor";
 import type { QueryLeafOps } from "./types";
 
 export const isPlainObject = (value: unknown): value is Record<string, unknown> =>
@@ -55,6 +54,19 @@ export const decodeDateValue = (value: unknown) => {
 
 export const jsonStr = (value: unknown) => JSON.stringify(sanitizeJson(value) ?? null);
 
+const nulEscape = /(?<!\\)(?:\\\\)*\\u0000/;
+
+/** Postgres refuses U+0000 inside jsonb, so every mode refuses it — one app stores the same thing in each. */
+export const assertStorableJson = (json: string, table: string) => {
+  if (nulEscape.test(json))
+    throw new Error(
+      `Cannot store a string holding U+0000 (NUL) in "${table}": Postgres refuses it inside jsonb, so no database mode stores one`,
+    );
+  return json;
+};
+
+export const likePattern = (value: unknown) => `%${String(value).replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+
 export const BASE_COLUMN_LEAF: QueryLeafOps = {
   eq: (path, value) =>
     value === null
@@ -87,5 +99,31 @@ export const BASE_COLUMN_LEAF: QueryLeafOps = {
     sql: `EXISTS (SELECT 1 FROM json_each(${quoteIdent(path)}) WHERE json_each.value = ?)`,
     params: [encodeSqlValue(value)],
   }),
-  contains: (path, value) => ({ sql: `${quoteIdent(path)} LIKE ?`, params: [`%${String(value)}%`] }),
+  contains: (path, value) => ({ sql: `${quoteIdent(path)} LIKE ? ESCAPE '\\'`, params: [likePattern(value)] }),
+};
+
+export const quoteIdent = (identifier: string) => `"${identifier.replaceAll('"', '""')}"`;
+
+export const jsonPath = (path: string) =>
+  `$.${path
+    .split(".")
+    .map((part) => part.replaceAll('"', '\\"'))
+    .join(".")}`;
+
+export const stableJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, val]) => `${JSON.stringify(key)}:${stableJson(val)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+
+/** Stored in `_akan_meta`, so a changed schema definition is detected without migrations. */
+export const descriptorHash = async (value: unknown) => {
+  const bytes = new TextEncoder().encode(stableJson(value));
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(hash)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 };

package/service/predefinedAdaptor/sqlitePath.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { getEnv } from "akanjs/base";
 
 interface ResolveDefaultSqliteFileOptions {
   appName: string;
@@ -21,3 +22,14 @@ export const resolveDefaultSqliteFile = ({
   if (isProduction && !isLocalOperation) return path.join(process.cwd(), "sqlite", fileName);
   return path.join(workspaceRoot ?? process.cwd(), "local", "apps", appName, fileName);
 };
+
+export const defaultSqliteFile = (suffix: string, workspaceRoot?: string) => {
+  const { appName, environment, operationMode } = getEnv();
+  return resolveDefaultSqliteFile({
+    appName,
+    fileName: `${appName}-${environment}${suffix}.db`,
+    isProduction: process.env.NODE_ENV === "production",
+    operationMode,
+    workspaceRoot,
+  });
+};

package/service/predefinedAdaptor/sseData.ts

@@ -0,0 +1,23 @@
+export const eachSseData = async (body: ReadableStream<Uint8Array>, onData: (payload: string) => void) => {
+  let buffer = "";
+  const decoder = new TextDecoder();
+  const feed = (line: string) => {
+    if (!line.startsWith("data:")) return;
+    const payload = line.slice(5).trim();
+    if (!payload) return;
+    try {
+      onData(payload);
+    } catch {
+    }
+  };
+  for await (const piece of body) {
+    buffer += decoder.decode(piece, { stream: true });
+    let cut = buffer.indexOf("\n");
+    while (cut !== -1) {
+      feed(buffer.slice(0, cut).trimEnd());
+      buffer = buffer.slice(cut + 1);
+      cut = buffer.indexOf("\n");
+    }
+  }
+  feed(buffer.trimEnd());
+};

package/service/predefinedAdaptor/storage.adaptor.ts

@@ -1,5 +1,5 @@
 import { renameSync } from "node:fs";
-import { type BaseEnv, getApiPrefix } from "akanjs/base";
+import { getApiPrefix, getEnv } from "akanjs/base";
 import { adapt } from "../adapt";
 
 export interface DownloadRequest {
@@ -52,27 +52,36 @@ export interface StorageAdaptor {
   deleteDataByPath(path: string): Promise<boolean>;
 }
 
-export interface BlobStorageOptions extends BaseEnv {
+export interface BlobStorageOptions {
   blobStorage?: { baseDir?: string; privateBaseDir?: string; urlPrefix?: string };
 }
 
 export class BlobStorage
   extends adapt("blobStorage", ({ env }) => ({
     root: env(
-      ({ appName, blobStorage = { baseDir: "local" } }: BlobStorageOptions) =>
-        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.baseDir ?? "local"}/${appName}/backend`,
+      ({ blobStorage = { baseDir: "local" } }: BlobStorageOptions) =>
+        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.baseDir ?? "local"}/${getEnv().appName}/backend`,
     ),
     privateRoot: env(
-      ({ appName, blobStorage = { privateBaseDir: "local" } }: BlobStorageOptions) =>
-        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.privateBaseDir ?? "local"}/${appName}/server-private`,
+      ({ blobStorage = { privateBaseDir: "local" } }: BlobStorageOptions) =>
+        `${process.env.AKAN_WORKSPACE_ROOT ?? "."}/${blobStorage.privateBaseDir ?? "local"}/${getEnv().appName}/server-private`,
     ),
-
+    
     urlPrefix: env(
       ({ blobStorage }: BlobStorageOptions) => blobStorage?.urlPrefix ?? `${getApiPrefix()}/localFile/getBlob`,
     ),
   }))
   implements StorageAdaptor
 {
+  /** Throws for a deployed `multiple`/`cluster` app on local disk unless `AKAN_STORAGE_SHARED=true` marks it shared. */
+  static assertShared(storage: string) {
+    const { databaseMode, environment, operationMode } = getEnv();
+    if (!databaseMode || databaseMode === "single" || environment === "local" || operationMode === "local") return;
+    if (["1", "true"].includes(process.env.AKAN_STORAGE_SHARED ?? "")) return;
+    throw new Error(
+      `${storage} keeps files on this instance's own disk, which the other instances of a ${databaseMode} deployment cannot read. Configure object storage, or mount one volume on every instance and set AKAN_STORAGE_SHARED=true.`,
+    );
+  }
   #localPathToUrl(path: string) {
     return `${this.urlPrefix}/${path}`;
   }
@@ -93,6 +102,7 @@ export class BlobStorage
     return paths.map((path) => this.#localPathToUrl(path));
   }
   async uploadDataFromLocal({ path, localPath, meta, access = "public" }: UploadRequest) {
+    BlobStorage.assertShared("BlobStorage");
     const filePath = access === "private" ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
     await Bun.write(filePath, Bun.file(localPath));
     if (meta) await Bun.write(`${filePath}.meta`, JSON.stringify(meta));
@@ -106,6 +116,7 @@ export class BlobStorage
     uploadSuccess,
     access = "public",
   }: UploadFromStreamRequest) {
+    BlobStorage.assertShared("BlobStorage");
     const filePath = access === "private" ? `${this.privateRoot}/${path}` : `${this.root}/${path}`;
     try {
       await Bun.write(filePath, new Response(body));
@@ -121,6 +132,7 @@ export class BlobStorage
     return { localPath: renamePath ?? localPath };
   }
   async copyData({ copyPath, pastePath, host }: CopyRequest) {
+    BlobStorage.assertShared("BlobStorage");
     await Bun.write(`${this.root}/${pastePath}`, Bun.file(`${this.root}/${copyPath}`));
     return pastePath;
   }

package/service/predefinedAdaptor/websocket.adaptor.ts

@@ -1,7 +1,7 @@
-import type { BaseEnv, Cls } from "akanjs/base";
+import { hostname } from "node:os";
+import { getEnv } from "akanjs/base";
 import { adapt } from "../adapt";
 import { RedisCache } from "./cache.adaptor";
-import { ProtobufCompressor } from "./compress.adaptor";
 
 export interface WsSocketData {
   socketId?: string;
@@ -9,51 +9,51 @@ export interface WsSocketData {
 }
 export type WsRedisEventHandler = (roomId: string, data: unknown) => void;
 
+/** A committed write to a model that live slices route, as text every server of the app turns back into documents. */
+export interface LiveChange {
+  refName: string;
+  next: string;
+  /** Absent on a create. */
+  previous?: string;
+}
+export type LiveChangeHandler = (change: LiveChange) => void;
+
+export interface WebsocketPublishOption {
+  /** Only the newest frame for the room matters, so an undelivered older one may be dropped for it. */
+  coalesce?: boolean;
+}
+
 export interface WebsocketAdaptor {
-  /** Publish data to a room across all server instances */
-  publish(roomId: string, data: unknown): void;
-  /** Register an event handler for incoming cross-server messages */
+  /** Across every server instance. */
+  publish(roomId: string, data: unknown, option?: WebsocketPublishOption): void;
   setEventHandler(handler: WsRedisEventHandler): void;
-  /** Unregister the event handler */
   clearEventHandler(): void;
-  /**
-   * Called after the cross-server channel has been down and come back, if this transport can lose one.
-   *
-   * A dropped subscription is the one message loss nothing else notices: the client's own socket stays open the
-   * whole time, so it has no reason to suspect its list is behind. A transport with no channel to lose — the
-   * single-node one, which delivers through the gateway's own IPC — leaves this out.
-   */
+  /** After a lost cross-server channel returns — a loss the still-open client socket never notices. Optional. */
   onRecovered?(handler: () => void): void;
-  /** Register endpoint return type info for protobuf encoding */
-  registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
-  /** Register a socket joining a room (tracked in Redis for cross-server awareness) */
+  /** To every other server of the app: the writer only knows its own rooms, and a batch process holds none. */
+  publishChange?(change: LiveChange): void;
+  onChange?(handler: LiveChangeHandler): void;
   joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-  /** Remove a socket from a room */
   leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-  /** Remove a socket from all rooms and clean up its Redis state */
   leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
-  /** Register a socket connection on this server */
   registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
-  /** Unregister a socket connection */
   unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
 }
 
 interface BufferedMessage {
-  channel: string;
+  roomId: string;
   message: Buffer;
+  coalesce: boolean;
 }
 
-const WEBSOCKET_PREFIX = "ws:";
-const BROADCAST_CHANNEL = "ws:broadcast";
-
 export class WebSocketRedisAdaptor
   extends adapt("wsRedis", ({ plug, env }) => ({
-    redis: plug(RedisCache, (cache) => cache.getClient()),
-    compressor: plug(ProtobufCompressor),
-    serverId: env(
-      ({ appName, environment, operationMode }: BaseEnv) =>
-        `${appName}-${environment}-${operationMode}-${process.env.POD_NAME ?? Bun.randomUUIDv7()}`,
-    ),
+    channelPrefix: plug(RedisCache, (cache) => cache.keyPrefix),
+    
+    serverId: env(() => {
+      const { appName, environment } = getEnv();
+      return `${appName}-${environment}-${process.env.POD_NAME ?? hostname()}-${process.pid}`;
+    }),
     publisher: plug(RedisCache, (cache) =>
       cache.getClient().duplicate({ lazyConnect: true, retryStrategy: (times) => Math.min(times * 200, 5000) }),
     ),
@@ -63,23 +63,31 @@ export class WebSocketRedisAdaptor
   }))
   implements WebsocketAdaptor
 {
+
+  static readonly #version = 1;
+  static readonly #kind = { json: 0x6a, bytes: 0x62, change: 0x63 } as const;
   readonly #buffer: BufferedMessage[] = [];
   readonly #maxBufferSize = 10000;
-  readonly #endpointMap = new Map<string, { returnRef: Cls; arrDepth: number }>();
+  readonly #roomSockets = new Map<string, Set<string>>();
+  readonly #socketRooms = new Map<string, Set<string>>();
   #eventHandler: WsRedisEventHandler | null = null;
+  #changeHandler: LiveChangeHandler | null = null;
   #recoveryHandler: (() => void) | null = null;
   #publisherReady = false;
   #subscriberReady = false;
   /** Whether the subscriber has ever been up, so the first `ready` is a start rather than a recovery. */
   #subscriberStarted = false;
-  #heartbeatInterval: Timer | null = null;
+  #warnedVersion = false;
+
+  get #channel() {
+    return `${this.channelPrefix}ws:broadcast`;
+  }
 
   override async onInit() {
-    
     this.publisher.on("connect", () => {
       this.#publisherReady = true;
       this.logger.verbose("Publisher connected");
-      this.#flushBuffer();
+      void this.#flushBuffer();
     });
     this.publisher.on("close", () => {
       this.#publisherReady = false;
@@ -108,53 +116,17 @@ export class WebSocketRedisAdaptor
 
     await this.publisher.connect();
     await this.subscriber.connect();
-
-    await this.subscriber.subscribe(BROADCAST_CHANNEL, (err?: Error | null) => {
+    await this.subscriber.subscribe(this.#channel, (err?: Error | null) => {
       if (err) this.logger.warn(`Subscribe error: ${err.message}`);
     });
-
-    this.subscriber.on("messageBuffer", (_channel: string, message: Buffer) => {
-      try {
-        const unpacked = this.#unpackMessage(message);
-        if (!unpacked) throw new Error("Failed to unpack message");
-        if (unpacked.origin === this.serverId || !this.#eventHandler) return;
-        const endpointKey = this.#getEndpointKey(unpacked.roomId);
-        const endpointInfo = endpointKey ? this.#endpointMap.get(endpointKey) : null;
-        if (!endpointInfo) throw new Error(`No endpoint registered for roomId ${unpacked.roomId}`);
-        const decoded = this.compressor.decode(endpointInfo.returnRef, endpointInfo.arrDepth, unpacked.payload, {
-          raw: true,
-        });
-        this.#eventHandler(unpacked.roomId, decoded);
-      } catch (err) {
-        this.logger.warn(`Failed to handle Redis WS message: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    });
-
-    await this.redis.set(`${WEBSOCKET_PREFIX}server:${this.serverId}`, Date.now().toString(), "EX", 60);
-    this.#heartbeatInterval = setInterval(async () => {
-      try {
-        await this.redis.expire(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, 60);
-        await this.redis.set(`${WEBSOCKET_PREFIX}server:${this.serverId}`, Date.now().toString(), "EX", 60);
-      } catch (err) {
-        this.logger.warn(`Heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    }, 30_000);
-
+    this.subscriber.on("messageBuffer", (_channel: Buffer, message: Buffer) => this.#receive(message));
     this.logger.verbose(`WebSocket Redis adaptor initialized (serverId: ${this.serverId})`);
   }
 
   override async onDestroy() {
-    
-    if (this.#heartbeatInterval) {
-      clearInterval(this.#heartbeatInterval);
-      this.#heartbeatInterval = null;
-    }
-
-    await this.#cleanupServer();
-
     if (this.subscriber) {
       try {
-        await this.subscriber.unsubscribe(BROADCAST_CHANNEL);
+        await this.subscriber.unsubscribe(this.#channel);
       } catch {}
       this.subscriber.disconnect();
     }
@@ -163,31 +135,42 @@ export class WebSocketRedisAdaptor
       this.publisher.disconnect();
     }
     this.#eventHandler = null;
+    this.#changeHandler = null;
     this.#recoveryHandler = null;
     this.#publisherReady = false;
     this.#subscriberReady = false;
+    this.#roomSockets.clear();
+    this.#socketRooms.clear();
     this.logger.verbose("WebSocket Redis adaptor destroyed");
   }
 
-  publish(roomId: string, data: unknown): void {
-    const endpointKey = this.#getEndpointKey(roomId);
-    const endpointInfo = endpointKey ? this.#endpointMap.get(endpointKey) : null;
-    if (!endpointInfo) {
-      this.logger.warn(`No endpoint registered for roomId ${roomId}, skipping publish`);
+  publish(roomId: string, data: unknown, { coalesce = false }: WebsocketPublishOption = {}): void {
+    const bytes = data instanceof Uint8Array;
+    const payload = bytes ? data : JSON.stringify(data);
+    if (payload === undefined) {
+      this.logger.warn(`Nothing to publish to ${roomId}: the payload has no JSON form`);
       return;
     }
-    const payload = this.compressor.encode(endpointInfo.returnRef, endpointInfo.arrDepth, data);
-    if (!payload) {
-      this.logger.warn(`Compressor encode failed for ${endpointKey}, skipping publish`);
+    this.#send({ roomId, message: this.#pack(bytes ? "bytes" : "json", roomId, payload), coalesce });
+  }
+
+  publishChange(change: LiveChange): void {
+    this.#send({ roomId: "", message: this.#pack("change", "", JSON.stringify(change)), coalesce: false });
+  }
+
+  onChange(handler: LiveChangeHandler): void {
+    this.#changeHandler = handler;
+  }
+
+  #send(buffered: BufferedMessage) {
+    if (!this.#publisherReady) {
+      this.#addToBuffer(buffered);
       return;
     }
-    const message = this.#packMessage(this.serverId, roomId, payload);
-    if (this.#publisherReady && this.publisher) {
-      this.publisher.publish(BROADCAST_CHANNEL, message).catch((err: Error) => {
-        this.logger.warn(`Publish failed, buffering: ${err.message}`);
-        this.#addToBuffer(BROADCAST_CHANNEL, message);
-      });
-    } else this.#addToBuffer(BROADCAST_CHANNEL, message);
+    this.publisher.publish(this.#channel, buffered.message).catch((err: Error) => {
+      this.logger.warn(`Publish failed, buffering: ${err.message}`);
+      this.#addToBuffer(buffered);
+    });
   }
 
   setEventHandler(handler: WsRedisEventHandler): void {
@@ -202,111 +185,120 @@ export class WebSocketRedisAdaptor
     this.#recoveryHandler = handler;
   }
 
-  registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void {
-    this.#endpointMap.set(key, { returnRef, arrDepth });
-  }
-
-  #getEndpointKey(roomId: string): string {
-    const idx = roomId.indexOf("-");
-    return idx >= 0 ? roomId.substring(0, idx) : roomId;
-  }
-
   async joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
     const socketId = this.#getSocketId(ws);
-    const pipeline = this.redis.multi();
-    pipeline.sadd(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
-    pipeline.sadd(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`, room);
-    await pipeline.exec();
+    const sockets = this.#roomSockets.get(room) ?? new Set<string>();
+    sockets.add(socketId);
+    this.#roomSockets.set(room, sockets);
+    const rooms = this.#socketRooms.get(socketId) ?? new Set<string>();
+    rooms.add(room);
+    this.#socketRooms.set(socketId, rooms);
   }
 
   async leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void> {
     const socketId = this.#getSocketId(ws);
-    const pipeline = this.redis.multi();
-    pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
-    pipeline.srem(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`, room);
-    await pipeline.exec();
+    this.#forget(socketId, room);
+    const rooms = this.#socketRooms.get(socketId);
+    rooms?.delete(room);
+    if (rooms?.size === 0) this.#socketRooms.delete(socketId);
   }
 
   async leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
     const socketId = this.#getSocketId(ws);
-    const rooms = await this.redis.smembers(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
-    const pipeline = this.redis.multi();
-    for (const room of rooms) {
-      pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
-    }
-    pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
-    pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}`);
-    pipeline.srem(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, socketId);
-    await pipeline.exec();
+    for (const room of this.#socketRooms.get(socketId) ?? []) this.#forget(socketId, room);
+    this.#socketRooms.delete(socketId);
   }
 
-  /**
-   * `AppWsData` mints the id at the handshake, so this reads it; the fallback only covers a socket that
-   * was upgraded outside the app router. The owning server is recorded in the socket hash below, so the
-   * id itself carries no prefix.
-   */
+  /** `AppWsData` mints the id at the handshake; the fallback covers a socket upgraded outside the app router. */
   #getSocketId(ws: Bun.ServerWebSocket<unknown>): string {
     const data = ws.data as WsSocketData;
     data.socketId ??= Bun.randomUUIDv7();
     return data.socketId;
   }
 
-  async registerSocket(ws: Bun.ServerWebSocket<unknown>, meta: Record<string, string> = {}): Promise<void> {
-    const pipeline = this.redis.multi();
-    const socketId = this.#getSocketId(ws);
-    pipeline.hset(`${WEBSOCKET_PREFIX}socket:${socketId}`, {
-      serverId: this.serverId,
-      connectedAt: Date.now().toString(),
-      ...meta,
-    });
-    pipeline.sadd(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`, socketId);
-    await pipeline.exec();
+  async registerSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
+    this.#getSocketId(ws);
   }
 
   async unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void> {
     await this.leaveAllRooms(ws);
   }
 
-  #packMessage(origin: string, roomId: string, payload: Buffer): Buffer {
-    const originBuf = Buffer.from(origin, "utf-8");
-    const roomIdBuf = Buffer.from(roomId, "utf-8");
-    const message = Buffer.alloc(2 + originBuf.length + 2 + roomIdBuf.length + payload.length);
-    let offset = 0;
-    message.writeUInt16BE(originBuf.length, offset);
-    offset += 2;
-    originBuf.copy(message, offset);
-    offset += originBuf.length;
-    message.writeUInt16BE(roomIdBuf.length, offset);
-    offset += 2;
-    roomIdBuf.copy(message, offset);
-    offset += roomIdBuf.length;
-    payload.copy(message, offset);
-    return message;
+  #forget(socketId: string, room: string) {
+    const sockets = this.#roomSockets.get(room);
+    sockets?.delete(socketId);
+    if (sockets?.size === 0) this.#roomSockets.delete(room);
+  }
+
+  #receive(message: Buffer) {
+    try {
+      const unpacked = this.#unpack(message);
+      if (!unpacked || unpacked.origin === this.serverId) return;
+      if (unpacked.kind === WebSocketRedisAdaptor.#kind.change) {
+        this.#changeHandler?.(JSON.parse(unpacked.payload.toString()) as LiveChange);
+        return;
+      }
+      
+      if (!this.#eventHandler || !this.#roomSockets.has(unpacked.roomId)) return;
+      const data =
+        unpacked.kind === WebSocketRedisAdaptor.#kind.bytes
+          ? new Uint8Array(unpacked.payload)
+          : (JSON.parse(unpacked.payload.toString()) as unknown);
+      this.#eventHandler(unpacked.roomId, data);
+    } catch (err) {
+      this.logger.warn(`Failed to handle Redis WS message: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
 
-  #unpackMessage(buffer: Buffer): { origin: string; roomId: string; payload: Buffer } | null {
-    if (buffer.length < 4) return null;
-    let offset = 0;
-    const originLen = buffer.readUInt16BE(offset);
+  #pack(kind: "json" | "bytes" | "change", roomId: string, payload: string | Uint8Array): Buffer {
+    const origin = Buffer.from(this.serverId, "utf-8");
+    const room = Buffer.from(roomId, "utf-8");
+    const header = Buffer.alloc(2 + 2 + origin.length + 2 + room.length);
+    let offset = header.writeUInt8(WebSocketRedisAdaptor.#version, 0);
+    offset = header.writeUInt8(WebSocketRedisAdaptor.#kind[kind], offset);
+    offset = header.writeUInt16BE(origin.length, offset);
+    offset += origin.copy(header, offset);
+    offset = header.writeUInt16BE(room.length, offset);
+    room.copy(header, offset);
+    const body = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+    return Buffer.concat([header, body]);
+  }
+
+  #unpack(buffer: Buffer): { kind: number; origin: string; roomId: string; payload: Buffer } | null {
+    if (buffer.length < 6) return null;
+    if (buffer.readUInt8(0) !== WebSocketRedisAdaptor.#version) {
+      if (!this.#warnedVersion)
+        this.logger.warn(
+          `Dropping cross-server events of envelope version ${buffer.readUInt8(0)}; this server reads 1`,
+        );
+      this.#warnedVersion = true;
+      return null;
+    }
+    const kind = buffer.readUInt8(1);
+    let offset = 2;
+    const originLength = buffer.readUInt16BE(offset);
     offset += 2;
-    if (buffer.length < offset + originLen + 2) return null;
-    const origin = buffer.subarray(offset, offset + originLen).toString("utf-8");
-    offset += originLen;
-    const roomIdLen = buffer.readUInt16BE(offset);
+    if (buffer.length < offset + originLength + 2) return null;
+    const origin = buffer.subarray(offset, offset + originLength).toString("utf-8");
+    offset += originLength;
+    const roomLength = buffer.readUInt16BE(offset);
     offset += 2;
-    if (buffer.length < offset + roomIdLen) return null;
-    const roomId = buffer.subarray(offset, offset + roomIdLen).toString("utf-8");
-    offset += roomIdLen;
-    const payload = buffer.subarray(offset);
-    return { origin, roomId, payload };
+    if (buffer.length < offset + roomLength) return null;
+    const roomId = buffer.subarray(offset, offset + roomLength).toString("utf-8");
+    offset += roomLength;
+    return { kind, origin, roomId, payload: buffer.subarray(offset) };
   }
 
-  #addToBuffer(channel: string, message: Buffer): void {
+  #addToBuffer(buffered: BufferedMessage): void {
+    if (buffered.coalesce) {
+      const stale = this.#buffer.findIndex((item) => item.coalesce && item.roomId === buffered.roomId);
+      if (stale >= 0) this.#buffer.splice(stale, 1);
+    }
     if (this.#buffer.length >= this.#maxBufferSize) {
       this.#buffer.shift();
       this.logger.warn("Buffer full, dropping oldest message");
     }
-    this.#buffer.push({ channel, message });
+    this.#buffer.push(buffered);
   }
 
   async #flushBuffer(): Promise<void> {
@@ -314,36 +306,14 @@ export class WebSocketRedisAdaptor
 
     this.logger.verbose(`Flushing ${this.#buffer.length} buffered messages`);
     const messages = this.#buffer.splice(0);
-    for (const { channel, message } of messages) {
+    for (const [idx, buffered] of messages.entries()) {
       try {
-        await this.publisher.publish(channel, message);
+        await this.publisher.publish(this.#channel, buffered.message);
       } catch {
-        this.#buffer.unshift({ channel, message });
+        this.#buffer.unshift(...messages.slice(idx));
         this.logger.warn(`Flush failed, ${this.#buffer.length} messages remain buffered`);
         break;
       }
     }
   }
-
-  async #cleanupServer(): Promise<void> {
-    try {
-      const sockets = await this.redis.smembers(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`);
-      const pipeline = this.redis.multi();
-      for (const socketId of sockets) {
-        
-        const rooms = await this.redis.smembers(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
-        for (const room of rooms) {
-          pipeline.srem(`${WEBSOCKET_PREFIX}room:${room}`, socketId);
-        }
-        pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}:rooms`);
-        pipeline.del(`${WEBSOCKET_PREFIX}socket:${socketId}`);
-      }
-      pipeline.del(`${WEBSOCKET_PREFIX}server:${this.serverId}:sockets`);
-      pipeline.del(`${WEBSOCKET_PREFIX}server:${this.serverId}`);
-      await pipeline.exec();
-      this.logger.verbose(`Cleaned up ${sockets.length} sockets from Redis`);
-    } catch (err) {
-      this.logger.warn(`Server cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
 }

package/service/serve.ts

@@ -42,7 +42,6 @@ const avoidKeys = new Set([
 
 export interface Service {
   readonly logger: Logger;
-  
   onInit(): Promise<void> | void;
   _libsOnInit(): Promise<void>;
   onDestroy(): Promise<void> | void;
@@ -153,7 +152,7 @@ export function serve(
     const postUpdateFns = extSrvs.map((srv) => srv.prototype._postUpdate);
     const preRemoveFns = extSrvs.map((srv) => srv.prototype._preRemove);
     const postRemoveFns = extSrvs.map((srv) => srv.prototype._postRemove);
-
+    
     Object.assign(srvRef, {
       [LIBS_REMOVE_HOOK]: preRemoveFns.some(Boolean) || postRemoveFns.some(Boolean),
     });