mechanomeld 0.1.0

data/README.md

@@ -0,0 +1,68 @@
+# Mechanomeld
+
+Read and write [Automerge](https://automerge.org) documents from Ruby. Mechanomeld is a native extension around the Rust `automerge` crate, so documents round-trip with JavaScript's `@automerge/automerge`.
+
+## Installation
+
+```bash
+bundle add mechanomeld
+```
+
+Precompiled gems are published for arm64/x86_64 macOS and Linux on Ruby 3.2–4.0. Other platforms build from source and need a Rust toolchain.
+
+## Usage
+
+```ruby
+require "mechanomeld"
+
+doc = Mechanomeld::Document.load(File.binread("todos.automerge"))
+doc.get(["todos", 0, "title"]) # => #<Mechanomeld::Text "Buy milk">
+doc.to_h                       # => {"todos" => [{"title" => #<Mechanomeld::Text "Buy milk">, ...}]}
+doc.keys                       # => ["todos"]
+doc.length("todos")            # => 1
+
+doc = Mechanomeld::Document.from({"title" => Mechanomeld::Text.new("Groceries"), "items" => []})
+doc.change(message: "Add milk") do |d|
+  d["count"] = Mechanomeld::Counter.new(1)
+end
+File.binwrite("groceries.automerge", doc.save)
+```
+
+### Values
+
+| Automerge | Ruby |
+|---|---|
+| map / list | `Hash` (String keys) / `Array` |
+| text object | `Mechanomeld::Text` |
+| string | `String` |
+| int / f64 / boolean / null | `Integer` / `Float` / `true`, `false` / `nil` |
+| counter / uint | `Mechanomeld::Counter` / `Mechanomeld::Uint` |
+| timestamp | `Mechanomeld::Timestamp` (milliseconds since the epoch) |
+| bytes | `Mechanomeld::Bytes` |
+
+JavaScript stores strings as text objects by default, so they read as `Mechanomeld::Text`. A Ruby `String` is written as an Automerge string, which JavaScript reads as an `ImmutableString`; write `Mechanomeld::Text.new("...")` to create text JavaScript reads as a plain string.
+
+Errors from Automerge raise `Mechanomeld::Error`.
+
+## Development
+
+Tools are pinned in `mise.toml`.
+
+```bash
+mise trust
+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
+```
+
+Check packaging with `gem build mechanomeld.gemspec`. Do not run `rake build` or `rake release` locally: reissue bumps the version and commits during `build`.
+
+## Releasing
+
+Releases run from the **Release gem to RubyGems.org** GitHub Actions workflow. Changelog entries and version bumps come from commit trailers (`Added:`, `Changed:`, `Fixed:`, `Version: minor`, ...). Run it with `dry_run` first.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/mechanomeld.

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "rb_sys/extensiontask"
+require "reissue/gem"
+
+GEMSPEC = Gem::Specification.load("mechanomeld.gemspec")
+
+# No platform list: cross-gem builds set RUBY_TARGET, which rb_sys reads.
+RbSys::ExtensionTask.new("mechanomeld", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/mechanomeld"
+end
+
+Minitest::TestTask.create
+task test: :compile
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/mechanomeld/version.rb"
+  task.fragment = :git
+  # The post-release bump goes on a pushed branch; the shared release workflow opens its PR.
+  # (0.5.1's default, stated explicitly: it is the "Option A" the shared workflow expects.)
+  task.push_reissue = :branch
+end
+
+task default: :test

data/checksums/mechanomeld-0.1.0.gem.sha512

@@ -0,0 +1 @@
+4a15ef106109b7d61c0c5f78cfc6f1599300b62a5410dbeb7e673cecd69731907125e006507dfc2b03eea8d6a738031569e5f430adcc0cb051fd36d7bdfcee4e

data/ext/mechanomeld/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "mechanomeld"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+automerge = "0.11"
+magnus = "0.8"
+rb-sys = "0.9.130"

data/ext/mechanomeld/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("mechanomeld/mechanomeld")

data/ext/mechanomeld/src/classes.rs

@@ -0,0 +1,24 @@
+//! Ruby classes defined in lib/, looked up once on first use.
+
+use magnus::{exception::ExceptionClass, prelude::*, value::Lazy, RClass, RModule};
+
+pub static MECHANOMELD: Lazy<RModule> =
+    Lazy::new(|ruby| ruby.define_module("Mechanomeld").unwrap());
+
+pub static ERROR: Lazy<ExceptionClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Error").unwrap());
+
+pub static TEXT: Lazy<RClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Text").unwrap());
+
+pub static COUNTER: Lazy<RClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Counter").unwrap());
+
+pub static TIMESTAMP: Lazy<RClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Timestamp").unwrap());
+
+pub static UINT: Lazy<RClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Uint").unwrap());
+
+pub static BYTES: Lazy<RClass> =
+    Lazy::new(|ruby| ruby.get_inner(&MECHANOMELD).const_get("Bytes").unwrap());

data/ext/mechanomeld/src/document.rs

@@ -0,0 +1,176 @@
+use std::cell::{Ref, RefCell, RefMut};
+use std::str::FromStr;
+
+use automerge::{
+    transaction::{CommitOptions, Transactable},
+    ActorId, AutoCommit, LoadOptions, ObjType, ReadDoc, TextEncoding, ROOT,
+};
+use magnus::{
+    prelude::*,
+    scan_args::{get_kwargs, scan_args},
+    typed_data::Obj,
+    Error, RArray, RHash, RString, Ruby, Value,
+};
+
+use crate::errors::{arg_error, automerge_error, error};
+use crate::{path, read, write};
+
+/// Text indexes count Unicode code points, matching Ruby's `String#length`.
+const ENCODING: TextEncoding = TextEncoding::UnicodeCodePoint;
+
+#[magnus::wrap(class = "Mechanomeld::Document", free_immediately, size)]
+pub struct Document {
+    inner: RefCell<AutoCommit>,
+}
+
+impl Document {
+    fn doc(&self, ruby: &Ruby) -> Result<Ref<'_, AutoCommit>, Error> {
+        self.inner
+            .try_borrow()
+            .map_err(|_| error(ruby, "document is being modified"))
+    }
+
+    fn doc_mut(&self, ruby: &Ruby) -> Result<RefMut<'_, AutoCommit>, Error> {
+        self.inner
+            .try_borrow_mut()
+            .map_err(|_| error(ruby, "document is already in use"))
+    }
+
+    /// `Document.new(actor_id: nil)`
+    pub fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let kwargs =
+            get_kwargs::<_, (), (Option<Option<String>>,), ()>(args.keywords, &[], &["actor_id"])?;
+        let mut doc = AutoCommit::new_with_encoding(ENCODING);
+        if let (Some(Some(actor_id)),) = kwargs.optional {
+            let actor = ActorId::from_str(&actor_id)
+                .map_err(|e| error(ruby, format!("invalid actor id: {e}")))?;
+            doc.set_actor(actor);
+        }
+        Ok(Self {
+            inner: RefCell::new(doc),
+        })
+    }
+
+    /// `Document.load(bytes)`
+    pub fn load(ruby: &Ruby, bytes: RString) -> Result<Self, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let doc = AutoCommit::load_with_options(&data, LoadOptions::new().text_encoding(ENCODING))
+            .map_err(|e| error(ruby, format!("could not load Automerge document: {e}")))?;
+        Ok(Self {
+            inner: RefCell::new(doc),
+        })
+    }
+
+    /// `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)?;
+        let doc = rb_self.doc(ruby)?;
+        let Some((last, parents)) = segments.split_last() else {
+            return read::object(ruby, &doc, &ROOT, ObjType::Map);
+        };
+        let Some((parent, parent_type)) = path::resolve(ruby, &doc, parents)? else {
+            return Ok(ruby.qnil().as_value());
+        };
+        let prop = path::prop(ruby, parent_type, *last)?;
+        match doc
+            .get(&parent, prop)
+            .map_err(|e| automerge_error(ruby, e))?
+        {
+            Some((value, id)) => read::value(ruby, &doc, value, id),
+            None => Ok(ruby.qnil().as_value()),
+        }
+    }
+
+    /// `doc.keys(path = [])`
+    pub fn keys(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<RArray, Error> {
+        let segments = optional_path(ruby, args)?;
+        let doc = rb_self.doc(ruby)?;
+        let (obj, obj_type) = path::resolve_existing(ruby, &doc, &segments)?;
+        if obj_type != ObjType::Map {
+            return Err(error(ruby, "keys target must be an Automerge map"));
+        }
+        Ok(ruby.ary_from_iter(doc.keys(&obj)))
+    }
+
+    /// `doc.length(path = [])`
+    pub fn length(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<usize, Error> {
+        let segments = optional_path(ruby, args)?;
+        let doc = rb_self.doc(ruby)?;
+        let (obj, _) = path::resolve_existing(ruby, &doc, &segments)?;
+        Ok(doc.length(&obj))
+    }
+
+    /// `doc.put(path, value)`
+    pub fn put(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        path: Value,
+        value: Value,
+    ) -> Result<Obj<Self>, Error> {
+        let segments = path::segments(path)?;
+        let Some((last, parents)) = segments.split_last() else {
+            return Err(arg_error(ruby, "path must not be empty"));
+        };
+        {
+            let mut doc = rb_self.doc_mut(ruby)?;
+            let (parent, parent_type) = path::resolve_existing(ruby, &doc, parents)?;
+            let prop = path::write_prop(ruby, &doc, &parent, parent_type, *last)?;
+            write::write(ruby, &mut doc, &parent, write::Slot::Put(prop), value)?;
+        }
+        Ok(rb_self)
+    }
+
+    /// `doc.delete(path)`
+    pub fn delete(ruby: &Ruby, rb_self: Obj<Self>, path: Value) -> Result<Obj<Self>, Error> {
+        let segments = path::segments(path)?;
+        let Some((last, parents)) = segments.split_last() else {
+            return Err(arg_error(ruby, "path must not be empty"));
+        };
+        {
+            let mut doc = rb_self.doc_mut(ruby)?;
+            let (parent, parent_type) = path::resolve_existing(ruby, &doc, parents)?;
+            let prop = path::write_prop(ruby, &doc, &parent, parent_type, *last)?;
+            doc.delete(&parent, prop)
+                .map_err(|e| automerge_error(ruby, e))?;
+        }
+        Ok(rb_self)
+    }
+
+    /// `doc.commit(message: nil, timestamp: nil)`: the binary change hash, or nil.
+    /// `timestamp` is Unix seconds (automerge's commit time), unlike Timestamp values.
+    pub fn commit(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Option<RString>, Error> {
+        let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+        let kwargs = get_kwargs::<_, (), (Option<Option<String>>, Option<Option<i64>>), ()>(
+            args.keywords,
+            &[],
+            &["message", "timestamp"],
+        )?;
+        let (message, timestamp) = kwargs.optional;
+        let mut options = CommitOptions::default();
+        if let Some(Some(message)) = message {
+            options = options.with_message(message);
+        }
+        if let Some(Some(seconds)) = timestamp {
+            options = options.with_time(seconds);
+        }
+        let hash = rb_self.doc_mut(ruby)?.commit_with(options);
+        Ok(hash.map(|hash| ruby.str_from_slice(&hash.0)))
+    }
+
+    /// `doc.rollback`: the number of pending operations discarded.
+    pub fn rollback(ruby: &Ruby, rb_self: &Self) -> Result<usize, Error> {
+        Ok(rb_self.doc_mut(ruby)?.rollback())
+    }
+
+    /// `doc.save`: the document as a binary String.
+    pub fn save(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        let bytes = rb_self.doc_mut(ruby)?.save();
+        Ok(ruby.str_from_slice(&bytes))
+    }
+}
+
+fn optional_path(ruby: &Ruby, args: &[Value]) -> Result<Vec<Value>, Error> {
+    let args = scan_args::<(), (Option<Value>,), (), (), (), ()>(args)?;
+    path::segments(args.optional.0.unwrap_or_else(|| ruby.qnil().as_value()))
+}

data/ext/mechanomeld/src/errors.rs

@@ -0,0 +1,24 @@
+use std::borrow::Cow;
+use std::fmt::Display;
+
+use magnus::{Error, Ruby};
+
+use crate::classes::ERROR;
+
+/// A `Mechanomeld::Error`.
+pub fn error<T: Into<Cow<'static, str>>>(ruby: &Ruby, message: T) -> Error {
+    Error::new(ruby.get_inner(&ERROR), message)
+}
+
+/// A `Mechanomeld::Error` carrying an automerge error's message.
+pub fn automerge_error(ruby: &Ruby, err: impl Display) -> Error {
+    error(ruby, err.to_string())
+}
+
+pub fn type_error<T: Into<Cow<'static, str>>>(ruby: &Ruby, message: T) -> Error {
+    Error::new(ruby.exception_type_error(), message)
+}
+
+pub fn arg_error<T: Into<Cow<'static, str>>>(ruby: &Ruby, message: T) -> Error {
+    Error::new(ruby.exception_arg_error(), message)
+}

