Crate autosurgeon 

AutoSurgeon

autosurgeon is a library for interaction with automerge documents in Rust with an API inspired by serde. The core of the library are two traits: Reconcile, which describes how to take a rust value and update an automerge document to match the value; and Hydrate, which describes how to create a rust value given an automerge document.

Whilst you can implement Reconcile and Hydrate manually, autosurgeon provides derive macros to do this work mechanically.

Additionally autosurgeon provides the Counter and Text data types which implement Reconcile and Hydrate for counters and text respectively.

Currently this library does not handle incremental updates, that means that every time you receive concurrent changes from other documents you will need to re-hydrate your data structures from your document. This will be addressed in future versions.

Feature Flags

• uuid - Includes implementations of Reconcile and Hydrate for the Uuid crate which will reconcile to a automerge::ScalarValue::Bytes

Example

Imagine we are writing a program to interact with a document containing some contact details. We start by writing some data types to represent the contact and deriving the Reconcile and Hydrate traits.

#[derive(Debug, Clone, Reconcile, Hydrate, PartialEq)]
struct Contact {
    name: String,
    address: Address,
}
#[derive(Debug, Clone, Reconcile, Hydrate, PartialEq)]
struct Address {
   line_one: String,
   line_two: Option<String>,
   city: String,
   postcode: String,
}

First we create a contact and put it into a document

let contact = Contact {
     name: "Sherlock Holmes".to_string(),
     address: Address{
         line_one: "221B Baker St".to_string(),
         line_two: None,
         city: "London".to_string(),
     },
};

let mut doc = automerge::AutoCommit::new();
reconcile(&mut doc, &contact).unwrap();

Now we can reconstruct the contact from the document

let contact2: Contact = hydrate(&doc).unwrap();
assert_eq!(contact, contact2);

reconcile is smart though, it doesn’t just update everything in the document, it figures out what’s changed, which means merging modified documents works as you would imagine. Let’s fork our document and make concurrent changes to it, then merge it and see how it looks.

// Fork and make changes
let mut doc2 = doc.fork().with_actor(automerge::ActorId::random());
let mut contact2: Contact = hydrate(&doc2).unwrap();
contact2.name = "Dangermouse".to_string();
reconcile(&mut doc2, &contact2).unwrap();

// Concurrently on doc1
contact.address.line_one = "221C Baker St".to_string();
reconcile(&mut doc, &contact).unwrap();

// Now merge the documents
doc.merge(&mut doc2).unwrap();

let merged: Contact = hydrate(&doc).unwrap();
assert_eq!(merged, Contact {
    name: "Dangermouse".to_string(), // This was updated in the first doc
    address: Address {
          line_one: "221C Baker St".to_string(), // This was concurrently updated in doc2
          line_two: None,
          city: "London".to_string(),
    }
})

Derive Macro

Automerge Representation

The derive macros map rust structs to the automerge structures in a similar manner to serde

struct W {
    a: i32,
    b: i32,
}
let w = W { a: 0, b: 0 }; // Represented as `{"a":0,"b":0}`

struct X(i32, i32);
let x = X(0, 0); // Represented as `[0,0]`

struct Y(i32);
let y = Y(0); // Represented as just the inner value `0`

enum E {
    W { a: i32, b: i32 },
    X(i32, i32),
    Y(i32),
    Z,
}
let w = E::W { a: 0, b: 0 }; // Represented as `{"W":{"a":0,"b":0}}`
let x = E::X(0, 0);          // Represented as `{"X":[0,0]}`
let y = E::Y(0);             // Represented as `{"Y":0}`
let z = E::Z;                // Represented as `"Z"`

The key attribute

autosurgeon will generally do its best to generate smart diffs. But sometimes you know additional information about your data which can make merges smarter. Consider the following scenario where we create a product catalog and then make concurrent changes to it.

#[derive(Reconcile, Hydrate, Clone, Debug, Eq, PartialEq)]
struct Product {
    id: u64,
    name: String,
}

#[derive(Reconcile, Hydrate, Clone, Debug, Eq, PartialEq)]
struct Catalog {
    products: Vec<Product>,
}

let mut catalog = Catalog {
    products: vec![
        Product {
            id: 1,
            name: "Lawnmower".to_string(),
        },
        Product {
            id: 2,
            name: "Strimmer".to_string(),
        }
    ]
};

