braid-blob 0.0.35 → 0.0.37

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,24 @@ function create_braid_blob() {
     }
 
     braid_blob.put = async (key, body, options = {}) => {
+        // What's the content type?
+        var content_type = options.content_type || options.accept || get_header(options.headers, 'content-type') || get_header(options.headers, 'accept')
+
         // 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 (content_type)
+                params.headers = { ...params.headers,
+                    'Content-Type': content_type }
 
             return await braid_fetch(key.href, params)
         }
@@ -136,8 +140,8 @@ function create_braid_blob() {
 
             // Update only the fields we want to change in metadata
             var meta_updates = { event: their_e }
-            if (options.content_type)
-                meta_updates.content_type = options.content_type
+            if (content_type)
+                meta_updates.content_type = content_type
 
             await update_meta(key, meta_updates)
             if (options.signal?.aborted) return
@@ -158,6 +162,9 @@ function create_braid_blob() {
     }
 
     braid_blob.get = async (key, options = {}) => {
+        // What's the content type?
+        var content_type = options.content_type || options.accept || get_header(options.headers, 'content-type') || get_header(options.headers, 'accept')
+
         // Handle URL case - make a remote GET request
         if (key instanceof URL) {
             var params = {
@@ -166,14 +173,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 (content_type)
+                params.headers = { ...params.headers,
+                    'Accept': 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 +198,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,16 +210,16 @@ function create_braid_blob() {
 
         var result = {
             version: [meta.event],
-            content_type: meta.content_type
+            content_type: meta.content_type || 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)
-        if (options.head) return
+            throw new Error('unknown version: ' + options.parents)
+        if (options.head) return result
 
         if (options.subscribe) {
             var subscribe_chain = Promise.resolve()
@@ -219,7 +237,7 @@ function create_braid_blob() {
                     options.my_subscribe({
                         body: update.body,
                         version: update.version,
-                        content_type: meta.content_type
+                        content_type: meta.content_type || content_type
                     })
                 }
             })
@@ -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 = {}) => {
+        // What's the content type?
+        var content_type = options.content_type || options.accept || get_header(options.headers, 'content-type') || get_header(options.headers, 'accept')
+
         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,14 @@ function create_braid_blob() {
 
             var a_ops = {
                 signal: options.signal,
+                headers: options.headers,
+                content_type,
                 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
                     }).then(a_first_put)
                 }
             }
@@ -392,11 +416,14 @@ function create_braid_blob() {
 
             var b_ops = {
                 signal: options.signal,
+                headers: options.headers,
+                content_type,
                 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
                     }).then(b_first_put)
                 }
             }
@@ -426,40 +453,55 @@ function create_braid_blob() {
             }
 
             async function connect() {
+                if (options.on_pre_connect) await options.on_pre_connect()
+
                 var ac = new AbortController()
                 disconnect = () => ac.abort()
 
                 try {
                     // Check if remote has our current version (simple fork-point check)
                     var local_result = await braid_blob.get(a, {
-                        signal: ac.signal
+                        signal: ac.signal,
+                        head: true,
+                        headers: options.headers,
+                        content_type
                     })
                     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
                         })
-                        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,
+                        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
+                                })
+                                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
@@ -472,14 +514,20 @@ function create_braid_blob() {
                     var b_ops = {
                         signal: ac.signal,
                         dont_retry: true,
+                        headers: options.headers,
+                        content_type,
                         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
                             })
                             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) {
@@ -499,6 +547,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)
@@ -616,6 +667,19 @@ 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]
+    }
+
     braid_blob.create_braid_blob = create_braid_blob
 
     return braid_blob

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-blob",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "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'))
             })()`
         })
 
@@ -1148,10 +1148,18 @@ runTest(
 )
 
 runTest(
-    "test sync does not disconnect unnecessarily",
+    "test sync connect does not read file body for version check",
     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 local_key = '/test-sync-no-read-' + Math.random().toString(36).slice(2)
+        var remote_key = 'test-sync-no-read-remote-' + Math.random().toString(36).slice(2)
+
+        // Put something on remote with SAME version as local, so no data needs to flow
+        var put_result = await braid_fetch(`/${remote_key}`, {
+            method: 'PUT',
+            version: ['same-version-123'],
+            body: 'same content'
+        })
+        if (!put_result.ok) return 'PUT status: ' + put_result.status
 
         var r1 = await braid_fetch(`/eval`, {
             method: 'POST',
@@ -1159,36 +1167,38 @@ runTest(
                 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}')
+                    // Put locally with SAME version - so when sync connects, no updates need to flow
+                    await braid_blob.put('${local_key}', Buffer.from('same content'), { version: ['same-version-123'] })
 
-                    // 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)
+                    // Wrap db.read to count calls for our specific key
+                    var read_count = 0
+                    var original_read = braid_blob.db.read
+                    braid_blob.db.read = async function(key) {
+                        if (key === '${local_key}') read_count++
+                        return original_read.call(this, key)
                     }
 
+                    var remote_url = new URL('http://localhost:' + req.socket.localPort + '/${remote_key}')
+
                     // Create an AbortController to stop the sync
                     var ac = new AbortController()
 
-                    // Start sync
+                    // Start sync - since both have same version, no updates should flow
                     braid_blob.sync('${local_key}', remote_url, { signal: ac.signal })
 
-                    // Wait for sync to establish and stabilize
-                    await new Promise(done => setTimeout(done, 500))
+                    // Wait for sync to establish connection
+                    await new Promise(done => setTimeout(done, 300))
 
                     // Stop sync
                     ac.abort()
 
-                    // Restore console.log
-                    console.log = original_log
+                    // Restore original read
+                    braid_blob.db.read = original_read
 
-                    // Should have zero disconnects during normal operation
-                    res.end(disconnect_count === 0 ? 'no disconnects' : 'disconnects: ' + disconnect_count)
+                    // db.read should not have been called since:
+                    // 1. Initial version check uses head:true (no body read)
+                    // 2. Both have same version so no updates flow
+                    res.end(read_count === 0 ? 'no reads' : 'reads: ' + read_count)
                 } catch (e) {
                     res.end('error: ' + e.message + ' ' + e.stack)
                 }
@@ -1196,7 +1206,7 @@ runTest(
         })
         return await r1.text()
     },
-    'no disconnects'
+    'no reads'
 )
 
 runTest(
@@ -1293,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']