braid-http 0.0.1

package/braid-http-client.js

@@ -0,0 +1,606 @@
+var peer = Math.random().toString(36).substr(2)
+
+// ***************************
+// http
+// ***************************
+
+function braidify_http (http) {
+    // Todo:  Wrap .put to add `peer` header
+    http.normal_get = http.get
+    http.get = function braid_req (arg1, arg2, arg3) {
+        var url, options, cb
+
+        // http.get() supports two forms:
+        //
+        //  - http.get(url[, options][, callback])
+        //  - http.get(options[, callback])
+        //
+        // We need to know which arguments are which, so let's detect which
+        // form we are looking at.
+
+        // Detect form #1: http.get(url[, options][, callback])
+        if (typeof arg1 === 'string' || arg1 instanceof URL) {
+            url = arg1
+            if (typeof arg2 === 'function')
+                cb = arg2
+            else {
+                options = arg2
+                cb = arg3
+            }
+        }
+
+        // Otherwise it's form #2: http.get(options[, callback])
+        else {
+            options = arg2
+            cb = arg3
+        }
+
+        options = options || {}
+
+        // Now we know where the `options` are specified, let's set headers.
+        if (!options.headers)
+            options.headers = {}
+
+        // Add the subscribe header if this is a subscription
+        if (options.subscribe)
+            options.headers.subscribe = 'true'
+
+        // Always add the `peer` header
+        options.headers.peer = options.headers.peer || peer
+
+        // Wrap the callback to provide our new .on('version', ...) feature
+        var on_version,
+            on_error,
+            orig_cb = cb
+        cb = (res) => {
+            res.orig_on = res.on
+            res.on = (key, f) => {
+
+                // Define .on('version', cb)
+                if (key === 'version') {
+
+                    // If we have an 'version' handler, let's remember it
+                    on_version = f
+
+                    // And set up a subscription parser
+                    var parser = subscription_parser((version, error) => {
+                        if (!error)
+                            on_version && on_version(version)
+                        else
+                            on_error && on_error(error)
+                    })
+
+                    // That will run each time we get new data
+                    res.orig_on('data', (chunk) => {
+                        parser.read(chunk.toString())
+                    })
+                }
+
+                // Forward .on('error', cb) and remember the error function
+                else if (key === 'error') {
+                    on_error = f
+                    res.orig_on(key, f)
+                }
+
+                // Forward all other .on(*, cb) calls
+                else res.orig_on(key, f)
+            }
+            orig_cb && orig_cb(res)
+        }
+            
+        // Now put the parameters back in their prior order and call the
+        // underlying .get() function
+        if (url) {
+            arg1 = url
+            if (options) {
+                arg2 = options
+                arg3 = cb
+            } else {
+                arg2 = cb
+            }
+        } else {
+            arg1 = options
+            arg2 = cb
+        }
+
+        return http.normal_get(arg1, arg2, arg3)
+    }
+    return http
+}
+
+
+
+// ***************************
+// Fetch
+// ***************************
+
+var normal_fetch,
+    AbortController,
+    Headers,
+    is_nodejs = typeof window === 'undefined'
+
+if (is_nodejs) {
+    // Nodejs
+
+    // Note that reconnect logic doesn't work in node-fetch, because it
+    // doesn't call the .catch() handler when the stream fails.
+    //
+    // See https://github.com/node-fetch/node-fetch/issues/753
+
+    normal_fetch = require('node-fetch')
+    AbortController = require('abort-controller')
+    Headers = normal_fetch.Headers
+    var to_whatwg_stream = require('node-web-streams').toWebReadableStream
+} else {
+    // Web Browser
+    normal_fetch = window.fetch
+    AbortController = window.AbortController
+    Headers = window.Headers
+    window.fetch = braid_fetch
+}
+
+async function braid_fetch (url, params = {}) {
+    // Initialize the headers object
+    if (!params.headers)
+        params.headers = new Headers()
+    if (!(params.headers instanceof Headers))
+        params.headers = new Headers(params.headers)
+
+    // Always set the peer
+    params.headers.set('peer', peer)
+
+    // We provide some shortcuts for Braid params
+    if (params.version)
+        params.headers.set('version', JSON.stringify(params.version))
+    if (params.parents)
+        params.headers.set('parents', params.parents.map(JSON.stringify).join(', '))
+    if (params.subscribe)
+        params.headers.set('subscribe', 'true')
+
+    // Prevent browsers from going to disk cache
+    params.cache = 'no-cache'
+
+    // 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')
+
+        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')
+    }
+
+    // Wrap the AbortController with a new one that we control.
+    //
+    // This is because we want to be able to abort the fetch that the user
+    // passes in.  However, the fetch() command uses a silly "AbortController"
+    // abstraction to abort fetches, which has both a `signal` and a
+    // `controller`, and only passes the signal to fetch(), but we need the
+    // `controller` to abort the fetch itself.
+
+    var original_signal = params.signal
+    var underlying_aborter = new AbortController()
+    params.signal = underlying_aborter.signal
+    if (original_signal)
+        original_signal.addEventListener(
+            'abort',
+            () => underlying_aborter.abort()
+        )
+
+    // Now we run the original fetch....
+    var res = await normal_fetch(url, params)
+
+    // And customize the response with a couple methods for getting
+    // the braid subscription data:
+    res.subscribe    = start_subscription
+    res.subscription = {[Symbol.asyncIterator]: iterator}
+
+
+    // Now we define the subscription function we just used:
+    function start_subscription (cb, error) {
+        if (!res.ok)
+            throw new Error('Request returned not ok', res)
+
+        if (res.bodyUsed)
+            // TODO: check if this needs a return
+            throw new Error('This response\'s body has already been read', res)
+
+        // Parse the streamed response
+        handle_fetch_stream(
+            res.body,
+
+            // Each time something happens, we'll either get a new
+            // version back, or an error.
+            (result, err) => {
+                if (!err)
+                    // Yay!  We got a new version!  Tell the callback!
+                    cb(result)
+                else {
+                    // This error handling code runs if the connection
+                    // closes, or if there is unparseable stuff in the
+                    // streamed response.
+
+                    // In any case, we want to be sure to abort the
+                    // underlying fetch.
+                    underlying_aborter.abort()
+
+                    // Then send the error upstream.
+                    if (error)
+                        error(err)
+                    else
+                        throw 'Unhandled network error in subscription'
+                }
+            }
+        )
+    }
+
+
+    // And the iterator for use with "for async (...)"
+    function iterator () {
+        // We'll keep this state while our iterator runs
+        var initialized = false,
+            inbox = [],
+            resolve = null,
+            reject = null
+
+        return {
+            async next() {
+                // If we've already received a version, return it
+                if (inbox.length > 0)
+                    return {done: false, value: inbox.shift()}
+
+                // Otherwise, let's set up a promise to resolve when we get the next item
+                var promise = new Promise((_resolve, _reject) => {
+                    resolve = _resolve
+                    reject  = _reject
+                })
+
+                // Start the subscription, if we haven't already
+                if (!initialized) {
+                    initialized = true
+
+                    // The subscription will call whichever resolve and
+                    // reject functions the current promise is waiting for
+                    start_subscription(x => resolve(x),
+                                       x => reject(x) )
+                }
+
+                // Now wait for the subscription to resolve or reject the promise.
+                var result = await promise
+
+                // Anything we get from here out we should add to the inbox
+                resolve = (new_version) => inbox.push(new_version)
+                reject  = (err) => {throw err}
+
+                return { done: false, value: result }
+            }
+        }
+    }
+
+    return res
+}
+
+// Parse a stream of versions from the incoming bytes
+async function handle_fetch_stream (stream, cb) {
+    if (is_nodejs)
+        stream = to_whatwg_stream(stream)
+
+    // Set up a reader
+    var reader = stream.getReader(),
+        decoder = new TextDecoder('utf-8'),
+        parser = subscription_parser(cb)
+    
+    while (true) {
+        var versions = []
+
+        try {
+            // Read the next chunk of stream!
+            var {done, value} = await reader.read()
+
+            // Check if this connection has been closed!
+            if (done) {
+                console.debug("Connection closed.")
+                cb(null, 'Connection closed')
+                return
+            }
+
+            // Tell the parser to process some more stream
+            parser.read(decoder.decode(value))
+        }
+
+        catch (e) {
+            cb(null, e)
+            return
+        }
+    }
+}
+
+
+
+// ****************************
+// Braid-HTTP Subscription Parser
+// ****************************
+
+
+var subscription_parser = (cb) => ({
+    // A parser keeps some parse state
+    state: {input: ''},
+
+    // And reports back new versions as soon as they are ready
+    cb: cb,
+
+    // You give it new input information as soon as you get it, and it will
+    // report back with new versions as soon as it finds them.
+    read (input) {
+
+        // Store the new input!
+        this.state.input += input
+
+        // Now loop through the input and parse until we hit a dead end
+        do {
+            this.state = parse_version (this.state)
+
+            // Maybe we parsed a version!  That's cool!
+            if (this.state.result === 'success') {
+                this.cb({
+                    version: this.state.version,
+                    parents: this.state.parents,
+                    body:    this.state.body,
+                    patches: this.state.patches
+                })
+
+                // Reset the parser for the next version!
+                this.state = {input: this.state.input}
+            }
+
+            // Or maybe there's an error to report upstream
+            else if (this.state.result === 'error') {
+                this.cb(null, this.state.message)
+                return
+            }
+
+            // We stop once we've run out of parseable input.
+        } while (this.state.result !== 'waiting' && this.state.input.trim() !== '')
+    }
+})
+
+
+// ****************************
+// General parsing functions
+// ****************************
+//
+// Each of these functions takes parsing state as input, mutates the state,
+// and returns the new state.
+//
+// Depending on the parse result, each parse function returns:
+//
+//  parse_<thing> (state)
+//  => {result: 'waiting', ...}  If it parsed part of an item, but neeeds more input
+//  => {result: 'success', ...}  If it parses an entire item
+//  => {result: 'error', ...}    If there is a syntax error in the input
+
+
+function parse_version (state) {
+    // If we don't have headers yet, let's try to parse some
+    if (!state.headers) {
+        var parsed = parse_headers(state.input)
+
+        // If header-parsing fails, send the error upstream
+        if (parsed.result === 'error')
+            return parsed
+        if (parsed.result === 'waiting') {
+            state.result = 'waiting'
+            return state
+        }
+
+        state.headers = parsed.headers
+        state.version = state.headers.version
+        state.parents = state.headers.parents
+
+        // Take the parsed headers out of the buffer
+        state.input = parsed.input
+    }
+
+    // We have headers now!  Try parsing more body.
+    return parse_body(state)
+}
+
+function swallow_blank_lines (input) {
+    var blank_lines = /(\r\n|\n)*/.exec(input)[0]
+    return input.substr(blank_lines.length)
+}
+
+// Parsing helpers
+function parse_headers (input) {
+    input = swallow_blank_lines(input)
+
+    // First, find the start & end block of the headers.  The headers start
+    // when there are no longer newlines, and end at the first double-newline.
+
+    // Look for the double-newline at the end of the headers
+    var headers_end = input.match(/(\r?\n)\r?\n/)
+
+    // ...if we found none, then we need to wait for more input to complete
+    // the headers..
+    if (!headers_end)
+        return {result: 'waiting'}
+
+    // We now know where the headers are to parse!
+    var headers_length = headers_end.index + headers_end[1].length,
+        headers_source = input.substring(0, headers_length)
+    
+    // Let's parse them!  First define some variables:
+    var headers = {},
+        header_regex = /([\w-_]+):\s?(.*)\r?\n/gy,  // Parses one line a time
+        match,
+        found_last_match = false
+
+    // And now loop through the block, matching one line at a time
+    while (match = header_regex.exec(headers_source)) {
+        // console.log('Header match:', match && [match[1], match[2]])
+        headers[match[1].toLowerCase()] = match[2]
+
+        // This might be the last line of the headers block!
+        if (header_regex.lastIndex === headers_length)
+            found_last_match = true
+    }
+
+    // If the regex failed before we got to the end of the block, throw error:
+    if (!found_last_match)
+        return {
+            result: 'error',
+            message: 'Parse error in headers: "'
+                + JSON.stringify(headers_source.substr(header_regex.lastIndex)) + '"',
+            headers_so_far: headers,
+            last_index: header_regex.lastIndex, headers_length
+        }
+
+    // Success!  Let's parse special headers
+    if ('version' in headers)
+        headers.version = JSON.parse(headers.version)
+    if ('parents' in headers)
+        headers.parents = JSON.parse('['+headers.parents+']')
+    if ('patches' in headers)
+        headers.patches = JSON.parse(headers.patches)
+
+    // Update the input
+    input = input.substring(headers_length)
+
+    // Swallow the final blank line ending the headers
+    if (input.substr(0, 2) === '\r\n')
+        // Swallow \r\n
+        input = input.substr(2)
+    else
+        // Swallow \n
+        input = input.substr(1)
+
+    // And return the parsed result
+    return { result: 'success', headers, input }
+}
+
+function parse_body (state) {
+    // Parse Body Snapshot
+
+    var content_length = parseInt(state.headers['content-length'])
+    if (content_length !== NaN) {
+        if (content_length > state.input.length) {
+            state.result = 'waiting'
+            return state
+        }
+
+        var consumed_length = content_length + 2
+        state.result = 'success'
+        state.body = state.input.substring(0, content_length)
+        state.input = state.input.substring(consumed_length)
+        return state
+    }
+
+    // Parse Patches
+
+    else if (state.headers.patches) {
+        state.patches = state.patches || []
+
+        var last_patch = state.patches[state.patches.length-1]
+
+        // Parse patches until the final patch has its content filled
+        while (!(state.patches.length === state.headers.patches
+                 && 'content' in last_patch)) {
+
+            state.input = state.input.trimStart()
+
+            // Are we starting a new patch?
+            if (!last_patch || 'content' in last_patch) {
+                last_patch = {}
+                state.patches.push(last_patch)
+            }
+
+            // Parse patch headers
+            if (!('headers' in last_patch)) {
+                var parsed = parse_headers(state.input)
+
+                // If header-parsing fails, send the error upstream
+                if (parsed.result === 'error')
+                    return parsed
+                if (parsed.result === 'waiting') {
+                    state.result = 'waiting'
+                    return state
+                }
+
+                // We parsed patch headers!  Update state.
+                last_patch.headers = parsed.headers
+                state.input = parsed.input
+            }
+
+            // Todo: support arbitrary patches, not just range-patch
+
+            // Parse Range Patch format
+            {
+                if (!('content-length' in last_patch.headers))
+                    return {
+                        result: 'error',
+                        message: 'no content-length in patch',
+                        patch: last_patch, input: state.input
+                    }
+
+                if (!('content-range' in last_patch.headers))
+                    return {
+                        result: 'error',
+                        message: 'no content-range in patch',
+                        patch: last_patch, input: state.input
+                    }
+
+                var content_length = parseInt(last_patch.headers['content-length'])
+
+                // Does input have the entire patch contents yet?
+                if (state.input.length < content_length) {
+                    state.result = 'waiting'
+                    return state
+                }
+
+                // Content-range is of the form '<unit> <range>' e.g. 'json .index'
+                
+                var match = last_patch.headers['content-range'].match(/(\S+) (.*)/)
+                if (!match)
+                    return {
+                        result: 'error',
+                        message: 'cannot parse content-range in patch',
+                        patch: last_patch, input: state.input
+                    }
+
+                last_patch.unit = match[1]
+                last_patch.range = match[2]
+                last_patch.content = state.input.substr(0, content_length)
+
+                // Consume the parsed input
+                state.input = state.input.substring(content_length)
+            }
+        }
+
+        state.result = 'success'
+        return state
+    }
+
+    return {
+        result: 'error',
+        message: 'cannot parse body without content-length or patches header'
+    }
+}
+
+
+// ****************************
+// Exports
+// ****************************
+
+if (typeof module !== 'undefined' && module.exports)
+    module.exports = {
+        fetch: braid_fetch,
+        http: braidify_http,
+        subscription_parser,
+        parse_version,
+        parse_headers,
+        parse_body
+    }

