@zubra/sync 5.9.0 → 5.9.2

package/README.md

@@ -12,4 +12,4 @@ Local-first state for Zubra components. `'use collection tasks'` at the top of a
 <task-item doc="">…</task-item>
 ```
 
-`<task-item doc="t42">` is the document `tasks/t42`. To share documents between devices, `connect()` from `@zubra/sync/connect` and serve the log with `createSyncServer()` from `@zubra/sync/server`; components don't change. see [docs/sync.md](https://github.com/journey-to-code-org/zubra/blob/main/docs/sync.md).
+`<task-item doc="t42">` is the document `tasks/t42`. To share documents between devices, `connect()` from `@zubra/sync/connect` and serve the log with `createSyncServer({ authorize })` from `@zubra/sync/server` (without `authorize`, pages may read but not write); components don't change. see [docs/sync.md](https://github.com/journey-to-code-org/zubra/blob/main/docs/sync.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/sync",
-  "version": "5.9.0",
+  "version": "5.9.2",
   "description": "Local-first state for Zubra components: 'use collection' keeps a component's state in IndexedDB, across reloads, offline, and in step across tabs.",
   "type": "module",
   "main": "./src/index.js",

package/src/connect.js

@@ -19,16 +19,31 @@ import { mesh } from './webrtc.js';
 const CLOCKS = '$clocks';
 const pad = (number, width) => String(number).padStart(width, '0');
 
-function clock(client) {
+/** How far ahead of this device a clock it hears can be before it stops following it. */
+const MAX_SKEW = 60_000;
+
+/** A device's hybrid logical clock (exported for tests). */
+export function deviceClock(client) {
   let last = 0;
   let counter = 0;
   const tick = (seen = 0) => {
-    const now = Math.max(Date.now(), last, seen);
+    let now = Math.max(Date.now(), last, seen);
     counter = now === last ? counter + 1 : 0;
+    // Five digits of counter; past them, the next millisecond (a clock must compare as a string).
+    if (counter > 99_999) {
+      now += 1;
+      counter = 0;
+    }
     last = now;
     return `${pad(now, 15)}-${pad(counter, 5)}-${client}`;
   };
-  return { tick, see: (stamp) => tick(Number(stamp.slice(0, 15))) };
+  // A stamp far in the future (a device with a wrong clock, or one sent to poison the log) isn't
+  // followed: this device's writes keep its own time, and the server refuses such stamps anyway.
+  const see = (stamp) => {
+    const time = Number(stamp.slice(0, 15));
+    return tick(time > Date.now() + MAX_SKEW ? 0 : time);
+  };
+  return { tick, see };
 }
 
 /**
@@ -86,7 +101,7 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
     keep('zubra-sync:client', id);
     return id;
   });
-  const clocks = clock(client);
+  const clocks = deviceClock(client);
   let cursor = remember(cursorName, () => '0');
   const outbox = outboxOf(JSON.parse(remember('zubra-sync:outbox', () => '[]')), (pending) =>
     keep('zubra-sync:outbox', JSON.stringify(pending)));
@@ -117,6 +132,7 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
   });
 
   let timer = null;
+  let warned = false;
   const schedule = () => {
     clearTimeout(timer);
     timer = setTimeout(flush, 30);
@@ -131,7 +147,16 @@ export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrt
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ changes: sending }),
       });
-      if (!response.ok) return;
+      if (!response.ok) {
+        // A refused write is kept (it may be allowed later), but say why once: a server with no
+        // `authorize` refuses every write from pages, and a silent outbox looks like a bug.
+        if (response.status === 403 && !warned) {
+          warned = true;
+          const why = await response.json().then((body) => body?.error, () => '');
+          console.warn(`@zubra/sync: the server refused this page's changes${why ? `: ${why}` : ''}`);
+        }
+        return;
+      }
       outbox.done(sending);
     } catch {
       // Offline: the outbox stays (in localStorage too), and goes with the next flush.

package/src/durable-core.js

@@ -7,7 +7,8 @@ import { durableObjectLog } from './durable-log.js';
 export { MOUNT };
 
 /**
- * `owner` is the object: its `authorize(…)`, if it has one, decides as `createSyncServer`'s does.
+ * `owner` is the object: its `authorize(…)`, if it has one, decides as `createSyncServer`'s does;
+ * without one, pages may read and not write.
  * `heartbeat` is shorter than on Node (2 s, not 15): a Durable Object isn't told when a page's
  * connection is cut, only that a keep-alive couldn't be written, which on workerd is the third
  * after the cut. So a crashed page's presence lingers about three keep-alives (6 s). A page that
@@ -20,7 +21,8 @@ export function syncObject(ctx, owner, { mount = MOUNT, heartbeat = 2_000, devic
     heartbeat,
     device,
     origins,
-    authorize: (asked) => (typeof owner.authorize === 'function' ? owner.authorize(asked) : true),
+    // Without an authorize of its own, the object takes reads only, as createSyncServer does.
+    authorize: typeof owner.authorize === 'function' ? (asked) => owner.authorize(asked) : undefined,
   });
   return {
     async fetch(request) {

package/src/durable.d.ts

@@ -24,7 +24,7 @@ export class SyncObject<Env = unknown> {
   protected ctx: any;
   protected env: Env;
   /** Refuse a write or hide a change; as `createSyncServer`'s. Allows everything if not defined. */
-  authorize?(asked: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }): boolean | Promise<boolean>;
+  authorize?(asked: { request: Request; collection: string; key: string; field?: string; value?: unknown; write: boolean; kind: 'change' | 'presence' | 'read' }): boolean | Promise<boolean>;
   fetch(request: Request): Promise<Response>;
   documents(): Promise<Documents>;
   write(collection: string, key: string, fields: Record<string, unknown>): Promise<Change[]>;

