Serve collaborative text over Braid-HTTP

This library provides a simple http route handler, enabling fast text synchronization over a standard protocol.

• Supports Braid-HTTP protocol
• Supports Simpleton merge-type
  • Enables light clients
    • As little as 50 lines of code!
    • With zero history overhead on client
  • Supports backpressure to run smoothly on constrained servers
• Supports Diamond Types merge-type
  • Fast / Robust / Extensively fuzz-tested
• Developed in braid.org

Use the Library

Install it in your project:

npm install braid-text-server

Import the request handler into your code, and use it to handle HTTP requests wherever you want:

var braid_text = require("braid-text-server")

server.on("request", (req, res) => {
  // Your server logic...

  // Whenever desired, serve braid text for this request/response:
  braid_text.serve(req, res)
})

Run the Demo

This will run a collaboratively-editable wiki:

npm install
node server-demo.js

Now open these URLs in your browser:

• http://localhost:8888/demo (to see the demo text)
• http://localhost:8888/demo?editor (to edit the text)
• http://localhost:8888/demo?markdown-editor (to edit it as markdown)

Or try opening the URL in Braid-Chrome, or another Braid client, to edit it directly!

Check out the server-demo.js file to see examples for how to add access control, and a /pages endpoint to show all the edited pages.

Full Library API

braid_text.db_folder = './braid-text-server-db' // <-- this is the default

• This is where the Diamond-Types history files will be stored for each resource.
• This folder will be created if it doesn't exist.
• The files for a resource will all be prefixed with a url-encoding of key within this folder.

braid_text.server(req, res, options)

• req: The incoming HTTP request object.
• res: The HTTP response object to send the response.
• options: [optional] An object containing additional options:
  • key: [optional] ID of text resource to sync with. Defaults to req.url.
  • content_type: [optional] The content type to tell the browser. Defaults to 'text/plain'.
• This is the main method of this library, and does all the work to handle Braid-HTTP GET and PUT requests concerned which a specific text resource.

await braid_text.get(key)

• key: ID of text resource.
• Returns the text of the resource as a string.

await braid_text.get(key, options)

• key: ID of text resource.
• options: An object containing additional options, like http headers:
  • version: [optional] The version to get.
  • parents: [optional] Array of parents — can also be used to define a version we want
  • subscribe: cb: [optional] Transforms get into a subscription that calls cb witch each update. The function cb is called with the argument {version, parents, body, patches} with each update to the text.
  • merge_type: [optional] When subscribing, identifies the synchronization protocol. Defaults to simpleton, but can be set to dt.
  • peer: [optional] When subscribing, identifies this peer, so PUTs are not mirrored back.
• If we are NOT subscribing, returns {version, body}, with the version being returned, and the text as body. If we are subscribing, this returns nothing.

await braid_text.put(key, options)

• key: ID of text resource.
• options: An object containing additional options, like http headers:
  • version: [optional] The version being supplied. Will be randomly generated if not supplied.
  • parents: [optional] Array of versions this update depends on. Defaults to whatever the most recent version is.
  • body: [optional] Use this to completely replace the existing text with this new text.
  • patches: [optional] Array of patches, each of the form {unit: 'text', range: '[1:3]', content: 'hi'}, which would replace the second and third unicode code-points in the text with hi.