cassie 1.0.0.beta.33 → 1.0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ffedeca0fe95eb9d618ed1042b54fc2ffbda0a4
-  data.tar.gz: 5bb78230669425a06ea21f8886006074b2b38878
+  metadata.gz: 699a8f4a3e3028c10784854a30872b34d4d484e9
+  data.tar.gz: 8fe8d9ae25aa618c70bf97ce8d77cbb24cda64db
 SHA512:
-  metadata.gz: 16503691f2a924dc76cae63749f0ab3cf5b40afa56b37fd51df271f500862ba181e83f45740c15f0305df2d5911437a26e89ce177ad58b6f617d32ee47f8e1cf
-  data.tar.gz: c3ede66882f0a2341581892ca83fbc430f0ba525b04ced68d1fdfa3ec0f1e2a67473a7c736793e9bb18f847e0215a7accffd1068bceaa7a835198188acfbe6cb
+  metadata.gz: '08b12a72644d875eecf1fa1ced9ba3be680d853e7ee6d7072f56c22b052bccd6aa668e202b6aae17382604dd9b63691d45fb737753b7e8f155b70248cc799307'
+  data.tar.gz: 0d639234ec78ca7ba54b83507a4d27790d9ac0f46bf7a277d2fea6549d3493d31b9f7d473d2f64f5214a48b65da3064748c7055fdf10e432804a828cbdab3ff9

data/bin/cassie

@@ -1,185 +1,12 @@
-#! ruby
-require_relative '../lib/cassie'
-
-def start
-  runner = Cassie::Support::CommandRunner.new("cassandra")
-  puts("Starting Cassandra...")
-  runner.run
-  runner.fail unless runner.completed?
-
-  if runner.output =~ /state jump to NORMAL/
-    puts "[#{green('✓')}] Cassandra Running"
-  else
-    runner.output.split("\n").grep(/ERROR/).each{|e| puts red("  " + e.gsub("; nested exception is:", "")) }
-    puts "[#{red('✘')}] Cassandra Failed to Start"
-  end
-end
-
-def stop(kill_all=false)
-  runner = Cassie::Support::CommandRunner.new("ps", ["-awx"])
-  runner.run
-  fail runner.failure_message unless runner.success?
-
-  cassandra_awx = runner.output.split("\n").grep(/cassandra/)
-  pids = cassandra_awx.map{ |p| p.split(' ').first.to_i }
-
-  if pids.empty?
-    puts red("No Cassandra process was found. Is Cassandra running?")
-    exit(1)
-  elsif pids.length > 1 && !kill_all
-    puts red("Couldn't single out a Cassandra process.")
-    puts red("  - Is cqlsh running?")
-    puts red("  - Kill all cassandra processes with --all")
-    cassandra_awx.each do |p|
-      puts "    - #{p.split(' ').first.ljust(5,' ')} | #{p.split(' ').last}"
-    end
-    exit(1)
-  end
-
-  puts("Stopping Cassandra...")
-  pids.each do|pid|
-    Process.kill("TERM", pid)
-    loop do
-      sleep(0.1)
-      begin
-        Process.getpgid( pid )
-      rescue Errno::ESRCH
-        break
-      end
-    end
-  end
-
-  puts "[#{green('✓')}] Cassandra Stopped"
-end
-
-def kick
-  stop
-  start
-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]
-
-  generator = Cassie::Configuration::Generator.new(opts)
-  generator.save
-  puts "[✓] Cassandra configuration written to #{generator.destination_path}"
-end
-
-def dump_structure
-  dumper = Cassie::Migration::StructureDumper.new
-  dumper.dump
-  puts "[#{green("✓")}] Cassandra schema written to #{dumper.destination_path}"
-
-rescue => e
-  puts e.message
-  exit(1)
-end
-
-def load_structure
-  loader = Cassie::Migration::StructureLoader.new
-  loader.load
-  puts "[#{green("✓")}] Cassandra schema loaded from #{loader.source_path}"
+#!/usr/bin/env ruby
 
