couchbase 3.0.0.alpha.5-x86_64-linux → 3.5.0-x86_64-linux

data/lib/couchbase/authenticator.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -13,13 +13,52 @@
 #  limitations under the License.
 
 module Couchbase
+  # Authenticator for username/password credentials
   class PasswordAuthenticator
+    DEFAULT_SASL_MECHANISMS = [:scram_sha512, :scram_sha256, :scram_sha1].freeze
+
     attr_accessor :username
     attr_accessor :password
+    attr_accessor :allowed_sasl_mechanisms
 
+    # Creates a new password authenticator with the default settings.
+    #
+    # @param [String] password the username to use for all authentication requests
+    # @param [String] username the password
     def initialize(username, password)
       @username = username
       @password = password
     end
+
+    # Creates a LDAP compatible password authenticator which is INSECURE if not used with TLS.
+    #
+    # Please note that this is INSECURE and will leak user credentials on the wire to eavesdroppers. This should
+    # only be enabled in trusted environments.
+    #
+    # @param [String] username the username to use for all authentication.
+    # @param [String] password the password to use alongside the username.
+    # @return [PasswordAuthenticator]
+    def self.ldap_compatible(username, password)
+      new(username, password).tap do |auth|
+        auth.allowed_sasl_mechanisms = [:plain]
+      end
+    end
+  end
+
+  # Authenticator for TLS client certificate
+  #
+  # @see https://docs.couchbase.com/server/current/manage/manage-security/configure-client-certificates.html
+  class CertificateAuthenticator
+    attr_accessor :certificate_path
+    attr_accessor :key_path
+
+    # Creates a new authenticator with certificate and key paths
+    #
+    # @param [String] certificate_path path to certificate
+    # @param [String] key_path path to private key
+    def initialize(certificate_path, key_path)
+      @certificate_path = certificate_path
+      @key_path = key_path
+    end
   end
 end

data/lib/couchbase/binary_collection.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -12,51 +12,77 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require "couchbase/options"
 require "couchbase/binary_collection_options"
 
 module Couchbase
+  # Allows to perform certain operations on non-JSON documents.
   class BinaryCollection
-    alias_method :inspect, :to_s
+    alias inspect to_s
 
     # @param [Couchbase::Collection] collection parent collection
     def initialize(collection)
       @collection = collection
-      @backend = collection.instance_variable_get("@backend")
+      @backend = collection.instance_variable_get(:@backend)
     end
 
     # Appends binary content to the document
     #
     # @param [String] id the document id which is used to uniquely identify it
     # @param [String] content the binary content to append to the document
-    # @param [AppendOptions] options custom options to customize the request
+    # @param [Options::Append] options custom options to customize the request
+    #
+    # @example Append "bar" to the content of the existing document
+    #   collection.upsert("mydoc", "foo")
+    #   collection.binary.append("mydoc", "bar", Options::Append(timeout: 3_000))
+    #   collection.get("mydoc", Options::Get(transcoder: nil)).content #=> "foobar"
     #
     # @return [Collection::MutationResult]
-    def append(id, content, options = AppendOptions.new) end
+    def append(id, content, options = Options::Append::DEFAULT)
+      resp = @backend.document_append(@collection.bucket_name, @collection.scope_name, @collection.name,
+                                      id, content, options.to_backend)
+      Collection::MutationResult.new do |res|
+        res.cas = resp[:cas]
+        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      end
+    end
 
     # Prepends binary content to the document
     #
     # @param [String] id the document id which is used to uniquely identify it
     # @param [String] content the binary content to prepend to the document
-    # @param [PrependOptions] options custom options to customize the request
+    # @param [Options::Prepend] options custom options to customize the request
+    #
+    # @example Prepend "bar" to the content of the existing document
+    #   collection.upsert("mydoc", "foo")
+    #   collection.binary.prepend("mydoc", "bar", Options::Prepend(timeout: 3_000))
+    #   collection.get("mydoc", Options::Get(transcoder: nil)).content #=> "barfoo"
     #
     # @return [Collection::MutationResult]
-    def prepend(id, content, options = PrependOptions.new) end
+    def prepend(id, content, options = Options::Prepend::DEFAULT)
+      resp = @backend.document_prepend(@collection.bucket_name, @collection.scope_name, @collection.name,
+                                       id, content, options.to_backend)
+      Collection::MutationResult.new do |res|
+        res.cas = resp[:cas]
+        res.mutation_token = @collection.send(:extract_mutation_token, resp)
+      end
+    end
 
     # Increments the counter document by one of the number defined in the options
     #
     # @param [String] id the document id which is used to uniquely identify it
-    # @param [IncrementOptions] options custom options to customize the request
+    # @param [Options::Increment] options custom options to customize the request
+    #
+    # @example Increment value by 10, and initialize to 0 if it does not exist
+    #   res = collection.binary.increment("raw_counter", Options::Increment(delta: 10, initial: 0))
+    #   res.content #=> 0
+    #   res = collection.binary.increment("raw_counter", Options::Increment(delta: 10, initial: 0))
+    #   res.content #=> 10
     #
     # @return [CounterResult]
