cassie 1.0.0.alpha.10 → 1.0.0.alpha.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fec7a911c85e20f50813efaa558b5d0874d22f81
-  data.tar.gz: 9b96499ef12e8544d238af49185afdf38eb762e1
+  metadata.gz: 51aee51ca2bee455d530c72090b9f44c52f9bd76
+  data.tar.gz: 49525a14eb23b418fae95415c63ef6cfbe12eabb
 SHA512:
-  metadata.gz: 5940e76a95f2414c6268d474edea614199c4313e17d0902e3be82a16d4641e9fd2e94aa0cdb22d33825dffe7bf5e5f5ce13c70a159c8154e70c6bec944c3e1a8
-  data.tar.gz: 6a774ce27b9934ac5023b2abd081c88a3b737f92833328866fe3ea0ee3a45fac728ebc06e521e29f06fb9a8417bbc831dde021a72ace61d9475fb0a72308c828
+  metadata.gz: 9349821c15b7c90df9ebbdb43577477b3c0fd549c2d10c9bc29b20286e773b2ccd978fddc8f44e8a4634ccd3def35f326901d19a4a5aaeaa70caf7b91e875816
+  data.tar.gz: ad8dc12ebfc74ae8719919894939a952a0dbd31a2b2095af436d5c2b34d4e23322abd79e5a854321b3ec8a5f0b2592e257086933daef483cca3d89d8fd8f5877

data/bin/cassie

@@ -0,0 +1,29 @@
+#! ruby
+require_relative '../lib/cassie/configuration/generator'
+
+def color(message)
+  "\e[1;31m#{message}\e[0m"
+end
+
+def generate_config
+  opts = {}
+  if ARGV[1]
+    opts[:destination_path] = if ARGV[1][0] == "/"
+      # cassie configuration:generate /usr/var/my_config_dir/cassandra_db.yml
+      ARGV[1]
+    else
+      # cassie configuration:generate my_config_dir/cassandra_db.yml
+      File.join(Dir.pwd, ARGV[1])
+    end
+  end
+  opts[:app_name]         = ARGV[2] if ARGV[2]
+
+  Cassie::Configuration::Generator.new(opts).save
+end
+
+case ARGV[0]
+when "configuration:generate"
+  generate_config
+else
+  puts color("`#{ARGV[0]}` is not a supported command. Did you mean `cassie configuration:generate`?")
+end

data/lib/cassie/configuration/README.md

