Sync Service

English | 中文

Sync service

The server behind Sync server (database) in cloud sync, deployed on your own Cloudflare account (Workers and a D1 database). The code is in the sync_server/ folder of the repository.

Since 8.2.0, S3, WebDAV and the sync server follow the same rules: one record per item, the later change wins, and deletions (unfavoriting, removing history and so on) reach other devices. They differ in where the data is: the sync server keeps it in a D1 database and each sync transfers only what other devices wrote since the last one; S3 and WebDAV keep it in records/v1/ in the bucket or folder.

Upgrading from 8.1.1 or earlier does not need the server redeployed, but every device needs upgrading, see Cloud sync.

What you need

• Node.js;
• a Cloudflare account (the free plan is enough).

Deployment

Run these commands in the sync_server/ folder.

1. Install the dependencies:

   npm install

2. Log in to Cloudflare (a browser opens):

   npx wrangler login

3. Create the D1 database and note the database_id it prints:

   npx wrangler d1 create gallery-sync

4. Copy the configuration and put the database_id in it (wrangler.toml is not committed):

   cp wrangler.example.toml wrangler.toml

5. Set the token. It is stored as an encrypted variable of the Worker, not in any file; it is what you enter in the app. openssl rand -hex 32 makes one:

   npx wrangler secret put SYNC_TOKEN

6. Deploy. The https://gallery-sync.<subdomain>.workers.dev it prints is the server address:

   npx wrangler deploy

The Worker creates its tables on the first request; there is nothing to set up by hand.

Connecting the app

1. Setting → Advanced → Cloud Sync Settings, turn on Enable Sync.
2. Set Sync Provider to Sync server (database).
3. Fill in Server address (https:// is added when missing) and Token.
4. Tap Test Connection.

Every device chooses the sync server and enters the same address and token. The provider is each device's own choice and is not changed by other devices.

Usage

The free allowances of D1 and Workers are enough for one person. The largest use is the first sync of the first device: one row for each history entry, each reading-progress entry and each favorite. After that, each sync writes only what changed.

Problems

What you see	Cause and what to do
Sync Failed: Sync server (401): Unauthorized	The token differs from the Worker's SYNC_TOKEN.
The Worker answers SYNC_TOKEN is not set for this Worker	Step 5 was skipped, or the deployment went to another Worker.
Sync Failed: The sync server address is not set	The server address is empty.
workers.dev cannot be reached	Some networks block workers.dev. Use a proxy in the app's network settings (sync requests follow the app's proxy), or bind your own domain to the Worker in Cloudflare and enter that domain in the app.
Sync Failed: Sync server: protocol N is not supported	Server and app speak different protocol versions; update both.

Interface

Protocol 1; every request carries Authorization: Bearer <token>:

• GET /v1/info: {"protocol": 1, "database": "<database id>", "seq": <highest sequence>}
• POST /v1/push: an array of records, each with kind, key, value, updatedAt, device, deleted; for the same (kind, key) the larger (updatedAt, device) wins.
• GET /v1/pull?since=<sequence>&device=<device>&limit=<count>: the records other devices wrote after that sequence.

Any server that speaks the same protocol can serve as the sync service.