SpawnDev.WebTorrent.Server.HuggingFace 3.2.3

SpawnDev.WebTorrent.Server.HuggingFace

Optional HuggingFace CDN proxy extension for SpawnDev.WebTorrent.Server. Fetches model files from HuggingFace's CDN on demand, caches them locally, generates SHA-256 .torrent files, and serves the cached bytes as a BEP 17/19 web seed. Browser clients hold the .torrent in memory and stream pieces from the local cache via WebRTC peers AND the HTTP web seed in the same swarm.

SpawnDev.WebTorrent.Server works without this extension — MapHuggingFaceProxy is opt-in.

Why this exists

AI models are big. CDNs scale poorly when every browser tab independently downloads the same 2 GB safetensors shard. SpawnDev's pattern: one cache server (this proxy) sits in front of HuggingFace, hashes everything once at SHA-256 piece level, and exposes both an HTTP range-request fallback (web seed) and a magnet URI (P2P seed). Every browser that loads the model becomes a peer for the next.

The hub.spawndev.com deployment runs this proxy in production for the SpawnDev model fleet.

Install

<PackageReference Include="SpawnDev.WebTorrent.Server.HuggingFace" Version="3.2.0" />

Pulls in SpawnDev.WebTorrent.Server 3.2.0 + SpawnDev.WebTorrent 3.2.0 transitively.

Quick start

using SpawnDev.WebTorrent.Server.HuggingFace;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var proxy = new HuggingFaceProxy(new HuggingFaceProxyOptions
{
    CacheDirectory = "hf-cache",                  // single dir (or use CacheDirectories for multi)
    TrackerUrls = new[] { "wss://your-tracker.example/announce" },
    MinFreeDiskSpaceBytes = 2L * 1024 * 1024 * 1024, // keep 2 GB headroom (default)
});

app.MapHuggingFaceProxy(proxy);
app.Run();

Endpoints

The extension wires five MapGet routes under your ASP.NET Core app:

Path style mirrors HuggingFace's own URL shape: org/repo/path/to/file.safetensors.

Options (HuggingFaceProxyOptions)

Cache lifecycle

1. Client hits /model/{org}/{repo}/{file} (or /torrent/... / /magnet/...).
2. Proxy checks the cache. Cache hit: returns the .torrent / magnet immediately.
3. Cache miss: proxy starts an async download from HuggingFace's CDN. The first request falls through to the CDN URL (so the client doesn't block); subsequent requests for the same file see the cached bytes.
4. As bytes land on disk, the proxy chunks them into BEP 52 v2 pieces (16 KiB Merkle leaves, SHA-256 piece hashes) and writes a .torrent next to the payload.
5. LRU eviction kicks in when MinFreeDiskSpaceBytes is at risk OR MaxCacheSizeBytes is exceeded.

The HuggingFace hostname (huggingface.co) is a hardcoded upstream — the proxy only fetches from that origin.

Use case: ML model delivery from Blazor

// Server side (this package)
app.MapHuggingFaceProxy(new HuggingFaceProxy(opts));

// Client side (Blazor WASM, using SpawnDev.WebTorrent)
var magnetJson = await Http.GetFromJsonAsync<MagnetResult>(
    $"https://your-server/magnet/Xenova/whisper-tiny/onnx/encoder_model.onnx");
var torrent = await Client.AddAsync(magnetJson!.MagnetUri);
var bytes = await torrent.Files[0].ReadAsync(0, (int)torrent.Files[0].Length);
// Pieces arrive from peers AND from the HTTP web seed (your server) in parallel.

record MagnetResult(string MagnetUri, string RepoId, string FilePath, string WebSeed);

The first browser to load a model fills the cache; every subsequent browser participates in the swarm.

Full end-to-end walkthrough (both sides — including service-worker streaming, status polling, ONNX Runtime integration, and live hub.spawndev.com examples): Docs/huggingface.md in the WebTorrent project.

Production notes

• Disk space. A single browser session loading a 2 GB safetensors shard fills 2 GB of cache. Provision CacheDirectories accordingly; the LRU eviction is the safety net, not the plan.
• CDN bandwidth. HuggingFace serves the first download; every subsequent download comes from your cache + peers in the swarm. Watching /hf-stats shows the win — request count grows but byte count from the upstream stays flat.
• Trackers. Override TrackerUrls to point at your own SpawnDev.RTC-based tracker (deploy via SpawnDev.RTC.ServerApp). Public trackers like wss://tracker.openwebtorrent.com work too but are best-effort.

Dependencies

• SpawnDev.WebTorrent.Server 3.2.0 (web seed server primitives)
• SpawnDev.WebTorrent 3.2.0 (.torrent creation, SHA-256 piece hashing, BEP 52 v2)
• ASP.NET Core 10 (Microsoft.AspNetCore.App framework reference)

License

MIT — see LICENSE.txt in the parent repository.