braid-text 0.5.7 → 0.5.8

package/client/simpleton-sync.js

@@ -1,19 +1,9 @@
-// ************************************************************************
-// ******* Reference Implementation of Simpleton Client Algorithm *********
-// ************************************************************************
-//
-// This is the canonical JS reference for implementing a simpleton client.
-// Other language implementations should mirror this logic exactly, with
-// adaptations only for language-specific details (e.g., string encoding).
-//
-// requires braid-http@~1.3/braid-http-client.js
+// Simpleton Javascript Client
 //
+//     requires braid-http@~1.3/braid-http-client.js
+
 // --- API ---
 //
-// url: resource endpoint
-//
-// headers:  custom headers that get forwarded through into the fetch
-//
 // on_patches?: (patches) => void
 //     processes incoming patches by applying them to the UI/textarea.
 //     Patches are guaranteed to be in-order and non-overlapping.
@@ -74,26 +64,6 @@
 //     get_patches is optional.)
 //     call abort() to abort the subscription.
 //
-// --- Retry and Reconnection Behavior ---
-//
-// Simpleton relies on braid_fetch for retry/reconnection:
-//
-// Subscription (GET):
-//   retry: () => true — always reconnect on any error (network failure,
-//   HTTP error, etc.). Reconnection backs off:
-//     delay = Math.min(retry_count + 1, 3) * 1000 ms
-//   i.e., 1s, 2s, 3s, 3s, 3s, ...
-//   On reconnect, sends Parents via the parents callback to resume
-//   from where the client left off.
-//
-// PUT requests:
-//   retry: (res) => res.status !== 550 — retry all errors EXCEPT
-//   HTTP 550 (Repr-Digest mismatch, meaning client is out of sync).
-//   This means:
-//     - Connection failure: retried with backoff
-//     - HTTP 401, 403, 408, 429, 500, 502, 503, 504, etc.: retried
-//     - HTTP 550: out of sync — stop retrying, throw error. The
-//       client must be torn down and restarted from scratch.
 //
 // --- Local Edit Absorption ---
 //
