braid-text 0.5.15 → 0.5.17

package/README.md

@@ -77,6 +77,7 @@ http_server.on("request", (req, res) => {
       - `version` - The version after the PUT
       - `parents` - The version prior to the PUT
   - This is the main method of this library, and does all the work to handle Braid-HTTP `GET` and `PUT` requests concerned with a specific text resource.
+  - A `GET` with `Subscribe: true` and `Method-Override: HEAD` headers subscribes to header-only updates: each update carries just `Version` and `Parents` headers, with no body or patches — useful for cheaply knowing *that* something changed. (A `Method-Override: HEAD` on a `GET` without `Subscribe` acts like a normal `HEAD` request.)
 
 `await braid_text.get(key)`
   - `key`: ID of text resource.
@@ -86,10 +87,11 @@ http_server.on("request", (req, res) => {
   - `key`: ID of text resource.
   - `options`: An object containing additional options, like http headers:
     - `version`:  <small style="color:lightgrey">[optional]</small> The [version](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-2) to get, as an array of strings.  (The array is typically length 1.)
-    - `parents`:  <small style="color:lightgrey">[optional]</small> The version to start the subscription at, as an array of strings.
+    - `parents`:  <small style="color:lightgrey">[optional]</small> The version to start the subscription at, as an array of strings. If this is already the current version, no initial update is sent.
     - `subscribe: cb`:  <small style="color:lightgrey">[optional]</small> Instead of returning the state; [subscribes](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-4) to the state, and calls `cb` with the initial state and each update. The function `cb` will be called with a Braid [update](https://datatracker.ietf.org/doc/html/draft-toomim-httpbis-braid-http#section-3) of the form `cb({version, parents, body, patches})`.
     - `merge_type`: <small style="color:lightgrey">[optional]</small> The CRDT/OT [merge-type](https://raw.githubusercontent.com/braid-org/braid-spec/master/draft-toomim-httpbis-merge-types-00.txt) algorithm to emulate.  Currently supports `"simpleton"` (default) and `"dt"`.
     - `peer`: <small style="color:lightgrey">[optional]</small> Unique string ID that identifies the peer making the subscription. Mutations will not be echoed back to the same peer that `PUT`s them, for any `PUT` setting the same `peer` header.
+    - `head`: <small style="color:lightgrey">[optional]</small> If true, the subscription receives header-only updates of the form `{version, parents}` — no `body` or `patches`. Useful for cheaply knowing *that* something changed, without the cost of materializing history or patch content. On subscribe, `cb` is called once with the current version (or not at all, if `parents` is already current — as with any subscription); after that, once per update. Only meaningful with `subscribe`.
   - If NOT subscribing, returns `{version: <current_version>, body: <current-text>}`. If subscribing, returns nothing.
 
 `await braid_text.put(key, options)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-text",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@braid.org/diamond-types-node": "^2.0.1",
-    "braid-http": "~1.3.125"
+    "braid-http": "~1.3.131"
   },
   "devDependencies": {
     "yjs": "^13.6.0"

package/server.js

@@ -372,9 +372,15 @@ function create_braid_text() {
         if (merge_type !== 'simpleton' && merge_type !== 'dt' && merge_type !== 'yjs')
             return my_end(400, `Unknown merge type: ${merge_type}`)
 
+        // Method-Override: HEAD makes a GET act like a HEAD request.
+        // Combined with Subscribe, it subscribes to header-only updates
+        // (Version/Parents, no body or patches) — which a real HEAD request
+        // can't do, since HEAD responses can't stream a body.
+        var head_override = /^head$/i.test(req.headers['method-override'] ?? '')
+
         var is_read  = req.method === 'GET' || req.method === 'HEAD',
             is_write = req.method === 'PUT' || req.method === 'POST' || req.method === 'PATCH',
-            is_head  = req.method === 'HEAD'
+            is_head  = req.method === 'HEAD' || (head_override && !req.subscribe)
 
         // ── Handle simple methods that don't need further processing ──
 
@@ -506,12 +512,16 @@ function create_braid_text() {
                         version: req.version,
                         parents: req.parents,
                         merge_type,
+                        head: head_override,
                         signal: aborter.signal,
                         accept_encoding:
                             req.headers['x-accept-encoding'] ?? req.headers['accept-encoding'],
                         subscribe: update => {
                             // Add digest for integrity checking on the client
-                            if (update.version && v_eq(update.version, resource.version))
+                            // (skipped for header-only updates, which carry
+                            // no content to check)
+                            if (!head_override
+                                && update.version && v_eq(update.version, resource.version))
                                 update['Repr-Digest'] = get_digest(resource.val)
 
                             // Collapse single-element patches array for HTTP
@@ -519,7 +529,7 @@ function create_braid_text() {
                                 update.patch = update.patches[0]
                                 delete update.patches
                             }
-                            if (!update.encoding)
+                            if (!update.encoding && !head_override)
                                 update.content_type = content_type
                             res.sendUpdate(update)
                         },
@@ -690,7 +700,11 @@ function create_braid_text() {
 
         var resource = (typeof key == 'string') ? await get_resource(key) : key
         var version = resource.version
-        var merge_type = options.range_unit === 'yjs-text' ? 'yjs'
+        // head: true = subscribe to header-only updates (version/parents,
+        // no body or patches). Cheap: never materializes history or patch
+        // content. Head clients live in the dt client list.
+        var merge_type = options.head ? 'dt'
+            : options.range_unit === 'yjs-text' ? 'yjs'
             : (options.merge_type || 'simpleton')
         var has_parents = Array.isArray(options.parents)
         var has_version = Array.isArray(options.version)
@@ -829,12 +843,20 @@ function create_braid_text() {
                 var client = {
                     merge_type: 'dt',
                     peer: options.peer,
+                    head: !!options.head,
                     send_update: one_at_a_time(options.subscribe),
                     accept_encoding_dt: !!options.accept_encoding?.match(/updates\s*\((.*)\)/)?.[1]?.split(',').map(x=>x.trim()).includes('dt'),
                 }
 
                 // Send initial history
-                if (client.accept_encoding_dt) {
+                if (client.head) {
+                    // Header-only: announce the current frontier in a single
+                    // update — or send nothing if the subscriber's parents
+                    // are already current (getting.history === false)
+                    if (getting.history)
+                        client.send_update({ version: resource.version,
+                                             parents: options.parents || [] })
+                } else if (client.accept_encoding_dt) {
                     if (!getting.history)
                         client.send_update({ encoding: 'dt', body: new Doc().toBytes() })
                     else {
@@ -993,7 +1015,11 @@ function create_braid_text() {
                         for (let client of resource.dt.clients) {
                             if (!peer || client.peer !== peer)
                                 await client.send_update(
-                                    client.accept_encoding_dt
+                                    client.head
+                                        ? { version: resource.version,
+                                            parents: version_before_yjs_sync
+                                          }
+                                    : client.accept_encoding_dt
                                         ? { version: resource.version,
                                             parents: version_before_yjs_sync,
                                             body: resource.dt.doc.getPatchSince(yjs_v_before),
@@ -1042,6 +1068,7 @@ function create_braid_text() {
 
             if (options.transfer_encoding === 'dt') {
                 await ensure_dt_exists(resource)
+                var version_before_dt_put = resource.version
                 var start_i = 1 + resource.dt.doc.getLocalVersion().reduce((a, b) => Math.max(a, b), -1)
 
                 resource.dt.doc.mergeBytes(body)
@@ -1059,9 +1086,10 @@ function create_braid_text() {
 
                 // Notify non-simpleton clients with the dt-encoded update
                 var dt_update = { body, encoding: 'dt' }
+                var head_update = { version: resource.version, parents: version_before_dt_put }
                 for (let client of resource.dt.clients)
                     if (!peer || client.peer !== peer)
-                        await client.send_update(dt_update)
+                        await client.send_update(client.head ? head_update : dt_update)
 
                 return { dt: { change_count: end_i - start_i + 1 } }
             }
@@ -1355,9 +1383,10 @@ function create_braid_text() {
                     content: p.content
                 })),
             }
+            var x_head = { version: x.version, parents: x.parents }
             for (let client of resource.dt.clients) {
                 if (!peer || client.peer !== peer)
-                    post_commit_updates.push([client, x])
+                    post_commit_updates.push([client, client.head ? x_head : x])
             }
 
             await resource.dt.log.save(resource.dt.doc.getPatchSince(v_before))