mechanomeld 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc3b7a58de04a5445e59c398a68556fddb11bd3ec013451733e9a962e6121608
-  data.tar.gz: 29c2f1e1c0eb082b0416994131c78073e3a93c8ffdbe122e3af96887e3712bb2
+  metadata.gz: 8e71318030a041eeb04f082e8ce7d096c015e7462e4273d244026331d79e1c2d
+  data.tar.gz: f66fecdc446f07fdea887099626204f446314353ad77b61602902e491cbf9d9d
 SHA512:
-  metadata.gz: 16f9c6cd1505ce2931ac90f75ac9eb391eea8a2c7be2d7e6e6fcb513819e4c2eebfa849ce02cbcd96c8b833caab3d73d5eeb151e6087739d47aee5ab9e14c6aa
-  data.tar.gz: 3d0c3dbbbd11ae5733fcb260548c2aa2eb03ce399970eacffc8571fa111e014e6471618737704914c2162def47ec4c204b3ec4f62158ad1581751e86ad525f07
+  metadata.gz: 909d370afa1a826a03f1d7afe2b1fcdc1f639f29d50cb6f50cb532822ae47df2b18d59c7849fb960b5ce05532312ac3a20c809ca3cf0738ab0ff067a4a5571df
+  data.tar.gz: 41686d01f296e39ffb334f94b33a08cd887f201439fd6ce5e907e1f3eb666ec5d14b0576807030e364db49be2bc283d3bd2c36a364709326c9f77d40f2e243ee

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.1.1] - 2026-09-25
+
+### Added
+
+- Document#load_incremental applies saved Automerge bytes into an existing document (d60a3eb)
+- Document.load_repo reads a document from automerge-repo's NodeFSStorageAdapter directory (d60a3eb)
+- Document#heads returns the document's change hashes as hex, matching JavaScript's Automerge.getHeads (d60a3eb)
+- Document#includes_heads?(heads) reports whether a document is at or past a set of heads (d60a3eb)
+- Mechanomeld::SyncState, the per-peer sync state, with encode and decode for persistence (eea3a51)
+- Document#generate_sync_message and #receive_sync_message, Automerge's per-document sync protocol (eea3a51)
+
+### Changed
+
+- releases also publish an x86_64-linux-musl platform gem (159dd59)
+
 ## [0.1.0] - 2026-09-17
 
 ### Added

data/README.md

