braid-blob 0.0.36 → 0.0.38

package/AI-README.md

@@ -188,7 +188,7 @@ SUBSCRIPTION_BEHAVIOR:
   - Subscription callback receives: {body: Buffer, version: [string], content_type: string}
 
 ERROR_HANDLING:
-  - Throws "unkown version: {version}" if requested version > local version
+  - Throws "unknown version: {version}" if requested version > local version
   - Returns 309 status code via serve() when version unknown
 ```
 
@@ -426,7 +426,7 @@ url-file-db (^0.0.15):
 ## ERROR_CONDITIONS
 
 ```
-"unkown version: {version}"
+"unknown version: {version}"
   - GET with version/parents newer than local version
   - Results in 309 status via serve()
 

package/README.md

@@ -88,6 +88,49 @@ Handles HTTP requests for blob storage and synchronization.
 - `PUT` - Store/update a blob
 - `DELETE` - Remove a blob
 
+### `braid_blob.get(key, options)`
+
+Retrieves a blob from local storage or a remote URL.
+
+**Parameters:**
+- `key` - Local storage key (string) or remote URL (URL object)
+- `options` - Optional configuration object
+  - `version` - Request a specific version
+  - `parents` - Version parents for subscription fork-point
+  - `subscribe` - Callback function for real-time updates
+  - `head` - If true, returns only metadata (version, content_type) without body
+  - `content_type` / `accept` - Content type for the request
+  - `signal` - AbortSignal for cancellation
+
+**Returns:** `{version, body, content_type}` object, or `null` if not found.
+
+### `braid_blob.put(key, body, options)`
+
+Stores a blob to local storage or a remote URL.
+
+**Parameters:**
+- `key` - Local storage key (string) or remote URL (URL object)
+- `body` - Buffer or data to store
+- `options` - Optional configuration object
+  - `version` - Version identifier
+  - `content_type` / `accept` - Content type of the blob
+  - `signal` - AbortSignal for cancellation
+
+### `braid_blob.sync(a, b, options)`
+
+Bidirectionally synchronizes blobs between two endpoints (local keys or URLs).
+
+**Parameters:**
+- `a` - First endpoint (local key or URL)
+- `b` - Second endpoint (local key or URL)
+- `options` - Optional configuration object
+  - `signal` - AbortSignal for cancellation (use to stop sync)
+  - `content_type` / `accept` - Content type for requests
+  - `on_pre_connect` - Async callback before connection attempt
+  - `on_disconnect` - Callback when connection drops
+  - `on_unauthorized` - Callback on 401/403 responses
+  - `on_res` - Callback receiving the response object
+
 ## Testing
 
 ### to run unit tests:

package/index.js

