braid-http 0.0.2 → 0.1.2

package/braid-http-client.js

@@ -136,14 +136,16 @@ if (is_nodejs) {
     normal_fetch = window.fetch
     AbortController = window.AbortController
     Headers = window.Headers
-    window.fetch = braid_fetch
+    // window.fetch = braid_fetch
 }
 
 async function braid_fetch (url, params = {}) {
+    params = {...params}  // Copy params, because we'll mutate it
+
     // Initialize the headers object
     if (!params.headers)
         params.headers = new Headers()
-    if (!(params.headers instanceof Headers))
+    else
         params.headers = new Headers(params.headers)
 
     // Always set the peer
@@ -162,16 +164,30 @@ async function braid_fetch (url, params = {}) {
 
     // Prepare patches
     if (params.patches) {
-        console.assert(Array.isArray(params.patches), 'Patches must be array')
         console.assert(!params.body, 'Cannot send both patches and body')
+        console.assert(typeof params.patches === 'object', 'Patches must be object or array')
+
+        // We accept a single patch as an array of one patch
+        if (!Array.isArray(params.patches))
+            params.patches = [params.patches]
+
+        // If just one patch, send it directly!
+        if (params.patches.length === 1) {
+            let patch = params.patches[0]
+            params.headers.set('Content-Range', `${patch.unit} ${patch.range}`)
+            params.headers.set('Content-Length', `${patch.content.length}`)
+            params.body = patch.content
+        }
 
-        params.patches = params.patches || []
-        params.headers.set('patches', params.patches.length)
-        params.body = (params.patches).map(patch => {
-            var length = `content-length: ${patch.content.length}`
-            var range = `content-range: ${patch.unit} ${patch.range}`
-            return `${length}\r\n${range}\r\n\r\n${patch.content}\r\n`
-        }).join('\r\n')
+        // Multiple patches get sent within a Patches: N block
+        else {
+            params.headers.set('Patches', params.patches.length)
+            params.body = (params.patches).map(patch => {
+                var length = `content-length: ${patch.content.length}`
+                var range = `content-range: ${patch.unit} ${patch.range}`
+                return `${length}\r\n${range}\r\n\r\n${patch.content}\r\n`
+            }).join('\r\n')
+        }
     }
 
     // Wrap the AbortController with a new one that we control.
@@ -482,19 +498,51 @@ function parse_headers (input) {
     return { result: 'success', headers, input }
 }
 
+// Content-range is of the form '<unit> <range>' e.g. 'json .index'
+var content_range_regex = /(\S+) (.*)/
 function parse_body (state) {
+
     // Parse Body Snapshot
 
     var content_length = parseInt(state.headers['content-length'])
-    if (content_length !== NaN) {
+    if (!isNaN(content_length)) {
+
+        // We've read a Content-Length, so we have a block to parse
         if (content_length > state.input.length) {
+            // But we haven't received the whole block yet
             state.result = 'waiting'
             return state
         }
 
+        // We have the whole block!
         var consumed_length = content_length + 2
         state.result = 'success'
-        state.body = state.input.substring(0, content_length)
+
+        // If we have a content-range, then this is a patch
+        if (state.headers['content-range']) {
+            var match = state.headers['content-range'].match(content_range_regex)
+            if (!match)
+                return {
+                    result: 'error',
+                    message: 'cannot parse content-range',
+                    range: state.headers['content-range']
+                }
+            state.patches = [{
+                unit: match[1],
+                range: match[2],
+                content: state.input.substring(0, content_length),
+
+                // Question: Perhaps we should include headers here, like we do for
+                // the Patches: N headers below?
+
+                // headers: state.headers
+            }]
+        }
+
+        // Otherwise, this is a snapshot body
+        else
+            state.body = state.input.substring(0, content_length)
+
         state.input = state.input.substring(consumed_length)
         return state
     }
@@ -535,7 +583,7 @@ function parse_body (state) {
                 state.input = parsed.input
             }
 
-            // Todo: support arbitrary patches, not just range-patch
+            // Todo: support custom patches, not just range-patch
 
             // Parse Range Patch format
             {
@@ -561,9 +609,7 @@ function parse_body (state) {
                     return state
                 }
 
-                // Content-range is of the form '<unit> <range>' e.g. 'json .index'
-                
-                var match = last_patch.headers['content-range'].match(/(\S+) (.*)/)
+                var match = last_patch.headers['content-range'].match(content_range_regex)
                 if (!match)
                     return {
                         result: 'error',

package/braid-http-server.js

@@ -1,31 +1,62 @@
 var assert = require('assert')
 
-// Write an array of patches into the pseudoheader format.
+// Return a string of patches in pseudoheader format.
+//
+//   The `patches` argument can be:
+//     - Array of patches
+//     - A single patch
+//
+//   Multiple patches are generated like:
+//
+//       Patches: n
+//
+//       content-length: 21
+//       content-range: json .range
+//
+//       {"some": "json object"}
+//
+//       content-length: x
+//       ...
+//
+//   A single patch is generated like:
+//
+//       content-length: 21
+//       content-range: json .range
+//
+//       {"some": "json object"}
+//
 function generate_patches(res, patches) {
+
+    // `patches` must be an object or an array
+    assert(typeof patches === 'object')
+
+    // An array of one patch behaves like a single patch
+    if (!Array.isArray(patches))
+        var patches = [patches]
+
     for (let patch of patches) {
         assert(typeof patch.unit    === 'string')
         assert(typeof patch.range   === 'string')
         assert(typeof patch.content === 'string')
     }
 
-    // This will return something like:
-    // Patches: n
-    // 
-    // content-length: 21
-    // content-range: json .range
-    //
-    // {"some": "json object"}
-    //
-    // content-length: x
-    // ...
-    var result = `Patches: ${patches.length}\r\n`
-    for (let patch of patches)
-        result += `\r
-content-length: ${patch.content.length}\r
-content-range: ${patch.unit} ${patch.range}\r
+    // Build up the string as a result
+    var result = ''
+
+    // Add `Patches: N` header if we have multiple patches
+    if (patches.length > 1)
+        result += `Patches: ${patches.length}\r\n\r\n`
+
+    // Generate each patch
+    patches.forEach((patch, i) => {
+        if (i > 0)
+            result += '\r\n\r\n'
+
+        result += `Content-Length: ${patch.content.length}\r
+Content-Range: ${patch.unit} ${patch.range}\r
 \r
-${patch.content}\r
-`
+${patch.content}`
+    })
     return result
 }
 
@@ -33,81 +64,118 @@ ${patch.content}\r
 // This function reads num_patches in pseudoheader format from a
 // ReadableStream and then fires a callback when they're finished.
 function parse_patches (req, cb) {
-    // Todo: make this work in the case where there is no Patches: header, but
-    // Content-Range is still set, nonetheless.
-
-    var num_patches = req.headers.patches,
-        stream = req
-
-    let patches = []
-    let buffer = ""
-    if (num_patches === 0)
-        return cb(patches)
-
-    stream.on('data', function parse (chunk) {
-        // Merge the latest chunk into our buffer
-        buffer = (buffer + chunk)
-
-        // We might have an extra newline at the start.  (mike: why?)
-        buffer = buffer.trimStart()
-
-        while (patches.length < num_patches) {
-            // First parse the patch headers.  It ends with a double-newline.
-            // Let's see where that is.
-            var headers_end = buffer.match(/(\r?\n)(\r?\n)/)
-
-            // Give up if we don't have a set of headers yet.
-            if (!headers_end)
-                return
-
-            // Now we know where things end
-            var first_newline = headers_end[1],
-                headers_length = headers_end.index + first_newline.length,
-                blank_line = headers_end[2]
-
-            // Now let's parse those headers.
-            var headers = require('parse-headers')(
-                buffer.substring(0, headers_length)
-            )
-
-            // We require `content-length` to declare the length of the patch.
-            if (!('content-length' in headers)) {
-                // Print a nice error if it's missing
-                console.error('No content-length in', JSON.stringify(headers))
-                process.exit(1)
-            }
-
-            var body_length = parseInt(headers['content-length'])
-
-            // Give up if we don't have the full patch yet.
-            if (buffer.length < headers_length + blank_line.length + body_length)
-                return
-
-            // XX Todo: support custom patch types beyond content-range.
+    var num_patches = req.headers.patches
 
-            // Content-range is of the form '<unit> <range>' e.g. 'json .index'
-            var [unit, range] = headers['content-range'].match(/(\S+) (.*)/).slice(1)
-            var patch_content =
-                buffer.substring(headers_length + blank_line.length,
-                                 headers_length + blank_line.length + body_length)
+    // Parse a single patch from the request body
+    if (num_patches === undefined) {
 
-            // We've got our patch!
-            patches.push({unit, range, content: patch_content})
+        // We only support range patches right now, so there must be a
+        // Content-Range header.
+        assert(req.headers['content-range'], 'No patches to parse: need `Patches: N` or `Content-Range:` header in ' + JSON.stringify(req.headers))
 
-            buffer = buffer.substring(headers_length + blank_line.length + body_length)
+        // Parse the Content-Range header
+        var match = req.headers['content-range'].match(/(\S+) (.*)/)
+        if (!match) {
+            console.error('Cannot parse Content-Range in', JSON.stringify(headers))
+            process.exit(1)
         }
+        var [unit, range] = match.slice(1)
+
+        // The contents of the patch is in the request body
+        var buffer = ''
+        // Read the body one chunk at a time
+        req.on('data', chunk => buffer = buffer + chunk)
+        // Then return it
+        req.on('end', () => {
+            patches = [{unit, range, content: buffer}]
+            cb(patches)
+        })
+    }
 
-        // We got all the patches!  Pause the stream and tell the callback!
-        stream.pause()
-        cb(patches)
-    })
-    stream.on('end', () => {
-        // If the stream ends before we get everything, then return what we
-        // did receive
-        console.error('Stream ended!')
-        if (patches.length !== num_patches)
-            console.error(`Got an incomplete PUT: ${patches.length}/${num_patches} patches were received`)
-    })
+    // Parse multiple patches within a Patches: N block
+    else {
+        num_patches = parseInt(num_patches)
+        let patches = []
+        let buffer = ""
+
+        // We check to send send patches each time we parse one.  But if there
+        // are zero to parse, we will never check to send them.
+        if (num_patches === 0)
+            return cb([])
+
+        req.on('data', function parse (chunk) {
+
+            // Merge the latest chunk into our buffer
+            buffer = (buffer + chunk)
+
+            while (patches.length < num_patches) {
+                // We might have extra newlines at the start, because patches
+                // can be separated by arbitrary numbers of newlines
+                buffer = buffer.trimStart()
+
+                // First parse the patch headers.  It ends with a double-newline.
+                // Let's see where that is.
+                var headers_end = buffer.match(/(\r?\n)(\r?\n)/)
+
+                // Give up if we don't have a set of headers yet.
+                if (!headers_end)
+                    return
+
+                // Now we know where things end
+                var first_newline = headers_end[1],
+                    headers_length = headers_end.index + first_newline.length,
+                    blank_line = headers_end[2]
+
+                // Now let's parse those headers.
+                var headers = require('parse-headers')(
+                    buffer.substring(0, headers_length)
+                )
+
+                // We require `content-length` to declare the length of the patch.
+                if (!('content-length' in headers)) {
+                    // Print a nice error if it's missing
+                    console.error('No content-length in', JSON.stringify(headers),
+                                  'from', {buffer, headers_length})
+                    process.exit(1)
+                }
+
+                var body_length = parseInt(headers['content-length'])
+
+                // Give up if we don't have the full patch yet.
+                if (buffer.length < headers_length + blank_line.length + body_length)
+                    return
+
+                // XX Todo: support custom patch types beyond content-range.
+
+                // Content-range is of the form '<unit> <range>' e.g. 'json .index'
+                var match = headers['content-range'].match(/(\S+) (.*)/)
+                if (!match) {
+                    console.error('Cannot parse Content-Range in', JSON.stringify(headers))
+                    process.exit(1)
+                }
+                var [unit, range] = match.slice(1)
+                var patch_content =
+                    buffer.substring(headers_length + blank_line.length,
+                                     headers_length + blank_line.length + body_length)
+
+                // We've got our patch!
+                patches.push({unit, range, content: patch_content})
+
+                buffer = buffer.substring(headers_length + blank_line.length + body_length)
+            }
+
+            // We got all the patches!  Pause the stream and tell the callback!
+            req.pause()
+            cb(patches)
+        })
+        req.on('end', () => {
+            // If the stream ends before we get everything, then return what we
+            // did receive
+            console.error('Request stream ended!')
+            if (patches.length !== num_patches)
+                console.error(`Got an incomplete PUT: ${patches.length}/${num_patches} patches were received`)
+        })
+    }
 }
 
 function braidify (req, res, next) {
@@ -116,7 +184,6 @@ function braidify (req, res, next) {
     // First, declare that we support Patches and JSON ranges.
     res.setHeader('Range-Request-Allow-Methods', 'PATCH, PUT')
     res.setHeader('Range-Request-Allow-Units', 'json')
-    res.setHeader("Patches", "OK")
 
     // Extract braid info from headers
     var version = req.headers.version && JSON.parse(req.headers.version),
@@ -163,6 +230,7 @@ function braidify (req, res, next) {
             res.statusCode = 209
             res.setHeader("subscribe", req.headers.subscribe)
             res.setHeader('cache-control', 'no-cache, no-transform')
+            res.setHeader('transfer-encoding', '')
 
             var connected = true
             function disconnected (x) {
@@ -198,7 +266,7 @@ function send_version(res, data, url, peer) {
     }
     function write_body (body) {
         if (res.isSubscription)
-            res.write('\r\n' + body + '\r\n')
+            res.write('\r\n' + body)
         else
             res.write(body)
     }
@@ -211,16 +279,26 @@ function send_version(res, data, url, peer) {
         assert(typeof body === 'string')
     else {
         assert(patches !== undefined)
-        patches.forEach(p => assert(typeof p.content === 'string'))
+        assert(patches !== null)
+        assert(typeof patches === 'object')
+        if (Array.isArray(patches))
+            patches.forEach(p => assert(typeof p.content === 'string'))
     }
+    assert(body || patches, 'Missing body or patches')
+    assert(!(body && patches), 'Cannot send both body and patches')
 
     // Write the headers or virtual headers
     for (var [header, value] of Object.entries(data)) {
+        header = header.toLowerCase()
+
         // Version and Parents get output in the Structured Headers format
-        if (header === 'version')
+        if (header === 'version') {
+            header = 'Version'               // Capitalize for prettiness
             value = JSON.stringify(value)
-        else if (header === 'parents')
+        } else if (header === 'parents') {
+            header = 'Parents'               // Capitalize for prettiness
             value = parents.map(JSON.stringify).join(", ")
+        }
 
         // We don't output patches or body yet
         else if (header === 'patches' || header == 'body')
@@ -230,20 +308,16 @@ function send_version(res, data, url, peer) {
     }
 
     // Write the patches or body
-    if (Array.isArray(patches))
-        res.write(generate_patches(res, patches)) // adds its own newline
-    else if (typeof body === 'string') {
-        set_header('content-length', body.length)
+    if (typeof body === 'string') {
+        set_header('Content-Length', body.length)
         write_body(body)
-    } else {
-        console.trace("Missing body or patches")
-        process.exit()
-    }
+    } else
+        res.write(generate_patches(res, patches))
 
     // Add a newline to prepare for the next version
     // See also https://github.com/braid-org/braid-spec/issues/73
     if (res.isSubscription) {
-        var extra_newlines = 0
+        var extra_newlines = 1
         if (res.is_firefox)
             // Work around Firefox network buffering bug
             // See https://github.com/braid-org/braidjs/issues/15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-http",
-  "version": "0.0.2",
+  "version": "0.1.2",
   "description": "An implementation of Braid-HTTP for Node.js and Browsers",
   "scripts": {
     "test": "node test/server.js"

package/readme.md

@@ -1,6 +1,6 @@
 # Braid-HTTP
 
-This polyfill library implements the [Braid-HTTP v03 protocol](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-braid-http-03.txt) in Javascript.  It extends the existing browser `fetch()` API, and the nodejs `http` library, with the ability to speak Braid.
+This polyfill library implements the [Braid-HTTP v03 protocol](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-braid-http-03.txt) in Javascript.  It gives browsers a `braid_fetch()` drop-in replacement for the `fetch()` API, and gives nodejs an `http` plugin, allowing them to speak Braid in a simple way.
 
 Developed in [braid.org](https://braid.org).
 
@@ -11,6 +11,10 @@ Browsers:
 
 ```html
 <script src="https://unpkg.com/braid-http/braid-http-client.js"></script>
+<script>
+  // To live on the cutting edge, you can now replace the browser's fetch() if desired:
+  // window.fetch = braid_fetch
+</script>
 ```
 
 Node.js:
@@ -98,7 +102,8 @@ async function connect () {
 ```javascript
 async function connect () {
     try {
-        for await (var v of fetch('/chat', {subscribe: true}).subscription) {
+        var subscription_iterator = fetch('/chat', {subscribe: true}).subscription
+        for await (var v of subscription_iterator) {
             // Updates might come in the form of patches:
             if (v.patches)
                 chat = apply_patches(v.patches, chat)