0xDocs 0x.limo

Docs / JavaScript SDK

@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

ts
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

text
asset-manifest.mjs --root <site dir> [--policy <file>] [--verify | --verify-only]
FlagMeaning
--rootthe site directory (required)
--policythe policy JSON (default <root>/swarm-assets.json; nothing is taken without one)
--verifyafterwards, re-hash every entry's file, torrent and stored copy; exit 1 on any mismatch
--verify-onlythe 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)

ts
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:

OptionDefaultMeaning
trackerUrlsrequiredtracker WebSocket URLs
originBaserequiredthe origin base URL (web seed and fallback)
swarmTimeoutMslongest swarm attempt for a tile
manifestfetchedpreload the manifest (works with the origin unreachable)
rtcConfigRTCConfiguration (STUN/TURN, iceTransportPolicy)
uploadLimit, perPeerUploadCap, maxSeeding, webseedDelayMs, maxConns, fetchNumwantswarm limits
assetNoPeerMs2000site files: wait for a peer before a plain fetch when seeds are unknown
assetMaxMs15000site files: longest projected peer download before a plain fetch
assetMinBps262144slowest peer rate (bytes/s) still worth waiting for
assetPeerWaitMs10000site 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, breakerCooldownMs3, 60000circuit breaker
cachea TileCache; revisits are served from it, and the reseedMax most recent entries are seeded again
reseedMax, reseedDelayMs200, 3000re-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

ts
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 memory

The 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

ts
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

ToolPurpose
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.mjsvoxel-world tiles and the browser/native bridge

0x dev starts the tracker and a seeder for your site on localhost.