akanjs 3.0.0-alpha.62 → 3.0.0-alpha.64

package/base/primitiveRegistry.ts

@@ -44,7 +44,7 @@ export class PrimitiveRegistry {
   }
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -176,6 +176,49 @@ export class Any extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Any);
 
+type NodeBuffer = Uint8Array & { toString(encoding: string): string };
+interface BufferCtor {
+  from(buffer: ArrayBufferLike, byteOffset: number, length: number): NodeBuffer;
+  from(text: string, encoding: string): NodeBuffer;
+}
+
+export class Binary extends PrimitiveScalar {
+  static override refName: "Binary" = "Binary";
+  static override [SERVER_VALUE]: Uint8Array;
+  static override [CLIENT_VALUE]: Uint8Array;
+  static override [DEFAULT_VALUE]: Uint8Array | null = null;
+  static override [PURIFIED_VALUE]: Uint8Array | null = null;
+  static override [EXAMPLE_VALUE]: string = "AAEC";
+
+  static override validate(value: Uint8Array | string): boolean {
+    return value instanceof Uint8Array || typeof value === "string";
+  }
+  static override parseValue(input: Uint8Array | string): Uint8Array {
+    return typeof input === "string" ? Binary.#fromBase64(input) : input;
+  }
+  static override serializeValue(value: Uint8Array | string): string {
+    return typeof value === "string" ? value : Binary.#toBase64(value);
+  }
+
+  static #toBase64(bytes: Uint8Array): string {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+    let binary = "";
+    for (let idx = 0; idx < bytes.length; idx += 0x8000)
+      binary += String.fromCharCode(...bytes.subarray(idx, idx + 0x8000));
+    return btoa(binary);
+  }
+  static #fromBase64(text: string): Uint8Array {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(text, "base64");
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let idx = 0; idx < binary.length; idx += 1) bytes[idx] = binary.charCodeAt(idx);
+    return bytes;
+  }
+}
+PrimitiveRegistry.register(Binary);
+
 export class Upload extends PrimitiveScalar {
   static override refName: "Upload" = "Upload";
   static override [SERVER_VALUE]: File;
@@ -354,4 +397,4 @@ Object.assign(Date, {
 });
 PrimitiveRegistry.register(Date);
 
-export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Upload";
+export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Binary" | "Upload";

package/common/clientAddress.ts

@@ -0,0 +1,40 @@
+/** Headers a proxy hop writes so the next hop can still name the original caller. */
+export const forwardedHeaders = [
+  "x-real-ip",
+  "x-forwarded-for",
+  "x-forwarded-port",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+] as const;
+
+/**
+ * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
+ * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
+ * it is unwrapped at every boundary rather than at each call site that happens to remember.
+ */
+export const normalizeIpAddress = (address: string): string => {
+  const trimmed = address.trim();
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
+  return mapped?.[1] ?? trimmed;
+};
+
+/**
+ * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
+ * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
+ * and everything after it is a proxy.
+ *
+ * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
+ * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
+ */
+export const clientAddressFromHeaders = (headers: Headers): string | null => {
+  const realIp = headers.get("x-real-ip")?.trim();
+  if (realIp) return normalizeIpAddress(realIp);
+  const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  return forwarded ? normalizeIpAddress(forwarded) : null;
+};
+
+/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
+export const clientPortFromHeaders = (headers: Headers): number | null => {
+  const port = Number(headers.get("x-forwarded-port"));
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+};

package/common/index.ts

@@ -1,5 +1,11 @@
 export { applyMixins } from "./applyMixins";
 export { capitalize } from "./capitalize";
+export {
+  clientAddressFromHeaders,
+  clientPortFromHeaders,
+  forwardedHeaders,
+  normalizeIpAddress,
+} from "./clientAddress";
 export { deepObjectify } from "./deepObjectify";
 export {
   type FileUploadCapability,
@@ -76,3 +82,4 @@ export {
   type WebsocketAuthRequest,
   websocketAuthContract,
 } from "./websocketAuth";
+export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame";

package/common/mcpExposure.ts

@@ -67,6 +67,8 @@ export const mcpRefusalOf = (endpoint: McpExposureEndpoint, { readOnly }: McpExp
     return "this deployment is read-only, which drops every endpoint that is not a query.";
   if (endpoint.returns.refName === "Any" || endpoint.returns.refName === "Upload")
     return `a return typed \`${endpoint.returns.refName}\` cannot be described to a model.`;
+  if (endpoint.returns.refName === "Binary")
+    return "a return typed `Binary` is raw bytes, which cost a model its window and tell it nothing.";
   if (endpoint.fileUpload || endpoint.args.some((arg) => arg.refName === "Upload"))
     return "a file upload has no MCP representation.";
   if (endpoint.type === "mutation" && !endpoint.guards.some((name) => name !== "Public"))

package/common/websocketBinaryFrame.ts

@@ -0,0 +1,46 @@
+export interface WebsocketBinaryFrame {
+  roomId: string;
+  payload: Uint8Array;
+}
+
+const MAGIC = 0xab;
+const KIND_PUB = 0x01;
+const HEADER_BYTES = 4;
+const MAX_ROOM_BYTES = 0xffff;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Framework-owned binary pubsub frame, shared by the publisher and the client dispatcher. A room whose whole
+ * return is `Binary` sends its bytes in a websocket binary frame instead of the JSON `{ type: "pub" }` envelope,
+ * because `Buffer.toJSON()` turns bytes into `{ type: "Buffer", data: number[] }` — 3.6x the wire and ~300x the
+ * encode cost on a 64 KB payload, and a shape `JSON.parse` never restores.
+ *
+ * Text and binary frames coexist on one socket, so this is additive: every JSON endpoint is untouched, and a
+ * federation gateway relays a binary frame unchanged with no code of its own.
+ */
+export const websocketBinaryFrameContract = {
+  encode: ({ roomId, payload }: WebsocketBinaryFrame): Uint8Array => {
+    const room = encoder.encode(roomId);
+    if (room.length > MAX_ROOM_BYTES) throw new Error(`Room id is too long to frame: ${roomId}`);
+    const frame = new Uint8Array(HEADER_BYTES + room.length + payload.length);
+    frame[0] = MAGIC;
+    frame[1] = KIND_PUB;
+    frame[2] = room.length >> 8;
+    frame[3] = room.length & 0xff;
+    frame.set(room, HEADER_BYTES);
+    frame.set(payload, HEADER_BYTES + room.length);
+    return frame;
+  },
+  decode: (data: ArrayBuffer | Uint8Array): WebsocketBinaryFrame | null => {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.length < HEADER_BYTES || bytes[0] !== MAGIC || bytes[1] !== KIND_PUB) return null;
+    const roomBytes = (bytes[2] << 8) | bytes[3];
+    if (bytes.length < HEADER_BYTES + roomBytes) return null;
+    return {
+      roomId: decoder.decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + roomBytes)),
+      payload: bytes.subarray(HEADER_BYTES + roomBytes),
+    };
+  },
+} as const;

