couchbase 3.0.3-universal-darwin-20

data/lib/couchbase/cluster.rb

@@ -0,0 +1,430 @@
+#    Copyright 2020 Couchbase, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "couchbase/configuration"
+require "couchbase/authenticator"
+require "couchbase/bucket"
+
+require "couchbase/management"
+require "couchbase/options"
+
+require "couchbase/search_options"
+require "couchbase/query_options"
+require "couchbase/analytics_options"
+require "couchbase/diagnostics"
+
+module Couchbase
+  # The main entry point when connecting to a Couchbase cluster.
+  class Cluster
+    alias inspect to_s
+
+    # Connect to the Couchbase cluster
+    #
+    # @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)
+    end
+
+    # Returns an instance of the {Bucket}
+    #
+    # @param [String] name name of the bucket
+    #
+    # @return [Bucket]
+    def bucket(name)
+      Bucket.new(@backend, name)
+    end
+
+    # Performs a query against the query (N1QL) services
+    #
+    # @param [String] statement the N1QL query statement
+    # @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))
+    #
+    # @example Execute query with consistency requirement. Make sure that the index is in sync with selected mutation
+    #   res = collection.upsert("user:42", {
+    #     "name" => "Brass Doorknob",
+    #     "email" => "brass.doorknob@example.com",
+    #   })
+    #   cluster.query("SELECT name, email FROM `mybucket`",
+    #                 Options::Query(consistent_with: MutationState.new(res.mutation_token)))
+    #
+    # @return [QueryResult]
+    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|
+          meta.status = resp[:meta][:status]
+          meta.request_id = resp[:meta][:request_id]
+          meta.client_context_id = resp[:meta][:client_context_id]
+          meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
+          meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
+          meta.metrics = QueryMetrics.new do |metrics|
+            if resp[:meta][:metrics]
+              metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
+              metrics.execution_time = resp[:meta][:metrics][:execution_time]
+              metrics.sort_count = resp[:meta][:metrics][:sort_count]
+              metrics.result_count = resp[:meta][:metrics][:result_count]
+              metrics.result_size = resp[:meta][:metrics][:result_size]
+              metrics.mutation_count = resp[:meta][:metrics][:mutation_count]
+              metrics.error_count = resp[:meta][:metrics][:error_count]
+              metrics.warning_count = resp[:meta][:metrics][:warning_count]
+            end
+          end
+          res[:warnings] = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+        end
+        res.instance_variable_set("@rows", resp[:rows])
+      end
+    end
+
+    # Performs an analytics query
+    #
+    # @param [String] statement the N1QL query statement
+    # @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 = Options::Analytics.new)
+      resp = @backend.document_analytics(statement, options.to_backend)
+
+      AnalyticsResult.new do |res|
+        res.transcoder = options.transcoder
+        res.meta_data = AnalyticsMetaData.new do |meta|
+          meta.status = resp[:meta][:status]
+          meta.request_id = resp[:meta][:request_id]
+          meta.client_context_id = resp[:meta][:client_context_id]
+          meta.signature = JSON.parse(resp[:meta][:signature]) if resp[:meta][:signature]
+          meta.profile = JSON.parse(resp[:meta][:profile]) if resp[:meta][:profile]
+          meta.metrics = AnalyticsMetrics.new do |metrics|
+            if resp[:meta][:metrics]
+              metrics.elapsed_time = resp[:meta][:metrics][:elapsed_time]
+              metrics.execution_time = resp[:meta][:metrics][:execution_time]
+              metrics.result_count = resp[:meta][:metrics][:result_count]
+              metrics.result_size = resp[:meta][:metrics][:result_size]
+              metrics.error_count = resp[:meta][:metrics][:error_count]
+              metrics.warning_count = resp[:meta][:metrics][:warning_count]
+              metrics.processed_objects = resp[:meta][:metrics][:processed_objects]
+            end
+          end
+          res[:warnings] = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+        end
+        res.instance_variable_set("@rows", resp[:rows])
+      end
+    end
+
+    # Performs a Full Text Search (FTS) query
+    #
+    # @param [String] index_name the name of the search index
+    # @param [SearchQuery] query 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 = 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|
+          meta.metrics.max_score = resp[:meta_data][:metrics][:max_score]
+          meta.metrics.error_partition_count = resp[:meta_data][:metrics][:error_partition_count]
+          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|
+            row.transcoder = options.transcoder
+            row.index = r[:index]
+            row.id = r[:id]
+            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
+              end
+            )
+            row.instance_variable_set("@fields", r[:fields])
+            row.explanation = JSON.parse(r[:explanation]) if r[:explanation]
+          end
+        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
+            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
+
+    # @return [Management::UserManager]
+    def users
+      Management::UserManager.new(@backend)
+    end
+
+    # @return [Management::BucketManager]
+    def buckets
+      Management::BucketManager.new(@backend)
+    end
+
+    # @return [Management::QueryIndexManager]
+    def query_indexes
+      Management::QueryIndexManager.new(@backend)
+    end
+
+    # @return [Management::AnalyticsIndexManager]
+    def analytics_indexes
+      Management::AnalyticsIndexManager.new(@backend)
+    end
+
+    # @return [Management::SearchIndexManager]
+    def search_indexes
+      Management::SearchIndexManager.new(@backend)
+    end
+
+    # Closes all connections to services and free allocated resources
+    #
+    # @return [void]
+    def disconnect
+      @backend.close
+    end
+
+    # 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
+
+    # 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
+
+    private
+
+    # Initialize {Cluster} object
+    #
+    # @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
+    #
+    # @overload new(configuration)
+    #   @param [Configuration] configuration configuration object
+    def initialize(connection_string, *args)
+      credentials = {}
+      open_options = {}
+
+      if connection_string.is_a?(Configuration)
+        options = connection_string
+        connection_string = options.connection_string
+        credentials[:username] = options.username
+        credentials[:password] = options.password
+        raise ArgumentError, "missing connection_string" unless connection_string
+        raise ArgumentError, "missing username" unless credentials[:username]
+        raise ArgumentError, "missing password" unless credentials[:password]
+
+        open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
+      else
+        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]
+
+          open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
+        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]
+
+            open_options[:allowed_sasl_mechanisms] = authenticator&.allowed_sasl_mechanisms
+          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
+      end
+
+      @backend = Backend.new
+      @backend.open(connection_string, credentials, open_options)
+    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

