0xDocs 0x.limo

Docs / JavaScript SDK

@0xlimo/swarm-sw reference

Every file, export, option, URL parameter and message of the 0x swarm service worker runtime, @0xlimo/swarm-sw 0.1.8 (runtime 0.2.6).

The package has no typings. Its files are loaded by URL from the site. This page describes src/ of @0xlimo/swarm-sw 0.1.8, whose runtime version (boot.js RUNTIME, the ?v= of the runtime's files) is 0.2.6. Items marked 0.1.9+, 0.2.x and so on are not in older runtimes. The 0x hosting builder installs runtime 0.1.4, and the published 0x CLI (0.1.7) installs 0.1.3; see Versions. Package exports: @0xlimo/swarm-sw/boot.js, @0xlimo/swarm-sw/host.js and @0xlimo/swarm-sw/x1-sw.js. src/starter.js ships in the package but is not exported.

#Site files

Site pathSourceKind
x1-sw.jssrc/x1-sw.jsclassic service worker script (no imports)
x1/boot.jssrc/boot.jsES module, the page's entry point
x1/host.jssrc/host.jsES module, the swarm host (imported by boot)
x1/privacy.jssrc/privacy.jsES module, the sharing mode
x1/meshtorrent.mjs@x1/meshtorrent dist-browser/meshtorrent.mjsES module, the WebRTC client
x1/starter.jssrc/starter.jsES module, starter packs (0.1.9+). 0x publish doesn't copy it: copy it yourself to use starter packs.

boot.js fetches the runtime files with ?v=0.2.6, so a cache in front of the site answers with this runtime's copy. The worker rewrites a request for x1/*.js or x1/*.mjs that has no query string to its own RUNTIME. In 0.1.8 that constant still says 0.1.8.

Mount pieces from other players need a meshtorrent.mjs whose client has fetchRanges. The @x1/meshtorrent 0.2.1 on the registry doesn't have it. With that client, mount pieces come from the mirror or the origin.

#x1/boot.js

html
<script type="module" src="./x1/boot.js"
        data-entry="./main.js"
        data-tracker="wss://…/p2p/tracker"
        data-manifest="swarm/manifest.json"
        data-timeout="20000"
        data-manual></script>
AttributeMeaning
data-entryyour module, imported after boot (relative to the page)
data-trackeroverrides x1.json tracker
data-manifestoverrides x1.json manifest (relative to the site root)
data-timeoutoverrides x1.json timeoutMs
data-manual0.1.9+: don't import data-entry until the page calls window.x1start() (a Play button). window.__wantStart = true, set before boot gets there, starts it at once.

x1.json keys read by boot: tracker, manifest, timeoutMs, swarm, reports, site, readahead (0.2.0+, only true turns it on) and mirror (0.2.3+, only an https:// URL; trailing / removed). See Mounts, mirror and readahead.

Boot order: register the worker, wait for it to control the page, import x1/host.js, open a starter pack (?starter=<url>, else the stored one) from x1/starter.js if that file exists, then startSwarmHost({…, localPack}).

The whole boot has 5000 ms. Any failure is logged as 0x swarm: <reason> - files load from the origin.

URL parameters: ?x1=off skips the worker and the swarm. ?starter=<url> (0.1.9+) reads a starter pack from that URL for this load. ?p2p=relay and ?p2p=0 are described under x1/privacy.js.

#window.x1swarm

MemberType
status{sw: boolean, host: boolean, error: string}
stats()Promise<{status, sw: object | null, host: object | null, starter}>
starter0.1.9+: {name, bytes, files} of the open starter pack, or null
starterPending0.1.9+: set when the stored pack needs a read grant: {name, grant(): Promise}. Call grant() from a user gesture, then reload.
takeTransfers()Promise<Array<{id: string, webtorrent?: number, origin?: number, up?: number}>>: the bytes moved since the last call, per file hash

#x1/host.js

ts
startSwarmHost(o: {
  tracker: string;          // ws(s) URL of the tracker; /health, /ice, /seeds are beside it
  manifestUrl: string;      // the swarm manifest (version 1)
  meshtorrentUrl: string;   // URL of meshtorrent.mjs
  cache?: boolean;          // default true: OPFS/IndexedDB tile cache, 512 MiB
  log?: boolean;
  localPack?: object;       // 0.1.9+: an opened starter pack (starter.js openStarterPack)
}): Promise<{
  stats(): object; takeUploads(): Array<{ id: string; up: number }>; client: object;
  swarmKey(): Promise<{ pub: string } | null>; useKey(kid: string): void; takeReceipts(): Promise<Array<{ r; s }>>;
}>
  • It throws when the sharing mode is off, when the tracker's /health does not answer in 3 s, or when the manifest is not a meshtorrent manifest (version !== 1).
  • It asks /ice for STUN and TURN servers and uses the browser's defaults when that fails.
  • Swarm limits: uploadLimit 2 MiB/s, perPeerUploadCap 128 MiB, maxSeeding 400, maxConns 24 and fetchNumwant 12 (0.1.9+, before that 8 and 3).
  • With localPack, the reads the pack covers are answered from disk (source "disk"), before the swarm: whole manifest files the pack holds completely, covered mount pieces, and whole mounted files the shards don't list (x1-local). A miss or a failed hash falls through.
  • 0.1.9+: tracker reports. Every 30 s, 5 s after start, and on pagehide (by sendBeacon), it POSTs cumulative counters to <tracker http base>/report as text/plain JSON: {sid, peerBytes, webseedBytes, originBytes, tilesSwarm, tilesWebseed, tilesOrigin, tilesCache, cacheBytes, directConns, relayConns, unknownConns, uploadedBytes, swarmFailures, integrityFailures, breakerTrips, manifestMismatches, verified, peerCapHits, reseeded}. sid is random per page. The byte and file counts come from the worker (x1-take-counts, every 10 s), and the rest from the swarm client.

#x1/privacy.js

ts
sharingMode(loc?: Location): "relay" | "off" | "on"
rtcConfigFor(mode: string, iceServers?: RTCIceServer[]): RTCConfiguration   // relay -> iceTransportPolicy: "relay"

The value comes from ?p2p= (relay, or 0 / off; any other value means on). It is kept in sessionStorage under x1-p2p. In relay mode it sets the cookie x1_private=1; Path=/; Secure; SameSite=None; Partitioned; Max-Age=43200; in the other modes it clears it.

#x1-sw.js

Registered by boot as x1-sw.js?manifest=<url>&timeout=<ms>[&readahead=1][&mirror=<url>]&v=<runtime>, with the site root as its scope. The worker also reads pieceTimeout (ms, default 400) and wholeWindow (pieces, default 8) from its URL. Boot never sets them.

BehaviourValue
HandlesGET, not navigations, for URLs on the site's origin under the manifest root whose key is in manifest.entries, or (0.1.9+) under a manifest.mounts prefix (case-insensitive)
Manifest refreshevery 60 s (MANIFEST_TTL_MS)
Host timeouttimeout parameter, default 20000 ms. 0.1.9+: for a whole file, the longer of that and its size at 256 KiB/s plus 5 s.
Memo64 MiB of recent whole files and mount pieces (for Range requests)
Order for a manifest filememo, then the mirror if the file is 16 MiB or more (0.2.6), then the page's swarm, then the mirror (0.2.5), then the origin
Order for a mount piecememo, then the page (its cache, a starter pack, peers: 400 ms), then the mirror (0.2.3), then the origin, one Range per run of missing pieces. See mounts.
MirrorGET <mirror>/file/<infoHash> (Range for pieces), timeout max(30 s, bytes/1000 ms). Off for 60 s after any failure. Whole files are SHA-256 checked before answering, and pieces after.
Readaheadwith readahead=1: after a ranged mount read, the next 6 pieces of that file are fetched into the memo
Responses200, 206 for a single Range, 416 for an unsatisfiable one; headers Content-Type (by extension), Accept-Ranges: bytes, X-X1-Source: swarm (mounts: swarm, origin or mixed, plus X-X1-Pieces: memo=…,cache=…,swarm=…,origin=…), Cross-Origin-Embedder-Policy: credentialless, Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Resource-Policy: cross-origin
Fallbackthe origin fetch of the same request; the bytes are handed to a hosting page to seed when they match the entry
LifecycleskipWaiting() on install, clients.claim() on activate

#Messages (page → worker)

tPayloadReply (on ports[0])
x1-host0.1.9+: seeds (the tracker's same-origin /seeds URL), kept (up to 8192 tile ids the page keeps), localPack (boolean){ok: true}; the page now hosts the swarm
x1-unhost
x1-statsthe worker's counters plus {hosts, hostHasPack, manifestEntries, mounts} (mount prefixes)
x1-take-counts0.1.9+: the byte and file counters for the tracker report since the last take
x1-xfer{items: [{id, webtorrent?, origin?}]}, taken since the last call
x1-reportreport: {url, site, session, seq}, uploadsthe worker posts the transfer report to report.url

#Messages (worker → page)

tPayloadReply (on ports[0])
x1-getkey, url, entry{ok, bytes, source: "swarm" | "cache" | "disk", stats} or {ok: false, why}
x1-pieces0.1.9+: key, url, fileId, pieces: [{i, tileId, infoHash, size, packRange, pack?, packTileId?, packSize?, seeds}], noPeerMs, maxMsone message per piece, {i, ok, bytes, source, stats} or {i, ok: false, why}, then {done: true}
x1-local0.1.9+: key, url{ok, bytes} of a whole file from the starter pack, or {ok: false, why}
x1-adoptkey, url, entry, bytes (and fileId for a piece)none: the page keeps and seeds the bytes

#Messages (page → launcher)

{x1: "transfers", v: 1, items} goes to the launcher's origin every 30 s and on pagehide, when the page runs inside the launcher.

#The manifest

swarm/manifest.json is built by @x1/meshtorrent's asset manifest builder: {version: 1, entries: {"/<site path>": {tileId, infoHash, size}}}. tileId is the file's SHA-256. Beside it are swarm/t/<infoHash>.torrent (metadata bootstrap) and swarm/content/<id>, <id>.info (the content-addressed store that native clients use). See @x1/meshtorrent.

0.1.9+: a site published with mounts also has mounts: [{prefix, base, pieceLen, pagePieces, buckets, files, pieces, bytes, packs}] beside entries, with its shards under swarm/x/<name>/ and a pack torrent per mounted file in swarm/t/. See What a mount writes.