@@ -113,26 +83,27 @@
 // update; otherwise your UI will not reflect remote changes.
 //
 function simpleton_client(url, {
-    on_patches,
-    on_state,
     get_patches,
     get_state,
-    content_type,
-    headers,                  // The user can pass in custom headers
-                              // that are forwarded into fetches
+
+    on_patches,
+    on_state,
     on_error,
     on_online,
     on_ack,
+
+    headers,                  // The user can pass in custom headers
+                              // that are forwarded into fetches
+    content_type,
     send_digests
 }) {
     var peer = Math.random().toString(36).slice(2)
     var client_version = []          // sorted version strings
     var client_state = ""            // text as of client_version
     var char_counter = -1            // char-delta for version IDs
-    var outstanding_changes = 0      // PUTs sent, not yet ACKed
-    var max_outstanding_changes = 10 // throttle limit
-    var throttled = false
-    var throttled_updates = []
+    var dirty = false                // true when local edits exist but haven't been sent
+    var is_online = false
+    var outstanding_puts = 0
 
     // extend the headers with merge-type and peer
     headers = {
@@ -145,31 +116,26 @@ function simpleton_client(url, {
     // channel with automatic reconnection and PUT queuing.
     var channel = reliable_update_channel(url, {
         reconnect_from_parents: () => client_version.length ? client_version : null,
-        get_headers: {
-            ...headers,
-            ...content_type && {Accept: content_type}
-        },
-        put_headers: {
-            ...headers,
-            ...content_type && {"Content-Type": content_type}
-        },
+        get_headers: { ...headers, ...content_type && {Accept: content_type} },
+        put_headers: { ...headers, ...content_type && {"Content-Type": content_type} },
         on_update: async update => {
             // ── Parent check ────────────────────────────────────────
             // Core simpleton invariant: only accept updates whose
-            // parents form a continuous chain. We compare against the
-            // last queued update's version (if throttled) or
-            // client_version. When throttled, matching updates are
-            // queued but not applied — they'll be applied later when
-            // the throttle clears (see changed()).
+            // parents match our current version. If we're dirty
+            // (have unsent local edits), skip — we'll reconnect
+            // once the edits are flushed.
             update.parents.sort()
-            var last_queued = throttled_updates.length
-                ? throttled_updates[throttled_updates.length - 1].version
-                : client_version
-            if (versions_eq(last_queued, update.parents))
-                if (throttled) throttled_updates.push(update)
-                else await apply_update(update)
+            if (!dirty && versions_eq(client_version, update.parents))
+                await apply_update(update)
+        },
+        on_status: status => {
+            is_online = status.online
+            outstanding_puts = status.outstanding_puts
+            if (on_online) on_online(status.online)
+            if (on_ack && outstanding_puts === 0) on_ack()
+            if (dirty && is_online && outstanding_puts < 10)
+                try_send()
         },
-        on_status: status => on_online && on_online(status.online),
         on_error: err => on_error && on_error(err),
 
         // this api is preliminary and undocumented;
@@ -200,12 +166,12 @@ function simpleton_client(url, {
             // are natively indexed by code points (e.g., Emacs Lisp,
             // Python, Rust's char iterator).
             convert_ranges_codepoints_to_utf16(patches, client_state)
-        } else {
+        } else
             // Initial snapshot: convert body to a patch replacing
             // [0,0] so it follows the same code path as incremental
             // patches.
             patches = [{range: [0, 0], content: update.body_text}]
-        }
+
 
         // ── Apply the update ────────────────────────────────────────
         if (on_patches) {
@@ -216,11 +182,11 @@ function simpleton_client(url, {
             // changed() after every local edit to avoid this.
             on_patches(patches)
             client_state = get_state()
-        } else {
+        } else
             // Apply patches to our internal state; the
             // result is delivered via on_state below.
             client_state = apply_patches(client_state, patches)
-        }
+
 
         // ── Advance version ─────────────────────────────────────────
         // IMPORTANT: This must happen synchronously (before any await)
@@ -235,135 +201,83 @@ function simpleton_client(url, {
         // loop handles flushing accumulated edits.
         if (on_state) on_state(client_state)
 
-        // ── Digest verification ─────────────────────────────────────
-        // If the server sent a repr-digest, verify our state
-        // matches. On mismatch, THROW — this halts the
-        // subscription handler. The document is corrupted and
-        // continuing would compound the problem.
-        //
-        // This is placed after advancing client_version and calling
-        // on_state so that the await does not create a yield point
-        // between applying patches and advancing client_version.
-        // That yield point previously allowed the changed() PUT loop
-        // to interleave, capturing a stale client_version and causing
-        // edit loss.
-        if (update.extra_headers &&
-            update.extra_headers["repr-digest"] &&
-            update.extra_headers["repr-digest"].startsWith('sha-256=') &&
-            update.extra_headers["repr-digest"] !== await get_digest(client_state)) {
-            console.log('repr-digest mismatch!')
-            console.log('repr-digest: ' + update.extra_headers["repr-digest"])
-            console.log('state: ' + client_state)
-            throw new Error('repr-digest mismatch')
-        }
+        // Now verify that we did this correct, and are in sync.  We do this
+        // at the end, so the prior updating is atomic.
+        await check_digest(update, client_state)
     }
 
-    // ── Public interface ────────────────────────────────────────────────
-    return {
-      // ── abort() — cancel the subscription ─────────────────────────
-      abort: () => channel.close(),
-
-      // ── changed() — call when local edits occur ───────────────────
-      // This is the entry point for sending local edits. It:
-      // 1. Diffs client_state vs current state
-      // 2. Checks the throttle (outstanding_changes >= max)
-      // 3. Sends a PUT with the diff
-      // 4. After the PUT completes, loops to check for MORE accumulated
-      //    edits (the async accumulation loop), sending them too.
-      //
-      // The async accumulation loop (while(true) {...}) is equivalent
-      // to a callback-driven flush: after each PUT ACK, re-diff and
-      // send again if changed. This ensures edits that accumulate
-      // during a PUT round-trip are eventually sent.
-      changed: () => {
-        function get_change() {
-            var new_state = get_state()
-            if (new_state === client_state) return null
-            var patches = get_patches ? get_patches(client_state) :
-                [simple_diff(client_state, new_state)]
-            return {patches, new_state}
-        }
-
-        var change = get_change()
-        if (!change) {
-            if (throttled) {
-                throttled = false
-                for (var update of throttled_updates)
-                    if (versions_eq(client_version, update.parents))
-                        apply_update(update).catch(on_error)
-                throttled_updates = []
-            }
-            return
-        }
-
-        if (outstanding_changes >= max_outstanding_changes) {
-            throttled = true
+    // ── try_send — attempt to flush local edits ───────────────────────
+    // Called from changed() and on_status. Diffs client_state vs current
+    // state and sends a PUT if there's a change. If dirty but no diff,
+    // we may have missed updates while dirty, so reconnect to re-sync.
+    function try_send() {
+        var new_state = get_state()
+        if (new_state === client_state) {
+            // No local diff — but we were dirty, meaning we may have
+            // skipped incoming updates. Reconnect to catch up.
+            dirty = false
+            channel.reconnect()
             return
         }
 
-        var {patches, new_state} = change
+        var patches = get_patches ? get_patches(client_state) :
+            [simple_diff(client_state, new_state)]
 
         // Save JS-index patches before code-point conversion mutates them
         var js_patches = patches.map(p => ({range: [...p.range], content: p.content}))
 
-        ;(async () => {
-            while (true) {
-                // ── JS-SPECIFIC: Convert JS UTF-16 ranges to code-points ──
-                // The wire protocol uses code-point offsets. See the
-                // inverse conversion in the receive path above.
-                //
-                // OTHER LANGUAGES: Skip this if your strings are
-                // natively code-point indexed.
-                convert_ranges_utf16_to_codepoints(patches, client_state)
-
-                for (let patch of patches) {
-                    // ── Update char_counter ─────────────────────────
-                    // Increment by deleted chars + inserted chars
-                    char_counter += patch.range[1] - patch.range[0]
-                    char_counter += count_code_points(patch.content)
-
-                    patch.unit = "text"
-                    patch.range = `[${patch.range[0]}:${patch.range[1]}]`
-                }
-
-                // ── Compute version and advance optimistically ──────
-                var version = [peer + "-" + char_counter]
-
-                var parents = client_version
-                client_version = version   // optimistic advance
-                client_state = new_state   // update client_state
-
-                // ── Send PUT ────────────────────────────────────────
-                // Uses braid_fetch with retry: (res) => res.status !== 550
-                // This means:
-                //   - Network failures: retried with backoff
-                //   - HTTP 401, 403, 408, 429, 500, 502, 503, 504: retried
-                //   - HTTP 550 (Repr-Digest mismatch / out of sync):
-                //     give up, throw — client must be re-created
-                outstanding_changes++
-
-                await channel.put({
-                    version, parents, patches,
-                    headers: {
-                        ...send_digests && {
-                            "Repr-Digest": await get_digest(client_state) }
-                    }
-                })
-                
-                throttled = false
-                outstanding_changes--
-                if (on_ack && !outstanding_changes) on_ack()
-
-                // ── Check for accumulated edits ─────────────────────
-                // While the PUT was in flight, more local edits may
-                // have occurred. Diff again and loop if changed.
-                var more = get_change()
-                if (!more) return
-                ;({patches, new_state} = more)
-            }
-        })()
+        // ── JS-SPECIFIC: Convert JS UTF-16 ranges to code-points ────
+        // The wire protocol uses code-point offsets. See the
+        // inverse conversion in the receive path above.
+        //
+        // OTHER LANGUAGES: Skip this if your strings are
+        // natively code-point indexed.
+        convert_ranges_utf16_to_codepoints(patches, client_state)
+
+        for (let patch of patches) {
+            // ── Update char_counter ─────────────────────────────────
+            // Increment by deleted chars + inserted chars
+            char_counter += patch.range[1] - patch.range[0]
+            char_counter += count_code_points(patch.content)
+
+            patch.unit = "text"
+            patch.range = `[${patch.range[0]}:${patch.range[1]}]`
+        }
+
+        // ── Compute version and advance optimistically ──────────────
+        var version = [peer + "-" + char_counter]
+
+        var parents = client_version
+        client_version = version   // optimistic advance
+        client_state = new_state   // update client_state
+        dirty = false
+
+        // Send Update — when the PUT completes, on_status fires
+        // with updated outstanding_puts, which will call try_send
+        // again if dirty.
+        if (send_digests)
+            get_digest(client_state).then(digest =>
+                channel.put({ version, parents, patches,
+                    headers: { "Repr-Digest": digest } }))
+        else
+            channel.put({ version, parents, patches })
 
         return js_patches
+    }
+
+    // ── Public interface ────────────────────────────────────────────────
+    return {
+      // ── abort() — cancel the subscription ─────────────────────────
+      abort: () => channel.close(),
+
+      // ── changed() — call when local edits occur ───────────────────
+      // If online and under the PUT limit, sends immediately.
+      // Otherwise marks dirty — on_status will flush later.
+      changed: () => {
+        if (is_online && outstanding_puts < 10)
+            return try_send()
+        else
+            dirty = true
       }
     }
 
@@ -497,12 +411,24 @@ function simpleton_client(url, {
         return state
     }
 
-    // ── get_digest ──────────────────────────────────────────────────────
-    // Computes SHA-256 of the UTF-8 encoding of the state string,
-    // formatted as the Repr-Digest header value:
-    //   sha-256=:<base64-encoded-hash>:
+    // get_digest():
+    //  - Computes SHA-256 of the UTF-8 encoding of the string
+    //  - Formatted as Repr-Digest: sha-256=:<base64-encoded-hash>:
     async function get_digest(str) {
         var bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(str))
         return `sha-256=:${btoa(String.fromCharCode(...new Uint8Array(bytes)))}:`
     }
+    // check_digest():
+    //  - Makes sure the current state matches the digest in the update
+    async function check_digest(update, client_state) {
+        // If the server sent a repr-digest, verify our state matches.  Throw
+        // exception if it fails.
+        if (update.extra_headers?.["repr-digest"]?.startsWith('sha-256=')
+            && update.extra_headers["repr-digest"] !== await get_digest(client_state)) {
+            console.log('repr-digest mismatch!')
+            console.log('repr-digest: ' + update.extra_headers["repr-digest"])
+            console.log('state: ' + client_state)
+            throw new Error('repr-digest mismatch')
+        }
+    }
 }

package/client/web-utils.js

@@ -1,16 +1,15 @@
 
-function set_acked_state(textarea, binary = true) {
-    if (!binary) {
+function set_acked_state(textarea, on = true) {
+    if (on)
+        textarea.style.caretColor = textarea.old_caretColor
+    else {
         textarea.old_caretColor = textarea.style.caretColor
-
         textarea.style.caretColor = 'red'
-    } else {
-        textarea.style.caretColor = textarea.old_caretColor
     }
 }
 
-function set_error_state(textarea, binary = true) {
-    if (binary) {
+function set_error_state(textarea, on = true) {
+    if (on) {
         textarea.old_disabled = textarea.disabled
         textarea.old_background = textarea.style.background
         textarea.old_border = textarea.style.border
@@ -25,6 +24,8 @@ function set_error_state(textarea, binary = true) {
     }
 }
 
+// A convenient wrapper around the myers-diff.js library's "diff_main()" function,
+// which is defined in https://braid.org/code/myers-diff1.js.
 function diff(before, after) {
     let diff = diff_main(before, after)
     let patches = []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-text",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Library for collaborative text over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-text",
@@ -25,7 +25,7 @@
   ],
   "dependencies": {
     "@braid.org/diamond-types-node": "^2.0.1",
-    "braid-http": "~1.3.123"
+    "braid-http": "~1.3.124"
   },
   "peerDependencies": {
     "yjs": "^13.6.0"

package/server-demo.js

@@ -14,7 +14,7 @@ var server = require("http").createServer(async (req, res) => {
     if (req.method === 'OPTIONS') return res.end()
 
     var q = req.url.split('?').slice(-1)[0]
-    if (q === 'editor' || q === 'markdown-editor' || q === 'yjs-editor' || q === 'demo') {
+    if (q === 'editor' || q === 'markdown-editor' || q === 'yjs-editor') {
         res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-cache" })
         require("fs").createReadStream(`./client/${q}.html`).pipe(res)
         return

package/server.js

@@ -93,45 +93,55 @@ function create_braid_text() {
             resource.save_meta()
         }
 
-        // Given a version frontier, incorporate a new update (version + parents)
-        // to compute the new frontier.  Walks the DT version DAG if needed.
-        function extend_frontier(frontier, version, parents) {
-            var frontier_set = new Set(frontier)
-            // Fast path: if the frontier contains all the update's parents,
-            // just swap them out for the new version
-            if (parents.length &&
-                parents.every(p => frontier_set.has(p))) {
-                parents.forEach(p => frontier_set.delete(p))
-                for (var event of version) frontier_set.add(event)
-                frontier = [...frontier_set.values()]
-            } else {
-                // Slow path: walk the full DT history to compute the frontier
-                var looking_for = frontier_set
-                for (var event of version) looking_for.add(event)
-
-                frontier = []
-                var shadow = new Set()
-
-                var bytes = resource.dt.doc.toBytes()
-                var [_, events, parentss] = braid_text.dt_parse([...bytes])
-                for (var i = events.length - 1; i >= 0 && looking_for.size; i--) {
-                    var e = events[i].join('-')
-                    if (looking_for.has(e)) {
-                        looking_for.delete(e)
-                        if (!shadow.has(e)) frontier.push(e)
-                        shadow.add(e)
+        // When we get an ackowledgement that a remote server has a version
+        // that we have:
+        //
+        //   - In a PUT acknowledgement
+        //   - Or a GET response
+        //
+        // ...then we extend our known fork point "frontier" to include that
+        // version.
+        function extend_fork_point(update) {
+
+            // Given a version frontier, incorporate a new update (version +
+            // parents) to compute the new frontier.  Walks the DT version DAG
+            // if needed.
+            function extend_frontier(frontier, version, parents) {
+                var frontier_set = new Set(frontier)
+                // Fast path: if the frontier contains all the update's parents,
+                // just swap them out for the new version
+                if (parents.length &&
+                    parents.every(p => frontier_set.has(p))) {
+                    parents.forEach(p => frontier_set.delete(p))
+                    for (var event of version) frontier_set.add(event)
+                    frontier = [...frontier_set.values()]
+                } else {
+                    // Slow path: walk the full DT history to compute the frontier
+                    var looking_for = frontier_set
+                    for (var event of version) looking_for.add(event)
+
+                    frontier = []
+                    var shadow = new Set()
+
+                    var bytes = resource.dt.doc.toBytes()
+                    var [_, events, parentss] = braid_text.dt_parse([...bytes])
+                    for (var i = events.length - 1; i >= 0 && looking_for.size; i--) {
+                        var e = events[i].join('-')
+                        if (looking_for.has(e)) {
+                            looking_for.delete(e)
+                            if (!shadow.has(e)) frontier.push(e)
+                            shadow.add(e)
+                        }
+                        if (shadow.has(e))
+                            parentss[i].forEach(p => shadow.add(p.join('-')))
                     }
-                    if (shadow.has(e))
-                        parentss[i].forEach(p => shadow.add(p.join('-')))
                 }
+                return frontier.sort()
             }
-            return frontier.sort()
-        }
 
-        function extend_fork_point(update) {
-            resource.meta.fork_point =
-                extend_frontier(resource.meta.fork_point,
-                                update.version, update.parents)
+            resource.meta.fork_point = extend_frontier(resource.meta.fork_point,
+                                                       update.version,
+                                                       update.parents)
             resource.save_meta()
         }
 
@@ -370,8 +380,8 @@ function create_braid_text() {
             res.setHeader('Content-Type', `${ct}; charset=utf-8`)
         else if (charset.toLowerCase() !== 'charset=utf-8')
             res.setHeader('Content-Type', ct_parts
-                .map(p => p.toLowerCase().startsWith('charset=') ? 'charset=utf-8' : p)
-                .join('; '))
+                          .map(p => p.toLowerCase().startsWith('charset=') ? 'charset=utf-8' : p)
+                          .join('; '))
 
         // ── Handle simple methods that don't need further processing ──
 
@@ -407,9 +417,9 @@ function create_braid_text() {
             var getting = {
                 subscribe: !!req.subscribe,
                 history:   (has_parents && v_eq(req.parents, resource.version)) ? false
-                         : has_parents ? 'since-parents'
-                         : (req.subscribe || req.parents || req.headers['accept-transfer-encoding']) ? 'up-to-version'
-                         : false,
+                    : has_parents ? 'since-parents'
+                    : (req.subscribe || req.parents || req.headers['accept-transfer-encoding']) ? 'up-to-version'
+                    : false,
                 transfer_encoding: req.headers['accept-transfer-encoding'],
             }
             getting.single_snapshot = !getting.subscribe && !getting.history
@@ -493,8 +503,7 @@ function create_braid_text() {
                         merge_type,
                         signal: aborter.signal,
                         accept_encoding:
-                            req.headers['x-accept-encoding'] ??
-                            req.headers['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))
@@ -688,9 +697,9 @@ function create_braid_text() {
             // 'up-to-version' = bring client up to current (from scratch)
             // false = no history needed
             history:   (has_parents && v_eq(options.parents, version)) ? false
-                     : has_parents ? 'since-parents'
-                     : (options.subscribe || options.parents || options.transfer_encoding) ? 'up-to-version'
-                     : false,
+                : has_parents ? 'since-parents'
+                : (options.subscribe || options.parents || options.transfer_encoding) ? 'up-to-version'
+                : false,
             transfer_encoding: options.transfer_encoding,
         }
         getting.single_snapshot = !getting.subscribe && !getting.history
@@ -733,6 +742,7 @@ function create_braid_text() {
             return { body: bytes }
         }
 
+        // Each merge-type has a different way of getting history
         switch (merge_type) {
 
         case 'yjs':
@@ -774,7 +784,7 @@ function create_braid_text() {
 
             if (getting.history && !getting.subscribe)
                 return dt_get_patches(resource.dt.doc,
-                    getting.history === 'since-parents' ? options.parents : undefined)
+                                      getting.history === 'since-parents' ? options.parents : undefined)
 
             if (getting.subscribe) {
                 var client = {
@@ -807,7 +817,7 @@ function create_braid_text() {
 
             if (getting.history && !getting.subscribe)
                 return dt_get_patches(resource.dt.doc,
-                    getting.history === 'since-parents' ? options.parents : undefined)
+                                      getting.history === 'since-parents' ? options.parents : undefined)
 
             if (getting.subscribe) {
                 var client = {