@@ -0,0 +1,562 @@
+#    Copyright 2020 Couchbase, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "couchbase/errors"
+require "couchbase/collection_options"
+require "couchbase/binary_collection"
+
+module Couchbase
+  # Provides access to all collection APIs
+  class Collection
+    attr_reader :bucket_name
+    attr_reader :scope_name
+    attr_reader :name
+
+    alias inspect to_s
+
+    # @param [Couchbase::Backend] backend
+    # @param [String] bucket_name name of the bucket
+    # @param [String, :_default] scope_name name of the scope
+    # @param [String, :_default] collection_name name of the collection
+    def initialize(backend, bucket_name, scope_name, collection_name)
+      @backend = backend
+      @bucket_name = bucket_name
+      @scope_name = scope_name
+      @name = collection_name
+    end
+
+    # Provides access to the binary APIs, not used for JSON documents
+    #
+    # @return [BinaryCollection]
+    def binary
+      BinaryCollection.new(self)
+    end
+
+    # Fetches the full document from the collection
+    #
+    # @param [String] id the document id which is used to uniquely identify it
+    # @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 = Options::Get.new)
+      resp = if options.need_projected_get?
+               @backend.document_get_projected(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
+             else
+               @backend.document_get(bucket_name, "#{@scope_name}.#{@name}", id, options.to_backend)
+             end
+      GetResult.new do |res|
+        res.transcoder = options.transcoder
+        res.cas = resp[:cas]
+        res.flags = resp[:flags]
+        res.encoded = resp[:content]
+        res.expiry = resp[:expiry] if resp.key?(:expiry)
+      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, #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 = 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]
+        res.flags = resp[:flags]
+        res.encoded = resp[:content]
+      end
+    end
+
+    # 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, #in_seconds, Time] 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 = Options::GetAndTouch.new)
+      resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id,
+                                             Utils::Time.extract_expiry_time(expiry),
+                                             options.to_backend)
+      GetResult.new do |res|
+        res.transcoder = options.transcoder
+        res.cas = resp[:cas]
+        res.flags = resp[:flags]
+        res.encoded = resp[:content]
+      end
+    end
+
+    # 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 [Options::GetAllReplicas] options request customization
+    #
+    # @return [Array<GetReplicaResult>]
+    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 [Options::GetAnyReplica] options request customization
+    #
+    # @return [GetReplicaResult]
+    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 [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 = 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]
+        res.cas = resp[:cas] if res.status != :not_found
+      end
+    end
+
+    # Removes a document from the collection
+    #
+    # @param [String] id the document id which is used to uniquely identify it.
+    # @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 = 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)
+          res.error = entry[:error]
+        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 [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 = 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)
+      end
+    end
+
+    # Upserts (inserts or updates) a full document which might or might not exist yet
+    #
+    # @param [String] id the document id which is used to uniquely identify it.
+    # @param [Object] content the document content to upsert
+    # @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 = 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)
+          res.error = entry[:error]
+        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 [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 = 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)
+      end
+    end
+
+    # 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, #in_seconds, Time] 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 = Options::Touch.new)
+      resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id,
+                                     Utils::Time.extract_expiry_time(expiry),
+                                     options.to_backend)
+      MutationResult.new do |res|
+        res.cas = resp[:cas]
+      end
+    end
+
+    # Unlocks a document if it has been locked previously
+    #
+    # @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 [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 = 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 [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)
+    #
+    # @example Retrieve country name and check if pending purchases array is empty
+    #   collection.lookup_in "customer123", [
+    #     LookupInSpec.get("addresses.delivery.country"),
+    #     LookupInSpec.exists("purchases.pending[-1]"),
+    #   ]
+    # @return [LookupInResult]
+    def lookup_in(id, specs, options = Options::LookupIn.new)
+      resp = @backend.document_lookup_in(
+        bucket_name, "#{@scope_name}.#{@name}", id,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            xattr: s.xattr?,
+            path: s.path,
+          }
+        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]
+            f.index = field[:index]
+            f.path = field[:path]
+            f.status = field[:status]
+            f.error = field[:error]
+            f.value = field[:value]
+            f.type = field[:type]
+          end
+        end
+      end
+    end
+
+    # Performs mutations to document fragments
+    #
+    # @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 [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))
+    #
+    # @example Write meta attribute, remove array entry and replace email field
+    #   collection.mutate_in("customer123", [
+    #     MutateInSpec.upsert("_framework.model_type", "Customer").xattr,
+    #     MutateInSpec.remove("addresses.billing[2]"),
+    #     MutateInSpec.replace("email", "dougr96@hotmail.com"),
+    #   ])
+    #
+    # @return [MutateInResult]
+    def mutate_in(id, specs, options = Options::MutateIn.new)
+      resp = @backend.document_mutate_in(
+        bucket_name, "#{@scope_name}.#{@name}", id,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            path: s.path,
+            param: s.param,
+            xattr: s.xattr?,
+            expand_macros: s.expand_macros?,
+            create_path: s.create_path?,
+          }
+        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|
+          SubDocumentField.new do |f|
+            f.exists = field[:exists]
+            f.path = field[:path]
+            f.status = field[:status]
+            f.error = field[:error]
+            f.value = field[:value]
+            f.type = field[:type]
+          end
+        end
+      end
+      raise result.first_error unless result.success?
+
+      result
+    end
+
+    private
+
+    def extract_mutation_token(resp)
+      MutationToken.new do |token|
+        token.partition_id = resp[:mutation_token][:partition_id]
+        token.partition_uuid = resp[:mutation_token][:partition_uuid]
+        token.sequence_number = resp[:mutation_token][:sequence_number]
+        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