braid-http 0.3.1 → 0.3.3

package/braid-http-client.js

@@ -48,25 +48,26 @@ function braidify_http (http) {
         // Always add the `peer` header
         options.headers.peer = options.headers.peer || peer
 
-        // Wrap the callback to provide our new .on('version', ...) feature
+        // Wrap the callback to provide our new .on('update', ...) feature
         // on nodejs servers
-        var on_version,
+        var on_update,
             on_error,
             orig_cb = cb
         cb = (res) => {
             res.orig_on = res.on
             res.on = (key, f) => {
 
-                // Define .on('version', cb)
-                if (key === 'version') {
+                // Define .on('update', cb)
+                if (key === 'update'
+                    || key === 'version' /* Deprecated API calls it 'version' */ ) {
 
-                    // If we have an 'version' handler, let's remember it
-                    on_version = f
+                    // If we have an 'update' handler, let's remember it
+                    on_update = f
 
                     // And set up a subscription parser
-                    var parser = subscription_parser((version, error) => {
+                    var parser = subscription_parser((update, error) => {
                         if (!error)
-                            on_version && on_version(version)
+                            on_update && on_update(update)
                         else
                             on_error && on_error(error)
                     })
@@ -149,13 +150,21 @@ async function braid_fetch (url, params = {}) {
     else
         params.headers = new Headers(params.headers)
 
+    // Sanity check inputs
+    if (params.version)
+        console.assert(Array.isArray(params.version),
+                       'fetch(): `version` must be an array')
+    if (params.parents)
+        console.assert(Array.isArray(params.parents),
+                       'fetch(): `parents` must be an array')
+
     // Always set the peer
     params.headers.set('peer', peer)
 
     // We provide some shortcuts for Braid params
     if (params.version)
         params.headers.set('version', params.version.map(JSON.stringify).join(', '))
-    if (params.parents?.length)
+    if (params.parents)
         params.headers.set('parents', params.parents.map(JSON.stringify).join(', '))
     if (params.subscribe)
         params.headers.set('subscribe', 'true')
@@ -342,7 +351,6 @@ async function handle_fetch_stream (stream, cb) {
 // Braid-HTTP Subscription Parser
 // ****************************
 
-
 var subscription_parser = (cb) => ({
     // A parser keeps some parse state
     state: {input: ''},
@@ -359,23 +367,18 @@ var subscription_parser = (cb) => ({
 
         // Now loop through the input and parse until we hit a dead end
         while (this.state.input.trim() !== '') {
-            this.state = parse_version (this.state)
+            this.state = parse_update (this.state)
 
             // Maybe we parsed a version!  That's cool!
             if (this.state.result === 'success') {
-                let ignore_headers = {
-                    version: true,
-                    parents: true,
-                    patches: true,
-                    'content-length': true,
-                    'content-range': true,
-                }
                 this.cb({
                     version: this.state.version,
                     parents: this.state.parents,
                     body:    this.state.body,
                     patches: this.state.patches,
-                    ...((x => Object.keys(x).length ? {extra_headers: x} : {})(Object.fromEntries(Object.entries(this.state.headers).filter(([k, v]) => !ignore_headers[k]))))
+
+                    // Output extra_headers if there are some
+                    extra_headers: extra_headers(this.state.headers)
                 })
 
                 // Reset the parser for the next version!
@@ -410,7 +413,7 @@ var subscription_parser = (cb) => ({
 //  => {result: 'error', ...}    If there is a syntax error in the input
 
 
-function parse_version (state) {
+function parse_update (state) {
     // If we don't have headers yet, let's try to parse some
     if (!state.headers) {
         var parsed = parse_headers(state.input)
@@ -488,7 +491,8 @@ function parse_headers (input) {
     // Success!  Let's parse special headers
     if ('version' in headers)
         headers.version = JSON.parse('['+headers.version+']')
-    headers.parents = JSON.parse('['+(headers.parents ?? '')+']')
+    if ('parents' in headers)
+        headers.parents = JSON.parse('['+headers.parents+']')
     if ('patches' in headers)
         headers.patches = JSON.parse(headers.patches)
 
@@ -632,13 +636,8 @@ function parse_body (state) {
                 last_patch.unit = match.unit
                 last_patch.range = match.range
                 last_patch.content = state.input.substr(0, content_length)
-
-                // instead of headers, we'll create an "extra_headers" field that ignore the headers we've used
-                last_patch.extra_headers = last_patch.headers
-                delete last_patch.headers
-                delete last_patch.extra_headers['content-length']
-                delete last_patch.extra_headers['content-range']
-                if (!Object.keys(last_patch.extra_headers).length) delete last_patch.extra_headers
+                last_patch.extra_headers = extra_headers(last_patch.headers)
+                delete last_patch.headers  // We only keep the extra headers ^^
 
                 // Consume the parsed input
                 state.input = state.input.substring(content_length)
@@ -655,6 +654,28 @@ function parse_body (state) {
     }
 }
 
+// The "extra_headers" field is returned to the client on any *update* or
+// *patch* to include any headers that we've received, but don't have braid
+// semantics for.
+//
+// This function creates that hash from a headers object, by filtering out all
+// known headers.
+function extra_headers (headers) {
+    // Clone headers
+    var result = Object.assign({}, headers)
+
+    // Remove the non-extra parts
+    var known_headers = ['version', 'parents', 'patches',
+                         'content-length', 'content-range']
+    for (var i = 0; i < known_headers.length; i++)
+        delete result[known_headers[i]]
+
+    // Return undefined if we deleted them all
+    if (Object.keys(result).length === 0)
+        return undefined
+
+    return result
+}
 
 // ****************************
 // Exports
@@ -665,7 +686,7 @@ if (typeof module !== 'undefined' && module.exports)
         fetch: braid_fetch,
         http: braidify_http,
         subscription_parser,
-        parse_version,
+        parse_update,
         parse_headers,
         parse_body
     }

package/braid-http-server.js

@@ -195,8 +195,8 @@ function braidify (req, res, next) {
     res.setHeader('Range-Request-Allow-Units', 'json')
 
     // Extract braid info from headers
-    var version = JSON.parse('['+(req.headers.version ?? '')+']'),
-        parents = JSON.parse('['+(req.headers.parents ?? '')+']'),
+    var version = req.headers.version && JSON.parse('['+req.headers.version+']'),
+        parents = req.headers.parents && JSON.parse('['+req.headers.parents+']'),
         peer = req.headers['peer'],
         url = req.url.substr(1)
 
@@ -211,8 +211,8 @@ function braidify (req, res, next) {
     req.subscribe = subscribe
 
     // Add the braidly request/response helper methods
-    res.sendVersion = (stuff) => send_version(res, stuff, req.url, peer)
-    res.sendUpdate = res.sendVersion
+    res.sendUpdate = (stuff) => send_update(res, stuff, req.url, peer)
+    res.sendVersion = res.sendUpdate
     req.patches = () => new Promise(
         (done, err) => parse_patches(req, (patches) => done(patches))
     )
@@ -273,7 +273,7 @@ function braidify (req, res, next) {
     next && next()
 }
 
-function send_version(res, data, url, peer) {
+function send_update(res, data, url, peer) {
     var {version, parents, patches, patch, body} = data
 
     function set_header (key, val) {
@@ -332,13 +332,13 @@ function send_version(res, data, url, peer) {
     for (var [header, value] of Object.entries(data)) {
         header = header.toLowerCase()
 
-        // Version and Parents get output in the Structured Headers format
+        // Version and Parents get output in the Structured Headers format,
+        // so we convert `value` from array to comma-separated strings.
         if (header === 'version') {
             header = 'Version'               // Capitalize for prettiness
             value = value.map(JSON.stringify).join(", ")
         } else if (header === 'parents') {
             header = 'Parents'               // Capitalize for prettiness
-            if (value.length == 0) continue  // we express no parents as not having the field at all
             value = value.map(JSON.stringify).join(", ")
         }
 

package/package.json

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

package/readme.md

@@ -38,7 +38,7 @@ import {fetch, http_client, http_server} from 'braid-http'
 This library adds a `{subscribe: true}` option to `fetch()`, and lets you
 access the result of a subscription with two new fields on the fetch response:
 
-- `response.subscribe( new_version => ... )`
+- `response.subscribe( update => ... )`
 - `response.subscription`: an iterator that can be used with `for await`
 
 ### Example Subscription with Promises
@@ -48,16 +48,16 @@ Here is an example of subscribing to a Braid resource using promises:
 ```javascript
 fetch('https://braid.org/chat', {subscribe: true}).then(
     res => res.subscribe(
-        (new_version) => {
-            console.log('We got a new version!', new_version)
+        (update) => {
+            console.log('We got a new update!', update)
             // {
-            //   version: "me",
+            //   version: ["me"],
             //   parents: ["mom", "dad"],
             //   patches: [{unit: "json", range: ".foo", content: "3"}]
             //   body:    "3"
             // }
             //
-            // Note that new_version will contain either patches *or* body
+            // Note that `update` will contain either patches *or* body
         }
     )
 )
@@ -69,9 +69,9 @@ If you want automatic reconnections, add two error handlers like this:
 function connect() {
     fetch('https://braid.org/chat', {subscribe: true}).then(
         res => res.subscribe(
-            (new_version) => {
-                console.log('We got a new version!', new_version)
-                // Do something with the new_version
+            (update) => {
+                console.log('We got a new update!', update)
+                // Do something with the update
             },
             e => setTimeout(connect, 1000)
         )
@@ -86,8 +86,8 @@ connect()
 async function connect () {
     try {
         (await fetch('/chat', {subscribe: true})).subscribe(
-            (new_version) => {
-                // We got a new version!
+            (update) => {
+                // We got a new update!
             },
             () => setTimeout(connect, 1000)
         )
@@ -108,7 +108,7 @@ async function connect () {
             if (v.patches)
                 chat = apply_patches(v.patches, chat)
 
-            // Or complete versions:
+            // Or complete snapshots:
             else
                 // Beware the server doesn't send these yet.
                 chat = JSON.parse(v.body)
@@ -153,7 +153,7 @@ require('http').createServer(
 
         // Send the current version
         res.sendUpdate({
-            version: 'greg',
+            version: ['greg'],
             body: JSON.stringify({greg: 'greg'})
         })
     }
@@ -184,14 +184,14 @@ app.get('/', (req, res) => {
 
     // Send the current version
     res.sendUpdate({
-        version: 'greg',
+        version: ['greg'],
         parents: ['gr','eg'],
         body: JSON.stringify({greg: 'greg'})
     })
 
     // Or you can send patches like this:
     // res.sendUpdate({
-    //     version: 'greg',
+    //     version: ['greg'],
     //     parents: ['gr','eg'],
     //     patches: [{range: '.greg', unit: 'json', content: '"greg"'}]
     // })
@@ -217,8 +217,8 @@ https.get(
    'https://braid.org/chat',
    {subscribe: true},
    (res) => {
-      res.on('version', (version) => {
-          console.log('well we got one', version)
+      res.on('update', (update) => {
+          console.log('well we got one', update)
       })
    }
 )
@@ -232,15 +232,15 @@ function connect () {
         'https://braid.org/chat',
         {subscribe: true},
         (res) => {
-            res.on('version', (version) => {
+            res.on('update', (update) => {
                 // {
-                //   version: "me",
+                //   version: ["me"],
                 //   parents: ["mom", "dad"],
                 //   patches: [{unit: "json", range: ".foo", content: "3"}]
                 //   body:    "3"
                 // }
-                //   // Version will contain either patches *or* body, but not both
-                console.log('We got a new version!', version)
+                //   // Update will contain either patches *or* body, but not both
+                console.log('We got a new update!', update)
             })
 
             res.on('end',   e => setTimeout(connect, 1000))
@@ -272,5 +272,3 @@ automatically reconnect.  (See
 [issue #980](https://github.com/node-fetch/node-fetch/issues/980) and
 [#753](https://github.com/node-fetch/node-fetch/issues/753).)  We recommend
 using the `http` library (below) for requests on nodejs instead.
-
-