The server

import { createSyncServer, nodeSqlite, sqliteStore } from 'ferrysync/server';
import { DatabaseSync } from 'node:sqlite';

import { schema } from './schema';

export const syncServer = createSyncServer({
  schema, // the same schema the app imports
  store: sqliteStore(nodeSqlite(new DatabaseSync('sync.db'))),
  auth: async (request) => (await getSession(request))?.userId ?? null,
});

// Hono, Bun, Deno, Workers: any framework with web Request and Response
import { Hono } from 'hono';

import { syncServer } from './sync-server';

const app = new Hono();
app.all('/sync/*', (c) => syncServer.fetch(c.req.raw));

The app points its client at that route, http({ url: 'https://api.example.com/sync' }), and the rest is automatic. See the client's backends.

What it doesCopy Anchor Link

Each device keeps its data on the device and talks to the server in four requests, all POSTs to your route:

On every push, in one database transaction, the server:

1. validates each row with the table's schema;
2. checks the user may write the row's space;
3. runs your hooks: rules that refuse, and writes that follow;
4. appends every change to a log, in one global order.

Pulls read that log from where each device left off, so devices never miss a change and never apply one twice. A rejected write comes back with a code, and the device rolls it back.

OptionsCopy Anchor Link

The server objectCopy Anchor Link

Mount itCopy Anchor Link

AnswersCopy Anchor Link

fetch never throws for a bad request: every failure is an answer, with a JSON body { error: { code, message } }.

toNodeHandler adds one: a request whose Host header is not a valid host gets a 400 invalid_request before it reaches the server.

The client treats every error as temporary and retries with backoff; a 401 also calls its onUnauthorized. One exception: a 413 (too_large, from the server or a proxy) makes it send fewer writes at once, and a single write that is still too large is rejected on the device with the code too_large (see When the server says no), so the writes behind it are not held up.

GotchasCopy Anchor Link

• The route is the whole API. fetch routes by the last path segment, so mount it under any prefix (/sync/*, /api/v1/sync/*) and give the client that prefix as its url.
• One server per process. Create it at module level and share it, like a database client: held requests and realtime live in it.
• It does not do CORS. If the app runs on another origin, answer preflight requests in your framework, and allow the authorization and content-type headers.
• Body limits must agree. A proxy in front of the server (nginx, a load balancer, a platform) has a body limit of its own, and the lowest one wins: nginx's client_max_body_size defaults to 1 MiB, a fifth of maxBodyBytes. A device whose single write is over the proxy's limit drops it as too_large, though the server would have taken it. Set the proxy's limit at or above maxBodyBytes (for example client_max_body_size 5m;), or lower maxBodyBytes to match it.
• Reading is yours. Ferry keeps rows as JSON in tables of its own (ferry_*). To query synced data from the rest of your backend, mirror the tables you need into your own, and read those with your ORM.

Next stepsCopy Anchor Link