rloss 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 032f5b4b44b83ca04abfa4d14381adbbc0e52565
+  data.tar.gz: 751b6adbda48d547a04c516f7e123f6f3cf1ed1d
+SHA512:
+  metadata.gz: 3e780da641248b462a9684536ccc82843821442471335efcd159cb62d429abd1c5bfd85831ef2baa76b4cbec704b46d5963f303d9044f232d3cdc4fad7fa1363
+  data.tar.gz: d0cde7f4a013edd6b65adbedf0af855f76baf161c30a6a93a55d3258727552653256b44c7cf488cb7b8cdfb6f49e919046768917fff9afcfa0c69678c29cbf7b

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store
+log/*

data/.rspec

@@ -0,0 +1 @@
+--fail-fast --backtrace --require spec_helper

data/.travis.yml

@@ -0,0 +1,3 @@
+before_install: sudo apt-get install libzmq3-dev
+script: bundle exec rake
+language: ruby

data/.yardopts

@@ -0,0 +1,3 @@
+--markup=markdown
+--charset=utf-8
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in floss.gemspec
+gemspec
+
+gem 'celluloid', github: 'celluloid/celluloid'
+gem 'celluloid-io', github: 'celluloid/celluloid-io'
+gem 'celluloid-zmq', github: 'celluloid/celluloid-zmq'
+
+group :docs do
+  gem 'yard'
+  gem 'redcarpet'
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Alexander Flatter
+
+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,102 @@
+[![Build Status](https://secure.travis-ci.org/celluloid/floss.png?branch=master)](http://travis-ci.org/celluloid/floss)
+
+# Floss
+
+An implementation of the [Raft consensus algorithm](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf) on top of Celluloid.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'floss'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install floss
+```
+
+## Usage
+
+We're going to implement a distributed counter. While not very useful, it's a good enough demonstration of what you can
+do with this library. Let's start with the counter service. It accepts three commands, `get`, `reset` and `increase`.
+The first simply returns the current count, the second sets the count to zero and the third changes the current count,
+optionally by a given amount.
+
+```ruby
+class Counter
+  attr_accessor :count
+
+  def initialize
+    self.count = 0
+  end
+
+  def get
+    count
+  end
+
+  def reset
+    self.count = 0
+  end
+
+  def increase(amount = 1)
+    self.count += amount
+  end
+end
+```
+
+To increase reliability of your counter, you decide to distribute it across multiple machines. This is where `floss`
+comes into play. To simplify this demonstration, we're going to start multiple nodes in the same process.
+
+```ruby
+addresses = [10001, 10002, 10003].map { |port| "tcp://127.0.0.1:#{port}" }
+
+$nodes = addresses.size.times.map do |i|
+  combination = addresses.rotate(i)
+  options = {id: combination.first, peers: combination[1..-1]}
+  Floss::Proxy.new(Counter.new, options)
+end
+
+# Give your nodes some time to start up.
+$nodes.each(&:wait_until_ready)
+```
+
+Now we're ready to play with our distributed counter.
+
+```ruby
+def random_node; $nodes.sample; end
+
+random_node.get # => 0
+random_node.increase # => 1
+random_node.get # => 1
+```
+
+That was easy wasn't it? Let's see what happens if the cluster is damaged.
+
+```ruby
+# Terminate a random node in the cluster.
+doomed_node = $nodes.delete(random_node)
+doomed_node_id = doomed_node.id
+doomed_node.terminate
+
+random_node.increase # => 2
+```
+
+Your cluster still works. If you'd kill another one, executing a command would result in an error because insufficient
+nodes are available to ensure your system's consistency.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/examples/distributed_hash.rb

@@ -0,0 +1,36 @@
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'floss/test_helper'
+require 'floss/proxy'
+
+include Celluloid::Logger
+
+class FSM
+  def initialize
+    @content = Hash.new
+  end
+
+  def set(key, value)
+    @content[key] = value
+  end
+
+  def get(key)
+    @content[key]
+  end
+end
+
+CLUSTER_SIZE = 5
+
+ids = CLUSTER_SIZE.times.map do |i|
+  port = 50000 + i
+  "tcp://127.0.0.1:#{port}"
+end
+
+proxies = Floss::TestHelper.cluster(ids) do |id, peers|
+  Floss::Proxy.new(FSM.new, id: id, peers: peers)
+end
+
+100.times do |i|
+  proxies.sample.set(:foo, i)
+  raise "fail" unless proxies.sample.get(:foo) == i
+end

data/lib/floss.rb

@@ -0,0 +1,7 @@
+require 'celluloid'
+require "floss/version"
+
+module Floss
+  class Error < StandardError; end
+  class TimeoutError < Error; end
+end

data/lib/floss/count_down_latch.rb

@@ -0,0 +1,23 @@
+require 'celluloid'
+require 'floss'
+
+class Floss::CountDownLatch
+  # @return [Fixnum] Current count.
+  attr_reader :count
+
+  def initialize(count)
+    @count = count
+    @condition = Celluloid::Condition.new
+  end
+
+  def signal
+    return if @count == 0 
+
+    @count -= 1
+    @condition.signal if @count == 0
+  end
+
+  def wait
+    @condition.wait
+  end
+end

data/lib/floss/latch.rb

@@ -0,0 +1,53 @@
+require 'celluloid'
+require 'floss'
+
+# Based on Celluloid::Condition.
+class Floss::Latch
+  SignalConditionRequest = Celluloid::SignalConditionRequest
+  class LatchError < Celluloid::Error; end
+
+  def initialize
+    @tasks = []
+    @mutex = Mutex.new
+    @ready = false
+    @values = nil
+  end
+
+  def ready?
+    @mutex.synchronize { @ready }
+  end
+
+  def wait
+    raise LatchError, "cannot wait for signals while exclusive" if Celluloid.exclusive?
+
+    task = Thread.current[:celluloid_actor] ? Celluloid::Task.current : Thread.current
+    waiter = Celluloid::Condition::Waiter.new(self, task, Celluloid.mailbox)
+
+    ready = @mutex.synchronize do
+      ready = @ready
+      @tasks << waiter unless ready
+      ready
+    end
+
+    values = if ready
+      @values
+    else
+      values = Celluloid.suspend(:condwait, waiter)
+      raise values if values.is_a?(LatchError)
+      values
+    end
+
+    values.size == 1 ? values.first : values
+  end
+
+  def signal(*values)
+    @mutex.synchronize do
+      return false if @ready
+
+      @ready = true
+      @values = values
+
+      @tasks.each { |waiter| waiter << SignalConditionRequest.new(waiter.task, values) }
+    end
+  end
+end

data/lib/floss/log.rb

@@ -0,0 +1,69 @@
+require 'forwardable'
+require 'floss'
+
+# See Section 5.3.
+class Floss::Log
+  include Celluloid
+  extend Forwardable
+
+  class Entry
+    # @return [Fixnum] When the entry was received by the leader.
+    attr_accessor :term
+
+    # @return [Object] A replicated state machine command.
+    attr_accessor :command
+
+    def initialize(command, term)
+      raise ArgumentError, "Term must be a Fixnum." unless term.is_a?(Fixnum)
+
+      self.term = term
+      self.command = command
+    end
+  end
+
+  def initialize(options={})
+    raise NotImplementedError
+  end
+
+  def []=(k,v)
+    raise NotImplementedError
+  end
+
+  def empty?
+    raise NotImplementedError
+  end
+
+  # @param [Array] The entries to append to the log.
+  def append(new_entries)
+    raise NotImplementedError
+  end
+
+  def starting_with(index)
+    raise NotImplementedError
+  end
+
+  # Returns the last index in the log or nil if the log is empty.
+  def last_index
+    raise NotImplementedError
+  end
+
+  # Returns the term of the last entry in the log or nil if the log is empty.
+  def last_term
+    raise NotImplementedError
+  end
+
+  def complete?(other_term, other_index)
+    # Special case: Accept the first entry if the log is empty.
+    return empty? if other_term.nil? && other_index.nil?
+
+    (other_term > last_term) || (other_term == last_term && other_index >= last_index)
+  end
+
+  def validate(index, term)
+    raise NotImplementedError
+  end
+
+  def remove_starting_with(index)
+    raise NotImplementedError
+  end
+end

data/lib/floss/log/simple.rb

@@ -0,0 +1,55 @@
+require 'forwardable'
+require 'floss'
+require 'floss/log'
+
+# See Section 5.3.
+class Floss::Log
+  class Simple < Floss::Log
+    include Celluloid
+    extend Forwardable
+
+    def_delegators :entries, :[], :empty?
+
+    # @return [Array<Entry>] The log's entries.
+    attr_accessor :entries
+
+    def initialize(options={})
+      self.entries = []
+    end
+
+    # @param [Array] The entries to append to the log.
+    def append(new_entries)
+      raise ArgumentError, 'The passed array is empty.' if new_entries.empty?
+
+      entries.concat(new_entries)
+      last_index
+    end
+
+    def starting_with(index)
+      entries[index..-1]
+    end
+
+    # Returns the last index in the log or nil if the log is empty.
+    def last_index
+      entries.any? ? entries.size - 1 : nil
+    end
+
+    # Returns the term of the last entry in the log or nil if the log is empty.
+    def last_term
+      entry = entries.last
+      entry ? entry.term : nil
+    end
+
+    def validate(index, term)
+      # Special case: Accept the first entry if the log is empty.
+      return empty? if index.nil? && term.nil?
+
+      entry = entries[index]
+      entry && entry.term == term
+    end
+
+    def remove_starting_with(index)
+      entries.slice!(index..-1)
+    end
+  end
+end

data/lib/floss/log_replicator.rb

@@ -0,0 +1,148 @@
+require 'floss'
+require 'floss/count_down_latch'
+
+# Used by the leader to manage the replicated log.
+class Floss::LogReplicator
+  extend Forwardable
+  include Celluloid
+
+  class IndexWaiter
+    class Waiter
+      attr_reader :peer
+      attr_reader :index
+      attr_reader :condition
+
+      def initialize(peer, index, condition)
+        @peer = peer
+        @index = index
+        @condition = condition
+      end
+    end
+
+    def initialize
+      @waiters = []
+    end
+
+    def register(peer, index, condition)
+      # This class is always used to wait for replication of a log entry, so we're failing fast here:
+      # Every log entry has an index, thus nil is disallowed.
+      unless index.is_a?(Fixnum) && index >= 0
+        raise ArgumentError, 'index must be a Fixnum and >= 0'
+      end
+
+      @waiters << Waiter.new(peer, index, condition)
+    end
+
+    def signal(peer, index)
+      return unless index # There's nothing to do if no index is given, see #register.
+
+      waiters = @waiters.delete_if do |waiter|
+        next unless waiter.peer == peer
+        waiter.index <= index
+      end
+
+      waiters.map(&:condition).each(&:signal)
+    end
+  end
+
+  finalizer :finalize
+
+  def_delegators :node, :peers, :log
+
+  # TODO: Pass those to the constructor: They don't change during a term.
+  def_delegators :node, :cluster_quorum, :broadcast_time, :current_term
+
+  # @return [Floss::Node]
+  attr_accessor :node
+
+  def initialize(node)
+    @node = node
+
+    # A helper for waiting on a certain index to be written to a peer.
+    @write_waiters = IndexWaiter.new
+
+    # Stores the index of the last log entry that a peer agrees with.
+    @write_indices = {}
+
+    # Keeps Celluloid::Timer instances that fire periodically for each peer to trigger replication.
+    @pacemakers = {}
+
+    initial_write_index = log.last_index
+
+    peers.each do |peer|
+      @write_indices[peer] = initial_write_index
+      @pacemakers[peer] = after(broadcast_time) { replicate(peer) }
+    end
+  end
+
+  def append(entry)
+    pause
+    index = log.append([entry])
+
+    quorum = Floss::CountDownLatch.new(cluster_quorum)
+    peers.each { |peer| signal_on_write(peer, index, quorum) }
+
+    resume
+    quorum.wait
+
+    # TODO: Ensure there's at least one write in the leader's current term.
+    @commit_index = index
+  end
+
+  def signal_on_write(peer, index, condition)
+    @write_waiters.register(peer, index, condition)
+  end
+
+  def pause
+    @pacemakers.values.each(&:cancel)
+  end
+
+  def resume
+    @pacemakers.values.each(&:fire)
+  end
+
+  def replicate(peer)
+    write_index = @write_indices[peer]
+    response = peer.append_entries(construct_payload(write_index))
+
+    if response[:success]
+      # nil if the log is still empty, last replicated log index otherwise
+      last_index = log.last_index
+
+      @write_indices[peer] = last_index
+      @write_waiters.signal(peer, last_index)
+    else
+      # Walk back in the peer's history.
+      @write_indices[peer] = write_index > 0 ? write_index - 1 : nil if write_index
+    end
+
+    @pacemakers[peer].reset
+  end
+
+  # Constructs payload for an AppendEntries RPC given a peer's write index.
+  # All entries **after** the given index will be included in the payload.
+  def construct_payload(index)
+    if index
+      prev_index = index
+      prev_term  = log[prev_index].term
+      entries = log.starting_with(index + 1)
+    else
+      prev_index = nil
+      prev_term = nil
+      entries = log.starting_with(0)
+    end
+
+    Hash[
+      leader_id: node.id,
+      term: current_term,
+      prev_log_index: prev_index,
+      prev_log_term: prev_term,
+      commit_index: @commit_index,
+      entries: entries
+    ]
+  end
+
+  def finalize
+    pause
+  end
+end