package/braid-http-server.js

@@ -0,0 +1,258 @@
+var assert = require('assert')
+
+// Write an array of patches into the pseudoheader format.
+function generate_patches(res, 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
+\r
+${patch.content}\r
+`
+    return result
+}
+
+
+// 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.
+
+            // 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)
+
+            // 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!
+        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`)
+    })
+}
+
+function braidify (req, res, next) {
+    // console.log('\n## Braidifying', req.method, req.url, req.headers.peer)
+
+    // 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),
+        parents = req.headers.parents && JSON.parse('['+req.headers.parents+']'),
+        peer = req.headers['peer'],
+        url = req.url.substr(1)
+
+    // Parse the subscribe header
+    var subscribe = req.headers.subscribe
+    if (subscribe === 'true')
+        subscribe = true
+
+    // Define convenience variables
+    req.version   = version
+    req.parents   = parents
+    req.subscribe = subscribe
+
+    // Add the braidly request/response helper methods
+    res.sendVersion = (stuff) => send_version(res, stuff, req.url, peer)
+    req.patches = () => new Promise(
+        (done, err) => parse_patches(req, (patches) => done(patches))
+    )
+    req.patchesJSON = () => new Promise(
+        (done, err) => parse_patches(
+            req,
+            (patches) => done(patches.map(
+                p => ({...p, content: JSON.parse(p.content)})
+            ))
+        )
+    )
+    req.startSubscription = res.startSubscription =
+        function startSubscription (args = {}) {
+            // console.log('Starting subscription!')
+            // console.log('Timeouts are:',
+            //             req.socket.server.timeout,
+            //             req.socket.server.keepAliveTimeout)
+
+            res.isSubscription = true
+
+            // Let's disable the timeouts
+            req.socket.server.timeout = 0.0
+
+            // We have a subscription!
+            res.statusCode = 209
+            res.setHeader("subscribe", req.headers.subscribe)
+            res.setHeader('cache-control', 'no-cache, no-transform')
+
+            var connected = true
+            function disconnected (x) {
+                if (!connected) return
+                connected = false
+                // console.log(`Connection closed on ${req.url} from`, x, 'event')
+
+                // Now call the callback
+                if (args.onClose)
+                    args.onClose()
+            }
+
+            res.on('close',   x => disconnected('close'))
+            res.on('finish',  x => disconnected('finish'))
+            req.on('abort',   x => disconnected('abort'))
+        }
+
+    // Check the Useragent to work around Firefox bugs
+    if (req.headers['user-agent'].toLowerCase().indexOf('firefox') > -1)
+        res.is_firefox = true
+
+    next && next()
+}
+
+function send_version(res, data, url, peer) {
+    var {version, parents, patches, body} = data
+
+    function set_header (key, val) {
+        if (res.isSubscription)
+            res.write(`${key}: ${val}\r\n`)
+        else
+            res.setHeader(key, val)
+    }
+    function write_body (body) {
+        if (res.isSubscription)
+            res.write('\r\n' + body + '\r\n')
+        else
+            res.write(body)
+    }
+
+    // console.log('sending version', {url, peer, version, parents, patches, body,
+    //                                 subscription: res.isSubscription})
+
+    // Validate that the body and patches are strings
+    if (body !== undefined)
+        assert(typeof body === 'string')
+    else {
+        assert(patches !== undefined)
+        patches.forEach(p => assert(typeof p.content === 'string'))
+    }
+
+    // Write the headers or virtual headers
+    for (var [header, value] of Object.entries(data)) {
+        // Version and Parents get output in the Structured Headers format
+        if (header === 'version')
+            value = JSON.stringify(value)
+        else if (header === 'parents')
+            value = parents.map(JSON.stringify).join(", ")
+
+        // We don't output patches or body yet
+        else if (header === 'patches' || header == 'body')
+            continue
+
+        set_header(header, value)
+    }
+
+    // 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)
+        write_body(body)
+    } else {
+        console.trace("Missing body or patches")
+        process.exit()
+    }
+
+    // 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
+        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")
+    }
+}
+
+
+module.exports = braidify