-rescue => e
-  puts e.message
-  exit(1)
-end
-
-def tail_log
-  runner = Cassie::Support::CommandRunner.new("which", ["cassandra"])
-  runner.run!
-
-  bin_path = runner.output.gsub("\n", '')
-  log_path = bin_path.sub('bin/cassandra', 'logs/system.log')
-  puts white("Tailing Cassandra system log, Ctrl-C to stop...")
-  puts "  #{log_path}:\n\n"
-
-  args = ['-f', log_path, '>', '/dev/tty']
-  runner = Cassie::Support::CommandRunner.new("tail", args)
-  runner.run!
-end
-
-# Use current schema to initialize versioned migrations
-#   * import current schema as initial migration
-#   * initialize cassie_schema keyspace and version table
-#   * insert initial version
-#   * dump structure
-def initialize_migrations
-  Cassie::Migration.initialize_versioning
-  puts "[#{green("✓")}] Versioned migrations initialized. Current version: #{Cassie::Migration.version_number}"
-rescue Cassie::Migration::AlreadyInitiailizedError
-  puts "[#{red('✘')}] Versioned migration metatdata already exists. Current version: #{Cassie::Migration.version_number}"
-rescue => e
-  puts e.message
-  exit(1)
-end
-
-def schema_history
-  print_versions(Cassie::Migration.versions)
-rescue Cassie::Migration::UninitializedError => e
-  puts red(e.message)
-end
-
-def schema_version
-  print_versions([Cassie::Migration.version])
-rescue Cassie::Migration::UninitializedError => e
-  puts red(e.message)
-end
-
-def print_versions(versions)
-  require 'terminal-table'
-  members = [:version_number, :description, :migrator, :migrated_at]
-  titles  = ['Version', 'Description', 'Migrated by', 'Migrated at']
-  table = Terminal::Table.new(headings:  titles)
-  versions.each.with_index do |v, i|
-    v.version_number = "* #{v.version_number}" if i == 0
-    table.add_row(v.to_h.values_at(*members))
-  end
-  table.align_column(0, :right)
-  puts table
-end
+require_relative '../lib/cassie'
+require_relative "../lib/cassie/tasks"
 
-def white(message)
-  "\e[1;37m#{message}\e[0m"
-end
-def red(message)
-  "\e[1;31m#{message}\e[0m"
-end
-def green(message)
-  "\e[1;32m#{message}\e[0m"
+runner = Cassie::Tasks::TaskRunner.new
+if ARGV.length > 0
+  runner.run_command(ARGV)
+else
+  runner.print_documentation
 end
 
-case ARGV[0]
-when "start"
-  start
-when "stop"
-  stop(ARGV.include?('--all'))
-when /kick|restart/
-  kick
-when /tail|log/
-  tail_log
-when "configuration:generate"
-  generate_config
-when "structure:dump"
-  dump_structure
-when "structure:load"
-  load_structure
-when /migrations?\:initialize/
-  initialize_migrations
-when "schema:history"
-  schema_history
-when "schema:version"
-  schema_version
-else
-  puts red("`#{ARGV[0]}` is not a supported command.")
-end

data/lib/cassie/configuration/core.rb

@@ -1,17 +1,24 @@
 require_relative 'loading'
 
 module Cassie::Configuration
-  #TODO: proper rdoc
-  # Extend a class with Core to enable configuration management
+  # Extend a class with Core to add configuration management
+  # methods and attributes
   module Core
     include Loading
 
-    attr_writer :keyspace
+    # The currently selected keyspace.
+    # If no keyspace has been explicitly set, then
+    # the default +:keyspace+ from {#configuration} is used.
+    attr_accessor :keyspace
 
+    # @!visibility private
     def self.extended(extender)
       extender.paths["cluster_configurations"] = "config/cassandra.yml"
     end
 
+    # The currently active environment.
+    # Used to select which configuration will be used
+    # @!parse attr_accessor :env
     def env
       @env ||= ActiveSupport::StringInquirer.new(ENV["CASSANDRA_ENV"] || ENV["RACK_ENV"] || "development")
     end
