Formalize Redis::Client's public API.

Author: djanowski

lib/redis/client.rb

@@ -3,6 +3,28 @@
 require "cgi"
 
 class Redis
+  # Redis::Client handles the connection to Redis, sending and receiving commands.
+  #
+  # Usage:
+  #
+  #   client = Redis::Client.new
+  #
+  #   client.call(["PING"])
+  #   => "PONG"
+  #
+  #   client.call(["SET", "key", "value"])
+  #   => "OK"
+  #
+  #   client.call(["INCR", "key"])
+  #   => 1
+  #
+  # It provides an API for command pipelining:
+  #
+  #   client.queue(["SET", "key", "value"])
+  #   client.queue(["GET", "key"])
+  #   client.commit
+  #   => ["OK", "value"]
+  #
   class Client
 
     DEFAULTS = {
@@ -84,6 +106,47 @@ def initialize(options = {})
       else
         @connector = Connector.new(@options)
       end
+
+      @queue = []
+    end
+
+    # Sends a command to Redis and returns its reply.
+    #
+    # Replies are converted to Ruby objects according to the RESP protocol, so
+    # you can expect a Ruby array, integer or nil when Redis sends one. Higher
+    # level transformations, such as converting an array of pairs into a Ruby
+    # hash, are up to consumers.
+    #
+    # Redis error replies are raised as Ruby exceptions.
+    def call(command, &block)
+      reply = process([command]) { read }
+      raise reply if reply.is_a?(CommandError)
+
+      if block
+        block.call(reply)
+      else
+        reply
+      end
+    end
+
+    # Queues a command for pipelining.
+    #
+    # Commands in the queue are executed with the Redis::Client#commit method.
+    #
+    # See http://redis.io/topics/pipelining for more details.
+    #
+    def queue(command)
+      @queue << command
+    end
+
+    # Sends all commands in the queue.
+    #
+    # See http://redis.io/topics/pipelining for more details.
+    #
+    def commit
+      call_pipelined(@queue)
+    ensure
+      @queue.clear
     end
 
     def connect
@@ -108,17 +171,6 @@ def location
       path || "#{host}:#{port}"
     end
 
-    def call(command, &block)
-      reply = process([command]) { read }
-      raise reply if reply.is_a?(CommandError)
-
-      if block
-        block.call(reply)
-      else
-        reply
-      end
-    end
-
     def call_loop(command)
       error = nil
 
@@ -174,15 +226,21 @@ def call_pipelined(commands)
       reconnect = @reconnect
 
       begin
+        exception = nil
+
         process(commands) do
           result[0] = read
 
           @reconnect = false
 
           (commands.size - 1).times do |i|
-            result[i + 1] = read
+            reply = read
+            result[i + 1] = reply
+            exception = reply if exception.nil? && reply.is_a?(CommandError)
           end
         end
+
+        raise exception if exception
       ensure
         @reconnect = reconnect
       end

test/client_test.rb

@@ -0,0 +1,59 @@
+require_relative "helper"
+
+class TestClient < Test::Unit::TestCase
+
+  include Helper::Client
+
+  def test_call
+    result = r.client.call(["PING"])
+    assert_equal result, "PONG"
+  end
+
+  def test_call_with_arguments
+    result = r.client.call(["SET", "foo", "bar"])
+    assert_equal result, "OK"
+  end
+
+  def test_call_integers
+    result = r.client.call(["INCR", "foo"])
+    assert_equal result, 1
+  end
+
+  def test_call_raise
+    assert_raises(Redis::CommandError) do
+      r.client.call(["INCR"])
+    end
+  end
+
+  def test_queue_commit
+    r.client.queue(["SET", "foo", "bar"])
+    r.client.queue(["GET", "foo"])
+    result = r.client.commit
+
+    assert_equal result, ["OK", "bar"]
+  end
+
+  def test_commit_raise
+    r.client.queue(["SET", "foo", "bar"])
+    r.client.queue(["INCR"])
+
+    assert_raise(Redis::CommandError) do
+      r.client.commit
+    end
+  end
+
+  def test_queue_after_error
+    r.client.queue(["SET", "foo", "bar"])
+    r.client.queue(["INCR"])
+
+    assert_raise(Redis::CommandError) do
+      r.client.commit
+    end
+
+    r.client.queue(["SET",  "foo", "bar"])
+    r.client.queue(["INCR", "baz"])
+    result = r.client.commit
+
+    assert_equal result, ["OK", 1]
+  end
+end