@raclettejs/core 0.1.34 → 0.1.36-canary.0

package/services/frontend/src/core/setup/socketClient.ts

@@ -3,59 +3,59 @@
  * Listens to the event bus and emits accordingly messages to the socket server.
  */
 import log from "@racletteCore/lib/logger"
+import { $store } from "@racletteCore"
 import { getUserToken } from "./sessionHandler"
 import configService from "@racletteCore/lib/configService"
-import { validate } from "uuid"
+import { extractSessionIdFromUrl } from "@racletteCore/lib/workSessionUrl"
+import { getActiveSocket, setActiveSocket } from "./socketRegistry"
+import type { Socket } from "socket.io-client"
 
-/**
- * Extract sessionId from URL if present
- * Supports racletteJS route format: /:workSession/id={uuid}
- */
-const extractSessionIdFromUrl = (): string | null => {
-  const path = window.location.pathname + (window.location.hash || "")
-  // Match /:workSession/id={uuid} pattern
-  const workSessionMatch = path.match(/\/:workSession\/id=([^/&#]+)/)
-
-  if (workSessionMatch && workSessionMatch[1]) {
-    const sessionId = workSessionMatch[1]
-    // Validate UUID format
-    if (validate(sessionId)) {
-      return sessionId
-    }
-  }
-
-  return null
-}
+let eventbusRegistered = false
 
-const registerSocketClient = ($socket, $eventbus) => {
-  $eventbus.on("socket/join/room", (roomId?: string) => {
-    const { requireAuthentication } = configService.getConfig()?.global ?? {
-      requireAuthentication: true,
-    }
+const registerSocketClient = ($socket: Socket, $eventbus) => {
+  setActiveSocket($socket)
 
-    let token: string | null = null
-    const sessionId = extractSessionIdFromUrl()
+  if (eventbusRegistered) {
+    return
+  }
+  eventbusRegistered = true
 
-    // Check if we're in a work session context (sessionId in URL indicates work session)
-    const isWorkSession = !!sessionId
+  $eventbus.on(
+    "socket/join/room",
+    (roomId?: string, options?: { bootstrap?: boolean }) => {
+      const { requireAuthentication } = configService.getConfig()?.global ?? {
+        requireAuthentication: true,
+      }
 
-    if (requireAuthentication) {
-      token = getUserToken()
+      const sessionId = extractSessionIdFromUrl()
+      const isWorkSession = !!sessionId
 
-      // For work sessions, we don't need a token - the sessionId is used for authentication
-      // The sessionId was already sent during socket handshake in the auth object
-      if (!token && !isWorkSession) {
+      if (requireAuthentication && !isWorkSession && !getUserToken()) {
         return log.socket("emitJoin", "no token and not a work session")
       }
-    }
 
-    log.socket("emitJoin", { roomId, token, sessionId, isWorkSession })
-    $socket.emit("join", { roomId, token })
-  })
+      // Light re-join: after a transport reconnect the project is still in store;
+      // skip full bootstrap and let the server use readMain (no roomId).
+      const projectId = $store.getState(["project", "_id"]) as string | null
+      const isLightRejoin =
+        options?.bootstrap === false ||
+        (!roomId && !!projectId && options?.bootstrap !== true)
+      const bootstrap =
+        options?.bootstrap ?? (isLightRejoin ? false : !roomId)
+
+      log.socket("emitJoin", {
+        roomId,
+        bootstrap,
+        isWorkSession,
+        lightRejoin: isLightRejoin,
+      })
+      getActiveSocket()?.emit("join", { roomId, bootstrap })
+    },
+  )
 
   $eventbus.on("socket/leave/room", (roomId) => {
     log.socket("emitLeave", { roomId })
-    $socket.emit("leave", roomId)
+    getActiveSocket()?.emit("leave", roomId)
   })
 }
 

package/services/frontend/src/core/setup/socketEvents.ts

@@ -1,91 +1,85 @@
-/**
- * listen to socket events received from the backend
- *
- * @param {object} $socket - a socketClient instance
- * @param {object} $store - a minirx-store instance, so we can dispatch actions
- * @param {object} $eventbus - instance of our custom eventbus
- */
 import type { Composition } from "@shared/types/core/Composition.types"
 import type { InteractionLink } from "@shared/types/core/InteractionLink.types"
 import log from "@racletteCore/lib/logger"
-import { setupSpace } from "@racletteCore/lib/projectDataHelper"
 import { handleServerItem } from "@racletteCore/lib/data/dataApi"
 import * as userNotifier from "@racletteCore/lib/userNotifier"
 import type { ProjectConfiguration } from "../store/types"
-import { validate } from "uuid"
+import type { Socket } from "socket.io-client"
+import { extractSessionIdFromUrl } from "@racletteCore/lib/workSessionUrl"
 import { setHttpToken, setWorkSessionId } from "@racletteCore/lib/httpClient"
+import { isActiveSocket, setActiveSocket } from "./socketRegistry"
+import { startProjectBootstrap } from "./socketBootstrap"
 
 /**
- * Extract sessionId from URL if present
- * Supports racletteJS route format: /:workSession/id={uuid}
+ * Listen to socket events received from the backend.
+ *
+ * @param $socket - socket.io client instance
+ * @param $store - mini-rx store (dispatch actions)
+ * @param $eventbus - global event bus
+ *
+ * Project bootstrap after joinConfirmation is handled in ./socketBootstrap.ts.
  */
-const extractSessionIdFromUrl = (): string | null => {
-  const path = window.location.pathname + (window.location.hash || "")
-  // Match /:workSession/id={uuid} pattern
-  const workSessionMatch = path.match(/\/:workSession\/id=([^/&#]+)/)
-
-  if (workSessionMatch && workSessionMatch[1]) {
-    const sessionId = workSessionMatch[1]
-    // Validate UUID format
-    if (validate(sessionId)) {
-      return sessionId
-    }
-  }
+const registerSocketEvents = ($socket: Socket, $store, $eventbus) => {
+  setActiveSocket($socket)
 
-  return null
-}
+  /** Ignore events from a replaced socket instance (see socketRegistry + main.ts teardown). */
+  const guardActive = (socket: Socket) => isActiveSocket(socket)
 
-const registerSocketEvents = ($socket, $store, $eventbus) => {
-  /**
-   * connect
-   * fired every time we have a new connection established
-   */
-  $socket.on("connect", (data) => {
+  // --- Connection lifecycle ---------------------------------------------------
+
+  /** Fired when a connection is established; triggers room join. */
+  $socket.on("connect", () => {
+    if (!guardActive($socket)) {
+      return
+    }
     log.socket("onConnect", "Socket connection established")
-    $store.dispatch({
-      type: "backend/socket/status",
-      payload: { status: 1 },
-    })
-    // @TODO if we re-connect after a drop out we need to subscribe to our project without
-    // completely setting up the project up, e.g. only re-join project room.
+    userNotifier.setServerConnected()
+    $eventbus.emit("socket/join/room")
   })
-  /**
-   * disconnect
-   */
-  $socket.on("disconnect", () => {
+
+  /** Enable offline mode here if project config disabled it. */
+  $socket.on("disconnect", (reason) => {
+    if (!guardActive($socket)) {
+      log.socket("onDisconnect", `ignored stale socket instance: ${reason}`)
+      return
+    }
     log.socket(
       "onDisconnect",
-      "Socket disconnected, Enable offline mode here if project conf disabled it",
+      `Socket disconnected (${reason}). Enable offline mode here if project conf disabled it`,
     )
     userNotifier.setServerDisconnected()
   })
+
   $socket.on("connect_error", (err) => {
+    if (!guardActive($socket)) {
+      return
+    }
     log.socket("onConnectError", err)
     userNotifier.setServerDisconnected()
   })
-  /**
-   * close
-   */
+
   $socket.on("close", () => {
+    if (!guardActive($socket)) {
+      return
+    }
     log.socket("onClose", "socket connection lost")
     userNotifier.setServerDisconnected()
   })
+
   /**
-   * reconnect
+   * Reconnect attempt in progress (status 2).
+   * connect handler will set online status and re-join the room.
    */
-  $socket.on("reconnect", () => {
-    console.error("not properly tested yet")
-    log.socket("onReconnect", "Socket reconnect")
-    $store.dispatch({
-      type: "backend/socket/status",
-      payload: { status: 2 },
-    })
+  $socket.on("reconnect", (attempt) => {
+    if (!guardActive($socket)) {
+      return
+    }
+    log.socket("onReconnect", `Socket reconnect (attempt ${attempt})`)
+    userNotifier.setServerConnecting()
   })
 
-  /**
-   * hello
-   * const data = { id: 'you'session'id' }
-   */
+  /** Server assigned this socket an id
+   * payload: { id: string } */
   $socket.on("socketEstablished", (data) => {
     log.socket("onSocketEstablished", data)
     $store.dispatch({
@@ -94,9 +88,8 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     })
   })
 
-  /**
-   * tagDeleted
-   */
+  // --- Entity sync (server → store / event bus) ------------------------------
+
   $socket.on("tagDeleted", (payload) => {
     const { appSessionId, body, type } = payload
 
@@ -112,9 +105,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
       body,
     })
   })
-  /**
-   * tagCreated
-   */
+
   $socket.on("tagCreated", (payload) => {
     const { appSessionId, body, type } = payload
 
@@ -130,9 +121,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
       body,
     })
   })
-  /**
-   * userCreated
-   */
+
   $socket.on("userCreated", (payload) => {
     const { appSessionId, body, type } = payload
 
@@ -143,9 +132,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     })
     $eventbus.emit("socket_createdUser", { offline: false, body })
   })
-  /**
-   * userDeleted
-   */
+
   $socket.on("userDeleted", (payload) => {
     const { appSessionId, body, type } = payload
     log.socket("onUserDeleted", {
@@ -155,9 +142,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     })
     $eventbus.emit("socket_deletedUser", { offline: false, body })
   })
-  /**
-   * projectUpdated
-   */
+
   $socket.on("projectUpdated", (payload) => {
     const { appSessionId, body, type } = payload
 
@@ -168,6 +153,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     })
     handleServerItem(payload, true, false)
   })
+
   $socket.on("projectConfigUpdated", (payload) => {
     const { appSessionId, body, type } = payload
 
@@ -180,9 +166,8 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
   })
 
   /**
-   * project/list
-   * Reports or updates the list of available projects
-   * This usually gets called after we requested a list of all projects which the user has access too
+   * Reports or updates the list of available projects.
+   * Usually sent after the client requested projects the user has access to.
    */
   $socket.on("getProjectList", (data) => {
     if (!data || data.length < 1) {
@@ -192,129 +177,141 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     $store.dispatch({ type: "projects/add", payload: data })
   })
 
+  // --- Room join / leave ------------------------------------------------------
+
+  $socket.on("joinFailed", (payload: { roomId?: string; code?: string; message?: string }) => {
+    if (!guardActive($socket)) {
+      return
+    }
+    log.socket("onJoinFailed", payload)
+    // Room-scoped failure: transport may still work. A snackbar alone is not enough —
+    // surfacing this as a hard error would blank the page while HTTP/socket stay up.
+    // TODO: targeted UX once space-switch / permission flows are defined.
+    if (!$socket.connected) {
+      userNotifier.setServerDisconnected()
+    }
+  })
+
   /**
-   * on joinConfirmation this means that we entered a new project with a new scope!
-   * For work sessions, the payload structure is different: { session, composition }
+   * Entered a project room (new scope). bootstrap=false is a light re-join after reconnect.
+   * Work sessions: no project in payload, but compositions/interactionLinks (+ optional token).
    */
   $socket.on(
     "joinConfirmation",
     (payload: {
+      roomId?: string
+      bootstrap?: boolean
       project?: { _id: string; account: string }
       projectConfig?: ProjectConfiguration
       compositions?: Composition[]
       interactionLinks?: InteractionLink[]
-      token?: string // Work session JWT token
+      token?: string // Work session JWT — replaces x-work-session-id header
     }) => {
-      const { project, projectConfig, compositions, interactionLinks, token } = payload
+      if (!guardActive($socket)) {
+        return
+      }
+
+      const {
+        project,
+        projectConfig,
+        compositions,
+        interactionLinks,
+        token,
+        bootstrap = true,
+      } = payload
 
-      // Check if this is a work session (no project but has compositions/interactionLinks)
       const isWorkSession = !project && compositions && compositions.length > 0
 
       if (isWorkSession) {
-        // Work session: use session ID as room identifier
         const sessionId = extractSessionIdFromUrl() || "work_session"
         const resolveId = "join_session_" + sessionId
 
         log.socket("onJoinConfirmation", "Work session join", payload)
 
-        // If token is provided, use it for authentication (replaces x-work-session-id header)
         if (token) {
           setHttpToken(token)
-          // Clear the x-work-session-id header since we're using token now
           setWorkSessionId(null)
-          log.socket("onJoinConfirmation", "Work session token set", { hasToken: !!token })
-        }
-
-        $eventbus.once("store_actionResolved_" + resolveId, async (action) => {
-          $store.dispatch({
-            type: "ui/update",
-            payload: { loading: true },
+          log.socket("onJoinConfirmation", "Work session token set", {
+            hasToken: !!token,
           })
+        }
 
-          // Use the same setupSpace function as logged-in users
-          // This ensures all normal processing happens (landing page detection, etc.)
-          await setupSpace(compositions || [], interactionLinks || [], projectConfig || {})
-
-          // Don't navigate - let the default composition loading logic handle it
-          // The URL stays as /:workSession/id={uuid} and the router will match
-          // the composition from the store based on the default logic
-
-          // Enable fullscreen mode (hide nav bars) for work sessions
-          $store.dispatch({
-            type: "ui/update",
-            payload: {
-              availableInterfaces: [], // Hide all UI interfaces for fullscreen
-              navigationOpen: false,
+        startProjectBootstrap(
+          { store: $store, eventbus: $eventbus },
+          resolveId,
+          {
+            compositions,
+            interactionLinks,
+            projectConfig,
+            roomId: sessionId,
+            afterSetup: async () => {
+              // Fullscreen work session — hide chrome; URL stays /:workSession/id={uuid}
+              // and the router resolves composition from store.
+              $store.dispatch({
+                type: "ui/update",
+                payload: {
+                  availableInterfaces: [],
+                  navigationOpen: false,
+                },
+              })
             },
-          })
+          },
+        )
 
-          $store.dispatch({
-            type: "ui/update",
-            payload: { loading: false },
-          })
+        return
+      }
 
-          $eventbus.emit("ui/setupProject", sessionId)
-        })
+      if (!project) {
+        log.socket("onJoinConfirmation", "no Room")
+        return
+      }
 
-        // Reset store states for work session
-        $store.dispatch({
-          type: "projectInit",
-          resolveId,
-        })
+      const roomId = payload.roomId ?? project._id
 
+      if (!roomId) {
+        log.socket("onJoinConfirmation", "no Room id")
         return
       }
 
-      // Regular project join confirmation (existing flow)
-      const roomId = project?._id
-
-      if (!project) {
-        log.socket("onJoinConfirmation", "no Room")
+      if (bootstrap === false) {
+        log.socket(
+          "onJoinConfirmation",
+          `Joined room without bootstrap: ${roomId}`,
+        )
+        userNotifier.setServerConnected()
         return
       }
 
       log.socket("onJoinConfirmation", payload)
 
-      const resolveId = "join_" + roomId
-
-      $eventbus.once("store_actionResolved_" + resolveId, async (action) => {
-        // start bootstraping of project
-        // this event will be fired once the projectInit is finished which gets triggered down there
-        $store.dispatch({
-          type: "project/set",
-          payload: project,
-        })
-        $store.dispatch({
-          type: "ui/update",
-          payload: { loading: true },
-        })
-        await setupSpace(compositions || [], interactionLinks || [], projectConfig || {})
-
-        $eventbus.emit("ui/setupProject", roomId)
-      })
-      // Reset all store states which are project dependent.
-      $store.dispatch({
-        type: "projectInit",
-        resolveId,
-      })
+      startProjectBootstrap(
+        { store: $store, eventbus: $eventbus },
+        "join_" + roomId,
+        {
+          project,
+          compositions,
+          interactionLinks,
+          projectConfig,
+          roomId,
+        },
+      )
     },
   )
 
-  /*
-   * leaveConfirm
-   * the backend reports when we leave a room, be it a resonse for our own
-   * request or forcefully.
+  /**
+   * Backend reports leaving a room — response to our request or forced by server.
    */
   $socket.on("leaveConfirmation", (data) => {
     log.socket("onLeaveConfirmation", data)
   })
 
-  /* login event
-   * the backend has approved our token
-   */
-  $socket.on("login", (data) =>
+  /** Backend has accepted our auth token on the socket. */
+  $socket.on("login", () =>
     log.socket("onLogin", "Socket connection successfully authenticated"),
   )
+
+  // --- Generic data sync ------------------------------------------------------
+
   $socket.on("dataCreated", (payload) => {
     const { body, appSessionId } = payload
 
@@ -325,6 +322,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     handleServerItem(payload, true, false)
     $eventbus.emit("socket_dataCreated", body)
   })
+
   $socket.on("dataDeleted", (payload) => {
     const { body, appSessionId } = payload
 
@@ -335,10 +333,8 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     handleServerItem(payload, true, false)
     $eventbus.emit("socket_dataDeleted", body)
   })
-  /**
-   * data
-   * We received a data object from the backend
-   */
+
+  /** Incremental data update from the backend. */
   $socket.on("data", (payload) => {
     const { body, appSessionId } = payload
 
@@ -350,9 +346,7 @@ const registerSocketEvents = ($socket, $store, $eventbus) => {
     $eventbus.emit("socket/data/update", { offline: false, body })
   })
 
-  /**
-   * New deployed frontend version available
-   */
+  /** New deployed frontend version available. */
   $socket.on("newVersionAvailable", () => {
     log.socket("onNewVersionAvailable", {})
     userNotifier.newVersionAvailable()

package/services/frontend/src/core/setup/socketRegistry.ts

@@ -0,0 +1,19 @@
+import type { Socket } from "socket.io-client"
+
+let activeSocket: Socket | null = null
+
+export const setActiveSocket = (socket: Socket) => {
+  activeSocket = socket
+}
+
+export const getActiveSocket = (): Socket | null => activeSocket
+
+export const isActiveSocket = (socket: Socket): boolean =>
+  socket === activeSocket
+
+export const teardownSocket = (socket: Socket) => {
+  socket.removeAllListeners()
+  if (socket.connected) {
+    socket.disconnect()
+  }
+}

package/services/frontend/src/core/store/index.ts

@@ -18,7 +18,7 @@ import {
   getValueFromLookup,
   deepFreeze,
 } from "../lib/dataHelper"
-import getEnvVariable from "../lib/getEnvVariable"
+import { isDevelopmentMode } from "@racletteCore/helpers/devMode"
 import { applicationState } from "./state"
 /* import feature reducers */
 import metaReducers from "./reducers/metaReducer"
@@ -46,9 +46,7 @@ import log from "@racletteCore/lib/logger"
 import type { RacletteStore, StoreHelperGetState } from "@racletteCore"
 
 /* Apply different extensions depending on the environment */
-const extensions =
-  getEnvVariable("RACLETTE_DEBUG_MODE") === "true" ||
-  !getEnvVariable("RACLETTE_DEBUG_MODE")
+const extensions = isDevelopmentMode()
     ? [
         new LoggerExtension(),
         new ReduxDevtoolsExtension({

package/services/frontend/src/core/types/DataApi.ts

@@ -1,5 +1,12 @@
 import type { QueryState } from "./Store"
-export type CustomStoreActionParams = Record<string, any>
+
+export type CustomStoreActionParams = Record<string, unknown>
+
+/** Callable params source — invoked on each query/write `execute()`. */
+export type QueryParamsSubscriber = () => CustomStoreActionParams
+
+/** Core query params: plain snapshot or subscriber (framework-agnostic). */
+export type QueryParamsInput = CustomStoreActionParams | QueryParamsSubscriber
 export type CustomStoreActionOptions = {
   immediate?: boolean
   cb?: Function // function to call when call finised -> execute für getAll
@@ -12,7 +19,8 @@ export type CustomStoreActionOptions = {
 
 export type CustomStoreActionsPayload = {
   id?: String // if set this will used as the final namespace giver for the actionId, if not it will be a nanoId
-  params?: CustomStoreActionParams
+  /** Plain object or subscriber function — resolved on each `execute()`. */
+  params?: QueryParamsInput
   options?: CustomStoreActionOptions
   config?: any
 }

package/services/frontend/src/core/types/PluginRegistrar.ts

@@ -12,7 +12,7 @@ import type {
   PluginApi,
 } from "@racletteOrchestrator"
 import type { DefineComponent } from "vue"
-import type { UIState, RouteState, WidgetBase } from "@racletteCore/store/types"
+import type { UIState, WidgetBase } from "@racletteCore/store/types"
 import type { Query } from "@racletteCore/store/reducers/queries/reducers"
 export type BroadcastChannelDefinition = {
   channel: string