package/constant/fieldQueryMeta.ts

@@ -0,0 +1,35 @@
+import { FIELD_META } from "akanjs/base";
+import { ConstantRegistry } from "./constantRegistry";
+import type { FieldObject } from "./fieldInfo";
+
+/**
+ * The query a field's value stands for, declared on the field itself with `.meta(...)`. A summary counter is the
+ * case this exists for: `hau` is however many rows one filter returns, so the tile showing it can open that exact
+ * listing without the page restating the filter beside it.
+ *
+ * The shape is read structurally rather than by class, so an app declares it with whatever builder it already has.
+ */
+export interface FieldQueryMeta {
+  /** The model the query runs against. */
+  refName: string;
+  /** One of that model's declared filter keys. */
+  queryKey: string | null;
+  /** Read when the query is applied, so an arg relative to now — `() => [dayjs().subtract(1, "hour")]` — is current. */
+  queryArgs?: unknown[] | (() => unknown[]);
+}
+
+const isFieldQueryMeta = (meta: unknown): meta is FieldQueryMeta => {
+  if (!meta || typeof meta !== "object") return false;
+  const { refName, queryKey, queryArgs } = meta as Record<string, unknown>;
+  if (typeof refName !== "string" || !refName) return false;
+  if (queryKey !== null && typeof queryKey !== "string") return false;
+  return queryArgs === undefined || Array.isArray(queryArgs) || typeof queryArgs === "function";
+};
+
+/** The query one field of `refName` names, or nothing when the model, the field, or the declaration is absent. */
+export const fieldQueryMetaOf = (refName: string, field: string): FieldQueryMeta | undefined => {
+  const cnst = ConstantRegistry.getDatabase(refName, { allowEmpty: true });
+  const fieldMap = cnst?.full[FIELD_META] as FieldObject | undefined;
+  const meta = fieldMap?.[field]?.meta;
+  return isFieldQueryMeta(meta) ? meta : undefined;
+};

