akanjs 3.0.0-alpha.63 → 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/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.63",
+  "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;
 }

package/service/ipcTypes.ts

@@ -37,6 +37,7 @@ export interface AkanMetricsReport {
   queueWakeCount?: number;
   pubsubDeliverCount?: number;
   pubsubDropCount?: number;
+  pubsubCoalesceCount?: number;
   rssBytes?: number;
   heapTotalBytes?: number;
   heapUsedBytes?: number;

package/service/predefinedAdaptor/compress.adaptor.ts

@@ -1,6 +1,7 @@
 import {
   Any,
   applyFnToArrayObjects,
+  Binary,
   type Cls,
   type Dayjs,
   dayjs,
@@ -41,10 +42,12 @@ export interface CompressAdaptor {
 }
 
 export class JsonCompressor extends adapt("jsonCompressor", () => ({})) implements CompressAdaptor {
-  encode(_ref: Cls, _arrDepth: number, value: unknown): Buffer | null {
+  encode(ref: Cls, arrDepth: number, value: unknown): Buffer | null {
+    if (ref === Binary && !arrDepth) return Buffer.from(value as Uint8Array);
     return Buffer.from(JSON.stringify(value));
   }
   decode<T = unknown>(ref: Cls, arrDepth: number, buffer: Buffer, { raw = false }: { raw?: boolean } = {}): T {
+    if (ref === Binary && !arrDepth) return buffer as T;
     const value = JSON.parse(buffer.toString()) as T;
     if (raw || arrDepth > 0 || PrimitiveRegistry.has(ref)) return value;
     return new (ref as ConstantCls)().set(value as object) as T;
@@ -59,6 +62,7 @@ export class ProtobufCompressor extends adapt("protobufCompressor", () => ({}))
     [Float, "float"],
     [Boolean, "bool"],
     [Date, "double"],
+    [Binary, "bytes"],
   ]);
   #primitiveProtoEncodeMap = new Map<PrimitiveScalar, (value: never) => unknown>([
     [Date, (value: Date | Dayjs) => dayjs(value).toDate().getTime()],

package/signal/internalArg.ts

@@ -21,6 +21,19 @@ export class Res implements InternalArg {
   }
 }
 
+/**
+ * Injects the caller's IP, as the nearest proxy recorded it rather than as the socket peer reports it.
+ * Behind the federation gateway every peer is the gateway, so an endpoint that reads `remoteAddress` sees
+ * `127.0.0.1` for every caller — this reads the forwarded headers first and falls back to the peer only
+ * when nothing proxied the call. IPv4 comes back unwrapped from `::ffff:`, so it can address a `udp4`
+ * socket. `null` when no proxy recorded one and the transport has no peer.
+ */
+export class Ip implements InternalArg<string | null> {
+  getArg(context: SignalContext): string | null {
+    return context.getClientIp();
+  }
+}
+
 /**
  * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
  * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to

package/signal/openapi/openapi.ts

@@ -210,6 +210,7 @@ const getProtectedGuards = (guards?: string[]) =>
 
 const isBinaryResponseEndpoint = (endpoint: SerializedEndpoint) =>
   endpoint.returns.refName === "Upload" ||
+  endpoint.returns.refName === "Binary" ||
   (endpoint.returns.refName === "Any" &&
     Boolean(endpoint.path?.includes("*") || endpoint.path?.toLowerCase().includes("blob")));
 

package/signal/schema/JsonSchemaBuilder.ts

@@ -193,6 +193,8 @@ export class JsonSchemaBuilder {
         return { type: "integer" };
       case "Upload":
         return { type: "string", format: "binary" };
+      case "Binary":
+        return { type: "string", contentEncoding: "base64" };
       case "Any":
         return {};
       default:

package/signal/signalContext.ts

@@ -8,6 +8,7 @@ import {
   type PromiseOrObject,
   Upload,
 } from "akanjs/base";
+import { clientAddressFromHeaders, clientPortFromHeaders, normalizeIpAddress } from "akanjs/common";
 import {
   type ConstantCls,
   type ConstantFieldTypeInput,
@@ -429,6 +430,27 @@ export class SignalContext<
     if (this.transport === "http") return this.getHttpContext<{ [key: string]: T }>().req[key] ?? null;
     return this.getWebSocketContext<{ [key: string]: T }>().ws.data[key] ?? null;
   }
+  /**
+   * The caller's IP, preferring what a proxy recorded over the socket peer. Behind the federation gateway the
+   * peer is the gateway itself for every request and for the whole life of every socket, so `remoteAddress`
+   * alone names the wrong machine — which is why nothing here reads it first. IPv4 arrives unwrapped from its
+   * `::ffff:` form, so it can be used as a destination as well as an identity.
+   *
+   * `null` means no proxy recorded one and the transport has no peer to fall back on — never a placeholder,
+   * because a loopback-looking address for an unknown caller is the failure this replaced.
+   */
+  getClientIp(): string | null {
+    if (this.transport === "http") return clientAddressFromHeaders(this.getHttpContext().req.headers);
+    const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
+    const forwarded = ws.data.headers ? clientAddressFromHeaders(ws.data.headers) : null;
+    return forwarded ?? (ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null);
+  }
+  /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
+  getClientPort(): number | null {
+    if (this.transport === "http") return clientPortFromHeaders(this.getHttpContext().req.headers);
+    const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
+    return (ws.data.headers ? clientPortFromHeaders(ws.data.headers) : null) ?? null;
+  }
   getRoomId(key: string) {
     if (this.transport !== "websocket") throw new Error("Transport is not websocket");
     else if (this.endpointInfo.type !== "pubsub") throw new Error("Endpoint is not pubsub");

package/signal/types.ts

@@ -85,6 +85,13 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   method?: HttpMutationMethod;
   /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
   fileUpload?: boolean;
+  /**
+   * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
+   * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
+   * newer one exists. Name `"queue"` when the frames are a sequence a subscriber has to see in full, such as
+   * deltas against a base it already holds; the send buffer then grows with the slowest subscriber.
+   */
+  backpressure?: "coalesce" | "queue";
 
   scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
   scheduleCron?: string;

package/test/sampleOf.ts

@@ -1,5 +1,6 @@
 import {
   Any,
+  Binary,
   type Cls,
   FIELD_META,
   Float,
@@ -28,6 +29,7 @@ const scalarSampleMap = new Map<PrimitiveScalar, () => any>([
   [Boolean, () => sample.bool()],
   [Date, () => sample.dayjs()],
   [Upload, () => "FileUpload"],
+  [Binary, () => new Uint8Array([0, 1, 2])],
   [Any, () => ({})],
 ]);
 const getPrimitiveSample = (ref: Cls, field: ConstantField) => {

package/types/base/primitiveRegistry.d.ts

@@ -17,7 +17,7 @@ export declare class PrimitiveRegistry {
     static getNames(): string[];
     static getAll(): (typeof PrimitiveScalar)[];
 }
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
 export declare class PrimitiveScalar {
     static refName: string;
     static [SERVER_VALUE]: unknown;
@@ -83,6 +83,18 @@ export declare class Any extends PrimitiveScalar {
     static [DEFAULT_VALUE]: object | null;
     static [EXAMPLE_VALUE]: object;
 }
+export declare class Binary extends PrimitiveScalar {
+    #private;
+    static refName: "Binary";
+    static [SERVER_VALUE]: Uint8Array;
+    static [CLIENT_VALUE]: Uint8Array;
+    static [DEFAULT_VALUE]: Uint8Array | null;
+    static [PURIFIED_VALUE]: Uint8Array | null;
+    static [EXAMPLE_VALUE]: string;
+    static validate(value: Uint8Array | string): boolean;
+    static parseValue(input: Uint8Array | string): Uint8Array;
+    static serializeValue(value: Uint8Array | string): string;
+}
 export declare class Upload extends PrimitiveScalar {
     static refName: "Upload";
     static [SERVER_VALUE]: File;
@@ -136,4 +148,4 @@ declare global {
         _checkValue(value: Date): void;
     }
 }
-export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Upload";
+export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Binary" | "Upload";

package/types/common/clientAddress.d.ts

@@ -0,0 +1,19 @@
+/** Headers a proxy hop writes so the next hop can still name the original caller. */
+export declare const forwardedHeaders: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto"];
+/**
+ * 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 declare const normalizeIpAddress: (address: string) => string;
+/**
+ * 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 declare const clientAddressFromHeaders: (headers: Headers) => string | null;
+/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
+export declare const clientPortFromHeaders: (headers: Headers) => number | null;

package/types/common/index.d.ts

@@ -1,5 +1,6 @@
 export { applyMixins } from "./applyMixins.d.ts";
 export { capitalize } from "./capitalize.d.ts";
+export { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress, } from "./clientAddress.d.ts";
 export { deepObjectify } from "./deepObjectify.d.ts";
 export { type FileUploadCapability, fileUploadContract, resolveFileUploadCapability, } from "./fileUpload.d.ts";
 export { formatNumber } from "./formatNumber.d.ts";
@@ -31,3 +32,4 @@ export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";
 export type * from "./types.d.ts";
 export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";
+export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame.d.ts";

package/types/common/websocketBinaryFrame.d.ts

@@ -0,0 +1,17 @@
+export interface WebsocketBinaryFrame {
+    roomId: string;
+    payload: Uint8Array;
+}
+/**
+ * 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 declare const websocketBinaryFrameContract: {
+    readonly encode: ({ roomId, payload }: WebsocketBinaryFrame) => Uint8Array;
+    readonly decode: (data: ArrayBuffer | Uint8Array) => WebsocketBinaryFrame | null;
+};

package/types/fetch/fetchType/appliedReturn.type.d.ts

@@ -14,6 +14,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<RefName extends string, Light, Insight = any, QueryArgs = any, Filter extends FilterInstance = any, _CapitalizedRefName extends string = Capitalize<RefName>, _LightObj = GetStateObject<Light>, _InsightObj = GetStateObject<Insight>, _Sort = ExtractSort<Filter>> = SliceMeta & {
     [K in `${RefName}ObjList`]: _LightObj[];

package/types/server/akanAppHeaders.d.ts

@@ -1 +1,7 @@
-export declare 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 declare function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?: ProxyClientPeer | null): Headers;

package/types/server/binaryPubsub.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare class BinaryPubsub {
+    #private;
+    get coalescedCount(): number;
+    setServers(...servers: (Bun.Server<never> | null)[]): void;
+    publish(roomId: string, frame: Uint8Array, { coalesce }?: {
+        coalesce?: boolean;
+    }): void;
+    /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
+    flush(): void;
+    clear(): void;
+}

package/types/server/resolver/signal.resolver.d.ts

@@ -7,12 +7,13 @@ import type { InternalInfo } from "../../signal/internalInfo.d.ts";
 import type { MiddlewareCls } from "../../signal/middleware.d.ts";
 import type { ServerSignalCls } from "../../signal/serverSignal.d.ts";
 import type { SliceCls } from "../../signal/slice.d.ts";
-import type { HttpRoutes, SignalRoutes } from "../types.d.ts";
+import type { HttpRoutes, LocalPublish, SignalRoutes } from "../types.d.ts";
 export declare class SignalResolver {
     #private;
     static logger: Logger;
     static makeRoomId(key: string, args: unknown[]): string;
-    static setLocalPublish(localPublish: (roomId: string, data: object | object[]) => void, websocket: WebsocketAdaptor): void;
+    static coalescesRoom(roomId: string): boolean;
+    static setLocalPublish(localPublish: LocalPublish, websocket: WebsocketAdaptor): void;
     static resolveServerSignal(serverSignalCls: ServerSignalCls, { registry, live }: {
         registry: InjectRegistry;
         live: LiveRegistry;

package/types/server/routing/apiRouter.d.ts

@@ -37,6 +37,7 @@ export interface WebsocketHandlersInputs {
     hmrHub: HmrWsHub | null;
     hmrState: HmrStateSource | null;
     logger: Logger;
+    onDrain?: () => void;
 }
 type WsTaggedData = {
     kind?: string;
@@ -56,6 +57,6 @@ export declare class ApiRouter {
      *   - `kind === "akan-hmr"` — dev HMR, delegated to `HmrWsHub`.
      *   - everything else — app signal channel, dispatched via `wsRoutes`.
      */
-    static buildWebsocketHandlers({ wsRoutes, registry, hmrHub, hmrState, logger, }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData>;
+    static buildWebsocketHandlers({ wsRoutes, registry, hmrHub, hmrState, logger, onDrain, }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData>;
 }
 export {};

package/types/server/routing/appWsData.d.ts

@@ -26,5 +26,11 @@ export declare 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;
+    /** The caller's source port as the nearest proxy recorded it, or null when nothing did. */
+    get port(): number | null;
+    /** The address to answer on: what a proxy recorded, else this socket's own peer. */
+    ipOf(ws: Bun.ServerWebSocket<unknown>): string | null;
     constructor(headers: Headers);
 }

package/types/server/types.d.ts

@@ -5,6 +5,7 @@ import type { SsrManifest } from "./ssrTypes.d.ts";
 export type WebsocketRoute = (ws: Bun.ServerWebSocket<unknown>, data: unknown[], event?: "message" | "subscribe" | "unsubscribe") => PromiseOrObject<unknown>;
 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;
 }

package/types/service/ipcTypes.d.ts

@@ -41,6 +41,7 @@ export interface AkanMetricsReport {
     queueWakeCount?: number;
     pubsubDeliverCount?: number;
     pubsubDropCount?: number;
+    pubsubCoalesceCount?: number;
     rssBytes?: number;
     heapTotalBytes?: number;
     heapUsedBytes?: number;

package/types/service/predefinedAdaptor/compress.adaptor.d.ts

@@ -5,7 +5,7 @@ export interface CompressAdaptor {
 }
 declare const JsonCompressor_base: import("..").AdaptorCls<{}, {}>;
 export declare class JsonCompressor extends JsonCompressor_base implements CompressAdaptor {
-    encode(_ref: Cls, _arrDepth: number, value: unknown): Buffer | null;
+    encode(ref: Cls, arrDepth: number, value: unknown): Buffer | null;
     decode<T = unknown>(ref: Cls, arrDepth: number, buffer: Buffer, { raw }?: {
         raw?: boolean;
     }): T;

package/types/signal/internalArg.d.ts

@@ -18,6 +18,16 @@ export declare class Res implements InternalArg {
         redirect(url: string | URL, status?: number): Response;
     };
 }
+/**
+ * Injects the caller's IP, as the nearest proxy recorded it rather than as the socket peer reports it.
+ * Behind the federation gateway every peer is the gateway, so an endpoint that reads `remoteAddress` sees
+ * `127.0.0.1` for every caller — this reads the forwarded headers first and falls back to the peer only
+ * when nothing proxied the call. IPv4 comes back unwrapped from `::ffff:`, so it can address a `udp4`
+ * socket. `null` when no proxy recorded one and the transport has no peer.
+ */
+export declare class Ip implements InternalArg<string | null> {
+    getArg(context: SignalContext): string | null;
+}
 /**
  * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
  * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to

package/types/signal/signalContext.d.ts

@@ -69,6 +69,18 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getHttpContext<Appended = unknown>(): HttpExecutionContext<Appended>;
     getWebSocketContext<Appended = unknown>(): WebSocketExecutionContext<Appended>;
     get<T = unknown>(key: string): T | null;
+    /**
+     * The caller's IP, preferring what a proxy recorded over the socket peer. Behind the federation gateway the
+     * peer is the gateway itself for every request and for the whole life of every socket, so `remoteAddress`
+     * alone names the wrong machine — which is why nothing here reads it first. IPv4 arrives unwrapped from its
+     * `::ffff:` form, so it can be used as a destination as well as an identity.
+     *
+     * `null` means no proxy recorded one and the transport has no peer to fall back on — never a placeholder,
+     * because a loopback-looking address for an unknown caller is the failure this replaced.
+     */
+    getClientIp(): string | null;
+    /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
+    getClientPort(): number | null;
     getRoomId(key: string): string;
     getEnv(): Env;
     getArg<T = unknown>(argName: string): T | undefined;

package/types/signal/types.d.ts

@@ -74,6 +74,13 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     method?: HttpMutationMethod;
     /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
     fileUpload?: boolean;
+    /**
+     * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
+     * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
+     * newer one exists. Name `"queue"` when the frames are a sequence a subscriber has to see in full, such as
+     * deltas against a base it already holds; the send buffer then grows with the slowest subscriber.
+     */
+    backpressure?: "coalesce" | "queue";
     scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
     scheduleCron?: string;
     scheduleTime?: number;

package/ui/Data/Dashboard.tsx

@@ -49,7 +49,8 @@ export default function Dashboard<T extends string, State>({
   const [selected, setSelected] = useState(typeof filter === "string" ? filter : undefined);
 
   const settingOf = (column: string): QuerySetting | undefined => {
-    if (queryMap?.[column]) return queryMap[column];
+    
+    if (queryMap?.[column]?.queryKey) return queryMap[column];
     const meta = fieldQueryMetaOf(summaryRefName, column);
     if (!meta?.queryKey || meta.refName !== slice.refName) return undefined;
     return { queryKey: meta.queryKey, args: meta.queryArgs };

package/ui/Data/QueryMaker.tsx

@@ -45,10 +45,10 @@ interface QueryMakerArgsProps {
 }
 
 /** A filter's args may be written as a thunk, so that an arg relative to now is read when the filter is applied. */
-export const resolveQuerySetting = (setting: QuerySetting): ResolvedQuerySetting => ({
-  queryKey: setting.queryKey,
-  args: typeof setting.args === "function" ? setting.args() : (setting.args ?? []),
-});
+export const resolveQuerySetting = (setting: QuerySetting): ResolvedQuerySetting => {
+  const args = setting.args ?? setting.queryArgs;
+  return { queryKey: setting.queryKey, args: typeof args === "function" ? args() : (args ?? []) };
+};
 
 const isFillableArg = (arg: SerializedArg) => !arg.modelType;
 const defaultArg = (arg: SerializedArg) => ((arg.arrDepth ?? 0) > 0 ? [] : null);

package/ui/Signal/Listener.tsx

@@ -20,8 +20,23 @@ interface ListenerResultProps {
   status: "ready" | "loading" | "error" | "listening";
   data: unknown;
 }
+/**
+ * A byte payload has no useful JSON form: `JSON.stringify` spells a `Uint8Array` as `{"0":2,"1":148,…}`, which
+ * is unreadable and, for one video chunk, megabytes of DOM. The head is enough to tell a stream apart.
+ */
+const previewBytes = (bytes: Uint8Array) => {
+  const head = [...bytes.subarray(0, 32)].map((byte) => byte.toString(16).padStart(2, "0")).join(" ");
+  return `Uint8Array(${bytes.length}) ${head}${bytes.length > 32 ? " …" : ""}`;
+};
+
+const replaceBytes = (_key: string, value: unknown) => {
+  if (!ArrayBuffer.isView(value)) return value;
+  const view = value as ArrayBufferView;
+  return previewBytes(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+};
+
 const ListenerResult = ({ status, data }: ListenerResultProps) => {
-  const dataStr = typeof data === "object" ? JSON.stringify(data, null, 2) : String(data);
+  const dataStr = typeof data === "object" ? JSON.stringify(data, replaceBytes, 2) : String(data);
   const ref = useRef<HTMLPreElement>(null);
   useEffect(() => {
     if (!ref.current) return;