package/src/server.d.ts

@@ -40,6 +40,9 @@ export function parseScope(text: string | null | undefined): Scope | null;
 /** Whether a document is in a scope (null is everything). */
 export function inScope(scope: Scope | null, collection: string, key: string): boolean;
 
+/** For `createSyncServer({ authorize: allowAnyone })`: every page may read and write everything. */
+export const allowAnyone: () => true;
+
 export function createSyncServer(options?: {
   log?: Log;
   /** Default `/_zb/sync`. */
@@ -47,9 +50,18 @@ export function createSyncServer(options?: {
   /**
    * Refuse a write, or hide a change from a reader, by returning false. `kind` is what's asked:
    * 'change' (a push), 'presence' (joining or signaling in a document's room; nothing is stored)
-   * or 'read' (a change about to be sent to this request). `write` is true for the first two.
+   * or 'read' (a change about to be sent to this request). `write` is true for the first two. A
+   * 'change' has the `field` and `value` it sets.
+   *
+   * Without it, pages may read but every write from a page is refused (403, saying why). Pass
+   * `allowAnyone` for a page everyone may edit. The server's own `write()` is never asked.
+   */
+  /**
+   * How far ahead of the server's clock a pushed change's clock may be, in ms (default 60 000).
+   * Further ahead is refused (400): a clock far in the future would win every merge for ever.
    */
-  authorize?: (from: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }) => boolean | Promise<boolean>;
+  maxSkew?: number;
+  authorize?: (from: { request: Request; collection: string; key: string; field?: string; value?: unknown; write: boolean; kind: 'change' | 'presence' | 'read' }) => boolean | Promise<boolean>;
   /** Other origins allowed to push. */
   /**
    * The scope a request may see and write (tenancy: a business's keys under its own prefix), or

package/src/server.js

@@ -10,7 +10,13 @@
 // `authorize({ request, collection, key, write, kind })` may refuse a change or hide one (return
 // false). `kind` says what's asked: 'read' (a change being sent to this request), 'change' (one
 // it pushed) or 'presence' (joining a document's room, or signaling in it: nothing is stored).
-// `write` is true for the last two.
+// `write` is true for the last two. A 'change' also has the `field` and `value` it sets, so an
+// app can keep fields (or whole collections) for the server alone.
+//
+// Without `authorize`, pages may read but not write: every push, presence and signal is refused
+// with a 403 saying so. Say who may change what, or, for a page everyone may edit (a shared
+// board on a trusted network), `createSyncServer({ authorize: allowAnyone })`. The server's own
+// `write()` is never asked.
 //
 // The server can take part too. `await sync.documents()` is every document as the devices see
 // it (last writer wins, per field), kept current; `sync.write(collection, key, fields)` writes as
@@ -129,9 +135,19 @@ const clock = {
   },
 };
 
+/**
+ * Field names a change can't have: `$clocks` is where a document keeps its fields' clocks, and
+ * `key` is the document's own key wherever documents are listed (`{ key, ...fields }`), so a
+ * field by that name would pass one document off as another.
+ */
+const RESERVED = new Set(['$clocks', 'key']);
+
 const valid = (change) =>
   change && typeof change.collection === 'string' && typeof change.key === 'string' && typeof change.field === 'string' &&
-  clock.parse(change.clock) !== null && change.field !== '$clocks';
+  clock.parse(change.clock) !== null && !RESERVED.has(change.field);
+
+/** The largest counter a clock can carry; past it, the clock moves on a millisecond. */
+const MAX_COUNTER = 99_999;
 
 /**
  * How documents are read, wherever they're kept: `find(collection, key)` → fields or undefined,
@@ -152,7 +168,8 @@ export function documentsView({ find, list, names }) {
     all: (collection, prefix = '') =>
       list(collection)
         .filter(({ key }) => key.startsWith(prefix))
-        .map(({ key, fields }) => ({ key, ...structuredClone(fields) })),
+        // The key last: nothing in the fields can stand in for it.
+        .map(({ key, fields }) => ({ ...structuredClone(fields), key })),
     /** The collections that have documents, in the order they were first written to. */
     collections: () => names(),
   };
@@ -188,8 +205,19 @@ function documentsOf() {
   };
 }
 
-export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, scope: serverScope = () => null, origins = [], heartbeat = 15_000, device = 'server' } = {}) {
+/** For `createSyncServer({ authorize: allowAnyone })`: every page may read and write everything. */
+export const allowAnyone = () => true;
+
+/** The default: pages may read; writes from pages need an `authorize` that says who may make them. */
+const readsOnly = ({ write }) => !write;
+const NO_AUTHORIZE = 'This sync server takes no writes from pages until it is told who may make them: pass createSyncServer({ authorize }) (or authorize: allowAnyone, for a page anyone may edit). See docs/sync.md, "Who may write".';
+
+export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize: given, scope: serverScope = () => null, origins = [], heartbeat = 15_000, device = 'server', maxSkew = 60_000 } = {}) {
   if (!/^[\w-]{1,40}$/.test(device)) throw new Error('createSyncServer: `device` names the server in its clocks: letters, digits, - and _');
+  if (given !== undefined && typeof given !== 'function') throw new TypeError('createSyncServer: `authorize` is a function ({ request, collection, key, field, value, write, kind }) => boolean');
+  const authorize = given ?? readsOnly;
+  /** What a refused write says: why, when no authorize was given; the app's own refusal otherwise. */
+  const refused = (fallback) => json(403, { error: given ? fallback : NO_AUTHORIZE });
   const base = mount.replace(/\/$/, '');
   // Appends, one after another, so the log's order is the order they were made in.
   let appending = Promise.resolve();
@@ -198,13 +226,23 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
   let lastTime = 0;
   let counter = 0;
   const tick = () => {
-    const now = Math.max(Date.now(), lastTime);
+    let now = Math.max(Date.now(), lastTime);
     counter = now === lastTime ? counter + 1 : 0;
+    // A counter can't outgrow its five digits (the clock would stop comparing as a string).
+    if (counter > MAX_COUNTER) {
+      now += 1;
+      counter = 0;
+    }
     lastTime = now;
     return clock.format(now, counter, device);
   };
+  /** Whether a clock is further ahead of this server's than `maxSkew`: a device can't push one. */
+  const ahead = (stamp) => clock.parse(stamp).time > Date.now() + maxSkew;
   const see = (change) => {
     const { time, counter: seen } = clock.parse(change.clock);
+    // One already in the log from before this check (or a log written elsewhere) doesn't drag
+    // this server's clock into the future with it.
+    if (time > Date.now() + maxSkew) return;
     if (time > lastTime) {
       lastTime = time;
       counter = seen;
@@ -315,10 +353,11 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
         return json(400, { error: 'Expected JSON' });
       }
       const changes = Array.isArray(body?.changes) ? body.changes : null;
-      if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }' });
+      if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }; a field can\'t be named key or $clocks' });
+      if (changes.some((change) => ahead(change.clock))) return json(400, { error: "A change's clock is ahead of the server's by more than maxSkew; check the device's time" });
       for (const change of changes) {
         if (!(await mayWrite(request, change.collection, change.key))) return json(403, { error: 'Not yours to change' });
-        if (!(await authorize({ request, collection: change.collection, key: change.key, write: true, kind: 'change' }))) return json(403, { error: 'Not yours to change' });
+        if (!(await authorize({ request, collection: change.collection, key: change.key, field: change.field, value: change.value, write: true, kind: 'change' }))) return refused('Not yours to change');
       }
       const appended = changes.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value, clock }));
       const cursor = await append(appended);
