@zubra/sync 5.8.0 → 5.9.1

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.8.0",
+  "version": "5.9.1",
   "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",
@@ -32,7 +32,7 @@
     "test:binary": "ZUBRA_SYNC_BACKEND=binary node --test test/browser.test.js"
   },
   "peerDependencies": {
-    "@zubra/runtime": "^5.8.0"
+    "@zubra/runtime": "^5.9.0"
   },
   "devDependencies": {
     "@zubra/compiler": "file:../compiler",

package/src/connect.js

@@ -117,6 +117,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 +132,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,13 @@ 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.
    */
-  authorize?: (from: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }) => boolean | Promise<boolean>;
+  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
@@ -188,8 +194,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' } = {}) {
   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();
@@ -318,7 +335,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }' });
       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 +357,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 +383,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 });