braid-http 1.3.105 → 1.3.107

package/README.md

@@ -82,7 +82,39 @@ fetch('https://braid.org/chat', {subscribe: true}).then(
 )
 ```
 
-If you want automatic reconnections, this library add a `{retry: true}` option to `fetch()`.
+### Example Subscription with Async/Await
+
+```javascript
+(await fetch('/chat', {subscribe: true, retry: true})).subscribe(
+    (update) => {
+        // We got a new update!
+    })
+```
+
+### Example Subscription with `for await`
+
+```javascript
+var subscription_iterator = (await fetch('/chat',
+    {subscribe: true, retry: true})).subscription
+for await (var update of subscription_iterator) {
+    // Updates might come in the form of patches:
+    if (update.patches)
+        chat = apply_patches(update.patches, chat)
+
+    // Or complete snapshots:
+    else
+        // Beware the server doesn't send these yet.
+        chat = JSON.parse(update.body_text)
+
+    render_stuff()
+}
+```
+
+### Advanced client features
+
+#### Automatic reconection
+
+Pass a `{retry: true}` option to `fetch()` to automatically reconnect:
 
 ```javascript
 fetch('https://braid.org/chat', {subscribe: true, retry: true}).then(
@@ -95,12 +127,16 @@ fetch('https://braid.org/chat', {subscribe: true, retry: true}).then(
 )
 ```
 
-For use in conjunction with `{retry: true}`, it's possible to make the `parents` param equal to a function, which will be called to get the current parents each time the fetch establishes a new connection.
+
+To update the parent version that you reconnect from, set the `parents`
+paramter to a function rather than an array of strings:
 
 ```javascript
-fetch('https://braid.org/chat', {subscribe: true, retry: true, parents: () => {
-        return current_parents
-    }}).then(
+fetch('https://braid.org/chat', {
+    subscribe: true,
+    retry: true,
+    parents: () => current_parents
+}).then(
     res => res.subscribe(
         (update) => {
             console.log('We got a new update!', update)
@@ -110,7 +146,13 @@ fetch('https://braid.org/chat', {subscribe: true, retry: true, parents: () => {
 )
 ```
 
-You can monitor the subscription's connection status with `onSubscriptionStatus`:
+It will call the `parents` function each time it reconnects to learn the
+current parents to connection from.
+
+#### Monitor the connection status
+
+The `onSubscriptionStatus(status)` callback informs you when the connection
+goes online and offline:
 
 ```javascript
 fetch('https://braid.org/chat', {
@@ -133,39 +175,13 @@ The callback receives an object with only the fields relevant to the event:
 - `{online: true}` — the subscription is connected
 - `{online: false, error}` — the subscription went offline, with the error/reason for disconnection
 
-### Example Subscription with Async/Await
-
-```javascript
-(await fetch('/chat', {subscribe: true, retry: true})).subscribe(
-    (update) => {
-        // We got a new update!
-    })
-```
-
-### Example Subscription with `for await`
 
-```javascript
-var subscription_iterator = (await fetch('/chat',
-    {subscribe: true, retry: true})).subscription
-for await (var update of subscription_iterator) {
-    // Updates might come in the form of patches:
-    if (update.patches)
-        chat = apply_patches(update.patches, chat)
-
-    // Or complete snapshots:
-    else
-        // Beware the server doesn't send these yet.
-        chat = JSON.parse(update.body_text)
-
-    render_stuff()
-}
-```
 
 ## Using it in Nodejs
 
 You can braidify your nodejs server with:
 
-```
+```javascript
 var braidify = require('braid-http').http_server
 ```
 
@@ -344,19 +360,19 @@ fetch('https://localhost:3009/chat',
 
 Run all tests from the command line:
 
-```
+```bash
 npm test
 ```
 
 Run tests in a browser (auto-opens):
 
-```
+```bash
 npm run test:browser
 ```
 
 You can also filter tests by name:
 
-```
+```bash
 node test/test.js --filter="version"
 ```
 
@@ -369,7 +385,7 @@ the scenes to overcome web browsers' 6-connection limit (with HTTP/1) and
 the recommended ways, you don't need to know it's happening — the abstraction
 is completely transparent.
 
-```
+```javascript
 // Recommendation #1: Wrapping the entire request handler
 require('http').createServer(
   braidify((req, res) => {
@@ -378,18 +394,22 @@ require('http').createServer(
 )
 ```
 
-```
+```javascript
 // Recommendation #2: As middleware
 var app = require('express')()
 app.use(braidify)
 ```
 
-```
+```javascript
 // Recommendation #3: With braidify(req, res, next)
 // (Equivalent to the middleware form.)
-   ...
-   braidify(req, res, next)
-   ...
+app.use(
+  (req, res, next) => {
+    ...
+    braidify(req, res, next)
+    ...
+  }
+)
 ```
 
 
@@ -397,14 +417,16 @@ app.use(braidify)
 
 If you are using braidify from within a library, or in another context without
 access to the entire request handler, or a `next()` method, then you can use
-the inline form:
+the inline `braidify(req, res)` form:
 
-```
+```javascript
+require('http').createServer(
   (req, res) => {
-      ...
-      braidify(req, res); if (req.is_multiplexer) return
-      ...
-  })
+    ...
+    braidify(req, res); if (req.is_multiplexer) return
+    ...
+  }
+)
 ```
 
 Just know that there are three abstraction leaks when using this form:

package/braid-http-client.js

@@ -159,20 +159,21 @@ async function braid_fetch (url, params = {}) {
         params.headers.set('version', params.version.map(JSON.stringify).map(ascii_ify).join(', '))
     if (Array.isArray(params.parents))
         params.headers.set('parents', params.parents.map(JSON.stringify).map(ascii_ify).join(', '))
-    if (params.subscribe)
+    if (params.subscribe) {
         params.headers.set('subscribe', 'true')
+        // Prevent this response from being cached
+        params.cache = 'no-store'
+    }
+
     if (params.peer)
         params.headers.set('peer', params.peer)
-    
+
     if (params.heartbeats)
         params.headers.set('heartbeats',
                            typeof params.heartbeats === 'number'
                            ? `${params.heartbeats}s`
                            : params.heartbeats)
 
-    // Prevent browsers from going to disk cache
-    params.cache = 'no-cache'
-
     // Prepare patches
     if (params.patches) {
         console.assert(!params.body, 'Cannot send both patches and body')
@@ -311,9 +312,32 @@ async function braid_fetch (url, params = {}) {
                     if (parents) params.headers.set('parents', parents.map(JSON.stringify).join(', '))
                 }
 
-                // undocumented feature used by braid-chrome
-                // to see the fetch args as they are right before it is actually called,
-                // to display them for the user in the dev panel
+                // Work around Chrome bug where when you restore a closed tab,
+                // Chrome overrides our {cache:'no-store'} parameter and instead sets
+                // SKIP_CACHE_VALIDATION, which overrides our subscription response
+                // with ... a static entry from its cache!  That sucks.
+                //
+                // See https://issues.chromium.org/issues/490673934
+                //
+                // Our workaround is to detect if we are in chrome, and subscribing,
+                // and are within a page restoration... and then...
+                if (!is_nodejs && params.headers.has('subscribe')) {
+                    var nav_entry = performance?.getEntriesByType?.('navigation')?.[0]
+                    if (nav_entry?.type === 'back_forward'
+                        && document.readyState !== 'complete')
+
+                        // ...we just wait until the page has loaded to send this fetch
+                        await new Promise(r => window.addEventListener('load', r))
+
+                        // Because the SKIP_CACHE_VALIDATION policy in chrome goes away
+                        // as soon as the page loads.
+                }
+
+                // Braid-Chrome needs the following special (undocumented)
+                // `onFetch` feature.  It's a callback with the params as they
+                // are being sent to the underlying fetch().  The Braid
+                // devtools wants to be able to display these in its devtools
+                // panel.
                 params.onFetch?.(url, params, underlying_aborter)
 
                 // Now we run the original fetch....

package/braid-http-server.js

@@ -332,12 +332,22 @@ function braidify (req, res, next) {
     if ((subscribe === '' || subscribe)
         // And this is a GET, because `Subscribe:` is only
         // specified for GET thus far...
-        && req.method === 'GET')
+        && req.method === 'GET') {
         // Then let's set 'subscribe' on.  We default to "true", but if the
         // client actually specified a value other than empty string '', let's
         // use that rich value.
         subscribe = subscribe || true
 
+        // Great. Now we also need to set the response body's content-type, so
+        // that FireFox doesn't try to sniff the content-type on a stream and
+        // hang forever waiting for 512 bytes (see firefox issue
+        // https://bugzilla.mozilla.org/show_bug.cgi?id=1544313)
+        res.setHeader('Content-Type', 'message/http-sequence')
+
+        // And we don't want any caches trying to store these stream bodies.
+        res.setHeader('Cache-Control', 'no-store')
+    }
+
     // Define convenience variables
     req.version   = version
     req.parents   = parents
@@ -649,9 +659,19 @@ function braidify (req, res, next) {
             res.isSubscription = true
 
             // Let's disable the timeouts (if it exists)
-            if (req.socket.server)
+            if (req.socket.server) {
                 req.socket.server.timeout = 0.0
 
+                // Node 18+ added requestTimeout (default 300s) and
+                // headersTimeout (default 60s) which will kill idle
+                // long-lived connections — our bread and butter.  We disable
+                // the requestTimeout, but the headersTimeout is probably
+                // fine.
+                //
+                req.socket.server.requestTimeout = 0
+                // req.socket.server.headersTimeout = 0
+            }
+
             // We have a subscription!
             res.statusCode = 209
             res.statusMessage = 'Multiresponse'
@@ -753,12 +773,12 @@ async function send_update(res, data, url, peer) {
     // Validate the body and patches
     assert(!(patch && patches),
            'sendUpdate: cannot have both `update.patch` and `update.patches` set')
-    if (patch)
-        patches = [patch]
     assert(!(body && patches),
            'sendUpdate: cannot have both `update.body` and `update.patch(es)')
     assert(!patches || Array.isArray(patches),
            'sendUpdate: `patches` provided is not array')
+    if (patch)
+        patches = patch
 
     // Validate body format
     if (body !== undefined) {
@@ -838,10 +858,15 @@ async function send_update(res, data, url, peer) {
     // See also https://github.com/braid-org/braid-spec/issues/73
     if (res.isSubscription) {
         var extra_newlines = 1
-        if (res.is_firefox)
-            // Work around Firefox network buffering bug
-            // See https://github.com/braid-org/braidjs/issues/15
-            extra_newlines = 240
+
+        // Note: this firefox workaround was replaced with a content-type fix
+        // above.  We realized that content-type fixes the issue when we found
+        // https://bugzilla.mozilla.org/show_bug.cgi?id=1544313
+        //
+        // if (res.is_firefox)
+        //     // Work around Firefox network buffering bug
+        //     // See https://github.com/braid-org/braidjs/issues/15
+        //     extra_newlines = 240
 
         for (var i = 0; i < 1 + extra_newlines; i++)
             res.write("\r\n")

package/package.json

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