package/constant/index.ts

@@ -3,6 +3,7 @@ export * from "./constantRegistry";
 export * from "./crystalize";
 export * from "./deserialize";
 export * from "./fieldInfo";
+export * from "./fieldQueryMeta";
 export * from "./getDefault";
 export * from "./immerify";
 export * from "./labelOf";

package/constant/via.ts

@@ -1,4 +1,5 @@
 import {
+  Binary,
   CLIENT_VALUE,
   type Cls,
   DEFAULT_VALUE,
@@ -439,7 +440,9 @@ const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldO
       return { ...defaultValue };
     },
   });
-  Object.entries(fieldMap).forEach(([, field]) => {
+  Object.entries(fieldMap).forEach(([key, field]) => {
+    if ((field.modelRef as unknown) === Binary || (field.of as unknown) === Binary)
+      throw new Error(`Field "${key}" is Binary, which is not storable. Reference the File model instead.`);
     if (field.enum) model.enums.add(field.enum);
     if (!field.isClass) return;
     if (field.isScalar) model.children.add(field.modelRef);

package/fetch/client/wsClient.ts

@@ -1,4 +1,4 @@
-import { Logger, websocketAuthContract } from "akanjs/common";
+import { Logger, websocketAuthContract, websocketBinaryFrameContract } from "akanjs/common";
 import type {
   WebsocketAuthAck,
   WebsocketMessageData,
@@ -85,6 +85,7 @@ export class WsClient {
     if (this.#destroyed) return;
 
     this.#ws = new WebSocket(this.url);
+    this.#ws.binaryType = "arraybuffer";
     this.#ws.onopen = (e) => {
       this.#reconnectAttempts = 0;
       this.connected = true;
@@ -101,7 +102,13 @@ export class WsClient {
     };
     this.#ws.onmessage = (e) => {
       try {
-        const parsed = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
+        if (typeof e.data !== "string") {
+          const frame = websocketBinaryFrameContract.decode(e.data as ArrayBuffer);
+          if (frame) this.#handlePubsub(frame.roomId, frame.payload);
+          else this.logger.warn("Unknown binary WebSocket frame");
+          return;
+        }
+        const parsed = JSON.parse(e.data) as { error?: unknown } & WebsocketResData;
         if (parsed?.error) {
           throw this.#restoreError(parsed);
         }

package/fetch/fetchType/appliedReturn.type.ts

@@ -16,6 +16,13 @@ export interface QuerySetting {
    * now — `() => [dayjs().subtract(1, "hour")]` — current at the moment the user asks for it.
    */
   args?: unknown[] | (() => unknown[]);
+  /**
+   * The same list under the name the rest of the framework already uses for it — the `queryArgsOf<Model>` state
+   * key, `refresh<Model>({ queryArgs })`, and a field's own `.meta(...)` declaration. Accepted so a query a
+   * field declares is one of these as it stands, rather than something every caller has to rename by hand.
+   * `args` wins when both are given.
+   */
+  queryArgs?: unknown[] | (() => unknown[]);
 }
 
 export type ServerInit<

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.62",
+  "version": "3.0.0-alpha.64",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -547,7 +547,7 @@ export class AkanApp {
     if (this.#isWebSocketPath(url.pathname)) return this.#upgradeWebSocket(req, server);
     const assetResponse = await this.#serveImmutableArtifact(req, url);
     if (assetResponse) return assetResponse;
-    return await this.#proxyHttp(req);
+    return await this.#proxyHttp(req, server);
   }
 
   #isWebSocketPath(pathname: string) {
@@ -592,7 +592,7 @@ export class AkanApp {
     if (!child || !upstream) return new Response("No websocket upstream is ready", { status: 503 });
     const url = new URL(req.url);
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
-      headers: this.#makeProxyHeaders(req, child.idx),
+      headers: this.#makeProxyHeaders(req, child.idx, server),
     } as unknown as string[]);
 
     const upgraded = server.upgrade(req, { data: { childIdx: child.idx, upstream: upstreamWs } });
@@ -691,14 +691,14 @@ export class AkanApp {
     };
   }
 
-  async #proxyHttp(req: Request): Promise<Response> {
+  async #proxyHttp(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response> {
     const child = this.#pickFederationChild();
     if (!child?.upstream || child.upstream.type !== "unix") {
       return this.#respondWithCrashPage(req) ?? new Response("No healthy federation child is ready", { status: 503 });
     }
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
-    const headers = this.#makeProxyHeaders(req, child.idx);
+    const headers = this.#makeProxyHeaders(req, child.idx, server);
     child.metrics.activeRequests = (child.metrics.activeRequests ?? 0) + 1;
     child.metrics.totalRequests = (child.metrics.totalRequests ?? 0) + 1;
     const traced = isTraceEnabled();
@@ -867,8 +867,8 @@ export class AkanApp {
     return resolved;
   }
 
-  #makeProxyHeaders(req: Request, childIdx: number) {
-    return makeAkanChildProxyHeaders(req, childIdx);
+  #makeProxyHeaders(req: Request, childIdx: number, server?: Bun.Server<GatewayWsData>) {
+    return makeAkanChildProxyHeaders(req, childIdx, server?.requestIP(req));
   }
 
   #invalidateFederationChildCache() {

package/server/akanAppHeaders.ts

@@ -1,3 +1,5 @@
+import { normalizeIpAddress } from "akanjs/common";
+
 const HOP_BY_HOP_HEADERS = new Set([
   "connection",
   "keep-alive",
@@ -9,13 +11,23 @@ const HOP_BY_HOP_HEADERS = new Set([
   "upgrade",
 ]);
 
-export function makeAkanChildProxyHeaders(req: Request, childIdx: number): Headers {
+/** What `Server.requestIP` reports for the socket this hop accepted. */
+export interface ProxyClientPeer {
+  address: string;
+  port: number;
+  family: string;
+}
+
+export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?: ProxyClientPeer | null): Headers {
   const headers = new Headers(req.headers);
   for (const key of HOP_BY_HOP_HEADERS) headers.delete(key);
   const forwardedFor = headers.get("x-forwarded-for");
-  const clientAddress = headers.get("x-real-ip") ?? "127.0.0.1";
+
+  const clientAddress = headers.get("x-real-ip") ?? (peer ? normalizeIpAddress(peer.address) : "127.0.0.1");
   const host = headers.get("host");
+  headers.set("x-real-ip", clientAddress);
   headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
+  if (peer && !headers.has("x-forwarded-port")) headers.set("x-forwarded-port", String(peer.port));
   headers.set("x-forwarded-host", headers.get("x-forwarded-host") ?? host ?? new URL(req.url).host);
   headers.set(
     "x-forwarded-proto",

package/server/akanServer.ts

@@ -1,5 +1,5 @@
 import { type BackendEnv, type BaseEnv, getEnv } from "akanjs/base";
-import { Logger } from "akanjs/common";
+import { Logger, websocketBinaryFrameContract } from "akanjs/common";
 import { DictionaryLookup } from "akanjs/dictionary";
 import type {
   Adaptor,
@@ -16,6 +16,7 @@ import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
+import { BinaryPubsub } from "./binaryPubsub";
 import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
@@ -27,7 +28,7 @@ import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
-import type { HttpRoutes, SignalRoutes, WebsocketRoutes } from "./types";
+import type { HttpRoutes, LocalPublish, SignalRoutes, WebsocketRoutes } from "./types";
 import type { WebRouter } from "./webRouter";
 
 export interface AkanServerProps extends AkanLibProps {
@@ -138,7 +139,8 @@ export class AkanServer {
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
   #di: DiLifecycle;
-  #localPublish: ((roomId: string, data: object | object[]) => void) | null = null;
+  #localPublish: LocalPublish | null = null;
+  readonly #binaryPubsub = new BinaryPubsub();
   #metricsTimer: Timer | null = null;
   constructor(
     name = "AkanServer",
@@ -318,6 +320,7 @@ export class AkanServer {
         hmrHub,
         hmrState: webRouter ? { state: webRouter.renderState } : null,
         logger: this.logger,
+        onDrain: () => this.#binaryPubsub.flush(),
       }),
       
       data: {},
@@ -375,16 +378,20 @@ export class AkanServer {
 
     const websocket = this.#di.getWebsocketAdaptor();
     if (!websocket) throw new Error("WebSocket Redis adaptor is not registered");
-    SignalResolver.setLocalPublish((roomId, data) => {
-      const publishData: WebsocketPublishData = { type: "pub", roomId, data };
-      server?.publish(roomId, JSON.stringify(publishData));
-      wsServer?.publish(roomId, JSON.stringify(publishData));
-    }, websocket);
-    this.#localPublish = (roomId, data) => {
+    this.#binaryPubsub.setServers(server, wsServer);
+    const localPublish: LocalPublish = (roomId, data) => {
+      if (data instanceof Uint8Array) {
+        this.#binaryPubsub.publish(roomId, websocketBinaryFrameContract.encode({ roomId, payload: data }), {
+          coalesce: SignalResolver.coalescesRoom(roomId),
+        });
+        return;
+      }
       const publishData: WebsocketPublishData = { type: "pub", roomId, data };
       server?.publish(roomId, JSON.stringify(publishData));
       wsServer?.publish(roomId, JSON.stringify(publishData));
     };
+    SignalResolver.setLocalPublish(localPublish, websocket);
+    this.#localPublish = localPublish;
 
     this.status = "running";
     this.#startMetricsReporting();
@@ -479,7 +486,8 @@ export class AkanServer {
 
   #handleIpcMessage(message: AkanIpcMessage) {
     if (!message || typeof message !== "object") return;
-    if (message.type === "pubsub.deliver") this.#localPublish?.(message.roomId, message.data as object | object[]);
+    if (message.type === "pubsub.deliver")
+      this.#localPublish?.(message.roomId, message.data as object | object[] | Uint8Array);
     else if (message.type === "health.ping")
       process.send?.({
         type: "health.pong",
@@ -506,6 +514,7 @@ export class AkanServer {
   async #reportMetrics() {
     const metrics = await ProcessMetricsCollector.collect({
       role: this.serverMode,
+      pubsubCoalesceCount: this.#binaryPubsub.coalescedCount,
       ...(this.#prepared?.webRouter?.getMetrics() ?? {}),
     });
     process.send?.({ type: "metrics.report", pid: process.pid, metrics } satisfies AkanIpcMessage);

package/server/binaryPubsub.ts

@@ -0,0 +1,55 @@
+import { Logger } from "akanjs/common";
+
+/**
+ * Sends binary pubsub frames and absorbs a slow subscriber. `Server.publish` reports `-1` when the socket is
+ * backpressured, `0` when the room has no subscriber, and the byte count otherwise — so a room that cannot
+ * keep up parks its newest frame here and every earlier one is dropped, rather than queueing behind the
+ * slowest subscriber until the send buffer is the stream. Bun fires `drain` per socket when its buffer
+ * empties; that is what flushes the parked frames.
+ */
+export class BinaryPubsub {
+  readonly #logger = new Logger("BinaryPubsub");
+  readonly #pending = new Map<string, Uint8Array>();
+  #servers: Bun.Server<unknown>[] = [];
+  #coalescedCount = 0;
+
+  get coalescedCount() {
+    return this.#coalescedCount;
+  }
+
+  setServers(...servers: (Bun.Server<never> | null)[]) {
+    this.#servers = servers.filter((server): server is Bun.Server<never> => !!server) as Bun.Server<unknown>[];
+  }
+
+  publish(roomId: string, frame: Uint8Array, { coalesce = false }: { coalesce?: boolean } = {}) {
+    if (!this.#send(roomId, frame) || !coalesce) return;
+    if (this.#pending.has(roomId)) this.#coalescedCount += 1;
+    this.#pending.set(roomId, frame);
+  }
+
+  /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
+  flush() {
+    if (!this.#pending.size) return;
+    for (const [roomId, frame] of [...this.#pending]) {
+      this.#pending.delete(roomId);
+      if (this.#send(roomId, frame)) this.#pending.set(roomId, frame);
+    }
+  }
+
+  clear() {
+    this.#pending.clear();
+  }
+
+  /** True when at least one server refused the frame for backpressure, which is the only case worth parking. */
+  #send(roomId: string, frame: Uint8Array): boolean {
+    let backpressured = false;
+    for (const server of this.#servers) {
+      try {
+        if (server.publish(roomId, frame) === -1) backpressured = true;
+      } catch (error) {
+        this.#logger.warn(`Binary publish failed for ${roomId}: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+    return backpressured;
+  }
+}

package/server/resolver/signal.resolver.ts

@@ -1,5 +1,6 @@
 import {
   type BackendEnv,
+  Binary,
   type Cls,
   ENDPOINT_META,
   FIELD_META,
@@ -31,7 +32,7 @@ import { SignalContext, type WebSocketExecutionContext } from "../../signal/sign
 import type { SliceCls } from "../../signal/slice";
 import type { SliceInfo } from "../../signal/sliceInfo";
 import type { WebsocketMessageData, WebsocketSubscribeAck } from "../../signal/types";
-import type { HttpRoutes, SignalRoutes, WebsocketRoutes } from "../types";
+import type { HttpRoutes, LocalPublish, SignalRoutes, WebsocketRoutes } from "../types";
 
 type HttpRouteHandler = (req: Bun.BunRequest) => Response | Promise<Response | undefined> | undefined;
 type HttpMethodRoutes = Record<string, HttpRouteHandler>;
@@ -42,12 +43,18 @@ export class SignalResolver {
   static makeRoomId(key: string, args: unknown[]) {
     return `${key}${args.length ? "-" : ""}${args.join("-")}`;
   }
-  static #localPublish: (roomId: string, data: object | object[]) => void = () => {
+  static #localPublish: LocalPublish = () => {
     SignalResolver.logger.verbose(`Local publish is not initialized yet`);
   };
-  static setLocalPublish(localPublish: (roomId: string, data: object | object[]) => void, websocket: WebsocketAdaptor) {
+  static readonly #coalescingRooms = new Set<string>();
+
+  static coalescesRoom(roomId: string): boolean {
+    const separator = roomId.indexOf("-");
+    return SignalResolver.#coalescingRooms.has(separator >= 0 ? roomId.slice(0, separator) : roomId);
+  }
+  static setLocalPublish(localPublish: LocalPublish, websocket: WebsocketAdaptor) {
     SignalResolver.#localPublish = localPublish;
-    websocket.setEventHandler((roomId, data) => localPublish(roomId, data as object | object[]));
+    websocket.setEventHandler((roomId, data) => localPublish(roomId, data as object | object[] | Uint8Array));
   }
   static resolveServerSignal(
     serverSignalCls: ServerSignalCls,
@@ -59,6 +66,9 @@ export class SignalResolver {
     Object.entries(endpointMeta).forEach(([key, endpointInfo]) => {
       if (endpointInfo.type !== "pubsub") throw new Error(`Endpoint ${key} is not a pubsub endpoint`);
       websocket.registerEndpoint(key, endpointInfo.returns.returnRef as Cls, endpointInfo.returns.arrDepth);
+      const isBinaryFrame = endpointInfo.returns.returnRef === Binary && !endpointInfo.returns.arrDepth;
+      if (isBinaryFrame && endpointInfo.signalOption.backpressure !== "queue") SignalResolver.#coalescingRooms.add(key);
+      let warnedRawBytes = false;
       const serializeFn = (data: unknown) =>
         serialize(endpointInfo.returns.returnRef, endpointInfo.returns.arrDepth, data, "object", {
           nullable: endpointInfo.returns.nullable,
@@ -74,12 +84,22 @@ export class SignalResolver {
             registry,
             live,
           });
+          const roomId = SignalResolver.makeRoomId(key, roomArgs);
+          if (isBinaryFrame) {
+            const bytes = Binary._parse(resolvedData as Uint8Array) as Uint8Array;
+            websocket.publish(roomId, bytes);
+            SignalResolver.#localPublish(roomId, bytes);
+            return;
+          }
           const serializedData = serializeFn(resolvedData) as object | object[] | null;
           if (!serializedData) {
             this.logger.warn(`Failed to serialize data for ${key}`);
             return;
           }
-          const roomId = SignalResolver.makeRoomId(key, roomArgs);
+          if (!warnedRawBytes && ArrayBuffer.isView(serializedData)) {
+            warnedRawBytes = true;
+            this.logger.warn(`${key} publishes bytes but does not return Binary; declare pubsub(Binary) instead.`);
+          }
           websocket.publish(roomId, serializedData);
           SignalResolver.#localPublish(roomId, serializedData);
         },

package/server/routing/apiRouter.ts

@@ -44,6 +44,7 @@ export interface WebsocketHandlersInputs {
   hmrHub: HmrWsHub | null;
   hmrState: HmrStateSource | null;
   logger: Logger;
+  onDrain?: () => void;
 }
 
 type WsTaggedData = { kind?: string };
@@ -111,8 +112,11 @@ export class ApiRouter {
     hmrHub,
     hmrState,
     logger,
+    onDrain,
   }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData> {
     return {
+      
+      drain: () => onDrain?.(),
       open: (ws) => {
 
         const data = ws.data as WsTaggedData | undefined;

package/server/routing/appWsData.ts

@@ -1,3 +1,5 @@
+import { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress } from "akanjs/common";
+
 const CREDENTIAL_HEADERS = ["authorization", "cookie", "user-agent"] as const;
 
 /**
@@ -9,7 +11,8 @@ const CREDENTIAL_HEADERS = ["authorization", "cookie", "user-agent"] as const;
 export class AppWsData {
   static fromRequest(req: Request): AppWsData {
     const headers = new Headers();
-    for (const key of CREDENTIAL_HEADERS) {
+
+    for (const key of [...CREDENTIAL_HEADERS, ...forwardedHeaders]) {
       const value = req.headers.get(key);
       if (value) headers.set(key, value);
     }
@@ -48,6 +51,18 @@ export class AppWsData {
    * It outlives a credential swap on purpose: the socket is still the same socket.
    */
   socketId: string;
+  /** The caller's address as the nearest proxy recorded it, or null when nothing did. */
+  get ip(): string | null {
+    return clientAddressFromHeaders(this.headers);
+  }
+  /** The caller's source port as the nearest proxy recorded it, or null when nothing did. */
+  get port(): number | null {
+    return clientPortFromHeaders(this.headers);
+  }
+  /** The address to answer on: what a proxy recorded, else this socket's own peer. */
+  ipOf(ws: Bun.ServerWebSocket<unknown>): string | null {
+    return this.ip ?? (ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null);
+  }
   constructor(headers: Headers) {
     this.createdAt = Date.now();
     this.headers = headers;

package/server/types.tsx

@@ -13,6 +13,8 @@ export type WebsocketRoutes = Record<string, WebsocketRoute>;
 
 export type HttpRoutes = Bun.Serve.Options<unknown>["routes"];
 
+export type LocalPublish = (roomId: string, data: object | object[] | Uint8Array) => void;
+
 export interface SignalRouteOptions {
   globalPrefix?: false;
 }