package/index.js

@@ -0,0 +1,12 @@
+// This is the root file for require('braid-http').
+//
+// It combines the client and server files into one file.
+
+var client = require('./braid-http-client'),
+    server = require('./braid-http-server')
+
+module.exports = {
+    fetch: client.fetch,
+    http: client.http,
+    http_server: server
+}

package/index.mjs

@@ -0,0 +1,15 @@
+// This is the root file for es modules:
+//
+//    import {fetch, http} from 'braid-http'
+//
+// This file combines the client and server files into one file.
+
+import braid_client from './braid-http-client.js'
+import braid_server from './braid-http-server.js'
+
+var fetch = braid_client.fetch,
+    http  = braid_client.http,
+    http_server = braid_server
+
+export { fetch, http, http_server }
+export default { fetch, http, http_server }

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "braid-http",
+  "version": "0.0.1",
+  "description": "An implementation of Braid-HTTP for Node.js and Browsers",
+  "scripts": {
+    "test": "node test/server.js"
+  },
+  "author": "Braid Working Group",
+  "repository": "braid-org/braidjs",
+  "homepage": "https://braid.org",
+  "files": [
+    "braid-http-client.js",
+    "braid-http-server.js",
+    "index.js",
+    "index.mjs"
+  ],
+  "main": "./index.js",
+  "exports": {
+    "require": "./index.js",
+    "import": "./index.mjs"
+  },
+  "browser": {
+    "node-web-streams": false,
+    "node-fetch": false,
+    "abort-controller": false
+  },
+  "dependencies": {
+    "abort-controller": "^3.0.0",
+    "node-fetch": "^2.6.1",
+    "node-web-streams": "^0.2.2",
+    "parse-headers": "^2.0.3"
+  }
+}

