Build a Braid Client with Braid-Fuzz

Braid-Fuzz is a test framework for braid-http client implementations. It helps you build a new braid-http client that syncs perfectly. It's great for guiding an AI.

Run your client through this gauntlet, and get back pass/fail results that an AI agent (or human) can act on.

First, connect your client to Braid-Fuzz

Implement a controller in your client that lets Braid-Fuzz control it. For example, if your client runs in nodejs, you'd write:

var readline = require('readline').createInterface({ input: process.stdin })
readline.on('line', (line) => {

  // The message is json
  var msg = JSON.parse(line)

  // Each message gives us a command
  switch (msg.cmd) {

    // The "hello" command tells us to reply back
    case "hello": {
      reply(msg.id)
      break
    }

    // The "results" gives us test results, and tells us to exit.
    case "results": {
      reply(msg.id)
      setTimeout(() => process.exit(0), 100)
      break
    }

    // You will implement additional commands here, to do things like edit
    // text, or open a HTTP network connection to a URL.

  }
})

// This is how we send data back to Braid-Fuzz
function reply(id, data) {
    process.stdout.write(JSON.stringify({ id, ok: true, ...data }) + "\n")
}
function reply_error(id, msg) {
    process.stdout.write(JSON.stringify({ id, error: msg }) + "\n")
}

(You can also communicate via TCP or WebSocket instead of STDIO if needed. See below.)

Now, write a headless launch-script.sh, that Braid-Fuzz can launch your client with. Something like this:

#!/bin/bash
./my-cool-client --headless --load-plugin=controller.js

Great! Now install braid-fuzz, and test your connection to it:

# Install braid-fuzz so you can run it as a command
npm install -g braid-fuzz

# Run the basic tests
braid-fuzz <launch-script.sh> basics

Jacked in? Now run the Feature Gauntlet!

For each feature below, you will:

Add controller commands to test the feature
Implement the feature
Test with braid-fuzz <launch-script.sh> <feature-name>
Fix the failures and iterate until tests pass!

Regular HTTP

This test whether your client can send a basic PUT and a GET.

Run these tests with:

braid-fuzz <launch-client.sh> http

Commands to implement:

Command	JSON `cmd`	What to do
Open HTTP request	`open-http`	Call `braid_fetch(url, {subscribe: true, ...})`. Push each update back as an `update` event.
Send PUT	`open-http`	Call `braid_fetch(url, {method: "PUT", version, parents, patches, ...})`. Push result as `ack`.

Subscriptions and Updates

These test subscription parsing in detail: snapshots, incremental patches, multi-patch updates, Patches: 0, and the Parents header.

Subscriptions: Making subscriptions, parsing streams of updates
Updates: Patches and whatnot

Run these tests with:

braid-fuzz <launch-client.sh> subscriptions

You need just one more command:

Command	JSON `cmd`	What to do
Close HTTP request	`close-http`	Abort the current `braid_fetch` subscription.

Reliable Updates

This tests your client's ability to recover from network failures gracefully:

Reliable Updates: Noticing and recovering from network failures
- Reconnection
- Retry
- Heartbeat detection
- PUT retry

Run with:

braid-fuzz <launch-client.sh> reliable-updates

These use the same commands as above.

Text Editing

This tests text edit synchronization, using the simpleton protocol:

Simpleton: the simpleton text sync protocol

Run these tests with:

braid-fuzz <launch-client.sh> simpleton

You need to implement these controller commands:

Command	JSON `cmd`	What to do
Sync text	`sync-text`	Start a `simpleton_client` subscription to the given URL.
End sync	`end-sync`	Abort the simpleton subscription.
Edit	`edit`	Edit the local buffer at `pos`, removing `len` chars, inserting `text`. Triggers a PUT via `simpleton.changed()`.
Send text	`send-text`	Respond with `{"state": "current buffer text"}`.
Ack	`ack`	Block until all pending PUTs are acknowledged.

Multiplayer Cursors

This tests syncing cursor locations and selections within text documents across multiple clients:

Cursors

Run these tests with:

braid-fuzz <launch-client.sh> cursors

You need to implement these controller commands:

Command	JSON `cmd`	What to do
Connect cursors	`connect-cursors`	Start cursor sharing on the currently synced document. Subscribe to `application/text-cursors+json` updates.
Set cursor	`set-cursor`	Set the local cursor position. `pos` is a 0-based character index; `end` (optional) is the end of a selection range. Triggers a cursor PUT.
Get cursors	`get-cursors`	Respond with `{"cursors": {"peer-id": [{"from": N, "to": N}], ...}}` showing all remote cursors.

Indexes

This tests syncing directories of multiple files:

Webindex

TBD

Putting it all together

You can run the full test-suite periodically to verify that prior features are still working with:

braid-fuzz <launch-script> everything

Protocol Details

Connection