// Put the catalog into the document
let mut doc = automerge::AutoCommit::new();
reconcile(&mut doc, &catalog).unwrap();

// Fork the document and insert a new product at the start of the catalog
let mut doc2 = doc.fork().with_actor(automerge::ActorId::random());
let mut catalog2 = catalog.clone();
catalog2.products.insert(0, Product {
    id: 3,
    name: "Leafblower".to_string(),
});
reconcile(&mut doc2, &catalog2).unwrap();

// Concurrenctly remove a product from the catalog in the original doc
catalog.products.remove(0);
reconcile(&mut doc, &catalog).unwrap();

// Merge the two changes
doc.merge(&mut doc2).unwrap();
assert_doc!(
    doc.document(),
    map! {
        "products" => { list! {
            // This first item is conflicted, we expected it to be the leafblower
            { map! {
                "id" => { 2_u64, 3_u64 }, // Conflict on the ID
                "name" => { "Strimmer", "Leafblower" }, // Conflict on the name
            }},
            { map! {
                "id" => { 2_u64 },
                "name" => { "Strimmer" },
            }}
        }}
    }
);

This is surprising, we have a bunch of merge conflicts on the fields of the first product in the list (as signified by the multiple values in the {..} on the inner values of the map!) and the second product in the list is also a strimmer. This is because autosurgeon has no way of knowing the difference between “I inserted an item at the front of the products list” and “I updated the first item in the products list”.

But we have an id field on the product, we can make autosurgeon aware of this.

#[derive(Reconcile, Hydrate, Clone, Debug, Eq, PartialEq)]
struct Product {
    #[key] // This is the important bit
    id: u64,
    name: String,
}

And with this our concurrent changes look like the following:

doc.merge(&mut doc2).unwrap();
assert_doc!(
    doc.document(),
    map! {
        "products" => { list! {
            { map! {
                "id" => { 3_u64 },
                "name" => { "Leafblower" },
            }},
            { map! {
                "id" => { 2_u64 },
                "name" => { "Strimmer" },
            }}
        }}
    }
);

Providing Implementations for foreign types

Deriving Hydrate and Reconcile is fine for your own types, but sometimes you are using a type which you did not write. For these situations there are a few attributes you can use.

reconcile=

The value of this attribute must be the name of a function with the same signature as Reconcile::reconcile

#[derive(Reconcile)]
struct File {
    #[autosurgeon(reconcile="reconcile_path")]
    path: std::path::PathBuf,
}

fn reconcile_path<R: Reconciler>(
        path: &std::path::PathBuf, mut reconciler: R
) -> Result<(), R::Error> {
    reconciler.str(path.display().to_string())
}

hydrate=

The value of this attribute must be the name of a function with the same signature as Hydrate::hydrate

#[derive(Hydrate)]
struct File {
    #[autosurgeon(hydrate="hydrate_path")]
    path: std::path::PathBuf,
}

fn hydrate_path<'a, D: ReadDoc>(
    doc: &D,
    obj: &automerge::ObjId,
    prop: Prop<'a>,
) -> Result<std::path::PathBuf, HydrateError> {
     let inner = String::hydrate(doc, obj, prop)?;
     inner.parse().map_err(|e| HydrateError::unexpected(
         "a valid path", format!("a path which failed to parse due to {}", e)
     ))
}

with=

The value of this attribute must be the name of a module wich has both a reconcile function and a hydrate function, with the same signatures as Reconcile::reconcile and Hydrate::hydrate respectively.

#[derive(Hydrate)]
struct File {
    #[autosurgeon(with="autosurgeon_path")]
    path: std::path::PathBuf,
}

mod autosurgeon_path {
    use autosurgeon::{Reconcile, Reconciler, Hydrate, ReadDoc, Prop, HydrateError};
    pub(super) fn hydrate<'a, D: ReadDoc>(
        doc: &D,
        obj: &automerge::ObjId,
        prop: Prop<'a>,
    ) -> Result<std::path::PathBuf, HydrateError> {
         let inner = String::hydrate(doc, obj, prop)?;
         inner.parse().map_err(|e| HydrateError::unexpected(
             "a valid path", format!("a path which failed to parse due to {}", e)
         ))
    }

    pub(super) fn reconcile<R: Reconciler>(
            path: &std::path::PathBuf, mut reconciler: R
    ) -> Result<(), R::Error> {
        reconciler.str(path.display().to_string())
    }
}

Providing default values with missing=

