couchbase 3.0.1-universal-darwin-19 → 3.0.2-universal-darwin-19

data/lib/couchbase/bucket.rb

@@ -15,7 +15,9 @@
 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
@@ -67,29 +69,18 @@ module Couchbase
     #
     # @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 [ViewResult]
-    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,
-      })
+    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]
@@ -117,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,9 +21,12 @@ 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
@@ -33,14 +36,32 @@ module Couchbase
     #
     # @overload connect(connection_string, options)
     #   @param [String] connection_string connection string used to locate the Couchbase Cluster
-    #   @param [ClusterOptions] options custom options when creating the cluster connection
+    #   @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 [ClusterOptions, nil] options custom options when creating the cluster connection
+    #   @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)
@@ -59,30 +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,
-        flex_index: options.flex_index,
-        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.export_positional_parameters,
-        named_parameters: options.export_named_parameters,
-        scope_qualifier: options.scope_qualifier,
-        raw_parameters: options.raw_parameters,
-        scan_consistency: options.scan_consistency,
-        mutation_state: options.mutation_state&.to_a,
-      })
+    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|
@@ -112,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.export_positional_parameters,
-        named_parameters: options.export_named_parameters,
-        raw_parameters: options.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
@@ -156,24 +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,
-        disable_scoring: options.disable_scoring,
-        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.scan_consistency,
-        mutation_state: options.mutation_state&.to_a,
-      })
+    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|
@@ -293,10 +290,11 @@ module Couchbase
     #
     # It does not proactively perform any I/O against the network
     #
+    # @param [Options::Diagnostics] options
+    #
     # @return [DiagnosticsResult]
-    def diagnostics(options = DiagnosticsOptions.new)
+    def diagnostics(options = Options::Diagnostics.new)
       resp = @backend.diagnostics(options.report_id)
-      pp resp
       DiagnosticsResult.new do |res|
         res.version = resp[:version]
         res.id = resp[:id]
@@ -309,113 +307,37 @@ module Couchbase
               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 ClusterOptions
-      attr_accessor :authenticator
-
-      # @yieldparam [ClusterOptions] self
-      def initialize
-        yield self if block_given?
-      end
-
-      def authenticate(username, password)
-        @authenticator = PasswordAuthenticator.new(username, password)
-        self
-      end
-    end
-
-    class DiagnosticsOptions
-      # @return [String] Holds custom report id.
-      attr_accessor :report_id
-
-      # @yieldparam [DiagnosticsOptions] self
-      def initialize
-        yield self if block_given?
-      end
-    end
-
-    class DiagnosticsResult
-      class ServiceInfo
-        # @return [String] endpoint unique identifier
-        attr_accessor :id
-
-        # Possible states are:
-        #
-        # :disconnected:: the endpoint is not reachable
-        # :connecting:: currently connecting (includes auth, handshake, etc.)
-        # :connected:: connected and ready
-        # :disconnecting:: disconnecting (after being connected)
-        #
-        # @return [Symbol] state of the endpoint
-        attr_accessor :state
-
-        # @return [Integer] how long ago the endpoint was active (in microseconds)
-        attr_accessor :last_activity_us
-
-        # @return [String] remote address of the connection
-        attr_accessor :remote
-
-        # @return [String] local address of the connection
-        attr_accessor :local
-
-        # @yieldparam [ServiceInfo] self
-        def initialize
-          yield self if block_given?
-        end
-
-        def to_json(*args)
-          data = {
-            id: @id,
-            state: @state,
-            remote: @remote,
-            local: @local,
-          }
-          data[:last_activity_us] = @last_activity_us if defined? @last_activity_us
-          data.to_json(*args)
+    # 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
-
-      # @return [String] report id
-      attr_accessor :id
-
-      # @return [String] SDK identifier
-      attr_accessor :sdk
-
-      # Returns information about currently service endpoints, that known to the library at the moment.
-      #
-      # :kv:: Key/Value data service
-      # :query:: N1QL query service
-      # :analytics:: Analtyics service
-      # :search:: Full text search service
-      # :views:: Views service
-      # :mgmt:: Management service
-      #
-      # @return [Hash<Symbol, ServiceInfo>] map service types to info
-      attr_accessor :services
-
-      # @yieldparam [DiagnosticsResult] self
-      def initialize
-        @services = Hash.new
-        yield self if block_given?
-      end
-
-      # @api private
-      # @return [Integer] version
-      attr_accessor :version
-
-      def to_json(*args)
-        {
-          version: @version,
-          id: @id,
-          sdk: @sdk,
-          services: @services,
-        }.to_json(*args)
-      end
     end
 
     private
