Retry setup-status checks before showing auth

Author: RhysSullivan

apps/host-selfhost/src/setup-status.web.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from "@effect/vitest";
+
+import { SetupStatusError, fetchNeedsSetup } from "../web/setup-status";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("fetchNeedsSetup", () => {
+  it("returns false when the server says setup is complete", async () => {
+    vi.stubGlobal("fetch", async () =>
+      new Response(JSON.stringify({ needsSetup: false }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    await expect(fetchNeedsSetup()).resolves.toBe(false);
+  });
+
+  it("retries failed setup checks before surfacing an error", async () => {
+    let calls = 0;
+    vi.stubGlobal("fetch", async () => {
+      calls += 1;
+      return new Response("unavailable", { status: 503 });
+    });
+
+    await expect(fetchNeedsSetup()).rejects.toBeInstanceOf(SetupStatusError);
+    expect(calls).toBe(3);
+  });
+});

apps/host-selfhost/web/routes/__root.tsx

@@ -6,6 +6,14 @@ import { ExecutorPluginsProvider } from "@executor-js/sdk/client";
 import { OrganizationProvider } from "@executor-js/react/api/organization-context";
 import { OrgSlugGate } from "@executor-js/react/multiplayer/org-slug-gate";
 import { Toaster } from "@executor-js/react/components/sonner";
+import { Button } from "@executor-js/react/components/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@executor-js/react/components/card";
 import { AuthProvider, useAuth } from "@executor-js/react/multiplayer/auth-context";
 import { Shell, defaultShellNavItems } from "@executor-js/react/multiplayer/shell";
 import { plugins as clientPlugins } from "virtual:executor/plugins-client";
@@ -48,26 +56,72 @@ const Loading = () => (
   </div>
 );
 
+const SetupStatusErrorCard = ({ onRetry }: { onRetry: () => void }) => (
+  <div className="flex min-h-screen items-center justify-center bg-background p-6">
+    <Card className="w-full max-w-md">
+      <CardHeader>
+        <CardTitle>Can't reach the server</CardTitle>
+        <CardDescription>
+          Executor couldn't check this instance's setup state. Make sure the server is running, then
+          retry.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Button type="button" onClick={onRetry}>
+          Retry
+        </Button>
+      </CardContent>
+    </Card>
+  </div>
+);
+
 function AuthGate({ children }: { children: ReactNode }) {
   const auth = useAuth();
   // When unauthenticated, decide between first-run setup and sign-in by asking
-  // the server whether the instance still has zero members. `null` = checking.
-  const [needsSetup, setNeedsSetup] = useState<boolean | null>(null);
+  // the server whether the instance still has zero members.
+  const [setupStatus, setSetupStatus] = useState<
+    | { state: "checking"; attempt: number }
+    | { state: "ready"; needsSetup: boolean }
+    | { state: "error"; attempt: number }
+  >({ state: "checking", attempt: 0 });
   useEffect(() => {
     if (auth.status !== "unauthenticated") return;
     let alive = true;
-    void fetchNeedsSetup().then((value) => {
-      if (alive) setNeedsSetup(value);
-    });
+    setSetupStatus((current) => ({ state: "checking", attempt: current.attempt }));
+    void fetchNeedsSetup().then(
+      (value) => {
+        if (alive) setSetupStatus({ state: "ready", needsSetup: value });
+      },
+      () => {
+        if (alive) {
+          setSetupStatus((current) => ({
+            state: "error",
+            attempt: current.state === "ready" ? 0 : current.attempt,
+          }));
+        }
+      },
+    );
     return () => {
       alive = false;
     };
-  }, [auth.status]);
+  }, [auth.status, setupStatus.attempt]);
 
   if (auth.status === "loading") return <Loading />;
   if (auth.status === "unauthenticated") {
-    if (needsSetup === null) return <Loading />;
-    return needsSetup ? <SetupPage /> : <LoginPage />;
+    if (setupStatus.state === "checking") return <Loading />;
+    if (setupStatus.state === "error") {
+      return (
+        <SetupStatusErrorCard
+          onRetry={() =>
+            setSetupStatus((current) => ({
+              state: "checking",
+              attempt: current.state === "ready" ? 0 : current.attempt + 1,
+            }))
+          }
+        />
+      );
+    }
+    return setupStatus.needsSetup ? <SetupPage /> : <LoginPage />;
   }
   return <>{children}</>;
 }

apps/host-selfhost/web/setup-status.ts

@@ -1,17 +1,34 @@
 // Pre-login check of whether the instance still needs first-run setup (its one
 // org has zero members). Read by the auth gate to choose the setup vs sign-in
 // screen. A plain same-origin fetch — the same boundary the /join + setup
-// screens use, which run before the atom registry exists. Two-arg `then` keeps
-// it Promise.catch-free; any failure falls back to "no setup needed" (sign-in).
+// screens use, which run before the atom registry exists.
+
+const retryDelaysMs = [250, 500, 1_000] as const;
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class SetupStatusError extends Error {
+  constructor() {
+    super("Unable to check setup status");
+    this.name = "SetupStatusError";
+  }
+}
+
 export const fetchNeedsSetup = async (): Promise<boolean> => {
-  const response = await fetch("/api/setup-status", { credentials: "same-origin" }).then(
-    (r) => r,
-    () => null,
-  );
-  if (!response || !response.ok) return false;
-  const data = (await response.json().then(
-    (d) => d,
-    () => ({}),
-  )) as { needsSetup?: boolean };
-  return data.needsSetup === true;
+  for (let attempt = 0; attempt < retryDelaysMs.length; attempt += 1) {
+    const response = await fetch("/api/setup-status", { credentials: "same-origin" }).then(
+      (r) => r,
+      () => null,
+    );
+    if (response?.ok) {
+      const data = (await response.json().then(
+        (d) => d,
+        () => ({}),
+      )) as { needsSetup?: boolean };
+      return data.needsSetup === true;
+    }
+    if (attempt < retryDelaysMs.length - 1) await sleep(retryDelaysMs[attempt]);
+  }
+  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: pre-Effect setup-status fetch rejects so the auth gate can surface retry failure
+  throw new SetupStatusError();
 };