frontend/editor: catch async load errors, retry logic, and render error urging user to refresh the page -- #8623

Author: haraldschilly

src/.claude/settings.json

@@ -17,6 +17,7 @@
       "Bash(git checkout:*)",
       "Bash(git commit:*)",
       "Bash(git diff:*)",
+      "Bash(git log:*)",
       "Bash(git push:*)",
       "Bash(grep:*)",
       "Bash(ln:*)",

src/packages/frontend/editors/register-all.ts

@@ -34,6 +34,6 @@ import "@cocalc/frontend/codemirror/init";
 
 // CSS for the lightweight (< 1MB) nextjs friendly CodeEditor
 // component (in components/code-editor).
-// This is only for making this editro work in this frontend app.
+// This is only for making this editor work in this frontend app.
 // This dist.css is only 7K.
 import "@uiw/react-textarea-code-editor/dist.css";

src/packages/frontend/file-editors-error.tsx

@@ -0,0 +1,50 @@
+/*
+ *  This file is part of CoCalc: Copyright © 2020 Sagemath, Inc.
+ *  License: MS-RSL – see LICENSE.md for details
+ */
+
+import { Alert as AntdAlert, Button } from "antd";
+import { ReactElement } from "react";
+
+import { Icon, Paragraph } from "@cocalc/frontend/components";
+
+interface EditorLoadErrorComponentProps {
+  path: string;
+  error: Error;
+}
+
+/**
+ * Error component shown when editor fails to load.
+ * Displays error message with a button to refresh the page.
+ */
+export function EditorLoadErrorComponent(
+  props: EditorLoadErrorComponentProps,
+): ReactElement {
+  const { path, error } = props;
+
+  const handleRefresh = () => {
+    // Refresh the page while preserving the current URL
+    window.location.reload();
+  };
+
+  return (
+    <AntdAlert
+      type="error"
+      message="Editor Load Failed"
+      description={
+        <div style={{ marginTop: "12px" }}>
+          <Paragraph>File: {path}</Paragraph>
+          <Paragraph code>{String(error)}</Paragraph>
+          <Paragraph>
+            This usually happens due to temporary network issues.
+          </Paragraph>
+          <Button type="primary" size="large" onClick={handleRefresh}>
+            <Icon name="reload" /> Refresh Page
+          </Button>
+        </div>
+      }
+      showIcon
+      style={{ margin: "20px" }}
+    />
+  );
+}

src/packages/frontend/file-editors.ts

@@ -3,6 +3,8 @@
  *  License: MS-RSL – see LICENSE.md for details
  */
 
+import { delay } from "awaiting";
+
 import type { IconName } from "@cocalc/frontend/components/icon";
 
 import {
@@ -13,9 +15,10 @@ import {
   required,
 } from "@cocalc/util/misc";
 
-import { React } from "./app-framework";
+import { React } from "@cocalc/frontend/app-framework";
 
-import { delay } from "awaiting";
+import { alert_message } from "./alerts";
+import { EditorLoadErrorComponent } from "./file-editors-error";
 
 declare let DEBUG: boolean;
 
@@ -131,6 +134,20 @@ export function register_file_editor(opts: FileEditorInfo): void {
   }
 }
 