@@ -340,7 +379,8 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !okPeer || !okState || JSON.stringify(message.state).length > 4096) {
         return json(400, { error: 'Expected { room: "<collection>/<key>", peer, state: {…} | null }' });
       }
-      if (!(await mayWrite(request, room.collection, room.key)) || !(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
+      if (!(await mayWrite(request, room.collection, room.key))) return json(403, { error: 'Not yours to join' });
+      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return refused('Not yours to join');
       const clean = { room: message.room, peer: message.peer, state: message.state };
       for (const listener of listeners) if (listener.peer === clean.peer) {
         if (clean.state === null) listener.rooms.delete(clean.room);
@@ -365,7 +405,8 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !peerOk(message.from) || !peerOk(message.to) || !dataOk) {
         return json(400, { error: 'Expected { room, from, to, data: {…} }' });
       }
-      if (!(await mayWrite(request, room.collection, room.key)) || !(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
+      if (!(await mayWrite(request, room.collection, room.key))) return json(403, { error: 'Not yours to join' });
+      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return refused('Not yours to join');
       const clean = { room: message.room, from: message.from, to: message.to, data: message.data };
       for (const listener of listeners) if (listener.peer === clean.to) listener.send('signal', clean);
       return json(200, { ok: true });
@@ -471,7 +512,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     if (typeof collection !== 'string' || typeof key !== 'string' || !fields || typeof fields !== 'object' || Array.isArray(fields)) {
       throw new TypeError('sync.write(collection, key, { field: value, … })');
     }
-    if ('$clocks' in fields) throw new TypeError('sync.write: `$clocks` is not a field');
+    for (const name of RESERVED) if (name in fields) throw new TypeError(`sync.write: \`${name}\` can't be a field name`);
     // A server that hasn't read its log yet (it just started, or a Durable Object was evicted)
     // hasn't seen the clocks in it: read it first, so this write comes after all of them. Once
     // the documents exist this doesn't wait, so a check and a write with no await between stay