Fix white screen on node connection failure with retry and error UI

When all RPC nodes are unreachable, the launcher previously showed a
permanent white screen with no feedback. This adds retry logic with
exponential backoff, a 5s per-node timeout, and a ConnectionErrorView
with a Retry button so users can recover without restarting.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ipdae

__tests__/node-retry.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+/**
+ * initializeNodeWithRetry 로직을 테스트하기 위해
+ * Electron 의존성 없이 동일한 로직을 재현합니다.
+ */
+
+type InitFn = () => Promise<string>;
+
+async function initializeNodeWithRetry(
+  initFn: InitFn,
+  maxRetries: number = 2,
+  baseDelayMs: number = 1000,
+): Promise<string> {
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await initFn();
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error(String(e));
+      if (attempt < maxRetries) {
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError!;
+}
+
+describe("initializeNodeWithRetry", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("첫 시도 성공 시 재시도 없이 반환", async () => {
+    const initFn = vi.fn().mockResolvedValue("node-1");
+
+    const promise = initializeNodeWithRetry(initFn);
+    const result = await promise;
+
+    expect(result).toBe("node-1");
+    expect(initFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("2번째 시도에서 성공", async () => {
+    const initFn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("fail"))
+      .mockResolvedValueOnce("node-2");
+
+    const promise = initializeNodeWithRetry(initFn);
+
+    // 첫 번째 실패 후 1초 대기
+    await vi.advanceTimersByTimeAsync(1000);
+
+    const result = await promise;
+    expect(result).toBe("node-2");
+    expect(initFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("3번째 시도에서 성공", async () => {
+    const initFn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("fail-1"))
+      .mockRejectedValueOnce(new Error("fail-2"))
+      .mockResolvedValueOnce("node-3");
+
+    const promise = initializeNodeWithRetry(initFn);
+
+    // 1초 (1st backoff) + 2초 (2nd backoff)
+    await vi.advanceTimersByTimeAsync(1000);
+    await vi.advanceTimersByTimeAsync(2000);
+
+    const result = await promise;
+    expect(result).toBe("node-3");
+    expect(initFn).toHaveBeenCalledTimes(3);
+  });
+
+  it("모든 시도 실패 시 마지막 에러를 throw", async () => {
+    const initFn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("fail-1"))
+      .mockRejectedValueOnce(new Error("fail-2"))
+      .mockRejectedValueOnce(new Error("fail-3"));
+
+    const promise = initializeNodeWithRetry(initFn);
+    // catch를 미리 걸어서 unhandled rejection 방지
+    const caught = promise.catch((e) => e);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await vi.advanceTimersByTimeAsync(2000);
+
+    const error = await caught;
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toBe("fail-3");
+    expect(initFn).toHaveBeenCalledTimes(3);
+  });
+
+  it("backoff 간격이 지수적으로 증가 (1s, 2s)", async () => {
+    const timestamps: number[] = [];
+    const initFn = vi.fn().mockImplementation(() => {
+      timestamps.push(Date.now());
+      return Promise.reject(new Error("fail"));
+    });
+
+    const promise = initializeNodeWithRetry(initFn).catch(() => {});
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await vi.advanceTimersByTimeAsync(2000);
+    await promise;
+
+    expect(timestamps).toHaveLength(3);
+    // 1번째 → 2번째: 1000ms
+    expect(timestamps[1] - timestamps[0]).toBe(1000);
+    // 2번째 → 3번째: 2000ms
+    expect(timestamps[2] - timestamps[1]).toBe(2000);
+  });
+});
+
+describe("PreloadEnded timeout", () => {
+  it("5초 초과 시 false 반환", async () => {
+    const slowRequest = new Promise<boolean>((resolve) => {
+      setTimeout(() => resolve(true), 10000);
+    });
+
+    const result = await Promise.race([
+      slowRequest,
+      new Promise<boolean>((_, reject) =>
+        setTimeout(() => reject(new Error("timeout")), 5000),
+      ),
+    ]).catch(() => false);
+
+    expect(result).toBe(false);
+  });
+});

src/config.ts

@@ -66,7 +66,12 @@ export class NodeInfo {
   public async PreloadEnded(): Promise<boolean> {
     const headlessGraphQLSDK = getSdk(this.GraphqlClient());
     try {
-      const ended = await headlessGraphQLSDK.PreloadEnded();
+      const ended = await Promise.race([
+        headlessGraphQLSDK.PreloadEnded(),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error("PreloadEnded timeout")), 5000),
+        ),
+      ]);
       if (ended.status === 200) {
         this.clientCount = ended.data!.rpcInformation.totalCount;
         this.tip = ended.data!.nodeStatus.tip.index;
@@ -330,3 +335,29 @@ export async function initializeNode(
   );
   return nodeInfo;
 }
+
+export async function initializeNodeWithRetry(
+  rpcEndpoints: RpcEndpoints,
+  quick: boolean = false,
+  maxRetries: number = 2,
+  baseDelayMs: number = 1000,
+): Promise<NodeInfo> {
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await initializeNode(rpcEndpoints, quick);
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error(String(e));
+      console.warn(
+        `initializeNode attempt ${attempt + 1}/${maxRetries + 1} failed: ${
+          lastError.message
+        }`,
+      );
+      if (attempt < maxRetries) {
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+  throw lastError!;
+}

src/main/main.ts

@@ -6,7 +6,7 @@ import {
   netenv,
   baseUrl,
   CONFIG_FILE_PATH,
-  initializeNode,
+  initializeNodeWithRetry,
   NodeInfo,
 } from "../config";
 import {
@@ -70,6 +70,8 @@ let registry: Planet[];
 let accessiblePlanets: Planet[];
 let remoteNode: NodeInfo;
 let geoBlock: { ip: string; country: string; isWhitelist?: boolean };
+// eslint-disable-next-line prefer-const
+let configInitError: string | null = null;
 
 const useUpdate = getConfig("UseUpdate", process.env.NODE_ENV === "production");
 
@@ -189,7 +191,7 @@ async function initializeConfig() {
         return accessiblePlanets[0];
       })();
 
-    remoteNode = await initializeNode(planet.rpcEndpoints, true);
+    remoteNode = await initializeNodeWithRetry(planet.rpcEndpoints, true);
     console.log(registry);
 
     const localConfigVersion = getConfig("ConfigVersion");
@@ -212,6 +214,7 @@ async function initializeConfig() {
     console.error(
       `An unexpected error occurred during fetching remote config. ${error}`,
     );
+    configInitError = error instanceof Error ? error.message : String(error);
   }
 
   log.transports.file.maxSize = getConfig("LogSizeBytes");
@@ -382,12 +385,33 @@ function initializeIpc() {
   });
 
   ipcMain.handle("get-planetary-info", async () => {
-    // Synchronously wait until registry / remote node initialized
-    // This should return, otherwise entry point of renderer will stuck in white screen.
+    const MAX_WAIT_MS = 30_000;
+    const POLL_INTERVAL_MS = 100;
+    let waited = 0;
+
     while (!registry || !remoteNode || !accessiblePlanets) {
-      await utils.sleep(100);
+      if (configInitError) {
+        return { error: configInitError };
+      }
+      if (waited >= MAX_WAIT_MS) {
+        return { error: "Timed out waiting for node initialization." };
+      }
+      await utils.sleep(POLL_INTERVAL_MS);
+      waited += POLL_INTERVAL_MS;
+    }
+    return { data: [registry, remoteNode, accessiblePlanets] };
+  });
+
+  ipcMain.handle("retry-planetary-init", async () => {
+    configInitError = null;
+    remoteNode = undefined as unknown as NodeInfo;
+    await initializeConfig();
+    if (remoteNode && registry && accessiblePlanets) {
+      return { data: [registry, remoteNode, accessiblePlanets] };
     }
-    return [registry, remoteNode, accessiblePlanets];
+    return {
+      error: configInitError ?? "Failed to initialize after retry.",
+    };
   });
 
   ipcMain.handle("check-geoblock", async () => {

src/renderer/App.tsx

@@ -13,31 +13,99 @@ import { observer } from "mobx-react";
 import { Planet } from "src/interfaces/registry";
 import { NodeInfo } from "src/config";
 
+function ConnectionErrorView({
+  error,
+  onRetry,
+}: {
+  error: string;
+  onRetry: () => void;
+}) {
+  const [retrying, setRetrying] = useState(false);
+  return (
+    <div
+      style={{
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: "#1d1e1f",
+        color: "white",
+        fontFamily: "sans-serif",
+      }}
+    >
+      <h1 style={{ color: "#74f4bc", marginBottom: 16 }}>Connection Failed</h1>
+      <p style={{ maxWidth: 400, textAlign: "center", marginBottom: 24 }}>
+        Unable to connect to the Nine Chronicles network. Please check your
+        internet connection.
+      </p>
+      <p style={{ fontSize: 12, color: "#888", marginBottom: 24 }}>{error}</p>
+      <button
+        onClick={() => {
+          setRetrying(true);
+          onRetry();
+        }}
+        disabled={retrying}
+        style={{
+          backgroundColor: retrying ? "#555" : "#3e2a8d",
+          color: "white",
+          border: "none",
+          padding: "12px 36px",
+          fontSize: 16,
+          fontWeight: "bold",
+          cursor: retrying ? "default" : "pointer",
+          borderRadius: 4,
+        }}
+      >
+        {retrying ? "Retrying..." : "Retry"}
+      </button>
+    </div>
+  );
+}
+
 function App() {
   const { planetary, account, game } = useStore();
   const client = useApolloClient();
+  const [initError, setInitError] = useState<string | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+
+  const handlePlanetaryResult = (result: {
+    data?: [Planet[], NodeInfo, Planet[]];
+    error?: string;
+  }) => {
+    if (result.error) {
+      setInitError(result.error);
+      setRetryCount((c) => c + 1);
+      return;
+    }
+    if (result.data) {
+      setInitError(null);
+      planetary.init(result.data[0], result.data[1], result.data[2]);
+    }
+  };
 
-  /** Asynchronous Invoke in useEffect
-   * As ipcRenderer.invoke() is async we're not guaranteed to receive IPC result on time
-   *
-   * Also even if we use .then() to force synchronous flow useEffect() won't wait.
-   * But we need these to render login page.
-   * hence we render null until all three initialized;
-   * Planetary, GQL client, AccountStore
-   *
-   * It could be better if we can have react suspense here.
-   */
   useEffect(() => {
-    ipcRenderer
-      .invoke("get-planetary-info")
-      .then((info: [Planet[], NodeInfo, Planet[]]) => {
-        planetary.init(info[0], info[1], info[2]);
-      });
+    ipcRenderer.invoke("get-planetary-info").then(handlePlanetaryResult);
     ipcRenderer
       .invoke("check-geoblock")
       .then((v) => game.setGeoBlock(v.country, v.isWhitelist ?? false));
   }, []);
 
+  if (initError) {
+    return (
+      <ConnectionErrorView
+        error={initError}
+        onRetry={() => {
+          ipcRenderer
+            .invoke("retry-planetary-init")
+            .then(handlePlanetaryResult);
+        }}
+        key={retryCount}
+      />
+    );
+  }
+
   if (planetary.node === null) return null;
   if (!account.isInitialized) return null;
   if (client === null) return null;