src/lib/server/hf-bucket/client.ts

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<string> {
	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<unknown> {
	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<HfBucketManifest> {
	const value = await fetchHfBucketJson('manifest.json');
	try {
		return parseHfBucketManifest(value);
	} catch (cause) {
		throw new HfBucketError('Bucket manifest failed validation.', { cause });
	}
}