braid-blob 0.0.68 → 0.0.70

package/README.md

@@ -46,7 +46,7 @@ node server-demo.js
 
 Now open up http://localhost:8888 in your browser, to see the client.  Open two windows.  You can drag and drop images between them, and they will always stay synchronized.
 
-<video src="https://github.com/user-attachments/assets/66ba0004-138c-4faa-a1d5-cb2cd06d3525" controls width="600"></video>
+<video src="https://github.com/user-attachments/assets/9416e06b-143a-4b3a-a840-b6484f2571b1" controls width="600"></video>
 
 ## Network API
 
@@ -56,7 +56,8 @@ Braid-blob speaks [Braid-HTTP](https://github.com/braid-org/braid-spec), an exte
 
 | Header | Description |
 |--------|-------------|
-| `Version` | Unique identifier for this version of the blob (e.g., `"alice-42"`) |
+| `Version` | Unique identifier for this version of the blob (e.g., `"1768467700000"`) |
+| `Version-Type` | How to interpret the structure of version strings (e.g., [`relative-wallclock`](https://braid.org/protocol/version-types/relative-wallclock)); see [Version-Type spec](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-versions-03.txt) |
 | `Parents` | The previous version |
 | `Merge-Type` | How conflicts resolve consistently (*e.g.* `aww` for [arbitrary-writer-wins](https://braid.org/protocol/merge-types/aww)) |
 | `Subscribe` | In GET, subscribes client to all future changes |
@@ -73,7 +74,8 @@ Response:
 
 ```http
 HTTP/1.1 200 OK
-Version: "alice-1"
+Version: "1768467700000"
+Version-Type: relative-wallclock
 Content-Type: image/png
 Merge-Type: aww
 Accept-Subscribe: true
@@ -98,10 +100,12 @@ Response (keeps connection open, streams updates):
 ```http
 HTTP/1.1 209 Multiresponse
 Subscribe: true
-Current-Version: "alice-1"
+Current-Version: "1768467700000"
+Version-Type: relative-wallclock
 
 HTTP 200 OK
-Version: "alice-1"
+Version: "1768467700000"
+Version-Type: relative-wallclock
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 12345
@@ -109,7 +113,8 @@ Content-Length: 12345
 <binary data>
 
 HTTP 200 OK
-Version: "bob-2"
+Version: "1768467701000"
+Version-Type: relative-wallclock
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 23456
@@ -124,7 +129,8 @@ If the blob doesn't exist yet, `Current-Version` will be blank and no initial up
 
 ```http
 PUT /blob.png HTTP/1.1
-Version: "carol-3"
+Version: "1768467702000"
+Version-Type: relative-wallclock
 Content-Type: image/png
 Merge-Type: aww
 Content-Length: 34567
@@ -136,7 +142,8 @@ Response:
 
 ```http
 HTTP/1.1 200 OK
-Current-Version: "carol-3"
+Current-Version: "1768467702000"
+Version-Type: relative-wallclock
 ```
 
 If the sent version is older or eclipsed by the server's current version, the returned `Current-Version` will be the server's version (not the one you sent).
@@ -157,13 +164,19 @@ HTTP/1.1 200 OK
 
 Returns `200 OK` even if the blob didn't exist.
 
-### Understanding versions
+### Understanding versions and conflict resolution
 
-Versions look like `"alice-42"` where:
-- `alice` is a peer ID (identifies who made the change)
-- `42` is a sequence number (generally milliseconds past the epoch, or one plus the current number if it is past the current time)
+Braid-blob uses two complementary mechanisms for distributed consistency:
 
-Conflicts resolve using ["arbitrary-writer-wins" (AWW)](https://braid.org/protocol/merge-types/aww): the version with the highest sequence number wins. If sequences match, the peer ID string is compared lexicographically.
+**Version-Type: [`relative-wallclock`](https://braid.org/protocol/version-types/relative-wallclock)** defines the format and interpretation of version identifiers:
+- Versions are millisecond timestamps (e.g., `"1768467700000"`)
+- If the current time is behind the latest known version, a small random number (1-1000) is added to the current version, providing entropy when multiple peers write simultaneously
+- Versions are compared numerically—larger timestamps are newer
+
+**Merge-Type: [`aww`](https://braid.org/protocol/merge-types/aww)** (arbitrary-writer-wins) defines how conflicts are resolved:
+- When two peers make concurrent changes, the version with the higher timestamp wins
+- All peers deterministically converge to the same state without coordination
+- This provides "last-writer-wins" semantics under normal clock conditions
 
 
 
@@ -192,7 +205,7 @@ var {body, version, content_type} = await braid_blob.get(new URL('https://foo.ba
 // Get a specific version of a remote blob:
 var {body} = await braid_blob.get(
     new URL('https://foo.bar/baz'),
-    {version: ['5zb2sjdstmk-1768093765048']}
+    {version: ['1768467700000']}
 )
 
 // To subscribe to a remote blob, without storing updates locally:
@@ -245,8 +258,8 @@ Retrieves a blob from local storage or a remote URL.
 Parameters:
 - `key` - The local blob (if string) or remote URL (if [URL object](https://nodejs.org/api/url.html#class-url)) to read from
 - `params` - Optional configuration object
-  - `version` - Retrieve a specific version instead of the latest (e.g., `['abc-123']`)
-  - `parents` - When subscribing, only receive updates newer than this version (e.g., `['abc-123']`)
+  - `version` - Retrieve a specific version instead of the latest (e.g., `['1768467700000']`)
+  - `parents` - When subscribing, only receive updates newer than this version (e.g., `['1768467700000']`)
   - `subscribe` - Callback `(update) => {}` called with each update; `update` has `{body, version, content_type}`
   - `head` - If `true`, returns only metadata (`{version, content_type}`) without the body—useful for checking if a blob exists or getting its current version
   - `content_type` - Expected content type (sent as Accept header for remote URLs)
@@ -262,7 +275,7 @@ Parameters:
 - `key` - The local blob (if string) or remote URL (if [URL object](https://nodejs.org/api/url.html#class-url)) to write to
 - `body` - The data to store (Buffer, ArrayBuffer, or Uint8Array)
 - `params` - Optional configuration object
-  - `version` - Specify a version ID for this write (e.g., `['my-version-1']`); if omitted, one is generated automatically
+  - `version` - Specify a version ID for this write (e.g., `['1768467700000']`); if omitted, one is generated automatically
   - `content_type` - MIME type of the blob (e.g., `'image/png'`, `'application/json'`)
   - `signal` - AbortSignal to cancel the request
 

package/client.js

@@ -51,9 +51,7 @@ function braid_blob_client(url, params = {}) {
 
     return {
         update: async (body, content_type) => {
-            var seq = max_seq('' + Date.now(),
-                increment_seq(get_event_seq(current_version)))
-            current_version = `${peer}-${seq}`
+            current_version = create_event(current_version)
 
             params.on_update?.(body, content_type, current_version)
 
@@ -80,41 +78,70 @@ function braid_blob_client(url, params = {}) {
         return 0
     }
 
+    function create_event(current_event, max_entropy = 1000) {
+        var new_event = '' + Date.now()
+
+        var current_seq = get_event_seq(current_event)
+        if (compare_seqs(new_event, current_seq) > 0) return new_event
+
+        // Find smallest base-10 integer where compare_seqs(int, current_seq) >= 0
+        var base = seq_to_int(current_seq)
+        return '' + (base + 1 + Math.floor(Math.random() * max_entropy))
+    }
+
     function get_event_seq(e) {
         if (!e) return ''
 
         for (let i = e.length - 1; i >= 0; i--)
-            if (e[i] === '-') return e.slice(i + 1)
+            if (e[i] === '-') return i == 0 ? e : e.slice(i + 1)
         return e
     }
 
-    function increment_seq(s) {
-        if (!s) return '1'
-
-        let last = s[s.length - 1]
-        let rest = s.slice(0, -1)
-
-        if (last >= '0' && last <= '8')
-            return rest + String.fromCharCode(last.charCodeAt(0) + 1)
-        else
-            return increment_seq(rest) + '0'
-    }
-
-    function max_seq(a, b) {
+    function compare_seqs(a, b) {
         if (!a) a = ''
         if (!b) b = ''
 
-        if (compare_seqs(a, b) > 0) return a
-        return b
-    }
+        var a_neg = a[0] === '-'
+        var b_neg = b[0] === '-'
+        if (a_neg !== b_neg) return a_neg ? -1 : 1
 
-    function compare_seqs(a, b) {
-        if (!a) a = ''
-        if (!b) b = ''
+        // Both negative: compare magnitudes (reversed)
+        if (a_neg) {
+            var swap = a.slice(1); a = b.slice(1); b = swap
+        }
 
         if (a.length !== b.length) return a.length - b.length
         if (a < b) return -1
         if (a > b) return 1
         return 0
     }
+
+    // Smallest base-10 integer n where compare_seqs(String(n), s) >= 0
+    function seq_to_int(s) {
+        if (!s || s[0] === '-') return 0
+
+        var len = s.length
+        var min_of_len = Math.pow(10, len - 1) // e.g., len=3 -> 100
+        var max_of_len = Math.pow(10, len) - 1 // e.g., len=3 -> 999
+
+        if (s < String(min_of_len)) return min_of_len
+        if (s > String(max_of_len)) return max_of_len + 1
+
+        // s is in the base-10 range for this length
+        // scan for first non-digit > '9', increment prefix and pad zeros
+        var n = 0
+        for (var i = 0; i < len; i++) {
+            var c = s.charCodeAt(i)
+            if (c >= 48 && c <= 57) {
+                n = n * 10 + (c - 48)
+            } else if (c > 57) {
+                // non-digit > '9': increment prefix, pad rest with zeros
+                return (n + 1) * Math.pow(10, len - i)
+            } else {
+                // non-digit < '0': just pad rest with zeros
+                return n * Math.pow(10, len - i)
+            }
+        }
+        return n
+    }
 }

package/index.js

@@ -152,6 +152,7 @@ function create_braid_blob() {
                     header_cb: (result) => {
                         res.setHeader((req.subscribe ? "Current-" : "") +
                             "Version", version_to_header(result.version))
+                        res.setHeader("Version-Type", "relative-wallclock")
                         if (result.content_type)
                             res.setHeader('Content-Type', result.content_type)
                     },
@@ -166,6 +167,7 @@ function create_braid_blob() {
                             delete update.content_type
                         }
                         update['Merge-Type'] = 'aww'
+                        update['Version-Type'] = 'relative-wallclock'
                         res.sendUpdate(update)
                     } : null
                 })
@@ -204,6 +206,7 @@ function create_braid_blob() {
                 peer: req.peer
             })
             res.setHeader("Current-Version", version_to_header(event != null ? [event] : []))
+            res.setHeader("Version-Type", "relative-wallclock")
             res.end('')
         } else if (req.method === 'DELETE') {
             await braid_blob.delete(params.key, {
@@ -234,6 +237,9 @@ function create_braid_blob() {
             if (params.content_type)
                 fetch_params.headers = { ...fetch_params.headers,
                     'Accept': params.content_type }
+            if (params.version || params.parents)
+                fetch_params.headers = { ...fetch_params.headers,
+                    'Version-Type': 'relative-wallclock' }
 
             var res = await braid_fetch(key.href, fetch_params)
 
@@ -345,6 +351,9 @@ function create_braid_blob() {
             if (params.content_type)
                 fetch_params.headers = { ...fetch_params.headers,
                     'Content-Type': params.content_type }
+            if (params.version)
+                fetch_params.headers = { ...fetch_params.headers,
+                    'Version-Type': 'relative-wallclock' }
 
             return await braid_fetch(key.href, fetch_params)
         }
@@ -358,8 +367,7 @@ function create_braid_blob() {
 
             var their_e = params.version ? params.version[0] :
                 // we'll give them a event id in this case
-                `${braid_blob.peer}-${max_seq('' + Date.now(),
-                    meta.event ? increment_seq(get_event_seq(meta.event)) : '')}`
+                create_event(meta.event)
 
             if (compare_events(their_e, meta.event) > 0) {
                 meta.event = their_e
@@ -591,37 +599,37 @@ function create_braid_blob() {
         return 0
     }
 
+    function create_event(current_event, max_entropy = 1000) {
+        var new_event = '' + Date.now()
+
+        var current_seq = get_event_seq(current_event)
+        if (compare_seqs(new_event, current_seq) > 0) return new_event
+
+        // Find smallest base-10 integer where compare_seqs(int, current_seq) >= 0
+        var base = seq_to_int(current_seq)
+        return '' + (base + 1 + Math.floor(Math.random() * max_entropy))
+    }
+
     function get_event_seq(e) {
         if (!e) return ''
 
         for (let i = e.length - 1; i >= 0; i--)
-            if (e[i] === '-') return e.slice(i + 1)
+            if (e[i] === '-') return i == 0 ? e : e.slice(i + 1)
         return e
     }
 
-    function increment_seq(s) {
-        if (!s) return '1'
-
-        let last = s[s.length - 1]
-        let rest = s.slice(0, -1)
-
-        if (last >= '0' && last <= '8')
-            return rest + String.fromCharCode(last.charCodeAt(0) + 1)
-        else
-            return increment_seq(rest) + '0'
-    }
-
-    function max_seq(a, b) {
+    function compare_seqs(a, b) {
         if (!a) a = ''
         if (!b) b = ''
 
-        if (compare_seqs(a, b) > 0) return a
-        return b
-    }
+        var a_neg = a[0] === '-'
+        var b_neg = b[0] === '-'
+        if (a_neg !== b_neg) return a_neg ? -1 : 1
 
-    function compare_seqs(a, b) {
-        if (!a) a = ''
-        if (!b) b = ''
+        // Both negative: compare magnitudes (reversed)
+        if (a_neg) {
+            var swap = a.slice(1); a = b.slice(1); b = swap
+        }
 
         if (a.length !== b.length) return a.length - b.length
         if (a < b) return -1
@@ -629,6 +637,35 @@ function create_braid_blob() {
         return 0
     }
 
+    // Smallest base-10 integer n where compare_seqs(String(n), s) >= 0
+    function seq_to_int(s) {
+        if (!s || s[0] === '-') return 0
+
+        var len = s.length
+        var min_of_len = Math.pow(10, len - 1) // e.g., len=3 -> 100
+        var max_of_len = Math.pow(10, len) - 1 // e.g., len=3 -> 999
+
+        if (s < String(min_of_len)) return min_of_len
+        if (s > String(max_of_len)) return max_of_len + 1
+
+        // s is in the base-10 range for this length
+        // scan for first non-digit > '9', increment prefix and pad zeros
+        var n = 0
+        for (var i = 0; i < len; i++) {
+            var c = s.charCodeAt(i)
+            if (c >= 48 && c <= 57) {
+                n = n * 10 + (c - 48)
+            } else if (c > 57) {
+                // non-digit > '9': increment prefix, pad rest with zeros
+                return (n + 1) * Math.pow(10, len - i)
+            } else {
+                // non-digit < '0': just pad rest with zeros
+                return n * Math.pow(10, len - i)
+            }
+        }
+        return n
+    }
+
     function ascii_ify(s) {
         return s.replace(/[^\x20-\x7E]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'))
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-blob",
-  "version": "0.0.68",
+  "version": "0.0.70",
   "description": "Library for collaborative blobs over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-blob",

package/relative-wallclock-version-type.md

@@ -0,0 +1,102 @@
+# Relative-Wallclock Version Type
+
+This document describes the **relative-wallclock** version type, which specifies how version identifiers are formatted and interpreted for resources using wallclock-based timestamps.
+
+## Overview
+
+The relative-wallclock version type uses millisecond timestamps as version identifiers. These timestamps generally correspond to wall-clock time (milliseconds since the Unix epoch), but can advance beyond wall-clock time when necessary to maintain monotonicity.
+
+## HTTP Header
+
+The relative-wallclock version type is indicated using the `Version-Type` header:
+
+```
+Version-Type: relative-wallclock
+```
+
+## Version Format
+
+Versions are numeric strings representing milliseconds since the Unix epoch:
+
+```
+"1768467700000"
+```
+
+Unlike some versioning schemes that include an agent/peer identifier (e.g., `"alice-1736625600000"`), relative-wallclock versions contain only the timestamp.
+
+## Version Generation
+
+When creating a new version, the timestamp is calculated as:
+
+```
+new_version = max(current_time_ms, current_version + random(1, 1000))
+```
+
+This ensures:
+
+1. **Monotonicity**: Versions always increase, even if the clock drifts backward
+2. **Entropy**: A small random number (between 1 and 1000) is added when the clock is behind, reducing collision probability when multiple peers write simultaneously
+3. **Approximate wall-clock correspondence**: Under normal conditions, versions reflect actual time
+
+## Comparison Procedure
+
+When comparing two versions `a` and `b`:
+
+1. **Compare as integers**: Parse the version strings as integers and compare numerically
+2. **Larger wins**: The version with the larger numeric value is considered newer
+
+```
+"1768467701000" > "1768467700000"  (numerically larger)
+```
+
+Note: Because versions are numeric strings of potentially different lengths, comparison should be done numerically, not lexicographically. However, in practice, millisecond timestamps from the same era will have the same number of digits.
+
+## Relationship to Merge Types
+
+The relative-wallclock version type specifies only the *format and interpretation* of version identifiers. It does not specify how conflicts are resolved when concurrent versions exist.
+
+Conflict resolution is handled by a **Merge Type** (specified via the `Merge-Type` header). For example, the [Arbitrary-Writer-Wins (AWW)](https://braid.org/protocol/merge-types/aww) merge type uses version comparison to deterministically select a winner.
+
+When used together:
+- `Version-Type: relative-wallclock` defines how to interpret and compare version strings
+- `Merge-Type: aww` defines that the higher version wins in a conflict
+
+## Example
+
+```http
+PUT /blob.png HTTP/1.1
+Version: "1768467702000"
+Version-Type: relative-wallclock
+Content-Type: image/png
+Merge-Type: aww
+Content-Length: 34567
+
+<binary data>
+```
+
+Response:
+
+```http
+HTTP/1.1 200 OK
+Current-Version: "1768467702000"
+Version-Type: relative-wallclock
+```
+
+## Properties
+
+- **Simple**: Version identifiers are just numbers
+- **Sortable**: Versions have a natural total ordering
+- **Distributed**: No coordination required between peers to generate versions
+- **Approximate causality**: Generally reflects wall-clock time, providing rough temporal ordering
+- **Collision-resistant**: Random entropy reduces concurrent write collisions
+
+## Security Considerations
+
+- **Clock manipulation**: A malicious peer could set their clock far in the future to generate versions that always win. Systems should consider rate-limiting or rejecting versions too far in the future.
+- **No authentication**: Version identifiers do not encode who created them. Authentication should be handled at a different layer.
+
+## References
+
+- [HTTP Resource Versioning](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-versions-03.txt)
+- [Merge Types](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-merge-types-00.txt)
+- [Arbitrary-Writer-Wins Merge Type](https://braid.org/protocol/merge-types/aww)