0xDocs 0x.limo

Docs / JavaScript SDK

@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.

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

WherePackageRuntime (?v=)
npm registry, latest@0xlimo/swarm-sw 0.1.80.2.6
0x hosting's site builder0.1.40.1.4
published 0x CLI (0.1.7), which pins @0xlimo/swarm-sw 0.1.30.1.30.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

  1. The worker (x1-sw.js, scope: the site root) answers GET requests, 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 single Range, keeps the last 64 MiB of whole files in memory for media seeking, and adds X-X1-Source: swarm. Unlisted files pass through untouched.
  2. 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.
  3. 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 than timeoutMs.

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.

json
{
  "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"]
}
FieldMeaning
includeglobs relative to the site root (** any depth, * within a name)
excludeglobs to leave on the origin
minBytessmaller files stay on the origin (default 16384)
maxByteslarger 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:

KeyDefaultMeaning
manifestswarm/manifest.jsonthe swarm manifest
trackerwss://<host><root>p2p/trackerthe meshtorrent tracker
timeoutMs20000longest wait for the swarm before asking the origin
swarmtruefalse: no worker, everything from the origin
reportson 0x hosting: /x1/xferfalse turns transfer reports off; a URL sends them there
sitethe site name the reports carry, when reports is a URL and the page isn't under /sites/<site>/<n>/
apithe platform API URL, read by @0xlimo/platform's siteApi()
mirrornoneruntime 0.2.3+: an https:// mirror the worker asks before the origin; see mirror
readaheadfalseruntime 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 partitioned x1_private=1 cookie tells hosted game servers too.
  • ?p2p=0 or ?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/xfer every minute, and when the page hides, unless sharing is off.

#In the console

window.x1swarm is there for the game and for tests:

js
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 not

The 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 each Range request from the pieces that cover it. See Mounts, mirror and readahead.
  • Mirror tier (x1.json mirror): 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.json readahead): 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 .x1patch updates it with only the changed pieces. data-manual on 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 /report every 30 s and when the page hides. They carry nothing about the player.