@@ -20,10 +27,17 @@ module Cassie::Configuration
       @env = ActiveSupport::StringInquirer.new(val)
     end
 
+    # Paths used for configuration loading.
+    #
+    # @return [Hash]
+    #   * +:cluster_configurations+ - The .yml file defining the configuration for your cluster for various environments.
     def paths
       @paths ||= {}.with_indifferent_access
     end
 
+    # The cluster configurations available for all environments
+    # @return [Hash{String => [Hash]}] Cluster configurations, keyed by environment.
+    # @!parse attr_accessor :configurations
     def configurations
       @configurations ||= cluster_configurations
     end
@@ -35,6 +49,15 @@ module Cassie::Configuration
       @configurations = val
     end
 
+    # The currently active configuration used
+    # for initializing new cluster connections.
+    # If none has been set, the configuration for the
+    # current {#env} is used from {#configuration}
+    #
+    # Note: setting a {#configuration} value will override
+    # the {#configurations} attribute, rendering it useless
+    # @return [Hash{String,Symbol => Object}] Hash of +cassandra-driver+ supported cluster configuration attributes
+    # @!parse attr_accessor :configuration
     def configuration
       return @configuration if defined?(@configuration)
       configurations[env]

data/lib/cassie/configuration/generator.rb

@@ -19,6 +19,7 @@ module Cassie
       end
 
       def save
+        raise "#{destination_path} already exists" if File.exists?(destination_path)
         File.open(destination_path, "w+") do |f|
           f.write(render)
         end

data/lib/cassie/configuration/loading.rb

@@ -1,6 +1,9 @@
 module Cassie::Configuration
   module Loading
-
+    # Fetch cluster configurations
+    # from configuraiton file located at
+    # +paths["cluster_configurations"]+
+    # @return [Hash{String => Object}] Configuration loaded from yml file
     def cluster_configurations
       path = paths["cluster_configurations"]
 
@@ -32,7 +35,7 @@ module Cassie::Configuration
       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>."
+      msg + ", or configure the correct path via Cassie::Configuration.paths['cluster_configurations'] = <path>."
     end
 
     def generation_instructions

data/lib/cassie/configuration.rb

@@ -1,6 +1,7 @@
 require 'active_support/core_ext/hash/indifferent_access'
 
 module Cassie
+  # Contains components for managing cluster configuration
   module Configuration
     require_relative 'configuration/generator'
     require_relative 'configuration/core'

data/lib/cassie/connection.rb

@@ -1,15 +1,21 @@
 module Cassie
-  # Include Cassie::Connection to add #session and #keyspace
-  # convenience methods that conform with object cacheing and reuse
+  # Defines interface providing Cassandra connection management
+  # including object cacheing and reuse
   # behavior in line with Cassandra best practices
+  #
+  # +include Cassie::Connection+ to add +keyspace+
+  # and +session+ attributes to the including module.
   module Connection
 
-    extend ActiveSupport::Concern
-
-    included do
-      attr_writer :keyspace
+    # @!visibility private
+    def self.included(base)
+      base.instance_eval do
+        attr_writer :keyspace
+      end
+      base.extend ClassMethods
     end
 
+    # @!parse extend ClassMethods
     module ClassMethods
       def keyspace(val=NilClass)
         # support DSL style
@@ -30,7 +36,7 @@ module Cassie
       end
 
       def keyspace=(val)
-        #support Class.keyspace = :foo
+        #support non DSL style Class.keyspace = :foo
         @keyspace = val
       end
     end

data/lib/cassie/connection_handler/README.md

@@ -61,7 +61,7 @@ class HelpfulCounter
 end
 ```
 
-Ignoring the likely irresponsible example query used -- The object falls back to using the `Cassie::keyspace` value by default.
+Ignoring the likely irresponsible example query used. The object falls back to using the `Cassie::keyspace` value by default.
 
 ```ruby
 Cassie.keyspace
