couchbase 3.0.0.alpha.4-universal-darwin-19 → 3.0.2-universal-darwin-19

data/lib/couchbase/bucket.rb

@@ -15,15 +15,20 @@
 require "couchbase/scope"
 require "couchbase/management/collection_manager"
 require "couchbase/management/view_index_manager"
+require "couchbase/options"
 require "couchbase/view_options"
+require "couchbase/diagnostics"
 
 module Couchbase
   class Bucket
-    alias_method :inspect, :to_s
+    # @return [String] name of the bucket
+    attr_reader :name
+
+    alias inspect to_s
 
     # @param [Couchbase::Backend] backend
     def initialize(backend, name)
-      backend.open_bucket(name)
+      backend.open_bucket(name, true)
       @backend = backend
       @name = name
     end
@@ -57,36 +62,25 @@ module Couchbase
     #
     # @return [Collection]
     def default_collection
-      default_scope.default_collection
+      Collection.new(@backend, @name, :_default, :_default)
     end
 
     # Performs query to view index.
     #
     # @param [String] design_document_name name of the design document
     # @param [String] view_name name of the view to query
-    # @param [ViewOptions] options
+    # @param [Options::View] options
+    #
+    # @example Make sure the view engine catch up with all mutations and return keys starting from +["random_brewery:"]+
+    #   bucket.view_query("beer", "brewery_beers",
+    #                     Options::View(
+    #                       start_key: ["random_brewery:"],
+    #                       scan_consistency: :request_plus
+    #                     ))
     #
-    # @return [ViewQueryResult]
-    def view_query(design_document_name, view_name, options = ViewOptions.new)
-      resp = @backend.document_view(@name, design_document_name, view_name, options.namespace, {
-          timeout: options.timeout,
-          scan_consistency: options.scan_consistency,
-          skip: options.skip,
-          limit: options.limit,
-          start_key: (JSON.generate(options.start_key) unless options.start_key.nil?),
-          end_key: (JSON.generate(options.end_key) unless options.end_key.nil?),
-          start_key_doc_id: options.start_key_doc_id,
-          end_key_doc_id: options.end_key_doc_id,
-          inclusive_end: options.inclusive_end,
-          group: options.group,
-          group_level: options.group_level,
-          key: (JSON.generate(options.key) unless options.key.nil?),
-          keys: options.keys&.map { |key| JSON.generate(key) },
-          order: options.order,
-          reduce: options.reduce,
-          on_error: options.on_error,
-          debug: options.debug,
-      })
+    # @return [ViewResult]
+    def view_query(design_document_name, view_name, options = Options::View.new)
+      resp = @backend.document_view(@name, design_document_name, view_name, options.namespace, options.to_backend)
       ViewResult.new do |res|
         res.meta_data = ViewMetaData.new do |meta|
           meta.total_rows = resp[:meta][:total_rows]
@@ -114,23 +108,36 @@ module Couchbase
 
     # Performs application-level ping requests against services in the couchbase cluster
     #
+    # @param [Options::Ping] options
+    #
     # @return [PingResult]
-    def ping(options = PingOptions.new) end
-
-    class PingOptions
-      # @return [String] Holds custom report id.
-      attr_accessor :report_id
-
-      # @return [Array<Symbol>] The service types to limit this diagnostics request
-      attr_accessor :service_types
-
-      # @return [Integer] the time in milliseconds allowed for the operation to complete
-      attr_accessor :timeout
-
-      def initialize
-        @service_types = [:kv, :query, :analytics, :search, :views, :management]
-        yield self if block_given?
+    def ping(options = Options::Ping.new)
+      resp = @backend.ping(@name, options.to_backend)
+      PingResult.new do |res|
+        res.version = resp[:version]
+        res.id = resp[:id]
+        res.sdk = resp[:sdk]
+        resp[:services].each do |type, svcs|
+          res.services[type] = svcs.map do |svc|
+            PingResult::ServiceInfo.new do |info|
+              info.id = svc[:id]
+              info.state = svc[:state]
+              info.latency = svc[:latency]
+              info.remote = svc[:remote]
+              info.local = svc[:local]
+              info.error = svc[:error]
+            end
+          end
+        end
       end
     end
+
+    # @api private
+    # TODO: deprecate in 3.1
+    PingOptions = ::Couchbase::Options::Ping
+
+    # @api private
+    # TODO: deprecate in 3.1
+    ViewOptions = ::Couchbase::Options::View
   end
 end

data/lib/couchbase/cluster.rb

