castle-web-sdk 0.4.24 → 0.4.25

package/README.md

@@ -54,7 +54,18 @@ metadata distinguishes a server `bye`, a replaced server version, an explicit
 
 When Castle selects solo fallback, the returned connection has `isSolo === true`,
 a one-player roster, and no server process. Calls to `send` are accepted but do
-nothing. Client frames are limited to 16KB after JSON serialization.
+nothing. Client→server frames are limited to 16 KB on the wire.
+
+### Binary messages
+
+Pass any typed array, `DataView`, or `ArrayBuffer` to client `send`, server `send`,
+or server `broadcast` to send its raw bytes. Receivers always get those bytes as a
+`Uint8Array`; reconstruct another view type such as `Float32Array` on receipt.
+Multi-byte values use the sender platform's byte order. Every other payload uses
+JSON. Client→server messages are capped at 16 KB and server→client messages at
+64 KB, for both JSON and binary frames. A binary frame includes a one-byte protocol
+tag. A published server bundle on an older runtime throws
+`TypeError: This Castle runtime does not support binary multiplayer messages yet.`
 
 Server callbacks are the default export from the deck's server entry. They are
 session-first and receive only platform-trusted player identities:

package/dist/multiplayer.d.ts

@@ -31,7 +31,9 @@ export interface MultiplayerConnection {
     readonly playerId: string;
     readonly sessionId: string;
     readonly isSolo: boolean;
+    /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
+    /** Receives binary payloads as Uint8Array values and JSON payloads otherwise. */
     onMessage(callback: (data: unknown) => void): () => void;
     onRoster(callback: (roster: MultiplayerRoster) => void): () => void;
     onStateChange(callback: (state: MultiplayerConnectionState, metadata?: MultiplayerStateMetadata) => void): () => void;

package/dist/multiplayer.js

@@ -1,5 +1,5 @@
 import { CastleError } from "./errors";
-import { MAX_CLIENT_FRAME_BYTES, } from "./multiplayerProtocol";
+import { BINARY_MESSAGE_TAG, isBinaryPayload, MAX_CLIENT_FRAME_BYTES, toUint8Array, } from "./multiplayerProtocol";
 import { hostRequest } from "./transport";
 const KEEPALIVE_INTERVAL_MS = 25_000;
 const HELLO_TIMEOUT_MS = 10_000;
@@ -70,7 +70,9 @@ class MultiplayerConnectionImpl {
     // has no useful branch to take meanwhile, so those messages are dropped.
     // State arrives in whole snapshots, so the next send past recovery is current.
     send(data) {
-        const text = serializeClientMessage(data);
+        const payload = isBinaryPayload(data)
+            ? serializeClientBinaryMessage(data)
+            : serializeClientMessage(data);
         if (this.currentState === "closed") {
             throw multiplayerError("MULTIPLAYER_NOT_CONNECTED", "Multiplayer.send requires a connected session.", "Multiplayer.send");
         }
@@ -78,7 +80,7 @@ class MultiplayerConnectionImpl {
             return;
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
             return;
-        this.socket.send(text);
+        this.socket.send(payload);
     }
     onMessage(callback) {
         this.messages.add(callback);
@@ -132,27 +134,48 @@ class MultiplayerConnectionImpl {
     openSocket(credential, value) {
         const attempt = ++this.socketAttempt;
         const socket = new WebSocket(authenticatedUrl(this.baseUrl, credential, value));
+        socket.binaryType = "arraybuffer";
         this.socket = socket;
         return new Promise((resolve, reject) => {
             let greeted = false;
+            let inbound = Promise.resolve();
+            const isCurrent = () => this.socketAttempt === attempt &&
+                this.currentState !== "closed" &&
+                this.socket === socket;
             const timeout = setTimeout(() => {
                 reject(new SocketClosedError(1006));
                 closeSocket(socket, 1000, "hello timeout");
             }, HELLO_TIMEOUT_MS);
             socket.onmessage = (event) => {
-                if (this.socketAttempt !== attempt || this.currentState === "closed")
-                    return;
-                const frame = parsePlatformFrame(event.data);
-                if (!frame)
-                    return;
-                if (frame.t === "hello") {
-                    greeted = true;
-                    clearTimeout(timeout);
-                    this.acceptHello(frame);
-                    resolve();
-                    return;
-                }
-                this.handleFrame(frame);
+                const data = event.data;
+                inbound = inbound
+                    .then(async () => {
+                    if (!isCurrent())
+                        return;
+                    if (data instanceof ArrayBuffer) {
+                        this.dispatchBinary(data, greeted);
+                        return;
+                    }
+                    if (typeof Blob !== "undefined" && data instanceof Blob) {
+                        const buffer = await data.arrayBuffer();
+                        if (!isCurrent())
+                            return;
+                        this.dispatchBinary(buffer, greeted);
+                        return;
+                    }
+                    const frame = parsePlatformFrame(data);
+                    if (!frame)
+                        return;
+                    if (frame.t === "hello") {
+                        greeted = true;
+                        clearTimeout(timeout);
+                        this.acceptHello(frame);
+                        resolve();
+                        return;
+                    }
+                    this.handleFrame(frame);
+                })
+                    .catch(() => { });
             };
             socket.onclose = (event) => {
                 clearTimeout(timeout);
@@ -210,6 +233,16 @@ class MultiplayerConnectionImpl {
                 break;
         }
     }
+    dispatchBinary(buffer, greeted) {
+        if (!greeted)
+            return;
+        const bytes = new Uint8Array(buffer);
+        if (bytes.byteLength < 1 || bytes[0] !== BINARY_MESSAGE_TAG)
+            return;
+        const payload = new Uint8Array(buffer, 1);
+        for (const callback of this.messages)
+            callListener(callback, payload);
+    }
     acceptRoster(frame) {
         const players = frame.players.slice();
         const you = players.find((player) => player.playerId === this.currentPlayerId) ?? null;
@@ -363,6 +396,16 @@ function serializeClientMessage(data) {
     }
     return text;
 }
+function serializeClientBinaryMessage(data) {
+    const payload = toUint8Array(data);
+    if (payload.byteLength + 1 > MAX_CLIENT_FRAME_BYTES) {
+        throw multiplayerError("MULTIPLAYER_MESSAGE_TOO_LARGE", `Multiplayer.send messages are limited to ${MAX_CLIENT_FRAME_BYTES} bytes.`, "Multiplayer.send");
+    }
+    const frame = new Uint8Array(payload.byteLength + 1);
+    frame[0] = BINARY_MESSAGE_TAG;
+    frame.set(payload, 1);
+    return frame;
+}
 function authenticatedUrl(baseUrl, credential, value) {
     const fallback = typeof window === "undefined" ? undefined : window.location.href;
     const url = new URL(baseUrl, fallback);

package/dist/multiplayerProtocol.d.ts

@@ -1,5 +1,8 @@
 export declare const MAX_CLIENT_FRAME_BYTES: number;
 export declare const MAX_PLAYERS_CAP = 24;
+export declare const BINARY_MESSAGE_TAG = 1;
+export declare function isBinaryPayload(value: unknown): value is ArrayBuffer | ArrayBufferView;
+export declare function toUint8Array(value: ArrayBuffer | ArrayBufferView): Uint8Array;
 export type SessionType = "named" | "party" | "public";
 export interface PlayerIdentity {
     userId: string;

package/dist/multiplayerProtocol.js

@@ -3,3 +3,16 @@
 // published and must not pull the server package into deck bundles.
 export const MAX_CLIENT_FRAME_BYTES = 16 * 1024;
 export const MAX_PLAYERS_CAP = 24;
+// Binary client wire frames are one tag byte (0x01) followed by the opaque
+// author payload. The frame-size limit includes both the tag and payload.
+export const BINARY_MESSAGE_TAG = 0x01;
+// ArrayBuffer and every ArrayBufferView (typed arrays and DataView) are sent as
+// their raw bytes. Receivers always see a Uint8Array over those bytes.
+export function isBinaryPayload(value) {
+    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+export function toUint8Array(value) {
+    return value instanceof ArrayBuffer
+        ? new Uint8Array(value)
+        : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}

package/dist/server/platformHandle.d.ts

@@ -15,10 +15,13 @@ export interface PlatformSessionConfig {
 export interface PlatformHandle {
     send(connId: string, text: string): void;
     broadcast(text: string): void;
+    sendBinary?(connId: string, bytes: Uint8Array | ArrayBuffer): void;
+    broadcastBinary?(bytes: Uint8Array | ArrayBuffer): void;
     disconnect(connId: string, code: string | number): void;
     on(event: "join", callback: (connId: string, player: PlayerIdentity) => unknown): void;
     on(event: "leave", callback: (connId: string) => unknown): void;
     on(event: "message", callback: (connId: string, text: string) => unknown): void;
+    on(event: "binaryMessage", callback: (connId: string, bytes: Uint8Array) => unknown): void;
     on(event: "replaced", callback: () => unknown): void;
     on(event: "shutdown", callback: (reason?: string) => unknown): void;
     readonly config: PlatformSessionConfig;

package/dist/server/wrapper.d.ts

@@ -11,7 +11,9 @@ export interface MultiplayerServerSession {
     readonly sessionId: string;
     readonly deckId: string;
     readonly mode: MultiplayerSessionMode;
+    /** Sends bytes as a binary message and all other payloads as JSON. */
     send(playerId: string, data: unknown): void;
+    /** Broadcasts bytes as a binary message and all other payloads as JSON. */
     broadcast(data: unknown, options?: MultiplayerBroadcastOptions): void;
     disconnect(playerId: string, reason?: string): void;
 }
@@ -20,6 +22,7 @@ export interface MultiplayerServerCallbacks {
     onStart?: (session: MultiplayerServerSession) => CallbackResult;
     onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
     onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
+    /** Receives binary messages as Uint8Array values and JSON messages otherwise. */
     onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
     onTick?: (session: MultiplayerServerSession) => CallbackResult;
     onReplaced?: (session: MultiplayerServerSession) => CallbackResult;

package/dist/server/wrapper.js

@@ -1,3 +1,4 @@
+import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
 export function createCastleSessionBoot(callbacks) {
@@ -29,6 +30,17 @@ async function bootSession(platformHandle, callbacks) {
             return;
         await callbacks.onMessage?.(session, player, parseHandleMessage(text));
     });
+    try {
+        platformHandle.on("binaryMessage", async (connId, bytes) => {
+            const player = players.get(connId);
+            if (!player)
+                return;
+            await callbacks.onMessage?.(session, player, bytes);
+        });
+    }
+    catch {
+        // Older shims may reject event names they do not recognize.
+    }
     platformHandle.on("replaced", async () => {
         await callbacks.onReplaced?.(session);
     });
@@ -54,9 +66,28 @@ function createAuthorSession(platformHandle, players) {
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
         send(playerId, data) {
+            if (isBinaryPayload(data)) {
+                requireSendBinary(platformHandle);
+                platformHandle.sendBinary(playerId, toUint8Array(data));
+                return;
+            }
             platformHandle.send(playerId, stringifyHandleMessage(data));
         },
         broadcast(data, options) {
+            if (isBinaryPayload(data)) {
+                const bytes = toUint8Array(data);
+                if (!options?.except) {
+                    requireBroadcastBinary(platformHandle);
+                    platformHandle.broadcastBinary(bytes);
+                    return;
+                }
+                requireSendBinary(platformHandle);
+                for (const playerId of players.keys()) {
+                    if (playerId !== options.except)
+                        platformHandle.sendBinary(playerId, bytes);
+                }
+                return;
+            }
             const text = stringifyHandleMessage(data);
             if (!options?.except) {
                 platformHandle.broadcast(text);
@@ -72,6 +103,17 @@ function createAuthorSession(platformHandle, players) {
         },
     };
 }
+function requireSendBinary(platformHandle) {
+    if (typeof platformHandle.sendBinary !== "function")
+        unsupportedBinaryRuntime();
+}
+function requireBroadcastBinary(platformHandle) {
+    if (typeof platformHandle.broadcastBinary !== "function")
+        unsupportedBinaryRuntime();
+}
+function unsupportedBinaryRuntime() {
+    throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
+}
 function joinedPlayer(connId, identity) {
     if (typeof connId === "string")
         return { ...identity, playerId: connId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",