@@ -76,7 +76,17 @@ object.user_count
 => 302525
 ```
 
-The keyspace can be set at the class level.
+Connection options follow the following lookup path:
+
+1. the object instance value
+2. the class instance value
+3. the `Cassie` instance value
+4. the `Cassie::configuruation[:option]` value
+5. the `Cassandra::cluster` value (default cassandra driver value)
+
+##### Examples:
+
+###### Set at the class level:
 
 ```ruby
 class Analytics::HelpfulCounter
@@ -102,7 +112,7 @@ object.user_count
 
 ```
 
-Or at the object level
+###### Set at the object level:
 
 ```ruby
 Cassie.keyspace

data/lib/cassie/connection_handler/cluster.rb

@@ -13,6 +13,11 @@ module Cassie::ConnectionHandler
       include Instrumentation
     end
 
+    # The cluster connection and metadata. This cluster connection is
+    # lazy-loaded, not calling out to Cassandra until it is first
+    # accessed. The single cluster object is cached for the entire process.
+    # @return [Cassandra::Cluster] The underlying driver cluster object
+    # @!parse attr_reader :cluster
     def cluster
       # Cassandra::cluster parses suppored
       # options from the passed hash, no need
@@ -20,6 +25,12 @@ module Cassie::ConnectionHandler
       @cluster ||= initialize_cluster
     end
 
+    # @param [String, Symbol] name The keyspace name to search for
+    # @return [Boolean] indicating if the cluster has the keyspace defined
+    def keyspace_exists?(name)
+      Cassie.cluster.keyspaces.map(&:name).any?{|k| k.to_s == name.to_s}
+    end
+
     protected
 
     def initialize_cluster

data/lib/cassie/connection_handler/sessions.rb

@@ -7,10 +7,19 @@ module Cassie::ConnectionHandler
       include Instrumentation
     end
 
+    # Sessions cache containint sessions that
+    # have been opened to the {#cluster}
+    # @return [Hash{String => Cassandra::Session}] The underlying driver sessions, keyed by keyspaced name
+    # @!parse attr_reader :sessions
     def sessions
       @sessions ||= {}
     end
 
+    # Fetches a session from the sessions cache.
+    # If no session has been opened to the requested keyspace
+    # a new session is created to the {#cluster} and cached.
+    # @param [String] keyspace The keyspace used for session scope. If +nil+, session will not be scoped (scoped to global space).
+    # @return [Cassandra::Session]
     def session(keyspace=self.keyspace)
       sessions[keyspace] || initialize_session(keyspace)
     end

data/lib/cassie/connection_handler.rb

@@ -2,7 +2,14 @@ module Cassie
   # Extend Cassie::ConnectionHandler to provide cluster and session
   # cacheing in line with Cassandra best practices.
   #
-  # The base class must implement `configuration` and `keyspace` methods.
+  # The extending class must provide two methods
+  # that will be used by the connection handler for connections:
+  # * +self.configuration+
+  #   * A configuration hash defining cluster options per environment
+  #   * Used when connecting through +cassandra_driver+
+  #   * See [Configuration::Core] for a sample implementation with a .yml back-end
+  # * +self.keyspace+
+  #   * The default keyspace to connect to when none is specified for a session.
   module ConnectionHandler
     require_relative 'connection_handler/cluster'
     require_relative 'connection_handler/sessions'
@@ -10,11 +17,5 @@ module Cassie
 
     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/definition.rb

@@ -1,4 +1,32 @@
 module Cassie
