Skip to content

Latest commit

 

History

History

worker

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 

README.md

JavStore sync worker

A single-user Cloudflare Worker that keeps the userscript's settings and visited history in a Durable Object, so the history survives a userscript-manager reinstall and follows you between devices.

One object, one bearer token. Anyone with that token can read and write the whole history, so treat it like a password.

Why a Durable Object

A Durable Object is single-threaded and strongly consistent, so the read-merge-write each sync performs is serialized: two devices syncing in the same second queue behind one another instead of both merging into the same stale base. Its storage is SQLite, so history is rows rather than one blob, and devices exchange only what changed — an idle page load costs about 150 bytes each way, against roughly 450 KB for a full history under the old whole-document protocol.

Deploy

cd worker
npx wrangler login
openssl rand -base64 32              # your access token — keep a copy
npx wrangler secret put SYNC_TOKEN   # paste the token when prompted
npx wrangler deploy

No namespace to create and nothing to paste into wrangler.toml.

workers_dev = false is set, so the worker has no *.workers.dev URL: those subdomains are guessable, and the history behind this one is worth not advertising. Give it a route on a domain you own instead — uncomment routes in wrangler.toml and point it at a hostname in a zone on the same Cloudflare account:

routes = [
    { pattern = "sync.example.com", custom_domain = true },
]

Deploying with workers_dev = false and no route leaves the worker unreachable. If you would rather use the free subdomain, comment workers_dev out and wrangler deploy prints the URL, e.g. https://javstore-sync.<subdomain>.workers.dev.

Deploy on every push

Workers & Pages → javstore-sync → Settings → Builds → Connect links the worker to this repository, so every push to main deploys it:

Setting Value
Production branch main
Build command (empty — there is nothing to build)
Deploy command npx wrangler deploy
Root directory /worker — wrangler.toml lives here, not at the repository root

The SYNC_TOKEN secret and any route or custom domain stay on the worker, so they survive a rebuild. To confirm a deploy landed, open the userscript's Cloud sync panel and press Sync now: the worker version shown there should match the release.

Point the userscript at it

Open the JVS panel on JavStore → Cloud sync:

  • Worker endpoint — your route, or the URL from wrangler deploy (any path works; /state reads well). Changing the endpoint later is safe: the device notices it is a different worker and re-uploads its history in full.
  • Access token — the token you generated.
  • Tick Sync to my Cloudflare Worker, then Save sync settings.

Repeat on every device with the same URL and token. Each device syncs on load, when its tab regains focus, a few seconds after a visit, on the interval you set, and on Sync now.

Upgrading from the KV version

Uncomment the [[kv_namespaces]] block in wrangler.toml, fill in your old namespace id and deploy. The worker imports that document into the Durable Object on its first request, once. After a sync you can delete the binding and the namespace.

Devices still running 6.2.0 keep working against this worker — it answers the old whole-document protocol as well — and a 6.3.0 device falls back to that protocol if it finds an old worker, so the two can be upgraded in either order.

Settings merge setting by setting on their own timestamps (meta.settingTimes). Settings stored by an earlier worker, or sent by a device older than 6.6.0, count as stamped at their single settingsUpdatedAt. Redeploy the worker when you move to 6.6.0: an older worker still keeps whichever device's settings object is newest as a whole.

API

Every route requires Authorization: Bearer <SYNC_TOKEN>; the path is ignored.

Method Body Answer
GET — { worker, "state": <whole document> }, for backups
POST { cursor, meta, changes[], limit? } { worker, cursor, more, meta, changes[] }
POST { "state": <document> } (6.2.0 clients) { worker, "state": <whole document> }
OPTIONS — CORS preflight

worker is the worker's version (from 6.7.0). The userscript shows it in the Cloud sync panel and flags a worker that is behind it.

A delta POST hands over the entries the device has touched since its last push and asks for everything recorded after cursor. Entries are last-writer-wins on their own event timestamp, with a deletion winning a tie. A device that pushes an entry older than the stored one is handed the winner back, so it cannot stay wrong about it.

Visited history is append-only: the worker ignores a device's visit deletions and its resetAt and prunedBefore horizons (from 6.10.0), and always reports both horizons as 0. Clearing history, retention pruning, unmarking a card and a backup import therefore change only the device they happen on. Per-card override removals still apply.

The object keeps up to 50,000 visited entries, dropping the oldest beyond that (a device keeps its newest 5,000), and expires override tombstones after 90 days.

Notes

  • Costs nothing in practice: a sync is one object request, and idle syncs move a few hundred bytes. SQLite-backed Durable Objects are free-plan eligible — check Cloudflare's current limits if you sync unusually often.
  • Rotating the token: npx wrangler secret put SYNC_TOKEN, then update it in the panel on each device.
  • Backing up the history: curl -H "Authorization: Bearer $TOKEN" https://<your-worker>/state > backup.json. That file is also a valid Import backup file for the panel.