@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 path | Source | Kind |
|---|---|---|
x1-sw.js | src/x1-sw.js | classic service worker script (no imports) |
x1/boot.js | src/boot.js | ES module, the page's entry point |
x1/host.js | src/host.js | ES module, the swarm host (imported by boot) |
x1/privacy.js | src/privacy.js | ES module, the sharing mode |
x1/meshtorrent.mjs | @x1/meshtorrent dist-browser/meshtorrent.mjs | ES module, the WebRTC client |
x1/starter.js | src/starter.js | ES 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
<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>| Attribute | Meaning |
|---|---|
data-entry | your module, imported after boot (relative to the page) |
data-tracker | overrides x1.json tracker |
data-manifest | overrides x1.json manifest (relative to the site root) |
data-timeout | overrides x1.json timeoutMs |
data-manual | 0.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
| Member | Type |
|---|---|
status | {sw: boolean, host: boolean, error: string} |
stats() | Promise<{status, sw: object | null, host: object | null, starter}> |
starter | 0.1.9+: {name, bytes, files} of the open starter pack, or null |
starterPending | 0.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
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/healthdoes not answer in 3 s, or when the manifest is not a meshtorrent manifest (version !== 1). - It asks
/icefor STUN and TURN servers and uses the browser's defaults when that fails. - Swarm limits:
uploadLimit2 MiB/s,perPeerUploadCap128 MiB,maxSeeding400,maxConns24 andfetchNumwant12 (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(bysendBeacon), it POSTs cumulative counters to<tracker http base>/reportastext/plainJSON:{sid, peerBytes, webseedBytes, originBytes, tilesSwarm, tilesWebseed, tilesOrigin, tilesCache, cacheBytes, directConns, relayConns, unknownConns, uploadedBytes, swarmFailures, integrityFailures, breakerTrips, manifestMismatches, verified, peerCapHits, reseeded}.sidis 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
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.
| Behaviour | Value |
|---|---|
| Handles | GET, 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 refresh | every 60 s (MANIFEST_TTL_MS) |
| Host timeout | timeout 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. |
| Memo | 64 MiB of recent whole files and mount pieces (for Range requests) |
| Order for a manifest file | memo, 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 piece | memo, 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. |
| Mirror | GET <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. |
| Readahead | with readahead=1: after a ranged mount read, the next 6 pieces of that file are fetched into the memo |
| Responses | 200, 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 |
| Fallback | the origin fetch of the same request; the bytes are handed to a hosting page to seed when they match the entry |
| Lifecycle | skipWaiting() on install, clients.claim() on activate |
#Messages (page → worker)
t | Payload | Reply (on ports[0]) |
|---|---|---|
x1-host | 0.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-stats | the worker's counters plus {hosts, hostHasPack, manifestEntries, mounts} (mount prefixes) | |
x1-take-counts | 0.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-report | report: {url, site, session, seq}, uploads | the worker posts the transfer report to report.url |
#Messages (worker → page)
t | Payload | Reply (on ports[0]) |
|---|---|---|
x1-get | key, url, entry | {ok, bytes, source: "swarm" | "cache" | "disk", stats} or {ok: false, why} |
x1-pieces | 0.1.9+: key, url, fileId, pieces: [{i, tileId, infoHash, size, packRange, pack?, packTileId?, packSize?, seeds}], noPeerMs, maxMs | one message per piece, {i, ok, bytes, source, stats} or {i, ok: false, why}, then {done: true} |
x1-local | 0.1.9+: key, url | {ok, bytes} of a whole file from the starter pack, or {ok: false, why} |
x1-adopt | key, 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.