@@ -28,6 +28,53 @@ end
 File.binwrite("groceries.automerge", doc.save)
 ```
 
+### Documents stored by automerge-repo
+
+`Document.load_repo` reads a document straight out of the directory written by `@automerge/automerge-repo`'s `NodeFSStorageAdapter`, applying its snapshot and incremental chunks and skipping its sync-state files.
+
+```ruby
+doc = Mechanomeld::Document.load_repo("automerge-repo-data", "4NtRZtd6yUtzf8qmEpKitAaW4JRp")
+```
+
+`Document#load_incremental(bytes)` is the piece underneath: it applies any saved Automerge bytes (a full save, a snapshot chunk, or an incremental change chunk) into an existing document and returns the document.
+
+### Heads
+
+`Document#heads` is the document's version: the change hashes JavaScript's `Automerge.getHeads(doc)` returns, as lowercase hex, so the two sides compare with `==`. `Document#includes_heads?(heads)` is true when every hash in `heads` is a change the document already contains, so `heads` is the same version or an older one.
+
+```ruby
+doc.heads                  # => ["9d434616e7af865757bad75cdebe4151bccf7e29214a71f2a65150846c2a4275"]
+doc.includes_heads?(heads) # => true when the document is at or past `heads`
+```
+
+Both take hex. automerge-repo's `handle.heads()` returns base58 URL heads, which are not accepted; send `Automerge.getHeads(handle.doc())` from JavaScript instead. A hash that is not 32 bytes of hex raises `Mechanomeld::Error`; a well-formed hash the document does not have is simply not included. Like `save`, both commit any pending change first.
+
+### Syncing with a peer
+
+`Document#generate_sync_message` and `Document#receive_sync_message` run Automerge's per-document sync protocol, so a Ruby document can exchange just the changes each side lacks with another Automerge peer: JavaScript's `Automerge.generateSyncMessage` / `receiveSyncMessage`, or another Ruby document. A `Mechanomeld::SyncState` tracks what one peer is known to have; keep one per peer for each document.
+
+```ruby
+left = Mechanomeld::Document.load(bytes)
+right = Mechanomeld::Document.load(bytes)
+left.change { |d| d["left"] = 1 }
+right.change { |d| d["right"] = 2 }
+
+left_state = Mechanomeld::SyncState.new  # left's view of right
+right_state = Mechanomeld::SyncState.new # right's view of left
+loop do
+  to_right = left.generate_sync_message(left_state)
+  right.receive_sync_message(right_state, to_right) if to_right
+  to_left = right.generate_sync_message(right_state)
+  left.receive_sync_message(left_state, to_left) if to_left
+  break if to_right.nil? && to_left.nil?
+end
+left.heads == right.heads # => true
+```
+
+Messages are binary Strings. `generate_sync_message` returns nil when the peer is up to date or the last message is still unanswered. `SyncState#encode` and `SyncState.decode(bytes)` carry a state across connections, keeping only the heads both sides are known to share (as JavaScript's `encodeSyncState` does), so a process that handles one message per request can decode, receive, generate, and encode again. Like `save`, both sync methods commit any pending change first. Bytes that are not a sync message or a sync state raise `Mechanomeld::Error`. The protocol carries no document identity: a message from a peer holding a different document merges that document in.
+
+This is the per-document protocol only. An automerge-repo sync server wraps these messages in its own envelope (peer and document ids, join and leave messages, CBOR encoding), which this gem does not provide.
+
 ### Values
 
 | Automerge | Ruby |
@@ -54,7 +101,7 @@ mise install
 mise run setup         # bundle install, npm ci for fixtures
 mise run test          # compile the extension and run the tests
 mise run test:interop  # check JavaScript reads Ruby-written documents
-mise run fixtures      # regenerate test/fixtures/*.automerge
+mise run fixtures      # regenerate test/fixtures/*.automerge, heads.json, and repo/
 ```
 
 Check packaging with `gem build mechanomeld.gemspec`. Do not run `rake build` or `rake release` locally: reissue bumps the version and commits during `build`.

data/ext/mechanomeld/src/document.rs

@@ -2,8 +2,9 @@ use std::cell::{Ref, RefCell, RefMut};
 use std::str::FromStr;
 
 use automerge::{
+    sync::{Message, SyncDoc},
     transaction::{CommitOptions, Transactable},
-    ActorId, AutoCommit, LoadOptions, ObjType, ReadDoc, TextEncoding, ROOT,
+    ActorId, AutoCommit, ChangeHash, LoadOptions, ObjType, ReadDoc, TextEncoding, ROOT,
 };
 use magnus::{
     prelude::*,
@@ -13,6 +14,7 @@ use magnus::{
 };
 
 use crate::errors::{arg_error, automerge_error, error};
+use crate::sync_state::SyncState;
 use crate::{path, read, write};
 
 /// Text indexes count Unicode code points, matching Ruby's `String#length`.
@@ -62,6 +64,21 @@ impl Document {
         })
     }
 