Stdin/Stdout:

Each message is newline-delimited

TCP

Each message is newline-delimited
Client connects to localhost:4445

WebSocket:

Each message is a WebSocket message
Client connects to ws://localhost:4444

Messages

Communication is JSON-RPC-like. There is one command or response per line (stdin/stdout and TCP) or per message (WebSocket).

Each command from braid-fuzz includes an id and cmd field. Your controller responds with the same id and either "ok": true or "error": "...". When all tests finish, braid-fuzz sends a results command with the test results.

Example flow

Controller                              braid-fuzz
  |                                         |
  |  {"id":1,"cmd":"hello"}                 |
  |  <────────────────────────────────────  |
  |                                         |
  |  {"id":1, "ok":true}                    |
  |  ────────────────────────────────────>  |
  |                                         |
  |  {"id":2,"cmd":"open-http","url":..}     |
  |  <────────────────────────────────────  |
  |                                         |
  |  {"id":2, "ok":true}                    |
  |  ────────────────────────────────────>  |
  |                                         |
  |  (updates arrive from braid server —    |
  |   controller forwards them as events)   |
  |                                         |
  |  {"event":"update", ...}                |
  |  ────────────────────────────────────>  |
  |                                         |
  |  ... more commands and events ...       |
  |                                         |
  |  {"cmd":"results", "results":[...]}     |
  |  <────────────────────────────────────  |
  |                                         |
  |  {"id":N, "ok":true}                    |
  |  ────────────────────────────────────>  |

Overview of commands

Basic commands
- Hello: We begin! Respond with ok.
- Results: Testing is done. Receive results and clean up.
HTTP commands
- Open HTTP request
- Close HTTP request
Text Sync commands
- Sync text: Start syncing client text with a url
- End sync: End syncing
- Edit: Simulate a user text edit
- Send text: Send a copy of the client's text buffer back to braid-fuzz
- Ack: Notify braid-fuzz when all client edits to get acknowledged by server
Cursor commands
- Connect cursors: Start cursor sharing on the synced document
- Set cursor: Set local cursor position
- Get cursors: Return all remote cursor positions

Commands (server → client)

Every command includes an id (integer, assigned by the server) and a cmd (string). The client must echo back the same id in its response.

`hello` — Greeting

{"id": 1, "cmd": "hello"}

Respond with {"id": 1, "ok": true}. This is the first command sent, used by the basics tests.

`results` — Test results

{"id": 2, "cmd": "results", "results": [...], "summary": {"passed": 5, "failed": 1, ...}}

Sent when all tests are done. The command includes the full test results. Respond with ok, then clean up and exit.

`open-http` — Call the client's braid_fetch

{"id": 1, "cmd": "open-http", "url": "http://...", "subscribe": true, "headers": {"Merge-Type": "simpleton"}}

Mirrors the braid_fetch API directly. The client should call its braid_fetch function with the given options.

Field	Type	Description
`url`	string	Full HTTP URL
`method`	string	`"GET"` (default) or `"PUT"`
`subscribe`	boolean	`true` to open a subscription (GET only)
`version`	array	Version strings (PUT only)
`parents`	array	Parent version strings (PUT only)
`patches`	array	Array of `{unit, range, content}` (PUT only)
`headers`	object	Extra headers (optional)

For subscriptions (subscribe: true), push updates as they arrive:

{"event": "update", "data": {"version": [...], "parents": [...], "body": "...", "patches": [...]}}

The data object should include:

version — the update's Version header (array of strings, or null)
parents — the update's Parents header (array of strings, or null)
body — the full body text (for snapshot updates)
patches — array of {range: [start, end], content: "..."} (for incremental updates)

For PUTs (method: "PUT"), push the result:

{"event": "ack", "data": {"status": 200}}

On errors (either type):

{"event": "error", "data": {"message": "..."}}

Used by subscription, reliable-updates, and PUT tests.

`close-http` — Abort a braid_fetch subscription

{"id": 2, "cmd": "close-http"}

Aborts the current braid_fetch subscription.

`sync-text` — Open a simpleton subscription

{"id": 3, "cmd": "sync-text", "url": "http://127.0.0.1:4567/doc"}

Field	Type	Description
`url`	string	Full HTTP URL of the braid-text resource to subscribe to

The client should start a simpleton_client (or equivalent) subscription to the given URL, wiring up on_state / get_state callbacks so the local buffer tracks remote state. Used by simpleton tests.

`edit` — Edit the local buffer

{"id": 4, "cmd": "edit", "pos": 3, "len": 2, "text": "x"}

Field	Type	Description
`pos`	number	0-based character index (not byte offset). Default: 0
`len`	number	Number of characters to remove. Default: 0
`text`	string	Text to insert at `pos` after removing. Default: ""