@@ -424,14 +346,14 @@ module Couchbase
     #
     # @overload new(connection_string, options)
     #   @param [String] connection_string connection string used to locate the Couchbase Cluster
-    #   @param [ClusterOptions] options custom options when creating the cluster connection
+    #   @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 [ClusterOptions, nil] options custom options when creating the cluster connection
+    #   @param [Options::Cluster, nil] options custom options when creating the cluster connection
     def initialize(connection_string, *args)
       credentials = {}
 
@@ -442,7 +364,7 @@ module Couchbase
         credentials[:password] = args.shift
         raise ArgumentError, "missing username" unless credentials[:username]
         raise ArgumentError, "missing password" unless credentials[:password]
-      when ClusterOptions
+      when Options::Cluster
         authenticator = options&.authenticator
         case authenticator
         when PasswordAuthenticator
@@ -469,5 +391,16 @@ module Couchbase
       @backend = Backend.new
       @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

data/lib/couchbase/collection.rb

@@ -45,18 +45,34 @@ module Couchbase
     # Fetches the full document from the collection
     #
     # @param [String] id the document id which is used to uniquely identify it
-    # @param [GetOptions] options request customization
+    # @param [Options::Get] options request customization
+    #
+    # @example Get document contents
+    #   res = collection.get("customer123")
+    #   res.content["addresses"]
+    #
+    #   # {"billing"=>
+    #   #   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"},
+    #   #  "delivery"=>
+    #   #   {"line1"=>"123 Any Street", "line2"=>"Anytown", "country"=>"United Kingdom"}}
+    #
+    # @example Get partial document using projections
+    #   res = collection.get("customer123", Options::Get(projections: ["name", "addresses.billing"]))
+    #   res.content
+    #
+    #   # {"addresses"=>
+    #   #    {"billing"=>
+    #   #      {"country"=>"United Kingdom",
+    #   #       "line1"=>"123 Any Street",
+    #   #       "line2"=>"Anytown"}},
+    #   #   "name"=>"Douglas Reynholm"}
     #
     # @return [GetResult]
-    def get(id, options = GetOptions.new)
+    def get(id, options = Options::Get.new)
       resp = if options.need_projected_get?
