dse-driver 1.0.1-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 43d6f472d065e4e4d980d6402fe26da4ab2f8259
+  data.tar.gz: 182fd750d7dc29158fe46a1e1d7063c2a41622bc
+SHA512:
+  metadata.gz: 986c12a9a51f42ee91253bf7fe25120e04b8877fd92f4e52332892f819d21a5e9aef639b208f8cb7d53f35db3cff822c14c1291d1f3917f95a4f46dcaccda270
+  data.tar.gz: 4515f1d9fd062288aea8de3f755467e1c749e1a5e2284862293703c290c9246f2b897e64208971176f4cd2d51c43593e2bec330df1365ae561a0e49879d772be

data/.yardopts

@@ -0,0 +1,13 @@
+--no-private
+--markup markdown
+--type-tag expected_errors:"Expected Errors"
+--tag jira_ticket:"JIRA Ticket"
+--type-tag expected_result:"Expected Result"
+--tag test_assumptions:"Test Assumptions"
+--tag test_category:"Test Category"
+
+lib/**/*.rb
+integration/**/*.rb
+-- README
+
+load_plugins: true

data/README.md

@@ -0,0 +1,72 @@
+# DataStax Enterprise Ruby Driver
+
+*NOTE: The DataStax Enterprise Ruby Driver can be used solely with DataStax Enterprise. Please consult [the license](http://www.datastax.com/terms/datastax-dse-driver-license-terms).*
+
+This driver is built on top of the [DataStax Ruby driver for Apache Cassandra](http://docs.datastax.com/en/latest-ruby-driver/ruby-driver/whatsNew.html)
+and enhanced for the adaptive data management and mixed workload capabilities
+provided by DSE. Therefore a lot of the underlying concepts are the same.
+
+## Documentation
+Driver documentation can be found [here](http://docs.datastax.com/en/latest-dse-ruby-driver/ruby-driver/whatsNew.html).
+
+In particular, you'll find our [Features](http://docs.datastax.com/en/latest-dse-ruby-driver/supplemental/features) and
+[API](http://docs.datastax.com/en/latest-dse-ruby-driver/supplemental/api) sections very enlightening.
+
+## Feedback Requested
+*Help us focus our efforts!* [Provide your input](http://goo.gl/forms/pCs8PTpHLf) on the Ruby Driver
+Platform and Runtime Survey (we kept it short).
+
+If you find an issue, please file an issue in our [public JIRA](https://datastax-oss.atlassian.net/browse/RUBY).
+*Please be sure to specify the affects-version (DSE-1.X.Y).*
+
+You can also post questions in [our forum](https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user).
+
+## Features
+
+This driver exposes the following features of DSE 5.0:
+
+* <a href="features/graph#graph">Graph</a>
+* <a href="features/authentication#authentication">Authentication</a> with nodes running DSE
+* <a href="features/geospatial#geospatial-types">Geospatial types</a>
+
+Note that this driver is fully compatible with previous versions of DataStax Enterprise.
+
+## Installation
+The driver is named dse-driver on rubygems.org and can easily be installed with Bundler or the gem program. It will
+download the appropriate Cassandra driver as well.
+
+## Upgrade
+The driver is intended to have the same look and feel as the core driver to make upgrading from the core driver
+trivial. The only change is to replace references to the <code>Cassandra</code> module with <code>Dse</code> when
+creating the cluster object:
+
+```ruby
+require 'dse'
+
+# This returns a Dse::Cluster instance
+cluster = Dse.cluster
+
+# This returns a Dse::Session instance
+session = cluster.connect
+rs = session.execute('select * from system.local')
+```
+
+## Determining driver versions
+Within a script or irb, you can determine the exact versions of the dse and core drivers by accessing the VERSION
+constant of the appropriate module:
+
+```ruby
+require 'dse'
+
+puts "Dse Driver Version: #{Dse::VERSION}"
+puts "Cassandra Driver Version: #{Cassandra::VERSION}"
+```
+
+## Compatibility
+Although this driver exposes new features introduced in DSE 5.0, it is fully compatible and supported for use with
+previous versions of DSE. 
+
+## License
+Copyright (C) 2016 DataStax Inc.
+
+The full license terms are available at http://www.datastax.com/terms/datastax-dse-driver-license-terms

data/lib/dse.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+require 'json'
+
+if RUBY_ENGINE == 'jruby'
+  require 'challenge_evaluator'
+else
+  require 'gss_api_context'
+end
+
+require 'cassandra'
+
+module Dse
+  # Creates a {Dse::Cluster Cluster instance}, which extends {http://dsdocs30/api/cassandra/cluster Cassandra::Cluster}.
+  # The API is identical, except that it returns a {Dse::Session Dse::Session} (see below). It takes all of the same
+  # options as Cassandra.cluster and the following extra options.
+  #
+  # @option options [Dse::Graph::Options] :graph_options options for the DSE graph statement handler. Takes
+  #    priority over other `:graph_*` options specified below.
+  # @option options [String] :graph_name name of graph to use in graph statements
+  # @option options [String] :graph_source graph traversal source
+  # @option options [String] :graph_language language used in graph queries
+  # @option options [Cassandra::CONSISTENCIES] :graph_read_consistency read consistency level for graph statements.
+  #    Overrides the standard statement consistency level
+  # @option options [Cassandra::CONSISTENCIES] :graph_write_consistency write consistency level for graph statements.
+  #    Overrides the standard statement consistency level
+  #
+  # @example Connecting to localhost
+  #   cluster = Dse.cluster
+  #
+  # @example Configuring {Dse::Cluster}
+  #   cluster = Dse.cluster(
+  #               username: username,
+  #               password: password,
+  #               hosts: ['10.0.1.1', '10.0.1.2', '10.0.1.3']
+  #             )
+  #
+  # @return [Dse::Cluster] a cluster instance
+  def self.cluster(options = {})
+    cluster_async(options).get
+  end
+
+  # Creates a {Dse::Cluster Cluster instance}.
+  #
+  # @see Dse.cluster
+  #
+  # @return [Cassandra::Future<Dse::Cluster>] a future resolving to the
+  #   cluster instance.
+  def self.cluster_async(options = {})
+    graph_options = if !options[:graph_options].nil?
+                      Cassandra::Util.assert_instance_of(Dse::Graph::Options, options[:graph_options])
+                      options[:graph_options]
+                    else
+                      Dse::Graph::Options.new(options)
+                    end
+    username = options[:username]
+    password = options[:password]
+    options[:custom_types] ||= []
+    options[:custom_types] << Dse::Geometry::Point << Dse::Geometry::LineString << Dse::Geometry::Polygon
+    options, hosts = Cassandra.validate_and_massage_options(options)
+
+    # Use the DSE plain text authenticator if we have a username and password. The above validation already
+    # raises an error if one is given without the other.
+    options[:auth_provider] = Auth::Providers::Password.new(username, password) if username && password
+  rescue => e
+    futures = options.fetch(:futures_factory) { return Cassandra::Future::Error.new(e) }
+    futures.error(e)
+  else
+    options[:cluster_klass] = Dse::Cluster
+    driver = ::Cassandra::Driver.new(options)
+
+    # Wrap the load-balancing policy that we'd otherwise run with, with a host-targeting policy.
+    # We do this before driver.connect because driver.connect saves off the policy in the cluster
+    # registry and does a few other things.
+
+    lbp = driver.load_balancing_policy
+    driver.load_balancing_policy = Dse::LoadBalancing::Policies::HostTargeting.new(lbp)
+    future = driver.connect(hosts)
+    future.then do |cluster|
+      cluster.graph_options.merge!(graph_options)
+      cluster
+    end
+  end
+end
+
+require 'dse/cluster'
+require 'dse/util/endian_buffer'
+require 'dse/geometry/line_string'
+require 'dse/geometry/point'
+require 'dse/geometry/polygon'
+require 'dse/session'
+require 'dse/version'
+require 'dse/graph'
+require 'dse/load_balancing/policies/host_targeting'
+require 'dse/statements'
+require 'dse/auth/providers/gss_api'
+require 'dse/auth/providers/password'

data/lib/dse/auth/providers/gss_api.rb

@@ -0,0 +1,160 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Auth
+    module Providers
+      # Auth provider to authenticate with Kerberos. Whenever the client connects to a DSE node,
+      # this provider will perform Kerberos authentication operations with it. By default, the provider
+      # takes the ip address of the node and uses `Socket#getnameinfo` to find its name in order to construct
+      # the full service address (e.g. service@host).
+      #
+      # @see #initialize
+      class GssApi < Cassandra::Auth::Provider
+        # @private
+        class NameInfoResolver
+          def resolve(host)
+            Socket.getnameinfo(['AF_INET', 0, host])[0]
+          end
+        end
+
+        # @private
+        class NoOpResolver
+          def resolve(host)
+            host
+          end
+        end
+
+        # @private
+        class Authenticator
+          # Copied from kerberosgss.h
+          AUTH_GSS_COMPLETE = 1
+
+          def initialize(authentication_class, host, service, principal, ticket_cache)
+            @authentication_class = authentication_class
+            @host = host
+            @service = service
+            @principal = principal
+            @ticket_cache = ticket_cache
+
+            if RUBY_ENGINE == 'jruby'
+              @sasl_client = javax.security.sasl.Sasl.createSaslClient(['GSSAPI'],
+                                                                       nil,
+                                                                       service,
+                                                                       host,
+                                                                       {javax.security.sasl.Sasl::SERVER_AUTH => 'true',
+                                                                        javax.security.sasl.Sasl::QOP => 'auth'},
+                                                                       nil)
+              config = Dse::Auth::Providers::ChallengeEvaluator.make_configuration(principal, ticket_cache)
+              login = javax.security.auth.login.LoginContext.new('DseClient', nil, nil, config)
+              login.login
+              @subject = login.getSubject
+            else
+              @gss_context = GssApiContext.new("#{@service}@#{@host}", @principal, @ticket_cache)
+            end
+          rescue => e
+            raise Cassandra::Errors::AuthenticationError.new(
+              "Failed to authenticate: #{e.message}",
+              nil,
+              nil,
+              nil,
+              nil,
+              nil,
+              nil,
+              :one,
+              0
+            )
+          end
+
+          def initial_response
+            @authentication_class == 'com.datastax.bdp.cassandra.auth.DseAuthenticator' ?
+                'GSSAPI' :
+                challenge_response('GSSAPI-START')
+          end
+
+          if RUBY_ENGINE == 'jruby'
+            def challenge_response(token)
+              if token == 'GSSAPI-START'
+                return '' unless @sasl_client.hasInitialResponse
+                token = ''
+              end
+
+              Dse::Auth::Providers::ChallengeEvaluator.evaluate(@sasl_client, @subject, token)
+            end
+          else
+            def challenge_response(token)
+              if token == 'GSSAPI-START'
+                response = @gss_context.step('')[1]
+              elsif !@is_gss_complete
+                # Process the challenge as a next step in authentication until we have gotten
+                # AUTH_GSS_COMPLETE.
+                rc, response = @gss_context.step(token)
+                @is_gss_complete = true if rc == AUTH_GSS_COMPLETE
+                response ||= ''
+              else
+                # Ok, we went through all initial phases of auth and now the server is giving us a message
+                # to decode.
+                data = @gss_context.unwrap(token)
+
+                raise 'Bad response from server' if data.length != 4
+                parsed = data.unpack('>L').first
+                max_length = [parsed & 0xffffff, 65536].min
+
+                # Set up a response like this:
+                # byte 0: the selected qop. 1==auth
+                # byte 1-3: the max length for any buffer sent back and forth on this connection. (big endian)
+                # the rest of the buffer: the authorization user name in UTF-8 - not null terminated.
+
+                user_name = @gss_context.user_name
+                out = [max_length | 1 << 24].pack('>L') + user_name
+                response = @gss_context.wrap(out)
+              end
+              response
+            end
+          end
+
+          def authentication_successful(token)
+          end
+        end
+
+        # @param service [String] name of the kerberos service; defaults to 'dse'.
+        # @param host_resolver [Boolean, Object] whether to use a host-resolver. By default,
+        #        `Socket#getnameinfo` is used. To disable host-resolution, specify a `false` value. You may also
+        #        provide a custom resolver, which is an object that implements the `resolve(host_ip)` method.
+        # @param principal [String] The principal whose cached credentials are used to authenticate. Defaults
+        #        to the first principal stored in the ticket cache.
+        # @param ticket_cache [String] The ticket cache containing the cached credential we seek. Defaults
+        #        *on Linux* to /tmp/krb5cc_&lt;uid&gt; (where uid is the numeric uid of the user running the
+        #        client program). In MRI only, the `KRB5CCNAME` environment variable supercedes this. On Mac,
+        #        the default is a symbolic reference to a ticket-cache server process.
+        def initialize(service = 'dse', host_resolver = true, principal = nil, ticket_cache = nil)
+          @service = service
+          @host_resolver = case host_resolver
+                           when false
+                             NoOpResolver.new
+                           when true
+                             NameInfoResolver.new
+                           else
+                             host_resolver
+                           end
+          Cassandra::Util.assert_responds_to(:resolve, @host_resolver,
+                                             'invalid host_resolver: it must have the :resolve method')
+          @principal = principal
+          @ticket_cache = ticket_cache
+        end
+
+        # @private
+        def create_authenticator(authentication_class, host)
+          Authenticator.new(authentication_class, @host_resolver.resolve(host.ip.to_s),
+                            @service, @principal, @ticket_cache)
+        end
+      end
+    end
+  end
+end

data/lib/dse/auth/providers/password.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Auth
+    module Providers
+      # Auth provider to authenticate with username/password for DSE's built-in authentication as well as LDAP.
+      #
+      # @note No need to instantiate this class manually, use `:username` and
+      #   `:password` options when calling {Dse.cluster} and one will be
+      #   created automatically for you.
+
+      class Password < Cassandra::Auth::Provider
+        # @private
+        class Authenticator
+          def initialize(authentication_class, username, password)
+            @authentication_class = authentication_class
+            @username = username
+            @password = password
+          end
+
+          def initial_response
+            @authentication_class == 'com.datastax.bdp.cassandra.auth.DseAuthenticator' ?
+                'PLAIN' :
+                challenge_response('PLAIN-START')
+          end
+
+          def challenge_response(token)
+            "\x00#{@username}\x00#{@password}"
+          end
+
+          def authentication_successful(token)
+          end
+        end
+
+        # @param username [String] username to use for authentication to Cassandra
+        # @param password [String] password to use for authentication to Cassandra
+        def initialize(username, password)
+          @username = username
+          @password = password
+        end
+
+        # @private
+        def create_authenticator(authentication_class, host)
+          Authenticator.new(authentication_class, @username, @password)
+        end
+      end
+    end
+  end
+end

data/lib/dse/cluster.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  # Cluster represents a DSE cluster. It serves as a {Dse::Session session factory} and a collection of metadata.
+  # It wraps a {http://dsdocs30/api/cassandra/cluster Cassandra::Cluster} and exposes all of its functionality.
+  class Cluster
+    # @return [Dse::Graph::Options] default graph options used by queries on this cluster.
+    attr_reader :graph_options
+
+    # @private
+    def initialize(logger,
+                   io_reactor,
+                   executor,
+                   control_connection,
+                   cluster_registry,
+                   cluster_schema,
+                   cluster_metadata,
+                   execution_options,
+                   connection_options,
+                   load_balancing_policy,
+                   reconnection_policy,
+                   retry_policy,
+                   address_resolution_policy,
+                   connector,
+                   futures_factory,
+                   timestamp_generator)
+      @delegate_cluster = Cassandra::Cluster.new(logger,
+                                                 io_reactor,
+                                                 executor,
+                                                 control_connection,
+                                                 cluster_registry,
+                                                 cluster_schema,
+                                                 cluster_metadata,
+                                                 execution_options,
+                                                 connection_options,
+                                                 load_balancing_policy,
+                                                 reconnection_policy,
+                                                 retry_policy,
+                                                 address_resolution_policy,
+                                                 connector,
+                                                 futures_factory,
+                                                 timestamp_generator)
+      @graph_options = Dse::Graph::Options.new
+
+      # We need the futures factory ourselves for async error reporting and potentially for our
+      # own async processing independent of the C* driver.
+      @futures = futures_factory
+    end
+
+    # Delegates to {http://docs.datastax.com/en/developer/ruby-driver/3.0/supplemental/api/cassandra/cluster/?local=true&nav=toc#connect_async-instance_method
+    # Cassandra::Cluster#connect_async}
+    # to connect asynchronously to a cluster, but returns a future that will resolve to a DSE session rather than
+    # Cassandra session.
+    #
+    # @param keyspace [String] optional keyspace to scope session to
+    #
+    # @return [Cassandra::Future<Dse::Session>]
+    def connect_async(keyspace = nil)
+      future = @delegate_cluster.connect_async(keyspace)
+      # We want to actually return a DSE session upon successful connection.
+      future.then do |cassandra_session|
+        Dse::Session.new(cassandra_session, @graph_options, @futures)
+      end
+    end
+
+    # Synchronous variant of {#connect_async}.
+    #
+    # @param keyspace [String] optional keyspace to scope the session to
+    #
+    # @return [Dse::Session]
+    def connect(keyspace = nil)
+      connect_async(keyspace).get
+    end
+
+    #### The following methods handle arbitrary delegation to the underlying cluster object. ####
+    protected
+
+    # @private
+    def method_missing(method_name, *args, &block)
+      # If we get here, we don't have a method of our own. Forward the request to the delegate_cluster.
+      # If it returns itself, we will coerce the result to return our *self* instead.
+
+      result = @delegate_cluster.send(method_name, *args, &block)
+      (result == @delegate_cluster) ? self : result
+    end
+
+    # @private
+    def respond_to?(method, include_private = false)
+      super || @delegate_cluster.respond_to?(method, include_private)
+    end
+  end
+end