braid-blob 0.0.53 → 0.0.55

package/README.md

@@ -20,39 +20,27 @@ require('http').createServer((req, res) => {
 }).listen(8888)
 ```
 
-That's it! You now have a blob synchronization server.
+That's it! You now have a blob synchronization server. Upload an image:
 
-### Usage Examples
-
-First let's upload a file:
 ```bash
-curl -X PUT -H "Content-Type: image/png" -T blob.png http://localhost:8888/image.png
+curl -X PUT -H "Content-Type: image/png" -T blob.png http://localhost:8888/blob.png
 ```
 
-View image in browser at http://localhost:8888/image.png
+Then view it at http://localhost:8888/blob.png
 
-To see updates, let's do a textual example for easy viewing:
+### Demo
 
-```
-curl -X PUT -H "Content-Type: text/plain" -d "hello" http://localhost:8888/text
-```
-
-Next, subscribe for updates:
-```
-curl -H "Subscribe: true" http://localhost:8888/text
-```
+Run the demo server:
 
-Now, in another terminal, write over the file:
 ```bash
-curl -X PUT -H "Content-Type: text/plain" -d "world" http://localhost:8888/text
+node server-demo.js
 ```
 
-Should see activity in the first terminal showing the update.
+Then open http://localhost:8888 in your browser. You can drag and drop images to upload them, and open multiple browser windows to see real-time sync in action.
 
-```
-# Delete a file
-curl -X DELETE http://localhost:8888/text
-```
+<!-- TODO: Add demo video
+![Demo](demo.mp4)
+-->
 
 ## API
 
@@ -61,16 +49,8 @@ curl -X DELETE http://localhost:8888/text
 ```javascript
 var braid_blob = require('braid-blob')
 
-// Set custom blob storage location (default: './braid-blob-db')
-// This uses url-file-db for efficient URL-to-file mapping
-braid_blob.db_folder = './custom_files_folder'
-
-// Set custom metadata storage location (default: './braid-blob-meta')
-// Stores version metadata and peer information
-braid_blob.meta_folder = './custom_meta_folder'
-
-// Set custom peer ID (default: auto-generated and persisted)
-braid_blob.peer = 'my-server-id'
+// Set custom storage location (default: './braid-blobs')
+braid_blob.db_folder = './my-blobs'
 ```
 
 ### `braid_blob.serve(req, res, options)`
@@ -88,6 +68,21 @@ Handles HTTP requests for blob storage and synchronization.
 - `PUT` - Store/update a blob
 - `DELETE` - Remove a blob
 
+### `braid_blob.sync(key, url, options)`
+
+Bidirectionally synchronizes a blob between local storage and a remote URL.
+
+**Parameters:**
+- `key` - Local storage key (string)
+- `url` - Remote URL (URL object)
+- `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
+
 ### `braid_blob.get(key, options)`
 
 Retrieves a blob from local storage or a remote URL.
@@ -113,30 +108,63 @@ Stores a blob to local storage or a remote URL.
 - `body` - Buffer or data to store
 - `options` - Optional configuration object
   - `version` - Version identifier
-  - `content_type` / `accept` - Content type of the blob
+  - `content_type` - Content type of the blob
   - `signal` - AbortSignal for cancellation
 
-### `braid_blob.sync(a, b, options)`
+### `braid_blob.delete(key, options)`
 
-Bidirectionally synchronizes blobs between two endpoints (local keys or URLs).
+Deletes a blob from local storage or a remote URL.
 
 **Parameters:**
