@x1/meshtorrent reference
The developer-facing modules, options and tools of @x1/meshtorrent 0.2.0, covering the asset manifest, the browser client, the tile cache and the manifest format.
This page covers version 0.2.0 as published. The typings are in the package
(dist/src/*.d.ts), but package.json does not point to them, so import by path. This page
lists the parts a game developer uses. The tracker and seeder exist for 0x dev and the
hosting service.
#dist/src/asset-manifest.js
interface AssetPolicy {
include: string[]; // globs relative to the site root: ** any depth, * within a name
exclude?: string[];
minBytes?: number; // default 16384 (16 KiB)
maxBytes?: number; // default 268435456 (256 MiB)
}
interface AssetManifestResult {
manifest: Manifest; files: number; bytes: number;
skippedSmall: number; skippedLarge: number;
torrentsWritten: number; torrentsPruned: number;
sgWritten: number; sgPruned: number; manifestChanged?: boolean;
}
interface AssetVerifyResult { entries: number; ok: number; mismatched: string[]; missing: string[]; bad: string[] }
const SWARM_DIR = "swarm", TORRENT_DIR = "t", CONTENT_DIR = "content";
function globRe(glob: string): RegExp;
function parsePolicy(text: string): AssetPolicy;
function buildAssetManifest(root: string, policy: AssetPolicy): Promise<AssetManifestResult>; // no writes
function writeAssetManifest(root: string, policy: AssetPolicy): Promise<AssetManifestResult>;
function verifyAssetManifest(root: string): Promise<AssetVerifyResult>;Keys are site paths (/registry/blocks.json). tileId is the file's SHA-256, and infoHash is
the deterministic torrent of the bytes named <tileId><ext>, with a 256 KiB piece length
(TILE_PIECE_LENGTH = 262144).
#bin/asset-manifest.mjs
asset-manifest.mjs --root <site dir> [--policy <file>] [--verify | --verify-only]| Flag | Meaning |
|---|---|
--root | the site directory (required) |
--policy | the policy JSON (default <root>/swarm-assets.json; nothing is taken without one) |
--verify | afterwards, re-hash every entry's file, torrent and stored copy; exit 1 on any mismatch |
--verify-only | the check alone, writing nothing |
Exit codes: 0 ok, 1 verify failed, 2 usage or policy error.
#Browser client: dist/src/client.js (also in the browser bundle)
function initClient(o: ClientOpts): MeshClient;
interface MeshClient {
fetchEntry(entry: { tileId: string; infoHash: string; size: number }, httpUrl: string, torrentUrl: string,
o?: { maxProjectedMs?: number }): Promise<FetchFileResult>;
fetchFile(key: string, httpUrl: string, expectedTileId?: string): Promise<FetchFileResult>;
adoptEntry(entry: { tileId: string; infoHash: string; size: number }, bytes: Uint8Array, httpUrl: string): Promise<boolean>;
fetchChunk(params: FetchChunkParams): Promise<ChunkResult>; // voxel world tiles (VXCH)
stats(): ClientStats;
}
interface FetchFileResult {
bytes: Uint8Array;
source: "cache" | "swarm" | "webseed" | "origin";
stats: { peerBytes: number; webseedBytes: number; originBytes: number };
}ClientOpts:
| Option | Default | Meaning |
|---|---|---|
trackerUrls | required | tracker WebSocket URLs |
originBase | required | the origin base URL (web seed and fallback) |
swarmTimeoutMs | longest swarm attempt for a tile | |
manifest | fetched | preload the manifest (works with the origin unreachable) |
rtcConfig | RTCConfiguration (STUN/TURN, iceTransportPolicy) | |
uploadLimit, perPeerUploadCap, maxSeeding, webseedDelayMs, maxConns, fetchNumwant | swarm limits | |
assetNoPeerMs | 2000 | site files: wait for a peer before a plain fetch when seeds are unknown |
assetMaxMs | 15000 | site files: longest projected peer download before a plain fetch |
assetMinBps | 262144 | slowest peer rate (bytes/s) still worth waiting for |
assetPeerWaitMs | 10000 | site files: wait for a peer when the tracker says somebody holds it |
seedsOf(infoHash) | the tracker's complete-peer count; 0 sends the file straight to a plain fetch | |
breakerFailures, breakerCooldownMs | 3, 60000 | circuit breaker |
cache | a TileCache; revisits are served from it, and the reseedMax most recent entries are seeded again | |
reseedMax, reseedDelayMs | 200, 3000 | re-seeding from the cache |
ClientStats adds to the swarm counters: totalPeerBytes, totalWebseedBytes,
totalOriginBytes, tilesFromSwarm, tilesFromWebseed, tilesFromOrigin, swarmFailures,
breakerTrips, manifestMismatches, tilesFromCache, totalCacheBytes, reseeded, noSeed,
lastSwarmError and cache.
The browser bundle (dist-browser/meshtorrent.mjs) exports initClient, openTileCache and
VERSION. dist-browser/meshtorrent.js sets window.MeshTorrent with the same members.
#Tile cache: dist/src/tile-cache.js
function openTileCache(o?: { budgetBytes?: number; backend?: TileCacheBackend; now?: () => number }): Promise<TileCache>;
interface TileCache {
get(tileId: string): Promise<Uint8Array | null>; // verified; marks it used
put(tileId: string, bytes: Uint8Array, meta: { ext: string; infoHash: string }): Promise<void>;
has(tileId: string): boolean;
entries(): CacheEntry[]; // most recently used first
stats(): TileCacheStats; // {backend, budgetBytes, tiles, bytes, hits, misses, puts, evictions, corrupt}
}
function opfsBackend(dirName?: string): Promise<TileCacheBackend | null>;
function idbBackend(dbName?: string): Promise<TileCacheBackend | null>;
function memoryBackend(): TileCacheBackend;
function defaultBackend(): Promise<TileCacheBackend>; // OPFS, then IndexedDB, then memoryThe default budget is 256 MiB, and never more than half of the origin's storage quota. Hosted
sites use 512 MiB. Eviction is least recently used. A read whose bytes no longer hash to their
id is dropped and counted in corrupt.
#Manifest helpers: dist/src/manifest.js
interface ManifestEntry { tileId: string; infoHash: string; size: number; sg?: SgEntryField } // sg: {piece_len, pieces}
interface Manifest { version: 1; entries: Record<string, ManifestEntry> }
const MANIFEST_VERSION: 1;
function emptyManifest(): Manifest;
function parseManifest(serialized: string | Uint8Array): Manifest;
function serializeManifest(manifest: Manifest): string; // canonical JSON
function lookupKey(manifest: Manifest, key: string): ManifestEntry | null;
function addRawEntry(manifest: Manifest, key: string, entry: ManifestEntry): Manifest;An entry larger than one piece carries sg: {piece_len, pieces}, the per-piece SHA-256 list
that native clients use. One-piece files derive it from tileId.
#Tools used by the CLI and hosting
| Tool | Purpose |
|---|---|
bin/tracker.mjs --config <file> | the tracker: per-origin swarm groups, a manifest allowlist, limits, GET /ice (STUN + TURN), POST /report, GET /stats.json, GET /health |
bin/seeder.mjs (--lod <dir> | --assets <site dir>) --tracker <ws url?group=&seedkey=> [--seedkey-file f] [--ice url] [--upload-limit B/s] [--per-peer-cap B] [--rescan-s 60] [--log-s 60] | an always-on seed for a site's listed files over WebRTC |
bin/lod-manifest.mjs, bin/seed-daemon.mjs, bin/bridge.mjs | voxel-world tiles and the browser/native bridge |
0x dev starts the tracker and a seeder for your site on localhost.