-               @backend.document_get_projected(bucket_name, "#{@scope_name}.#{@name}", id,
-                                               options.timeout,
-                                               options.with_expiry,
-                                               options.projections,
-                                               options.preserve_array_indexes)
+               @backend.document_get_projected(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
              else
-               @backend.document_get(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout)
+               @backend.document_get(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
              end
       GetResult.new do |res|
         res.transcoder = options.transcoder
@@ -67,15 +83,54 @@ module Couchbase
       end
     end
 
+    # Fetches multiple documents from the collection.
+    #
+    # @note that it will not generate {Error::DocumentNotFound} exceptions in this case. The caller should check
+    #  {GetResult#error} property of the result
+    #
+    # @param [Array<String>] ids the array of document identifiers
+    # @param [Options::GetMulti] options request customization
+    #
+    # @example Fetch "foo" and "bar" in a batch
+    #   res = collection.get(["foo", "bar"], Options::GetMulti(timeout: 3_000))
+    #   res[0].content #=> content of "foo"
+    #   res[1].content #=> content of "bar"
+    #
+    # @return [Array<GetResult>]
+    def get_multi(ids, options = Options::GetMulti.new)
+      collection_spec = "#{@scope_name}.#{@name}"
+      resp = @backend.document_get_multi(ids.map { |id| [bucket_name, collection_spec, id] }, options.to_backend)
+      resp.map do |entry|
+        GetResult.new do |res|
+          res.transcoder = options.transcoder
+          res.cas = entry[:cas]
+          res.flags = entry[:flags]
+          res.encoded = entry[:content]
+          res.error = entry[:error]
+        end
+      end
+    end
+
     # Fetches the full document and write-locks it for the given duration
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer] lock_time how long to lock the document (values over 30 seconds will be capped)
-    # @param [GetAndLockOptions] options request customization
+    # @param [Integer, #in_seconds] lock_time how long to lock the document (values over 30 seconds will be capped)
+    # @param [Options::GetAndLock] options request customization
+    #
+    # @example Retrieve document and lock for 10 seconds
+    #   collection.get_and_lock("customer123", 10, Options::GetAndLock(timeout: 3_000))
+    #
+    # @example Update document pessimistically
+    #   res = collection.get_and_lock("customer123", 10)
+    #   user_data = res.content
+    #   user_data["admin"] = true
+    #   collection.replace("user", user_data, Options::Upsert(cas: res.cas))
     #
     # @return [GetResult]
-    def get_and_lock(id, lock_time, options = GetAndLockOptions.new)
-      resp = @backend.document_get_and_lock(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, lock_time)
+    def get_and_lock(id, lock_time, options = Options::GetAndLock.new)
+      resp = @backend.document_get_and_lock(bucket_name, "#{@scope_name}.#{@name}", id,
+                                            lock_time.respond_to?(:in_seconds) ? lock_time.public_send(:in_seconds) : lock_time,
+                                            options.to_backend)
       GetResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
@@ -87,12 +142,17 @@ module Couchbase
     # Fetches a full document and resets its expiration time to the duration provided
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer] expiry the new expiration time for the document
-    # @param [GetAndTouchOptions] options request customization
+    # @param [Integer, #in_seconds] expiry the new expiration time for the document
+    # @param [Options::GetAndTouch] options request customization
+    #
+    # @example Retrieve document and prolong its expiration for another 10 seconds
+    #   collection.get_and_touch("customer123", 10)
     #
     # @return [GetResult]
-    def get_and_touch(id, expiry, options = GetAndTouchOptions.new)
-      resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, expiry)
+    def get_and_touch(id, expiry, options = Options::GetAndTouch.new)
+      resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id,
+                                             expiry.respond_to?(:in_seconds) ? expiry.public_send(:in_seconds) : expiry,
+                                             options.to_backend)
       GetResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
@@ -104,27 +164,31 @@ module Couchbase
     # Reads from all available replicas and the active node and returns the results
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [GetAllReplicasOptions] options request customization
+    # @param [Options::GetAllReplicas] options request customization
     #
     # @return [Array<GetReplicaResult>]
-    def get_all_replicas(id, options = GetAllReplicasOptions.new) end
+    def get_all_replicas(id, options = Options::GetAllReplicas.new) end
 
     # Reads all available replicas, and returns the first found
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [GetAnyReplicaOptions] options request customization
+    # @param [Options::GetAnyReplica] options request customization
     #
     # @return [GetReplicaResult]
-    def get_any_replica(id, options = GetAnyReplicaOptions.new) end
+    def get_any_replica(id, options = Options::GetAnyReplica.new) end
 
     # Checks if the given document ID exists on the active partition.
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [ExistsOptions] options request customization
+    # @param [Options::Exists] options request customization
+    #
+    # @example Check if the document exists without fetching its contents
+    #   res = collection.exists("customer123")
+    #   res.exists? #=> true
     #
     # @return [ExistsResult]
