fraggle 3.0.0 → 4.0.0.pre.1

data/README.md

@@ -1,7 +1,6 @@
-# Fraggle (v3.0.0 is compatible with Doozer 0.6)
+# Fraggle (v4.0.0.pre.1 is compatible with Doozer 0.6)
 
 Fraggle currently is only a raw interface to Doozer 0.6.
-Sugar for `WALK`, `GETDIR`, etc are to come in v3.0.0.
 
 **An EventMachine based Doozer client**
 
@@ -11,31 +10,42 @@ Sugar for `WALK`, `GETDIR`, etc are to come in v3.0.0.
 
 ## Use
 
+*Connecting to a cluster*
+
+Use `Fraggle.connect`.  It takes an optional [doozer uri][] (String).  If no
+parameters are given, it will use the DOOZER_URI` environment variable if
+present, otherwise it will default to the uri containing the default doozer
+addresses with IP 127.0.0.1 and ports 8046, 8041, 8042, 8043.
+
+*simple example*
+
     require 'rubygems'
     require 'eventmachine'
     require 'fraggle'
 
-    EM.start do
+    EM.run do
       # In the event of a lost connection, fraggle will attempt
       # other doozers until one accepts or it runs out of options; A NoAddrs
       # exception will be raised if that later happens.
-      c = Fraggle.connect "doozerd://127.0.0.1:8046"
 
-      req = c.get("/foo") do |e|
-        if e.ok?
-          e.value    # => nil
-          e.rev      # => 0
-          e.missing? # => true
-        else
-          e.err_code # => Fraggle::<CONST>
-          e.err_detail # => "bad path" or something
-        end
-      end
+      c = Fraggle.connect
 
       c.rev do |v|
+        c.get(v.rev, "/foo") do |e|
+          p [:get, e]
+          if e.ok?
+            e.value    # => nil
+            e.rev      # => 0
+            e.missing? # => true
+          else
+            e.err_code # => nil
+            e.err_detail # => nil
+          end
+        end
+
         ## Obtain the current revision the store is at and watch from then on for
         ## any SET or DEL to /foo.
-        c.wait("/foo", v.rev) do |e|
+        c.wait(v.rev, "/foo") do |e|
           # The event has:
           # ------------------------
           e.err_code   # => nil
@@ -45,11 +55,13 @@ Sugar for `WALK`, `GETDIR`, etc are to come in v3.0.0.
           e.rev        # => 123
           e.set?       # => true
           e.del?       # => false
+
+          p [:wait, e]
         end
       end
 
       ## Setting a key (this will trigger the watch above)
-      req = c.set("/foo", "zomg!", 0) do |e|
+      c.set(Fraggle::Clobber, "/foo", "zomg!") do |e|
         # Success!
         case e.err_code
         when Fraggle::REV_MISMATCH
@@ -57,7 +69,7 @@ Sugar for `WALK`, `GETDIR`, etc are to come in v3.0.0.
         when nil
           # Success!
         else
-          fail "something bad happened"
+          fail "something bad happened: " + e.inspect
         end
       end
 
@@ -70,17 +82,17 @@ the most up-to-date data.   If you need to do multiple reads at certain
 point in time for consistency, use the `rev` command.
 
     c.rev do |v|
-      c.get("/a", v.rev) { ... }
-      c.get("/b", v.rev) { ... }
-      c.get("/c", v.rev) { ... }
+      c.get(v.rev, "/a") { ... }
+      c.get(v.rev, "/b") { ... }
+      c.get(v.rev, "/c") { ... }
     end
 
 This also means you can go back in time or into the future!
 
     # This will not yield until the data store is at revision 100,000
-    c.get("/a", 100_000) { ... }
+    c.get(100_000, "/a") { ... }
 
-NOTE:  Doozer's data store is a persistent data structure.  You can reference the
+NOTE:  Doozer's data store is a [persistent data structure][pd].  You can reference the
 stores history as far back as it is configured to hold it.  The default is
 360,000 revisions.  See [data model][] for more information.
 
@@ -103,11 +115,54 @@ stores history as far back as it is configured to hold it.  The default is
   You will have to handle these yourself because Fraggle cannot know whether or
   not it's safe to retry on your behalf.
 
+## Commands
+
+Each command behaves according to the [proto spec][], respectively.
+Their `blk`s are called with one parameter, a `Fraggle::Response`, when a response is
+returned from the server.
+
+`set(rev, path, value, &blk)`
+
+`del(rev, path, &blk)`
+
+`get(rev, path, &blk)`
+
+`getdir(rev, path, offset, &blk)`
+
+`walk(rev, path, offset, &blk)`
+
+`wait(rev, path, &blk)`
+
+`rev(&blk)`
+
+`stat(rev, path, &blk)`
+
+## Sugar commands
+
+`watch(rev, path, &blk)`
+
+Watches `path` (a glob pattern) for changes, from `rev` in history on.  Its
+`blk` is called with a `Fraggle::Response` for each event.
+
+`getdir_all(rev, path, off=0, lim=MaxInt64, ents=[], &blk)`
+
+Behaves like `getdir` but collects `ents`, starting at `off` until all or `lim`
+entries are read. When done `blk` is called with the result as the first
+parameter or an error as the second.  Depending on the response, one or the
+other will be set and the other with be `nil`.
+
+`walk_all(rev, path, off=0, lim=MaxInt64, ents=[], &blk)`
+
+Behaves like `walk` but collects `ents`, starting at `off` until all or `lim`
+entries are read. When done `blk` is called with the result as the first
+parameter or an error as the second.  Depending on the response, one or the
+other will be set and the other with be `nil`.
+
 ## Dev
 
 **Clone**
 
-    $ git clone http://github.com/bmizerany/fraggle.git
+    $ git clone http://github.com/ha/fraggle.git
 
 **Test**
 
@@ -121,3 +176,6 @@ Please join the Doozer mailing list for help:
 http://groups.google.com/forum/#!forum/doozer
 
 [data model]: https://github.com/ha/doozerd/blob/master/doc/data-model.md
+[doozer uri]: https://github.com/ha/doozerd/blob/master/doc/uri.md
+[proto spec]: https://github.com/ha/doozerd/blob/master/doc/proto.md
+[pd]: http://en.wikipedia.org/wiki/Persistent_data_structure

data/example/getdir_all.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'fraggle'
+
+EM.run do
+  c = Fraggle.connect
+
+  c.rev do |v|
+    # Valid
+    req = c.getdir_all("/ctl/node", v.rev) do |ents, err|
+      if err
+        p [:err, err]
+      else
+        ents.each do |e|
+          puts File.join(req.path, e.path)
+        end
+      end
+    end
+
+    # Limit 0 return nothing
+    c.getdir_all("/ctl/node", v.rev, 0, 0) do |ents, err|
+      p [:ret, ents, err]
+    end
+
+    # Error
+    c.getdir_all("/nothere", v.rev) do |ents, err|
+      p [:ret, ents, err]
+    end
+  end
+end

data/example/readme.rb

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'eventmachine'
+require 'fraggle'
+
+EM.run do
+  # In the event of a lost connection, fraggle will attempt
+  # other doozers until one accepts or it runs out of options; A NoAddrs
+  # exception will be raised if that later happens.
+
+  c = Fraggle.connect
+
+  c.rev do |v|
+    c.get(v.rev, "/foo") do |e|
+      p [:get, e]
+      if e.ok?
+        e.value    # => nil
+        e.rev      # => 0
+        e.missing? # => true
+      else
+        e.err_code # => nil
+        e.err_detail # => nil
+      end
+    end
+
+    ## Obtain the current revision the store is at and watch from then on for
+    ## any SET or DEL to /foo.
+    c.wait(v.rev, "/foo") do |e|
+      # The event has:
+      # ------------------------
+      e.err_code   # => nil
+      e.err_detail # => nil
+      e.path       # => "/foo"
+      e.value      # => "zomg!"
+      e.rev        # => 123
+      e.set?       # => true
+      e.del?       # => false
+
+      p [:wait, e]
+    end
+  end
+
+  ## Setting a key (this will trigger the watch above)
+  c.set(0, "/foo", "zomg!") do |e|
+    # Success!
+    case e.err_code
+    when Fraggle::REV_MISMATCH
+      p :not_it
+    when nil
+      # Success!
+      p :it
+    else
+      fail "something bad happened: " + e.inspect
+    end
+  end
+
+end

data/example/walk_all.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'fraggle'
+
+EM.run do
+  c = Fraggle.connect
+
+  c.rev do |v|
+    # Valid
+    req = c.walk_all("/ctl/node/**", v.rev) do |ents, err|
+      if err
+        p [:err, err]
+      else
+        ents.each do |e|
+          puts File.join(req.path, e.path) + "=" + e.value
+        end
+      end
+    end
+
+    # Limit 0 return nothing
+    c.walk_all("/ctl/node/**", v.rev, 0, 0) do |ents, err|
+      p [:ret, ents, err]
+    end
+
+    # Error
+    c.walk_all("/nothere", v.rev) do |ents, err|
+      p [:ret, ents, err]
+    end
+  end
+end

data/example/watch.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'fraggle'
+
+EM.run do
+  c = Fraggle.connect
+
+  c.rev do |v|
+    c.watch("/ctl/node/**", v.rev) do |e|
+      p e
+    end
+  end
+end

data/lib/fraggle.rb

@@ -1,6 +1,9 @@
 require 'fraggle/client'
 
 module Fraggle
+  include Response::Err
+
+  Clobber = Client::MaxInt64
 
   DEFAULT_URI = "doozer:?" + [
     "ca=127.0.0.1:8046",

data/lib/fraggle/client.rb

@@ -6,6 +6,8 @@ module Fraggle
   class Client
     include Request::Verb
 
+    MaxInt64 = 1<<63 - 1
+
     class NoMoreAddrs < StandardError
     end
 
@@ -22,7 +24,7 @@ module Fraggle
       cn.addr
     end
 
-    def set(path, value, rev, &blk)
+    def set(rev, path, value, &blk)
       req = Request.new
       req.verb  = SET
       req.rev   = rev
@@ -32,7 +34,7 @@ module Fraggle
       idemp(req, &blk)
     end
 
-    def get(path, rev=nil, &blk)
+    def get(rev, path, &blk)
       req = Request.new
       req.verb = GET
       req.rev  = rev
@@ -41,7 +43,7 @@ module Fraggle
       resend(req, &blk)
     end
 
-    def del(path, rev, &blk)
+    def del(rev, path, &blk)
       req = Request.new
       req.verb = DEL
       req.rev  = rev
@@ -50,7 +52,7 @@ module Fraggle
       idemp(req, &blk)
     end
 
-    def getdir(path, rev=nil, offset=nil, &blk)
+    def getdir(rev, path, offset, &blk)
       req = Request.new
       req.verb   = GETDIR
       req.rev    = rev
@@ -60,7 +62,7 @@ module Fraggle
       resend(req, &blk)
     end
 
-    def walk(path, rev=nil, offset=nil, &blk)
+    def walk(rev, path, offset, &blk)
       req = Request.new
       req.verb   = WALK
       req.rev    = rev
@@ -70,7 +72,7 @@ module Fraggle
       resend(req, &blk)
     end
 
-    def wait(path, rev=nil, &blk)
+    def wait(rev, path, &blk)
       req = Request.new
       req.verb = WAIT
       req.rev  = rev
@@ -86,7 +88,7 @@ module Fraggle
       resend(req, &blk)
     end
 
-    def stat(path, rev=nil, &blk)
+    def stat(rev, path, &blk)
       req = Request.new
       req.rev  = rev
       req.verb = STAT
@@ -95,19 +97,51 @@ module Fraggle
       resend(req, &blk)
     end
 
+    def watch(rev, path, &blk)
+      wait(rev, path, rev) do |e|
+        blk.call(e)
+        if e.ok?
+          watch(rev, path, e.rev+1, &blk)
+        end
+      end
+    end
+
+    def getdir_all(rev, path, off=0, lim=MaxInt64, ents=[], &blk)
+      all(:getdir, rev, path, off, lim, ents, &blk)
+    end
+
+    def walk_all(rev, path, off=0, lim=MaxInt64, ents=[], &blk)
+      all(:walk, rev, path, off, lim, ents, &blk)
+    end
+
+    def all(m, rev, path, off, lim, ents=[], &blk)
+      if lim == 0
+        cn.next_tick { blk.call([], nil) }
+        return
+      end
+
+      __send__(m, rev, path, off) do |e|
+        case e.err_code
+        when nil
+          ents << e
+          all(m, rev, path, off+1, lim-1, ents, &blk)
+        when Fraggle::Response::Err::RANGE
+          blk.call(ents, nil)
+        else
+          blk.call(nil, e)
+        end
+      end
+    end
+
     # Sends a request to the server.  Returns the request with a new tag
     # assigned.
     def send(req, &blk)
       cb = Proc.new do |e|
         log.debug("response: #{e.inspect} for #{req.inspect}")
 
-        case true
-        when e.disconnected?
-          # If we haven't already reconnected, do so.
-          if cn.err?
-            log.error("conn err: #{req.inspect}")
-            reconnect!
-          end
+        if e.disconnected? && cn.err?
+          log.error("conn err: #{req.inspect}")
+          reconnect!
         end
 
         blk.call(e)

data/lib/fraggle/version.rb

@@ -1,3 +1,3 @@
 module Fraggle
-  VERSION = "3.0.0"
+  VERSION = "4.0.0.pre.1"
 end

data/test/fraggle_client_test.rb

@@ -150,7 +150,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :value => "bar"
     }
 
-    assert_verb exp, :set, "/foo", "bar", 0
+    assert_verb exp, :set, 0, "/foo", "bar"
   end
 
   def test_get
@@ -160,7 +160,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :path => "/foo"
     }
 
-    assert_verb exp, :get, "/foo", 0
+    assert_verb exp, :get, 0, "/foo"
   end
 
   def test_del
@@ -170,7 +170,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :path => "/foo"
     }
 
-    assert_verb exp, :del, "/foo", 0
+    assert_verb exp, :del, 0, "/foo"
   end
 
   def test_getdir
@@ -181,7 +181,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :offset => 0
     }
 
-    assert_verb exp, :getdir, "/foo", 0, 0
+    assert_verb exp, :getdir, 0, "/foo", 0
   end
 
   def test_rev
@@ -199,7 +199,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :path => "/foo"
     }
 
-    assert_verb exp, :stat, "/foo", 0
+    assert_verb exp, :stat, 0, "/foo"
   end
 
   def test_walk
@@ -210,7 +210,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :offset => 0
     }
 
-    assert_verb exp, :walk, "/foo/*", 0, 0
+    assert_verb exp, :walk, 0, "/foo/*", 0
   end
 
   def test_wait
@@ -220,7 +220,7 @@ class FraggleClientTest < Test::Unit::TestCase
       :path => "/foo/*"
     }
 
-    assert_verb exp, :wait, "/foo/*", 0
+    assert_verb exp, :wait, 0, "/foo/*"
   end
 
 end

metadata

@@ -1,13 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: fraggle
 version: !ruby/object:Gem::Version 
-  hash: 7
-  prerelease: 
+  hash: 1923831851
+  prerelease: 6
   segments: 
-  - 3
+  - 4
   - 0
   - 0
-  version: 3.0.0
+  - pre
+  - 1
+  version: 4.0.0.pre.1
 platform: ruby
 authors: 
 - Blake Mizerany
@@ -15,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-29 00:00:00 -07:00
+date: 2011-05-02 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,6 +79,10 @@ files:
 - README.md
 - Rakefile
 - bench/gets.rb
+- example/getdir_all.rb
+- example/readme.rb
+- example/walk_all.rb
+- example/watch.rb
 - fraggle.gemspec
 - lib/fraggle.rb
 - lib/fraggle/client.rb
@@ -110,12 +116,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: fraggle