@@ -0,0 +1,57 @@
+# Cassie Configuration
+
+Cassie provides cluster configuration storage and retrieval.
+
+`Cassie` extends `Configuration::Core`, providing functionality to act as a configuration handler.
+
+```ruby
+Cassie.env
+=> "development"
+
+Cassie.configurations
+=> {"development"=>{"hosts"=>["127.0.0.1"], "port"=>9042, "reconnection_policy"=>nil, "keyspace"=>"my_app_development"}, "test"=>{"hosts"=>["127.0.0.1"], "port"=>9042, "idle_timeout"=>"nil", "keyspace"=>"my_app_test"}, "production"=>{"hosts"=>["cass1.my_app.biz", "cass2.my_app.biz", "cass3.my_app.biz"], "port"=>9042, "keyspace"=>"my_app_production"}}
+
+Cassie.configuration
+=> {"hosts"=>["127.0.0.1"], "port"=>9042, "reconnection_policy"=>nil, "keyspace"=>"my_app_development"}
+
+Cassie.keyspace
+=> "my_app_development"
+```
+
+The env supports loading from the environment, by default, as follows:
+```
+ENV["CASSANDRA_ENV"] || ENV["RACK_ENV"] || "development"
+```
+It may also explicitly be set via `Cassie.env=`.
+
+#### Usage
+
+Cassie also acts as a connection handler. It uses the above configuration functionality to instantiate a `Cassandra::Cluster` using the desired configuration and connect `Cassandra::Sessions`.
+
+See the [Connection README](./lib/cassie/connection_hanlder/README.md#readme) for more on features and usage.]
+
+#### Advanced / Manual Usage
+
+A YAML backend is provided by default. Run `cassie configuration:generate` to generate the configuration file. The default location for these cluster configurations is `config/cassandra.yml`. This is configurable.
+
+```ruby
+$ cassie configuration:generate cassandra_clusters.yml
+$ irb
+irb(main):001:0> require 'cassie'
+=> true
+irb(main):002:0> Cassie.paths
+=> {"cluster_configurations"=>"config/cassandra.yml"}
+irb(main):003:0> Cassie.paths["cluster_configurations"] = 'cassandra_clusters.yml'
+=> "cassandra_clusters.yml"
+irb(main):004:0> Cassie.configurations
+=> {"development"=>{"hosts"=>["127.0.0.1"], "port"=>9042, "reconnection_policy"=>nil, "keyspace"=>"my_app_development"}, "test"=>{"hosts"=>["127.0.0.1"], "port"=>9042, "idle_timeout"=>"nil", "keyspace"=>"my_app_test"}, "production"=>{"hosts"=>["cass1.my_app.biz", "cass2.my_app.biz", "cass3.my_app.biz"], "port"=>9042, "keyspace"=>"my_app_production"}}
+irb(main):005:0>
+```
+
+`configurations`, `env`, `configuration` and `keyspace` may be set explicitly as well.
+
+```
+Cassie.configuration = {"hosts"=>["localhost"], "port"=>9042, "keyspace"=> 'my_default_keyspace'}
+```
+
+> *Note:* Setting the `configuration` explicitly naturally means that `configurations` and `env` will no longer have functional meaning.

data/lib/cassie/configuration/core.rb

@@ -0,0 +1,53 @@
+require_relative 'loading'
+
+module Cassie::Configuration
+  #TODO: proper rdoc
+  # Extend a class with Core to enable configuration management
+  module Core
+    include Loading
+
+    attr_writer :keyspace
+
+    def self.extended(extender)
+      extender.paths["cluster_configurations"] = "config/cassandra.yml"
+    end
+
+    def env
+      @env ||= ActiveSupport::StringInquirer.new(ENV["CASSANDRA_ENV"] || ENV["RACK_ENV"] || "development")
+    end
+
+    def env=(val)
+      @env = ActiveSupport::StringInquirer.new(val)
+    end
+
+    def paths
+      @paths ||= {}.with_indifferent_access
+    end
+
+    def configurations
+      @configurations ||= cluster_configurations
+    end
+
+    def configurations=(val)
+      if val && defined?(@configuration)
+        puts "WARNING:\n `#{self}.configuration` as been set explicitly. Setting `configurations` will have no effect."
+      end
+      @configurations = val
+    end
+
+    def configuration
+      return @configuration if defined?(@configuration)
+      configurations[env]
+    end
+
+    def configuration=(val)
+      @configuration = val
+    end
+
+    def keyspace
+      return @keyspace if defined?(@keyspace)
+      @keyspace = configuration[:keyspace]
+    end
+
+  end
+end

data/lib/cassie/configuration/generator.rb

@@ -0,0 +1,55 @@
+require "erb"
+
+module Cassie
+  module Configuration
+    class Generator
+      include ERB::Util
+      attr_accessor :app_name,
+                    :template_path,
+                    :destination_path
+
+      def initialize(opts={})
+        @app_name = opts.fetch(:app_name, default_app_name)
+        @template_path = opts.fetch(:template_path, default_template_path)
+        @destination_path = opts.fetch(:destination_path, default_destination_path)
+      end
+
+      def render
+        ERB.new(template).result(binding)
+      end
+
+      def save
+        File.open(destination_path, "w+") do |f|
+          f.write(render)
+        end
+      end
+
+      protected
+
+      def template
+        File.new(template_path).read
+      end
+
+      def default_app_name
+        "my_app"
+      end
+
+      def default_template_path
+        File.expand_path("../templates/cassandra.yml", __FILE__)
+      end
+
+      def default_destination_path
+        Dir.mkdir(config_dir) unless File.directory?(config_dir)
+        File.join(root, "config/cassandra.yml")
+      end
+
+      def config_dir
+        File.join(root, "config")
+      end
+
+      def root
+        Dir.pwd
+      end
+    end
+  end
+end

data/lib/cassie/configuration/loading.rb

@@ -0,0 +1,42 @@
+module Cassie::Configuration
+  module Loading
+
+    def cluster_configurations
+      path = paths["cluster_configurations"]
+
+      file = begin
+        File.new(path)
+      rescue StandardError
+        raise MissingClusterConfigurations.new(path)
+      end
+
+      require "yaml"
+      require "erb"
+
+      hash = YAML.load(ERB.new(file.read).result) || {}
+      hash.with_indifferent_access
+    rescue StandardError => e
+      raise e, "Cannot load Cassandra cluster configurations:\n#{e.message}", e.backtrace
+    end
+  end
+
+  class MissingClusterConfigurations < StandardError
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      super(build_message)
+    end
+
+    def build_message
+      msg = "Could not load cassandra cluster configurations. "
+      msg += "No cluster configurations exists at #{path}.\n"
+      msg += generation_instructions
+      msg += ", or configure the correct path via Cassie::Configuration.paths['cluster_configurations'] = <path>."
+    end
+
+    def generation_instructions
+      "Generate #{path} by running `cassie configuration:generate` or `cassie configuration:generate <relative or absolute path>.yml`"
+    end
+  end
+end

data/lib/cassie/configuration/templates/cassandra.yml

@@ -0,0 +1,30 @@
+# Generated and used by Cassie::Configuration.
+#
+# Per-enviornment options are passed to `cassandra-driver` during
+# cluster creation and used to determine default keyspace for session creation.
+# See valid options and values for cluster configuration at:
+# http://datastax.github.io/ruby-driver/api/#cluster-class_method
+
+development:
+  hosts:
+    - 127.0.0.1
+  port: 9042
+  reconnection_policy: <%%= Cassandra::Reconnection::Policies::Exponential.new(0.5, 60, 2) %>
+  keyspace: <%=app_name%>_development
+
+test:
+  hosts:
+    - 127.0.0.1
+  port: 9042
+  idle_timeout: nil
+  keyspace: <%=app_name%>_test
+
+production:
+  hosts:
+    - cass1.<%=app_name%>.biz
+    - cass2.<%=app_name%>.biz
+    - cass3.<%=app_name%>.biz
+  port: 9042
+#  username: 'cassandra_web_server_user'
+#  password: 'cassandra_web_server_password'
+  keyspace: <%=app_name%>_production

data/lib/cassie/configuration.rb

@@ -0,0 +1,9 @@
+require 'active_support/core_ext/hash/indifferent_access'
+
+module Cassie
+  module Configuration
+    require_relative 'configuration/generator'
+    require_relative 'configuration/core'
+
+  end
+end

data/lib/cassie/connection.rb

@@ -0,0 +1,47 @@
+module Cassie
+  #TODO: proper rdoc
+  # include to give #session and #keyspace
+  # convenience methods
+  module Connection
+
+    extend ActiveSupport::Concern
+
+    included do
+      attr_writer :keyspace
+    end
+
+    module ClassMethods
+      def keyspace(val=NilClass)
+        # support DSL style
+        # class Foo
+        #   include Cassie::Connection
+        #   keyspace :foo
+        # end
+        if val == NilClass
+          # regular getter behavior
+          return @keyspace if defined?(@keyspace)
+          # fall back to global default when not
+          # defined for class
+          Cassie.keyspace
+        else
+          # DSL style set
+          self.keyspace = val
+        end
+      end
+
+      def keyspace=(val)
+        #support Class.keyspace = :foo
+        @keyspace = val
+      end
+    end
+
+    def keyspace
+      return @keyspace if defined?(@keyspace)
+      self.class.keyspace
+    end
+
+    def session
+      Cassie.session(keyspace)
+    end
+  end
+end

data/lib/cassie/connection_handler/README.md

@@ -0,0 +1,123 @@
+# Cassie Connection Handling
+
+Cassie provides cluster and session connection handling that adheres to `cassandra-driver` best practices:
+  * Maintains 1 `Cassandra::Cluster` instance
+  * Maintains 1 `Cassandra::Session` per keyspace (or less)
+
+Cassie also provides a `Connection` module to allow easy integration of connection handling into application classes.
+
+
+#### Core functionality
+
+`Cassie` extends `ConnectionHandler`, providing functionality to act as a connection handler using its `configuration` and `keyspace` attributes.
+
+```ruby
+Cassie.cluster
+=> #<Cassandra::Cluster:0x3fec245dceb0> # <= cluster instance configured according to `Cassie::configuration`
+
+Cassie.keyspace
+=> "default_keyspace"
+
+Cassie.session
+=> #<Cassandra::Session:0x3fec24b13668>
+
+Cassie.session(nil)
+=> #<Cassandra::Session:0x3fec24b339b8>
+
+Cassie.session('my_other_keyspace')
+=> #<Cassandra::Session:0x3fec24b558a8>
+
+Cassie.sessions
+=> {
+    "default_keyspace"=>#<Cassandra::Session:0x3fec24b13668>,
+    ""=>#<Cassandra::Session:0x3fec24b13668>,
+    "my_other_keyspace" >#<Cassandra::Session:0x3fec24b558a8>
+   }
+
+# Future session retrieval reuses previously connected sessions
+Cassie.session
+=> #<Cassandra::Session:0x3fec24b13668>
+
+Cassie.sessions
+=> {
+    "default_keyspace"=>#<Cassandra::Session:0x3fec24b13668>,
+    ""=>#<Cassandra::Session:0x3fec24b13668>,
+    "my_other_keyspace" >#<Cassandra::Session:0x3fec24b558a8>
+   }
+```
+
+
+#### Mixin functionality
+
+Including `Connection` gives convenience accessors that allow overriding and fallback behavior.
+
+```ruby
+class HelpfulCounter
+  include Cassie::Connection
+
+  def user_count
+    session.execute('SELECT count(*) FROM users WHERE id = ?;').rows.first['count']
+  end
+end
+```
+
+Ignoring the likely irresponsible example query used -- The object falls back to using the `Cassie::keyspace` value by default.
+
+```ruby
+Cassie.keyspace
+=> "default_keyspace"
+
+object = HelpfulCounter.new
+
+object.keyspace
+=> "default_keyspace"
+
+object.user_count
+=> 302525
+```
+
+The keyspace can be set at the class level.
+
+```ruby
+class Analytics::HelpfulCounter
+  include Cassie::Connection
+
+  keyspace :analytics_keyspace
+
+  def user_count
+    session.execute('SELECT count(*) FROM users WHERE id = ?;').rows.first['count']
+  end
+end
+
+Cassie.keyspace
+=> "default_keyspace"
+
+object = Analytics::HelpfulCounter.new
+
+object.keyspace
+=> "analytics_keyspace"
+
+object.user_count
+=> 300715
+
+```
+
+Or at the object level
+
+```
+Cassie.keyspace
+=> "default_keyspace"
+
+object = HelpfulCounter.new
+
+object.keyspace
+=> "default_keyspace"
+
+object.user_count
+=> 302525
+
+object.keyspace = "analytics_keyspace"
+=> "analytics_keyspace"
+
+object.user_count
+=> 300715

data/lib/cassie/connection_handler/cluster.rb

@@ -0,0 +1,11 @@
+module Cassie::ConnectionHandler
+  module Cluster
+
+    def cluster
+      # Cassandra::cluster parses suppored
+      # options from the passed hash, no need
+      # to validate/transform ourselves yet
+      @cluster ||= Cassandra.cluster(configuration)
+    end
+  end
+end

data/lib/cassie/connection_handler/sessions.rb

@@ -0,0 +1,18 @@
+module Cassie::ConnectionHandler
+  module Sessions
+
+    def sessions
+      @sessions ||= {}
+    end
+
+    def session(_keyspace=self.keyspace)
+      sessions[_keyspace] || connect(_keyspace)
+    end
+
+    protected
+
+    def connect(_keyspace)
+      @sessions[_keyspace] = cluster.connect(_keyspace)
+    end
+  end
+end

data/lib/cassie/connection_handler.rb

@@ -0,0 +1,17 @@
+module Cassie
+  #TODO: proper rdoc
+  # Assumes module responds to `configuration`, `keyspace`, and `cluster`
+  module ConnectionHandler
+    require_relative 'connection_handler/cluster'
+    require_relative 'connection_handler/sessions'
+
+    include Cluster
+    include Sessions
+
+    def self.extended(extender)
+      #TODO: raise if extender doesn't
+      #      respond to configuration
+      #      and keyspace
+    end
+  end
+end

data/lib/cassie/queries/README.md

@@ -0,0 +1,316 @@
+# Cassie Queries
+
+`cassie` query classes provide query interface that is
+
+* Easy to use
+* Easy to understand (and thus maintain)
+* Easy to test
+* Works well with the data mapper design pattern
+
+### Usage
+
+What you might expect to see:
+
+```
+Cassie.insert(:users_by_username,
+              "id = #{some_id}",
+              username: some_username)
+```
+
+Queries defined on the fly like this tend to create debt for an application in the long term. They:
+  * create gaps in test coverage
+  * resist documentation
+  * resist refactoring
+
+Your application queries represent behavior, `cassie` queries are structured to help you create query classes that are reusable, testable and maintainable, so you can sleep better at night.
+
+```ruby
+# Some PORO user model
+user = User.new(username: username)
+
+MyInsertionQuery.new.insert(user)
+```
+<pre><b>
+(1.2ms) INSERT INTO users_by_username (id, username) VALUES (?, ?); [["uuid()", "eprothro"]]
+</b></pre>
+
+```ruby
+class MyInsertionQuery < Cassie::Query
+
+  insert :users_by_username do |u|
+    u.id,
+    u.username
+  end
+
+  def id
+    "uuid()"
+  end
+end
+```
+
+CQL algebra is less complex than with SQL. So, rather than introducing a query abstraction layer (e.g. something like [arel](https://github.com/rails/arel)), `cassie` queries provide a lightweight CQL DSL to codify your CQL queries.
+
+```sql
+  SELECT *
+  FROM posts_by_author_category
+  WHERE author_id = ?
+  AND category = ?
+  LIMIT 30;
+```
+```ruby
+  select :posts_by_author_category
+  where :author_id, :eq
+  where :category, :eq
+  limit 30
+```
+
+This maintains the clarity of your CQL, allowing you to be expressive, but still use additional features without having get crazy with string manipulation.
+
+#### Dynamic term values
+
+```ruby
+select :posts_by_author
+
+where :user_id, :eq
+```
+
+Defining a CQL relation in a cassie query (the "where") creates a setter and getter for that relation. This allows the term value to be set for a particular query instance.
+
+```ruby
+query.user_id = 123
+query.fetch
+=> [#<Struct user_id=123, id="some post id">]
+```
+
+<pre><b>
+(2.9ms) SELECT * FROM posts_by_author WHERE user_id = ? LIMIT 1; [[123]]
+</b></pre>
+
+These methods are plain old attr_accessors, and may be overriden
+
+```ruby
+select :posts_by_author
+
+where :user_id, :eq
+
+def author=(user)
+  @user_id = user.id
+end
+```
+
+```ruby
+query.author = User.new(id: 123)
+query.fetch
+=> [#<Struct user_id=123, id="some post id">]
+```
+
+<pre><b>
+(2.9ms) SELECT * FROM posts_by_author WHERE user_id = ? LIMIT 1; [[123]]
+</b></pre>
+
+A specific name can be provided for the setter/getter:
+
+```ruby
+select :posts_by_author
+
+where :user_id, :eq, value: :author_id
+```
+
+```ruby
+query.author_id = 123
+query.fetch
+=> [#<Struct user_id=123, id="some post id">]
+```
+
+<pre><b>
+(2.9ms) SELECT * FROM posts_by_author WHERE user_id = ? LIMIT 1; [[123]]
+</b></pre>
+
+#### Conditional relations
+
+```ruby
+  select :posts_by_author_category
+
+  where :author_id, :eq
+  where :category, :eq, if: "category.present?"
+```
+
+or
+
+```ruby
+  select :posts_by_author_category
+
+  where :author_id, :eq
+  where :category, :eq, if: :filter_by_category?
+
+  def filter_by_category?
+    #true or false, as makes sense for your query
+  end
+```
+
+#### Object Mapping
+For Selection Queries, resources are returned as structs by default for manipulation using accessor methods.
+
+```ruby
+UsersByUsernameQuery.new.fetch(username: "eprothro")
+=> [#<Struct id=:123, username=:eprothro>]
+
+UsersByUsernameQuery.new.find(username: "eprothro").username
+=> "eprothro"
+```
+
+Override `build_resource` to construct more useful objects
+
+```
+class UsersByUsernameQuery < Cassie::Query
+
+  select :users_by_username
+
+  where :username, :eq
+
+  def build_resource(row)
+    User.new(row)
+  end
+end
+```
+
+```ruby
+UsersByUsernameQuery.new.find(username: "eprothro")
+=> #<User:0x007fedec219cd8 @id=123, @username="eprothro">
+```
+
+For Data Modification Queries (`insert`, `update`, `delete`), mapping binding values from an object is supported.
+
+```ruby
+class UpdateUserQuery < Cassandra::Query
+
+  update :users_by_id do |q|
+    q.set :phone
+    q.set :email
+    q.set :address
+    q.set :username
+  end
+
+  where :id, :eq
+
+  map_from :user
+```
+
+Allowing you to pass an object to the modification method, and binding values will be retrieved from the object
+
+```ruby
+user
+=> #<User:0x007ff8895ce660 @id=6539, @phone="+15555555555", @email="etp@example.com", @address=nil, @username= "etp">
+UpdateUserQuery.new.update(user)
+```
+
+<pre><b>
+(1.2ms) UPDATE users_by_id (phone, email, address, username) VALUES (?, ?, ?, ?) WHERE id = ?; [["+15555555555", "etp@example.com", nil, "etp", 6539]]
+</b></pre>
+
+#### Cursored paging
+
+Read about [cursored pagination](https://www.google.com/webhp?q=cursored%20paging#safe=off&q=cursor+paging) if unfamiliar with concept and how it optimizes paging through frequently updated data sets and I/O bandwidth.
+
+```ruby
+class MyPagedQuery < Cassie::Query
+
+  select :events_by_user
+
+  where :user_id, :eq
+
+  max_cursor :event_id
+  since_cursor :event_id
+end
+```
+
+```ruby
+# Imagine a set of id's 100 decreasing to 1
+# where the client already has 1-50 in memory.
+
+q = MyPagedQuery.new(page_size: 25, user: current_user)
+
+# fetch 100 - 76
+page_1 = q.fetch(max_event_id: nil, since_event_id: 50)
+q.next_max_event_id
+# => 75
+
+# fetch 75 - 51
+page_2 = q.fetch(max_event_id: q.next_max_event_id, since_event_id: 50)
+q.next_max_id
+# => nil
+```
+
+The `cursor_by` helper can be used as shorthand for defining these relations for which you wish to use cursors.
+```ruby
+class MyPagedQuery < Cassie::Query
+
+  select :events_by_user
+
+  where :user_id, :eq
+
+  cursor_by :event_id
+end
+```
+
+#### Prepared statements
+
+A `Cassie::Query` will use prepared statements by default, cacheing prepared statements across all Cassie::Query objects, keyed by the bound CQL string.
+
+
+To not use prepared statements for a particular query, disable the `.prepare` class option.
+
+```ruby
+class MySpecialQuery < Cassie::Query
+
+  select :users_by_some_value do
+    where :bucket
+    where :some_value, :in
+  end
+
+  # the length of `some_values` that will be passed in
+  # is highly variable, so we don't want to incur the
+  # cost of preparing a statement for each unique length
+  self.prepare = false
+end
+```
+
+```ruby
+query = MySpecialQuery.new
+
+# will not prepare statement
+set_1 = query.fetch([1, 2, 3])
+# will not prepare statement
+set_2 = query.fetch([7, 8, 9, 10, 11, 12])
+```
+
+#### Unbound statements
+
+Cassie Query features are built around bound statements. However, we've tried to keep a simple ruby design in place to make custom behavior easier. If you want to override the assumption of bound statements, simply override `#statement`, returnign something that a `Cassandra::Session` can execute.
+
+```ruby
+class NotSureWhyIWouldDoThisButHereItIsQuery < Cassie::Query
+  def statement
+    "SELECT * FROM users WHERE id IN (1,2,3);"
+  end
+end
+```
+
+#### Logging
+
+Set the log level to debug to log execution details.
+
+```ruby
+Cassie::Queries::Logging.logger.level = Logger::DEBUG
+```
+
+```ruby
+SelectUserByUsernameQuery.new('some_user').execute
+(2.9ms) SELECT * FROM users_by_username WHERE username = ? LIMIT 1; [["some_user"]]
+```
+
+Logs to STDOUT by default. Set any log stream you wish.
+
+```ruby
+  Cassie::Queries::Logging.logger = my_app.config.logger
+```

data/lib/cassie/queries/statement.rb

@@ -1,4 +1,5 @@
 require 'active_support/core_ext/string/filters'
+require 'active_support/hash_with_indifferent_access'
 require_relative 'statement/preparation'
 require_relative 'statement/callbacks'
 require_relative 'statement/limiting'

data/lib/cassie/query.rb

@@ -1,23 +1,12 @@
 module Cassie
-  # Active Support used for
-  #  * include convenience via ActiveSupport::Concern
-  #  * string extensions
-  #  * notification pub/sub
-  #  * log formatting
-  #
-  # We require/autoload extensions only as needed,
-  # this base require has almost no overhead
-  #
-  # http://guides.rubyonrails.org/active_support_core_extensions.html
-  require 'active_support'
-  require 'cassandra'
-  require_relative 'queries/session'
-  require_relative 'queries/statement'
-  require_relative 'queries/instrumentation'
-  require_relative 'queries/logging'
-
+  module Queries
+  end
   class Query
-    include Queries::Session
+    require_relative 'queries/statement'
+    require_relative 'queries/instrumentation'
+    require_relative 'queries/logging'
+
+    include Cassie::Connection
     include Queries::Statement
     include Queries::Instrumentation
     include Queries::Logging
@@ -30,4 +19,4 @@ module Cassie
       super()
     end
   end
-end
+end

data/lib/cassie/testing/README.md

@@ -0,0 +1,58 @@
+# Cassie Test Harnessing
+
+We're all trying to avoid overly integrated tests. When it comes to the persistance layer adapter, that can be tough. Cassie provides a simple test harness to allow you to stub out the `cassie-driver` layer when it makes sense to do so.
+
+### Usage
+Extend a `Cassie::Query` class or object with `Cassie::Testing::Fake::Query` to stub out calls to the `cassandra-driver` (and thus actual persistance layer) in a way that still allows calls to `execute` to occur.
+
+Stubbing an object will only apply to that object, not other objects created from that class.
+
+```ruby
+some_query = SomeQuery.new
+some_query.extend(Cassie::Testing::Fake::Query)
+some_query.session
+=> #<Cassie::Testing::Fake::Session::Session:0x007fd03e29a688>
+
+another_query = SomeQuery.new
+another_query.session
+# => this is not a fake session
+```
+
+Stubbing a class will apply to all objects of that class.
+
+```ruby
+SomeQuery.include(Cassie::Testing::Fake::Query)
+SomeQuery.new.session
+=> #<Cassie::Testing::Fake::Session::Session:0x007fd03e29a688>
+SomeQuery.new.session
+=> #<Cassie::Testing::Fake::Session::Session:0x007fd03e3577a8>
+```
+
+If you're testing query extensions you have created, it may be more DRY to use a `Cassie::FakeQuery`, which is simply a child of `Cassie::Query` that has already extended `Cassie::Testing::Fake::Query`.
+
+```ruby
+class TestQuery < Cassie::FakeQuery
+end
+TestQuery.new.session
+=> #<Cassie::Testing::Fake::Session::Session:0x007fd03e29a688>
+```
+
+As shown above, query fakes uses a fake session, which provides a few useful features in additon to allowing mock execution:
+
+##### Accessing the last statement executed
+
+```ruby
+some_query.execute
+
+some_query.session.last_statement
+=> #<Cassandra::Statements::Simple:0x3ffde09930b8 @cql="SELECT * FROM users LIMIT 1;" @params=[]>
+```
+
+##### Mocking rows returned in result from query execution
+
+```ruby
+some_query.session.rows = [{id: 1, username: "eprothro"}]
+
+some_query.fetch
+=> [#<Struct id=1, username="eprothro">]
+```

data/lib/cassie/testing/fake/query.rb

@@ -5,6 +5,6 @@ module Cassie
   end
 
   class FakeQuery < Cassie::Query
-    extend Cassie::Testing::Fake::SessionMethods
+    include Cassie::Testing::Fake::SessionMethods
   end
 end

data/lib/cassie/testing/fake/session_methods.rb

@@ -2,26 +2,8 @@ require_relative 'session'
 
 module Cassie::Testing::Fake
   module SessionMethods
-    def self.extended(extender)
-      return if extender.class === Class
 
-      # object has been extended (as opposed to class)
-      # memoize the fake session in metaclass for this object
-      # as we don't want to change behavior of _every_ object
-      # instantiated from the class, only _this_ object
-      extender.class.define_singleton_method(:session) do
-        @session ||= Cassie::Testing::Fake::Session.new
-      end
-
-      # overwrite definition from extension
-      # to delegate to class definition to
-      # minimize difference from vanilla Query
-      def extender.session
-        self.class.session
-      end
-    end
-
-    def session
+    def session(_keyspace=self.keyspace)
       @session ||= Cassie::Testing::Fake::Session.new
     end
   end

data/lib/cassie/testing.rb

@@ -1,5 +1,6 @@
 module Cassie
   module Testing
     require_relative 'testing/fake/query'
+
   end
-end
+end

data/lib/cassie.rb

@@ -1 +1,22 @@
-require_relative 'cassie/query'
+# Active Support used for
+#  * include convenience via ActiveSupport::Concern
+#  * string extensions
+#  * notification pub/sub
+#  * log formatting
+#
+# We require/autoload extensions only as needed,
+# this base require has almost no overhead
+#
+# http://guides.rubyonrails.org/active_support_core_extensions.html
+require 'active_support'
+require 'cassandra'
+
+module Cassie
+  require_relative 'cassie/configuration'
+  require_relative 'cassie/connection_handler'
+  require_relative 'cassie/connection'
+  require_relative 'cassie/query'
+
+  extend Configuration::Core
+  extend ConnectionHandler
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cassie
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.10
+  version: 1.0.0.alpha.15
 platform: ruby
 authors:
 - Evan Prothro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-20 00:00:00.000000000 Z
+date: 2016-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cassandra-driver
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -99,17 +113,30 @@ description: Cassie provides database configration, versioned migrations, effici
   provided by the official `cassandra-driver` through lightweight and easy to use
   interfaces.
 email: evan.prothro@gmail.com
-executables: []
+executables:
+- cassie
 extensions: []
 extra_rdoc_files: []
 files:
+- bin/cassie
 - lib/cassie.rb
+- lib/cassie/configuration.rb
+- lib/cassie/configuration/README.md
+- lib/cassie/configuration/core.rb
+- lib/cassie/configuration/generator.rb
+- lib/cassie/configuration/loading.rb
+- lib/cassie/configuration/templates/cassandra.yml
+- lib/cassie/connection.rb
+- lib/cassie/connection_handler.rb
+- lib/cassie/connection_handler/README.md
+- lib/cassie/connection_handler/cluster.rb
+- lib/cassie/connection_handler/sessions.rb
+- lib/cassie/queries/README.md
 - lib/cassie/queries/instrumentation.rb
 - lib/cassie/queries/logging.rb
 - lib/cassie/queries/logging/cql_execution_event.rb
 - lib/cassie/queries/logging/logger.rb
 - lib/cassie/queries/logging/subscription.rb
-- lib/cassie/queries/session.rb
 - lib/cassie/queries/statement.rb
 - lib/cassie/queries/statement/assignment.rb
 - lib/cassie/queries/statement/assignments.rb
@@ -133,6 +160,7 @@ files:
 - lib/cassie/queries/statement/updating.rb
 - lib/cassie/query.rb
 - lib/cassie/testing.rb
+- lib/cassie/testing/README.md
 - lib/cassie/testing/fake/execution_info.rb
 - lib/cassie/testing/fake/prepared_statement.rb
 - lib/cassie/testing/fake/query.rb
@@ -159,8 +187,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Apache Cassandra application support
 test_files: []
+has_rdoc: 

data/lib/cassie/queries/session.rb

@@ -1,22 +0,0 @@
-module Cassie::Queries
-  module Session
-    extend ::ActiveSupport::Concern
-
-    module ClassMethods
-      def session
-        # until cassie-configuration exists,
-        # we're relying on the client to
-        # supply the session
-        if defined?(super)
-          super
-        else
-          raise "Oops! Cassie::Queries doesn't manage a Cassandra session for you, yet. You must provide a .session class method that returns a valid session."
-        end
-      end
-    end
-
-    def session
-      self.class.session
-    end
-  end
-end