Improve backend request performance

Dockerfile

@@ -17,7 +17,7 @@ COPY requirements.txt ./
 RUN pip install --no-cache-dir -r requirements.txt
 COPY --from=node-build --chown=appuser:appuser /app/dist ./dist
 COPY --from=node-build --chown=appuser:appuser /app/node_modules ./node_modules
-COPY --chown=appuser:appuser package.json app.py start.py ./
+COPY --chown=appuser:appuser package.json app.py start.py storage_listing.py ./
 USER appuser
 EXPOSE 7860
 CMD ["python", "start.py"]

PERFORMANCE.md

@@ -0,0 +1,26 @@
+# Performance checks
+
+The API includes `Server-Timing` on JSON responses:
+
+- `app`: server time until JSON serialization starts.
+- `supabase`: summed response-header waits for Supabase requests started in this request, including auth. Parallel waits overlap, and shared in-flight work is counted only on the originating request.
+
+Requests taking at least one second emit `slow_request` with a route template, status, elapsed time and upstream counts. No cookies, bodies, query parameters or user IDs are logged by this instrumentation. Streaming transfer time is not included in the JSON header.
+
+Compare browser Network timings against these headers after deploying. High browser waiting time with low `app` time points toward transport/proxy latency; high `supabase` times identify upstream waits. Inspect authenticated list, detail, update and delete requests separately.
+
+Read-only baseline from the development machine on 2026-10-20 (two requests per endpoint, not an authenticated benchmark):
+
+| Endpoint | First | Second |
+| --- | ---: | ---: |
+| Public Space `/health` | 1006 ms | 787 ms |
+| Public Space `/api/subscriptions` | 921 ms | 613 ms |
+| Pages proxy `/api/subscriptions` | 1258 ms | 703 ms |
+
+These samples include the development machine's network and do not establish a hosting bottleneck or a before/after improvement.
+
+Changes reduce repeated profile reads after mutations, avoid writes on ordinary profile reads, coalesce concurrent authentication/role checks without caching completed permission decisions, and scope storage listings to one session. The storage listing APIs are documented at https://huggingface.co/docs/huggingface_hub/package_reference/hf_api.
+
+The frontend keeps bounded, account-keyed summary snapshots in tab session storage for at most five minutes. Reloads display them while revalidating. Full analysis payloads are excluded; logout/account changes clear the cache. Server authorization remains required for every API request.
+
+Remaining scaling work should follow production measurements: paginate large rosters and session lists, aggregate ratings in the database, and evaluate backend/database region placement. No production infrastructure or database changes were made here.

app.py

@@ -30,6 +30,7 @@ from fastapi import FastAPI, File, Form, HTTPException, Request, UploadFile
 from fastapi.responses import FileResponse, JSONResponse
 from huggingface_hub import HfApi, hf_hub_download, snapshot_download
 from huggingface_hub.errors import RemoteEntryNotFoundError
+from storage_listing import session_files, session_folder_exists
 
 load_dotenv(Path(__file__).with_name(".env"))
 jobs = {}
@@ -862,9 +863,7 @@ def delete_session(session_id: UUID, request: Request):
         raise HTTPException(409, "Session uses a different storage layout")
 
     if storage_path == expected_path:
-        prefix = f"{storage_path}/"
-        existing_files = hub().list_repo_files(repo_id=os.environ["STORAGE_REPO_ID"], repo_type="dataset")
-        if any(file_path.startswith(prefix) for file_path in existing_files):
+        if session_folder_exists(hub(), os.environ["STORAGE_REPO_ID"], storage_path):
             hub().delete_folder(
                 repo_id=os.environ["STORAGE_REPO_ID"], repo_type="dataset",
                 path_in_repo=storage_path, commit_message=f"Delete session {session_id}",
@@ -884,7 +883,7 @@ def results(session_id: UUID, request: Request):
     prefix = f'{video_dir}camera_'
     video_extensions = {".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v"}
     camera_files = []
-    for repo_file in hub().list_repo_files(repo_id=os.environ["STORAGE_REPO_ID"], repo_type="dataset"):
+    for repo_file in session_files(hub(), os.environ["STORAGE_REPO_ID"], video_dir.rstrip("/")):
         if not repo_file.startswith(prefix):
             continue
         filename = repo_file[len(video_dir):]

package.json

@@ -1,30 +1,31 @@
-{
-  "name": "sporalize-backend",
-  "private": true,
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "tsx watch src/server.ts",
-    "build": "tsc -p tsconfig.json",
-    "start": "python start.py"
-  },
-  "dependencies": {
-    "@supabase/supabase-js": "^2.57.0",
-    "bcryptjs": "^3.0.2",
-    "cookie-parser": "^1.4.7",
-    "cors": "^2.8.5",
-    "dotenv": "^16.6.1",
-    "express": "^5.1.0",
-    "express-rate-limit": "^8.1.0",
-    "helmet": "^8.1.0",
-    "zod": "^4.1.5"
-  },
-  "devDependencies": {
-    "@types/cookie-parser": "^1.4.9",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.3",
-    "@types/node": "^22.16.5",
-    "tsx": "^4.20.5",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "sporalize-backend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "python start.py"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.57.0",
+    "bcryptjs": "^3.0.2",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.5",
+    "dotenv": "^16.6.1",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.1.0",
+    "helmet": "^8.1.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.9",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.16.5",
+    "tsx": "^4.20.5",
+    "typescript": "^5.8.3"
+  }
+}

src/auth.ts

@@ -3,6 +3,12 @@ import type { Request, Response } from "express";
 import type { Session, User } from "@supabase/supabase-js";
 import { env, isProduction } from "./config.js";
 import { supabaseAuth } from "./supabase.js";
+import { singleFlight } from "./single-flight.js";
+
+// Several page, image and polling requests arrive together. Validate once for
+// that burst, without extending a revoked token's lifetime through a TTL cache.
+const verifyAccess = singleFlight((token: string) => supabaseAuth.auth.getUser(token));
+const refreshAccess = singleFlight((token: string) => supabaseAuth.auth.refreshSession({ refresh_token: token }));
 
 const accessCookie = "sp_access";
 const refreshCookie = "sp_refresh";