-    def exists(id, options = ExistsOptions.new)
-      resp = @backend.document_exists(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout)
+    def exists(id, options = Options::Exists.new)
+      resp = @backend.document_exists(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
       ExistsResult.new do |res|
         res.status = resp[:status]
         res.partition_id = resp[:partition_id]
@@ -135,32 +199,91 @@ module Couchbase
     # Removes a document from the collection
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [RemoveOptions] options request customization
+    # @param [Options::Remove] options request customization
+    #
+    # @example Remove the document in collection
+    #   res = collection.remove("customer123")
+    #   res.cas #=> 241994216651798
+    #
+    # @example Remove the document in collection, but apply optimistic lock
+    #   res = collection.upsert("mydoc", {"foo" => 42})
+    #   res.cas #=> 7751414725654
+    #
+    #   begin
+    #     res = collection.remove("mydoc", Options::Remove(cas: 3735928559))
+    #   rescue Error::CasMismatch
+    #     puts "Failed to remove the document, it might be changed by other application"
+    #   end
     #
     # @return [MutationResult]
-    def remove(id, options = RemoveOptions.new)
-      resp = @backend.document_remove(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, {
-        durability_level: options.durability_level,
-      })
+    def remove(id, options = Options::Remove.new)
+      resp = @backend.document_remove(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
         res.mutation_token = extract_mutation_token(resp)
       end
     end
 
+    # Removes a list of the documents from the collection
+    #
+    # @note that it will not generate {Error::DocumentNotFound} or {Error::CasMismatch} exceptions in this case.
+    #  The caller should check {MutationResult#error} property of the result
+    #
+    # @param [Array<String, Array>] ids the array of document ids, or ID/CAS pairs +[String,Integer]+
+    # @param [Options::RemoveMulti] options request customization
+    #
+    # @example Remove two documents in collection. For "mydoc" apply optimistic lock
+    #   res = collection.upsert("mydoc", {"foo" => 42})
+    #   res.cas #=> 7751414725654
+    #
+    #   res = collection.remove_multi(["foo", ["mydoc", res.cas]])
+    #   if res[1].error.is_a?(Error::CasMismatch)
+    #     puts "Failed to remove the document, it might be changed by other application"
+    #   end
+    #
+    # @return [Array<MutationResult>]
+    def remove_multi(ids, options = Options::RemoveMulti.new)
+      collection_spec = "#{@scope_name}.#{@name}"
+      resp = @backend.document_remove_multi(ids.map do |id|
+        case id
+        when String
+          [bucket_name, collection_spec, id, nil]
+        when Array
+          [bucket_name, collection_spec, id[0], id[1]]
+        else
+          raise ArgumentError, "id argument of remove_multi must be a String or Array<String, Integer>, given: #{id.inspect}"
+        end
+      end, options.to_backend)
+      resp.map do |entry|
+        MutationResult.new do |res|
+          res.cas = entry[:cas]
+          res.mutation_token = extract_mutation_token(entry)
+        end
+      end
+    end
+
     # Inserts a full document which does not exist yet
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Object] content the document content to insert
-    # @param [InsertOptions] options request customization
+    # @param [Options::Insert] options request customization
+    #
+    # @example Insert new document in collection
+    #   res = collection.insert("mydoc", {"foo" => 42}, Options::Insert(expiry: 20))
+    #   res.cas #=> 242287264414742
+    #
+    # @example Handle error when the document already exists
+    #   collection.exists("mydoc").exists? #=> true
+    #   begin
+    #     res = collection.insert("mydoc", {"foo" => 42})
+    #   rescue Error::DocumentExists
+    #     puts "Failed to insert the document, it already exists in the collection"
+    #   end
     #
     # @return [MutationResult]
-    def insert(id, content, options = InsertOptions.new)
-      blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_insert(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
-        durability_level: options.durability_level,
-        expiry: options.expiry,
-      })
+    def insert(id, content, options = Options::Insert.new)
+      blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
+      resp = @backend.document_insert(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
         res.mutation_token = extract_mutation_token(resp)
@@ -171,35 +294,69 @@ module Couchbase
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Object] content the document content to upsert
-    # @param [UpsertOptions] options request customization
+    # @param [Options::Upsert] options request customization
+    #
+    # @example Upsert new document in collection
+    #   res = collection.upsert("mydoc", {"foo" => 42}, Options::Upsert(expiry: 20))
+    #   res.cas #=> 242287264414742
     #
     # @return [MutationResult]
