braid-blob 0.0.67 → 0.0.69

package/README.md

@@ -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`); 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).
@@ -159,11 +166,9 @@ Returns `200 OK` even if the blob didn't exist.
 
 ### Understanding versions
 
-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)
+Versions are timestamps representing milliseconds past the epoch (e.g., `"1768467700000"`). If the current time is less than the latest known version, a small random number is added to the current version to provide entropy in case multiple peers are writing simultaneously.
 
-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.
+Conflicts resolve using ["arbitrary-writer-wins" (AWW)](https://braid.org/protocol/merge-types/aww): the version with the highest timestamp wins.
 
 
 
@@ -178,97 +183,95 @@ var braid_blob = require('braid-blob')
 braid_blob.db_folder = './braid-blobs'       // Default: ./braid-blobs
 ```
 
-### Serve blobs to HTTP Requests (GET, PUT, and DELETE)
+### Examples
 
-Your app becomes a blob server with:
+#### Get a blob
 
 ```javascript
-braid_blob.serve(req, res, params)
+// Get a local blob:
+var {body, version, content_type} = await braid_blob.get('foo')
+
+// Get a remote blob:
+var {body, version, content_type} = await braid_blob.get(new URL('https://foo.bar/baz'))
+
+// Get a specific version of a remote blob:
+var {body} = await braid_blob.get(
+    new URL('https://foo.bar/baz'),
+    {version: ['5zb2sjdstmk-1768093765048']}
+)
+
+// To subscribe to a remote blob, without storing updates locally:
+await braid_blob.get(new URL('https://foo.bar/baz'), {
+    subscribe: (update) => {
+        console.log('Got update:', update.version, update.content_type)
+        // update.body contains the new blob data
+    }
+})
+
+// To mirror a remote blob to local storage (bidirectional sync):
+var ac = new AbortController()
+braid_blob.sync('local-key', new URL('https://foo.bar/baz'), {signal: ac.signal})
+// Later, stop syncing:
+ac.abort()
 ```
 
-This will synchronize the client issuing the given request and response with its blob on disk.
+Note: `.get()` with `subscribe` receives updates but does not store them locally.  `.sync()` performs two subscriptions (local↔remote) plus auto-forwards updates in both directions.
 
-Parameters:
-- `req` - HTTP request object
-- `res` - HTTP response object
-- `params` - Optional configuration object
-  - `key` - The blob on disk to sync with (default: `req.url`)
-
-### Sync a remotely served blob to disk
-
-Your app becomes a blob client with:
+#### Put a blob
 
 ```javascript
-braid_blob.sync(key, url, params)
+// Write to a local blob:
+await braid_blob.put('foo', Buffer.from('hello'), {content_type: 'text/plain'})
+
+// Write to a remote blob:
+await braid_blob.put(
+    new URL('https://foo.bar/baz'),
+    Buffer.from('hello'),
+    {content_type: 'text/plain'}
+)
 ```
 
-Synchronizes a remote URL to its blob on disk.
-
-Parameters:
-- `key` - The blob on disk (string)
-- `url` - Remote URL (URL object)
-- `params` - Optional configuration object
-  - `signal` - AbortSignal for cancellation (use to stop sync)
-  - `content_type` - Content type for requests
-
-### Read, Write or Delete a blob
-
-#### Read a local or remote blob
+#### Delete a blob
 
 ```javascript
-braid_blob.get(key, params)
+// Delete a local blob:
+await braid_blob.delete('foo')
+
+// Delete a remote blob:
+await braid_blob.delete(new URL('https://foo.bar/baz'))
 ```
 
-Retrieves a blob from local storage or a remote URL.
+### API Reference
 
-Examples:
-```javascript
-// Get the current contents of a local blob:
-braid_blob.get('foo').body
+#### braid_blob.get(key, params)
 
-// Get the contents of a remote blob:
-braid_blob.get(new URL('https://foo.bar/baz')).body
-
-// Get an old version of a remote blob:
-braid_blob.get(
-   new URL('https://foo.bar/baz'),
-   {version: ["5zb2sjdstmk-1768093765048"]}
-).body
-```
+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` - Version ID to check existence (use with `head: true`)
-  - `parent` - Version ID; when subscribing, only receive updates newer than this
-  - `subscribe` - Callback function for real-time updates
-  - `head` - If true, returns only metadata (version, content_type) without body
-  - `content_type` - Content type for the request
-  - `signal` - AbortSignal for cancellation
+  - `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']`)
+  - `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)
+  - `signal` - AbortSignal to cancel the request or stop a subscription
 
-Returns: `{version, body, content_type}` object, or `null` if not found.
+Returns: `{version, body, content_type}` object, or `null` if the blob doesn't exist.  When subscribing to a remote URL, returns the fetch response object; updates are delivered via the callback.
 
-#### Write a local or remote blob
+#### braid_blob.put(key, body, params)
 
-```javascript
-braid_blob.put(key, body, params)
-```
-
-Writes a blob to local storage or a remote URL.  Any other peers synchronizing with this blob (via `.serve()`, `.sync()`, or `.get(.., {subscribe: ..}`) will be updated.
+Writes a blob to local storage or a remote URL.  Any other peers synchronizing with this blob (via `.serve()`, `.sync()`, or `.get(.., {subscribe: ..})`) will be updated.
 
 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` - Buffer or data to store
+- `body` - The data to store (Buffer, ArrayBuffer, or Uint8Array)
 - `params` - Optional configuration object
-  - `version` - Version identifier
-  - `content_type` - Content type of the blob
-  - `signal` - AbortSignal for cancellation
+  - `version` - Specify a version ID for this write (e.g., `['my-version-1']`); 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
 
-#### Delete a local or remote blob
-
-```javascript
-braid_blob.delete(key, params)
-```
+#### braid_blob.delete(key, params)
 
 Deletes a blob from local storage or a remote URL.
 
@@ -277,6 +280,27 @@ Parameters:
 - `params` - Optional configuration object
   - `signal` - AbortSignal for cancellation
 
+#### braid_blob.sync(key, url, params)
+
+Synchronizes a remote URL bidirectionally with a local blob on disk.  This performs two subscriptions (one to the remote, one to the local blob) and auto-forwards updates in both directions.
+
+Parameters:
+- `key` - The local blob on disk (string)
+- `url` - Remote URL (URL object)
+- `params` - Optional configuration object
+  - `signal` - AbortSignal for cancellation (use to stop sync)
+  - `content_type` - Content type for requests
+
+#### braid_blob.serve(req, res, params)
+
+Serves blob requests over HTTP.  Synchronizes the client issuing the given request with its blob on disk.
+
+Parameters:
+- `req` - HTTP request object
+- `res` - HTTP response object
+- `params` - Optional configuration object
+  - `key` - The blob on disk to sync with (default: the path from `req.url`)
+
 ## Browser Client API
 
 A simple browser client is included for subscribing to blob updates.

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.67",
+  "version": "0.0.69",
   "description": "Library for collaborative blobs over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-blob",