data/ext/mechanomeld/src/lib.rs

@@ -0,0 +1,27 @@
+mod classes;
+mod document;
+mod errors;
+mod path;
+mod read;
+mod write;
+
+use magnus::{function, method, prelude::*, Error, Ruby};
+
+use crate::document::Document;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Mechanomeld")?;
+    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("get", method!(Document::get, 1))?;
+    class.define_method("keys", method!(Document::keys, -1))?;
+    class.define_method("length", method!(Document::length, -1))?;
+    class.define_method("put", method!(Document::put, 2))?;
+    class.define_method("delete", method!(Document::delete, 1))?;
+    class.define_method("commit", method!(Document::commit, -1))?;
+    class.define_method("rollback", method!(Document::rollback, 0))?;
+    class.define_method("save", method!(Document::save, 0))?;
+    Ok(())
+}

data/ext/mechanomeld/src/path.rs

@@ -0,0 +1,117 @@
+//! Turning Ruby paths like `["todos", 0, "title"]` into automerge objects and props.
+
+use automerge::{AutoCommit, ObjId, ObjType, Prop, ReadDoc, Value as AmValue, ROOT};
+use magnus::{prelude::*, Error, Integer, RArray, RString, Ruby, Symbol, Value};
+
+use crate::errors::{arg_error, automerge_error, error, type_error};
+
+/// `nil` is the root, an Array is a list of segments, anything else is a single segment.
+///
+/// The returned Values stay alive for the method call because the caller's `path`
+/// argument still references them.
+pub fn segments(path: Value) -> Result<Vec<Value>, Error> {
+    if path.is_nil() {
+        return Ok(Vec::new());
+    }
+    let Some(array) = RArray::from_value(path) else {
+        return Ok(vec![path]);
+    };
+    (0..array.len())
+        .map(|index| array.entry::<Value>(index as isize))
+        .collect()
+}
+
+pub fn key(ruby: &Ruby, segment: Value) -> Result<String, Error> {
+    if let Some(symbol) = Symbol::from_value(segment) {
+        return Ok(symbol.name()?.into_owned());
+    }
+    if let Some(string) = RString::from_value(segment) {
+        return string.to_string();
+    }
+    Err(type_error(
+        ruby,
+        format!(
+            "map key must be a String or Symbol, got {}",
+            class_name(segment)
+        ),
+    ))
+}
+
+pub fn index(ruby: &Ruby, segment: Value) -> Result<usize, Error> {
+    let Some(integer) = Integer::from_value(segment) else {
+        return Err(type_error(
+            ruby,
+            format!("list index must be an Integer, got {}", class_name(segment)),
+        ));
+    };
+    usize::try_from(integer.to_i64()?)
+        .map_err(|_| arg_error(ruby, "list index must be non-negative"))
+}
+
+pub fn class_name(value: Value) -> String {
+    unsafe { value.classname() }.into_owned()
+}
+
+/// The prop addressing `segment` inside an object of `obj_type`.
+pub fn prop(ruby: &Ruby, obj_type: ObjType, segment: Value) -> Result<Prop, Error> {
+    match obj_type {
+        ObjType::Map | ObjType::Table => Ok(Prop::Map(key(ruby, segment)?)),
+        ObjType::List => Ok(Prop::Seq(index(ruby, segment)?)),
+        ObjType::Text => Err(error(ruby, "cannot descend into Automerge text")),
+    }
+}
+
+/// Follows `segments` from the root. `None` when a key or index along the way is missing.
+pub fn resolve(
+    ruby: &Ruby,
+    doc: &AutoCommit,
+    segments: &[Value],
+) -> Result<Option<(ObjId, ObjType)>, Error> {
+    let mut obj = ROOT;
+    let mut obj_type = ObjType::Map;
+    for segment in segments {
+        let prop = prop(ruby, obj_type, *segment)?;
+        match doc.get(&obj, prop).map_err(|e| automerge_error(ruby, e))? {
+            None => return Ok(None),
+            Some((AmValue::Object(child_type), child)) => {
+                obj = child;
+                obj_type = child_type;
+            }
+            Some((AmValue::Scalar(_), _)) => {
+                return Err(error(ruby, "path does not resolve to an Automerge object"))
+            }
+        }
+    }
+    Ok(Some((obj, obj_type)))
+}
+
+/// Like [`resolve`], but a missing key or index is an error.
+pub fn resolve_existing(
+    ruby: &Ruby,
+    doc: &AutoCommit,
+    segments: &[Value],
+) -> Result<(ObjId, ObjType), Error> {
+    resolve(ruby, doc, segments)?.ok_or_else(|| error(ruby, "path does not exist"))
+}
+
+/// The prop for writing `segment` into `obj`. List indexes must already exist.
+pub fn write_prop(
+    ruby: &Ruby,
+    doc: &AutoCommit,
+    obj: &ObjId,
+    obj_type: ObjType,
+    segment: Value,
+) -> Result<Prop, Error> {
+    if obj_type != ObjType::List {
+        return prop(ruby, obj_type, segment);
+    }
+    let index = index(ruby, segment)?;
+    let length = doc.length(obj);
+    if index >= length {
+        return Err(error(
+            ruby,
+            format!("list index {index} is out of bounds (length {length})"),
+        ));
+    }
+    Ok(Prop::Seq(index))
+}