-    def upsert(id, content, options = UpsertOptions.new)
-      blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_upsert(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
-        durability_level: options.durability_level,
-        expiry: options.expiry,
-      })
+    def upsert(id, content, options = Options::Upsert.new)
+      blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
+      resp = @backend.document_upsert(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
         res.mutation_token = extract_mutation_token(resp)
       end
     end
 
+    # Upserts (inserts or updates) a list of documents which might or might not exist yet
+    #
+    # @note that it will not generate exceptions in this case. The caller should check {MutationResult#error} property of the
+    #  result
+    #
+    # @param [Array<Array>] id_content array of tuples +String,Object+, where first entry treated as document key,
+    #   and the second as value to upsert.
+    # @param [Options::UpsertMulti] options request customization
+    #
+    # @example Upsert two documents with IDs "foo" and "bar" into a collection
+    #   res = collection.upsert_multi([
+    #     "foo", {"foo" => 42},
+    #     "bar", {"bar" => "some value"}
+    #   ])
+    #   res[0].cas #=> 7751414725654
+    #   res[1].cas #=> 7751418925851
+    #
+    # @return [Array<MutationResult>]
+    def upsert_multi(id_content, options = Options::UpsertMulti.new)
+      collection_spec = "#{@scope_name}.#{@name}"
+      resp = @backend.document_upsert_multi(id_content.map do |(id, content)|
+        blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
+        [bucket_name, collection_spec, id, blob, flags]
+      end, options.to_backend)
+      resp.map do |entry|
+        MutationResult.new do |res|
+          res.cas = entry[:cas]
+          res.mutation_token = extract_mutation_token(entry)
+        end
+      end
+    end
+
     # Replaces a full document which already exists
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Object] content the document content to upsert
-    # @param [ReplaceOptions] options request customization
+    # @param [Options::Replace] options request customization
+    #
+    # @example Replace new document in collection with optimistic locking
+    #   res = collection.get("mydoc")
+    #   res = collection.replace("mydoc", {"foo" => 42}, Options::Replace(cas: res.cas))
+    #   res.cas #=> 242287264414742
     #
     # @return [MutationResult]
-    def replace(id, content, options = ReplaceOptions.new)
-      blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_replace(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
-        durability_level: options.durability_level,
-        expiry: options.expiry,
-        cas: options.cas,
-      })
+    def replace(id, content, options = Options::Replace.new)
+      blob, flags = options.transcoder ? options.transcoder.encode(content) : [content, 0]
+      resp = @backend.document_replace(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
         res.mutation_token = extract_mutation_token(resp)
@@ -209,12 +366,17 @@ module Couchbase
     # Update the expiration of the document with the given id
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer] expiry new expiration time for the document
-    # @param [TouchOptions] options request customization
+    # @param [Integer, #in_seconds] expiry new expiration time for the document
+    # @param [Options::Touch] options request customization
+    #
+    # @example Reset expiration timer for document to 30 seconds
+    #   res = collection.touch("customer123", 30)
     #
     # @return [MutationResult]
-    def touch(id, expiry, options = TouchOptions.new)
-      resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, expiry)
+    def touch(id, expiry, options = Options::Touch.new)
+      resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id,
+                                     expiry.respond_to?(:in_seconds) ? expiry.public_send(:in_seconds) : expiry,
+                                     options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
       end
@@ -224,34 +386,47 @@ module Couchbase
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Integer] cas CAS value which is needed to unlock the document
-    # @param [UnlockOptions] options request customization
+    # @param [Options::Unlock] options request customization
+    #
+    # @example Lock (pessimistically) and unlock document
+    #   res = collection.get_and_lock("customer123", 10)
+    #   collection.unlock("customer123", res.cas)
+    #
+    # @return [void]
     #
     # @raise [Error::DocumentNotFound]
-    def unlock(id, cas, options = UnlockOptions.new)
-      @backend.document_unlock(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, cas)
+    def unlock(id, cas, options = Options::Unlock.new)
+      @backend.document_unlock(bucket_name, "#{@scope_name}.#{@name}", id, cas, options.to_backend)
     end
 
     # Performs lookups to document fragments
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Array<LookupInSpec>] specs the list of specifications which describe the types of the lookups to perform
-    # @param [LookupInOptions] options request customization
+    # @param [Options::LookupIn] options request customization
+    #
+    # @example Get list of IDs of completed purchases
+    #   lookup_specs = [
+    #     LookupInSpec::get("purchases.complete")
+    #   ]
+    #   collection.lookup_in("customer123", lookup_specs)
     #
     # @return [LookupInResult]