@@ -21,24 +21,58 @@ require "couchbase/management/query_index_manager"
 require "couchbase/management/analytics_index_manager"
 require "couchbase/management/search_index_manager"
 
+require "couchbase/options"
+
 require "couchbase/search_options"
 require "couchbase/query_options"
 require "couchbase/analytics_options"
+require "couchbase/diagnostics"
 
 module Couchbase
   class Cluster
-    alias_method :inspect, :to_s
+    alias inspect to_s
 
     # Connect to the Couchbase cluster
     #
-    # @param [String] connection_string connection string used to locate the Couchbase Cluster
-    # @param [ClusterOptions] options custom options when creating the cluster connection
+    # @overload connect(connection_string, options)
+    #   @param [String] connection_string connection string used to locate the Couchbase Cluster
+    #   @param [Options::Cluster] options custom options when creating the cluster connection
+    #
+    # @overload connect(connection_string, username, password, options)
+    #   Shortcut for {PasswordAuthenticator}
+    #   @param [String] connection_string connection string used to locate the Couchbase Cluster
+    #   @param [String] username name of the user
+    #   @param [String] password password of the user
+    #   @param [Options::Cluster, nil] options custom options when creating the cluster connection
+    #
+    # @example Explicitly create options object and initialize PasswordAuthenticator internally
+    #   options = Cluster::ClusterOptions.new
+    #   options.authenticate("Administrator", "password")
+    #   Cluster.connect("couchbase://localhost", options)
+    #
+    # @example Pass authenticator object to Options
+    #   Cluster.connect("couchbase://localhost",
+    #     Options::Cluster(authenticator: PasswordAuthenticator.new("Administrator", "password")))
+    #
+    # @example Shorter version, more useful for interactive sessions
+    #   Cluster.connect("couchbase://localhost", "Administrator", "password")
+    #
+    # @example Authentication with TLS client certificate (note +couchbases://+ schema)
+    #   Cluster.connect("couchbases://localhost?trust_certificate=/tmp/ca.pem",
+    #     Options::Cluster(authenticator: CertificateAuthenticator.new("/tmp/certificate.pem", "/tmp/private.key")))
+    #
+    # @see https://docs.couchbase.com/server/current/manage/manage-security/configure-client-certificates.html
     #
     # @return [Cluster]
-    def self.connect(connection_string, options)
-      Cluster.new(connection_string, options)
+    def self.connect(connection_string, *options)
+      Cluster.new(connection_string, *options)
     end
 
+    # Returns an instance of the {Bucket}
+    #
+    # @param [String] name name of the bucket
+    #
+    # @return [Bucket]
     def bucket(name)
       Bucket.new(@backend, name)
     end
@@ -46,35 +80,15 @@ module Couchbase
     # Performs a query against the query (N1QL) services
     #
     # @param [String] statement the N1QL query statement
-    # @param [QueryOptions] options the custom options for this query
+    # @param [Options::Query] options the custom options for this query
+    #
+    # @example Select first ten hotels from travel sample dataset
+    #   cluster.query("SELECT * FROM `travel-sample` WHERE type = $type LIMIT 10",
+    #                 Options::Query(named_parameters: {type: "hotel"}, metrics: true))
     #
     # @return [QueryResult]
-    def query(statement, options = QueryOptions.new)
-      resp = @backend.document_query(statement, {
-          timeout: options.timeout,
-          adhoc: options.adhoc,
-          client_context_id: options.client_context_id,
-          max_parallelism: options.max_parallelism,
-          readonly: options.readonly,
-          scan_wait: options.scan_wait,
-          scan_cap: options.scan_cap,
-          pipeline_batch: options.pipeline_batch,
-          pipeline_cap: options.pipeline_cap,
-          metrics: options.metrics,
-          profile: options.profile,
-          positional_parameters: options.instance_variable_get("@positional_parameters")&.map { |p| JSON.dump(p) },
-          named_parameters: options.instance_variable_get("@named_parameters")&.each_with_object({}) { |(n, v), o| o[n.to_s] = JSON.dump(v) },
-          raw_parameters: options.instance_variable_get("@raw_parameters"),
-          scan_consistency: options.instance_variable_get("@scan_consistency"),
-          mutation_state: options.instance_variable_get("@mutation_state")&.tokens&.map { |t|
-            {
-                bucket_name: t.bucket_name,
-                partition_id: t.partition_id,
-                partition_uuid: t.partition_uuid,
-                sequence_number: t.sequence_number,
-            }
-          },
-      })
+    def query(statement, options = Options::Query.new)
+      resp = @backend.document_query(statement, options.to_backend)
 
       QueryResult.new do |res|
         res.meta_data = QueryMetaData.new do |meta|
