{"id":41307473,"url":"https://github.com/braid-org/braid-http","last_synced_at":"2026-01-23T05:08:40.790Z","repository":{"id":251346442,"uuid":"837144447","full_name":"braid-org/braid-http","owner":"braid-org","description":"An implementation of Braid-HTTP for Node.js and Browsers","archived":false,"fork":false,"pushed_at":"2026-01-18T02:59:13.000Z","size":459,"stargazers_count":6,"open_issues_count":4,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-01-18T14:42:57.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/braid-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-02T10:00:12.000Z","updated_at":"2026-01-18T02:59:16.000Z","dependencies_parsed_at":"2026-01-04T19:07:28.476Z","dependency_job_id":null,"html_url":"https://github.com/braid-org/braid-http","commit_stats":null,"previous_names":["braid-org/braid-http"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/braid-org/braid-http","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braid-org%2Fbraid-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braid-org%2Fbraid-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braid-org%2Fbraid-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braid-org%2Fbraid-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/braid-org","download_url":"https://codeload.github.com/braid-org/braid-http/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braid-org%2Fbraid-http/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28680623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T04:33:33.518Z","status":"ssl_error","status_checked_at":"2026-01-23T04:33:30.433Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-23T05:08:40.682Z","updated_at":"2026-01-23T05:08:40.764Z","avatar_url":"https://github.com/braid-org.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Braid-HTTP\n\nThis [ponyfill](https://ponyfill.com/) library extends the HTTP\nimplementations of Browsers and Nodejs with Braid-HTTP; transforming them from\n*state transfer* to *state synchronization* systems.\n\nThese features are provided in an elegant, backwards-compatible way:\n- Browsers: get a drop-in replacement for `fetch()`\n- Nodejs: get a route handler that adds abilities to the `http`, `https`, and `http2` modules\n\nIt conforms to the [Braid-HTTP\nv04](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-braid-http-04.txt)\nspecification, with the additional [HTTP\nMultiresponse](https://braid.org/meeting-89) and [Multiplexing\nv1.0](https://braid.org/protocol/multiplexing) extensions.\n\nDeveloped in [braid.org](https://braid.org).\n\n\n## Installing\n\nBrowsers:\n\n```html\n\u003cscript src=\"https://unpkg.com/braid-http/braid-http-client.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // To live on the cutting edge, you can now replace the browser's fetch() if desired:\n  // window.fetch = braid_fetch\n\u003c/script\u003e\n```\n\nNode.js:\n\n```shell\nnpm install braid-http\n```\n\n```javascript\n// Import with require()\nrequire('braid-http').fetch       // A polyfill for fetch\nrequire('braid-http').http_client // A polyfill for require('http') clients\nrequire('braid-http').http_server // A polyfill for require('http') servers\n\n// Or as es6 module\nimport {fetch, http_client, http_server} from 'braid-http'\n```\n\n## Using it in Browsers\n\nThis library adds a `{subscribe: true}` option to `fetch()`, and lets you\naccess the result of a subscription with these new fields on the fetch response:\n\n- `response.subscribe( update =\u003e ... )`\n- `response.subscription`: an iterator that can be used with `for await`\n- `response.version`: the parsed version from the response headers (if present)\n\n### Example Subscription with Promises\n\nHere is an example of subscribing to a Braid resource using promises:\n\n```javascript\nfetch('https://braid.org/chat', {subscribe: true}).then(\n    res =\u003e res.subscribe(\n        (update) =\u003e {\n            console.log('We got a new update!', update)\n            // {\n            //   version: [\"me\"],\n            //   parents: [\"mom\", \"dad\"],\n            //   patches: [{\n            //.      unit: \"json\",\n            //       range: \".foo\",\n            //       content: new Uint8Array([51]),\n            //       content_text: \"3\" \u003c-- getter\n            //.  }],\n            //   body: new Uint8Array([51]),\n            //   body_text: \"3\" \u003c-- getter\n            // }\n            //\n            // Note that `update` will contain either patches *or* body\n        }\n    )\n)\n```\n\nIf you want automatic reconnections, this library add a `{retry: true}` option to `fetch()`.\n\n```javascript\nfetch('https://braid.org/chat', {subscribe: true, retry: true}).then(\n    res =\u003e res.subscribe(\n        (update) =\u003e {\n            console.log('We got a new update!', update)\n            // Do something with the update\n        }\n    )\n)\n```\n\nFor 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.\n\n```javascript\nfetch('https://braid.org/chat', {subscribe: true, retry: true, parents: () =\u003e {\n        return current_parents\n    }}).then(\n    res =\u003e res.subscribe(\n        (update) =\u003e {\n            console.log('We got a new update!', update)\n            // Do something with the update\n        }\n    )\n)\n```\n\n### Example Subscription with Async/Await\n\n```javascript\n(await fetch('/chat', {subscribe: true, retry: true})).subscribe(\n    (update) =\u003e {\n        // We got a new update!\n    })\n```\n\n### Example Subscription with `for await`\n\n```javascript\nvar subscription_iterator = (await fetch('/chat',\n    {subscribe: true, retry: true})).subscription\nfor await (var update of subscription_iterator) {\n    // Updates might come in the form of patches:\n    if (update.patches)\n        chat = apply_patches(update.patches, chat)\n\n    // Or complete snapshots:\n    else\n        // Beware the server doesn't send these yet.\n        chat = JSON.parse(update.body_text)\n\n    render_stuff()\n}\n```\n\n## Using it in Nodejs\n\nYou can braidify your nodejs server with:\n\n```\nvar braidify = require('braid-http').http_server\n```\n\nBraidify adds these new abilities to requests and responses:\n\n- `req.subscribe`\n- `req.startSubscription({onClose: cb})`\n- `await req.parseUpdate()`\n- `res.sendUpdate()`\n\nYou can call it in two ways:\n\n1. `braidify((req, res) =\u003e ...)` wraps your HTTP request handler, and gives it\n   perfectly braidified requests and responses.\n2. `braidify(req, res, next)` will add arguments to your existing requests and\n   responses.  You can use this as express middleware.\n\n### Example Nodejs server with the built-in HTTP module\n\n```javascript\nvar braidify = require('braid-http').http_server\n// or:\nimport {http_server as braidify} from 'braid-http'\n\nrequire('http').createServer(\n    braidify((req, res) =\u003e {\n        // Now braid stuff is available on req and res\n\n        // So you can easily handle subscriptions\n        if (req.subscribe)\n            res.startSubscription({ onClose: _=\u003e null })\n            // startSubscription automatically sets statusCode = 209\n        else\n            res.statusCode = 200\n\n        // And send updates over a subscription\n        res.sendUpdate({\n            version: ['greg'],\n            body: JSON.stringify({greg: 'greg'})\n        })\n    })\n).listen(9935)\n```\n\nYou can also use `braidify` within a request handler like this:\n\n```javascript\nrequire('http').createServer(\n    (req, res) =\u003e {\n        braidify(req, res); if (req.is_multiplexer) return\n        // Now braid stuff is available on req and res\n\n        // ...\n    })\n).listen(9935)\n```\n\nThe `is_multiplexer` test in this form is only necessary if multiplexing is\nenabled.\n\n### Example Nodejs server with Express\n\nOr if you're using `express`, you can just call `app.use(braidify)` to get\nbraid features added to every request and response.\n\n```javascript\nvar braidify = require('braid-http').http_server\n// or:\nimport {http_server as braidify} from 'braid-http'\n\nvar app = require('express')()\n\napp.use(braidify)    // Add braid stuff to req and res\n\napp.get('/', (req, res) =\u003e {\n    // Now use it\n    if (req.subscribe)\n        res.startSubscription({ onClose: _=\u003e null })\n        // startSubscription automatically sets statusCode = 209\n    else\n        res.statusCode = 200\n\n    // Send the current version\n    res.sendUpdate({\n        version: ['greg'],\n        parents: ['gr','eg'],\n        body: JSON.stringify({greg: 'greg'})\n    })\n\n    // Or you can send patches like this:\n    // res.sendUpdate({\n    //     version: ['greg'],\n    //     parents: ['gr','eg'],\n    //     patches: [{range: '.greg', unit: 'json', content: '\"greg\"'}]\n    // })\n})\n\nrequire('http').createServer(app).listen(8583)\n```\n\n\n### Example Nodejs client with `require('http')`\n\n```javascript\n// Use this line if necessary for self-signed certs\n// process.env[\"NODE_TLS_REJECT_UNAUTHORIZED\"] = 0\n\nvar https = require('braid-http').http_client(require('https'))\n// or:\n// import braid_http from 'braid-http'\n// https = braid_http.http_client(require('https'))\n\nhttps.get(\n   'https://braid.org/chat',\n   {subscribe: true},\n   (res) =\u003e {\n      res.on('update', (update) =\u003e {\n          console.log('well we got one', update)\n      })\n   }\n)\n```\n\nTo get auto-reconnections use:\n\n```javascript\nfunction connect () {\n    https.get(\n        'https://braid.org/chat',\n        {subscribe: true},\n        (res) =\u003e {\n            res.on('update', (update) =\u003e {\n                // {\n                //   version: [\"me\"],\n                //   parents: [\"mom\", \"dad\"],\n                //   patches: [{\n                //.      unit: \"json\",\n                //       range: \".foo\",\n                //       content: new Uint8Array([51]),\n                //       content_text: \"3\" \u003c-- getter\n                //.  }],\n                //   body: new Uint8Array([51]),\n                //   body_text: \"3\" \u003c-- getter\n                // }\n                // Update will contain either patches *or* body, but not both\n                console.log('We got a new update!', update)\n            })\n\n            res.on('end',   e =\u003e setTimeout(connect, 1000))\n            res.on('error', e =\u003e setTimeout(connect, 1000))\n        })\n}\nconnect()\n```\n\n\n### Example Nodejs client with `fetch()`\n\n```javascript\nvar fetch = require('braid-http').fetch\n// or:\nimport {fetch} from 'braid-http'\n\n// process.env[\"NODE_TLS_REJECT_UNAUTHORIZED\"] = 0\n\nfetch('https://localhost:3009/chat',\n      {subscribe: true}).andThen(\n          x =\u003e console.log('Got ', x)\n      )\n```\n\n## Configuring Multiplexing\n\nYou shouldn't need to, but can, configure which requests the library will\n[multiplex](https://braid.org/protocol/multiplexing).  You can configure\nmultiplexing on both the client and the server.  They both need multiplexing\nenabled for it to happen.\n\n### Client\n\nA client can globally disable multiplexing on `braid_fetch()` with:\n\n```javascript\nbraid_fetch.enable_multiplex = false\n```\n\nIt can enable multiplexing for all GET requests with:\n\n```javascript\nbraid_fetch.enable_multiplex = true\n```\n\nIt can also set it to multiplex after `N` connections to an origin with:\n\n```javascript\nbraid_fetch.enable_multiplex = {after: N}\n```\n\nThe default value is `{after: 1}`.\n\nA client can override this global setting per-request by passing the same\nvalue into `braid_fetch(url, {multiplex: \u003cvalue\u003e})`, such as with:\n\n```javascript\nbraid_fetch('/example', {multiplex: true, subscription: true})\nbraid_fetch('/example', {multiplex: false, subscription: true})\n// or\nbraid_fetch('/example', {multiplex: {after: 1}, subscription: true})\n```\n\n### Server\n\nConfigure mutliplexing with:\n\n```javascript\nvar braidify = require('braid-http').http-server\nnbraidify.enable_multiplex = true   // or false\n```\n\n## Test Procedure\n\nRun tests from the command line:\n\n```\nnode test/test.js\n```\n\nOr run tests in a browser by starting the test server:\n\n```\nnode test/test.js --browser\n```\n\nThen open https://localhost:9000 and make sure all the boxes turn green.\n\nYou can also filter tests by name:\n\n```\nnode test/test.js --filter=\"version\"\n```\n\nFor the complete browser test (including demos), use 3 terminals. In the first terminal start the demo chat server:\n\n```\ncd demos/chat\nnode server.js\n```\n\nIn the second terminal start the demo blog server:\n```\ncd demos/blog\nnode server.js\n```\n\nAnd in the third terminal, start the test server:\n```\nnode test/test.js --browser\n```\n\nNow open https://localhost:9000, make sure all the boxes turn green, and try out the demo chat and blog, sending a message in each.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraid-org%2Fbraid-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbraid-org%2Fbraid-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraid-org%2Fbraid-http/lists"}