@dreamboard-games/cli 0.1.30-alpha.0

package/dist/runtime-packages/ui-host-runtime/src/session-ingress-controller.ts

@@ -0,0 +1,583 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { ValidationResult } from "@dreamboard-games/sdk/runtime/runtime-api";
+import type { LoggerLike } from "./logger.js";
+import {
+  PERF_MARK_NAMES,
+  correlateVersion,
+  correlateSyncId,
+  findActionIdByVersion,
+  recordMark,
+} from "./perf.js";
+import type { HostSessionTransport } from "./host-session-transport.js";
+import type {
+  HostActionSubmitWireResponse,
+  NormalizedSubmitResponse,
+} from "./session-ingress.js";
+import {
+  normalizeEvent,
+  normalizeSnapshot,
+  normalizeSubmitResponse,
+} from "./session-ingress.js";
+import { getSessionRecoveryDetails } from "./session-recovery.js";
+import {
+  getGameplayViewport,
+  getSessionContext,
+  resolveControllablePlayerIds,
+} from "./session-model.js";
+import type { SSEManagerLike } from "./session-live-runtime.js";
+import { createSessionLiveRuntime } from "./session-live-runtime.js";
+import {
+  createInitialUnifiedSessionState,
+  reduceSessionState,
+  type SessionStateEffect,
+  type SessionStateIngress,
+  type SessionStateReducerEnvironment,
+  type UnifiedSessionState,
+} from "./session-state-reducer.js";
+
+export interface SessionIngressControllerActions {
+  loadSessionByShortCode: (input: {
+    shortCode: string;
+    userId?: string | null;
+    requestedPlayerId?: string | null;
+    source?: string;
+  }) => Promise<void>;
+  loadSessionSnapshot: (input: {
+    sessionId: string;
+    userId?: string | null;
+    requestedPlayerId?: string | null;
+    expectedPerspectivePlayerId?: string | null;
+    source?: string;
+  }) => Promise<void>;
+  startSession: (input: {
+    sessionId: string;
+    userId?: string | null;
+    source?: string;
+  }) => Promise<void>;
+  submitInteraction: (input: {
+    sessionId: string;
+    playerId: string;
+    interactionId: string;
+    params: unknown;
+    clientActionId?: string | null;
+  }) => Promise<void>;
+  validateInteraction: (input: {
+    sessionId: string;
+    playerId: string;
+    interactionId: string;
+    params: unknown;
+  }) => Promise<ValidationResult>;
+  restoreHistory: (input: {
+    sessionId: string;
+    entryId: string;
+  }) => Promise<void>;
+  selectPlayer: (playerId: string) => void;
+  clearConnectionError: () => void;
+  enqueueActionRejected: (reason: string, targetPlayer?: string) => void;
+  closeStreams: () => void;
+  onStateAck: (syncId: number) => void;
+  markNotificationRead: (id: string) => void;
+  clearNotifications: () => void;
+  dismissHostFeedback: (id: string) => void;
+  clearHostFeedback: () => void;
+  clearSSEEvents: () => void;
+  reset: () => void;
+}
+
+export interface CreateSessionIngressControllerOptions<
+  TStore extends UnifiedSessionState,
+> {
+  store: StoreApi<TStore>;
+  createSseManager: () => SSEManagerLike;
+  transport: HostSessionTransport;
+  logger: LoggerLike;
+  fallbackToAllSeatsWhenUserIdMissing: boolean;
+  reducerEnvironment: SessionStateReducerEnvironment;
+}
+
+function describeSseError(error: unknown): string {
+  if (error instanceof Error) {
+    if (
+      error.message.includes("429") ||
+      error.message.includes("400 Bad Request")
+    ) {
+      return "Too many live views are open for this session. Close unused tabs or devices, then refresh.";
+    }
+    return "Live session updates disconnected. Check your network and refresh to reconnect.";
+  }
+  return "Live session updates disconnected. Refresh to reconnect.";
+}
+
+function describeCommandFailure(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+  const payload = error as { detail?: unknown; message?: unknown } | null;
+  if (typeof payload?.detail === "string" && payload.detail.trim()) {
+    return payload.detail;
+  }
+  if (typeof payload?.message === "string" && payload.message.trim()) {
+    return payload.message;
+  }
+  return fallback;
+}
+
+function createSubmissionError(
+  errorCode: string | undefined,
+  message: string | undefined,
+): Error & { errorCode?: string } {
+  const error = new Error(message ?? "Interaction rejected") as Error & {
+    errorCode?: string;
+  };
+  error.name = "SubmissionError";
+  error.errorCode = errorCode;
+  return error;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function createSessionIngressController<
+  TStore extends UnifiedSessionState,
+>(
+  options: CreateSessionIngressControllerOptions<TStore>,
+): SessionIngressControllerActions {
+  const {
+    store,
+    transport,
+    logger,
+    fallbackToAllSeatsWhenUserIdMissing,
+    reducerEnvironment,
+  } = options;
+
+  const dispatchIngress = (ingress: SessionStateIngress) => {
+    const { state, effects } = reduceSessionState(
+      store.getState(),
+      ingress,
+      reducerEnvironment,
+    );
+    store.setState(state as Partial<TStore>);
+    effects.forEach(executeEffect);
+  };
+
+  const runtime = createSessionLiveRuntime({
+    createSseManager: options.createSseManager,
+    onConnectionChange: (channel, connected) => {
+      dispatchIngress({ type: "connection.changed", channel, connected });
+    },
+    onConnectionError: (error) => {
+      logger.error("[UnifiedSession] SSE connection error:", error);
+      dispatchIngress({
+        type: "connection.failed",
+        message: describeSseError(error),
+      });
+    },
+    onConnectionRecovering: (details) => {
+      dispatchIngress({
+        type: "connection.recovering",
+        message: details.message,
+        retryAfterMs: details.retryAfterMs,
+        attempt: details.attempt,
+      });
+    },
+    onLiveMessage: (message) => {
+      const state = store.getState();
+      const context = getSessionContext(state.session);
+      const event = normalizeEvent(message, {
+        currentContext: context,
+        currentGameplay: getGameplayViewport(state.session),
+        userId: context?.userId ?? null,
+      });
+      dispatchIngress({
+        type: "event.received",
+        source: "sse",
+        event,
+        debugEvent: { eventType: message.type, data: message },
+        clientActionId:
+          message.type === "session.gameplayUpdated"
+            ? message.causation?.clientActionId
+            : undefined,
+      });
+    },
+  });
+
+  function executeEffect(effect: SessionStateEffect): void {
+    switch (effect.type) {
+      case "requestGameplayResync":
+        logger.warn(
+          `[UnifiedSession] ${effect.reason}; reconnecting to refresh gameplay.bootstrap`,
+        );
+        runtime.requestGameplayResync(
+          effect.sessionId,
+          effect.playerId,
+          "board-static-resync",
+        );
+        break;
+      case "reconnectGameplay":
+        runtime.reconnectGameplay(
+          effect.sessionId,
+          effect.playerId,
+          effect.source,
+        );
+        break;
+      case "perf.storeApplied": {
+        const actionId = findActionIdByVersion(effect.gameplayVersion);
+        if (!actionId) break;
+        recordMark(actionId, PERF_MARK_NAMES.T5_STORE_APPLIED, {
+          extra: {
+            version: effect.gameplayVersion,
+            syncId: effect.syncId,
+          },
+        });
+        correlateSyncId(actionId, effect.syncId);
+        break;
+      }
+      case "log.warn":
+        logger.warn(effect.message);
+        break;
+    }
+  }
+
+  function connectLiveSession(
+    sessionId: string,
+    userId: string | null,
+    connectOptions: { source?: string; playerId?: string } = {},
+  ) {
+    const context = getSessionContext(store.getState().session);
+    const controllablePlayerIds = context
+      ? resolveControllablePlayerIds(
+          context.switchablePlayerIds,
+          context.seats,
+          userId,
+          fallbackToAllSeatsWhenUserIdMissing,
+        )
+      : [];
+    const session = store.getState().session;
+    const playerId =
+      connectOptions.playerId ??
+      (session.type === "gameplay"
+        ? session.perspective.playerId
+        : controllablePlayerIds[0]);
+    dispatchIngress({
+      type: "connection.prepared",
+      userId,
+      switchablePlayerIds: controllablePlayerIds,
+    });
+    logger.log(`[UnifiedSession] Connecting to session: ${sessionId}`);
+    runtime.connectSession(sessionId, {
+      source: connectOptions.source,
+      playerId,
+    });
+  }
+
+  async function runSnapshotCommand(
+    input: {
+      target?: { sessionId?: string; shortCode?: string };
+      sourceLabel: "short-code" | "snapshot" | "start" | "dev-new";
+      connectSource?: string;
+      userId?: string | null;
+      expectedPerspectivePlayerId?: string | null;
+      preserveCurrentOnFailure?: boolean;
+      load: () => Promise<
+        Awaited<ReturnType<HostSessionTransport["loadSessionSnapshot"]>>
+      >;
+    },
+    failureMessage: string,
+  ): Promise<void> {
+    if (!input.preserveCurrentOnFailure) {
+      dispatchIngress({ type: "command.loading", target: input.target });
+    }
+    let recoveryAttempt = 0;
+    while (true) {
+      try {
+        const snapshot = await input.load();
+        const normalized = normalizeSnapshot(snapshot, {
+          userId: input.userId ?? null,
+          previousGameplay: getGameplayViewport(store.getState().session),
+        });
+        dispatchIngress({
+          type: "snapshot.loaded",
+          source: input.sourceLabel,
+          snapshot: normalized,
+          expectedPerspectivePlayerId: input.expectedPerspectivePlayerId,
+        });
+        connectLiveSession(
+          normalized.context.identity.sessionId,
+          input.userId ?? null,
+          {
+            source: input.connectSource,
+            playerId:
+              normalized.type === "gameplay"
+                ? normalized.perspective.playerId
+                : undefined,
+          },
+        );
+        return;
+      } catch (error) {
+        const recovery = getSessionRecoveryDetails(error);
+        if (recovery && recoveryAttempt < 60) {
+          recoveryAttempt += 1;
+          dispatchIngress({
+            type: "connection.recovering",
+            message: recovery.message,
+            retryAfterMs: recovery.retryAfterMs,
+            attempt: recoveryAttempt,
+          });
+          await sleep(recovery.retryAfterMs);
+          continue;
+        }
+        if (!input.preserveCurrentOnFailure) {
+          dispatchIngress({
+            type: "command.failed",
+            message: describeCommandFailure(error, failureMessage),
+          });
+        }
+        throw error;
+      }
+    }
+  }
+
+  function normalizeSubmitResponseForCurrentState(
+    response: HostActionSubmitWireResponse,
+  ): NormalizedSubmitResponse {
+    const state = store.getState();
+    const context = getSessionContext(state.session);
+    return normalizeSubmitResponse(response, {
+      currentContext: context,
+      currentGameplay: getGameplayViewport(state.session),
+      userId: context?.userId ?? null,
+    });
+  }
+
+  function dispatchSubmitResponse(
+    event: NormalizedSubmitResponse,
+    clientActionId?: string | null,
+  ) {
+    if (!event) return;
+    if (clientActionId && event.type === "session.gameplayUpdated") {
+      recordMark(clientActionId, PERF_MARK_NAMES.T3B_RESPONSE_APPLIED, {
+        extra: { version: event.gameplay.version },
+      });
+    }
+    dispatchIngress({
+      type: "event.received",
+      source: "submit-response",
+      event,
+      clientActionId,
+    });
+  }
+
+  return {
+    loadSessionByShortCode: async (input) => {
+      await runSnapshotCommand(
+        {
+          target: { shortCode: input.shortCode },
+          sourceLabel: "short-code",
+          connectSource: input.source,
+          userId: input.userId,
+          load: () =>
+            transport.loadSessionByShortCode({
+              shortCode: input.shortCode,
+              requestedPlayerId: input.requestedPlayerId,
+            }),
+        },
+        "Failed to load session by short code.",
+      );
+    },
+    loadSessionSnapshot: async (input) => {
+      await runSnapshotCommand(
+        {
+          target: { sessionId: input.sessionId },
+          sourceLabel: input.source === "dev-new" ? "dev-new" : "snapshot",
+          connectSource: input.source,
+          userId: input.userId,
+          expectedPerspectivePlayerId: input.expectedPerspectivePlayerId,
+          preserveCurrentOnFailure: input.source === "player-switch",
+          load: () =>
+            transport.loadSessionSnapshot({
+              sessionId: input.sessionId,
+              requestedPlayerId: input.requestedPlayerId,
+            }),
+        },
+        "Failed to load session snapshot.",
+      );
+    },
+    startSession: async (input) => {
+      await runSnapshotCommand(
+        {
+          target: { sessionId: input.sessionId },
+          sourceLabel: "start",
+          connectSource: input.source,
+          userId: input.userId,
+          load: () => transport.startSession({ sessionId: input.sessionId }),
+        },
+        "Failed to start session.",
+      );
+    },
+    submitInteraction: async (input) => {
+      const gameplay = getGameplayViewport(store.getState().session);
+      if (!gameplay) {
+        throw new Error("No renderable gameplay snapshot is available.");
+      }
+      if (input.clientActionId) {
+        recordMark(input.clientActionId, PERF_MARK_NAMES.T2_HTTP_SENT, {
+          extra: {
+            playerId: input.playerId,
+            interactionId: input.interactionId,
+            expectedVersion: gameplay.version,
+          },
+        });
+      }
+      let response: HostActionSubmitWireResponse | null = null;
+      let recoveryAttempt = 0;
+      while (!response) {
+        try {
+          response = await transport.submitInteraction({
+            sessionId: input.sessionId,
+            playerId: input.playerId,
+            interactionId: input.interactionId,
+            expectedVersion: gameplay.version,
+            actionSetVersion: gameplay.actionSetVersion,
+            params: input.params,
+            clientActionId: input.clientActionId,
+          });
+        } catch (error) {
+          const recovery = getSessionRecoveryDetails(error);
+          if (recovery && recoveryAttempt < 60) {
+            recoveryAttempt += 1;
+            dispatchIngress({
+              type: "connection.recovering",
+              message: recovery.message,
+              retryAfterMs: recovery.retryAfterMs,
+              attempt: recoveryAttempt,
+            });
+            await sleep(recovery.retryAfterMs);
+            continue;
+          }
+          const message = describeCommandFailure(error, "Interaction rejected");
+          dispatchIngress({
+            type: "feedback.actionRejected",
+            reason: message,
+            targetPlayer: input.playerId,
+          });
+          throw createSubmissionError("api-error", message);
+        }
+      }
+      const normalizedResponse =
+        normalizeSubmitResponseForCurrentState(response);
+      if (input.clientActionId) {
+        recordMark(input.clientActionId, PERF_MARK_NAMES.T3_HTTP_RESPONSE, {
+          extra: {
+            accepted: response.accepted,
+            errorCode: response.errorCode,
+            version: response.version,
+            transport: "ok",
+          },
+        });
+        const acceptedGameplayVersion =
+          normalizedResponse?.type === "session.gameplayUpdated"
+            ? normalizedResponse.gameplay.version
+            : response.version;
+        if (
+          acceptedGameplayVersion !== undefined &&
+          response.accepted !== false
+        ) {
+          correlateVersion(input.clientActionId, acceptedGameplayVersion);
+        }
+      }
+      if (response.accepted !== false) {
+        dispatchSubmitResponse(normalizedResponse, input.clientActionId);
+        return;
+      }
+      dispatchIngress({
+        type: "feedback.actionRejected",
+        reason: response.message ?? "Interaction rejected",
+        targetPlayer: input.playerId,
+      });
+      throw createSubmissionError(
+        response.errorCode ?? undefined,
+        response.message ?? "Interaction rejected",
+      );
+    },
+    validateInteraction: async (input) => {
+      const gameplay = getGameplayViewport(store.getState().session);
+      if (!gameplay) {
+        return {
+          valid: false,
+          errorCode: "runtime-unavailable",
+          message: "No renderable gameplay snapshot is available.",
+        };
+      }
+      return transport.validateInteraction({
+        sessionId: input.sessionId,
+        playerId: input.playerId,
+        interactionId: input.interactionId,
+        expectedVersion: gameplay.version,
+        actionSetVersion: gameplay.actionSetVersion,
+        params: input.params,
+      });
+    },
+    restoreHistory: async (input) => {
+      const event = await transport.restoreHistory(input);
+      if (event) {
+        dispatchIngress({
+          type: "event.received",
+          source: "submit-response",
+          event: normalizeEvent(event, {
+            currentContext: getSessionContext(store.getState().session),
+            currentGameplay: getGameplayViewport(store.getState().session),
+            userId: getSessionContext(store.getState().session)?.userId ?? null,
+          }),
+          debugEvent: { eventType: event.type, data: event },
+        });
+      }
+    },
+    selectPlayer: (playerId) => {
+      const session = store.getState().session;
+      const currentPlayerId =
+        session.type === "gameplay"
+          ? session.perspective.playerId
+          : session.type === "gameplayLoading"
+            ? session.requestedPlayerId
+            : null;
+      if (playerId === currentPlayerId) {
+        return;
+      }
+      const context = getSessionContext(session);
+      if (!context) return;
+      dispatchIngress({
+        type: "local.playerSelected",
+        playerId,
+        sessionId:
+          runtime.getConnectedSessionId() ?? context.identity.sessionId,
+      });
+    },
+    clearConnectionError: () =>
+      dispatchIngress({ type: "connection.errorCleared" }),
+    enqueueActionRejected: (reason, targetPlayer) =>
+      dispatchIngress({
+        type: "feedback.actionRejected",
+        reason,
+        targetPlayer,
+      }),
+    closeStreams: () => {
+      runtime.closeStreams();
+      dispatchIngress({ type: "streams.closed" });
+    },
+    onStateAck: () => dispatchIngress({ type: "activity.stateAcked" }),
+    markNotificationRead: (id) =>
+      dispatchIngress({ type: "activity.notificationRead", id }),
+    clearNotifications: () =>
+      dispatchIngress({ type: "activity.notificationsCleared" }),
+    dismissHostFeedback: (id) =>
+      dispatchIngress({ type: "activity.hostFeedbackDismissed", id }),
+    clearHostFeedback: () =>
+      dispatchIngress({ type: "activity.hostFeedbackCleared" }),
+    clearSSEEvents: () => dispatchIngress({ type: "debug.sseEventsCleared" }),
+    reset: () => {
+      runtime.closeStreams();
+      store.setState(createInitialUnifiedSessionState() as Partial<TStore>);
+    },
+  };
+}