@noya-app/noya-multiplayer-react 0.1.89 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noya-app/noya-multiplayer-react",
-  "version": "0.1.89",
+  "version": "0.2.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     "dev": "npm run build -- --watch"
   },
   "dependencies": {
-    "@noya-app/state-manager": "0.2.0",
+    "@noya-app/state-manager": "0.3.0",
     "@noya-app/emitter": "0.1.0",
     "@noya-app/observable": "0.1.12",
     "@noya-app/task-runner": "0.1.7",

package/src/WebSocketConnection.ts

@@ -1,38 +1,122 @@
 import {
+  ClientMessageBatch,
+  ClientTransportMessage,
   ClientToServerMessage,
-  MultiplayerStateManagerError,
+  ConnectionEvent as StateManagerConnectionEvent,
+  EnqueueInputMessage,
+  MAX_CLIENT_MESSAGE_BATCH_SIZE,
+  MAX_REALTIME_INPUT_BATCHES_IN_FLIGHT,
   ReconnectingWebSocket,
   ReconnectingWebSocketState,
   ServerToClientMessage,
+  SimulationFrameReceiptMessage,
   UserActivityDetector,
 } from "@noya-app/state-manager";
 
-export type ConnectionEvent<State> =
-  | {
-      type: "stateChange";
-      state: ReconnectingWebSocketState;
-    }
-  | {
-      type: "send";
-      message: ClientToServerMessage<State>;
-    }
-  | {
-      type: "receive";
-      message: ServerToClientMessage<State>;
-    }
-  | {
-      type: "error";
-      error: MultiplayerStateManagerError;
-    };
+export type ConnectionEvent<State> = StateManagerConnectionEvent<State>;
 
 export type ConnectionOptions<State> = {
   debug?: boolean;
+  heartbeatIntervalMs?: number;
+  silentTimeoutMs?: number;
+  realtimeInputWatchdogMs?: number;
   onConnectionEvent?: (event: ConnectionEvent<State>) => void;
 };
 
+type SimulationResumeCursor = {
+  sequence: number;
+  sessionIdentity?: string;
+};
+
+function simulationSessionIdentity(state: unknown) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return;
+  const game = Reflect.get(state, "$game");
+  if (!game || typeof game !== "object" || Array.isArray(game)) return;
+  const startedAt = Reflect.get(game, "startedAt");
+  if (
+    startedAt === null ||
+    typeof startedAt === "string" ||
+    (typeof startedAt === "number" && Number.isFinite(startedAt))
+  ) {
+    return `startedAt:${typeof startedAt}:${String(startedAt)}`;
+  }
+}
+
+function simulationStateSequence(state: unknown) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return;
+  const simulation = Reflect.get(state, "simulation");
+  const simulationTick =
+    simulation && typeof simulation === "object"
+      ? Reflect.get(simulation, "tick")
+      : undefined;
+  if (Number.isSafeInteger(simulationTick) && (simulationTick as number) >= 0) {
+    return simulationTick as number;
+  }
+  const game = Reflect.get(state, "$game");
+  const gameTick =
+    game && typeof game === "object"
+      ? Reflect.get(game, "simulationTick")
+      : undefined;
+  return Number.isSafeInteger(gameTick) && (gameTick as number) >= 0
+    ? (gameTick as number)
+    : undefined;
+}
+
+function sameSimulationSession(
+  left: SimulationResumeCursor,
+  right: SimulationResumeCursor
+) {
+  return (
+    left.sessionIdentity === undefined ||
+    right.sessionIdentity === undefined ||
+    left.sessionIdentity === right.sessionIdentity
+  );
+}
+
+function createRealtimeInputSessionId() {
+  return typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
 export class WebSocketConnection<State> {
   private ws: ReconnectingWebSocket;
   private closedForever = false;
+  private heartbeatIntervalHandle?: ReturnType<typeof setInterval>;
+  private silentTimeoutHandle?: ReturnType<typeof setTimeout>;
+  private simulationClockPulseIntervalHandle?: ReturnType<typeof setInterval>;
+  private simulationClockPulseSocket?: ReconnectingWebSocket;
+  private simulationClockDirectFailed = false;
+  private heartbeatSequence = 0;
+  private pendingSimulationFrames = new Map<
+    string,
+    Extract<ServerToClientMessage<State>, { type: "simulationFrame" }>
+  >();
+  private frameFlushHandle?: number;
+  private frameFlushScheduler?: "animationFrame" | "timeout";
+  private droppedSimulationFrames = 0;
+  private pendingFrameReceipts = new Map<
+    string,
+    SimulationFrameReceiptMessage
+  >();
+  private deliveredSimulationFrameCursors = new Map<
+    string,
+    SimulationResumeCursor
+  >();
+  private queuedRealtimeInputs: EnqueueInputMessage[] = [];
+  /**
+   * A batch stays here until the server explicitly confirms ingestion.
+   * Reconnects resend these exact batches, so a frame that was already in
+   * flight can never create a hole in an input stream.
+   */
+  private unconfirmedRealtimeBatches: ClientMessageBatch[] = [];
+  private lastSentRealtimeSequences = new Map<string, number>();
+  private readonly realtimeInputSessionId = createRealtimeInputSessionId();
+  private nextRealtimeInputBatchSequence = 0;
+  private realtimeInputWatchdogHandle?: ReturnType<typeof setTimeout>;
+  private realtimeBatchesSent = 0;
+  private realtimeInputsSent = 0;
 
   constructor(
     private url: URL,
@@ -56,6 +140,10 @@ export class WebSocketConnection<State> {
   private handleOpen = () => {
     if (this.closedForever) return;
 
+    this.startHeartbeat();
+    this.replayUnconfirmedRealtimeBatches();
+    this.armRealtimeInputWatchdog();
+
     if (this.options.debug) {
       console.info("ws connected");
     }
@@ -69,19 +157,151 @@ export class WebSocketConnection<State> {
   private handleMessage = (event: MessageEvent) => {
     if (this.closedForever) return;
 
+    this.armSilentTimeout();
+
     if (this.options.debug) {
       console.info("ws receiving message ", event.data);
     }
 
     const parsed = JSON.parse(event.data) as ServerToClientMessage<State>;
+    if (parsed.type === "simulationClockConfig") {
+      this.applySimulationClockConfig(parsed);
+      return;
+    }
+    if (parsed.type === "simulationFrame") {
+      const cursor = {
+        sequence: parsed.frame.sequence,
+        sessionIdentity: simulationSessionIdentity(parsed.frame.state),
+      };
+      const receipt: SimulationFrameReceiptMessage = {
+        type: "simulationFrameReceipt",
+        scriptId: parsed.frame.scriptId,
+        sequence: parsed.frame.sequence,
+      };
+      const pendingReceipt = this.pendingFrameReceipts.get(
+        parsed.frame.scriptId
+      );
+      if (!pendingReceipt || receipt.sequence > pendingReceipt.sequence) {
+        this.pendingFrameReceipts.set(parsed.frame.scriptId, receipt);
+      }
+      const delivered = this.deliveredSimulationFrameCursors.get(
+        parsed.frame.scriptId
+      );
+      const pending = this.pendingSimulationFrames.get(parsed.frame.scriptId);
+      const pendingCursor = pending
+        ? {
+            sequence: pending.frame.sequence,
+            sessionIdentity: simulationSessionIdentity(pending.frame.state),
+          }
+        : undefined;
+      if (
+        (delivered &&
+          sameSimulationSession(delivered, cursor) &&
+          cursor.sequence <= delivered.sequence) ||
+        (pendingCursor &&
+          sameSimulationSession(pendingCursor, cursor) &&
+          cursor.sequence <= pendingCursor.sequence)
+      ) {
+        this.droppedSimulationFrames += 1;
+        this.scheduleSimulationFrameFlush();
+        return;
+      }
+      if (pending) this.droppedSimulationFrames += 1;
+      this.pendingSimulationFrames.set(parsed.frame.scriptId, parsed);
+      this.scheduleSimulationFrameFlush();
+      return;
+    }
+    if (
+      parsed.type === "object" &&
+      this.shouldSuppressNonMonotonicObject(parsed.object)
+    ) {
+      return;
+    }
+
+    if (parsed.type === "realtimeInputReceipt") {
+      this.confirmRealtimeInputBatches(parsed.sessionId, parsed.sequence);
+      return;
+    }
+    this.flushSimulationFrames();
+    this.emitReceivedMessage(parsed);
+  };
 
+  private emitReceivedMessage(message: ServerToClientMessage<State>) {
     this.options.onConnectionEvent?.({
       type: "receive",
-      message: parsed,
+      message,
     });
-  };
+  }
+
+  private scheduleSimulationFrameFlush() {
+    if (this.frameFlushHandle !== undefined) return;
+    const flush = () => {
+      this.frameFlushHandle = undefined;
+      this.frameFlushScheduler = undefined;
+      this.flushSimulationFrames();
+    };
+    if (typeof requestAnimationFrame === "function") {
+      this.frameFlushScheduler = "animationFrame";
+      this.frameFlushHandle = requestAnimationFrame(flush);
+    } else {
+      this.frameFlushScheduler = "timeout";
+      this.frameFlushHandle = setTimeout(flush, 0) as unknown as number;
+    }
+  }
+
+  private flushSimulationFrames() {
+    this.cancelSimulationFrameFlush();
+    this.flushPendingFrameReceipts();
+    const frames = Array.from(this.pendingSimulationFrames.values());
+    this.pendingSimulationFrames.clear();
+    for (const frame of frames) {
+      this.deliveredSimulationFrameCursors.set(frame.frame.scriptId, {
+        sequence: frame.frame.sequence,
+        sessionIdentity: simulationSessionIdentity(frame.frame.state),
+      });
+      this.emitReceivedMessage(frame);
+    }
+  }
+
+  private shouldSuppressNonMonotonicObject(state: State) {
+    const sequence = simulationStateSequence(state);
+    if (sequence === undefined) return false;
+    const cursor = {
+      sequence,
+      sessionIdentity: simulationSessionIdentity(state),
+    };
+    const previous = Array.from(this.deliveredSimulationFrameCursors.values());
+    const comparable = previous.filter((entry) =>
+      sameSimulationSession(entry, cursor)
+    );
+    if (
+      cursor.sessionIdentity !== undefined &&
+      previous.some((entry) => entry.sessionIdentity !== undefined) &&
+      comparable.length === 0
+    ) {
+      this.deliveredSimulationFrameCursors.clear();
+      return false;
+    }
+    return comparable.some((entry) => entry.sequence > cursor.sequence);
+  }
+
+  private cancelSimulationFrameFlush() {
+    if (this.frameFlushHandle === undefined) return;
+
+    if (this.frameFlushScheduler === "animationFrame") {
+      cancelAnimationFrame(this.frameFlushHandle);
+    } else {
+      clearTimeout(this.frameFlushHandle);
+    }
+    this.frameFlushHandle = undefined;
+    this.frameFlushScheduler = undefined;
+  }
 
   private handleClose = () => {
+    this.stopHeartbeat();
+    this.stopSimulationClockPulses();
+    this.stopRealtimeInputWatchdog();
+
     if (this.closedForever) return;
 
     if (this.options.debug) {
@@ -94,9 +314,180 @@ export class WebSocketConnection<State> {
     });
   };
 
+  private startHeartbeat() {
+    this.stopHeartbeat();
+    this.armSilentTimeout();
+
+    const intervalMs = this.options.heartbeatIntervalMs ?? 15_000;
+    if (intervalMs <= 0) return;
+
+    this.heartbeatIntervalHandle = setInterval(() => {
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+
+      this.send({
+        type: "ping",
+        id: `heartbeat-${Date.now()}-${++this.heartbeatSequence}`,
+        clientSentAt: Date.now(),
+      });
+    }, intervalMs);
+  }
+
+  private armSilentTimeout() {
+    if (this.silentTimeoutHandle !== undefined) {
+      clearTimeout(this.silentTimeoutHandle);
+      this.silentTimeoutHandle = undefined;
+    }
+
+    const timeoutMs = this.options.silentTimeoutMs ?? 45_000;
+    if (timeoutMs <= 0 || this.closedForever || this.ws.state !== "OPEN")
+      return;
+
+    this.silentTimeoutHandle = setTimeout(() => {
+      this.silentTimeoutHandle = undefined;
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+
+      this.stopSimulationClockPulses();
+      this.stopHeartbeat();
+      this.ws.reconnect();
+    }, timeoutMs);
+  }
+
+  private stopHeartbeat() {
+    if (this.heartbeatIntervalHandle !== undefined) {
+      clearInterval(this.heartbeatIntervalHandle);
+      this.heartbeatIntervalHandle = undefined;
+    }
+    if (this.silentTimeoutHandle !== undefined) {
+      clearTimeout(this.silentTimeoutHandle);
+      this.silentTimeoutHandle = undefined;
+    }
+    this.cancelSimulationFrameFlush();
+    this.pendingSimulationFrames.clear();
+    this.pendingFrameReceipts.clear();
+  }
+
+  private applySimulationClockConfig(
+    config: Extract<
+      ServerToClientMessage<State>,
+      { type: "simulationClockConfig" }
+    >
+  ) {
+    this.stopSimulationClockPulses();
+    if (
+      config.enabled !== true ||
+      !Number.isFinite(config.intervalMs) ||
+      config.intervalMs <= 0 ||
+      this.closedForever ||
+      this.ws.state !== "OPEN"
+    ) {
+      return;
+    }
+
+    const intervalMs = Math.max(1, Math.floor(config.intervalMs));
+    if (config.pulsePath !== undefined) {
+      this.openSimulationClockPulseSocket(config.pulsePath);
+    }
+    this.simulationClockPulseIntervalHandle = setInterval(() => {
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+      const pulse = JSON.stringify({ type: "simulationClockPulse" });
+      if (this.simulationClockPulseSocket?.state === "OPEN") {
+        this.simulationClockPulseSocket.send(pulse);
+        return;
+      }
+      if (
+        this.simulationClockPulseSocket &&
+        !this.simulationClockDirectFailed
+      ) {
+        return;
+      }
+      this.sendTransportMessage({ type: "simulationClockPulse" });
+    }, intervalMs);
+  }
+
+  private openSimulationClockPulseSocket(pulsePath: string) {
+    if (
+      !pulsePath.startsWith("/") ||
+      pulsePath.includes("?") ||
+      pulsePath.includes("#")
+    ) {
+      this.simulationClockDirectFailed = true;
+      return;
+    }
+    const pulseUrl = new URL(this.url);
+    pulseUrl.pathname = pulsePath;
+    pulseUrl.hash = "";
+    const socket = new ReconnectingWebSocket({
+      onopen: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = false;
+      },
+      onclose: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = true;
+      },
+      onerror: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = true;
+      },
+    });
+    this.simulationClockPulseSocket = socket;
+    this.simulationClockDirectFailed = false;
+    try {
+      socket.connect(pulseUrl.toString());
+    } catch {
+      this.simulationClockPulseSocket = undefined;
+      this.simulationClockDirectFailed = true;
+      socket.shutdown();
+    }
+  }
+
+  private stopSimulationClockPulses() {
+    if (this.simulationClockPulseIntervalHandle !== undefined) {
+      clearInterval(this.simulationClockPulseIntervalHandle);
+      this.simulationClockPulseIntervalHandle = undefined;
+    }
+    const socket = this.simulationClockPulseSocket;
+    this.simulationClockPulseSocket = undefined;
+    this.simulationClockDirectFailed = false;
+    socket?.shutdown();
+  }
+
+  getSimulationFrameDiagnostics() {
+    return {
+      pending: this.pendingSimulationFrames.size,
+      dropped: this.droppedSimulationFrames,
+      pendingReceipts: this.pendingFrameReceipts.size,
+      queuedRealtimeInputs: this.queuedRealtimeInputs.length,
+      replayRealtimeInputs: this.unconfirmedRealtimeBatches.reduce(
+        (count, batch) => count + batch.messages.length,
+        0
+      ),
+      unconfirmedRealtimeBatches: this.unconfirmedRealtimeBatches.length,
+      realtimeBatchesSent: this.realtimeBatchesSent,
+      realtimeInputsSent: this.realtimeInputsSent,
+      realtimeWatchdogArmed: this.realtimeInputWatchdogHandle !== undefined,
+      simulationClockPulsesActive:
+        this.simulationClockPulseIntervalHandle !== undefined,
+    };
+  }
+
   send(message: ClientToServerMessage<State>) {
     if (this.closedForever) return;
 
+    if (
+      message.type === "enqueueInput" &&
+      message.transport === "realtime" &&
+      this.getRealtimeInputSequence(message)
+    ) {
+      this.queuedRealtimeInputs.push(message);
+      this.armRealtimeInputWatchdog();
+      return;
+    }
+
+    this.sendTransportMessage(message);
+  }
+
+  private sendTransportMessage(message: ClientTransportMessage<State>) {
     if (this.options.debug) {
       console.info("ws sending message", message);
     }
@@ -109,10 +500,155 @@ export class WebSocketConnection<State> {
     this.ws.send(JSON.stringify(message));
   }
 
+  private getRealtimeInputSequence(message: EnqueueInputMessage) {
+    const payload = message.payload;
+    if (!payload || typeof payload !== "object") return;
+    const streamId = Reflect.get(payload, "streamId");
+    const sequence = Reflect.get(payload, "sequence");
+    if (
+      typeof streamId !== "string" ||
+      streamId.length === 0 ||
+      !Number.isInteger(sequence) ||
+      (sequence as number) < 0
+    ) {
+      return;
+    }
+    return {
+      key: `${message.queue}\u0000${streamId}`,
+      sequence: sequence as number,
+    };
+  }
+
+  private getContiguousRealtimeInputCount() {
+    const sequences = new Map(this.lastSentRealtimeSequences);
+    let count = 0;
+    for (const message of this.queuedRealtimeInputs) {
+      if (count >= MAX_CLIENT_MESSAGE_BATCH_SIZE) break;
+      const input = this.getRealtimeInputSequence(message);
+      if (!input) break;
+      const previous = sequences.get(input.key);
+      if (input.sequence !== (previous === undefined ? 0 : previous + 1)) {
+        break;
+      }
+      sequences.set(input.key, input.sequence);
+      count += 1;
+    }
+    return { count, sequences };
+  }
+
+  private flushRealtimeBatch(receipt?: SimulationFrameReceiptMessage) {
+    if (this.closedForever || this.ws.state !== "OPEN") return false;
+    const canSendInputBatch =
+      this.unconfirmedRealtimeBatches.length <
+      MAX_REALTIME_INPUT_BATCHES_IN_FLIGHT;
+    const contiguous = this.getContiguousRealtimeInputCount();
+    const messages = canSendInputBatch
+      ? this.queuedRealtimeInputs.slice(0, contiguous.count)
+      : [];
+    if (!receipt && messages.length === 0) return false;
+
+    const batch: ClientMessageBatch = {
+      type: "clientMessageBatch",
+      ...(receipt && { receipt }),
+      ...(messages.length > 0 && {
+        inputBatch: {
+          sessionId: this.realtimeInputSessionId,
+          sequence: this.nextRealtimeInputBatchSequence,
+        },
+      }),
+      messages,
+    };
+    this.sendTransportMessage(batch);
+    if (messages.length > 0) {
+      this.queuedRealtimeInputs.splice(0, messages.length);
+      this.lastSentRealtimeSequences = contiguous.sequences;
+      this.unconfirmedRealtimeBatches.push(batch);
+      this.nextRealtimeInputBatchSequence += 1;
+      this.realtimeInputsSent += messages.length;
+    }
+    this.realtimeBatchesSent += 1;
+    return true;
+  }
+
+  private flushPendingFrameReceipts() {
+    for (const [scriptId, receipt] of Array.from(
+      this.pendingFrameReceipts.entries()
+    )) {
+      if (!this.flushRealtimeBatch(receipt)) continue;
+      if (this.pendingFrameReceipts.get(scriptId) === receipt) {
+        this.pendingFrameReceipts.delete(scriptId);
+      }
+    }
+    if (this.queuedRealtimeInputs.length > 0) {
+      this.armRealtimeInputWatchdog();
+    } else {
+      this.stopRealtimeInputWatchdog();
+    }
+  }
+
+  private armRealtimeInputWatchdog() {
+    if (
+      this.realtimeInputWatchdogHandle !== undefined ||
+      this.queuedRealtimeInputs.length === 0 ||
+      this.closedForever ||
+      this.ws.state !== "OPEN"
+    ) {
+      return;
+    }
+    const configuredDelay = this.options.realtimeInputWatchdogMs;
+    const delay =
+      configuredDelay !== undefined && Number.isFinite(configuredDelay)
+        ? Math.max(1, Math.floor(configuredDelay))
+        : 200;
+    this.realtimeInputWatchdogHandle = setTimeout(() => {
+      this.realtimeInputWatchdogHandle = undefined;
+      this.flushRealtimeBatch();
+      if (this.queuedRealtimeInputs.length > 0) {
+        this.armRealtimeInputWatchdog();
+      }
+    }, delay);
+  }
+
+  private stopRealtimeInputWatchdog() {
+    if (this.realtimeInputWatchdogHandle === undefined) return;
+    clearTimeout(this.realtimeInputWatchdogHandle);
+    this.realtimeInputWatchdogHandle = undefined;
+  }
+
+  private replayUnconfirmedRealtimeBatches() {
+    if (this.closedForever || this.ws.state !== "OPEN") return;
+    for (const batch of this.unconfirmedRealtimeBatches) {
+      this.sendTransportMessage(batch);
+    }
+  }
+
+  private confirmRealtimeInputBatches(sessionId: string, sequence: number) {
+    if (
+      sessionId !== this.realtimeInputSessionId ||
+      !Number.isInteger(sequence) ||
+      sequence < 0
+    ) {
+      return;
+    }
+    this.unconfirmedRealtimeBatches = this.unconfirmedRealtimeBatches.filter(
+      (batch) => !batch.inputBatch || batch.inputBatch.sequence > sequence
+    );
+    if (this.queuedRealtimeInputs.length > 0) {
+      this.armRealtimeInputWatchdog();
+    }
+  }
+
   close() {
     if (this.closedForever) return;
 
     this.closedForever = true;
+    this.stopHeartbeat();
+    this.stopSimulationClockPulses();
+    this.stopRealtimeInputWatchdog();
+    this.queuedRealtimeInputs = [];
+    this.unconfirmedRealtimeBatches = [];
+    this.lastSentRealtimeSequences.clear();
+    this.deliveredSimulationFrameCursors.clear();
     this.ws.shutdown();
 
     // remove all listeners