braid_rs

A unified Rust implementation of the Braid Protocol for building decentralized, synchronized web applications.

Features

Quick Start

[dependencies]

braid_rs = "0.1.0"

Braid-HTTP Client

use braid_rs::core::client::BraidClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = BraidClient::new();
    
    // Simple GET request
    let response = client.get("http://braid.org/resource").await?;
    println!("Content: {:?}", response.body());
    
    // Subscribe to updates
    let mut subscription = client.subscribe("http://braid.org/resource").await?;
    while let Some(update) = subscription.next().await {
        println!("Update: version={:?}", update.version);
    }
    
    Ok(())
}

Antimatter CRDT

use braid_rs::antimatter::{AntimatterCrdt, PrunableCrdt};
use braid_rs::antimatter::messages::Patch;
use serde_json::json;

// Create CRDT with send callback
let mut crdt = AntimatterCrdt::new(
    Some("peer1".to_string()),
    MyCrdt::new(),
    Box::new(|msg| { /* send to other peers */ }),
);

// Apply local edit
let version = crdt.update(vec![Patch {
    range: "0:0".to_string(),
    content: json!("Hello"),
}]);

// Get current state
println!("Content: {}", crdt.crdt.get_content());
println!("Version: {:?}", crdt.current_version);

// Prune history when acknowledged
crdt.prune(false);

MergeType System

use braid_rs::core::merge::{MergeType, MergeTypeRegistry, MergePatch};
use serde_json::json;

// Create registry with built-in types
let mut registry = MergeTypeRegistry::new();

// Get a merge type by name
let mut merge = registry.create("sync9", "peer1").unwrap();

// Initialize with content
merge.initialize("Hello World");

// Apply local edit
let patch = MergePatch::new("0:5", json!("Hi"));
let result = merge.local_edit(patch);

println!("New version: {:?}", result.version);
println!("Content: {}", merge.get_content());

Axum Server Integration

use axum::{Router, routing::get};
use braid_rs::core::server::{BraidLayer, BraidState};

async fn handler() -> impl IntoResponse {
    "Hello from Braid!"
}

let app = Router::new()
    .route("/resource", get(handler))
    .layer(BraidLayer::new().middleware());

Architecture

braid_rs/
├── src/
│   ├── core/           # Braid-HTTP protocol
│   │   ├── client/     # HTTP client with subscriptions
│   │   ├── server/     # Axum middleware & handlers
│   │   ├── merge/      # MergeType trait & implementations
│   │   └── protocol/   # Protocol constants & types
│   │
│   ├── antimatter/     # Antimatter CRDT (JS-compatible)
│   │   ├── antimatter.rs    # Main coordination layer
│   │   ├── sequence_crdt.rs # Text/array CRDT
│   │   ├── json_crdt.rs     # Recursive JSON CRDT
│   │   └── messages.rs      # Protocol messages
│   │
│   ├── blob/           # Content-addressable storage
│   │   ├── store.rs    # SQLite metadata + FS storage
│   │   └── http.rs     # Axum HTTP endpoints
│   │
│   └── fs/             # Filesystem sync daemon
│       ├── mod.rs      # Daemon & file watching
│       └── config.rs   # .braidignore, debouncing

Binaries

braidfs

Sync local files with a Braid server:

# Start the daemon

braidfs run


# Add a sync mapping

braidfs sync ./my-folder http://example.com/resource

braid-blob

Run a standalone blob server:

braid-blob serve --port 8080 --data ./data

Configuration

.braidignore

Place a .braidignore file in synced directories:

# Ignore git files
.git
.git/**

# Ignore dependencies
node_modules/**

# Ignore temp files
*.swp
*.swo
*~

BraidFS Config

Location: ~/.braidfs/config

{
  "port": 45678,
  "debounce_ms": 100,
  "sync": {
    "./project": true
  },
  "ignore_patterns": [".git/**", "node_modules/**"]
}

Protocol Compliance

This implementation follows draft-toomim-httpbis-braid-http-04:

License

Dual-licensed under Apache 2.0 or MIT at your option.

Links

• Braid Specification
• Antimatter Algorithm
• Braid-HTTP Draft