Add cache backup support

.gitignore

@@ -1,6 +1,7 @@
 node_modules
 dist
 .cache
+.idea
 .DS_Store
 .env
 .env.*

Dockerfile

@@ -20,6 +20,7 @@ RUN npm install --omit=dev
 
 COPY --from=build /app/dist ./dist
 COPY server ./server
+COPY dupr_players.csv ./dupr_players.csv
 
 EXPOSE 7860
 

README.md

@@ -24,13 +24,20 @@ This Hugging Face Docker Space displays a May 2026 DUPR event roster from `dupr_
 Add this Hugging Face Space Secret:
 
 - `DUPR_BEARER_TOKEN`
+- `HF_TOKEN`
 
-The value should be a valid DUPR bearer token copied from an authenticated DUPR session. Keep the Space private unless you are comfortable with other users making requests through that session.
+`DUPR_BEARER_TOKEN` should be a valid DUPR bearer token copied from an authenticated DUPR session. `HF_TOKEN` should have write access to the backup dataset. Keep the Space private unless you are comfortable with other users making requests through that session.
+
+Optional cache backup settings:
+
+- `HF_DATASET_REPO`, defaults to `derek-thomas/dupr_explorer_may_2026`
+- `HF_CACHE_PATH`, defaults to `player-cache.json`
 
 ## Data Files
 
 - `dupr_players.csv` is the roster source.
 - `.cache/player-cache.json` is generated at runtime and stores DUPR lookups, ratings, match summaries, and unresolved lookup errors.
+- When `HF_TOKEN` is configured, the server restores `.cache/player-cache.json` from the Hugging Face dataset if the local file is missing, then backs up each cache write to `derek-thomas/dupr_explorer_may_2026`.
 
 The CSV expects these columns:
 
@@ -46,6 +53,7 @@ Create a local `.env` file:
 
 ```bash
 DUPR_BEARER_TOKEN=your_token
+HF_TOKEN=your_hf_token
 ```
 
 Then run:
@@ -71,5 +79,6 @@ Then open `http://127.0.0.1:7860`.
 - Runtime port is `7860`.
 - Create the Space with the Docker SDK.
 - Keep `DUPR_BEARER_TOKEN` configured as a Space Secret.
+- Keep `HF_TOKEN` configured as a Space Secret so runtime cache updates survive Space restarts and DUPR token interruptions.
 - The DUPR token can expire and may need to be refreshed.
 - Do not commit tokens or private DUPR session data.

package-lock.json

@@ -8,6 +8,7 @@
       "name": "dupr-url-resolver",
       "version": "1.0.0",
       "dependencies": {
+        "@huggingface/hub": "^2.13.0",
         "dotenv": "^17.4.2",
         "express": "^4.19.2"
       },
@@ -748,6 +749,47 @@
         "node": ">=18"
       }
     },