package/readme.md

@@ -0,0 +1,269 @@
+# 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.
+
+Developed in [braid.org](https://braid.org).
+
+
+## Installing
+
+Browsers:
+
+```html
+<script src="https://unpkg.com/braid-http/braid-http-client.js"></script>
+```
+
+Node.js:
+
+```shell
+npm install braid-http
+```
+
+Then in your node.js code:
+
+```javascript
+require('braid-http').fetch       // A polyfill for require('node-fetch')
+require('braid-http').http        // A polyfill for require('http') clients
+require('braid-http').http_server // A polyfill for require('http') servers
+```
+
+## Using it in Browsers
+
+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.subscription`: an iterator that can be used with `for await`
+
+### Example Subscription with Promises
+
+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)
+            // {
+            //   version: "me",
+            //   parents: ["mom", "dad"],
+            //   patches: [{unit: "json", range: ".foo", content: "3"}]
+            //   body:    "3"
+            // }
+            //
+            // Note that new_version will contain either patches *or* body
+        }
+    )
+)
+```
+
+If you want automatic reconnections, add two error handlers like this:
+
+```javascript
+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
+            },
+            e => setTimeout(connect, 1000)
+        )
+    ).catch(e => setTimeout(connect, 1000))
+}
+connect()
+```
+
+### Example Subscription with Async/Await
+
+```javascript
+async function connect () {
+    try {
+        (await fetch('/chat', {subscribe: true})).subscribe(
+            (new_version) => {
+                // We got a new version!
+            },
+            () => setTimeout(connect, 1000)
+        )
+    } catch (e) {
+        setTimeout(connect, 1000)
+    }
+}
+```
+
+### Example Subscription with `for await`
+
+```javascript
+async function connect () {
+    try {
+        for await (var v of fetch('/chat', {subscribe: true}).subscription) {
+            // Updates might come in the form of patches:
+            if (v.patches)
+                chat = apply_patches(v.patches, chat)
+
+            // Or complete versions:
+            else
+                // Beware the server doesn't send these yet.
+                chat = JSON.parse(v.body)
+
+            render_stuff()
+        }
+    } catch (e) {
+        console.log('Reconnecting...')
+        setTimeout(connect, 4000)
+    }
+}
+```
+
+## Using it in Nodejs
+
+### Example Nodejs server with `require('http')`
+
+Braidify adds these fields and methods to requests and responses:
+- `req.subscribe`
+- `req.startSubscription({onClose: cb})`
+- `await req.patches()`
+- `res.sendVersion()`
+
+Use it like this:
+
+```javascript
+var braidify = require('braid-http').http_server
+// or:
+import {http_server as braidify} from 'braid-http'
+
+require('http').createServer(
+    (req, res) => {
+        // Add braid stuff to req and res
+        braidify(req, res)
+
+        // Now use it
+        if (req.subscribe)
+            res.startSubscription({ onClose: _=> null })
+            // startSubscription automatically sets statusCode = 209
+        else
+            res.statusCode = 200
+
+        // Send the current version
+        res.sendVersion({
+            version: 'greg',
+            body: JSON.stringify({greg: 'greg'})
+        })
+    }
+).listen(9935)
+```
+
+### Example Nodejs server with `require('express')`
+
+With `express`, you can simply call `app.use(braidify)` to get braid features
+added to every request and response.
+
+```javascript
+var braidify = require('braid-http').http_server
+// or:
+import {http_server as braidify} from 'braid-http'
+
+var app = require('express')()
+
+app.use(braidify)    // Add braid stuff to req and res
+
+app.get('/', (req, res) => {
+    // Now use it
+    if (req.subscribe)
+        res.startSubscription({ onClose: _=> null })
+        // startSubscription automatically sets statusCode = 209
+    else
+        res.statusCode = 200
+
+    // Send the current version
+    res.sendVersion({
+        version: 'greg',
+        parents: ['gr','eg'],
+        body: JSON.stringify({greg: 'greg'})
+    })
+
+    // Or you can send patches like this:
+    // res.sendVersion({
+    //     version: 'greg',
+    //     parents: ['gr','eg'],
+    //     patches: [{range: '.greg', unit: 'json', content: '"greg"'}]
+    // })
+})
+
+require('http').createServer(app).listen(8583)
+```
+
+
+
+### Example Nodejs client with `require('http')`
+
+```javascript
+// Use this line if necessary for self-signed certs
+// process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0
+
+var https = require('braid-http').http(require('https'))
+// or:
+// import braid_http from 'braid-http'
+// https = braid_http.http(require('https'))
+
+https.get(
+   'https://braid.org/chat',
+   {subscribe: true},
+   (res) => {
+      res.on('version', (version) => {
+          console.log('well we got one', version)
+      })
+   }
+)
+```
+
+To get auto-reconnections use:
+
+```javascript
+function connect () {
+    https.get(
+        'https://braid.org/chat',
+        {subscribe: true},
+        (res) => {
+            res.on('version', (version) => {
+                // {
+                //   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)
+            })
+
+            res.on('end',   e => setTimeout(connect, 1000))
+            res.on('error', e => setTimeout(connect, 1000))
+        })
+}
+connect()
+```
+
+
+### Example Nodejs client with `fetch()`
+
+```javascript
+var fetch = require('braid-http').fetch
+// or:
+import {fetch} from 'braid-http'
+
+// process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0
+
+fetch('https://localhost:3009/chat',
+      {subscribe: true}).andThen(
+          x => console.log('Got ', x)
+      )
+```
+
+Note: the current version of `node-fetch` doesn't properly throw errors when a
+response connection dies, and thus you cannot attach a `.catch()` handler to
+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.
+
+