+  # A concrete implementation of a functional base class used to
+  # make CQL DDL or generic queries without any DSL.
+  # Inherit from this class to create application query classes.
+  #
+  # * The Cassandra connection is provided and managed by {Cassie::Connection}
+  # * Generic statement functionality is provided by {Statements::Core}
+  # * Defining the statement and options is up the subclass's responsibility (e.g. no DSL is provided)
+  #
+  # See the {file:lib/cassie/statements/README.md} for information on usage and examples.
+  #
+  # @example Inserting a record into a Table
+  #   class CreateKeyspaceQuery < Cassie::Definition
+  #     attr_accessor :name
+  #
+  #     self.prepare = false
+  #
+  #     def statement
+  #       cql = %(
+  #         CREATE KEYSPACE #{name}
+  #         WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'}
+  #         AND durable_writes = true;
+  #        )
+  #     end
+  #   end
+  #
+  #   CreateKeyspaceQuery.new(name: "my keyspace").excecute
+  #   #=> true
+  #
   class Definition
     require_relative 'statements'
 

data/lib/cassie/extensions/object/color_methods.rb

@@ -0,0 +1,21 @@
+module Cassie::Extensions
+  module Object
+    module ColorMethods
+      def white(message)
+        "\e[1;37m#{message}\e[0m"
+      end
+
+      def red(message)
+        "\e[1;31m#{message}\e[0m"
+      end
+
+      def green(message)
+        "\e[1;32m#{message}\e[0m"
+      end
+    end
+  end
+end
+
+class Object
+  include Cassie::Extensions::Object::ColorMethods
+end

data/lib/cassie/instrumentation.rb

@@ -1,4 +1,8 @@
 module Cassie
+
+  # Instrumentor used for notifications for events
+  # such as connecting clusters, openeing sessions,
+  # and executing queries
   def self.instrumenter
     @instrumenter ||= ActiveSupport::Notifications
   end

data/lib/cassie/modification.rb

@@ -1,4 +1,33 @@
 module Cassie
+  # A concrete implementation of a functional base class used to
+  # make CQL +INSERT+, +UPDATE+, and +DELETE+ queries.
+  # Inherit from this class to create application query classes.
+  #
+  # * The Cassandra connection is provided and managed by {Cassie::Connection}
+  # * Generic statement functionality is provided by {Statements::Core}
+  # * +INSERT|UPDATE|DELETE+ specific statement DSL and functionality is provided by {Statements::Modification}
+  #
+  # See the {file:lib/cassie/statements/README.md} for information on usage and examples.
+  #
+  # @example Inserting a record into a Table
+  #   class InsertUserQuery < Cassie::Modification
+  #
+  #     insert_into :users_by_username
+  #     consistency :all
+  #
+  #     set :id
+  #     set :username
+  #
+  #     map_from :user
+  #
+  #     def id
+  #       Cassandra::TimeUuid::Generator.new.now
+  #     end
+  #   end
+  #
+  #   InsertUserQuery.new(user: user).excecute
+  #   #=> true
+  #
   class Modification
     require_relative 'statements'
 

data/lib/cassie/query.rb

@@ -1,4 +1,28 @@
 module Cassie
+  # A concrete implementation of a functional base class used to
+  # make CQL +SELECT+ queries. Inherit from this class to create application query classes.
+  #
+  # * The Cassandra connection is provided and managed by {Cassie::Connection}
+  # * Generic statement functionality is provided by {Statements::Core}
+  # * +SELECT+ specific statement DSL and functionality is provided by {Statements::Query}
+  #
+  # See the {file:lib/cassie/statements/README.md} for information on usage and examples.
+  #
+  # @example Selecting a record from a Table
+  #   class UsersByUsernameQuery < Cassie::Query
+  #
+  #     select_from :users_by_username
+  #
+  #     where :username, :eq
+  #
+  #     def build_result(row)
+  #       User.new(row)
+  #     end
+  #   end
+  #
+  #   user = UsersByUsernameQuery.new(username: 'eprothro').fetch_first
+  #   #=> #<User:0x007fedec219cd8 @id=123, @username="eprothro">
+  #
   class Query
     require_relative 'statements'
 
@@ -6,5 +30,8 @@ module Cassie
     include Statements::Core
     include Statements::Query
 
+    # @!parse extend Cassie::Connection::ClassMethods
+    # @!parse extend Cassie::Statements::Core::ClassMethods
+    # @!parse extend Cassie::Statements::Query::ClassMethods
   end
 end