+/**
+ * Logs when a file extension falls back to the unknown editor.
+ * This helps with debugging why an editor failed to load.
+ */
+function logFallback(
+  ext: string | undefined,
+  path: string,
+  is_public: boolean,
+): void {
+  console.warn(
+    `Editor fallback triggered: No editor found for ext '${ext ?? "unknown"}' on path '${path}' (is_public: ${is_public}), using unknown editor catchall`,
+  );
+}
+
 // Get editor for given path and is_public state.
 
 function get_ed(
@@ -152,10 +169,12 @@ function get_ed(
     filename_extension(path).toLowerCase();
 
   // either use the one given by ext, or if there isn't one, use the '' fallback.
-  const spec =
-    file_editors[is_pub][ext] != null
-      ? file_editors[is_pub][ext]
-      : file_editors[is_pub][""];
+  let spec = file_editors[is_pub][ext];
+  if (spec == null) {
+    // Log when falling back to unknown editor
+    logFallback(ext, path, !!is_public);
+    spec = file_editors[is_pub][""];
+  }
   if (spec == null) {
     // This happens if the editors haven't been loaded yet.  A valid use
     // case is you open a project and session restore creates one *background*
@@ -183,7 +202,19 @@ export async function initializeAsync(
     return editor.init(path, redux, project_id, content);
   }
   if (editor.initAsync != null) {
-    return await editor.initAsync(path, redux, project_id, content);
+    try {
+      return await editor.initAsync(path, redux, project_id, content);
+    } catch (err) {
+      console.error(`Failed to initialize async editor for ${path}: ${err}`);
+      // Single point where all async editor load errors are reported to user
+      alert_message({
+        type: "error",
+        title: "Editor Load Failed",
+        message: `Failed to load editor for ${path}: ${err}. Please check your internet connection and refresh the page.`,
+        timeout: 10,
+      });
+      throw err;
+    }
   }
 }
 
@@ -223,7 +254,22 @@ export async function generateAsync(
   const { component, componentAsync } = e;
   if (component == null) {
     if (componentAsync != null) {
-      return await componentAsync();
+      try {
+        return await componentAsync();
+      } catch (err) {
+        const error = err as Error;
+        console.error(`Failed to load editor component for ${path}: ${error}`);
+        // Single point where all async editor load errors are reported to user
+        alert_message({
+          type: "error",
+          title: "Editor Load Failed",
+          message: `Failed to load editor for ${path}: ${error}. Please check your internet connection and refresh the page.`,
+          timeout: 10,
+        });
+        // Return error component with refresh button
+        return () =>
+          React.createElement(EditorLoadErrorComponent, { path, error });
+      }
     }
     return () =>
       React.createElement(

src/packages/frontend/frame-editors/code-editor/code-editor-manager.ts

@@ -25,19 +25,25 @@ export class CodeEditor {
   }
 
   async init(): Promise<void> {
-    const ext = filename_extension(this.path);
-    let editor = get_file_editor(ext, false);
-    if (editor == null) {
-      // fallback to text
-      editor = get_file_editor("txt", false);
-    }
-    let name: string;
-    if (editor.init != null) {
-      name = editor.init(this.path, redux, this.project_id);
-    } else {
-      name = await editor.initAsync(this.path, redux, this.project_id);
+    try {
+      const ext = filename_extension(this.path);
+      let editor = get_file_editor(ext, false);
+      if (editor == null) {
+        // fallback to text
+        editor = get_file_editor("txt", false);
+      }
+      let name: string;
+      if (editor.init != null) {
+        name = editor.init(this.path, redux, this.project_id);
+      } else {
+        name = await editor.initAsync(this.path, redux, this.project_id);
+      }
+      this.actions = redux.getActions(name) as unknown as Actions; // definitely right
+    } catch (err) {
+      console.error(`Failed to initialize editor for ${this.path}: ${err}`);
+      // Alert is shown at higher level in file-editors.ts
+      throw err;
     }
-    this.actions = redux.getActions(name) as unknown as Actions; // definitely right
   }
 
   close(): void {

src/packages/frontend/frame-editors/frame-tree/register.ts

@@ -85,6 +85,95 @@ if (DEBUG) {
   // (window as any).frame_editor_reference_count = reference_count;
 }
 
+/**
+ * Wraps an async data loader with timeout protection and retry logic.
+ *
+ * Strategy:
+ * - If 10 second timeout occurs → retry immediately
+ * - If asyncLoader() fails immediately due to network error → wait 5 seconds → retry
+ * - Maximum 3 attempts total
+ *
+ * This ensures that temporary network hiccups don't silently cause fallback to wrong editor.
+ * NOTE: The caller must wrap this with reuseInFlight to prevent duplicate simultaneous loads.
+ */
+function withTimeoutAndRetry<T>(
+  asyncLoaderFn: () => Promise<T>,
+  ext: string | string[],
+  timeoutMs: number = 10000,
+  maxRetries: number = 3,
+): () => Promise<T> {
+  const extStr = Array.isArray(ext) ? ext.join(",") : ext;
+
+  return async () => {
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        // Only log if retrying (attempt >= 2), not on first attempt
+        if (attempt >= 2) {
+          console.warn(
+            `frame-editor/register: loading ${extStr} (attempt ${attempt}/${maxRetries})`,
+          );
+        }
+
+        // TEST: Uncomment below to simulate network error for ipynb files
+        // if (extStr === "ipynb") {
+        //   throw new Error("Simulated network error for testing");
+        // }
+
+        const result = await Promise.race([
+          asyncLoaderFn(),
+          new Promise<T>((_, reject) =>
+            setTimeout(
+              () =>
+                reject(
+                  new Error(
+                    `Editor load timeout after ${timeoutMs}ms for ${extStr}. Check your internet connection.`,
+                  ),
+                ),
+              timeoutMs,
+            ),
+          ),
+        ]);
+
+        // Only log success if we retried, not on first attempt
+        if (attempt >= 2) {
+          console.warn(`frame-editor/register: loaded ${extStr} successfully`);
+        }
+        return result;
+      } catch (err) {
+        lastError = err as Error;
+        const errorMsg = lastError.message || String(lastError);
+
+        if (attempt < maxRetries) {
+          // Check if it's a timeout error or immediate network error
+          const isTimeout = errorMsg.includes("timeout");
+          const retryDelayMs = isTimeout ? 0 : 5000;
+          const retryDelayStr =
+            retryDelayMs === 0 ? "immediately" : "after 5 seconds";
+
+          console.warn(
+            `frame-editor/register: failed to load ${extStr} (attempt ${attempt}/${maxRetries}): ${errorMsg}. Retrying ${retryDelayStr}...`,
+          );
+
+          // Wait before retry (0ms for timeout, 5s for network errors)
+          if (retryDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+          }
+        } else {
+          // Final attempt failed
+          console.error(
+            `frame-editor/register: failed to load ${extStr} after ${maxRetries} attempts: ${errorMsg}`,
+          );
+        }
+      }
+    }
+
+    // All retries exhausted
+    throw lastError || new Error(`Failed to load editor for ${extStr}`);
+  };
+}
+
 function register(
   icon: IconName | undefined,
   ext: string | string[],
@@ -182,20 +271,42 @@ function register(
         "either asyncData must be given or components and Actions must be given (or both)",
       );
     }
+
     let async_data: any = undefined;
-    // so calls to componentAsync and initAsync don't happen at once!
-    const getAsyncData = reuseInFlight(asyncData);
+
+    // Wrap the entire withTimeoutAndRetry with reuseInFlight to ensure
+    // that if multiple callers request the editor simultaneously,
+    // only ONE attempt is made (with retry logic).
+    const getAsyncData = reuseInFlight(withTimeoutAndRetry(asyncData, ext));
 
     data.componentAsync = async () => {
       if (async_data == null) {
-        async_data = await getAsyncData();
+        try {
+          async_data = await getAsyncData();
+        } catch (err) {
+          console.error(
+            `Failed to load async editor component for ext '${
+              Array.isArray(ext) ? ext.join(",") : ext
+            }': ${err}`,
+          );
+          // Alert is shown at higher level in file-editors.ts
+          throw err;
+        }
       }
       return async_data.component;
     };
 
     data.initAsync = async (path: string, redux, project_id: string) => {
       if (async_data == null) {
-        async_data = await getAsyncData();
+        try {
+          async_data = await getAsyncData();
+        } catch (err) {
+          console.error(
+            `Failed to load async editor for path '${path}': ${err}`,
+          );
+          // Alert is shown at higher level in file-editors.ts
+          throw err;
+        }
       }
       return init(async_data.Actions)(path, redux, project_id);
     };