test(face-clusters): add useGlobalRecluster tests; warn on multi-worker setup

- Add unit tests for the useGlobalRecluster polling hook covering the success
  lifecycle, error from start, error reported by the status poll, polling
  cleanup on unmount, and that a rapid second trigger does not leave a second
  poll loop running.

- Warn at startup when WORKERS > 1, since model-download and global-reclustering
  job tracking is in-memory and per-worker; a job started in one worker is
  invisible to others, so deployments should keep a single worker. This is a
  non-breaking safeguard (no behaviour change to the default single-worker run).

Author: VanshajPoonia

backend/main.py

@@ -46,6 +46,8 @@
 # Configure Uvicorn logging to use our custom formatter
 configure_uvicorn_logging("backend")
 
+logger = get_logger("backend")
+
 path = os.path.dirname(DATABASE_PATH)
 os.makedirs(path, exist_ok=True)
 
@@ -64,6 +66,22 @@ async def lifespan(app: FastAPI):
     db_create_albums_table()
     db_create_album_images_table()
     db_create_metadata_table()
+    # Model-download and global-reclustering job tracking is in-memory and
+    # per-worker. With more than one worker, a job started in one worker is
+    # invisible to the others, so status polls can miss it and duplicate jobs
+    # can start. Warn loudly so deployments keep a single worker (WORKERS=1).
+    try:
+        worker_count = int(os.environ.get("WORKERS", "1"))
+    except ValueError:
+        worker_count = 1
+    if worker_count > 1:
+        logger.warning(
+            "WORKERS=%s: model-download and global-reclustering job tracking is "
+            "in-memory and per-worker. Run with a single worker (WORKERS=1) to "
+            "avoid duplicate jobs and missed status polls.",
+            worker_count,
+        )
+
     # Create ProcessPoolExecutor and attach it to app.state
     app.state.executor = ProcessPoolExecutor(max_workers=1)
 

frontend/src/hooks/__tests__/useGlobalRecluster.test.tsx

@@ -0,0 +1,164 @@
+import React from 'react';
+import { renderHook, act } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useGlobalRecluster } from '@/hooks/useGlobalRecluster';
+import {
+  startGlobalReclustering,
+  getGlobalReclusterStatus,
+} from '@/api/api-functions/face_clusters';
+
+jest.mock('@/api/api-functions/face_clusters', () => ({
+  startGlobalReclustering: jest.fn(),
+  getGlobalReclusterStatus: jest.fn(),
+}));
+
+const mockStart = startGlobalReclustering as jest.MockedFunction<
+  typeof startGlobalReclustering
+>;
+const mockStatus = getGlobalReclusterStatus as jest.MockedFunction<
+  typeof getGlobalReclusterStatus
+>;
+
+const POLL_INTERVAL_MS = 2000;
+
+const startOk = { success: true, message: 'started', data: { task_id: 'abc' } };
+const running = {
+  success: true,
+  data: {
+    status: 'running' as const,
+    clusters_created: null,
+    faces_skipped: null,
+  },
+};
+const complete = {
+  success: true,
+  message: 'done',
+  data: { status: 'complete' as const, clusters_created: 3, faces_skipped: 1 },
+};
+const errored = {
+  success: false,
+  message: 'reclustering failed',
+  data: {
+    status: 'error' as const,
+    clusters_created: null,
+    faces_skipped: null,
+  },
+};
+
+function setup() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const invalidateSpy = jest.spyOn(queryClient, 'invalidateQueries');
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  const utils = renderHook(() => useGlobalRecluster(), { wrapper });
+  return { ...utils, invalidateSpy };
+}
+
+// Flush pending promises and advance fake timers together.
+const flush = async (ms = 0) => {
+  await act(async () => {
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(ms);
+  });
+};
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  mockStart.mockReset();
+  mockStatus.mockReset();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+describe('useGlobalRecluster', () => {
+  test('polls until the job completes successfully', async () => {
+    mockStart.mockResolvedValue(startOk);
+    mockStatus.mockResolvedValueOnce(running).mockResolvedValueOnce(complete);
+
+    const { result, invalidateSpy } = setup();
+
+    act(() => {
+      result.current.trigger();
+    });
+    expect(result.current.isPending).toBe(true);
+
+    await flush(); // start resolves, first poll -> running
+    expect(mockStatus).toHaveBeenCalledTimes(1);
+    expect(result.current.isPending).toBe(true);
+
+    await flush(POLL_INTERVAL_MS); // scheduled poll -> complete
+    expect(result.current.isSuccess).toBe(true);
+    expect(result.current.successData).toEqual(complete.data);
+    expect(result.current.successMessage).toBe('done');
+    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ['clusters'] });
+  });
+
+  test('sets an error when the job reports failure', async () => {
+    mockStart.mockResolvedValue(startOk);
+    mockStatus.mockResolvedValue(errored);
+
+    const { result, invalidateSpy } = setup();
+    act(() => {
+      result.current.trigger();
+    });
+    await flush();
+
+    expect(result.current.isError).toBe(true);
+    expect(result.current.errorMessage).toBe('reclustering failed');
+    expect(invalidateSpy).toHaveBeenCalledWith({ queryKey: ['clusters'] });
+  });
+
+  test('sets an error when starting the job fails', async () => {
+    mockStart.mockRejectedValue(new Error('network down'));
+
+    const { result } = setup();
+    act(() => {
+      result.current.trigger();
+    });
+    await flush();
+
+    expect(result.current.isError).toBe(true);
+    expect(mockStatus).not.toHaveBeenCalled();
+  });
+
+  test('stops polling after unmount', async () => {
+    mockStart.mockResolvedValue(startOk);
+    mockStatus.mockResolvedValue(running);
+
+    const { result, unmount } = setup();
+    act(() => {
+      result.current.trigger();
+    });
+    await flush(); // first poll
+    expect(mockStatus).toHaveBeenCalledTimes(1);
+
+    unmount();
+    await flush(POLL_INTERVAL_MS * 3);
+    // No further polls once unmounted.
+    expect(mockStatus).toHaveBeenCalledTimes(1);
+  });
+
+  test('a rapid second trigger does not leave a second poll loop running', async () => {
+    mockStart.mockResolvedValue(startOk);
+    mockStatus.mockResolvedValue(running);
+
+    const { result } = setup();
+    // Both triggers fire before startGlobalReclustering resolves.
+    act(() => {
+      result.current.trigger();
+      result.current.trigger();
+    });
+
+    await flush(); // both starts resolve; only the latest run may poll
+    expect(mockStatus).toHaveBeenCalledTimes(1);
+
+    const callsBefore = mockStatus.mock.calls.length;
+    await flush(POLL_INTERVAL_MS); // exactly one loop advances
+    expect(mockStatus.mock.calls.length).toBe(callsBefore + 1);
+  });
+});