Mutates the local buffer and triggers a PUT to the server (via simpleton.changed() or equivalent). Covers insert (len: 0), delete (text: ""), and replace.

`send-text` — Return the current buffer contents

{"id": 7, "cmd": "send-text"}

Response must include a state field:

{"id": 7, "ok": true, "state": "current buffer text"}

`ack` — Block until all pending PUTs are acknowledged

{"id": 8, "cmd": "ack"}

The client must not respond until every previously triggered PUT has received an ACK from the server. If there are no pending PUTs, respond immediately.

`end-sync` — Tear down the active simpleton subscription

{"id": 9, "cmd": "end-sync"}

Aborts the current simpleton subscription. Does not clear the local buffer.

Responses (client → runner)

Every response is a single JSON line containing the id from the command.

Success:

{"id": 1, "ok": true}

Success with data (only state returns extra fields):

{"id": 7, "ok": true, "state": "buffer contents here"}

Error:

{"id": 1, "error": "description of what went wrong"}

Unsolicited events (no id — pushed proactively by the client):

{"event": "update", "data": {...}}
{"event": "ack", "data": {"status": 200}}
{"event": "error", "data": {"message": "..."}}

See examples/braid-text-simpleton-controller.js for a complete reference implementation.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Test Runner (Node.js)                 │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │ Test Suites  │  │ Socket Proxy │  │ Braid-Text     │  │
│  │              │  │ (fault       │  │ Server         │  │
│  │              │  │  injection)  │  │ (real CRDT)    │  │
│  └──────┬───────┘  └──────┬───────┘  └───────┬────────┘  │
│         │                 │                  │           │
│         ▼                 ▼                  │           │
│  ┌─────────────────────────────┐             │           │
│  │      Client Bridge          │◄────────────┘           │
│  │  WebSocket, TCP, or stdio   │                         │
│  └──────────┬──────────────────┘                         │
│             │                                            │
│             ▼                                            │
│  ┌─────────────────────────────┐                         │
│  │  Your client (any language) │                         │
│  └─────────────────────────────┘                         │
└──────────────────────────────────────────────────────────┘

Test server (server.js) — wraps braid-text with a control API for making server-side edits, reading state, and configuring behavior (ACK delays, PUT drops, etc.)
Socket proxy (proxy.js) — TCP proxy between client and server. Supports modes: passthrough, blackhole, rst, close, delay, corrupt. Tests switch modes to simulate network faults.
Client bridge — communicates with the client under test via WebSocket, TCP (lib/stream-bridge.js), or stdin/stdout (lib/client-bridge.js). All transports use the same JSON-lines protocol.
Test suites (tests/) — discrete, named tests with structured assertions.

Extra stuff

Example Scripts

See the example controller and launch script for braid-text simpleton: braid-text-simpleton-controller.js, braid-text-simpleton-launcher.sh.

Reading specs from disk

When you run braid-fuzz, it automatically downloads the latest Braid protocol specs into the specs/ directory. If you're using an AI agent to build your client, point it at these files for the full protocol details:

specs/subscriptions.md — how subscriptions and update streams work (source)
specs/reliable-updates.md — retry, reconnection, and heartbeat behavior (source)
specs/reliable-updates-tests.md — detailed test scenarios (source)
specs/simpleton.md — the simpleton text sync protocol (source)
specs/cursors.md — multiplayer cursors (source)

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
examples		examples
lib		lib
tests		tests
README.md		README.md
braid-fuzz.js		braid-fuzz.js
fuzz-server.js		fuzz-server.js
package-lock.json		package-lock.json
package.json		package.json
proxy.js		proxy.js
server.js		server.js
test-runner.js		test-runner.js

Folders and files

Latest commit

History

Repository files navigation

Build a Braid Client with Braid-Fuzz

First, connect your client to Braid-Fuzz

Jacked in? Now run the Feature Gauntlet!

Regular HTTP

Subscriptions and Updates

Reliable Updates

Text Editing

Multiplayer Cursors

Indexes

Putting it all together

Protocol Details

Connection

Messages

Example flow

Overview of commands

Commands (server → client)

hello — Greeting

results — Test results

open-http — Call the client's braid_fetch

close-http — Abort a braid_fetch subscription

sync-text — Open a simpleton subscription

edit — Edit the local buffer

send-text — Return the current buffer contents

ack — Block until all pending PUTs are acknowledged

end-sync — Tear down the active simpleton subscription

Responses (client → runner)

Architecture

Extra stuff

Example Scripts

Reading specs from disk

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`hello` — Greeting

`results` — Test results

`open-http` — Call the client's braid_fetch

`close-http` — Abort a braid_fetch subscription

`sync-text` — Open a simpleton subscription

`edit` — Edit the local buffer

`send-text` — Return the current buffer contents

`ack` — Block until all pending PUTs are acknowledged

`end-sync` — Tear down the active simpleton subscription

Packages