@@ -104,20 +118,15 @@ module Couchbase
     # Performs an analytics query
     #
     # @param [String] statement the N1QL query statement
-    # @param [AnalyticsOptions] options the custom options for this query
+    # @param [Options::Analytics] options the custom options for this query
+    #
+    # @example Select name of the given user
+    #   cluster.analytics_query("SELECT u.name AS uname FROM GleambookUsers u WHERE u.id = $user_id ",
+    #                           Options::Analytics(named_parameters: {user_id: 2}))
     #
     # @return [AnalyticsResult]
-    def analytics_query(statement, options = AnalyticsOptions.new)
-      resp = @backend.document_analytics(statement, {
-          timeout: options.timeout,
-          client_context_id: options.client_context_id,
-          scan_consistency: options.scan_consistency,
-          readonly: options.readonly,
-          priority: options.priority,
-          positional_parameters: options.instance_variable_get("@positional_parameters")&.map { |p| JSON.dump(p) },
-          named_parameters: options.instance_variable_get("@named_parameters")&.each_with_object({}) { |(n, v), o| o[n.to_s] = JSON.dump(v) },
-          raw_parameters: options.instance_variable_get("@raw_parameters"),
-      })
+    def analytics_query(statement, options = Options::Analytics.new)
+      resp = @backend.document_analytics(statement, options.to_backend)
 
       AnalyticsResult.new do |res|
         res.transcoder = options.transcoder
@@ -148,30 +157,20 @@ module Couchbase
     #
     # @param [String] index_name the name of the search index
     # @param [SearchQuery] query the query tree
-    # @param [SearchOptions] options the query tree
+    # @param [Options::Search] options the query tree
+    #
+    # @example Return first 10 results of "hop beer" query and request highlighting
+    #   cluster.search_query("beer_index", Cluster::SearchQuery.match_phrase("hop beer"),
+    #                        Options::Search(
+    #                          limit: 10,
+    #                          fields: %w[name],
+    #                          highlight_style: :html,
+    #                          highlight_fields: %w[name description]
+    #                        ))
     #
     # @return [SearchResult]
-    def search_query(index_name, query, options = SearchOptions.new)
-      resp = @backend.document_search(index_name, JSON.generate(query), {
-          timeout: options.timeout,
-          limit: options.limit,
-          skip: options.skip,
-          explain: options.explain,
-          highlight_style: options.highlight_style,
-          highlight_fields: options.highlight_fields,
-          fields: options.fields,
-          sort: options.sort&.map { |v| JSON.generate(v) },
-          facets: options.facets&.map { |(k, v)| [k, JSON.generate(v)] },
-          scan_consistency: options.instance_variable_get("@scan_consistency"),
-          mutation_state: options.instance_variable_get("@mutation_state")&.tokens&.map { |t|
-            {
-                bucket_name: t.bucket_name,
-                partition_id: t.partition_id,
-                partition_uuid: t.partition_uuid,
-                sequence_number: t.sequence_number,
-            }
-          },
-      })
+    def search_query(index_name, query, options = Options::Search.new)
+      resp = @backend.document_search(index_name, JSON.generate(query), options.to_backend)
 
       SearchResult.new do |res|
         res.meta_data = SearchMetaData.new do |meta|
@@ -180,6 +179,7 @@ module Couchbase
           meta.metrics.success_partition_count = resp[:meta_data][:metrics][:success_partition_count]
           meta.metrics.took = resp[:meta_data][:metrics][:took]
           meta.metrics.total_rows = resp[:meta_data][:metrics][:total_rows]
+          meta.errors = resp[:meta_data][:errors]
         end
         res.rows = resp[:rows].map do |r|
           SearchRow.new do |row|
@@ -189,50 +189,67 @@ module Couchbase
             row.score = r[:score]
             row.fragments = r[:fragments]
             row.locations = SearchRowLocations.new(
-                r[:locations].map do |loc|
-                  SearchRowLocation.new do |location|
-                    location.field = loc[:field]
-                    location.term = loc[:term]
-                    location.position = loc[:position]
-                    location.start_offset = loc[:start_offset]
-                    location.end_offset = loc[:end_offset]
-                    location.array_positions = loc[:array_positions]
-                  end
+              r[:locations].map do |loc|
+                SearchRowLocation.new do |location|
+                  location.field = loc[:field]
+                  location.term = loc[:term]
+                  location.position = loc[:position]
+                  location.start_offset = loc[:start_offset]
+                  location.end_offset = loc[:end_offset]
+                  location.array_positions = loc[:array_positions]
                 end
+              end
             )
             row.instance_variable_set("@fields", r[:fields])
             row.explanation = JSON.parse(r[:explanation]) if r[:explanation]
           end
         end