-    def lookup_in(id, specs, options = LookupInOptions.new)
+    def lookup_in(id, specs, options = Options::LookupIn.new)
       resp = @backend.document_lookup_in(
-        bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, options.access_deleted,
+        bucket_name, "#{@scope_name}.#{@name}", id,
         specs.map do |s|
           {
             opcode: s.type,
             xattr: s.xattr?,
             path: s.path,
           }
-        end
+        end, options.to_backend
       )
       LookupInResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
+        res.deleted = resp[:deleted]
         res.encoded = resp[:fields].map do |field|
           SubDocumentField.new do |f|
             f.exists = field[:exists]
@@ -270,12 +445,18 @@ module Couchbase
     #
     # @param [String] id the document id which is used to uniquely identify it.
     # @param [Array<MutateInSpec>] specs the list of specifications which describe the types of the lookups to perform
-    # @param [MutateInOptions] options request customization
+    # @param [Options::MutateIn] options request customization
+    #
+    # @example Append number into subarray of the document
+    #   mutation_specs = [
+    #     MutateInSpec::array_append("purchases.complete", [42])
+    #   ]
+    #   collection.mutate_in("customer123", mutation_specs, Options::MutateIn(expiry: 10))
     #
     # @return [MutateInResult]
-    def mutate_in(id, specs, options = MutateInOptions.new)
+    def mutate_in(id, specs, options = Options::MutateIn.new)
       resp = @backend.document_mutate_in(
-        bucket_name, "#{@scope_name}.#{@name}", id, options.timeout,
+        bucket_name, "#{@scope_name}.#{@name}", id,
         specs.map do |s|
           {
             opcode: s.type,
@@ -285,18 +466,12 @@ module Couchbase
             expand_macros: s.expand_macros?,
             create_path: s.create_path?,
           }
-        end,
-        {
-          durability_level: options.durability_level,
-          store_semantics: options.store_semantics,
-          access_deleted: options.access_deleted,
-          cas: options.cas,
-          expiry: options.expiry,
-        }
+        end, options.to_backend
       )
       result = MutateInResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
+        res.deleted = resp[:deleted]
         res.mutation_token = extract_mutation_token(resp)
         res.first_error_index = resp[:first_error_index]
         res.encoded = resp[:fields].map do |field|
@@ -325,5 +500,48 @@ module Couchbase
         token.bucket_name = resp[:mutation_token][:bucket_name]
       end
     end
+
+    # @api private
+    # TODO: deprecate in 3.1
+    GetOptions = ::Couchbase::Options::Get
+    # @api private
+    # TODO: deprecate in 3.1
+    GetAndLockOptions = ::Couchbase::Options::GetAndLock
+    # @api private
+    # TODO: deprecate in 3.1
+    GetAndTouchOptions = ::Couchbase::Options::GetAndTouch
+    # @api private
+    # TODO: deprecate in 3.1
+    LookupInOptions = ::Couchbase::Options::LookupIn
+    # @api private
+    # TODO: deprecate in 3.1
+    MutateInOptions = ::Couchbase::Options::MutateIn
+    # @api private
+    # TODO: deprecate in 3.1
+    UnlockOptions = ::Couchbase::Options::Unlock
+    # @api private
+    # TODO: deprecate in 3.1
+    TouchOptions = ::Couchbase::Options::Touch
+    # @api private
+    # TODO: deprecate in 3.1
+    ReplaceOptions = ::Couchbase::Options::Replace
+    # @api private
+    # TODO: deprecate in 3.1
+    UpsertOptions = ::Couchbase::Options::Upsert
+    # @api private
+    # TODO: deprecate in 3.1
+    InsertOptions = ::Couchbase::Options::Insert
+    # @api private
+    # TODO: deprecate in 3.1
+    RemoveOptions = ::Couchbase::Options::Remove
+    # @api private
+    # TODO: deprecate in 3.1
+    ExistsOptions = ::Couchbase::Options::Exists
+    # @api private
+    # TODO: deprecate in 3.1
+    GetAnyReplicaOptions = ::Couchbase::Options::GetAnyReplica
+    # @api private
+    # TODO: deprecate in 3.1
+    GetAllReplicasOptions = ::Couchbase::Options::GetAllReplicas
   end
 end