+    "node_modules/@huggingface/blake3-jit": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/@huggingface/blake3-jit/-/blake3-jit-0.0.2.tgz",
+      "integrity": "sha512-Bq7B5qabyjrJfhBsl85Jd2QBtf+HzRD7h7A9GfN2lzrrsABhOa5evVPgzoCTxR7Ub0QFj7YDK1YkYRWBU25+2w==",
+      "license": "MIT"
+    },
+    "node_modules/@huggingface/hub": {
+      "version": "2.13.0",
+      "resolved": "https://registry.npmjs.org/@huggingface/hub/-/hub-2.13.0.tgz",
+      "integrity": "sha512-IAoqdpTV9HeMyooxKVvVGWirOJ+S2IAKnU2FSQSMz62ehPTKzxADAATy1fwAlYYQdHCV119GHFf4p9+ECQ+I5g==",
+      "license": "MIT",
+      "dependencies": {
+        "@huggingface/tasks": "^0.21.1",
+        "@huggingface/xetchunk-wasm": "^0.0.6"
+      },
+      "bin": {
+        "hfjs": "dist/cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "cli-progress": "^3.12.0"
+      }
+    },
+    "node_modules/@huggingface/tasks": {
+      "version": "0.21.1",
+      "resolved": "https://registry.npmjs.org/@huggingface/tasks/-/tasks-0.21.1.tgz",
+      "integrity": "sha512-EGy9VE8h9d39JgyKY5+Nwl0mcGQOK3el8rlR9Y09KVCZOHsLHAsOP1e7D9M7P781dSObZW9lokdfT+Sm26Iv3g==",
+      "license": "MIT"
+    },
+    "node_modules/@huggingface/xetchunk-wasm": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/@huggingface/xetchunk-wasm/-/xetchunk-wasm-0.0.6.tgz",
+      "integrity": "sha512-LoYPl7jvUvOnkysrhMjAeBzK5mVe2GFu8O3IsZb1w7l7v+NqjDsyRduwct3yraPAGmzTxxdb/2aIORL98Y949g==",
+      "license": "MIT",
+      "dependencies": {
+        "@huggingface/blake3-jit": "0.0.2",
+        "gearhash-jit": "1.0.2"
+      }
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -1284,7 +1326,7 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
       "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -1487,6 +1529,19 @@
         "node": ">=8"
       }
     },
+    "node_modules/cli-progress": {
+      "version": "3.12.0",
+      "resolved": "https://registry.npmjs.org/cli-progress/-/cli-progress-3.12.0.tgz",
+      "integrity": "sha512-tRkV3HJ1ASwm19THiiLIXLO7Im7wlTuKnvkYaTkyoAPefqjNg7W7DHKUlGRxy9vxDvbyCYQkQozvptuMkGCg8A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^4.2.3"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/cliui": {
       "version": "8.0.1",
       "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
@@ -1670,7 +1725,7 @@
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
       "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/encodeurl": {
@@ -1933,6 +1988,12 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/gearhash-jit": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/gearhash-jit/-/gearhash-jit-1.0.2.tgz",
+      "integrity": "sha512-UhzJL4KXSdqAKepy/tZwmi2Rcy0YMmtiC4DQS4SURCuIWdh8ECZtnXK2ePRMLigfB61hRKdLK/Vgg2bSw73izQ==",
+      "license": "MIT"
+    },
     "node_modules/gensync": {
       "version": "1.0.0-beta.2",
       "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
@@ -2087,7 +2148,7 @@
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
       "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "engines": {
         "node": ">=8"
@@ -2708,7 +2769,7 @@
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
       "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "emoji-regex": "^8.0.0",
@@ -2723,7 +2784,7 @@
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
       "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "ansi-regex": "^5.0.1"

package.json

@@ -9,6 +9,7 @@
     "start": "NODE_ENV=production node server/index.js"
   },
   "dependencies": {
+    "@huggingface/hub": "^2.13.0",
     "dotenv": "^17.4.2",
     "express": "^4.19.2"
   },

server/index.js

@@ -3,6 +3,7 @@ import "dotenv/config";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { downloadFile, uploadFile } from "@huggingface/hub";
 
 const DUPR_SEARCH_URL = "https://api.dupr.gg/player/v1.0/search";
 const DUPR_PLAYER_URL = "https://api.dupr.gg/player/v1.0";
@@ -11,6 +12,9 @@ const DEFAULT_LAT = 24.453884;
 const DEFAULT_LNG = 54.3773438;
 const EXPLORER_URL_PATTERN =
   process.env.DUPR_EXPLORER_URL_PATTERN || "https://duprexplorer.com/player/{numericPlayerId}";
+const HF_DATASET_REPO = process.env.HF_DATASET_REPO || "derek-thomas/dupr_explorer_may_2026";
+const HF_CACHE_PATH = process.env.HF_CACHE_PATH || "player-cache.json";
+const HF_TOKEN = process.env.HF_TOKEN || process.env.HUGGINGFACE_HUB_TOKEN;
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -19,6 +23,13 @@ const distPath = path.resolve(rootPath, "dist");
 const rosterPath = path.resolve(rootPath, "dupr_players.csv");
 const cacheDir = path.resolve(rootPath, ".cache");
 const cachePath = path.resolve(cacheDir, "player-cache.json");
+let hydrateCachePromise = null;
+let lastCacheBackup = {
+  status: HF_TOKEN ? "pending" : "disabled",
+  message: HF_TOKEN ? "Waiting for cache changes." : "Set HF_TOKEN to enable Hugging Face dataset backup.",
+  fetchedAt: null,
+  pushedAt: null
+};
 
 const app = express();
 
@@ -265,7 +276,78 @@ async function fetchMatchInfo(numericPlayerId) {
   };
 }
 
