import { env } from '$env/dynamic/private'; import { parseHfBucketManifest } from './manifest'; import type { HfBucketManifest } from './types'; const DEFAULT_ENDPOINT = 'https://huggingface.co'; const DEFAULT_BUCKET_ID = 'hivetrace/leaderboard_frontend_v2'; const DEFAULT_PREFIX = 'latest'; const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; const DEFAULT_REQUEST_RETRIES = 2; type HfBucketConfig = { token: string; bucketId: string; prefix: string; endpoint: string; requestTimeoutMs: number; requestRetries: number; }; export class HfBucketError extends Error { readonly status?: number; constructor(message: string, options?: { cause?: unknown; status?: number }) { super(message, { cause: options?.cause }); this.name = 'HfBucketError'; this.status = options?.status; } } function positiveInteger(value: string | undefined, fallback: number) { if (!value) return fallback; const parsed = Number(value); return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback; } function nonNegativeInteger(value: string | undefined, fallback: number) { if (!value) return fallback; const parsed = Number(value); return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback; } function normalizePrefix(value: string) { return value .split('/') .map((part) => part.trim()) .filter(Boolean) .join('/'); } function getConfig(): HfBucketConfig { const token = env.HF_TOKEN?.trim(); if (!token) { throw new HfBucketError('HF_TOKEN is not configured on the server.'); } const bucketId = (env.HF_BUCKET_ID ?? DEFAULT_BUCKET_ID).trim(); if (!/^[^/\s]+\/[^/\s]+$/.test(bucketId)) { throw new HfBucketError('HF_BUCKET_ID must use the "namespace/bucket" format.'); } return { token, bucketId, prefix: normalizePrefix(env.HF_BUCKET_PREFIX ?? DEFAULT_PREFIX), endpoint: (env.HF_BUCKET_ENDPOINT ?? DEFAULT_ENDPOINT).replace(/\/+$/, ''), requestTimeoutMs: positiveInteger(env.HF_BUCKET_REQUEST_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS), requestRetries: nonNegativeInteger(env.HF_BUCKET_REQUEST_RETRIES, DEFAULT_REQUEST_RETRIES) }; } function remotePath(prefix: string, path: string) { return [prefix, path].filter(Boolean).join('/').split('/').filter(Boolean).join('/'); } function bucketFileUrl(config: HfBucketConfig, path: string) { const encodedBucketId = config.bucketId.split('/').map(encodeURIComponent).join('/'); const encodedPath = encodeURIComponent(remotePath(config.prefix, path)); return `${config.endpoint}/buckets/${encodedBucketId}/resolve/${encodedPath}`; } function responseErrorMessage(status: number, path: string) { if (status === 401) return `Hugging Face rejected authentication while reading "${path}".`; if (status === 403) return `HF_TOKEN has no permission to read "${path}".`; if (status === 404) return `Bucket file "${path}" was not found.`; return `Hugging Face returned HTTP ${status} while reading "${path}".`; } export async function fetchHfBucketText(path: string): Promise { const config = getConfig(); const maxAttempts = config.requestRetries + 1; for (let attempt = 1; attempt <= maxAttempts; attempt += 1) { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), config.requestTimeoutMs); try { const response = await fetch(bucketFileUrl(config, path), { headers: { Authorization: `Bearer ${config.token}` }, redirect: 'follow', signal: controller.signal }); if (!response.ok) { throw new HfBucketError(responseErrorMessage(response.status, path), { status: response.status }); } return await response.text(); } catch (cause) { if (cause instanceof HfBucketError) throw cause; if (attempt < maxAttempts) continue; if (cause instanceof Error && cause.name === 'AbortError') { throw new HfBucketError( `Timed out after ${config.requestTimeoutMs} ms while reading "${path}" after ${maxAttempts} attempts.`, { cause } ); } throw new HfBucketError(`Failed to read bucket file "${path}".`, { cause }); } finally { clearTimeout(timeout); } } throw new HfBucketError(`Failed to read bucket file "${path}".`); } export async function fetchHfBucketJson(path: string): Promise { const text = await fetchHfBucketText(path); try { return JSON.parse(text) as unknown; } catch (cause) { throw new HfBucketError(`Bucket file "${path}" is not valid JSON.`, { cause }); } } export async function fetchHfBucketManifest(): Promise { const value = await fetchHfBucketJson('manifest.json'); try { return parseHfBucketManifest(value); } catch (cause) { throw new HfBucketError('Bucket manifest failed validation.', { cause }); } }