data/ext/mechanomeld/src/read.rs

@@ -0,0 +1,80 @@
+//! Converting automerge values into Ruby values.
+
+use automerge::{AutoCommit, ObjId, ObjType, ReadDoc, ScalarValue, Value as AmValue};
+use magnus::{prelude::*, value::Lazy, Error, IntoValue, RClass, RObject, Ruby, Value};
+
+use crate::classes::{BYTES, COUNTER, TEXT, TIMESTAMP, UINT};
+use crate::errors::{automerge_error, error};
+
+pub fn value(ruby: &Ruby, doc: &AutoCommit, value: AmValue<'_>, id: ObjId) -> Result<Value, Error> {
+    match value {
+        AmValue::Object(obj_type) => object(ruby, doc, &id, obj_type),
+        AmValue::Scalar(scalar_value) => scalar(ruby, &scalar_value),
+    }
+}
+
+pub fn object(
+    ruby: &Ruby,
+    doc: &AutoCommit,
+    obj: &ObjId,
+    obj_type: ObjType,
+) -> Result<Value, Error> {
+    match obj_type {
+        ObjType::Map => {
+            let hash = ruby.hash_new();
+            for key in doc.keys(obj) {
+                if let Some((child, id)) = doc
+                    .get(obj, key.as_str())
+                    .map_err(|e| automerge_error(ruby, e))?
+                {
+                    hash.aset(key, value(ruby, doc, child, id)?)?;
+                }
+            }
+            Ok(hash.as_value())
+        }
+        ObjType::List => {
+            let length = doc.length(obj);
+            let array = ruby.ary_new_capa(length);
+            for index in 0..length {
+                match doc.get(obj, index).map_err(|e| automerge_error(ruby, e))? {
+                    Some((child, id)) => array.push(value(ruby, doc, child, id)?)?,
+                    None => array.push(ruby.qnil())?,
+                }
+            }
+            Ok(array.as_value())
+        }
+        ObjType::Text => {
+            let text = doc.text(obj).map_err(|e| automerge_error(ruby, e))?;
+            wrap(ruby, &TEXT, ruby.str_new(&text))
+        }
+        ObjType::Table => Err(error(ruby, "Automerge tables are not supported")),
+    }
+}
+
+pub fn scalar(ruby: &Ruby, scalar: &ScalarValue) -> Result<Value, Error> {
+    match scalar {
+        ScalarValue::Str(string) => Ok(ruby.str_new(string.as_str()).as_value()),
+        ScalarValue::Int(int) => Ok(ruby.integer_from_i64(*int).as_value()),
+        ScalarValue::F64(float) => Ok(ruby.float_from_f64(*float).as_value()),
+        ScalarValue::Boolean(boolean) => Ok(boolean.into_value_with(ruby)),
+        ScalarValue::Null => Ok(ruby.qnil().as_value()),
+        ScalarValue::Counter(counter) => {
+            wrap(ruby, &COUNTER, ruby.integer_from_i64(i64::from(counter)))
+        }
+        ScalarValue::Timestamp(millis) => wrap(ruby, &TIMESTAMP, ruby.integer_from_i64(*millis)),
+        ScalarValue::Uint(uint) => wrap(ruby, &UINT, ruby.integer_from_u64(*uint)),
+        ScalarValue::Bytes(bytes) => wrap(ruby, &BYTES, ruby.str_from_slice(bytes)),
+        ScalarValue::Unknown { type_code, .. } => Err(error(
+            ruby,
+            format!("unsupported Automerge value type code {type_code}"),
+        )),
+    }
+}
+
+/// Builds a scalar wrapper by allocating it and setting `@value`, without running Ruby code.
+fn wrap(ruby: &Ruby, class: &'static Lazy<RClass>, value: impl IntoValue) -> Result<Value, Error> {
+    let instance = ruby.get_inner(class).obj_alloc()?;
+    let object = RObject::try_convert(instance.as_value())?;
+    object.ivar_set("@value", value)?;
+    Ok(object.as_value())
+}