@0xlimo/swarm-sw
The service worker and one-line boot script that serve a hosted web game's files from the player swarm, verified by SHA-256, with the origin as a fallback; mounts, a mirror tier, readahead and starter packs in runtime 0.2.x.
Add one line to your index.html, and the game's own loaders get the files that the site's
swarm manifest lists from other players instead of the origin. This works for GLTFLoader,
TextureLoader, Audio, fetch and wasm streaming, with no code change. Every file is checked
against the manifest's SHA-256. Anything the swarm cannot deliver in time comes from the origin,
as it would have without the swarm.
<script type="module" src="./x1/boot.js" data-entry="./main.js"></script>boot.js registers the worker, starts the page's swarm host, and then imports your entry
module, so the first asset request already goes through the swarm. If the browser has no
service workers, or anything fails, boot waits at most 5 s. It then imports the entry anyway,
and the game loads from the origin.
Versions
Not every 0x tool installs the same runtime:
| Where | Package | Runtime (?v=) |
|---|---|---|
npm registry, latest | @0xlimo/swarm-sw 0.1.8 | 0.2.6 |
| 0x hosting's site builder | 0.1.4 | 0.1.4 |
published 0x CLI (0.1.7), which pins @0xlimo/swarm-sw 0.1.3 | 0.1.3 | 0.1.3 |
Everything on this page above Mounts, mirror and starter packs works the same in all three. The features in that section need runtime 0.2.x.
You normally do not install this package. 0x publish (and the hosting service, for uploads
from the browser) copies x1-sw.js, x1/boot.js, x1/host.js, x1/privacy.js and
x1/meshtorrent.mjs into the site. It also writes x1.json and builds swarm/manifest.json
from your swarm policy. Every exported file, option and message is
listed in the reference.
#How it works
- The worker (
x1-sw.js, scope: the site root) answersGETrequests, but not navigations, for files that the manifest lists. It asks a page that hosts the swarm for the bytes, verifies them, and responds. It honours a singleRange, keeps the last 64 MiB of whole files in memory for media seeking, and addsX-X1-Source: swarm. Unlisted files pass through untouched. - The page (
x1/host.js) runs the meshtorrent WebRTC client, because service workers cannot open WebRTC connections. It caches pieces in OPFS or IndexedDB (512 MiB budget) and seeds what it has. The defaults are an upload limit of 2 MiB/s, at most 128 MiB to any one peer, and at most 400 files seeded at once. - The fallback: if no page hosts the swarm, nobody seeds the file, it takes longer than
timeoutMs(20 s), or anything fails, the worker fetches the request from the origin. It then hands the bytes to the page to seed. From runtime 0.1.9 on, a big file gets more time from the swarm: its size at 256 KiB/s plus 5 s, if that is longer thantimeoutMs.
Swarm responses carry the same isolation headers the origin sends
(Cross-Origin-Embedder-Policy: credentialless, Cross-Origin-Opener-Policy: same-origin,
Cross-Origin-Resource-Policy: cross-origin). This keeps a cross-origin-isolated game working
when its files come from peers.
#What goes into the swarm
The policy is swarm-assets.json in your game's directory. Without one, the default applies:
every file of 16 KiB or more, except pages and the runtime.
{
"include": ["**"],
"exclude": ["**/*.html", "**/*.htm", "x1/**", "x1-sw.js", "x1.json", "swarm-assets.json",
"node_modules/**", ".x1/**", "server.mjs", "package.json", "package-lock.json", "0x.config.json"]
}| Field | Meaning |
|---|---|
include | globs relative to the site root (** any depth, * within a name) |
exclude | globs to leave on the origin |
minBytes | smaller files stay on the origin (default 16384) |
maxBytes | larger files stay on the origin (default 256 MiB) |
The hosting builder keeps the swarm-assets.json you upload. A paid game's site is built
origin-only: x1.json is {"swarm": false}, there is no manifest, and nothing is seeded.
#Settings: x1.json
boot.js reads <site>/x1.json, which the builder writes:
| Key | Default | Meaning |
|---|---|---|
manifest | swarm/manifest.json | the swarm manifest |
tracker | wss://<host><root>p2p/tracker | the meshtorrent tracker |
timeoutMs | 20000 | longest wait for the swarm before asking the origin |
swarm | true | false: no worker, everything from the origin |
reports | on 0x hosting: /x1/xfer | false turns transfer reports off; a URL sends them there |
site | the site name the reports carry, when reports is a URL and the page isn't under /sites/<site>/<n>/ | |
api | the platform API URL, read by @0xlimo/platform's siteApi() | |
mirror | none | runtime 0.2.3+: an https:// mirror the worker asks before the origin; see mirror |
readahead | false | runtime 0.2.0+: true warms the next 6 pieces after each ranged read of a mounted file; see readahead |
data-tracker, data-manifest and data-timeout on the script tag override the file.
?x1=off in the page URL skips the swarm entirely. Neither builder writes mirror or
readahead. On a self-hosted site, add them to the published x1.json after each
0x publish --to.
#Player privacy
The launcher passes the player's sharing choice in the URL. privacy.js keeps it for the tab
in sessionStorage:
?p2p=relay(Private): WebRTC only through the 0x TURN relay, so other players never see the player's address. A partitionedx1_private=1cookie tells hosted game servers too.?p2p=0or?p2p=off(Off): no swarm; every file comes from the origin.
#Transfer reports
The worker counts the bytes each listed file took from the swarm and from the origin, and the host counts the bytes this page uploaded. The reports are sums per file hash only: no addresses and no peers.
- Inside the launcher: every 30 s, and when the page hides, they go to the launcher
(
postMessage {x1: "transfers", v: 1, items}). The launcher reports them unless the player turned sharing off. - Opened directly on 0x hosting: the worker posts them to the origin's
/x1/xferevery minute, and when the page hides, unless sharing is off.
#In the console
window.x1swarm is there for the game and for tests:
await x1swarm.stats(); // {status: {sw, host, error}, sw: {...worker counters}, host: {asked, swarm, cache, declined, adopted, peerBytes, client}}
x1swarm.status.error; // why the swarm is not running, if it is notThe development server 0x dev serves the same runtime with a local tracker and seeder; see
the 0x CLI.
#Mounts, mirror and starter packs (runtime 0.2.x)
Runtime 0.2.6 (@0xlimo/swarm-sw 0.1.8) adds these for games with very large data. Today they
are for self-hosted sites only. See the version table above.
- Mounts:
0x publish --to … --mount /data/=<dir>puts an external data tree on the swarm in 1 MiB pieces without copying it into the site. The worker answers eachRangerequest from the pieces that cover it. See Mounts, mirror and readahead. - Mirror tier (
x1.jsonmirror): a fast HTTPS copy of the swarm's files, asked before the origin, and before the swarm for files of 16 MiB or more. - Readahead (
x1.jsonreadahead): sequential reads of a mounted file warm the next 6 MiB. - Starter packs: one file on the player's disk answers the reads it covers, and a
.x1patchupdates it with only the changed pieces.data-manualon the boot tag waits for your Play button. See Starter packs and .x1patch updates. - Tracker reports: the swarm host posts cumulative counters (bytes from peers, origin and
cache, and connection kinds) under a random per-page id to the tracker's
/reportevery 30 s and when the page hides. They carry nothing about the player.
