y-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10cd525c4f285fedd7ea5460790a0515bd15227d49606a8c283b313b9fdd233c
+  data.tar.gz: 8645608ebd5f936cb3eb11e16a1e8b6fde1874881990b7cd18eb1f1624d5f2af
+SHA512:
+  metadata.gz: 7b36dda334a509d2123430871c47f713852eea552f804db174c2ca2089b6184dacfe6c30641d0693bb4e58897c9659fc99279607498ffe3be44863b369d7080b
+  data.tar.gz: 3fe5990b463b06da580ada4705e011c84579e5b07eb5565bd15ca80b25a184ef6fac78db423a240521aa9c60313c08ef59e927ef3705897b84b4eacbce97b772

data/.cargo/config.toml

@@ -0,0 +1,5 @@
+[target.x86_64-apple-darwin]
+linker = "x86_64-apple-darwin14-clang"
+ar = "x86_64-apple-darwin14-ar"
+
+[target.aarch64-apple-darwin]

data/.dockerignore

@@ -0,0 +1,5 @@
+.idea/
+.yardoc/
+doc/
+docs/
+target/

data/.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.{rb,yml}]
+indent_style = space
+indent_size = 2
+
+[*.rs]
+indent_style = space
+indent_size = 4

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,23 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.6
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/y/*_spec.rb
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 80
+  Exclude:
+    - y-rb.gemspec

data/.rustfmt.toml

@@ -0,0 +1,75 @@
+max_width = 80
+hard_tabs = false
+tab_spaces = 4
+newline_style = "Auto"
+indent_style = "Block"
+use_small_heuristics = "Default"
+fn_call_width = 60
+attr_fn_like_width = 70
+struct_lit_width = 18
+struct_variant_width = 35
+array_width = 60
+chain_width = 60
+single_line_if_else_max_width = 50
+wrap_comments = false
+format_code_in_doc_comments = false
+comment_width = 80
+normalize_comments = false
+normalize_doc_attributes = false
+license_template_path = ""
+format_strings = false
+format_macro_matchers = false
+format_macro_bodies = true
+empty_item_single_line = true
+struct_lit_single_line = true
+fn_single_line = false
+where_single_line = false
+imports_indent = "Block"
+imports_layout = "Mixed"
+imports_granularity = "Preserve"
+group_imports = "Preserve"
+reorder_imports = true
+reorder_modules = true
+reorder_impl_items = false
+type_punctuation_density = "Wide"
+space_before_colon = false
+space_after_colon = true
+spaces_around_ranges = false
+binop_separator = "Front"
+remove_nested_parens = true
+combine_control_expr = true
+overflow_delimited_expr = false
+struct_field_align_threshold = 0
+enum_discrim_align_threshold = 0
+match_arm_blocks = true
+match_arm_leading_pipes = "Never"
+force_multiline_blocks = false
+fn_args_layout = "Tall"
+brace_style = "SameLineWhere"
+control_brace_style = "AlwaysSameLine"
+trailing_semicolon = true
+trailing_comma = "Never"
+match_block_trailing_comma = false
+blank_lines_upper_bound = 1
+blank_lines_lower_bound = 0
+edition = "2015"
+version = "One"
+inline_attribute_width = 0
+merge_derives = true
+use_try_shorthand = false
+use_field_init_shorthand = false
+force_explicit_abi = true
+condense_wildcard_suffixes = false
+color = "Auto"
+required_version = "1.4.37"
+unstable_features = false
+disable_all_formatting = false
+skip_children = false
+hide_parse_errors = false
+error_on_line_overflow = false
+error_on_unformatted = false
+report_todo = "Never"
+report_fixme = "Never"
+ignore = []
+emit_mode = "Files"
+make_backup = false

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "y-rb"
+version = "0.1.0"
+authors = ["Hannes Moser <box@hannesmoser.at>"]
+edition = "2021"
+homepage = "https://github.com/y-crdt/yrb"
+repository = "https://github.com/y-crdt/yrb"
+
+[dependencies]
+lazy_static = "1.4.0"
+rutie = "0.8.4"
+yrs = "0.7.1"
+lib0 = "0.7.1"
+cross = "0.2.1"
+
+[lib]
+name = "y_rb"
+crate-type = ["cdylib"]
+
+[package.metadata.thermite]
+github_releases = true

data/Cross.toml

@@ -0,0 +1,2 @@
+[build]
+xargo = true

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in y-rb.gemspec
+gemspec
+
+gem "github-markup"
+gem "redcarpet"
+gem "rspec", "~> 3.11.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-rspec", "~> 2.10.0"
+gem "yard"

data/Gemfile.lock

@@ -0,0 +1,75 @@
+PATH
+  remote: .
+  specs:
+    y-rb (0.1.0)
+      rake (~> 13.0)
+      rutie (~> 0.0.4)
+      thermite (~> 0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    github-markup (4.0.0)
+    minitar (0.9)
+    parallel (1.22.1)
+    parser (3.1.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    redcarpet (3.5.1)
+    regexp_parser (2.3.1)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rubocop (1.28.2)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.17.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.17.0)
+      parser (>= 3.1.1.0)
+    rubocop-rspec (2.10.0)
+      rubocop (~> 1.19)
+    ruby-progressbar (1.11.0)
+    rutie (0.0.4)
+    thermite (0.13.0)
+      minitar (~> 0.5)
+      rake (>= 10)
+      tomlrb (~> 1.2)
+    tomlrb (1.3.0)
+    unicode-display_width (2.1.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  github-markup
+  redcarpet
+  rspec (~> 3.11.0)
+  rubocop (~> 1.21)
+  rubocop-rspec (~> 2.10.0)
+  y-rb!
+  yard
+
+BUNDLED WITH
+   2.2.32

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Hannes Moser <hmoser@gitlab.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Yrb
+
+> Attention: This gem isn't published yet, but you can play around with it.
+> Feedback on the Ruby API is welcome 🙌.
+
+Yrb is a Ruby binding for Y-CRDT. It provides distributed data types that enable
+real-time collaboration between devices. Yrb can sync data with any other
+platform that has a Y-CRDT binding, allowing for seamless cross-domain
+communication.
+
+The library is a thin wrapper around Yrs, taking advantage of the safety and
+performance of Rust.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'y-rb'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install y-rb
+
+## Usage
+
+```ruby
+# creates a new document and text structure
+local = Y::Doc.new 
+local_text = local.get_text("my text")
+
+# add some data to the text structure
+local_text.push("hello")  
+  
+# create a remote doccument sharing the same text structure
+remote = Y::Doc.new 
+remote_text = remote.get_text("my text")  
+
+# retrieve the current state of the remote document
+remote_state = remote.state  
+
+# create an update for the remote document based on the current
+# state of the remote document
+update = local.diff(remote_state)  
+  
+# apply update to remote document
+remote.sync(update)  
+
+puts remote_text.to_s == local_text.to_s # true  
+```  
+
+More [examples](./docs/examples).
+
+## Development
+
+Make sure you have `cargo` available (2021 edition). The gem needs the lib to
+be built every time when there is a change.
+
+```bash
+cargo build --release
+```
+
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Docs
+
+You can run `yard` locally and open the docs with:
+
+```bash
+yard server 
+open "http://0.0.0.0:8808/"
+```
+
+## Decision log
+
+For this `gem`, we maintain a [decision log](./docs/decisions.md). Please consult it
+in case there is some ambiguity in terms of why certain implementation details
+look as they are. 
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+require "rubocop/rake_task"
+require "thermite/tasks"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc "Compile the y-rb crate"
+task :compile do
+  # MacOS: ARM + x64
+  `cargo build --release --target=aarch64-apple-darwin`
+  `cargo build --release --target=x86_64-apple-darwin`
+
+  # Copy to target folder
+  `cp target/aarch64-apple-darwin/release/liby_rb.dylib target/release/`
+end
+
+task :clean do
+  `cargo clean`
+end
+
+task test: :spec
+
+task :docs do
+  `yard server --reload`
+end
+
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new
+
+Thermite::Tasks.new

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "y/rb"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docs/build.md

@@ -0,0 +1 @@
+# Build Instructions

data/docs/decisions.md

@@ -0,0 +1,64 @@
+# Decision log
+
+## 2022-05-12
+
+### Transactions do not always commit automatically
+
+In `yrs`, the lifetime of a transaction is determined automatically. This can
+lead to an interesting situation in Ruby, where we attach a listener to receive
+changes, never commit a transaction explicitly and where the transaction gets
+dropped automatically. I believe we still maintain a pointer to the transaction
+that no longer exists, and therefore we receive a segfault.
+
+## 2022-05-12
+
+### Add event-driven approach to receive changes
+
+It is not clear if this ends up being the final API to receive changes, but
+it is the one that is supported in one or the other way across all `yrs`
+implementations. It might be beneficial to add a synchronous API in the future,
+but this isn't supported right away. All common styles of closure like behavior
+are supported: `Proc`, `Lambda` and `Block`.
+
+## 2022-05-09
+
+### Supported operations on data types are either read-only or mutable
+
+In a meeting with the wider `y-crdt` group on May 6th, 2022, it became clear
+that the cost of creating a new instance of a data type is common operation in
+many languages (Python, Ruby, …), but it is not something we should to support.
+This pattern leads to all sort of problems, mostly because it contradicts the
+common usage pattern of replicating changes between two or more clients.
+
+Instead, the API should be explicit about this fact and should not make it too
+easy to do that.
+
+## 2022-05-06
+
+### Transactions are implicit by default
+
+The developer should not be exposed to transactions until they need to
+change the default logic in any way. If someone creates a structure and inserts,
+removes, this should be part of the same transaction until stated otherwise.
+
+### Synchronisation happens at the document level
+
+It might be interesting to sync at a more granular level, but for the sake of
+simplicity, the first iteration of this library will only support
+synchronization of the complete document.
+
+## 2022-05-05
+
+### No direct exposure of internal API
+
+The internal API (`y-crdt`) is subject to constant changes and does not
+necessarily offer an idiomatic Ruby interface. Therefore, the public API of
+`y-rb` does not follow the `y-crdt` API, but prefers familiar Ruby idioms when
+possible and might even require libraries where it makes sense (e.g. `nokogiri` for XML).
+
+### Rutie is a temporary dependency
+
+The Ruby<->Rust binding feels immature. But it is not the goal of this project
+to fix this immediately. The long-term vision is to replace this part by
+something more lightweight and opinionated that could be part of the Rust
+codebase of this project.

data/docs/examples.md

@@ -0,0 +1,16 @@
+# Examples
+
+> Usage patterns
+
+## Send a full document update to a client
+
+```ruby
+doc = Y::Doc.new
+text = doc.get_text("about")
+text << "My name is, my name is, my name is … Slim Shady"
+
+zero = Y::Doc.new
+update = doc.diff(zero.state)
+
+transfer update
+```

data/ext/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "thermite/tasks"
+
+project_dir = File.dirname(File.dirname(__FILE__))
+Thermite::Tasks.new(cargo_project_path: project_dir,
+                    ruby_project_path: project_dir)
+
+task default: %w[thermite:build]