Occasionally you may want to provide a default value for a field which wasn’t found in the document. This can be done using the missing attribute. The value of the missing attribute should be the name of a function which returns a value of the annotated field.

#[derive(Hydrate)]
struct Contact {
    name: String,
    #[autosurgeon(missing="Visibility::default")]
    visibility: Visibility
}

#[derive(Hydrate, Default, Debug, PartialEq)]
enum Visibility {
    #[default]
    Public,
    Private,
}

let mut doc = automerge::AutoCommit::new();
doc.put(&automerge::ROOT, "name", "Sherlock Holmes".to_string());
let contact: Contact = hydrate(&doc).unwrap();
assert_eq!(contact.visibility, Visibility::Public);

Renaming fields and variants with rename=

By default, struct fields and enum variants are serialized using their Rust identifier names. The rename attribute allows you to specify a custom name for the serialized form. This is useful when:

• You need to use names that aren’t valid Rust identifiers (e.g., names with hyphens)
• You want to maintain compatibility with existing data that uses different naming conventions
• You’re interoperating with other systems that expect specific field names

Renaming struct fields

#[derive(Reconcile, Hydrate, Debug, PartialEq)]
struct Config {
    #[autosurgeon(rename = "api-key")]
    api_key: String,

    #[autosurgeon(rename = "max-retries")]
    max_retries: u64,
}

let config = Config {
    api_key: "secret".to_string(),
    max_retries: 3,
};

let mut doc = automerge::AutoCommit::new();
reconcile(&mut doc, &config).unwrap();

// The document now contains keys "api-key" and "max-retries"
// instead of "api_key" and "max_retries"

let hydrated: Config = hydrate(&doc).unwrap();
assert_eq!(config, hydrated);

Renaming enum variants

The rename attribute can also be applied to enum variants:

#[derive(Reconcile, Hydrate, Debug, PartialEq)]
enum Status {
    #[autosurgeon(rename = "in-progress")]
    InProgress,

    #[autosurgeon(rename = "done")]
    Completed,

    Active,  // Not renamed, uses "Active"
}

let mut doc = automerge::AutoCommit::new();
reconcile_prop(&mut doc, automerge::ROOT, "status", Status::InProgress).unwrap();

// The document contains "in-progress" as the status value

let status: Status = autosurgeon::hydrate_prop(&doc, automerge::ROOT, "status").unwrap();
assert_eq!(status, Status::InProgress);

Combining field and variant renames

You can combine field renames within enum variants:

#[derive(Reconcile, Hydrate, Debug, PartialEq)]
enum Event {
    #[autosurgeon(rename = "user-login")]
    UserLogin {
        #[autosurgeon(rename = "user-id")]
        user_id: String,
        timestamp: u64,
    },
}

let event = Event::UserLogin {
    user_id: "user123".to_string(),
    timestamp: 1234567890,
};

let mut doc = automerge::AutoCommit::new();
reconcile(&mut doc, &event).unwrap();

// The document contains {"user-login": {"user-id": "user123", "timestamp": 1234567890}}

let hydrated: Event = hydrate(&doc).unwrap();
assert_eq!(event, hydrated);

Modules

bytes

Newtypes for [u8;N] and Vec<u8> which encode to automerge::ScalarValue::Bytes

hydrate

map_with_parseable_keys

Derive macro adaptors for maps with parseable and printable keys (i.e. non string keyed maps).

reconcile

Structs

Counter

A type which reconciles to an automerge::ScalarValue::Counter

Text

A type which reconciles to an automerge::ObjType::Text

Enums

HydrateError

MaybeMissing

A convenience type to track whether a value was missing in the document

Prop

ReconcileError

Traits

Doc

An abstraction over the read + write operations we need from an automerge document

Hydrate

A type which can be hydrated from an automerge document

ReadDoc

An abstraction over the different ways of reading an automerge document

Reconcile

A data type which can be reconciled

Reconciler

A node in the document we are reconciling with.

Functions

hydrate

Hydrate an instance of H from doc

hydrate_key

Hydrate the key inner from inside the object outer

hydrate_path

Hydrate an instance of H located at a path in the document

hydrate_prop

Hydrate an instance of H located at property prop of object obj

reconcile

Reconcile value with doc

reconcile_insert

Reconcile into a new index in a sequence

reconcile_prop

Reconcile value with (obj, prop) in doc

Derive Macros

Hydrate

Reconcile