@@ -92,20 +92,23 @@ function create_braid_blob() {
     }
 
     braid_blob.put = async (key, body, options = {}) => {
+        options = normalize_options(options)
+
         // Handle URL case - make a remote PUT request
         if (key instanceof URL) {
 
             var params = {
                 method: 'PUT',
                 signal: options.signal,
-                retry: () => true,
                 body: body
             }
+            if (!options.dont_retry)
+                params.retry = () => true
             for (var x of ['headers', 'version', 'peer'])
                 if (options[x] != null) params[x] = options[x]
-            if (options.content_type) {
-                params.headers = { ...params.headers, 'Content-Type': options.content_type }
-            }
+            if (options.content_type)
+                params.headers = { ...params.headers,
+                    'Content-Type': options.content_type }
 
             return await braid_fetch(key.href, params)
         }
@@ -146,7 +149,7 @@ function create_braid_blob() {
             // (except the peer which made the PUT request itself)
             if (braid_blob.key_to_subs[key])
                 for (var [peer, sub] of braid_blob.key_to_subs[key].entries())
-                    if (peer !== options.peer)
+                    if (!options.peer || options.peer !== peer)
                         sub.sendUpdate({
                             version: [meta.event],
                             'Merge-Type': 'aww',
@@ -158,6 +161,8 @@ function create_braid_blob() {
     }
 
     braid_blob.get = async (key, options = {}) => {
+        options = normalize_options(options)
+
         // Handle URL case - make a remote GET request
         if (key instanceof URL) {
             var params = {
@@ -166,14 +171,24 @@ function create_braid_blob() {
                 heartbeats: 120,
             }
             if (!options.dont_retry) {
-                params.retry = (res) => res.status !== 404
+                params.retry = (res) => res.status !== 309 &&
+                    res.status !== 404 && res.status !== 406
             }
+            if (options.head) params.method = 'HEAD'
             for (var x of ['headers', 'parents', 'version', 'peer'])
                 if (options[x] != null) params[x] = options[x]
+            if (options.content_type)
+                params.headers = { ...params.headers,
+                    'Accept': options.content_type }
 
             var res = await braid_fetch(key.href, params)
 
-            if (res.status === 404) return null
+            if (!res.ok) return null
+
+            var result = {}
+            if (res.version) result.version = res.version
+
+            if (options.head) return result
 
             if (options.subscribe) {
                 res.subscribe(async update => {
@@ -181,7 +196,8 @@ function create_braid_blob() {
                 }, e => options.on_error?.(e))
                 return res
             } else {
-                return await res.arrayBuffer()
+                result.body = await res.arrayBuffer()
+                return result
             }
         }
 
@@ -192,15 +208,15 @@ function create_braid_blob() {
 
         var result = {
             version: [meta.event],
-            content_type: meta.content_type
+            content_type: meta.content_type || options.content_type
         }
         if (options.header_cb) await options.header_cb(result)
         if (options.signal?.aborted) return
         // Check if requested version/parents is newer than what we have - if so, we don't have it
         if (options.version && options.version.length && compare_events(options.version[0], meta.event) > 0)
-            throw new Error('unkown version: ' + options.version)
+            throw new Error('unknown version: ' + options.version)
         if (options.parents && options.parents.length && compare_events(options.parents[0], meta.event) > 0)
-            throw new Error('unkown version: ' + options.parents)
+            throw new Error('unknown version: ' + options.parents)
         if (options.head) return result
 
         if (options.subscribe) {
@@ -219,7 +235,7 @@ function create_braid_blob() {
                     options.my_subscribe({
                         body: update.body,
                         version: update.version,
-                        content_type: meta.content_type
+                        content_type: meta.content_type || options.content_type
                     })
                 }
             })
@@ -253,6 +269,8 @@ function create_braid_blob() {
     }
 
     braid_blob.delete = async (key, options = {}) => {
+        options = normalize_options(options)
+
         // Handle URL case - make a remote DELETE request
         if (key instanceof URL) {
 
@@ -326,7 +344,7 @@ function create_braid_blob() {
                         } : null
                     })
                 } catch (e) {
-                    if (e.message && e.message.startsWith('unkown version')) {
+                    if (e.message && e.message.startsWith('unknown version')) {
                         // Server doesn't have this version
                         res.statusCode = 309
                         res.statusMessage = 'Version Unknown Here'
@@ -370,6 +388,9 @@ function create_braid_blob() {
     }
 
     braid_blob.sync = (a, b, options = {}) => {
+        options = normalize_options(options)
+        if (!options.peer) options.peer = Math.random().toString(36).slice(2)
+
         if ((a instanceof URL) === (b instanceof URL)) {
             // Both are URLs or both are local keys
             var a_first_put, b_first_put
@@ -378,11 +399,16 @@ function create_braid_blob() {
 
             var a_ops = {
                 signal: options.signal,
+                headers: options.headers,
+                content_type: options.content_type,
+                peer: options.peer,
                 subscribe: update => {
                     braid_blob.put(b, update.body, {
                         signal: options.signal,
                         version: update.version,
-                        content_type: update.headers?.['content-type']
+                        headers: options.headers,
+                        content_type: update.content_type,
+                        peer: options.peer,
                     }).then(a_first_put)
                 }
             }
@@ -392,11 +418,16 @@ function create_braid_blob() {
 
             var b_ops = {
                 signal: options.signal,
+                headers: options.headers,
+                content_type: options.content_type,
+                peer: options.peer,
                 subscribe: update => {
                     braid_blob.put(a, update.body, {
                         signal: options.signal,
                         version: update.version,
-                        content_type: update.headers?.['content-type']
+                        headers: options.headers,
+                        content_type: update.content_type,
+                        peer: options.peer,
                     }).then(b_first_put)
                 }
             }
@@ -426,6 +457,8 @@ function create_braid_blob() {
             }
 
             async function connect() {
+                if (options.on_pre_connect) await options.on_pre_connect()
+
                 var ac = new AbortController()
                 disconnect = () => ac.abort()
 
@@ -433,34 +466,50 @@ function create_braid_blob() {
                     // Check if remote has our current version (simple fork-point check)
                     var local_result = await braid_blob.get(a, {
                         signal: ac.signal,
-                        head: true
+                        head: true,
+                        headers: options.headers,
+                        content_type: options.content_type,
+                        peer: options.peer,
                     })
                     var local_version = local_result ? local_result.version : null
                     var server_has_our_version = false
 
                     if (local_version) {
-                        // Check if server has our version
-                        var r = await braid_fetch(b.href, {
+                        var r = await braid_blob.get(b, {
                             signal: ac.signal,
-                            method: "HEAD",
-                            version: local_version
+                            head: true,
+                            dont_retry: true,
+                            version: local_version,
+                            headers: options.headers,
+                            content_type: options.content_type,
+                            peer: options.peer,
                         })
-                        server_has_our_version = r.ok
+                        server_has_our_version = !!r
                     }
 
                     // Local -> remote: subscribe to future local changes
                     var a_ops = {
                         signal: ac.signal,
-                        subscribe: update => {
-                            braid_blob.put(b, update.body, {
-                                signal: ac.signal,
-                                version: update.version,
-                                content_type: update.content_type
-                            }).then(local_first_put).catch(e => {
-                                if (e.name === 'AbortError') {
-                                    // ignore
-                                } else throw e
-                            })
+                        headers: options.headers,
+                        content_type: options.content_type,
+                        peer: options.peer,
+                        subscribe: async update => {
+                            try {
+                                var x = await braid_blob.put(b, update.body, {
+                                    signal: ac.signal,
+                                    dont_retry: true,
+                                    version: update.version,
+                                    headers: options.headers,
+                                    content_type: update.content_type,
+                                    peer: options.peer,
+                                })
+                                if (x.ok) local_first_put()
+                                else if (x.status === 401 || x.status === 403) {
+                                    await options.on_unauthorized?.()
+                                } else throw new Error('failed to PUT: ' + x.status)
+                            } catch (e) {
+                                if (e.name !== 'AbortError') throw e
+                            }
                         }
                     }
                     // Only set parents if server already has our version
@@ -473,14 +522,22 @@ function create_braid_blob() {
                     var b_ops = {
                         signal: ac.signal,
                         dont_retry: true,
+                        headers: options.headers,
+                        content_type: options.content_type,
+                        peer: options.peer,
                         subscribe: async update => {
                             await braid_blob.put(a, update.body, {
                                 version: update.version,
-                                content_type: update.headers?.['content-type']
+                                headers: options.headers,
+                                content_type: update.content_type,
+                                peer: options.peer,
                             })
                             remote_first_put()
                         },
-                        on_error: handle_error
+                        on_error: e => {
+                            options.on_disconnect?.()
+                            handle_error(e)
+                        }
                     }
                     // Use fork-point (parents) to avoid receiving data we already have
                     if (local_version) {
@@ -500,6 +557,9 @@ function create_braid_blob() {
                         disconnect()
                         connect()
                     }
+
+                    options.on_res?.(remote_res)
+
                     // Otherwise, on_error will call handle_error when connection drops
                 } catch (e) {
                     handle_error(e)
@@ -617,6 +677,59 @@ function create_braid_blob() {
         }
     }
 
+    function get_header(headers, key) {
+        if (!headers) return
+
+        // optimization..
+        if (headers.hasOwnProperty(key))
+            return headers[key]
+
+        var lowerKey = key.toLowerCase()
+        for (var headerKey of Object.keys(headers))
+            if (headerKey.toLowerCase() === lowerKey)
+                return headers[headerKey]
+    }
+
+    function normalize_options(options = {}) {
+        if (!normalize_options.special) {
+            normalize_options.special = {
+                version: 'version',
+                parents: 'parents',
+                'content-type': 'content_type',
+                accept: 'content_type',
+                peer: 'peer',
+            }
+        }
+
+        var normalized = {}
+        Object.assign(normalized, options)
+
+        // Normalize top-level accept to content_type
+        if (options.accept) {
+            normalized.content_type = options.accept
+            delete normalized.accept
+        }
+
+        if (options.headers) {
+            normalized.headers = {}
+            for (var [k, v] of (options.headers instanceof Headers ?
+                options.headers.entries() :
+                Object.entries(options.headers))) {
+                var s = normalize_options.special[k]
+                if (s) normalized[s] = v
+                else normalized.headers[k] = v
+            }
+        }
+
+        // Normalize version/parents strings to arrays
+        if (typeof normalized.version === 'string')
+            normalized.version = JSON.parse('[' + normalized.version + ']')
+        if (typeof normalized.parents === 'string')
+            normalized.parents = JSON.parse('[' + normalized.parents + ']')
+
+        return normalized
+    }
+
     braid_blob.create_braid_blob = create_braid_blob
 
     return braid_blob

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-blob",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "description": "Library for collaborative blobs over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-blob",
@@ -10,6 +10,6 @@
     "test:browser": "node test/test.js --browser"
   },
   "dependencies": {
-    "braid-http": "~1.3.83"
+    "braid-http": "~1.3.84"
   }
 }

package/test/tests.js

@@ -918,7 +918,7 @@ runTest(
                 var braid_blob = require(\`\${__dirname}/../index.js\`)
                 var url = new URL('http://localhost:' + req.socket.localPort + '/${key}')
                 var result = await braid_blob.get(url)
-                res.end(Buffer.from(result).toString('utf8'))
+                res.end(Buffer.from(result.body).toString('utf8'))
             })()`
         })
 
@@ -1147,58 +1147,6 @@ runTest(
     'shared content'
 )
 
-runTest(
-    "test sync does not disconnect unnecessarily",
-    async () => {
-        var local_key = 'test-sync-no-disconnect-local-' + Math.random().toString(36).slice(2)
-        var remote_key = 'test-sync-no-disconnect-remote-' + Math.random().toString(36).slice(2)
-
-        var r1 = await braid_fetch(`/eval`, {
-            method: 'POST',
-            body: `void (async () => {
-                try {
-                    var braid_blob = require(\`\${__dirname}/../index.js\`)
-
-                    // Put something locally first
-                    await braid_blob.put('${local_key}', Buffer.from('local content'), { version: ['600'] })
-
-                    var remote_url = new URL('http://localhost:' + req.socket.localPort + '/${remote_key}')
-
-                    // Capture console.log to count disconnects
-                    var disconnect_count = 0
-                    var original_log = console.log
-                    console.log = function(...args) {
-                        if (args[0]?.includes?.('disconnected')) disconnect_count++
-                        original_log.apply(console, args)
-                    }
-
-                    // Create an AbortController to stop the sync
-                    var ac = new AbortController()
-
-                    // Start sync
-                    braid_blob.sync('${local_key}', remote_url, { signal: ac.signal })
-
-                    // Wait for sync to establish and stabilize
-                    await new Promise(done => setTimeout(done, 500))
-
-                    // Stop sync
-                    ac.abort()
-
-                    // Restore console.log
-                    console.log = original_log
-
-                    // Should have zero disconnects during normal operation
-                    res.end(disconnect_count === 0 ? 'no disconnects' : 'disconnects: ' + disconnect_count)
-                } catch (e) {
-                    res.end('error: ' + e.message + ' ' + e.stack)
-                }
-            })()`
-        })
-        return await r1.text()
-    },
-    'no disconnects'
-)
-
 runTest(
     "test sync connect does not read file body for version check",
     async () => {
@@ -1355,7 +1303,7 @@ runTest(
         })
 
         // Try to subscribe with parents 200 (newer than what server has)
-        // This triggers the "unkown version" error which gets caught and returns 309
+        // This triggers the "unknown version" error which gets caught and returns 309
         var r = await braid_fetch(`/${key}`, {
             subscribe: true,
             parents: ['200']