crdt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd48ff44957feb80db35dde367d7738a00017ba4
+  data.tar.gz: 14f4d3d491163faaad568b5dd827e058671a3640
+SHA512:
+  metadata.gz: f93a162bb0765597bb6519a41691bcca73bcd5c7ee6f6d67b91f02434a514d5088b11980716fa0a9297eabadb71c9a5d7be370d06255f1a4195562699715d5b0
+  data.tar.gz: 512bd46616582d6d910302677d3f9956e261965db82391f5cccaf1413aae37aa813545b2daf081137519c11b7909038b4984beb8c68fb4e9d6c73d98997a0f67

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in crdt.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Steven Karas
+
+MIT License
+
+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,59 @@
+# CRDTs for Ruby
+
+This gem provides CRDTs for use in other projects. I've favored clarity of code and intent over optimizations, so if you really need the extra performance, you can use these as a guide to understand the underlying concept, and then implement a more performant version.
+
+That means no fancy class hierarchy, no performance oriented code, no complex loading path and class space munging.
+
+## What are CRDTs
+
+CRDTS are distributed data types that exhibit something called Strong Eventual Consistency. Basically, they're the building blocks that let you build distributed systems.
+
+## How can I learn more
+
+Marc Shapiro has cowritten a bunch of papers that cover both the basics of CRDTs and also a useful survey of simple CRDTs. There are video lectures where he explains most of them visually as well.
+
+In fact, the names of the data types in this project I've taken from his survey paper.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'crdt'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install crdt
+
+## Usage
+
+You can require all the CRDTs, or individual ones:
+
+```ruby
+require 'crdt'
+```
+
+Or
+
+```ruby
+require 'crdt/or_set'
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/stevenkaras/crdt/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Acknowledgements
+
+Based on research by Marc Shapiro, et al.
+
+Inspired by [aphyr/meangirls](https://github.com/aphyr/meangirls), but not based on (he does some funky class inheritence/loading tricks I don't like).

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/crdt.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'crdt/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'crdt'
+  spec.version     = CRDT::VERSION
+
+  spec.licenses    = ['MIT']
+  spec.summary     = "Convergent/Commutative Replicated Data Types"
+  spec.description = "This library provides naive implementations of common CRDTs"
+
+  spec.authors     = ["Steven Karas"]
+  spec.email       = 'steven.karas@gmail.com'
+  spec.homepage    = 'https://rubygems.org/gems/crdt'
+
+  spec.files       = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files  = spec.files.grep(%r{^(test|spec|features)/})
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+end

data/lib/crdt.rb

@@ -0,0 +1,15 @@
+# Convergent/Commutative Replicated Data Types
+#
+# TODO: document library inclusion
+# TODO: document usage example
+module CRDT
+end
+
+%w{
+  pn_counter
+  vector_clock
+  or_set
+  lww_register
+}.each do |lib|
+  require File.expand_path("crdt/#{lib}", __DIR__)
+end

data/lib/crdt/lww_register.rb

@@ -0,0 +1,66 @@
+module CRDT
+  # Last Write Wins Register
+  #
+  # This is a LWWRegister, useful for storing arbitrary data. However, it assumes that your nodes' clocks are synchronized.
+  #
+  # In practice, this is problematic if you expect changes to take place more often than the clock drift.
+  # In my personal experience, clock drift is usually only a few seconds between servers, but can be upwards of several minutes between personal devices such as mobile phones/tablets (especially those on different cellular networks)
+  class LWWRegister
+    def initialize(tiebreaker = Thread.current.object_id.to_i)
+      @tiebreaker = tiebreaker
+      @value = nil
+      @timestamp = nil
+    end
+
+    attr_accessor :value, :timestamp, :timestamp_nsec, :timestamp_tiebreaker
+
+    # Set the value of this register, throwing out any previous value
+    def set(value)
+      @value = value
+      time = Time.now
+      @timestamp = time.to_i
+      @timestamp_nsec = time.nsec
+      @timestamp_tiebreaker = @tiebreaker
+    end
+
+    # Get the value in this register
+    def get
+      @value
+    end
+
+    # Perform a one way merge, potentially bringing in the value from another register
+    def merge(other)
+      return unless other.timestamp
+      return unless other.timestamp >= @timestamp
+      return unless other.timestamp_nsec >= @timestamp_nsec
+      return unless other.timestamp_tiebreaker >= @timestamp_tiebreaker
+      @value = other.value
+      @timestamp = other.timestamp
+      @timestamp_nsec = other.timestamp_nsec
+      @timestamp_tiebreaker = other.timestamp_tiebreaker
+    end
+
+    # Get a hash representation of this register, suitable for serialization to JSON
+    def to_h
+      return {
+        value: @value,
+        timestamp: @timestamp,
+        timestamp_nsec: @timestamp_nsec,
+        timestamp_tiebreaker: @timestamp_tiebreaker,
+        tiebreaker: @tiebreaker,
+      }
+    end
+
+    # Build a new register from the given hash
+    def self.from_h(hash)
+      register = LWWRegister.new(hash["tiebreaker"])
+
+      register.value = hash["value"]
+      register.timestamp = hash["timestamp"]
+      register.timestamp_nsec = hash["timestamp_nsec"]
+      register.timestamp_tiebreaker = hash["timestamp_tiebreaker"]
+
+      return register
+    end
+  end
+end

data/lib/crdt/or_set.rb

@@ -0,0 +1,106 @@
+module CRDT
+  # Observed-Removed Set
+  #
+  # This CRDT allows items to be added, and removed. The idea being that when an item is added, it is added along with a token. When removing an element, all tokens for that item are marked as removed.
+  # This implementation of an ORSet keeps a unified record for each item, where removed tokens are moved from an "observed" set to a "removed" set.
+  #
+  # Efficiency:
+  # Number of items: n, Number of nodes: m, Number of operations: k
+  # Space efficiency: O(k)
+  # Space efficiency with garbage collection: O(n)
+  # Adding an item: O(1)
+  # Removing an item: O(k) in the degenerate case, typically closer to O(1)
+  # Testing if an item is in the set: O(1)
+  class ORSet
+    # Create a new, empty set
+    def initialize(node_identity = Thread.current.object_id, token_counter = 0)
+      @node_identity = node_identity
+      @token_counter = token_counter
+      @items = {}
+    end
+
+    attr_accessor :items, :token_counter
+
+    # Check if this item is in the set
+    def has?(item)
+      tokens = @items[item]
+      return false unless tokens
+      return ! tokens[:observed].empty?
+    end
+
+    # Add an item to this set
+    def add(item)
+      # the token in this implementation is "better", since it's easier for us to parse/garbage collect
+      token = "#{@node_identity}:#{@token_counter}"
+      @token_counter += 1
+
+      @items[item] ||= { observed: [], removed: []}
+      @items[item][:observed] << token
+    end
+
+    # Mark an item as removed from the set
+    def remove(item)
+      @items[item][:removed] += @items[item][:observed]
+      @items[item][:observed] = []
+    end
+
+    # Get a hash representation of this set, suitable for serialization to JSON
+    def to_h
+      return {
+        node_identity: @node_identity,
+        token_counter: @token_counter,
+        items: @items,
+      }
+    end
+
+    # Create a ORSet from a hash, such as that deserialized from JSON
+    def self.from_h(hash)
+      set = ORSet.new(hash["node_identity"], hash["token_counter"])
+
+      hash["items"].each do |item, record|
+        set.items[item] = {observed: [], removed: []}
+        set.items[item][:observed] += record[:observed]
+        set.items[item][:removed] += record[:removed]
+      end
+
+      return set
+    end
+
+    # Perform a one-way merge, bringing changes from the other ORSet provided
+    #
+    # @param other (ORSet)
+    def merge(other)
+      other.items.each do |item, record|
+        @items[item] ||= {observed: [], removed: []}
+        @items[item][:observed] += record[:observed]
+        @items[item][:removed] += record[:removed]
+        @items[item][:observed] -= @items[item][:removed]
+      end
+    end
+
+    # garbage collect all tokens originating from the given node that are smaller than the given counter
+    #
+    # This should be called only when partial consensus can be ascertained for the system
+    def gc(node_to_collect, until_counter)
+      match_proc = proc do |token|
+        node, counter = token.split(":")
+        node == node_to_collect && counter.to_i <= until_counter
+      end
+
+      @items.each do |item, record|
+        # remove any removal records, since the system has reached consensus up to this node's counter
+        record[:removed].reject!(&:match_proc)
+
+        # squash all the observed tokens into one
+        # This is potentially unnecessary so long as at most one active observed token is recorded per node
+        tokens = record[:observed].select(&:match_proc).map do |token|
+          node, counter = token.split(":")
+          [node, counter.to_i]
+        end.sort_by(&:last)
+        surviving_token = tokens.pop
+        record[:observed] -= tokens
+        record[:observed] << surviving_token
+      end
+    end
+  end
+end

data/lib/crdt/pn_counter.rb

@@ -0,0 +1,143 @@
+module CRDT
+  # A positive negative counter
+  #
+  # This counter can be incremented up or down. Each node should only adjust it's up and down counters.
+  # The current value of the counter is calculated by taking the sum of all the positive counters and subtracting the sum of all the negative counters
+  #
+  # # Efficiency:
+  # value in counter: n, number of nodes: m, number of changes: k
+  # Local changes (+/-) are O(1)
+  # Merging changes are O(m)
+  # The space cost is O(m)
+  # The space cost of synchronization is O(m)
+  #
+  # # Implementation notes:
+  # This implementation is a CvRDT. That means it takes 
+  # This implementation doesn't support garbage collection, although you could add it by removing a node's records, and folding it into a base value.
+  class PNCounter
+    # @param hash [Hash] a serialized PNCounter, conforming to the format here
+    # 
+    # Expects a Hash in the following format:
+    # {
+    #   "positive" => {
+    #     "1" => 15,
+    #     "3" => 4
+    #   },
+    #   "negative" => {
+    #   }
+    # }
+    def self.from_h(hash)
+      counter = PNCounter.new
+
+      hash["positive"].each do |source, amount|
+        counter.increase(amount, source)
+      end
+      hash["negative"].each do |source, amount|
+        counter.decrease(amount, source)
+      end
+
+      return counter
+    end
+
+    # Get a hash representation of this object, which is suitable for serialization to JSON
+    def to_h
+      return {
+        cached_value: @cached_value,
+        positive: @positive_counters,
+        negative: @negative_counters,
+      }
+    end
+
+    # Create a new counter
+    #
+    # @param this_source Identifier for this node, used for tracking changes to the counter. Defaults to the current Thread's object ID
+    def initialize(this_source = Thread.current.object_id)
+      @cached_value = 0
+      @positive_counters = {}
+      @negative_counters = {}
+      @this_source = this_source
+    end
+
+    attr_accessor :positive_counters, :negative_counters
+
+    # Increase this counter by the given amount
+    #
+    # @param amount [Number] a non-negative amount to decrease this counter by
+    def increase(amount, source = nil)
+      source ||= @this_source
+      positive_counters[source] ||= 0
+      positive_counters[source] += amount
+      @cached_value += amount
+
+      return self
+    end
+
+    # Decrease this counter by the given amount
+    #
+    # @param amount [Number] a non-negative amount to decrease this counter by
+    def decrease(amount, source = nil)
+      source ||= @this_source
+      negative_counters[source] ||= 0
+      negative_counters[source] += amount
+      @cached_value -= amount
+
+      return self
+    end
+
+    # Add something to this counter
+    #
+    # @param other [Number] the amount to add to this counter
+    def +=(other)
+      if other > 0
+        increase(other)
+      else
+        decrease(- other)
+      end
+    end
+
+    # Subtract something from this counter
+    #
+    # @param other [Number] the amount to subtract from this counter
+    def -=(other)
+      if other > 0
+        decrease(other)
+      else
+        increase(- other)
+      end
+    end
+
+    def value
+      @cached_value
+    end
+
+    def to_i
+      @cached_value.to_i
+    end
+
+    # Merge the counters from the other PNCounter into this one
+    def merge(other)
+      other.positive_counters.each do |source, amount|
+        current_amount = @positive_counters[source]
+        if current_amount
+          if current_amount < amount
+            @positive_counters[source] = amount
+          end
+        else
+          @positive_counters[source] = amount
+        end
+      end
+      other.negative_counters.each do |source, amount|
+        current_amount = @negative_counters[source]
+        if current_amount
+          if current_amount < amount
+            @negative_counters[source] = amount
+          end
+        else
+          @negative_counters[source] = amount
+        end
+      end
+
+      return self
+    end
+  end
+end

data/lib/crdt/vector_clock.rb

@@ -0,0 +1,74 @@
+module CRDT
+  # Vector clocks are a loose synchronization primitive
+  #
+  # Vector clocks can be used as a building block to create other replicated data types, and tracking operations
+  #
+  # Formally, a vector clock is equivalent to a GCounter that is only incremented by 1, and the aggregate value is ignored
+  class VectorClock
+    # Create a new vector clock
+    #
+    # @param default_node Identity of the current node. Defaults to the current Thread object id
+    def initialize(default_node = Thread.current.object_id)
+      @default_node = default_node
+      @clocks = {}
+    end
+
+    attr_accessor :clocks
+
+    # Increment the clock for the given node by 1
+    #
+    # @param node The node to update the clock for. Defaults to the default node
+    def increment_clock(node = nil)
+      node ||= @default_node
+      @clocks[node] ||= 0
+      @clocks[node] += 1
+    end
+
+    # Get the current clock value for the given node
+    #
+    # @param node the node to check for. Defaults to the default node
+    def value(node = nil)
+      node ||= @default_node
+      @clocks[node]
+    end 
+
+    # Create a new VectorClock from the provided hash. The hash should follow this syntax:
+    #
+    # {
+    #   "clocks" => {
+    #     "1" => 3,
+    #     "3" => 2
+    #   }
+    # }
+    def self.from_h(hash)
+      clock = VectorClock.new
+
+      hash["clocks"].each do |node, value|
+        clock.clocks[node] = value
+      end
+
+      return clock
+    end
+
+    # Get a hash representation of this vector clock, suitable for serialization to JSON
+    def to_h
+      return {
+        clocks: @clocks,
+      }
+    end
+
+    # Perform a one-way merge, bringing in clock values from the other clock
+    def merge(other)
+      other.clocks.each do |node, value|
+        current_value = @clocks[node]
+        if current_value
+          if current_value < value
+            @clocks[node] = value
+          end
+        else
+          @clocks[node] = value
+        end
+      end
+    end
+  end
+end

data/lib/crdt/version.rb

@@ -0,0 +1,3 @@
+module CRDT
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: crdt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Steven Karas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This library provides naive implementations of common CRDTs
+email: steven.karas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- crdt.gemspec
+- lib/crdt.rb
+- lib/crdt/lww_register.rb
+- lib/crdt/or_set.rb
+- lib/crdt/pn_counter.rb
+- lib/crdt/vector_clock.rb
+- lib/crdt/version.rb
+homepage: https://rubygems.org/gems/crdt
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Convergent/Commutative Replicated Data Types
+test_files: []