+function getHfRepo() {
+  return {
+    type: "dataset",
+    name: HF_DATASET_REPO
+  };
+}
+
+function updateCacheBackupStatus(status, message, extra = {}) {
+  lastCacheBackup = {
+    ...lastCacheBackup,
+    status,
+    message,
+    ...extra
+  };
+}
+
+async function hydrateCacheFromDataset() {
+  if (!HF_TOKEN) {
+    return;
+  }
+
+  try {
+    await fs.access(cachePath);
+    updateCacheBackupStatus("local", "Using local cache; dataset backup is available for future writes.");
+    return;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  try {
+    const remoteFile = await downloadFile({
+      repo: getHfRepo(),
+      path: HF_CACHE_PATH,
+      accessToken: HF_TOKEN
+    });
+
+    if (!remoteFile) {
+      updateCacheBackupStatus("empty", `No cache backup found in ${HF_DATASET_REPO}/${HF_CACHE_PATH}.`);
+      return;
+    }
+
+    const text = await remoteFile.text();
+    const parsed = JSON.parse(text);
+
+    if (!parsed.players || typeof parsed.players !== "object") {
+      throw new Error("Remote cache backup does not contain a players object.");
+    }
+
+    await fs.mkdir(cacheDir, { recursive: true });
+    await fs.writeFile(cachePath, text.endsWith("\n") ? text : `${text}\n`);
+    updateCacheBackupStatus("hydrated", `Hydrated cache from ${HF_DATASET_REPO}/${HF_CACHE_PATH}.`, {
+      fetchedAt: new Date().toISOString()
+    });
+  } catch (error) {
+    console.error("Could not hydrate cache from Hugging Face dataset.", error);
+    updateCacheBackupStatus(
+      "hydrate_failed",
+      "Could not hydrate cache from the Hugging Face dataset; using local cache only."
+    );
+  }
+}
+
+async function ensureCacheHydrated() {
+  hydrateCachePromise ??= hydrateCacheFromDataset();
+  await hydrateCachePromise;
+}
+
 async function readCache() {
+  await ensureCacheHydrated();
+
   try {
     const text = await fs.readFile(cachePath, "utf8");
     const parsed = JSON.parse(text);
@@ -284,7 +366,33 @@ async function readCache() {
 
 async function writeCache(cache) {
   await fs.mkdir(cacheDir, { recursive: true });
-  await fs.writeFile(cachePath, `${JSON.stringify(cache, null, 2)}\n`);
+  const serialized = `${JSON.stringify(cache, null, 2)}\n`;
+  await fs.writeFile(cachePath, serialized);
+
+  if (!HF_TOKEN) {
+    return;
+  }
+
+  try {
+    await uploadFile({
+      repo: getHfRepo(),
+      file: {
+        path: HF_CACHE_PATH,
+        content: new Blob([serialized], { type: "application/json" })
+      },
+      accessToken: HF_TOKEN,
+      commitTitle: "Update DUPR player cache backup"
+    });
+    updateCacheBackupStatus("pushed", `Backed up cache to ${HF_DATASET_REPO}/${HF_CACHE_PATH}.`, {
+      pushedAt: new Date().toISOString()
+    });
+  } catch (error) {
+    console.error("Could not back up cache to Hugging Face dataset.", error);
+    updateCacheBackupStatus(
+      "push_failed",
+      "Could not back up cache to the Hugging Face dataset; local cache was still written."
+    );
+  }
 }
 
 function walkJson(value) {
@@ -545,7 +653,12 @@ async function readRoster() {
     },
     cache: {
       cachedPlayers: attemptedPlayers.length,
-      explorerUrlPattern: EXPLORER_URL_PATTERN
+      explorerUrlPattern: EXPLORER_URL_PATTERN,
+      backup: {
+        repo: HF_DATASET_REPO,
+        path: HF_CACHE_PATH,
+        ...lastCacheBackup
+      }
     }
   };
 }
@@ -590,10 +703,20 @@ async function refreshPlayer(duprId) {
     await writeCache(cache);
     return entry;
   } catch (error) {
+    const existingEntry = cache.players[normalizedDuprId];
+    const errorCode = error?.body?.errorCode || error?.errorCode || "refresh_failed";
+
+    if (
+      existingEntry?.status === "success" &&
+      ["invalid_token", "rate_limited", "network_error", "dupr_api_error"].includes(errorCode)
+    ) {
+      return existingEntry;
+    }
+
     const entry = {
       status: "error",
       fetchedAt: new Date().toISOString(),
-      errorCode: error?.body?.errorCode || error?.errorCode || "refresh_failed",
+      errorCode,
       message: error?.body?.message || error?.message || "Could not refresh this player.",
       matchedPlayer: error?.body?.matchedPlayer ?? null,
       raw: error?.body?.raw ?? null
@@ -611,7 +734,8 @@ app.get("/api/health", (_req, res) => {
 app.get("/api/roster", async (_req, res) => {
   try {
     res.json(await readRoster());
-  } catch {
+  } catch (error) {
+    console.error("Could not read roster CSV.", error);
     res.status(500).json({
       ok: false,
       errorCode: "roster_read_failed",
@@ -634,7 +758,12 @@ app.get("/api/cache", async (_req, res) => {
             message: entry.message ?? null
           }
         ])
-      )
+      ),
+      backup: {
+        repo: HF_DATASET_REPO,
+        path: HF_CACHE_PATH,
+        ...lastCacheBackup
+      }
     });
   } catch {
     res.status(500).json({

spec.md

@@ -80,7 +80,7 @@ Required detail behavior:
 
 ### `GET /api/roster`
 
-Reads `dupr_players.csv`, joins cached DUPR enrichment from `.cache/player-cache.json`, and returns teams plus aggregate stats.
+Reads `dupr_players.csv`, joins cached DUPR enrichment from `.cache/player-cache.json`, and returns teams plus aggregate stats. If the local cache is missing and `HF_TOKEN` is configured, the server first attempts to hydrate the cache from the Hugging Face dataset backup.
 
 The response includes:
 
@@ -100,7 +100,12 @@ The response includes:
   },
   "cache": {
     "cachedPlayers": 0,
-    "explorerUrlPattern": "https://duprexplorer.com/player/{numericPlayerId}"
+    "explorerUrlPattern": "https://duprexplorer.com/player/{numericPlayerId}",
+    "backup": {
+      "repo": "derek-thomas/dupr_explorer_may_2026",
+      "path": "player-cache.json",
+      "status": "pushed"
+    }
   }
 }
 ```
@@ -108,6 +113,7 @@ The response includes:
 ### `POST /api/players/refresh`
 
 Refreshes missing, failed, or incomplete player cache entries. By default it skips successful cached players that already have match information.
+Successful existing entries are preserved if a refresh fails because the DUPR token is invalid, DUPR is rate-limited, or the network/upstream API is unavailable.
 
 Request body: