@cat-factory/app 0.136.0 → 0.136.1

package/app/stores/auth.ts

@@ -6,6 +6,7 @@ import type {
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import type { AuthUser } from '~/types/domain'
+import { retryWhileBackendUnreachable } from '~/utils/backendReady'
 
 /**
  * "Login with GitHub" session state. The backend mints a signed session token
@@ -184,7 +185,10 @@ export const useAuthStore = defineStore(
       // which must be exchanged — not stored as a local token by `consumeRedirectToken`).
       if (!(await maybeConnectMothership())) consumeRedirectToken()
       try {
-        const config = await api.getAuthConfig()
+        // Tolerate a cold-start race: when the SPA and backend boot together, this first call
+        // can beat the backend's listener by a second or two. Retry a not-listening-yet socket
+        // (the gate keeps showing its spinner) instead of degrading to the unreachable screen.
+        const config = await retryWhileBackendUnreachable(() => api.getAuthConfig())
         required.value = config.enabled
         if (config.providers) providers.value = config.providers
         patProviders.value = config.patLogin?.providers ?? []

package/app/stores/workspace.ts

@@ -35,6 +35,7 @@ import { useGitHubStore } from '~/stores/github'
 import { useFragmentsStore } from '~/stores/fragments'
 import { useProviderConnectionsStore } from '~/stores/providerConnections'
 import { markBoot } from '~/utils/bootMarks'
+import { retryWhileBackendUnreachable } from '~/utils/backendReady'
 
 /**
  * Owns the active workspace and bootstraps the app against the backend. On load
@@ -207,7 +208,10 @@ export const useWorkspaceStore = defineStore(
           useAccountsStore()
             .load()
             .catch(() => {}),
-          api.listWorkspaces(),
+          // Retry a not-listening-yet backend (cold-start race) before surfacing the
+          // unreachable screen. This gates the rest of init, so once it resolves the
+          // backend is up and the speculative/follow-up snapshot fetches succeed too.
+          retryWhileBackendUnreachable(() => api.listWorkspaces()),
         ])
         markBoot('workspaces-listed')
         workspaces.value = workspaceList

package/app/utils/backendReady.spec.ts

@@ -0,0 +1,69 @@
+import { SchemaValidationError } from '@toad-contracts/core'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiError } from '~/composables/api/errors'
+import { isBackendUnreachable, retryWhileBackendUnreachable } from '~/utils/backendReady'
+
+// The cold-start race: the SPA's first fetch can beat the backend's listener, throwing a
+// status-less network fault. These lock in that we wait THAT out (with a deadline) but
+// surface a real HTTP error response — a live-but-erroring backend — immediately.
+
+describe('isBackendUnreachable', () => {
+  it('is true for a status-less network fault', () => {
+    expect(isBackendUnreachable(new Error('Failed to fetch'))).toBe(true)
+  })
+
+  it('is false for an HTTP error response (the backend answered)', () => {
+    expect(isBackendUnreachable(new ApiError(500, {}))).toBe(false)
+    expect(isBackendUnreachable({ status: 503 })).toBe(false)
+  })
+
+  it('is false for a schema-validation failure (a deterministic answer, not a dead socket)', () => {
+    // The backend answered but its body (or our request) didn't match the contract — retrying
+    // can never clear it, so it must surface at once rather than wait out the deadline.
+    expect(isBackendUnreachable(new SchemaValidationError([]))).toBe(false)
+  })
+})
+
+describe('retryWhileBackendUnreachable', () => {
+  afterEach(() => vi.useRealTimers())
+
+  it('returns the first result without waiting when the backend answers', async () => {
+    const fn = vi.fn(async () => 'ok')
+    await expect(retryWhileBackendUnreachable(fn)).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries a not-listening-yet backend, then succeeds', async () => {
+    vi.useFakeTimers()
+    let calls = 0
+    const fn = vi.fn(async () => {
+      if (++calls < 3) throw new Error('connection refused') // status-less
+      return 'ok'
+    })
+    const promise = retryWhileBackendUnreachable(fn)
+    await vi.advanceTimersByTimeAsync(10_000)
+    await expect(promise).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('rethrows an HTTP error response immediately (no retry)', async () => {
+    const fn = vi.fn(async () => {
+      throw new ApiError(500, {})
+    })
+    await expect(retryWhileBackendUnreachable(fn)).rejects.toBeInstanceOf(ApiError)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('gives up and rethrows the last fault once the deadline passes', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn(async () => {
+      throw new Error('down')
+    })
+    const rejects = expect(retryWhileBackendUnreachable(fn, { deadlineMs: 1_000 })).rejects.toThrow(
+      'down',
+    )
+    await vi.advanceTimersByTimeAsync(2_000)
+    await rejects
+    expect(fn.mock.calls.length).toBeGreaterThan(1)
+  })
+})

package/app/utils/backendReady.ts

@@ -0,0 +1,54 @@
+import { SchemaValidationError } from '@toad-contracts/core'
+import { apiErrorStatus } from '~/composables/api/errors'
+
+/**
+ * True only for a not-listening-yet backend — a connection-level fault (connection refused /
+ * reset / DNS) that throws before any HTTP round-trip completes, so it carries neither an HTTP
+ * status nor schema issues. Everything else is a real, deterministic answer that retrying can
+ * never clear, so it must surface at once, not loop:
+ *
+ * - An HTTP RESPONSE arrived — a declared non-2xx (`ApiError`) or an undeclared status
+ *   (`UnexpectedResponseError`); both carry a `statusCode`, so `apiErrorStatus` returns it.
+ * - A `SchemaValidationError` — the backend answered but its body (or our own request) didn't
+ *   match the contract, i.e. a version skew / client bug, NOT a dead socket.
+ */
+export function isBackendUnreachable(error: unknown): boolean {
+  if (error instanceof SchemaValidationError) return false
+  return apiErrorStatus(error) === undefined
+}
+
+export interface BackendRetryOptions {
+  /** Total wall-clock budget before we give up and rethrow (default 15s). */
+  deadlineMs?: number
+  /** First backoff delay; doubles each attempt up to {@link BackendRetryOptions.maxDelayMs}. */
+  baseDelayMs?: number
+  /** Backoff ceiling (default 2s). */
+  maxDelayMs?: number
+}
+
+/**
+ * Run `fn`, retrying while the backend is merely not-listening-yet (see
+ * {@link isBackendUnreachable}) with exponential backoff, up to a wall-clock deadline.
+ *
+ * This exists for the cold-open race: when the frontend and backend are started together,
+ * the SPA's first fetch can beat the backend's listener by a second or two. A single attempt
+ * would strand the board on the "Can't reach the backend" screen until a manual reload, even
+ * though the backend comes up moments later. An HTTP error response (any status) is a real
+ * answer, so it rethrows immediately rather than looping — we only wait out a dead socket.
+ */
+export async function retryWhileBackendUnreachable<T>(
+  fn: () => Promise<T>,
+  { deadlineMs = 15_000, baseDelayMs = 300, maxDelayMs = 2_000 }: BackendRetryOptions = {},
+): Promise<T> {
+  const start = Date.now()
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      const elapsed = Date.now() - start
+      if (!isBackendUnreachable(error) || elapsed >= deadlineMs) throw error
+      const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt, deadlineMs - elapsed)
+      await new Promise<void>((resolve) => setTimeout(resolve, delay))
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.136.0",
+  "version": "0.136.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",