@cf-sync/client 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/{client-tvsT_ixa.d.ts → client-C488ro1Y.d.ts} +19 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +42 -0
- package/dist/react.d.ts +1 -1
- package/docs/config.json +75 -0
- package/docs/guide/auth.md +135 -0
- package/docs/guide/collaborative-text.md +83 -0
- package/docs/guide/defining-your-app.md +117 -0
- package/docs/guide/getting-started.md +150 -0
- package/docs/guide/limits-and-costs.md +58 -0
- package/docs/guide/mutations.md +112 -0
- package/docs/guide/offline-persistence.md +67 -0
- package/docs/guide/operations.md +97 -0
- package/docs/guide/presence.md +64 -0
- package/docs/guide/reading-data.md +102 -0
- package/docs/guide/schema-evolution.md +91 -0
- package/docs/guide/testing.md +66 -0
- package/docs/guide/troubleshooting.md +68 -0
- package/docs/guide/why.md +54 -0
- package/docs/index.md +38 -0
- package/docs/reference/collections.md +105 -0
- package/docs/reference/define-kit.md +143 -0
- package/docs/reference/index.md +25 -0
- package/docs/reference/server.md +174 -0
- package/docs/reference/sync-client.md +294 -0
- package/docs/reference/testing.md +135 -0
- package/docs/reference/yjs.md +110 -0
- package/package.json +8 -7
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
This walks a fresh project from zero to two browser tabs converging through a Durable Object. Time budget: about ten minutes.
|
|
4
|
+
|
|
5
|
+
::: tip Not published to npm yet
|
|
6
|
+
The `@cf-sync/*` packages are not on the public registry yet. Until they are, the fastest way to try the engine is to clone the [repository](https://github.com/InfinityBowman/cf-sync) and run the [demo app](https://github.com/InfinityBowman/cf-sync/tree/main/apps/demo) (`pnpm dev:worker` + `pnpm dev:web`). The steps below are what a consuming project looks like.
|
|
7
|
+
:::
|
|
8
|
+
|
|
9
|
+
## Prerequisites
|
|
10
|
+
|
|
11
|
+
- A Cloudflare account and [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) (Durable Objects with SQLite are available on the free plan)
|
|
12
|
+
- Node 18+ and a bundler for the web side (examples use Vite)
|
|
13
|
+
|
|
14
|
+
## 1. Install
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm install @cf-sync/protocol @cf-sync/server @cf-sync/client @tanstack/db zod
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`zod` and `@tanstack/db` are peer dependencies. React is optional — the core client is framework-agnostic.
|
|
21
|
+
|
|
22
|
+
## 2. Define the app (shared)
|
|
23
|
+
|
|
24
|
+
One file, imported by **both** the worker and the browser. This is the central idea: the server and every client are configured with the *same value*, so they can't disagree about the schema, the mutators, or the version.
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// src/schema.ts
|
|
28
|
+
import { defineApp, defineSchema, defineMutators, AppError } from '@cf-sync/protocol'
|
|
29
|
+
import { z } from 'zod'
|
|
30
|
+
|
|
31
|
+
const schema = defineSchema({
|
|
32
|
+
todos: z.object({
|
|
33
|
+
id: z.string(),
|
|
34
|
+
title: z.string(),
|
|
35
|
+
done: z.boolean().default(false),
|
|
36
|
+
}),
|
|
37
|
+
})
|
|
38
|
+
|
|
39
|
+
const mutators = defineMutators(schema, {
|
|
40
|
+
'todo.toggle': {
|
|
41
|
+
args: z.object({ id: z.string() }),
|
|
42
|
+
apply: (tx, { id }) => {
|
|
43
|
+
const todo = tx.get('todos', id)
|
|
44
|
+
if (!todo) throw new AppError('NotFound', `todo ${id} does not exist`)
|
|
45
|
+
tx.put('todos', id, { ...todo, done: !todo.done })
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
})
|
|
49
|
+
|
|
50
|
+
export const app = defineApp({ version: 1, schema, mutators })
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
::: tip Wire the schema tripwire now, not when drift first bites
|
|
54
|
+
Every future schema change will require bumping `version` — including additive ones. The one mistake the engine can only warn about after the fact is changing a schema *without* a bump, so add the one-line CI check from the start: a test calling [`checkSchemaEvolution`](/guide/schema-evolution#drift-detection) from `@cf-sync/server/testing` fails the build naming the exact fix.
|
|
55
|
+
:::
|
|
56
|
+
|
|
57
|
+
## 3. The worker
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
// worker/worker.ts
|
|
61
|
+
import { createWorkspaceDO, createSyncFetch } from '@cf-sync/server'
|
|
62
|
+
import { app } from '../src/schema'
|
|
63
|
+
|
|
64
|
+
// A class declaration, not `const`: the name doubles as a TypeScript type,
|
|
65
|
+
// which `wrangler types` needs to generate a typed Env. Keep the body empty —
|
|
66
|
+
// the engine's handlers are not extension points.
|
|
67
|
+
export class WorkspaceDO extends createWorkspaceDO({ app }) {}
|
|
68
|
+
|
|
69
|
+
export default {
|
|
70
|
+
fetch: createSyncFetch<Env>({
|
|
71
|
+
namespace: (env) => env.WORKSPACE,
|
|
72
|
+
authorize: async (request, { workspaceId }) => {
|
|
73
|
+
// Validate the session, check workspace membership.
|
|
74
|
+
// Returning true admits everyone — fine for a first run, not for production.
|
|
75
|
+
return true
|
|
76
|
+
},
|
|
77
|
+
}),
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The `Env` type comes from `npx wrangler types` — run it after saving the wrangler config below and it generates `WORKSPACE: DurableObjectNamespace<WorkspaceDO>` from your bindings (naming that type is why the DO is exported as a class). Prefer hand-writing? `interface Env { WORKSPACE: DurableObjectNamespace<WorkspaceDO> }` works the same.
|
|
82
|
+
|
|
83
|
+
When the worker grows more routes (the [admin surface](/guide/operations), your own endpoints), switch to the composable form: `createSyncRoute`/`createAdminRoute` resolve to `null` for traffic that isn't theirs and chain with `??` — no hand-routing on `pathname`.
|
|
84
|
+
|
|
85
|
+
```jsonc
|
|
86
|
+
// wrangler.jsonc
|
|
87
|
+
{
|
|
88
|
+
"name": "my-sync-worker",
|
|
89
|
+
"main": "./worker/worker.ts",
|
|
90
|
+
"compatibility_date": "2025-08-01",
|
|
91
|
+
"durable_objects": {
|
|
92
|
+
"bindings": [{ "name": "WORKSPACE", "class_name": "WorkspaceDO" }]
|
|
93
|
+
},
|
|
94
|
+
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["WorkspaceDO"] }]
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
::: warning `new_sqlite_classes`, not `new_classes`
|
|
99
|
+
The workspace DO requires SQLite-backed storage. Declaring it with `new_classes` is the classic footgun — the deploy succeeds, and the DO fails at runtime on its first SQL access. If you've already deployed with `new_classes`, you need a [new class name](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/); the storage backend of an existing class can't be changed.
|
|
100
|
+
:::
|
|
101
|
+
|
|
102
|
+
## 4. The client
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
// src/sync.ts
|
|
106
|
+
import { createWorkspace } from '@cf-sync/client'
|
|
107
|
+
import { app } from './schema'
|
|
108
|
+
|
|
109
|
+
export const { client, collections } = createWorkspace({
|
|
110
|
+
url: 'ws://localhost:8787', // wss://your-worker in production
|
|
111
|
+
workspaceId: 'my-first-workspace',
|
|
112
|
+
app,
|
|
113
|
+
persist: true, // IndexedDB mirror + durable offline outbox
|
|
114
|
+
})
|
|
115
|
+
|
|
116
|
+
// Optimistic local write, synced as a full-row mutation:
|
|
117
|
+
collections.todos.insert({ id: crypto.randomUUID(), title: 'ship it' })
|
|
118
|
+
|
|
119
|
+
// Typed intent mutation — runs instantly locally, authoritatively on the server:
|
|
120
|
+
await client.mutate.todo.toggle({ id })
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The client connects on construction (pass `autoStart: false` to decouple that — SSR, auth gating), appends `/sync/<workspaceId>?clientId=…` to your URL, and manages the clientId lifecycle for you. `createWorkspace` returns one typed collection per schema table — row types, runtime validation, and keys all derive from the schema — plus the client and a single `destroy` that tears everything down (the unit to rebuild when [switching workspaces](/guide/offline-persistence#closing-a-workspace)). Syncing starts immediately (the socket carries every table's pokes regardless; pass `startSync: false` to defer to first subscriber). For finer control, construct the pieces yourself with `new SyncClient(...)` + `createCollections`/`workspaceCollectionOptions`.
|
|
124
|
+
|
|
125
|
+
In React, read collections with `useLiveQuery` from `@tanstack/react-db` — install it alongside `@cf-sync/client` (it's declared as an optional peer, so your package manager will flag a version pair whose pinned `@tanstack/db` disagrees). Sync state comes from the shipped hooks:
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
import { useSyncStatus } from '@cf-sync/client/react'
|
|
129
|
+
|
|
130
|
+
const status = useSyncStatus(client) // 'idle' | 'connecting' | … | 'synced'
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## 5. Run it
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
npx wrangler dev # the worker + Workspace DO on :8787
|
|
137
|
+
npm run dev # your vite dev server, second terminal
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Open the app in **two tabs**. Mutations apply instantly in the originating tab and propagate to the other through the server. Then try turning the network off in devtools, mutating, and reloading — the mirror hydrates instantly and the outbox replays on reconnect.
|
|
141
|
+
|
|
142
|
+
Each `workspaceId` is its own Durable Object with its own storage and sockets. Switching workspaces is `await ws.destroy()` then `createWorkspace({ ...same, workspaceId: next })` — see [Offline & persistence](/guide/offline-persistence#closing-a-workspace).
|
|
143
|
+
|
|
144
|
+
## Where next
|
|
145
|
+
|
|
146
|
+
- [Defining your app](/guide/defining-your-app) — schemas, mutators, and the two rules that keep optimistic and authoritative runs in agreement
|
|
147
|
+
- [Reading data](/guide/reading-data) — live queries, joins, and derived collections over synced rows
|
|
148
|
+
- [Mutations & optimistic writes](/guide/mutations) — what confirm, reject, and offline actually mean
|
|
149
|
+
- [Auth & sessions](/guide/auth) — a real `authorize` hook, typed auth context in mutators, kick and refresh
|
|
150
|
+
- [Testing your app](/guide/testing) — unit-test mutators and migrations in plain node, no workerd
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Limits & costs
|
|
2
|
+
|
|
3
|
+
Two kinds of numbers live here: the engine's own caps — designed values, enforced with named errors — and the Cloudflare platform's, which cf-sync inherits. Platform pricing is quoted from [Cloudflare's pricing page](https://developers.cloudflare.com/durable-objects/platform/pricing/) as of early 2026 (post the January 2026 SQLite billing change) — verify against the source before capacity planning.
|
|
4
|
+
|
|
5
|
+
## Engine limits
|
|
6
|
+
|
|
7
|
+
| What | Limit | On violation |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Row data (JSON-serialized) | 700,000 bytes | permanent [`RowTooLarge`](/reference/sync-client#mutationerror) rejection |
|
|
10
|
+
| Presence state | 8,192 bytes | error frame — never truncated |
|
|
11
|
+
| Row id | 256 UTF-16 code units | permanent `InvalidArgs` rejection |
|
|
12
|
+
| Table name | identifier-like, ≤ 64 chars | `defineSchema` throws at definition time |
|
|
13
|
+
| Yjs field (total doc) | 700,000 bytes | field freezes — reads fine, writes reject `Frozen` |
|
|
14
|
+
| Yjs field update (one frame) | 200,000 bytes | `TooLarge` reject; the client guard refuses to send first |
|
|
15
|
+
| Yjs field id | 256 UTF-8 bytes | `getDoc` throws |
|
|
16
|
+
| Tombstone retention | 10,000 data versions (configurable) | older offline clients re-bootstrap instead of catching up |
|
|
17
|
+
|
|
18
|
+
The row cap exists so a single row always fits a WebSocket frame with headroom — larger protocol messages are chunked at 900 KB, comfortably under platform frame limits. Rows are for structured state, not payloads: large text belongs in a [Yjs field](/guide/collaborative-text), blobs in R2 with a key in the row ([Troubleshooting](/guide/troubleshooting#a-mutation-rejected-with-rowtoolarge)).
|
|
19
|
+
|
|
20
|
+
Relevant platform ceilings underneath: 10 GB of SQLite per Durable Object (= per workspace), a 2 MB SQLite row cap (the engine's 700 KB sits well under it), and 30s of CPU per request by default. Per-workspace `stats` — row counts and database size — is scrapeable from the [admin surface](/guide/operations#what-to-monitor).
|
|
21
|
+
|
|
22
|
+
## Sizing a workspace
|
|
23
|
+
|
|
24
|
+
A workspace syncs whole to every member — that's the [design](/guide/why#honest-non-goals), and sizing is its one obligation. The practical governor is not the 10 GB storage ceiling but the **bootstrap**: a new client (or one past the tombstone window) downloads every live row. Tens of thousands of rows bootstrap in seconds and hydrate instantly from IndexedDB thereafter; millions of rows in one workspace means you wanted more workspaces (or a different tool — a global feed is not a workspace).
|
|
25
|
+
|
|
26
|
+
Linear's model is the calibration: a workspace is a team's working set, not your whole database. Cross-workspace data lives in your app's own store, with the workspace holding what the team collaborates on live.
|
|
27
|
+
|
|
28
|
+
## What a workspace costs
|
|
29
|
+
|
|
30
|
+
The architecture's cost story is simple: **an idle workspace costs storage and nothing else.** Sockets hibernate — clients stay connected at the edge while the DO is evicted from memory, and duration charges do not accrue during hibernation. The client's keepalive pings are answered by the server's auto-responder without waking the DO. A workspace nobody touches overnight bills zero compute overnight.
|
|
31
|
+
|
|
32
|
+
When it's awake, three meters run (Workers Paid, after included allotments):
|
|
33
|
+
|
|
34
|
+
- **Requests** — $0.15/million past 1M/month. Incoming WebSocket messages bill at a 20:1 ratio (20 messages = 1 request); outbound broadcasts are not billed as requests. Every mutation push and every throttled presence frame is one incoming message.
|
|
35
|
+
- **Duration** — $12.50/million GB-s past 400k GB-s/month, billed at the DO's 128 MB allocation for wall-clock time awake. This is the meter that matters: it runs while the DO is in memory, and hibernation is what stops it.
|
|
36
|
+
- **SQLite** — rows read at $0.001/million past 25 billion/month, rows written at $1.00/million past 50M/month, storage at $0.20/GB-month past 5 GB-months. A mutation writes a handful of rows (data + log + bookkeeping); presence writes none (never stored).
|
|
37
|
+
|
|
38
|
+
Rough arithmetic for feel, not precision: a 10-person workspace whose members send 1,000 messages each per active day (presence dominates, already client-throttled to 10/s max) produces ~10k incoming messages/day → 500 request-equivalents at 20:1 → ~15k/month, or **1.5% of the included million**. If processing keeps the DO awake a generous two hours a day, that's ~27k GB-s/month — **7% of the included 400k**. The included allotments of one $5 Workers Paid plan cover dozens to hundreds of such workspaces; the marginal cost of workspace #200 is its storage.
|
|
39
|
+
|
|
40
|
+
The free plan is genuinely usable for development and small apps: 100k requests/day, 13k GB-s/day, 5M row reads/day, 100k row writes/day, 5 GB storage — with SQLite-backed DOs available without a paid plan.
|
|
41
|
+
|
|
42
|
+
## What keeps the duration meter honest
|
|
43
|
+
|
|
44
|
+
Duration is the one number an app can accidentally inflate, and the engine's defaults exist to protect it:
|
|
45
|
+
|
|
46
|
+
- **Presence throttling** (default 100ms, trailing-edge) bounds the message rate per client no matter how fast the mouse moves — presence is the workload that keeps sockets chatty, so its throttle is effectively a duration-billing control.
|
|
47
|
+
- **Keepalive pings** (default 25s) are answered without waking the DO — liveness costs no duration.
|
|
48
|
+
- **The maintenance alarm** (compaction, R2 export) wakes the DO on its interval — default 6h, or 5min with an [R2 export](/guide/operations#r2-mutation-log-archive) configured. Each wake is brief; an export interval far below the default on thousands of idle workspaces is the one configuration that turns "idle is free" into a steady hum.
|
|
49
|
+
- **All DO handlers are synchronous** by design (an engine invariant) — no awaited I/O stretching awake-time per message.
|
|
50
|
+
|
|
51
|
+
The R2 archive itself bills on [R2's pricing](https://developers.cloudflare.com/r2/pricing/) (storage plus class-A writes, no egress) — at one object per export interval per active workspace, it's noise next to the meters above.
|
|
52
|
+
|
|
53
|
+
## When you outgrow a number
|
|
54
|
+
|
|
55
|
+
- **Row too large** → the data wanted to be a Yjs field or an R2 object; see [Troubleshooting](/guide/troubleshooting#a-mutation-rejected-with-rowtoolarge).
|
|
56
|
+
- **Workspace too large** → split it; workspaces are cheap by construction and the [admin surface](/guide/operations) exports/imports them.
|
|
57
|
+
- **Long-offline clients re-bootstrapping** → raise `compaction.tombstoneRetentionVersions` ([reference](/reference/server#compaction)) and pay storage for the longer catch-up window.
|
|
58
|
+
- **A truly hot workspace** (hundreds of concurrent editors) → it still works — hibernating sockets scale to thousands of clients per DO — but the single-DO-per-workspace serialization point is the design's honest ceiling: one writer, one workspace, by intent.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Mutations & optimistic writes
|
|
2
|
+
|
|
3
|
+
There are two ways to write data, and they end up on the same wire:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
// Collection writes — full-row LWW, emitted as the built-in sync.put / sync.del
|
|
7
|
+
issues.insert({ id: ulid(), title: 'ship it' })
|
|
8
|
+
|
|
9
|
+
// Intent mutations — named mutators from your app definition
|
|
10
|
+
await client.mutate.issue.move({ id, column: 'done' })
|
|
11
|
+
// equivalent string form:
|
|
12
|
+
await client.mutate('issue.move', { id, column: 'done' })
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`mutate` is fully typed from your app definition: names autocomplete, bad args are a compile error.
|
|
16
|
+
|
|
17
|
+
## What "optimistic" means here
|
|
18
|
+
|
|
19
|
+
When you call `mutate`, the shared mutator's `apply` runs **locally first**, against your collections, and all of its writes land as **one atomic overlay**:
|
|
20
|
+
|
|
21
|
+
- Visible instantly — no waiting on the network.
|
|
22
|
+
- Swapped for the server's authoritative patch on confirm.
|
|
23
|
+
- Rolled back **together** if the server rejects.
|
|
24
|
+
|
|
25
|
+
A multi-row intent like `clearCompleted` is one line in the mutator, one wire mutation, one overlay. There is no separate "optimistic effect" to hand-write and keep in sync with the server logic, and no per-row CRUD echo.
|
|
26
|
+
|
|
27
|
+
For this to feel seamless, your mutators must be deterministic and tolerant of lagging local state — the [two authoring rules](/guide/defining-your-app#the-two-authoring-rules).
|
|
28
|
+
|
|
29
|
+
## The one semantic to internalize
|
|
30
|
+
|
|
31
|
+
::: warning A rejection always means the mutation will not apply
|
|
32
|
+
If the promise from `mutate` rejects, that mutation is finished — it has been rolled back locally and will never land on the server. There is no "maybe it went through". Conversely, while the promise is pending with persistence on, the mutation is durably queued and *will* apply when connectivity returns.
|
|
33
|
+
:::
|
|
34
|
+
|
|
35
|
+
What resolution looks like depends on whether the client has a durable store:
|
|
36
|
+
|
|
37
|
+
| | `persist: true` (or a custom store) | memory-only |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| Online, accepted | resolves on server confirm | resolves on server confirm |
|
|
40
|
+
| Online, rejected | rejects with the server's code | rejects with the server's code |
|
|
41
|
+
| Offline | stays **pending** — queued durably, replays exactly once, survives reloads | rejects with `Timeout` after `confirmTimeoutMs` (default 30s) and is discarded |
|
|
42
|
+
|
|
43
|
+
The memory-only timeout is honest: without a store, a queued mutation would not survive a reload anyway, so the client refuses to pretend otherwise.
|
|
44
|
+
|
|
45
|
+
A reload doesn't hide queued work either: at hydration each queued mutation's mutator re-runs locally and its optimistic overlay comes back, so pending edits stay visible until the server settles them. (The `mutate` promise itself doesn't survive the reload — [`onMutationRejected`](#one-handler-instead-of-a-catch-per-call-site) is how a post-reload rejection reaches your app.)
|
|
46
|
+
|
|
47
|
+
Beyond server rejection, a pending mutation can also reject with `Stopped` (`client.destroy()` was called) or `Fatal` (the connection hit a permanent failure — see [Auth & sessions](/guide/auth#close-codes)).
|
|
48
|
+
|
|
49
|
+
## Rejection codes
|
|
50
|
+
|
|
51
|
+
Rejected mutations throw `MutationError`, which carries a typed `code`:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { MutationError } from '@cf-sync/client'
|
|
55
|
+
|
|
56
|
+
try {
|
|
57
|
+
await client.mutate.issue.move({ id, column })
|
|
58
|
+
} catch (e) {
|
|
59
|
+
if (e instanceof MutationError && e.code === 'NotFound') {
|
|
60
|
+
toast('That issue was deleted by someone else.')
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The vocabulary, in three groups:
|
|
66
|
+
|
|
67
|
+
- **Engine rejections** (`EngineErrorCode`) — the server refused before your mutator ran: `InvalidArgs`, `UnknownMutator`, `RowTooLarge`.
|
|
68
|
+
- **Client-local outcomes** — `Timeout`, `Stopped`, `Fatal`, `LocalApplyFailed` (your mutator threw during the optimistic run; nothing was sent).
|
|
69
|
+
- **Your codes** — whatever your mutators throw in an `AppError('YourCode', …)`.
|
|
70
|
+
|
|
71
|
+
The built-in set is exported as `MutationErrorCode`, so branching on codes autocompletes.
|
|
72
|
+
|
|
73
|
+
## One handler instead of a catch per call site
|
|
74
|
+
|
|
75
|
+
Per-call `try`/`catch` is right when the caller can *do* something specific. For everything else — toasting, logging, telemetry — attach `onMutationRejected` once. Two equivalent surfaces: the constructor option, or the subscription method for layers that mount after the client exists (a toast system, an error boundary):
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
const client = new SyncClient({
|
|
79
|
+
// …
|
|
80
|
+
onMutationRejected: (error, { name }) => {
|
|
81
|
+
toast.error(`"${name}" was rejected: ${error.message}`)
|
|
82
|
+
},
|
|
83
|
+
})
|
|
84
|
+
|
|
85
|
+
// …or attach later, with an unsubscribe:
|
|
86
|
+
const unsubscribe = client.onMutationRejected((error, { name }) => {
|
|
87
|
+
toast.error(`"${name}" was rejected: ${error.message}`)
|
|
88
|
+
})
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
It fires for **every** rejection, including the ones that have no awaiting caller and would otherwise roll back invisibly: collection `insert`/`update`/`delete` writes, and offline mutations replayed from the persisted outbox after a reload. (Filter on `error.code` if you only want server verdicts — the lifecycle codes `Stopped`/`Timeout`/`Fatal` arrive here too.)
|
|
92
|
+
|
|
93
|
+
With the handler set, fire-and-forget calls are safe: `void client.mutate.todos.clearCompleted()` needs no `.catch()` — the rejection is considered handled by the hook, while awaiting callers still see it normally.
|
|
94
|
+
|
|
95
|
+
## Permanent vs transient, precisely
|
|
96
|
+
|
|
97
|
+
An `AppError` (or invalid args) is **permanent**: the server records the mutation as processed — its data effects are refused, but the client's `lastMutationId` still advances, in the same SQLite transaction. This is what makes rejection final and the queue unblockable: a poison mutation can't wedge everything behind it.
|
|
98
|
+
|
|
99
|
+
Any other throw in an authoritative run is **transient**: nothing commits, the mutation stays unprocessed, and it is retried on the next connection. Infrastructure blips heal themselves; business-rule violations reject exactly once.
|
|
100
|
+
|
|
101
|
+
## Watching sync state
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
const unsubscribe = client.subscribeStatus((status) => { /* 'idle' | 'connecting' | … | 'synced' */ })
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import { useSyncStatus } from '@cf-sync/client/react'
|
|
109
|
+
const status = useSyncStatus(client)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Status is about the *pipe*, not about individual mutations — individual outcomes arrive through each `mutate` promise.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Offline & persistence
|
|
2
|
+
|
|
3
|
+
One option turns on the whole story:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
const client = new SyncClient({ url, workspaceId, app, persist: true })
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
`persist: true` gives you a durable local mirror in IndexedDB:
|
|
10
|
+
|
|
11
|
+
- **Instant reloads** — the UI hydrates from cache immediately, then resumes from the server *by cursor*: only what changed since the last sync crosses the wire, not a re-bootstrap.
|
|
12
|
+
- **A durable outbox** — mutations made offline survive reloads and replay **exactly once** when connectivity returns. The idempotency contract (per-client `lastMutationId`) makes replay safe: the server skips what it has already processed, no matter how many times a reconnect retries it.
|
|
13
|
+
- **Reloads keep your pending edits visible** — at hydration, each queued mutation's mutator re-runs locally against the cached rows and its optimistic overlay comes back, so what you saw before the reload is what you see after it. The server's verdict still settles each one: a confirm swaps the overlay for the authoritative rows, a rejection rolls it back and reports through [`onMutationRejected`](/guide/mutations#one-handler-instead-of-a-catch-per-call-site).
|
|
14
|
+
- **Honest pending promises** — while offline, `mutate` promises simply stay pending; they resolve when the queued mutation finally confirms. Memory-only clients instead reject with `Timeout` (default 30s), because without a store the mutation wouldn't survive a reload anyway. See [Mutations](/guide/mutations#the-one-semantic-to-internalize).
|
|
15
|
+
|
|
16
|
+
## What's managed for you
|
|
17
|
+
|
|
18
|
+
- **clientId lifecycle** — one per tab/session, minted and persisted automatically. Pass `clientId` explicitly to take it over.
|
|
19
|
+
- **Storage** — `IndexedDBSyncStore` under the hood; pass `store` to substitute your own `SyncStore` implementation (the contract is exported, and `MemorySyncStore` is the reference).
|
|
20
|
+
- **Fatal handling** — a permanent connection failure (e.g. `VersionNotSupported` after a deploy) reloads the page, throttled to once per minute so a bad deploy window can't reload-loop. Pass `onFatal` to customize — see [Auth & sessions](/guide/auth#close-codes).
|
|
21
|
+
- **Connection timing** — the client connects on construction. Pass `autoStart: false` (SSR, auth gating) and call `client.start()` yourself.
|
|
22
|
+
|
|
23
|
+
## Rendering before the network answers {#first-paint}
|
|
24
|
+
|
|
25
|
+
An offline launch has everything it needs on disk, but it has to know that before it paints. `useSyncStatus` won't tell you: `connecting` covers hydration, so it reads the same whether the cache is full or empty. Neither will the collection — no rows mid-hydration looks exactly like a workspace that genuinely has none, which is precisely the first-launch case you must not paint as "empty".
|
|
26
|
+
|
|
27
|
+
`useHydrated` is that signal. It flips true once cached rows are restored and collections are ready:
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { useSyncStatus, useHydrated } from '@cf-sync/client/react'
|
|
31
|
+
|
|
32
|
+
function WorkspaceGate({ client, children }) {
|
|
33
|
+
const status = useSyncStatus(client)
|
|
34
|
+
const hydrated = useHydrated(client)
|
|
35
|
+
|
|
36
|
+
// Cache restored → paint now, offline or not. Otherwise wait for the server.
|
|
37
|
+
if (hydrated || status === 'synced') return children
|
|
38
|
+
if (status === 'fatal') return <Reconnect />
|
|
39
|
+
return <Spinner />
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
It stays `false` when there is nothing cached to paint — no store, a first launch, a cache discarded by a version bump, or a store that failed to open. That's deliberate: those all mean "wait for the first sync", which is the branch above. It settles once and survives reconnects, so a dropped socket never sends you back to the spinner.
|
|
44
|
+
|
|
45
|
+
Outside React, `await client.whenHydrated` resolves to the same boolean.
|
|
46
|
+
|
|
47
|
+
## Closing a workspace {#closing-a-workspace}
|
|
48
|
+
|
|
49
|
+
`client.destroy()` is the one-call teardown: stops syncing, cleans up every collection from `createCollections`, detaches add-ons (yjs fields), and closes the store connection.
|
|
50
|
+
|
|
51
|
+
Nothing durable is lost. Persisted rows and the offline outbox stay on disk, and the managed clientId is reused — mutations queued offline still replay exactly once when a client for that workspace is next constructed.
|
|
52
|
+
|
|
53
|
+
A destroyed client is inert: `start()` throws, `mutate` rejects with `Stopped`. To switch workspaces — one workspace per project, say — destroy and reconstruct:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
await client.destroy()
|
|
57
|
+
client = new SyncClient({ url, workspaceId: nextProjectId, app, persist: true })
|
|
58
|
+
collections = createCollections(client, { startSync: true })
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Multi-tab behavior
|
|
62
|
+
|
|
63
|
+
Each tab is its own client with its own clientId and socket — that's what makes presence per-tab and keeps the protocol simple. The IndexedDB store handles concurrent tabs against the same workspace safely; convergence between tabs happens through the server, which is never more than a poke away.
|
|
64
|
+
|
|
65
|
+
## What offline can't do
|
|
66
|
+
|
|
67
|
+
Offline writes are optimistic against a **lagging local state** — the server may reject them on reconnect (a permission change, a row deleted by someone else). That's the same rejection path as online: the overlay rolls back atomically and the `mutate` promise rejects with the server's code. Design mutators so that "state moved underneath me" degrades gracefully — see [the two authoring rules](/guide/defining-your-app#the-two-authoring-rules).
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Operations
|
|
2
|
+
|
|
3
|
+
Every workspace exposes an admin surface: stats, export/import, reset, and session control. It's a separate router from sync, and `authorize` is **mandatory** — these endpoints read and destroy whole workspaces.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { createAdminRoute, bearerTokenAuth } from '@cf-sync/server'
|
|
9
|
+
|
|
10
|
+
const adminRoute = createAdminRoute<Env>({
|
|
11
|
+
namespace: (env) => env.WORKSPACE,
|
|
12
|
+
authorize: bearerTokenAuth((env) => env.ADMIN_TOKEN), // wrangler secret put ADMIN_TOKEN
|
|
13
|
+
})
|
|
14
|
+
|
|
15
|
+
export default {
|
|
16
|
+
fetch: async (request: Request, env: Env) =>
|
|
17
|
+
(await adminRoute(request, env)) ?? syncHandler(request, env),
|
|
18
|
+
}
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Routes resolve to `null` for traffic that isn't theirs, so they chain with `??` — no hand-routing on `pathname`. (`createAdminFetch` is the same route with a built-in 404, for mounting standalone.)
|
|
22
|
+
|
|
23
|
+
`bearerTokenAuth` compares in constant time and **fails closed** when the secret is unset. Your `authorize` receives the op name (`'stats'`, `'export'`, `'import'`, `'reset'`, `'disconnect'`), so per-op policies are one `switch` away.
|
|
24
|
+
|
|
25
|
+
## The endpoints
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
GET /admin/<workspaceId>/stats gauges + counters (rows, versions, connections, db size)
|
|
29
|
+
GET /admin/<workspaceId>/export JSON snapshot of live rows
|
|
30
|
+
POST /admin/<workspaceId>/import replace state from a snapshot (live clients converge via reset poke)
|
|
31
|
+
POST /admin/<workspaceId>/reset wipe the workspace; new history (backendId)
|
|
32
|
+
POST /admin/<workspaceId>/disconnect kick or refresh live sessions ({principal?, clientId?, mode})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
With the [yjs fields extension](/guide/collaborative-text) registered, `stats` includes its gauges and `export`/`import` round-trip fields alongside rows.
|
|
36
|
+
|
|
37
|
+
Live clients need no special handling around any of these: an `import` or `reset` changes the workspace's history id, and connected clients converge through a reset poke — a full re-bootstrap delivered as a normal protocol message.
|
|
38
|
+
|
|
39
|
+
## Same-worker callers
|
|
40
|
+
|
|
41
|
+
Don't hand-build HTTP requests against your own routes — `workspaceAdmin` wraps every op as a typed method on the DO stub:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { workspaceAdmin } from '@cf-sync/server'
|
|
45
|
+
|
|
46
|
+
const ws = workspaceAdmin(env.WORKSPACE, workspaceId)
|
|
47
|
+
await ws.stats()
|
|
48
|
+
await ws.disconnect({ principal: userId, mode: 'kick', reason: 'membership-revoked' })
|
|
49
|
+
await ws.reset()
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
This is the natural home for billing webhooks and app command handlers — see [Auth & sessions](/guide/auth#revoking-and-refreshing-live-sessions) for the kick/refresh semantics.
|
|
53
|
+
|
|
54
|
+
## `reset` as the recovery hatch
|
|
55
|
+
|
|
56
|
+
A workspace whose stored state can no longer be loaded (e.g. written by a much older deploy, outside the migration chain) is **quarantined**: sync upgrades answer 503 and admin ops report the failure — but `reset` stays reachable by design. Export what you can, reset, re-import: the workspace is healthy again with a new `backendId`, and clients re-bootstrap automatically.
|
|
57
|
+
|
|
58
|
+
## R2 mutation-log archive
|
|
59
|
+
|
|
60
|
+
Add an `export` bucket to the DO config and a periodic alarm streams the mutation log to R2 as ndjson — archive and analytics without touching the hot path:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
export class WorkspaceDO extends createWorkspaceDO({
|
|
64
|
+
app,
|
|
65
|
+
export: { bucket: (env: Env) => env.EXPORT_BUCKET }, // the annotation types the whole DO's env
|
|
66
|
+
}) {}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Objects land at `cf-sync/<workspaceId>/mutation-log/<from>-<to>.ndjson`. DO SQLite remains the system of record (it has point-in-time recovery of its own); R2 covers everything beyond it.
|
|
70
|
+
|
|
71
|
+
## What to monitor
|
|
72
|
+
|
|
73
|
+
`stats` is designed to be scraped: row counts, schema version, live connections, and database size per workspace. The engine also logs actionable warnings worth alerting on — most notably the [schema-drift warning](/guide/schema-evolution#drift-detection), which means a deploy changed table schemas without a version bump.
|
|
74
|
+
|
|
75
|
+
## Error reporting (Sentry) {#sentry}
|
|
76
|
+
|
|
77
|
+
`createWorkspaceDO` returns an ordinary Durable Object class, so Sentry's Durable Object wrapper composes with it directly:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { instrumentDurableObjectWithSentry } from '@sentry/cloudflare'
|
|
81
|
+
import { createWorkspaceDO } from '@cf-sync/server'
|
|
82
|
+
import { app } from '../src/schema'
|
|
83
|
+
|
|
84
|
+
export const WorkspaceDO = instrumentDurableObjectWithSentry(
|
|
85
|
+
// Annotate the env parameter even if you don't use it — Sentry infers its
|
|
86
|
+
// `Env` type from this callback, and a bare `() => ({…})` widens it to
|
|
87
|
+
// `unknown`, which then rejects the engine class.
|
|
88
|
+
(env: Env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1 }),
|
|
89
|
+
createWorkspaceDO({ app }),
|
|
90
|
+
)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Add `nodejs_compat` to `compatibility_flags` — `@sentry/cloudflare` needs `AsyncLocalStorage`. The engine itself does not require the flag.
|
|
94
|
+
|
|
95
|
+
This combination is covered by a test in the engine's own suite: a real wrap driven through a real socket, asserting that the upgrade, `webSocketMessage`, `webSocketClose`, and the maintenance alarm all still dispatch, that handlers are re-wrapped when the object wakes, and that a mutation is committed to SQL before the handler yields — Sentry wraps the handlers in scope and span machinery, but never defers the call, so the engine's synchronous commit-then-send is intact.
|
|
96
|
+
|
|
97
|
+
Note that Sentry replaces `ctx.storage` with a span-instrumenting proxy, which means every `sql.exec` the engine runs becomes a `db.query` span. That is a lot of spans per poke on a busy workspace — sample with `tracesSampleRate` accordingly.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Presence
|
|
2
|
+
|
|
3
|
+
Who's online, live cursors, "X is editing this field" — ephemeral peer state relayed over the same socket as your data, and **never persisted**.
|
|
4
|
+
|
|
5
|
+
## Declare the shape once
|
|
6
|
+
|
|
7
|
+
Add a `presence` schema to `defineApp` and the whole surface lights up, typed end to end. The server validates every inbound state against it before relaying, so peers can't feed junk into your UI:
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
export const app = defineApp({
|
|
11
|
+
version: 1,
|
|
12
|
+
schema,
|
|
13
|
+
mutators,
|
|
14
|
+
presence: z.object({
|
|
15
|
+
name: z.string(),
|
|
16
|
+
cursor: z.object({ x: z.number(), y: z.number() }).optional(),
|
|
17
|
+
}),
|
|
18
|
+
})
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## The client surface
|
|
22
|
+
|
|
23
|
+
Provide identity once at construction; afterwards every call site can be a bare merge, immune to component mount order:
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const client = new SyncClient({ ..., initialPresence: { name: 'ada' } })
|
|
27
|
+
|
|
28
|
+
client.presence.update({ cursor: { x, y } }) // shallow merge — no re-stating `name`
|
|
29
|
+
client.presence.update({ cursor: undefined }) // clear one field, keep the rest
|
|
30
|
+
client.presence.set({ name: 'ada lovelace' }) // full replace, when you mean it
|
|
31
|
+
client.presence.self // your own parsed state (never in peers)
|
|
32
|
+
client.presence.clear() // peers see you go quiet
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { usePresence } from '@cf-sync/client/react'
|
|
37
|
+
|
|
38
|
+
const peers = usePresence(client) // typed by the presence schema, self excluded
|
|
39
|
+
peers.map((p) => <Cursor key={p.clientId} name={p.state.name} at={p.state.cursor} />)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## What the library owns so apps don't
|
|
43
|
+
|
|
44
|
+
- **Pacing** — call `set`/`update` straight from a `mousemove` handler; the client throttles trailing-edge (one frame per `presenceThrottleMs`, default 100ms, latest state wins). No throttle glue in app code.
|
|
45
|
+
- **Lifecycle** — the last-set state re-announces on every reconnect and after DO hibernation wakes; peers reset to empty on disconnect. Stale presence is worse than absent presence.
|
|
46
|
+
- **Identity** — `clientId` and `principal` on every peer update are stamped by the server from the connection's [auth verdict](/guide/auth), never read from the payload. A modified client cannot impersonate another user's presence.
|
|
47
|
+
|
|
48
|
+
::: tip One avatar per user
|
|
49
|
+
Peers are per *connection* — the same user in two tabs is two peers. Key avatar stacks by `principal` (falling back to `clientId` when unauthenticated) and you get "one avatar per user" for free, attested by the server rather than claimed by the payload.
|
|
50
|
+
:::
|
|
51
|
+
|
|
52
|
+
## Two semantics to know
|
|
53
|
+
|
|
54
|
+
::: info Presence is ephemeral — no version bumps
|
|
55
|
+
Nothing is ever stored, so changing the presence schema needs **no version bump**. A reshape logs a soft server-side warning and that is all. Prefer additive changes (optional fields): old and new bundles share a workspace during a deploy window, and invalid state is dropped gracefully on both sides.
|
|
56
|
+
:::
|
|
57
|
+
|
|
58
|
+
::: warning Liveness is TCP-bound — treat presence as advisory
|
|
59
|
+
A peer that dies silently (laptop lid, network partition) lingers until socket teardown surfaces — anywhere from ~75 seconds to a couple of minutes. Never hard-lock UI on presence. Every peer entry carries `receivedAt` (local receipt time), so a tighter staleness bound is one comparison:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
const stale = Date.now() - p.receivedAt > 30_000
|
|
63
|
+
```
|
|
64
|
+
:::
|