@@ -59,7 +65,7 @@ export async function authenticatedUser(req: Request, res: Response): Promise<{
   if (!accessToken && !refreshToken) return null;
 
   if (accessToken) {
-    const { data, error } = await supabaseAuth.auth.getUser(accessToken);
+    const { data, error } = await verifyAccess(accessToken);
     if (data.user && !error) return { user: data.user };
   }
 
@@ -67,7 +73,7 @@ export async function authenticatedUser(req: Request, res: Response): Promise<{
     clearSessionCookies(res);
     return null;
   }
-  const { data, error } = await supabaseAuth.auth.refreshSession({ refresh_token: refreshToken });
+  const { data, error } = await refreshAccess(refreshToken);
   if (error || !data.user || !data.session) {
     clearSessionCookies(res);
     return null;

src/read-batches.ts

@@ -0,0 +1,19 @@
+/** Bound parallel DB reads so large rosters do not create unbounded fan-out. */
+export async function readBatches<T, R>(
+  items: readonly T[],
+  load: (batch: T[]) => PromiseLike<readonly R[]>,
+  batchSize = 100,
+  concurrency = 4,
+): Promise<R[]> {
+  if (!Number.isInteger(batchSize) || batchSize < 1 ||
+      !Number.isInteger(concurrency) || concurrency < 1) throw new Error("Invalid batch configuration");
+  const output: R[] = [];
+  for (let offset = 0; offset < items.length; offset += batchSize * concurrency) {
+    const group: PromiseLike<readonly R[]>[] = [];
+    for (let cursor = offset; cursor < Math.min(items.length, offset + batchSize * concurrency); cursor += batchSize) {
+      group.push(load(items.slice(cursor, cursor + batchSize)));
+    }
+    for (const rows of await Promise.all(group)) output.push(...rows);
+  }
+  return output;
+}

src/request-timing.ts

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { RequestHandler } from "express";
+
+const timings = new AsyncLocalStorage<{ upstreamMs: number; calls: number }>();
+
+/** Measures remote response-header wait, without logging tokens or query data. */
+export const timedFetch: typeof fetch = async (input, init) => {
+  const timing = timings.getStore();
+  const started = performance.now();
+  try {
+    return await fetch(input, init);
+  } finally {
+    if (timing) {
+      timing.calls += 1;
+      timing.upstreamMs += performance.now() - started;
+    }
+  }
+};
+
+export const requestTiming: RequestHandler = (req, res, next) => {
+  const timing = { upstreamMs: 0, calls: 0 };
+  const started = performance.now();
+  const json = res.json.bind(res);
+  res.json = (body) => {
+    res.setHeader("Server-Timing",
+      `app;dur=${(performance.now() - started).toFixed(1)}, supabase;dur=${timing.upstreamMs.toFixed(1)};desc="${timing.calls} upstream calls"`);
+    return json(body);
+  };
+  res.once("finish", () => {
+    const duration = performance.now() - started;
+    if (duration >= 1000) console.info("slow_request", {
+      method: req.method, route: req.route?.path ?? "(middleware)",
+      status: res.statusCode, durationMs: Math.round(duration),
+      upstreamMs: Math.round(timing.upstreamMs), upstreamCalls: timing.calls,
+    });
+  });
+  timings.run(timing, next);
+};

src/server.ts

@@ -16,10 +16,14 @@ import { registerProfileImageRoutes } from "./profile-images.js";
 import { registerAdminRoutes } from "./admin.js";
 import { colabWorkerRouter } from "./colab-worker.js";
 import { deleteStoredSession, refundAdminUsage } from "./resource-deletion.js";
+import { singleFlight } from "./single-flight.js";
+import { requestTiming } from "./request-timing.js";
+import { readBatches } from "./read-batches.js";
 
 const app = express();
 app.disable("x-powered-by");
 app.set("trust proxy", env.TRUST_PROXY_HOPS);
+app.use(requestTiming);
 app.use(helmet());
 app.use(cors({
   origin: env.FRONTEND_URL,
@@ -146,11 +150,11 @@ function playerSkillRatings(
   });
 }
 
-export async function accountRoleFor(userId: string) {
+export const accountRoleFor = singleFlight(async (userId: string) => {
   const { data, error } = await supabaseAdmin.from("users").select("account_role").eq("user_id", userId).maybeSingle();
   if (error) throw new Error(`Unable to load account permissions: ${error.message}`);
   return String(data?.account_role ?? "user").toLowerCase();
-}
+});
 
 export async function userIsAdmin(userId: string) {
   return await accountRoleFor(userId) === "admin";
@@ -170,16 +174,12 @@ export async function requireAdmin(req: Request, res: Response) {
 }
 
 async function loadActionAnnotations(actionIds: string[]) {
-  const annotations: Array<{ action_id: string; score: number | null }> = [];
-  // Keep PostgREST query URLs small when a player has many analyzed actions.
-  for (let offset = 0; offset < actionIds.length; offset += 100) {
-    const batch = actionIds.slice(offset, offset + 100);
+  return readBatches<string, { action_id: string; score: number | null }>(actionIds, async (batch) => {
     const { data, error } = await supabaseAdmin.from("annotations")
       .select("action_id,score").in("action_id", batch);
     if (error) throw new Error(`Unable to load action scores: ${error.message}`);
-    annotations.push(...(data ?? []));
-  }
-  return annotations;
+    return data ?? [];
+  });
 }
 
 
@@ -376,11 +376,6 @@ app.put("/api/players/:playerId", async (req, res, next) => {
     if (height < 100 || height > 230 || weight < 20 || weight > 150) {
       return res.status(400).json({ error: "Check the player's age, height and weight." });
     }
-    let existingQuery = supabaseAdmin.from("players").select("player_id").eq("player_id", id.data);
-    if (!isAdmin) existingQuery = existingQuery.eq("user_id", current.user.id);
-    const { data: existing, error: readError } = await existingQuery.maybeSingle();
-    if (readError) throw new Error(`Unable to load player: ${readError.message}`);
-    if (!existing) return res.status(404).json({ error: "Player not found." });
     let updateQuery = supabaseAdmin.from("players").update({
       fname: input.fname,
       lname: input.lname?.trim() || null,
@@ -392,9 +387,17 @@ app.put("/api/players/:playerId", async (req, res, next) => {
       gender: input.gender,
     }).eq("player_id", id.data);
     if (!isAdmin) updateQuery = updateQuery.eq("user_id", current.user.id);
-    const { error } = await updateQuery;
+    const { data, error } = await updateQuery
+      .select("player_id,fname,lname,bdate,height,weight,club,position,gender,image_path").maybeSingle();
     if (error) throw new Error(`Unable to update player: ${error.message}`);
-    return res.json({ ok: true });
+    if (!data) return res.status(404).json({ error: "Player not found." });
+    return res.json({ ok: true, player: {
+      playerId: data.player_id, fname: data.fname ?? "", lname: data.lname ?? "",
+      name: [data.fname, data.lname].filter(Boolean).join(" "), bdate: data.bdate,
+      age: ageFromBirthday(data.bdate), heightCm: String(data.height ?? ""),
+      weightKg: String(data.weight ?? ""), club: data.club ?? "", position: data.position ?? "",
+      gender: data.gender ?? null, imagePath: data.image_path ?? null,
+    } });
   } catch (error) { next(error); }
 });
 
@@ -543,11 +546,11 @@ app.get("/api/players-overview/:playerId", async (req, res, next) => {
       .select("player_id,user_id,fname,lname,bdate,height,weight,position,club,gender,image_path")
       .order("fname", { ascending: true });
     if (!isAdmin) overviewQuery = overviewQuery.eq("user_id", current.user.id);
-    const { data: overview, error: overviewError } = await overviewQuery;
-    if (overviewError) throw new Error(`Unable to load players: ${overviewError.message}`);
     let sessionsQuery = supabaseAdmin.from("sessions").select("session_id,player_id,name,created_at,user_id");
     if (!isAdmin) sessionsQuery = sessionsQuery.eq("user_id", current.user.id);
-    const { data: sessions, error: sessionsError } = await sessionsQuery;
+    const [{ data: overview, error: overviewError }, { data: sessions, error: sessionsError }] =
+      await Promise.all([overviewQuery, sessionsQuery]);
+    if (overviewError) throw new Error(`Unable to load players: ${overviewError.message}`);
     if (sessionsError) throw new Error(`Unable to load sessions: ${sessionsError.message}`);
     const { data: actions, error: actionsError } = (sessions ?? []).length
       ? await supabaseAdmin.from("actions").select("action_id,session_id,type").in("session_id", sessions!.map((row) => row.session_id))
@@ -558,7 +561,8 @@ app.get("/api/players-overview/:playerId", async (req, res, next) => {
 
     const scoreMap = new Map(annotations.map((row) => [row.action_id, row.score == null ? null : Number(row.score)]));
     const ownSessions = (sessions ?? []).filter((row) => row.player_id === playerId.data);
-    const ownActions = (actions ?? []).filter((row) => ownSessions.some((session) => session.session_id === row.session_id));
+    const ownSessionIds = new Set(ownSessions.map((session) => session.session_id));
+    const ownActions = (actions ?? []).filter((row) => ownSessionIds.has(row.session_id));
     const ownScores = ownActions.map((row) => scoreMap.get(row.action_id)).filter((score): score is number => score != null && Number.isFinite(score));
     const byAction = playerSkillRatings(ownActions, scoreMap);
     const sessionPlayerById = new Map((sessions ?? []).map((row) => [row.session_id, row.player_id]));
@@ -574,10 +578,6 @@ app.get("/api/players-overview/:playerId", async (req, res, next) => {
       const values = sessionActions.map((action) => scoreMap.get(action.action_id)).filter((score): score is number => score != null && Number.isFinite(score));
       return { sessionId: row.session_id, createdAt: Date.parse(row.created_at) || 0, score: meanPlayerScore(values), actionCount: sessionActions.length, scoredCount: values.length };
     });
-    let peersQuery = supabaseAdmin.from("players").select("player_id");
-    if (!isAdmin) peersQuery = peersQuery.eq("user_id", current.user.id);
-    const { data: peers, error: peersError } = await peersQuery;
-    if (peersError) throw new Error(`Unable to load roster: ${peersError.message}`);
     const playerScores = new Map<string, number[]>();
     for (const action of actions ?? []) {
       const ownerId = sessionPlayerById.get(action.session_id);
@@ -601,7 +601,7 @@ app.get("/api/players-overview/:playerId", async (req, res, next) => {
       createdAt: "", updatedAt: "", hasProfile: true, sessionCount: ownSessions.length, actionCount: ownActions.length,
       lastSessionAt: sessionsForPlayer[0]?.createdAt ?? 0,
       scores: { playerId: player.player_id, rubricVersion: "database", totalActions: ownActions.length, scoredActions: ownScores.length, byAction, byQuality: [], overall: meanPlayerScore(ownScores), sessions: sessionsForPlayer },
-      squadAverage, rank: rankIndex < 0 ? null : rankIndex + 1, playerCount: peers?.length ?? 0,
+      squadAverage, rank: rankIndex < 0 ? null : rankIndex + 1, playerCount: overview?.length ?? 0,
     });
   } catch (error) { next(error); }
 });
@@ -619,14 +619,16 @@ app.get("/api/sessions-overview", async (req, res, next) => {
     const { data: sessions, error } = await sessionsQuery;
     if (error) throw new Error(`Unable to load sessions: ${error.message}`);
     const playerIds = [...new Set((sessions ?? []).flatMap((row) => row.player_id ? [row.player_id] : []))];
-    const { data: players, error: playersError } = playerIds.length
-      ? await supabaseAdmin.from("players").select("player_id,fname,lname,gender,image_path").in("player_id", playerIds)
-      : { data: [], error: null };
-    if (playersError) throw new Error(`Unable to load session players: ${playersError.message}`);
     const sessionIds = (sessions ?? []).map((row) => row.session_id);
-    const { data: actions, error: actionsError } = sessionIds.length
-      ? await supabaseAdmin.from("actions").select("session_id,type").in("session_id", sessionIds)
-      : { data: [], error: null };
+    const [{ data: players, error: playersError }, { data: actions, error: actionsError }] = await Promise.all([
+      playerIds.length
+        ? supabaseAdmin.from("players").select("player_id,fname,lname,gender,image_path").in("player_id", playerIds)
+        : Promise.resolve({ data: [], error: null }),
+      sessionIds.length
+        ? supabaseAdmin.from("actions").select("session_id,type").in("session_id", sessionIds)
+        : Promise.resolve({ data: [], error: null }),
+    ]);
+    if (playersError) throw new Error(`Unable to load session players: ${playersError.message}`);
     if (actionsError) throw new Error(`Unable to load session actions: ${actionsError.message}`);
     const playerNames = new Map((players ?? []).map((row) => [row.player_id, [row.fname, row.lname].filter(Boolean).join(" ")]));
     const playerImages = new Map((players ?? []).map((row) => [row.player_id, { gender: row.gender, imagePath: row.image_path }]));
@@ -1032,11 +1034,16 @@ app.get("/api/auth/profile", async (req, res, next) => {
   try {
     const current = await authenticatedUser(req, res);
     if (!current) return res.status(401).json({ error: "Authentication required." });
-    await syncProfile(current.user);
-    const { data, error } = await supabaseAdmin.from("users")
+    const readProfile = () => supabaseAdmin.from("users")
       .select("fname,lname,email,academy,role,image_path")
       .eq("user_id", current.user.id)
-      .single();
+      .maybeSingle();
+    let { data, error } = await readProfile();
+    // Repair an absent profile only; normal reads must not write to the DB.
+    if (!error && !data) {
+      await syncProfile(current.user);
+      ({ data, error } = await readProfile());
+    }
     if (error || !data) throw new Error(`Unable to load user profile: ${error?.message ?? "Profile not found"}`);
     const hasPassword = userHasPassword(current.user);
     return res.json({ profile: { ...data, imagePath: data.image_path, emailVerified: Boolean(current.user.email_confirmed_at), hasPassword } });

src/single-flight.ts

@@ -0,0 +1,13 @@
+/** Share only concurrent work. Completed values and failures are never cached. */
+export function singleFlight<Key, Value>(load: (key: Key) => PromiseLike<Value>) {
+  const pending = new Map<Key, Promise<Value>>();
+  return (key: Key): Promise<Value> => {
+    const existing = pending.get(key);
+    if (existing) return existing;
+    const request = Promise.resolve().then(() => load(key)).finally(() => {
+      if (pending.get(key) === request) pending.delete(key);
+    });
+    pending.set(key, request);
+    return request;
+  };
+}

src/supabase.ts

@@ -3,6 +3,7 @@ import bcrypt from "bcryptjs";
 import { randomBytes } from "node:crypto";
 import type { Request, Response } from "express";
 import { env, isProduction } from "./config.js";
+import { timedFetch } from "./request-timing.js";
 
 // Bind Google's PKCE verifier to the initiating browser, not a shared client's
 // in-memory store (which concurrent logins can overwrite or a restart can lose).
@@ -10,6 +11,7 @@ export function oauthClient(req: Request, res: Response) {
   const cookieName = "sp_oauth_verifier";
   const options = { httpOnly: true, secure: isProduction, sameSite: "lax" as const, path: "/api/auth" };
   return createClient(env.SUPABASE_URL, env.SUPABASE_ANON_KEY, {
+    global: { fetch: timedFetch },
     auth: {
       autoRefreshToken: false, persistSession: true, detectSessionInUrl: false, flowType: "pkce",
       storage: {
@@ -26,12 +28,14 @@ export function oauthClient(req: Request, res: Response) {
 }
 
 export const supabaseAuth = createClient(env.SUPABASE_URL, env.SUPABASE_ANON_KEY, {
+  global: { fetch: timedFetch },
   // OAuth returns a one-time code for the backend callback to exchange, rather
   // than placing session tokens in the browser URL fragment.
   auth: { autoRefreshToken: false, persistSession: false, detectSessionInUrl: false, flowType: "pkce" },
 });
 
 export const supabaseAdmin = createClient(env.SUPABASE_URL, env.SUPABASE_SERVICE_ROLE_KEY, {
+  global: { fetch: timedFetch },
   auth: { autoRefreshToken: false, persistSession: false, detectSessionInUrl: false },
 });
 

storage_listing.py

@@ -0,0 +1,20 @@
+"""Keep metadata requests scoped to the session being viewed."""
+from huggingface_hub import RepoFile
+from huggingface_hub.errors import RemoteEntryNotFoundError
+
+
+def session_files(api, repo_id, folder):
+    try:
+        return [
+            entry.path for entry in api.list_repo_tree(
+                repo_id=repo_id, repo_type="dataset", path_in_repo=folder,
+                recursive=False, expand=False,
+            ) if isinstance(entry, RepoFile)
+        ]
+    except RemoteEntryNotFoundError:
+        # Old sessions can have results but no source video folder.
+        return []
+
+
+def session_folder_exists(api, repo_id, folder):
+    return bool(api.get_paths_info(repo_id=repo_id, repo_type="dataset", paths=[folder]))

tests/read-batches.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readBatches } from "../src/read-batches.js";
+
+test("caps concurrent reads, keeps result order and includes the final partial batch", async () => {
+  let active = 0;
+  let peak = 0;
+  const input = Array.from({ length: 23 }, (_, index) => index);
+  const output = await readBatches(input, async (batch) => {
+    peak = Math.max(peak, ++active);
+    await new Promise((resolve) => setTimeout(resolve, batch[0] % 2 ? 1 : 5));
+    active--;
+    return batch;
+  }, 5, 3);
+  assert.equal(peak, 3);
+  assert.deepEqual(output, input);
+});
+
+test("does not query empty input or return incomplete results after failure", async () => {
+  assert.deepEqual(await readBatches([], () => { throw new Error("should not run"); }), []);
+  await assert.rejects(readBatches([1, 2], async () => { throw new Error("DB unavailable"); }), /DB unavailable/);
+});

tests/single-flight.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { singleFlight } from "../src/single-flight.js";
+
+test("shares concurrent validation, isolates tokens, and revalidates after completion", async () => {
+  let calls = 0;
+  const run = singleFlight(async (token: string) => { calls++; return token; });
+  const first = run("one");
+  assert.equal(first, run("one"));
+  assert.notEqual(first, run("two"));
+  assert.equal(await first, "one");
+  assert.equal(calls, 2);
+  await run("one");
+  assert.equal(calls, 3);
+});
+
+test("does not retain failed validation", async () => {
+  let calls = 0;
+  const run = singleFlight(async () => { if (++calls === 1) throw new Error("network"); return "verified"; });
+  await assert.rejects(run("token"), /network/);
+  assert.equal(await run("token"), "verified");
+});

tests/test_storage_listing.py

@@ -0,0 +1,42 @@
+import unittest
+import httpx
+from unittest.mock import Mock
+from huggingface_hub import RepoFile, RepoFolder
+from huggingface_hub.errors import RemoteEntryNotFoundError
+from storage_listing import session_files, session_folder_exists
+
+
+class StorageListingTest(unittest.TestCase):
+    def test_lists_only_requested_folder_and_excludes_directories(self):
+        api = Mock()
+        api.list_repo_tree.return_value = [
+            RepoFile(path="sessions/one/videos/camera_1.mp4", size=1, oid="a"),
+            RepoFolder(path="sessions/one/videos/subdir", oid="b"),
+        ]
+        self.assertEqual(session_files(api, "repo", "sessions/one/videos"),
+                         ["sessions/one/videos/camera_1.mp4"])
+        api.list_repo_tree.assert_called_once_with(
+            repo_id="repo", repo_type="dataset", path_in_repo="sessions/one/videos",
+            recursive=False, expand=False)
+        api.list_repo_files.assert_not_called()
+
+    def test_missing_folder_is_empty_but_other_errors_propagate(self):
+        api = Mock()
+        api.list_repo_tree.side_effect = RemoteEntryNotFoundError(
+            "missing", response=httpx.Response(404, request=httpx.Request("GET", "https://example.com/tree")))
+        self.assertEqual(session_files(api, "repo", "folder"), [])
+        api.list_repo_tree.side_effect = RuntimeError("unavailable")
+        with self.assertRaises(RuntimeError):
+            session_files(api, "repo", "folder")
+
+    def test_deletion_checks_only_the_session_path(self):
+        api = Mock()
+        api.get_paths_info.return_value = []
+        self.assertFalse(session_folder_exists(api, "repo", "sessions/one"))
+        api.get_paths_info.assert_called_once_with(
+            repo_id="repo", repo_type="dataset", paths=["sessions/one"])
+        api.list_repo_files.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()