-    def increment(id, options = IncrementOptions.new)
-      resp = @backend.document_increment(@collection.bucket_name, "#{@collection.scope_name}.#{@collection.name}", id,
-                                         options.timeout,
-                                         {
-                                             delta: options.delta,
-                                             initial_value: options.initial,
-                                             expiration: options.expiration,
-                                             durability_level: options.durability_level,
-                                         })
+    def increment(id, options = Options::Increment::DEFAULT)
+      resp = @backend.document_increment(@collection.bucket_name, @collection.scope_name, @collection.name, id,
+                                         options.to_backend)
       CounterResult.new do |res|
         res.cas = resp[:cas]
         res.content = resp[:content]
@@ -67,23 +93,36 @@ module Couchbase
     # Decrements the counter document by one of the number defined in the options
     #
     # @param [String] id the document id which is used to uniquely identify it
-    # @param [DecrementOptions] options custom options to customize the request
+    # @param [Options::Decrement] options custom options to customize the request
+    #
+    # @example Decrement value by 2, and initialize to 100 if it does not exist
+    #   res = collection.binary.decrement("raw_counter", Options::Decrement(delta: 2, initial: 100))
+    #   res.value #=> 100
+    #   res = collection.binary.decrement("raw_counter", Options::Decrement(delta: 2, initial: 100))
+    #   res.value #=> 98
     #
     # @return [CounterResult]
-    def decrement(id, options = DecrementOptions.new)
-      resp = @backend.document_decrement(@collection.bucket_name, "#{@collection.scope_name}.#{@collection.name}", id,
-                                         options.timeout,
-                                         {
-                                             delta: options.delta,
-                                             initial_value: options.initial,
-                                             expiration: options.expiration,
-                                             durability_level: options.durability_level,
-                                         })
+    def decrement(id, options = Options::Decrement::DEFAULT)
+      resp = @backend.document_decrement(@collection.bucket_name, @collection.scope_name, @collection.name, id,
+                                         options.to_backend)
       CounterResult.new do |res|
         res.cas = resp[:cas]
         res.content = resp[:content]
         res.mutation_token = @collection.send(:extract_mutation_token, resp)
       end
     end
+
+    # @api private
+    # TODO: deprecate in 3.1
+    AppendOptions = ::Couchbase::Options::Append
+    # @api private
+    # TODO: deprecate in 3.1
+    PrependOptions = ::Couchbase::Options::Prepend
+    # @api private
+    # TODO: deprecate in 3.1
+    IncrementOptions = ::Couchbase::Options::Increment
+    # @api private
+    # TODO: deprecate in 3.1
+    DecrementOptions = ::Couchbase::Options::Decrement
   end
 end

data/lib/couchbase/binary_collection_options.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -16,80 +16,6 @@ require "couchbase/collection_options"
 
 module Couchbase
   class BinaryCollection
-    class AppendOptions < CommonOptions
-      # @return [Integer] The default CAS used (0 means no CAS in this context)
-      attr_accessor :cas
-
-      # @yieldparam [AppendOptions] self
-      def initialize
-        yield self if block_given?
-      end
-    end
-
-    class PrependOptions < CommonOptions
-      # @return [Integer] The default CAS used (0 means no CAS in this context)
-      attr_accessor :cas
-
-      # @yieldparam [PrependOptions] self
-      def initialize
-        yield self if block_given?
-      end
-    end
-
-    class IncrementOptions < CommonOptions
-      # @return [Integer] the delta for the operation
-      attr_reader :delta
-
-      # @return [Integer] if present, holds the initial value
-      attr_accessor :initial
-
-      # @return [Integer] if set, holds the expiration for the operation
-      attr_accessor :expiration
-
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
-
-      # @yieldparam [IncrementOptions] self
-      def initialize
-        @delta = 1
-        yield self if block_given?
-      end
-
-      def delta=(value)
-        if delta < 0
-          raise ArgumentError, "the delta cannot be less than 0"
-        end
-        @delta = value
-      end
-    end
-
-    class DecrementOptions < CommonOptions
-      # @return [Integer] the delta for the operation
-      attr_reader :delta
-
-      # @return [Integer] if present, holds the initial value
-      attr_accessor :initial
-
-      # @return [Integer] if set, holds the expiration for the operation
-      attr_accessor :expiration
-
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
-
-      # @yieldparam [DecrementOptions] self
-      def initialize
-        @delta = 1
-        yield self if block_given?
-      end
-
-      def delta=(value)
-        if delta < 0
-          raise ArgumentError, "the delta cannot be less than 0"
-        end
-        @delta = value
-      end
-    end
-
     class CounterResult < ::Couchbase::Collection::MutationResult
       # @return [Integer] current value of the counter
       attr_accessor :content

data/lib/couchbase/bucket.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -15,18 +15,21 @@
 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
+  # Provides access to a Couchbase bucket APIs
   class Bucket
     # @return [String] name of the bucket
     attr_reader :name
 
-    alias_method :inspect, :to_s
+    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
@@ -35,7 +38,7 @@ module Couchbase
     #
     # @return [Scope]
     def default_scope
-      Scope.new(@backend, @name, :_default)
+      Scope.new(@backend, @name, "_default")
     end
 
     # Get a named scope
@@ -60,36 +63,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
     #
-    # @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,
-      })
+    # @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 [ViewResult]
+    def view_query(design_document_name, view_name, options = Options::View::DEFAULT)
+      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]
@@ -117,23 +109,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::DEFAULT)
+      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