Update the documentation with compression support docs

README.md

@@ -162,6 +162,19 @@ The default consistency level unless you've set it yourself is `:quorum`.
 
 Consistency is ignored for `USE`, `TRUNCATE`, `CREATE` and `ALTER` statements, and some (like `:any`) aren't allowed in all situations.
 
+## Compression
+
+The CQL protocol supports frame compression, which can give you a performance boost if your requests or responses are big. To enable it you can pass a compressor object when you connect.
+
+Cassandra currently supports two compression algorithms: Snappy and LZ4. Support for Snappy compression ships with cql-rb, but in order to use it you will have to install the [snappy](http://rubygems.org/gems/snappy) gem separately. Once it's installed you can enable compression like this:
+
+```ruby
+require 'cql/compression/snappy_compressor'
+
+compressor = Cql::Compression::SnappyCompressor.new
+client = Cql::Client.connect(hosts: %w[localhost], compressor: compressor)
+```
+
 # CQL3
 
 This is just a driver for the Cassandra native CQL protocol, it doesn't really know anything about CQL. You can run any CQL3 statement and the driver will return whatever Cassandra replies with.
@@ -232,7 +245,6 @@ Prereleases will be stable, in the sense that they will have finished and proper
 
 # Known bugs & limitations
 
-* No support for compression.
 * JRuby 1.6 is not officially supported, although 1.6.8 should work, if you're stuck in JRuby 1.6.8 try and see if it works for you.
 * Large results are buffered in memory until the whole response has been loaded, the protocol makes it possible to start to deliver rows to the client code as soon as the metadata is loaded, but this is not supported yet.
 * There is no cluster introspection utilities (like the `DESCRIBE` commands in `cqlsh`).

lib/cql/client.rb

@@ -89,6 +89,9 @@ module Client
     # @option options [Integer] :default_consistency (:quorum) The consistency
     #   to use unless otherwise specified. Consistency can also be specified on
     #   a per-request basis.
+    # @option options [Cql::Compression::Compressor] :compressor An object that
+    #   can compress and decompress frames. By specifying this option frame
+    #   compression will be enabled.
     # @option options [Integer] :logger If you want the client to log
     #   significant events pass an object implementing the standard Ruby logger
     #   interface (e.g. quacks like `Logger` from the standard library) with

lib/cql/compression.rb

@@ -3,5 +3,51 @@
 module Cql
   module Compression
     CompressionError = Class.new(CqlError)
+
+    # @note Compressors given to {Cql::Client.connect} as the `:compressor`
+    #   option don't need to be subclasses of this class, but need to
+    #   implement the same methods. This class exists only for documentation
+    #   purposes.
+    class Compressor
+      # @!method algorithm
+      #
+      # Returns the name of the algorithm this compressor supports,
+      # e.g. "snappy" or "lz4".
+      #
+      # @return [String]
+
+      # @!method compress?
+      #
+      # Before compressing a frame the compressor will be asked if it wants
+      # to compress it or not. One reason it could say no is if the frame is
+      # small enough that compression would be unlikely to decrease its size.
+      #
+      # If your operations consist mostly of small prepared statement
+      # executions it might not be useful to compress the frames being sent
+      # _to_ Cassandra, but enabling compression can still be useful on the
+      # frames coming _from_ Cassandra. Making this method always return
+      # false disables request compression, but will still make the client
+      # tell Cassandra that it supports compressed frames.
+      #
+      # The bytes given to {#compress?} are the same as to {#compress}
+      #
+      # @param [String] frame the bytes of the frame to be compressed
+      # @return [true, false]
+
+      # @!method compress
+      #
+      # Compresses the raw bytes of a frame.
+      #
+      # @param [String] frame the bytes of the frame to be compressed
+      # @return [String] the compressed frame
+
+      # @!method decompress
+      #
+      # Decompresses the raw bytes of a compressed frame.
+      #
+      # @param [String] compressed_frame the bytes of the compressed
+      #   frame to be uncompressed
+      # @return [String]
+    end
   end
 end

lib/cql/compression/snappy_compressor.rb

@@ -9,14 +9,23 @@
 module Cql
   module Compression
 
+    # A compressor that uses the Snappy compression library.
+    #
+    # @note This compressor requires the [snappy](http://rubygems.org/gems/snappy)
+    #   gem (v0.0.10 or later for JRuby support).
     class SnappyCompressor
+      # @return [String]
       attr_reader :algorithm
 
+      # @param [Integer] min_size (64) Don't compress frames smaller than
+      #   this size (see {#compress?}).
       def initialize(min_size=64)
         @algorithm = 'snappy'.freeze
         @min_size = min_size
       end
 
+      # @return [true, false] will return false for frames smaller than the
+      #   `min_size` given to the constructor.
       def compress?(str)
         str.bytesize > @min_size
       end