feat(FR-1568): migrate app launcher notifications from Lit to React (#4617)

Resolves #TBD ([FR-1568](https://lablup.atlassian.net/browse/FR-1568))

## 📋 Overview

Migration of the app launcher notification system from Lit-based (`lablup-notification`) to React-based notification system in Backend.AI.

## 🔄 App Launch & Notification Flow

### 1. **App Launch Request Initiation** (React → Lit)

**`AppLauncherModal.tsx` (lines 108-133)**
- Create notification in React component with session info and app name
- Call Lit component's `_runApp` with unified notification key

### 2. **App Launch Process** (Lit Component)

**`backend-ai-app-launcher.ts`** updates notification at each stage during app launch:

#### Phase 1: Initial Setup (lines 1251-1255)
- Start backgroundTask at 10%
- Status: `pending`

#### Phase 2: Proxy Configuration
- **V1 Proxy** (lines 715-720): Progress at 20%
- **V2 Proxy** (lines 773-780): Error handling with `status: 'failed'`

#### Phase 3: Socket Queue Addition (lines 902-909)
- Progress at 50%
- Adding kernel to socket queue

#### Phase 4: App Launch Completion (lines 1375-1387)
- Progress at 100%
- Status: `succeeded`
- Update notification after showing TCP app dialogs (SSH, VNC, etc.)

#### Phase 5: Final Cleanup (lines 1447-1451)
- Final notification display in finally block

### 3. **Error Handling**

Notification alerts users on errors:
- Proxy setup failure (lines 697-702, 727-734)
- Session creation failure (lines 821-826)
- Service port unavailable (lines 835-841)
- Connection failure (lines 916-930)

## 🎯 Key Changes

1. **Unified Notification Key**:
   - Shared key (`session-app-${sessionUuid}`) between React and Lit components for state synchronization

2. **Progress Tracking**:
   - Visual progress via `backgroundTask` property (0% → 10% → 20% → 50% → 100%)
   - Status transitions: `pending` → `succeeded` or `failed`

3. **Error Handling**:
   - Updates to `status: 'failed'` on failure at any stage
   - User-friendly error messages

## 📝 Review Points

- Notification state synchronization between React and Lit components
- Prevention of duplicate notifications using shared notification key
- Real-time progress updates for improved UX
- Clear feedback on error occurrences

## ✅ Testing

- [x] App launch notifications appear correctly
- [x] Progress indicators update during app launch
- [x] Error states display appropriate messages
- [x] No duplicate notifications with same key
- [x] Backward compatibility maintained

[FR-1568]: https://lablup.atlassian.net/browse/FR-1568?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: ironAiken2

react/src/components/BAIComputeSessionNodeNotificationItem.tsx

@@ -32,7 +32,7 @@ interface BAINodeNotificationItemProps {
 const BAIComputeSessionNodeNotificationItem: React.FC<
   BAINodeNotificationItemProps
 > = ({ sessionFrgmt, showDate, notification, primaryAppOption }) => {
-  const { destroyNotification } = useSetBAINotification();
+  const { closeNotification } = useSetBAINotification();
   const { t } = useTranslation();
   const navigate = useNavigate();
   const node = useFragment(
@@ -70,7 +70,7 @@ const BAIComputeSessionNodeNotificationItem: React.FC<
   useUpdateEffect(() => {
     if (node?.status === 'TERMINATED' || node?.status === 'CANCELLED') {
       setTimeout(() => {
-        destroyNotification(notification.key);
+        closeNotification(notification.key);
       }, 3000);
     }
   }, [node?.status]);
@@ -90,7 +90,7 @@ const BAIComputeSessionNodeNotificationItem: React.FC<
                 navigate(
                   `/session${node.row_id ? `?${new URLSearchParams({ sessionDetail: node.row_id }).toString()}` : ''}`,
                 );
-                destroyNotification(notification.key);
+                closeNotification(notification.key);
               }}
             >
               {node.name}

react/src/components/BAINotificationButton.tsx

@@ -16,19 +16,34 @@ import useKeyboardShortcut from 'src/hooks/useKeyboardShortcut';
 export const isOpenDrawerState = atom(false);
 
 const BAINotificationButton: React.FC<ButtonProps> = ({ ...props }) => {
-  const [notifications, { upsertNotification }] = useBAINotificationState();
+  const [notifications, { upsertNotification, clearNotification }] =
+    useBAINotificationState();
   useBAINotificationEffect();
 
   const [isOpenDrawer, setIsOpenDrawer] = useAtom(isOpenDrawerState);
   useEffect(() => {
-    const handler = (e: any) => {
+    const addNotificationHandler = (e: any) => {
       upsertNotification(e.detail);
     };
-    document.addEventListener('add-bai-notification', handler);
+    const clearNotificationHandler = (e: any) => {
+      clearNotification(e.detail.key);
+    };
+    document.addEventListener('add-bai-notification', addNotificationHandler);
+    document.addEventListener(
+      'clear-bai-notification',
+      clearNotificationHandler,
+    );
     return () => {
-      document.removeEventListener('add-bai-notification', handler);
+      document.removeEventListener(
+        'add-bai-notification',
+        addNotificationHandler,
+      );
+      document.removeEventListener(
+        'clear-bai-notification',
+        clearNotificationHandler,
+      );
     };
-  }, [upsertNotification]);
+  }, [upsertNotification, clearNotification]);
 
   useKeyboardShortcut(
     (event) => {

react/src/components/ComputeSessionNodeItems/AppLauncherModal.tsx

@@ -18,11 +18,20 @@ import {
   Row,
   Typography,
 } from 'antd';
-import { BAIFlex, BAIModal, BAISelect, BAIText } from 'backend.ai-ui';
+import {
+  BAIButton,
+  BAIFlex,
+  BAILink,
+  BAIModal,
+  BAISelect,
+  BAIText,
+} from 'backend.ai-ui';
 import _ from 'lodash';
 import { useRef, useState } from 'react';
 import { Trans, useTranslation } from 'react-i18next';
 import { graphql, useFragment } from 'react-relay';
+import { useNavigate } from 'react-router-dom';
+import { useSetBAINotification } from 'src/hooks/useBAINotification';
 
 interface AppLauncherModalProps extends ModalProps {
   onRequestClose: () => void;
@@ -43,6 +52,9 @@ const AppLauncherModal: React.FC<AppLauncherModalProps> = ({
   const [forceUseV2Proxy, setForceUseV2Proxy] = useState<boolean>(false);
   const [useSubDomain, setUseSubDomain] = useState<boolean>(false);
 
+  const { upsertNotification } = useSetBAINotification();
+  const navigate = useNavigate();
+
   const session = useFragment(
     graphql`
       fragment AppLauncherModalFragment on ComputeSessionNode {
@@ -92,9 +104,38 @@ const AppLauncherModal: React.FC<AppLauncherModalProps> = ({
       }
     });
 
+    // set notification for lit-element component
+    upsertNotification({
+      key: `session-app-${session?.row_id}`,
+      message: (
+        <span>
+          {t('general.Session')}:&nbsp;
+          <BAILink
+            style={{
+              fontWeight: 'normal',
+            }}
+            onClick={() => {
+              const newSearchParams = new URLSearchParams(location.search);
+              newSearchParams.set('sessionDetail', session?.row_id || '');
+              navigate({
+                pathname: `/session`,
+                search: newSearchParams.toString(),
+              });
+            }}
+          >
+            {session?.name}
+          </BAILink>
+        </span>
+      ),
+      description: t('session.appLauncher.LaunchingApp', {
+        appName: app?.title || '',
+      }),
+    });
+
     const appController = {
       'app-name': app?.name ?? '',
       'session-uuid': session?.row_id ?? '',
+      'session-name': session?.name ?? '',
       'url-postfix': app?.redirect ?? '',
     };
 
@@ -121,10 +162,7 @@ const AppLauncherModal: React.FC<AppLauncherModalProps> = ({
       return;
     }
     // @ts-ignore
-    globalThis.appLauncher._runApp(appController).then(() => {});
-    setOpenToPublic(false);
-    setTryPreferredPort(false);
-    onRequestClose();
+    await globalThis.appLauncher._runApp(appController).then(() => {});
   };
 
   return (
@@ -172,7 +210,7 @@ const AppLauncherModal: React.FC<AppLauncherModalProps> = ({
                         gap={'xs'}
                         style={{ height: '100%' }}
                       >
-                        <Button
+                        <BAIButton
                           icon={
                             <Image
                               src={app?.src}
@@ -181,8 +219,12 @@ const AppLauncherModal: React.FC<AppLauncherModalProps> = ({
                               style={{ height: 36, width: 36 }}
                             />
                           }
-                          onClick={() => {
-                            handleAppLaunch(app);
+                          action={async () => {
+                            await handleAppLaunch(app).then(() => {
+                              setOpenToPublic(false);
+                              setTryPreferredPort(false);
+                              onRequestClose();
+                            });
                           }}
                           style={{ height: 72, width: 72 }}
                         />

react/src/components/FileUploadManager.tsx

@@ -73,7 +73,7 @@ const FileUploadManager: React.FC = () => {
   const { t } = useTranslation();
   const { token } = theme.useToken();
   const baiClient = useSuspendedBackendaiClient();
-  const { upsertNotification, destroyNotification } = useSetBAINotification();
+  const { upsertNotification, closeNotification } = useSetBAINotification();
   const { generateFolderPath } = useFolderExplorerOpener();
   const [uploadRequests, setUploadRequests] = useAtom(uploadRequestAtom);
   const [uploadStatus, setUploadStatus] = useAtom(uploadStatusAtom);
@@ -176,7 +176,7 @@ const FileUploadManager: React.FC = () => {
                 }}
                 to={generateFolderPath(vFolderId)}
                 onClick={() => {
-                  destroyNotification('upload:' + vFolderId);
+                  closeNotification('upload:' + vFolderId);
                 }}
               >{`${vFolderName}`}</BAILink>
             </span>
@@ -306,7 +306,7 @@ const FileUploadManager: React.FC = () => {
                 }}
                 to={generateFolderPath(vFolderId)}
                 onClick={() => {
-                  destroyNotification('upload:' + vFolderId);
+                  closeNotification('upload:' + vFolderId);
                 }}
               >{`${status?.vFolderName}`}</BAILink>
             </span>

react/src/hooks/useBAINotification.tsx

@@ -7,7 +7,7 @@ import { createStyles } from 'antd-style';
 import { ArgsProps } from 'antd/lib/notification';
 import { atom, useAtomValue, useSetAtom } from 'jotai';
 import _ from 'lodash';
-import { Key, ReactNode, useCallback, useEffect, useRef } from 'react';
+import React, { Key, ReactNode, useCallback, useEffect, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 import { To, createPath } from 'react-router-dom';
 import { BAINodeNotificationItemFragment$key } from 'src/__generated__/BAINodeNotificationItemFragment.graphql';
@@ -289,23 +289,42 @@ export const useSetBAINotification = () => {
   const webuiNavigate = useWebUINavigate();
   const { styles } = useStyle();
 
-  const destroyAllNotifications = useCallback(() => {
+  const closeAllNotifications = useCallback(() => {
     _activeNotificationKeys.splice(0, _activeNotificationKeys.length);
     app.notification.destroy();
   }, [app.notification]);
 
+  /**
+   * Function to permanently clear all notifications.
+   */
   const clearAllNotifications = useCallback(() => {
     setNotifications([]);
-    destroyAllNotifications();
-  }, [setNotifications, destroyAllNotifications]);
+    closeAllNotifications();
+  }, [setNotifications, closeAllNotifications]);
 
-  const destroyNotification = useCallback(
+  /**
+   * Function to hide specific notification. It remains in the drawer.
+   */
+  const closeNotification = useCallback(
     (key: React.Key) => {
       app.notification.destroy(key);
     },
     [app.notification],
   );
 
+  /**
+   * Function to remove specific notification from the list and hide it.
+   */
+  const clearNotification = useCallback(
+    (key: React.Key) => {
+      setNotifications((prev) => {
+        return prev.filter((n) => n.key !== key);
+      });
+      closeNotification(key);
+    },
+    [setNotifications, closeNotification],
+  );
+
   /**
    * Function to upsert a notification.
    * @param params - The parameters for the notification.
@@ -398,7 +417,7 @@ export const useSetBAINotification = () => {
                   if (newNotification.to) {
                     webuiNavigate(newNotification.to);
                   }
-                  destroyNotification(newNotification.key);
+                  closeNotification(newNotification.key);
                 }}
               />
             ),
@@ -412,6 +431,12 @@ export const useSetBAINotification = () => {
               });
               if (idx >= 0) {
                 setNotifications((prevList) => {
+                  // check the notification is removed by clearNotification function. If so, do nothing.
+                  const exists = prevList.some(
+                    (n) => n.key === newNotification.key,
+                  );
+                  if (!exists) return prevList;
+
                   const newList = [...prevList];
                   newList[idx] = {
                     ...newList[idx],
@@ -423,7 +448,7 @@ export const useSetBAINotification = () => {
             },
           });
         } else if (newNotification.open === false && newNotification.key) {
-          destroyNotification(newNotification.key);
+          closeNotification(newNotification.key);
         }
         currentKey = newNotification.key;
         return nextNotifications;
@@ -435,7 +460,7 @@ export const useSetBAINotification = () => {
     [
       app.notification,
       setNotifications,
-      destroyNotification,
+      closeNotification,
       desktopNotification,
     ],
   );
@@ -467,9 +492,10 @@ export const useSetBAINotification = () => {
 
   return {
     upsertNotification,
+    clearNotification,
     clearAllNotifications,
-    destroyNotification,
-    destroyAllNotifications,
+    closeNotification,
+    closeAllNotifications,
   };
 };
 

react/src/hooks/useBackendAIAppLauncher.tsx

@@ -1,13 +1,22 @@
+import { useSetBAINotification } from './useBAINotification';
+import { BAILink } from 'backend.ai-ui';
+import { useTranslation } from 'react-i18next';
 import { graphql, useFragment } from 'react-relay';
+import { useNavigate } from 'react-router-dom';
 import { useBackendAIAppLauncherFragment$key } from 'src/__generated__/useBackendAIAppLauncherFragment.graphql';
 
 export const useBackendAIAppLauncher = (
   sessionFrgmt?: useBackendAIAppLauncherFragment$key | null,
 ) => {
+  const { t } = useTranslation();
+  const { upsertNotification } = useSetBAINotification();
+  const navigate = useNavigate();
+
   // TODO: migrate backend-ai-app-launcher features to this hook using fragment data.
   const session = useFragment(
     graphql`
       fragment useBackendAIAppLauncherFragment on ComputeSessionNode {
+        name
         row_id @required(action: NONE)
         vfolder_mounts
       }
@@ -17,7 +26,35 @@ export const useBackendAIAppLauncher = (
 
   // @ts-ignore
   return {
+    // TODO: AppLauncherModal should modify the hook to use, as it is currently separated,
+    // to re-declare the notification for use by the backend-ai-app-launcher.
     runTerminal: () => {
+      upsertNotification({
+        key: `session-app-${session?.row_id}`,
+        message: (
+          <span>
+            {t('general.Session')}:&nbsp;
+            <BAILink
+              style={{
+                fontWeight: 'normal',
+              }}
+              onClick={() => {
+                const newSearchParams = new URLSearchParams(location.search);
+                newSearchParams.set('sessionDetail', session?.row_id || '');
+                navigate({
+                  pathname: `/session`,
+                  search: newSearchParams.toString(),
+                });
+              }}
+            >
+              {session?.name}
+            </BAILink>
+          </span>
+        ),
+        description: t('session.appLauncher.LaunchingApp', {
+          appName: 'Console',
+        }),
+      });
       // @ts-ignore
       globalThis.appLauncher.runTerminal(session.row_id);
     },

resources/i18n/de.json

@@ -1423,6 +1423,7 @@
       "ConfirmAndRun": "Ich habe nachgesehen und ich fange an",
       "ConnectUrlIsNotValid": "Die Verbindungs-URL ist ungültig.",
       "DownloadSSHKey": "SSH-Schlüssel herunterladen",
+      "LaunchingApp": "Die App {{appName}} wird gestartet.",
       "NoExistingConnectionExample": "Keine Verbindung Zu kopierendes Beispiel.",
       "OpenVSCodeRemote": "Lokalen Visual Studio Code öffnen",
       "Prepared": "Bereit",

resources/i18n/el.json

@@ -1422,6 +1422,7 @@
       "ConfirmAndRun": "Έλεγξα και θα ξεκινήσω",
       "ConnectUrlIsNotValid": "Η διεύθυνση URL σύνδεσης δεν είναι έγκυρη.",
       "DownloadSSHKey": "Λήψη κλειδιού SSH",
+      "LaunchingApp": "Η εφαρμογή {{appName}} εκκινείται.",
       "NoExistingConnectionExample": "Δεν υπάρχει σύνδεση Παράδειγμα προς αντιγραφή.",
       "OpenVSCodeRemote": "Ανοίξτε τον τοπικό κώδικα του Visual Studio",
       "Prepared": "Ετοιμος",

resources/i18n/en.json

@@ -1431,6 +1431,7 @@
       "ConfirmAndRun": "I checked and I'll start",
       "ConnectUrlIsNotValid": "Connect URL is not valid.",
       "DownloadSSHKey": "Download SSH Key",
+      "LaunchingApp": "Starting {{appName}} app.",
       "NoExistingConnectionExample": "No Connection Example to be copied.",
       "OpenVSCodeRemote": "Open local Visual Studio Code",
       "Prepared": "Prepared",