-        res.facets = resp[:facets]&.each_with_object({}) do |(k, v), o|
-          facet = case options.facets[k]
-                  when SearchFacet::SearchFacetTerm
-                    SearchFacetResult::TermFacetResult.new do |f|
-                      f.terms = v[:terms]&.map do |t|
-                        SearchFacetResult::TermFacetResult::TermFacet.new(t[:term], t[:count])
-                      end || []
-                    end
-                  when SearchFacet::SearchFacetDateRange
-                    SearchFacetResult::DateRangeFacetResult.new do |f|
-                      f.date_ranges = v[:date_ranges]&.map do |r|
-                        SearchFacetResult::DateRangeFacetResult::DateRangeFacet.new(r[:name], r[:count], r[:start_time], r[:end_time])
-                      end || []
-                    end
-                  when SearchFacet::SearchFacetNumericRange
-                    SearchFacetResult::NumericRangeFacetResult.new do |f|
-                      f.numeric_ranges = v[:numeric_ranges]&.map do |r|
-                        SearchFacetResult::NumericRangeFacetResult::NumericRangeFacet.new(r[:name], r[:count], r[:min], r[:max])
-                      end || []
+        if resp[:facets]
+          res.facets = resp[:facets].each_with_object({}) do |(k, v), o|
+            facet = case options.facets[k]
+                    when SearchFacet::SearchFacetTerm
+                      SearchFacetResult::TermFacetResult.new do |f|
+                        f.terms =
+                          if v[:terms]
+                            v[:terms].map do |t|
+                              SearchFacetResult::TermFacetResult::TermFacet.new(t[:term], t[:count])
+                            end
+                          else
+                            []
+                          end
+                      end
+                    when SearchFacet::SearchFacetDateRange
+                      SearchFacetResult::DateRangeFacetResult.new do |f|
+                        f.date_ranges =
+                          if v[:date_ranges]
+                            v[:date_ranges].map do |r|
+                              SearchFacetResult::DateRangeFacetResult::DateRangeFacet.new(r[:name], r[:count], r[:start_time], r[:end_time])
+                            end
+                          else
+                            []
+                          end
+                      end
+                    when SearchFacet::SearchFacetNumericRange
+                      SearchFacetResult::NumericRangeFacetResult.new do |f|
+                        f.numeric_ranges =
+                          if v[:numeric_ranges]
+                            v[:numeric_ranges].map do |r|
+                              SearchFacetResult::NumericRangeFacetResult::NumericRangeFacet.new(r[:name], r[:count], r[:min], r[:max])
+                            end
+                          else
+                            []
+                          end
+                      end
+                    else
+                      next # ignore unknown facet result
                     end
-                  else
-                    next # ignore unknown facet result
-                  end
-          facet.name = v[:name]
-          facet.field = v[:field]
-          facet.total = v[:total]
-          facet.missing = v[:missing]
-          facet.other = v[:other]
-          o[k] = facet
+            facet.name = v[:name]
+            facet.field = v[:field]
+            facet.total = v[:total]
+            facet.missing = v[:missing]
+            facet.other = v[:other]
+            o[k] = facet
+          end
         end
       end
     end
@@ -262,31 +279,64 @@ module Couchbase
       Management::SearchIndexManager.new(@backend)
     end
 
+    # Closes all connections to services and free allocated resources
+    #
+    # @return [void]
     def disconnect
       @backend.close
     end
 
-    def diagnostics(options = DiagnosticsOptions.new) end
-
-    class ClusterOptions
-      attr_accessor :authenticator
-
-      def initialize
-        yield self if block_given?
-      end
-
-      def authenticate(username, password)
-        @authenticator = PasswordAuthenticator.new(username, password)
-        self
+    # Creates diagnostic report that can be used to determine the health of the network connections.
+    #
+    # It does not proactively perform any I/O against the network
+    #
+    # @param [Options::Diagnostics] options
+    #
+    # @return [DiagnosticsResult]
+    def diagnostics(options = Options::Diagnostics.new)
+      resp = @backend.diagnostics(options.report_id)
+      DiagnosticsResult.new do |res|
+        res.version = resp[:version]
+        res.id = resp[:id]
+        res.sdk = resp[:sdk]
+        resp[:services].each do |type, svcs|
+          res.services[type] = svcs.map do |svc|
+            DiagnosticsResult::ServiceInfo.new do |info|
+              info.id = svc[:id]
+              info.state = svc[:state]
+              info.last_activity_us = svc[:last_activity_us]
+              info.remote = svc[:remote]
+              info.local = svc[:local]
+              info.details = svc[:details]
+            end
+          end
+        end
       end
     end
 