+    /// `doc.load_incremental(bytes)`: applies a full save, snapshot, or incremental
+    /// change chunk into this document.
+    pub fn load_incremental(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        bytes: RString,
+    ) -> Result<Obj<Self>, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        rb_self
+            .doc_mut(ruby)?
+            .load_incremental(&data)
+            .map_err(|e| error(ruby, format!("could not load Automerge document: {e}")))?;
+        Ok(rb_self)
+    }
+
     /// `doc.get(path)`: the value at `path`, or nil when anything along it is missing.
     pub fn get(ruby: &Ruby, rb_self: &Self, path: Value) -> Result<Value, Error> {
         let segments = path::segments(path)?;
@@ -168,6 +185,64 @@ impl Document {
         let bytes = rb_self.doc_mut(ruby)?.save();
         Ok(ruby.str_from_slice(&bytes))
     }
+
+    /// `doc.heads`: the current heads as lowercase hex change hashes, the format
+    /// JavaScript's `Automerge.getHeads` returns.
+    pub fn heads(ruby: &Ruby, rb_self: &Self) -> Result<RArray, Error> {
+        let heads = rb_self.doc_mut(ruby)?.get_heads();
+        Ok(ruby.ary_from_iter(heads.iter().map(ChangeHash::to_string)))
+    }
+
+    /// `doc.includes_heads?(heads)`: whether every hex change hash in `heads` is a
+    /// change this document already contains.
+    pub fn includes_heads(ruby: &Ruby, rb_self: &Self, heads: Vec<String>) -> Result<bool, Error> {
+        let hashes = heads
+            .iter()
+            .map(|hex| change_hash(ruby, hex))
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut doc = rb_self.doc_mut(ruby)?;
+        Ok(hashes
+            .iter()
+            .all(|hash| doc.get_change_meta_by_hash(hash).is_some()))
+    }
+
+    /// `doc.generate_sync_message(sync_state)`: the next binary message for the peer
+    /// `sync_state` tracks, or nil when there is nothing to send.
+    pub fn generate_sync_message(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sync_state: &SyncState,
+    ) -> Result<Option<RString>, Error> {
+        let mut doc = rb_self.doc_mut(ruby)?;
+        let mut state = sync_state.state_mut(ruby)?;
+        let message = doc.sync().generate_sync_message(&mut state);
+        Ok(message.map(|message| ruby.str_from_slice(&message.encode())))
+    }
+
+    /// `doc.receive_sync_message(sync_state, bytes)`: applies a peer's message to this
+    /// document and to `sync_state`.
+    pub fn receive_sync_message(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        sync_state: &SyncState,
+        bytes: RString,
+    ) -> Result<Obj<Self>, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let message = Message::decode(&data)
+            .map_err(|e| error(ruby, format!("could not decode sync message: {e}")))?;
+        {
+            let mut doc = rb_self.doc_mut(ruby)?;
+            let mut state = sync_state.state_mut(ruby)?;
+            doc.sync()
+                .receive_sync_message(&mut state, message)
+                .map_err(|e| automerge_error(ruby, e))?;
+        }
+        Ok(rb_self)
+    }
+}
+
+fn change_hash(ruby: &Ruby, hex: &str) -> Result<ChangeHash, Error> {
+    ChangeHash::from_str(hex).map_err(|e| error(ruby, format!("invalid change hash {hex:?}: {e}")))
 }
 
 fn optional_path(ruby: &Ruby, args: &[Value]) -> Result<Vec<Value>, Error> {

data/ext/mechanomeld/src/lib.rs

@@ -3,11 +3,13 @@ mod document;
 mod errors;
 mod path;
 mod read;
+mod sync_state;
 mod write;
 
 use magnus::{function, method, prelude::*, Error, Ruby};
 
 use crate::document::Document;
+use crate::sync_state::SyncState;
 
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
@@ -15,6 +17,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let class = module.define_class("Document", ruby.class_object())?;
     class.define_singleton_method("new", function!(Document::new, -1))?;
     class.define_singleton_method("load", function!(Document::load, 1))?;
+    class.define_method("load_incremental", method!(Document::load_incremental, 1))?;
     class.define_method("get", method!(Document::get, 1))?;
     class.define_method("keys", method!(Document::keys, -1))?;
     class.define_method("length", method!(Document::length, -1))?;
@@ -23,5 +26,19 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     class.define_method("commit", method!(Document::commit, -1))?;
     class.define_method("rollback", method!(Document::rollback, 0))?;
     class.define_method("save", method!(Document::save, 0))?;
+    class.define_method("heads", method!(Document::heads, 0))?;
+    class.define_method("includes_heads?", method!(Document::includes_heads, 1))?;
+    class.define_method(
+        "generate_sync_message",
+        method!(Document::generate_sync_message, 1),
+    )?;
+    class.define_method(
+        "receive_sync_message",
+        method!(Document::receive_sync_message, 2),
+    )?;
+    let sync_state = module.define_class("SyncState", ruby.class_object())?;
+    sync_state.define_singleton_method("new", function!(SyncState::new, 0))?;
+    sync_state.define_singleton_method("decode", function!(SyncState::decode, 1))?;
+    sync_state.define_method("encode", method!(SyncState::encode, 0))?;
     Ok(())
 }

