dreamboard 0.1.21 → 0.1.23

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

@@ -0,0 +1,477 @@
+import type { StoreApi } from "zustand/vanilla";
+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 {
+  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>;
+  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;
+}
+
+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),
+      });
+    },
+    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 },
+      });
+    },
+  });
+
+  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 });
+    }
+    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,
+        },
+      );
+    } catch (error) {
+      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,
+          },
+        });
+      }
+      const 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,
+      });
+      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",
+      );
+    },
+    restoreHistory: async (input) => {
+      await transport.restoreHistory(input);
+    },
+    selectPlayer: (playerId) => {
+      const context = getSessionContext(store.getState().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>);
+    },
+  };
+}

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

@@ -0,0 +1,209 @@
+import type {
+  HostActionSubmitResponse,
+  HostSessionEvent,
+  HostSessionSnapshot,
+} from "@dreamboard/api-client";
+import type {
+  GameplayPerspective,
+  GameplayViewport,
+  SessionContext,
+} from "./session-model.js";
+import {
+  contextFromHostEventContext,
+  contextFromHostSnapshot,
+  gameplayViewportFromSnapshot,
+} from "./session-model.js";
+
+type WireSessionIngressSnapshot = HostSessionSnapshot;
+type WireSessionIngressEvent = HostSessionEvent;
+type WireSessionIngressActionSubmitResponse = HostActionSubmitResponse;
+
+export type HostSessionWireSnapshot = WireSessionIngressSnapshot;
+export type HostSessionWireEvent = WireSessionIngressEvent;
+export type HostActionSubmitWireResponse =
+  WireSessionIngressActionSubmitResponse;
+
+export type NormalizedSessionSnapshot =
+  | {
+      type: "lobby";
+      context: SessionContext;
+      gameplay: null;
+      preferredPlayerId: string | null;
+    }
+  | {
+      type: "gameplay";
+      context: SessionContext;
+      perspective: GameplayPerspective;
+      gameplay: GameplayViewport;
+    }
+  | {
+      type: "ended";
+      context: SessionContext;
+      gameplay: null;
+      preferredPlayerId: string | null;
+    };
+
+export type NormalizedSessionEvent =
+  | {
+      type: "session.snapshot";
+      snapshot: NormalizedSessionSnapshot;
+      context: SessionContext;
+      gameplay: GameplayViewport | null;
+    }
+  | {
+      type: "session.lobbyUpdated";
+      context: SessionContext | null;
+      gameplay: GameplayViewport | null;
+    }
+  | {
+      type: "session.gameplayUpdated";
+      context: SessionContext | null;
+      gameplay: GameplayViewport;
+      perspective: GameplayPerspective;
+    }
+  | {
+      type: "session.historyUpdated";
+      context: SessionContext | null;
+      gameplay: GameplayViewport | null;
+    }
+  | {
+      type: "session.ended";
+      context: SessionContext | null;
+      gameplay: GameplayViewport | null;
+    }
+  | {
+      type: "session.error";
+      message: string;
+      code?: string;
+      context: SessionContext | null;
+      gameplay: GameplayViewport | null;
+    };
+
+export type NormalizedSubmitResponse = NormalizedSessionEvent | null;
+
+export function normalizeSnapshot(
+  snapshot: HostSessionWireSnapshot,
+  options: {
+    userId: string | null;
+    previousGameplay?: GameplayViewport | null;
+  },
+): NormalizedSessionSnapshot {
+  const context = contextFromHostSnapshot(snapshot, options.userId);
+  if (snapshot.type !== "gameplay") {
+    return {
+      type: snapshot.type,
+      context,
+      gameplay: null,
+      preferredPlayerId: null,
+    };
+  }
+  return {
+    type: "gameplay",
+    context,
+    perspective: { playerId: snapshot.gameplay.playerId },
+    gameplay: gameplayViewportFromSnapshot(
+      snapshot.gameplay,
+      options.previousGameplay,
+    ),
+  };
+}
+
+export function normalizeEvent(
+  event: HostSessionWireEvent,
+  options: {
+    currentContext: SessionContext | null;
+    currentGameplay: GameplayViewport | null;
+    userId: string | null;
+  },
+): NormalizedSessionEvent {
+  const context = options.currentContext;
+  switch (event.type) {
+    case "session.snapshot": {
+      const normalized = normalizeSnapshot(event.snapshot, {
+        userId: options.userId,
+        previousGameplay: options.currentGameplay,
+      });
+      return {
+        type: "session.snapshot",
+        snapshot: normalized,
+        context: normalized.context,
+        gameplay: normalized.gameplay,
+      };
+    }
+    case "session.lobbyUpdated":
+      return {
+        type: "session.lobbyUpdated",
+        context: context
+          ? contextFromHostEventContext(
+              { ...context, userId: options.userId },
+              event.context,
+              event.lobby,
+            )
+          : null,
+        gameplay: options.currentGameplay,
+      };
+    case "session.gameplayUpdated":
+      return {
+        type: "session.gameplayUpdated",
+        context: context
+          ? contextFromHostEventContext(
+              { ...context, userId: options.userId },
+              event.context,
+            )
+          : null,
+        gameplay: gameplayViewportFromSnapshot(
+          event.gameplay,
+          options.currentGameplay,
+        ),
+        perspective: { playerId: event.gameplay.playerId },
+      };
+    case "session.historyUpdated":
+      return {
+        type: "session.historyUpdated",
+        context: context
+          ? contextFromHostEventContext(
+              { ...context, userId: options.userId },
+              event.context,
+            )
+          : null,
+        gameplay: options.currentGameplay,
+      };
+    case "session.ended":
+      return {
+        type: "session.ended",
+        context: context
+          ? contextFromHostEventContext(
+              { ...context, userId: options.userId },
+              event.context,
+              event.lobby,
+            )
+          : null,
+        gameplay: options.currentGameplay,
+      };
+    case "session.error":
+      return {
+        type: "session.error",
+        message: event.message,
+        code: event.code,
+        context,
+        gameplay: options.currentGameplay,
+      };
+  }
+}
+
+export function normalizeSubmitResponse(
+  response: HostActionSubmitWireResponse,
+  options: {
+    currentContext: SessionContext | null;
+    currentGameplay: GameplayViewport | null;
+    userId: string | null;
+  },
+): NormalizedSubmitResponse {
+  return response.event
+    ? normalizeEvent(response.event, {
+        currentContext: options.currentContext,
+        currentGameplay: options.currentGameplay,
+        userId: options.userId,
+      })
+    : null;
+}