noeq 0.1.0 → 0.2.0

data/README.md

@@ -2,6 +2,8 @@
 
 noeq-rb is a [noeqd](https://github.com/bmizerany/noeqd) GUID client in Ruby.
 
+[Annotated source code is available](http://titanous.com/noeq-rb/).
+
 ## Installation
 
 ```
@@ -26,3 +28,14 @@ noeq = Noeq.new('idserver.local')
 noeq.generate #=> 142692638036852736
 noeq.generate(5) #=> [142692782450933760, 142692782450933761, 142692782450933762, 142692782450933763, 142692782450933764]
 ```
+
+### Async usage
+
+```ruby
+require 'noeq'
+
+noeq = Noeq.new('localhost', 4444, :async => true)
+noeq.request_id
+# do some things
+noeq.fetch_id #=> 142692638036852736
+```

data/TODO

@@ -0,0 +1,2 @@
+* generate can probably block forever in specific failure cases
+* multiple server failover support

data/lib/noeq.rb

@@ -1,6 +1,13 @@
+# **Noeq** generates GUIDs using [noeqd](https://github.com/bmizerany/noeqd).
+
+# `noeqd` uses a simple TCP wire protocol, so let's require our only dependency,
+# `socket`.
 require 'socket'
 
 class Noeq
+
+  # If you just want to test out `noeq` or need to use it in a one-off script,
+  # this method allows for very simple usage.
   def self.generate(n=1)
     noeq = new
     ids = noeq.generate(n)
@@ -8,36 +15,94 @@ class Noeq
     ids
   end
 
-  def initialize(server = 'localhost', port = 4444)
-    @server, @port, = server, port
+  # `Noeq.new` defaults to connecting to `localhost:4444` with async off.
+  # The `options` hash is used so that we are verbose when turning async on.
+  def initialize(host = 'localhost', port = 4444, options = {})
+    @host, @port, @async = host, port, options[:async]
     connect
   end
 
+  # The first thing that we need to do is connect to the `noeqd` server.
   def connect
-    @socket = TCPSocket.new @server, @port
+    # We create a new TCP `STREAM` socket. There are a few other types of
+    # sockets, but this is the most common.
+    @socket = Socket.new(:INET, :STREAM)
+
+    # In order to create a socket connection we need an address object.
+    address = Socket.sockaddr_in(@port, @host)
+
+    # If async is enabled, we establish the connection in nonblocking mode,
+    # otherwise we connect normally, which will wait until the connection is
+    # established.
+    @async ? @socket.connect_nonblock(address) : @socket.connect(address)
+
+    # `Socket.connect_nonblock` raises `Errno::EINPROGRESS` if the socket isn't
+    # connected instantly. It will be connected in the background, so we ignore
+    # the exception
+  rescue Errno::EINPROGRESS
   end
 
   def disconnect
+    # If the socket has already been closed by the other side, `close` will
+    # raise, so we rescue it.
     @socket.close rescue false
   end
 
+  # The workhorse generate method. Defaults to one id, but up to 255 can be
+  # requested.
   def generate(n=1)
-    @socket.send [n].pack('c'), 0
-    ids = (1..n).map { get_id }.compact
-    ids.length > 1 ? ids : ids.first
+    request_id(n)
+    fetch_id(n)
+
+    # If something goes wrong, we reconnect and retry. There is a slim chance
+    # that this will result in an infinite loop, but most errors are raised in
+    # the reconnect step and won't get re-rescued here.
   rescue
     disconnect
     connect
     retry
   end
 
+  def request_id(n=1)
+    # The integer is packed into a binary byte and sent to the `noeqd` server.
+    # The second argument to `BasicSocket#send` is a bitmask of flags, we don't
+    # need anything special, so it is set to zero.
+    @socket.send [n].pack('c'), 0
+  end
+  alias :request_ids :request_id
+
+  def fetch_id(n=1)
+    # We collect the ids from the `noeqd` server.
+    ids = (1..n).map { get_id }.compact
+
+    # If we have more than one id, we return the array, otherwise we return the
+    # single id.
+    ids.length > 1 ? ids : ids.first
+  end
+  alias :fetch_ids :fetch_id
+
   private
 
   def get_id
-    (read_long << 32) + read_long
+    # `noeqd` sends us a 64-bit unsigned integer in network (big-endian) byte
+    # order, but Ruby 1.8 doesn't have a native unpack directive for this, so we
+    # do it manually by shifting the high bits and adding the low bits.
+    high, low = read_long, read_long
+    return unless high && low
+    (high << 32) + low
   end
 
   def read_long
-    @socket.read(4).unpack("N").first
+    # `IO.select` blocks until one of the sockets passed in has an event
+    # or a timeout is reached (the fourth argument). We don't do the `select`
+    # if we are in async mode.
+    IO.select([@socket], nil, nil, 0.1) unless @async
+
+    # Since `select` has already blocked for us, we are pretty sure that
+    # there is data available on the socket, so we try to fetch 4 bytes and
+    # unpack them as a 32-bit big-endian unsigned integer. If there is no data
+    # available this will raise `Errno::EAGAIN` which will propagate up and
+    # could cause a retry.
+    @socket.recv_nonblock(4).unpack("N").first
   end
 end

data/noeq.gemspec

@@ -12,5 +12,5 @@ Gem::Specification.new do |gem|
   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   gem.name          = "noeq"
   gem.require_paths = ["lib"]
-  gem.version       = "0.1.0"
+  gem.version       = "0.2.0"
 end

data/test/noeq_test.rb

@@ -0,0 +1,89 @@
+require 'test/unit'
+require './lib/noeq'
+
+class NoeqTest < Test::Unit::TestCase
+
+  def setup
+    FakeNoeqd.start
+  end
+
+  def teardown
+    FakeNoeqd.stop
+  end
+
+  def test_simple_generate
+    assert_equal expected_id, Noeq.generate
+  end
+
+  def test_multiple_generate
+    noeq = Noeq.new
+    assert_equal [expected_id]*3, noeq.generate(3)
+  end
+
+  def test_different_port
+    FakeNoeqd.stop
+    FakeNoeqd.start(4545)
+
+    noeq = Noeq.new('localhost', 4545)
+    assert_equal expected_id, noeq.generate
+  end
+
+  def test_reconnect
+    noeq = Noeq.new
+    assert noeq.generate
+
+    FakeNoeqd.stop
+    FakeNoeqd.start
+
+    assert_equal expected_id, noeq.generate
+  end
+
+  def test_async_generate
+    noeq = Noeq.new('localhost', 4444, :async => true)
+    noeq.request_id
+    sleep 0.0001
+    assert_equal expected_id, noeq.fetch_id
+  end
+
+  def test_async_request_with_disconnected_server_raises
+    noeq = Noeq.new('localhost', 4444, :async => true)
+    FakeNoeqd.stop
+    assert_raises(Errno::EPIPE) { noeq.request_id }
+  end
+
+  private
+
+  def expected_id
+    144897448664367104
+  end
+
+end
+
+class FakeNoeqd
+
+  def self.start(port = 4444)
+    @server = new(port)
+    Thread.new { @server.accept_connections }
+  end
+
+  def self.stop
+    @server.stop
+  end
+
+  def initialize(port)
+    @socket = TCPServer.new(port)
+  end
+
+  def stop
+    @socket.close rescue true
+  end
+
+  def accept_connections
+    while conn = @socket.accept
+      while n = conn.read(1)
+        conn.send "\x02\x02\xC7v<\x80\x00\x00" * n.unpack('c')[0], 0
+      end
+    end
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: noeq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-02 00:00:00.000000000 Z
+date: 2011-12-09 00:00:00.000000000 Z
 dependencies: []
 description: Ruby noeqd GUID client
 email:
@@ -22,8 +22,10 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- TODO
 - lib/noeq.rb
 - noeq.gemspec
+- test/noeq_test.rb
 homepage: http://github.com/titanous/noeq-rb
 licenses: []
 post_install_message: 
@@ -48,4 +50,5 @@ rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: Ruby noeqd GUID client
-test_files: []
+test_files:
+- test/noeq_test.rb