braid-text 0.0.1

package/README.md

@@ -0,0 +1,122 @@
+# Collaborative text over Braid-HTTP
+
+This library provides a simple http route handler, along with client code, enabling fast text synchronization over a standard protocol.
+
+- Supports [Braid-HTTP](https://github.com/braid-org/braid-spec/blob/master/draft-toomim-httpbis-braid-http-04.txt) protocol
+- Supports [Simpleton](https://braid.org/meeting-76/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](https://github.com/josephg/diamond-types) merge-type
+  - Fast / Robust / Extensively fuzz-tested 
+- Developed in [braid.org](https://braid.org)
+
+## Use the Library on the Server
+
+Install it in your project:
+```shell
+npm install braid-text
+```
+
+Import the request handler into your code, and use it to handle HTTP requests wherever you want:
+
+```javascript
+var braid_text = require("braid-text")
+
+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:
+
+```shell
+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](https://github.com/braid-org/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 Server Library API
+
+`braid_text.db_folder = './braid-text-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`: <small style="color:lightgrey">[optional]</small> An object containing additional options:
+    - `key`:  <small style="color:lightgrey">[optional]</small> ID of text resource to sync with.  Defaults to `req.url`.
+  - This is the main method of this library, and does all the work to handle Braid-HTTP `GET` and `PUT` requests concerned with 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`:  <small style="color:lightgrey">[optional]</small> The version to get.
+    - `subscribe: cb`:  <small style="color:lightgrey">[optional]</small> Transforms `get` into a subscription that calls `cb` with each update. The function `cb` is called with the argument `{version, parents, body, patches}` with each update to the text.
+    - `parents`:  <small style="color:lightgrey">[optional]</small> Array of parents — the subscription will only send newer updates than these.
+    - `merge_type`: <small style="color:lightgrey">[optional]</small> When subscribing, identifies the synchronization protocol. Defaults to `simpleton`, but can be set to `dt`.
+    - `peer`: <small style="color:lightgrey">[optional]</small> When subscribing, identifies this peer. Mutations will not be echoed back to the same peer that puts them, if that put also sets the same `peer` header.
+
+  - 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`:  <small style="color:lightgrey">[optional]</small> The version being supplied. Will be randomly generated if not supplied.
+    - `parents`:  <small style="color:lightgrey">[optional]</small> Array of versions this update depends on. Defaults to the server’s current version.
+    - `body`: <small style="color:lightgrey">[optional]</small> Use this to completely replace the existing text with this new text.
+    - `patches`: <small style="color:lightgrey">[optional]</small> 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`.
+    - `peer`: <small style="color:lightgrey">[optional]</small> Identifies this peer. This mutation will not be echoed back to `get` subscriptions that use this same `peer` header.
+
+## Use the Library on the Client
+
+    <script src="https://unpkg.com/braid-text/client.js"></script>
+    
+    ...
+    // connect to the server
+    let braid_text = braid_text_client(SERVER_URL, {
+      apply_remote_update: ({ state, patches }) => {
+        // apply incoming state / return new state
+      },
+      generate_local_diff_update: (prev_state) => {
+        // report changes between prev_state and the current state
+      },
+    });
+    
+    ...
+    
+    // when changes are made, let braid-text know
+    braid_text.changed()
+
+See [editor.html](https://raw.githubusercontent.com/braid-org/braid-text/master/editor.html) for a simple working example.
+
+## Full Client Library API
+
+    braid_text = braid_text_client(url, {
+      apply_remote_update,
+      generate_local_diff_update}
+
+  - `url`: The url of the resource to synchronize with.
+  - `apply_remote_update`: This function will be called whenever an update is received from the server. The function should look like `({state, patches}) => {...}`. Only one of `state` or `patches` will be set. If it is `state`, then this is the new value of the text. If it is `patches`, then patches is an array of values like `{range: [1, 3], content: "Hi"}`. Each such value represents a string-replace operation; the `range` specifies a start and end position — these characters will be deleted — and `content` says what text to put in its place. Note that these patches will always be in order, but that the range positions of each patch always reference the original string, e.g., the second patch's range values do not take into account applying the first patch. Finally, this function returns the new state, after the application of the `state` or `patches`.
+  - `generate_local_diff_update`: This function will often be called whenever an update happens locally, but the system may delay calling it if the network is congested. The function should look like `(prev_state) => {...}`. The function should basically do a diff between `prev_state` and the current state, and express this diff as an array of patches similar to the ones discussed above. Finally, if there is an actual difference detected, this function should return an object `{state, patches}`, otherwise it should return nothing.
+  - `braid_text.changed()`: Call this to report local updates whenever they occur, e.g., in the `oninput` handler of a textarea being synchronized.

package/client.js

@@ -0,0 +1,173 @@
+// requires braid-http@0.3.14
+// 
+// url: resource endpoint
+//
+// apply_remote_update: ({patches, state}) => {...}
+//     this is for incoming changes;
+//     one of these will be non-null,
+//     and can be applied to the current state.
+//
+// generate_local_diff_update: (prev_state) => {...}
+//     this is to generate outgoing changes,
+//     and if there are changes, returns { patches, state }
+//
+// content_type: overrides the Accept and Content-Type headers
+//
+// returns { changed(): (diff_function) => {...} }
+//     this is for outgoing changes;
+//     diff_function = () => ({patches, new_version}).
+//
+function braid_text_client(url, { apply_remote_update, generate_local_diff_update, content_type }) {
+    var peer = Math.random().toString(36).substr(2)
+    var current_version = []
+    var prev_state = ""
+    var char_counter = -1
+    var outstanding_changes = 0
+    var max_outstanding_changes = 10
+
+    braid_fetch_wrapper(url, {
+        headers: { "Merge-Type": "simpleton",
+            ...(content_type ? {Accept: content_type} : {}) },
+        subscribe: true,
+        retry: true,
+        parents: () => current_version.length ? current_version : null,
+        peer
+    }).then(res =>
+        res.subscribe(update => {
+            // Only accept the update if its parents == our current version
+            update.parents.sort()
+            if (current_version.length === update.parents.length
+                && current_version.every((v, i) => v === update.parents[i])) {
+                current_version = update.version.sort()
+                update.state = update.body
+
+                if (update.patches) {
+                    for (let p of update.patches) p.range = p.range.match(/\d+/g).map((x) => 1 * x)
+                    update.patches.sort((a, b) => a.range[0] - b.range[0])
+
+                    // convert from code-points to js-indicies
+                    let c = 0
+                    let i = 0
+                    for (let p of update.patches) {
+                        while (c < p.range[0]) {
+                            i += get_char_size(prev_state, i)
+                            c++
+                        }
+                        p.range[0] = i
+
+                        while (c < p.range[1]) {
+                            i += get_char_size(prev_state, i)
+                            c++
+                        }
+                        p.range[1] = i
+                    }
+                }
+
+                prev_state = apply_remote_update(update)
+            }
+        })
+    )
+    
+    return {
+      changed: async () => {
+        if (outstanding_changes >= max_outstanding_changes) return
+        while (true) {
+            var update = generate_local_diff_update(prev_state)
+            if (!update) return   // Stop if there wasn't a change!
+            var {patches, state} = update
+
+            // convert from js-indicies to code-points
+            let c = 0
+            let i = 0
+            for (let p of patches) {
+                while (i < p.range[0]) {
+                    i += get_char_size(prev_state, i)
+                    c++
+                }
+                p.range[0] = c
+
+                while (i < p.range[1]) {
+                    i += get_char_size(prev_state, i)
+                    c++
+                }
+                p.range[1] = c
+
+                char_counter += p.range[1] - p.range[0]
+                char_counter += count_code_points(p.content)
+
+                p.unit = "text"
+                p.range = `[${p.range[0]}:${p.range[1]}]`
+            }
+
+            var version = [peer + "-" + char_counter]
+
+            var parents = current_version
+            current_version = version
+            prev_state = state
+
+            outstanding_changes++
+            await braid_fetch_wrapper(url, {
+                headers: { "Merge-Type": "simpleton",
+                    ...(content_type ? {"Content-Type": content_type} : {}) },
+                method: "PUT",
+                retry: true,
+                version, parents, patches,
+                peer
+            })
+            outstanding_changes--
+        }
+      }
+    }
+}
+
+function get_char_size(s, i) {
+    const charCode = s.charCodeAt(i)
+    return (charCode >= 0xd800 && charCode <= 0xdbff) ? 2 : 1
+}
+
+function count_code_points(str) {
+    let code_points = 0
+    for (let i = 0; i < str.length; i++) {
+        if (str.charCodeAt(i) >= 0xd800 && str.charCodeAt(i) <= 0xdbff) i++
+        code_points++
+    }
+    return code_points
+}
+
+async function braid_fetch_wrapper(url, params) {
+    if (!params.retry) throw "wtf"
+    var waitTime = 10
+    if (params.subscribe) {
+        var subscribe_handler = null
+        connect()
+        async function connect() {
+            try {
+                var c = await braid_fetch(url, { ...params, parents: params.parents?.() })
+                c.subscribe((...args) => subscribe_handler?.(...args), on_error)
+                waitTime = 10
+            } catch (e) {
+                on_error(e)
+            }
+        }
+        function on_error(e) {
+          console.log('eee = ' + e.stack)
+            setTimeout(connect, waitTime)
+            waitTime = Math.min(waitTime * 2, 3000)
+        }
+        return {subscribe: handler => { subscribe_handler = handler }}
+    } else {
+        return new Promise((done) => {
+            send()
+            async function send() {
+                try {
+                    var res = await braid_fetch(url, params)
+                    if (res.status !== 200) throw "status not 200: " + res.status
+                    done(res)
+                } catch (e) {
+                    setTimeout(send, waitTime)
+                    waitTime = Math.min(waitTime * 2, 3000)
+                }
+            }
+        })
+    }
+}

package/editor.html

@@ -0,0 +1,79 @@
+<body style="background: auto; margin: 0px; padding: 0px">
+  <textarea
+    id="texty"
+    style="width: 100%; height: 100%; box-sizing: border-box"
+  ></textarea>
+</body>
+<script src="https://braid.org/code/myers-diff1.js"></script>
+<script src="https://unpkg.com/braid-http@~0.3/braid-http-client.js"></script>
+<script src="https://unpkg.com/braid-text/client.js"></script>
+<script>
+  let braid_text = braid_text_client(location.pathname, {
+    apply_remote_update: ({ state, patches }) => {
+      if (state !== undefined) texty.value = state;
+      else apply_patches_and_update_selection(texty, patches);
+      return texty.value;
+    },
+    generate_local_diff_update: (prev_state) => {
+      var patches = diff(prev_state, texty.value);
+      if (patches.length === 0) return null;
+      return { patches, state: texty.value };
+    },
+  });
+
+  texty.value = "";
+  texty.oninput = (e) => braid_text.changed();
+
+  function diff(before, after) {
+    let diff = diff_main(before, after);
+    let patches = [];
+    let offset = 0;
+    for (let d of diff) {
+      let p = null;
+      if (d[0] == 1) p = { range: [offset, offset], content: d[1] };
+      else if (d[0] == -1) {
+        p = { range: [offset, offset + d[1].length], content: "" };
+        offset += d[1].length;
+      } else offset += d[1].length;
+      if (p) {
+        p.unit = "text";
+        patches.push(p);
+      }
+    }
+    return patches;
+  }
+
+  function apply_patches_and_update_selection(textarea, patches) {
+    let offset = 0;
+    for (let p of patches) {
+      p.range[0] += offset;
+      p.range[1] += offset;
+      offset -= p.range[1] - p.range[0];
+      offset += p.content.length;
+    }
+
+    let original = textarea.value;
+    let sel = [textarea.selectionStart, textarea.selectionEnd];
+
+    for (var p of patches) {
+      let range = p.range;
+
+      for (let i = 0; i < sel.length; i++)
+        if (sel[i] > range[0])
+          if (sel[i] > range[1]) sel[i] -= range[1] - range[0];
+          else sel[i] = range[0];
+
+      for (let i = 0; i < sel.length; i++)
+        if (sel[i] > range[0]) sel[i] += p.content.length;
+
+      original =
+        original.substring(0, range[0]) +
+        p.content +
+        original.substring(range[1]);
+    }
+
+    textarea.value = original;
+    textarea.selectionStart = sel[0];
+    textarea.selectionEnd = sel[1];
+  }
+</script>