-- `a` - First endpoint (local key or URL)
-- `b` - Second endpoint (local key or URL)
+- `key` - Local storage key (string) or remote URL (URL object)
 - `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
+  - `signal` - AbortSignal for cancellation
+
+## Browser Client
+
+A simple browser client is included for subscribing to blob updates.
+
+```html
+<script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
+<script src="/client.js"></script>
+<script>
+    braid_blob_client('http://localhost:8888/blob.png', {
+        on_update: (blob, content_type, version) => {
+            // Called whenever the blob is updated
+            var url = URL.createObjectURL(new Blob([blob], { type: content_type }))
+            document.getElementById('image').src = url
+        },
+        on_delete: () => console.log('Blob was deleted'),
+        on_error: (e) => console.error('Error:', e)
+    })
+</script>
+```
+
+### `braid_blob_client(url, options)`
+
+Subscribes to a blob endpoint and receives updates.
+
+**Parameters:**
+- `url` - The blob endpoint URL
+- `options` - Configuration object
+  - `on_update(blob, content_type, version)` - Callback for updates
+  - `on_delete` - Callback when blob is deleted
+  - `on_error` - Callback for errors
   - `on_res` - Callback receiving the response object
 
+**Returns:** `{ stop }` - Call `stop()` to unsubscribe.
+
 ## Testing
 
-### to run unit tests:
-first run the test server:
+```bash
+npm install
+node test/test.js
+```
+
+Or run tests in the browser:
 
-    npm install
-    node test/server.js
+```bash
+node test/test.js -b
+```
 
-then open http://localhost:8889/test.html, and the boxes should turn green as the tests pass.
+Then open http://localhost:8889/test.html

package/client-demo.html

@@ -0,0 +1,146 @@
+<body style="margin: 0; padding: 20px; font-family: sans-serif;">
+    <div id="drop_overlay" style="display: none; position: fixed; top: 0; left: 0; right: 0; bottom: 0; background: rgba(0, 100, 200, 0.8); z-index: 1000; justify-content: center; align-items: center;">
+        <div style="color: white; font-size: 24px; text-align: center;">
+            <div style="font-size: 48px; margin-bottom: 20px;">Drop file here</div>
+            <div>to upload to <span id="drop_url"></span></div>
+        </div>
+    </div>
+    <h2>Braid Blob Client Demo</h2>
+    <p>
+        <label>URL: <input type="text" id="url_input" style="width: 400px;" /></label>
+    </p>
+    <p>Version: <code id="version_display">-</code></p>
+    <p>Content-Type: <code id="content_type_display">-</code></p>
+    <div id="image_container">
+        <img id="blob_image" style="max-width: 100%; border: 1px solid #ccc;" />
+    </div>
+    <p id="status">Enter a URL and click Connect</p>
+</body>
+<script src="https://unpkg.com/braid-http@~1.3/braid-http-client.js"></script>
+<script src="/client.js"></script>
+<script>
+    var current_object_url = null
+    var current_client = null
+    var current_blob_url = null
+
+    // Initialize URL input from query parameter, or default to /test_blob
+    var params = new URLSearchParams(location.search)
+    var initial_url = params.get('url') || `${location.origin}/blob.png`
+    document.getElementById('url_input').value = initial_url
+
+    function connect(blob_url) {
+        current_blob_url = blob_url
+        // Stop existing subscription
+        if (current_client) {
+            current_client.stop()
+            current_client = null
+        }
+
+        // Clear previous image
+        if (current_object_url) {
+            URL.revokeObjectURL(current_object_url)
+            current_object_url = null
+        }
+        document.getElementById('blob_image').src = ''
+        document.getElementById('version_display').textContent = '-'
+        document.getElementById('content_type_display').textContent = '-'
+        document.getElementById('status').textContent = 'Connecting...'
+
+        current_client = braid_blob_client(blob_url, {
+            on_update: (blob, content_type, version) => {
+                document.getElementById('status').textContent = ''
+                document.getElementById('version_display').textContent =
+                    version ? JSON.stringify(version) : '-'
+                document.getElementById('content_type_display').textContent =
+                    content_type || '-'
+
+                // Revoke old object URL to free memory
+                if (current_object_url) {
+                    URL.revokeObjectURL(current_object_url)
+                }
+
+                // Create a blob URL from the binary data and display it
+                var image_blob = new Blob([blob], { type: content_type || 'image/png' })
+                current_object_url = URL.createObjectURL(image_blob)
+                document.getElementById('blob_image').src = current_object_url
+            },
+            on_error: (e) => {
+                document.getElementById('status').textContent = 'Connecting...'
+            },
+            on_delete: () => {
+                document.getElementById('status').textContent = 'Blob deleted'
+                document.getElementById('blob_image').src = ''
+                if (current_object_url) {
+                    URL.revokeObjectURL(current_object_url)
+                    current_object_url = null
+                }
+            }
+        })
+    }
+
+    document.getElementById('url_input').onkeydown = (e) => {
+        if (e.key === 'Enter') {
+            var url = document.getElementById('url_input').value.trim()
+            if (url) connect(url)
+        }
+    }
+
+    // Auto-connect on load
+    connect(initial_url)
+
+    // Drag and drop handling
+    var drop_overlay = document.getElementById('drop_overlay')
+    var drag_counter = 0
+
+    document.addEventListener('dragenter', (e) => {
+        e.preventDefault()
+        drag_counter++
+        if (drag_counter === 1) {
+            document.getElementById('drop_url').textContent = current_blob_url || 'the current URL'
+            drop_overlay.style.display = 'flex'
+        }
+    })
+
+    document.addEventListener('dragleave', (e) => {
+        e.preventDefault()
+        drag_counter--
+        if (drag_counter === 0) {
+            drop_overlay.style.display = 'none'
+        }
+    })
+
+    document.addEventListener('dragover', (e) => {
+        e.preventDefault()
+    })
+
+    document.addEventListener('drop', async (e) => {
+        e.preventDefault()
+        drag_counter = 0
+        drop_overlay.style.display = 'none'
+
+        if (!current_blob_url) {
+            alert('Please connect to a URL first')
+            return
+        }
+
+        var file = e.dataTransfer.files[0]
+        if (!file) return
+
+        document.getElementById('status').textContent = 'Uploading...'
+
+        try {
+            var response = await fetch(current_blob_url, {
+                method: 'PUT',
+                headers: { 'Content-Type': file.type || 'application/octet-stream' },
+                body: file
+            })
+            if (!response.ok) {
+                document.getElementById('status').textContent = 'Upload failed: ' + response.status
+            }
+            // The subscription will automatically show the new image
+        } catch (err) {
+            document.getElementById('status').textContent = 'Upload error: ' + err.message
+            console.error('Upload error:', err)
+        }
+    })
+</script>

package/client.js

@@ -0,0 +1,79 @@
+// Braid-Blob Client
+// requires braid-http@~1.3/braid-http-client.js
+//
+// Usage:
+//   braid_blob_client(url, {
+//       on_update: (blob, content_type, version) => {
+//           // Called whenever there's a new version of the blob
+//           console.log('New blob:', blob, content_type, version)
+//       }
+//   })
+//
+// Returns: { stop } - call stop() to unsubscribe
+//
+function braid_blob_client(url, options = {}) {
+    var ac = new AbortController()
+    var peer = Math.random().toString(36).substr(2)
+    var current_version = null
+
+    braid_fetch(url, {
+        headers: { "Merge-Type": "aww" },
+        subscribe: true,
+        retry: () => true,
+        peer,
+        signal: ac.signal
+    }).then(res => {
+        if (options.on_res) options.on_res(res)
+
+        res.subscribe(async update => {
+            if (update.status === 404) {
+                current_version = null
+                if (options.on_delete) options.on_delete()
+                return
+            }
+
+            var content_type = update.extra_headers?.['content-type']
+            var version = update.version?.[0]
+
+            // Only update if version is newer
+            if (compare_events(version, current_version) > 0) {
+                current_version = version
+                if (options.on_update) options.on_update(update.body, content_type, update.version)
+            }
+        }, options.on_error || (e => console.error('braid_blob_client error:', e)))
+    }).catch(options.on_error || (e => console.error('braid_blob_client error:', e)))
+
+    return {
+        stop: () => ac.abort()
+    }
+
+    function compare_events(a, b) {
+        if (!a) a = ''
+        if (!b) b = ''
+
+        var c = compare_seqs(get_event_seq(a), get_event_seq(b))
+        if (c) return c
+
+        if (a < b) return -1
+        if (a > b) return 1
+        return 0
+    }
+
+    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)
+        return e
+    }
+
+    function compare_seqs(a, b) {
+        if (!a) a = ''
+        if (!b) b = ''
+
+        if (a.length !== b.length) return a.length - b.length
+        if (a < b) return -1
+        if (a > b) return 1
+        return 0
+    }
+}

package/package.json

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

package/server-demo.js

@@ -3,22 +3,40 @@ var port = process.argv[2] || 8888
 var braid_blob = require(`${__dirname}/index.js`)
 
 // TODO: set a custom storage base
-// (the default is ./braid-blob-files)
+// (the default is ./braid-blobs)
 //
 // braid_blob.db_folder = './custom_files_folder'
-// braid_blob.meta_folder = './custom_meta_folder'
 
 braid_blob.init()
 
 var server = require("http").createServer(async (req, res) => {
     console.log(`${req.method} ${req.url}`)
 
+    var url = req.url.split('?')[0]
+
+    if (url === '/client.js') {
+        res.writeHead(200, {
+            "Content-Type": "text/javascript",
+            "Cache-Control": "no-cache"
+        })
+        require("fs").createReadStream(`${__dirname}/client.js`).pipe(res)
+        return
+    }
+
+    if (url === '/') {
+        res.writeHead(200, {
+            "Content-Type": "text/html",
+            "Cache-Control": "no-cache"
+        })
+        require("fs").createReadStream(`${__dirname}/client-demo.html`).pipe(res)
+        return
+    }
+
     braid_blob.serve(req, res)
 })
 
 server.listen(port, () => {
-    console.log(`server started on port ${port}`)
-    console.log(`files stored in: ${braid_blob.db_folder}`)
+    console.log(`server started on http://localhost:${port}`)
 })
 
 // curl -X PUT -H "Content-Type: image/png" --data-binary @blob.png http://localhost:8888/blob.png