-    class DiagnosticsOptions
-      # @return [String] Holds custom report id.
-      attr_accessor :report_id
-
-      def initialize
-        yield self if block_given?
+    # Performs application-level ping requests against services in the couchbase cluster
+    #
+    # @param [Options::Ping] options
+    #
+    # @return [PingResult]
+    def ping(options = Options::Ping.new)
+      resp = @backend.ping(nil, options.to_backend)
+      PingResult.new do |res|
+        res.version = resp[:version]
+        res.id = resp[:id]
+        res.sdk = resp[:sdk]
+        resp[:services].each do |type, svcs|
+          res.services[type] = svcs.map do |svc|
+            PingResult::ServiceInfo.new do |info|
+              info.id = svc[:id]
+              info.state = svc[:state]
+              info.latency = svc[:latency]
+              info.remote = svc[:remote]
+              info.local = svc[:local]
+              info.error = svc[:error]
+            end
+          end
+        end
       end
     end
 
@@ -294,20 +344,63 @@ module Couchbase
 
     # Initialize {Cluster} object
     #
-    # @param [String] connection_string connection string used to locate the Couchbase Cluster
-    # @param [ClusterOptions] options custom options when creating the cluster connection
-    def initialize(connection_string, options)
-      conn_info = Backend.parse_connection_string(connection_string)
-      raise ArgumentError, "missing hostname" if conn_info[:nodes].empty?
-      hostname = conn_info[:nodes].first[:address]
-      raise ArgumentError, "options must have authenticator configured" unless options.authenticator
-      username = options.authenticator.username
-      raise ArgumentError, "missing username" unless username
-      password = options.authenticator.password
-      raise ArgumentError, "missing password" unless password
+    # @overload new(connection_string, options)
+    #   @param [String] connection_string connection string used to locate the Couchbase Cluster
+    #   @param [Options::Cluster] options custom options when creating the cluster connection
+    #
+    # @overload new(connection_string, username, password, options)
+    #   Shortcut for {PasswordAuthenticator}
+    #   @param [String] connection_string connection string used to locate the Couchbase Cluster
+    #   @param [String] username name of the user
+    #   @param [String] password password of the user
+    #   @param [Options::Cluster, nil] options custom options when creating the cluster connection
+    def initialize(connection_string, *args)
+      credentials = {}
+
+      options = args.shift
+      case options
+      when String
+        credentials[:username] = options
+        credentials[:password] = args.shift
+        raise ArgumentError, "missing username" unless credentials[:username]
+        raise ArgumentError, "missing password" unless credentials[:password]
+      when Options::Cluster
+        authenticator = options&.authenticator
+        case authenticator
+        when PasswordAuthenticator
+          credentials[:username] = authenticator&.username
+          raise ArgumentError, "missing username" unless credentials[:username]
+
+          credentials[:password] = authenticator&.password
+          raise ArgumentError, "missing password" unless credentials[:password]
+
+        when CertificateAuthenticator
+          credentials[:certificate_path] = authenticator&.certificate_path
+          raise ArgumentError, "missing certificate path" unless credentials[:certificate_path]
+
+          credentials[:key_path] = authenticator&.key_path
+          raise ArgumentError, "missing key path" unless credentials[:key_path]
+
+        else
+          raise ArgumentError, "options must have authenticator configured"
+        end
+      else
+        raise ArgumentError, "unexpected second argument, have to be String or ClusterOptions"
+      end
 
       @backend = Backend.new
-      @backend.open(hostname, username, password)
+      @backend.open(connection_string, credentials, {})
     end
+
+    # @api private
+    ClusterOptions = ::Couchbase::Options::Cluster
+    # @api private
+    DiagnosticsOptions = ::Couchbase::Options::Diagnostics
+    # @api private
+    AnalyticsOptions = ::Couchbase::Options::Analytics
+    # @api private
+    QueryOptions = ::Couchbase::Options::Query
+    # @api private
+    SearchOptions = ::Couchbase::Options::Search
   end
 end