data/ext/mechanomeld/src/sync_state.rs

@@ -0,0 +1,49 @@
+use std::cell::{Ref, RefCell, RefMut};
+
+use automerge::sync::State;
+use magnus::{Error, RString, Ruby};
+
+use crate::errors::error;
+
+/// What a document knows about one peer while syncing with it.
+#[magnus::wrap(class = "Mechanomeld::SyncState", free_immediately, size)]
+pub struct SyncState {
+    inner: RefCell<State>,
+}
+
+impl SyncState {
+    fn state(&self, ruby: &Ruby) -> Result<Ref<'_, State>, Error> {
+        self.inner
+            .try_borrow()
+            .map_err(|_| error(ruby, "sync state is being modified"))
+    }
+
+    pub fn state_mut(&self, ruby: &Ruby) -> Result<RefMut<'_, State>, Error> {
+        self.inner
+            .try_borrow_mut()
+            .map_err(|_| error(ruby, "sync state is already in use"))
+    }
+
+    /// `SyncState.new`: a fresh state for a peer this document has not synced with.
+    pub fn new() -> Self {
+        Self {
+            inner: RefCell::new(State::new()),
+        }
+    }
+
+    /// `SyncState.decode(bytes)`
+    pub fn decode(ruby: &Ruby, bytes: RString) -> Result<Self, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let state = State::decode(&data)
+            .map_err(|e| error(ruby, format!("could not decode sync state: {e}")))?;
+        Ok(Self {
+            inner: RefCell::new(state),
+        })
+    }
+
+    /// `sync_state.encode`: the state as a binary String, keeping only what is worth
+    /// reusing on a later connection with the same peer.
+    pub fn encode(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        Ok(ruby.str_from_slice(&rb_self.state(ruby)?.encode()))
+    }
+}

data/lib/mechanomeld/document.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Mechanomeld
-  # Native methods (new, load, get, keys, length, put, delete, commit, rollback, save)
+  # Native methods (new, load, load_incremental, get, keys, length, put, delete, commit,
+  # rollback, save, heads, includes_heads?, generate_sync_message, receive_sync_message)
   # are defined in ext/mechanomeld/src/document.rs.
   class Document
     def self.from(hash, actor_id: nil)
@@ -13,6 +14,19 @@ module Mechanomeld
       doc
     end
 
+    # Loads a document from the directory written by @automerge/automerge-repo's
+    # NodeFSStorageAdapter. Snapshot chunks are applied before incremental ones, as
+    # automerge-repo does; its sync-state files are not document data and are skipped.
+    def self.load_repo(base_dir, document_id)
+      document_dir = File.join(base_dir, document_id[0, 2], document_id[2..])
+      chunks = %w[snapshot incremental].flat_map do |kind|
+        Dir.glob(File.join(document_dir, kind, "*")).sort.select { |path| File.file?(path) }
+      end
+      raise Error, "no chunks for document #{document_id} in #{base_dir}" if chunks.empty?
+
+      chunks.each_with_object(new) { |path, doc| doc.load_incremental(File.binread(path)) }
+    end
+
     def [](path)
       get(path)
     end

data/lib/mechanomeld/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mechanomeld
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mechanomeld
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jim Gay
@@ -46,6 +46,7 @@ files:
 - ext/mechanomeld/src/lib.rs
 - ext/mechanomeld/src/path.rs
 - ext/mechanomeld/src/read.rs
+- ext/mechanomeld/src/sync_state.rs
 - ext/mechanomeld/src/write.rs
 - lib/mechanomeld.rb
 - lib/mechanomeld/document.rb
@@ -74,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Read and write Automerge documents from Ruby
 test_files: []