couchbase 3.0.2 → 3.0.3

data/ext/couchbase/protocol/client_request.hxx

@@ -27,6 +27,7 @@
 #include <protocol/client_opcode.hxx>
 #include <protocol/magic.hxx>
 #include <protocol/client_response.hxx>
+#include <utils/byteswap.hxx>
 
 namespace couchbase::protocol
 {
@@ -61,7 +62,7 @@ class client_request
 
     void cas(std::uint64_t val)
     {
-        cas_ = val;
+        cas_ = utils::byte_swap_64(val);
     }
 
     std::uint32_t opaque()

data/ext/couchbase/protocol/client_response.hxx

@@ -27,15 +27,12 @@
 #include <protocol/datatype.hxx>
 #include <protocol/cmd_info.hxx>
 #include <protocol/frame_info_id.hxx>
+#include <protocol/enhanced_error_info.hxx>
+#include <utils/byteswap.hxx>
 
 namespace couchbase::protocol
 {
 
-struct enhanced_error {
-    std::string context;
-    std::string ref;
-};
-
 template<typename Body>
 class client_response
 {
@@ -51,7 +48,7 @@ class client_response
     std::uint8_t extras_size_{ 0 };
     std::size_t body_size_{ 0 };
     protocol::status status_{};
-    std::optional<enhanced_error> error_;
+    std::optional<enhanced_error_info> error_;
     std::uint32_t opaque_{};
     std::uint64_t cas_{};
     cmd_info info_{};
@@ -138,9 +135,15 @@ class client_response
         memcpy(&opaque_, header_.data() + 12, sizeof(opaque_));
 
         memcpy(&cas_, header_.data() + 16, sizeof(cas_));
+        cas_ = utils::byte_swap_64(cas_);
+    }
+
+    [[nodiscard]] std::optional<enhanced_error_info> error_info()
+    {
+        return error_;
     }
 
-    std::string error_message()
+    [[nodiscard]] std::string error_message()
     {
         if (error_) {
             return fmt::format(R"(magic={}, opcode={}, status={}, error={})", magic_, opcode_, status_, *error_);
@@ -157,10 +160,10 @@ class client_response
             if (error.is_object()) {
                 auto& err_obj = error["error"];
                 if (err_obj.is_object()) {
-                    enhanced_error err{};
+                    enhanced_error_info err{};
                     auto& ref = err_obj["ref"];
                     if (ref.is_string()) {
-                        err.ref = ref.get_string();
+                        err.reference = ref.get_string();
                     }
                     auto& ctx = err_obj["context"];
                     if (ctx.is_string()) {
@@ -202,14 +205,14 @@ class client_response
 } // namespace couchbase::protocol
 
 template<>
-struct fmt::formatter<couchbase::protocol::enhanced_error> : formatter<std::string> {
+struct fmt::formatter<couchbase::protocol::enhanced_error_info> : formatter<std::string> {
     template<typename FormatContext>
-    auto format(const couchbase::protocol::enhanced_error& error, FormatContext& ctx)
+    auto format(const couchbase::protocol::enhanced_error_info& error, FormatContext& ctx)
     {
-        if (!error.ref.empty() && !error.context.empty()) {
-            format_to(ctx.out(), R"((ref: "{}", ctx: "{}"))", error.ref, error.context);
-        } else if (!error.ref.empty()) {
-            format_to(ctx.out(), R"((ref: "{}"))", error.ref);
+        if (!error.reference.empty() && !error.context.empty()) {
+            format_to(ctx.out(), R"((ref: "{}", ctx: "{}"))", error.reference, error.context);
+        } else if (!error.reference.empty()) {
+            format_to(ctx.out(), R"((ref: "{}"))", error.reference);
         } else if (!error.context.empty()) {
             format_to(ctx.out(), R"((ctx: "{}"))", error.context);
         }

data/ext/couchbase/protocol/cmd_exists.hxx

@@ -87,6 +87,7 @@ class exists_response_body
             offset++;
 
             memcpy(&cas_, body.data() + offset, sizeof(cas_));
+            cas_ = utils::byte_swap_64(cas_);
         }
         return false;
     }

data/ext/couchbase/protocol/cmd_get.hxx

@@ -19,8 +19,8 @@
 
 #include <protocol/unsigned_leb128.h>
 
-#include <protocol/client_opcode.hxx>
 #include <document_id.hxx>
+#include <protocol/client_opcode.hxx>
 
 namespace couchbase::protocol
 {

data/ext/couchbase/protocol/cmd_mutate_in.hxx

@@ -31,9 +31,9 @@ class mutate_in_response_body
     static const inline client_opcode opcode = client_opcode::subdoc_multi_mutation;
 
     struct mutate_in_field {
-        std::uint8_t index;
-        protocol::status status;
-        std::string value;
+        std::uint8_t index{};
+        protocol::status status{};
+        std::string value{};
     };
 
   private:
@@ -80,7 +80,6 @@ class mutate_in_response_body
                 mutate_in_field field;
 
                 field.index = body[static_cast<std::size_t>(offset)];
-                Expects(field.index < 16);
                 offset++;
 
                 std::uint16_t entry_status = 0;

data/ext/couchbase/protocol/enhanced_error_info.hxx

@@ -0,0 +1,28 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     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.
+ */
+
+#pragma once
+
+namespace couchbase::protocol
+{
+
+struct enhanced_error_info {
+    std::string reference;
+    std::string context;
+};
+
+} // namespace couchbase::protocol

data/ext/couchbase/utils/connection_string.hxx

@@ -86,7 +86,7 @@ using opt_bucket_name = opt_must<one<'/'>, bucket_name>;
 using opt_params = opt_must<one<'?'>, list_must<param, one<'&'>>>;
 using opt_nodes = seq<list_must<node, one<',', ';'>>, opt_bucket_name>;
 
-using grammar = must<seq<uri::scheme, one<':'>, uri::dslash, opt_nodes, opt_params, eof>>;
+using grammar = must<seq<uri::scheme, one<':'>, uri::dslash, opt_nodes, opt_params, tao::json::pegtl::eof>>;
 
 template<typename Rule>
 struct action {

data/ext/couchbase/version.hxx

@@ -24,7 +24,7 @@
 namespace couchbase
 {
 constexpr auto BACKEND_VERSION_MAJOR = 1;
-constexpr auto BACKEND_VERSION_MINOR = 2;
+constexpr auto BACKEND_VERSION_MINOR = 3;
 constexpr auto BACKEND_VERSION_PATCH = 0;
 
 inline const std::string&

data/ext/extconf.rb

@@ -64,7 +64,7 @@ FileUtils.rm_rf(build_dir, verbose: true) unless ENV['CB_PRESERVE_BUILD_DIR']
 FileUtils.mkdir_p(build_dir, verbose: true)
 Dir.chdir(build_dir) do
   puts "-- build #{build_type} extension #{SDK_VERSION} for ruby #{RUBY_VERSION}-#{RUBY_PATCHLEVEL}-#{RUBY_PLATFORM}"
-  sys(cmake, *cmake_flags, project_path)
+  sys(cmake, *cmake_flags, "-B#{build_dir}", "-S#{project_path}")
   number_of_jobs = (ENV["CB_NUMBER_OF_JOBS"] || 4).to_s
   sys(cmake, "--build", build_dir, "--parallel", number_of_jobs,  "--verbose")
 end

data/ext/test/test_native_binary_operations.cxx

@@ -59,10 +59,10 @@ TEST_CASE("native: append", "[native]")
         couchbase::operations::upsert_request req{ id, "world" };
         auto barrier = std::make_shared<std::promise<couchbase::operations::upsert_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::upsert_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::upsert_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("seqno=" << resp.token.sequence_number);
@@ -72,10 +72,10 @@ TEST_CASE("native: append", "[native]")
         couchbase::operations::append_request req{ id, "!" };
         auto barrier = std::make_shared<std::promise<couchbase::operations::append_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::append_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::append_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("seqno=" << resp.token.sequence_number);
@@ -85,10 +85,10 @@ TEST_CASE("native: append", "[native]")
         couchbase::operations::get_request req{ id };
         auto barrier = std::make_shared<std::promise<couchbase::operations::get_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::get_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::get_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("value=" << resp.value);
@@ -140,10 +140,10 @@ TEST_CASE("native: prepend", "[native]")
         couchbase::operations::upsert_request req{ id, "world" };
         auto barrier = std::make_shared<std::promise<couchbase::operations::upsert_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::upsert_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::upsert_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("seqno=" << resp.token.sequence_number);
@@ -153,10 +153,10 @@ TEST_CASE("native: prepend", "[native]")
         couchbase::operations::prepend_request req{ id, "Hello, " };
         auto barrier = std::make_shared<std::promise<couchbase::operations::prepend_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::prepend_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::prepend_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("seqno=" << resp.token.sequence_number);
@@ -166,10 +166,10 @@ TEST_CASE("native: prepend", "[native]")
         couchbase::operations::get_request req{ id };
         auto barrier = std::make_shared<std::promise<couchbase::operations::get_response>>();
         auto f = barrier->get_future();
-        cluster.execute(req, [barrier](couchbase::operations::get_response resp) mutable { barrier->set_value(resp); });
+        cluster.execute(req, [barrier](couchbase::operations::get_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("value=" << resp.value);

data/ext/test/test_native_diagnostics.cxx

@@ -355,8 +355,8 @@ TEST_CASE("native: fetch diagnostics after N1QL query", "[native]")
         auto f = barrier->get_future();
         cluster.execute_http(req, [barrier](couchbase::operations::query_response&& resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rows.size() =" << resp.payload.rows.size());
         REQUIRE(resp.payload.rows.size() == 1);
         INFO("row=" << resp.payload.rows[0]);

data/ext/test/test_native_trivial_crud.cxx

@@ -65,8 +65,8 @@ TEST_CASE("native: upsert document into default collection", "[native]")
         auto f = barrier->get_future();
         cluster.execute(req, [barrier](couchbase::operations::upsert_response resp) mutable { barrier->set_value(resp); });
         auto resp = f.get();
-        INFO(resp.ec.message());
-        REQUIRE_FALSE(resp.ec);
+        INFO(resp.ctx.ec.message());
+        REQUIRE_FALSE(resp.ctx.ec);
         INFO("rc=" << resp.cas);
         REQUIRE(resp.cas != 0);
         INFO("seqno=" << resp.token.sequence_number);

data/ext/third_party/json/include/tao/json/external/pegtl/internal/file_reader.hpp

@@ -17,19 +17,15 @@ namespace TAO_JSON_PEGTL_NAMESPACE::internal
    [[nodiscard]] inline std::FILE* file_open( const std::filesystem::path& path )
    {
       errno = 0;
-#if defined( _MSC_VER )
+#if defined( _MSC_VER ) || defined( __MINGW32__ )
       std::FILE* file;
       if( ::_wfopen_s( &file, path.c_str(), L"rb" ) == 0 ) {
          return file;
       }
       const std::error_code ec( errno, std::system_category() );
       throw std::filesystem::filesystem_error( "_wfopen_s() failed", path, ec );
-#else
-#if defined( __MINGW32__ )
-      if( auto* file = std::fopen( path.c_str(), "rb" ) )
 #else
       if( auto* file = std::fopen( path.c_str(), "rbe" ) )
-#endif
       {
          return file;
       }

data/lib/active_support/cache/couchbase_store.rb

@@ -0,0 +1,362 @@
+#    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"
+
+module ActiveSupport
+  module Cache
+    # A cache store implementation which stores data in Couchbase: https://couchbase.com
+    #
+    # * Local cache. Hot in-memory primary cache within block/middleware scope.
+    # * +read_multi+ and +write_multi+ support.
+    # * +delete_matched+ support using N1QL queries.
+    # * +clear+ for erasing whole collection (optionally can flush the bucket).
+    #
+    # To use this store, add the select it in application config
+    #
+    #     config.cache_store = :couchbase_store, {
+    #       connection_string: "couchbase://localhost",
+    #       username: "app_cache_user",
+    #       password: "s3cret",
+    #       bucket: "app_cache"
+    #     }
+    #
+    # @see https://guides.rubyonrails.org/caching_with_rails.html#cache-stores
+    class CouchbaseStore < Store
+      MAX_KEY_BYTESIZE = 250
+      DEFAULT_ERROR_HANDLER = lambda do |method:, returning:, exception:, logger: CouchbaseStore.logger|
+        logger&.error { "CouchbaseStore: #{method} failed, returned #{returning.inspect}: #{exception.class}: #{exception.message}" }
+      end
+
+      # Advertise cache versioning support.
+      def self.supports_cache_versioning?
+        true
+      end
+
+      module LocalCacheWithRaw # :nodoc:
+        private
+
+        def write_entry(key, entry, **options)
+          if options[:raw] && local_cache
+            raw_entry = Entry.new(entry.value.to_s)
+            raw_entry.expires_at = entry.expires_at
+            super(key, raw_entry, **options)
+          else
+            super
+          end
+        end
+
+        def write_multi_entries(entries, **options)
+          if options[:raw] && local_cache
+            raw_entries = entries.map do |_key, entry|
+              raw_entry = Entry.new(serialize_entry(entry, raw: true))
+              raw_entry.expires_at = entry.expires_at
+            end.to_h
+
+            super(raw_entries, **options)
+          else
+            super
+          end
+        end
+      end
+
+      prepend Strategy::LocalCache
+      prepend LocalCacheWithRaw
+
+      def initialize(options = nil)
+        super
+        @error_handler = options.delete(:error_handler) { DEFAULT_ERROR_HANDLER }
+        @couchbase_options = {}
+        @couchbase_options[:connection_string] =
+          @options.delete(:connection_string) do
+            raise ArgumentError, "Missing connection string for Couchbase cache store. Use :connection_string in the store options"
+          end
+        @couchbase_options[:username] =
+          @options.delete(:username) do
+            raise ArgumentError, "Missing username for Couchbase cache store. Use :username in the store options"
+          end
+        @couchbase_options[:password] =
+          @options.delete(:password) do
+            raise ArgumentError, "Missing password for Couchbase cache store. Use :password in the store options"
+          end
+        @couchbase_options[:bucket] =
+          @options.delete(:bucket) { raise ArgumentError, "Missing bucket for Couchbase cache store. Use :bucket in the store options" }
+        @couchbase_options[:scope] = @options.delete(:scope) if @options.key?(:scope)
+        @couchbase_options[:collection] = @options.delete(:collection) if @options.key?(:collection)
+        @last_mutation_token = nil
+      end
+
+      def collection
+        @collection ||= build_collection
+      end
+
+      def cluster
+        @cluster ||= build_cluster
+      end
+
+      def inspect
+        "#<#{self.class} options=#{options.inspect} collection=#{@collection.inspect}>"
+      end
+
+      # Deletes all entries with keys matching the regular expression.
+      #
+      # The +matcher+ must be valid pattern for N1QL +REGEXP_MATCHES+ function. More info at
+      # https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/patternmatchingfun.html#section_regex_matches
+      #
+      # Because the operation performed on query engine, and it might take time to propagate changes
+      # from key/value engine to the indexer. Therefore the keys, that were created a moment ago
+      # might not be deleted.
+      #
+      # Also this method assumes, that primary index created on the target bucket
+      def delete_matched(matcher, _options = nil)
+        pattern =
+          case matcher
+          when Regexp
+            matcher.inspect[1..-2]
+          when String
+            matcher.tr("?", ".").gsub("*", ".*")
+          else
+            raise NotImplementedError, "Unable to convert #{matcher.inspect} to Regexp pattern"
+          end
+        operation_options = ::Couchbase::Options::Query(named_parameters: {"pattern" => pattern})
+        operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+        begin
+          cluster.query("DELETE FROM #{scope_qualifier} cache WHERE REGEXP_MATCHES(META(cache).id, $pattern)", operation_options)
+        rescue ::Couchbase::Error::ParsingFailure, ::Couchbase::Error::ServiceNotAvailable
+          raise NotImplementedError, "The server does not support delete_matched operation"
+        end
+      end
+
+      # Increments an integer value in the cache.
+      #
+      # Note that it uses binary collection interface, therefore will fail if the value is not
+      # represented as ASCII-encoded number using +:raw+.
+      def increment(name, amount = 1, expires_in: nil, initial: nil, **options)
+        instrument :increment, name, amount: amount do
+          failsafe :increment do
+            key = normalize_key(name, options)
+            res = collection.binary.increment(
+              key, ::Couchbase::Options::Increment(delta: amount, expiry: expires_in, initial: initial)
+            )
+            @last_mutation_token = res.mutation_token
+            res.content
+          end
+        end
+      end
+
+      # Decrements an integer value in the cache.
+      #
+      # Note that it uses binary collection interface, therefore will fail if the value is not
+      # represented as ASCII-encoded number using +:raw+.
+      #
+      # Note that the counter represented by non-negative number on the server, and it will not
+      # cycle to maximum integer when decrementing zero.
+      def decrement(name, amount = 1, expires_in: nil, initial: nil, **_options)
+        instrument :decrement, name, amount: amount do
+          failsafe :decrement do
+            key = normalize_key(name, options)
+            res = collection.binary.decrement(
+              key, ::Couchbase::Options::Decrement(delta: amount, expiry: expires_in, initial: initial)
+            )
+            @last_mutation_token = res.mutation_token
+            res.content
+          end
+        end
+      end
+
+      # Clears the entire cache. Be careful with this method since it could
+      # affect other processes if shared cache is being used.
+      #
+      # When +use_flush+ option set to +true+ it will flush the bucket. Otherwise, it uses N1QL query
+      # and relies on default index.
+      def clear(use_flush: false, **_options)
+        failsafe(:clear) do
+          if use_flush
+            cluster.buckets.flush_bucket(@couchbase_options[:bucket_name])
+          else
+            operation_options = ::Couchbase::Options::Query.new
+            operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+            cluster.query("DELETE FROM #{scope_qualifier}", operation_options)
+          end
+        end
+      end
+
+      private
+
+      def deserialize_entry(payload, raw:)
+        if payload && raw
+          Entry.new(payload, compress: false)
+        else
+          super(payload)
+        end
+      end
+
+      def serialize_entry(entry, raw: false)
+        if raw
+          entry.value.to_s
+        else
+          super(entry)
+        end
+      end
+
+      # Reads an entry from the cache
+      def read_entry(key, **options)
+        failsafe(:read_entry, returning: nil) do
+          result = collection.get(key, ::Couchbase::Options::Get(transcoder: nil))
+          deserialize_entry(result.content, raw: options&.fetch(:raw, false))
+        end
+      end
+
+      # Reads multiple entries from the cache implementation. Subclasses MAY
+      # implement this method.
+      def read_multi_entries(names, **options)
+        return {} if names.empty?
+
+        keys = names.map { |name| normalize_key(name, options) }
+        return_value = {}
+        failsafe(:read_multi_entries, returning: return_value) do
+          results = collection.get_multi(keys, ::Couchbase::Options::GetMulti(transcoder: nil))
+          results.each_with_index do |result, index|
+            next unless result.success?
+
+            entry = deserialize_entry(result.content, raw: options[:raw])
+            unless entry.nil? || entry.expired? || entry.mismatched?(normalize_version(names[index], options))
+              return_value[names[index]] = entry.value
+            end
+          end
+          return_value
+        end
+      end
+
+      # Writes an entry to the cache
+      def write_entry(key, entry, raw: false, expires_in: nil, race_condition_ttl: nil, **_options)
+        if race_condition_ttl && expires_in && expires_in.positive? && !raw
+          # Add few minutes to expiry in the future to support race condition TTLs on read
+          expires_in += 5.minutes
+        end
+        failsafe(:write_entry, returning: false) do
+          res = collection.upsert(key, serialize_entry(entry, raw: raw),
+                                  ::Couchbase::Options::Upsert(transcoder: nil, expiry: expires_in))
+          @last_mutation_token = res.mutation_token
+          true
+        end
+      end
+
+      def write_multi_entries(hash, **options)
+        return 0 if hash.empty?
+
+        return super if local_cache
+
+        expires_in = options[:expires_in]
+        if options[:race_condition_ttl] && expires_in && expires_in.positive?
+          # Add few minutes to expiry in the future to support race condition TTLs on read
+          expires_in += 5.minutes
+        end
+        operation_options = ::Couchbase::Options::UpsertMulti(transcoder: nil, expiry: expires_in)
+
+        pairs = hash.map do |key, entry|
+          [key, options[:raw] ? entry.value.to_s : serialize_entry(entry)]
+        end
+        failsafe(:write_multi_entries, returning: nil) do
+          successful = collection.upsert_multi(pairs, operation_options).select(&:success?)
+          return 0 if successful.empty?
+
+          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          successful.count
+        end
+      end
+
+      # Deletes an entry from the cache implementation. Subclasses must
+      # implement this method.
+      def delete_entry(key, **_options)
+        failsafe(:delete_entry, returning: false) do
+          res = collection.remove(key)
+          @last_mutation_token = res.mutation_token
+          true
+        end
+      end
+
+      # Deletes multiple entries in the cache. Returns the number of entries deleted.
+      def delete_multi_entries(entries, **_options)
+        return if entries.empty?
+
+        failsafe(:delete_multi_entries, returning: nil) do
+          successful = collection.remove_multi(entries).select(&:success?)
+          return 0 if successful.empty?
+
+          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          successful.count
+        end
+      end
+
+      def failsafe(method, returning: nil)
+        yield
+      rescue ::Couchbase::Error::CouchbaseError => e
+        handle_exception(exception: e, method: method, returning: returning)
+        returning
+      end
+
+      def handle_exception(exception:, method:, returning:)
+        return unless @error_handler
+
+        @error_handler.call(method: method, exception: exception, returning: returning)
+      rescue StandardError => e
+        warn "CouchbaseStore ignored exception in handle_exception: #{e.class}: #{e.message}\n  #{e.backtrace.join("\n  ")}"
+      end
+
+      # Truncate keys that exceed 250 characters
+      def normalize_key(key, options)
+        truncate_key super&.b
+      end
+
+      def truncate_key(key)
+        if key && key.bytesize > MAX_KEY_BYTESIZE
+          suffix = ":sha2:#{::Digest::SHA2.hexdigest(key)}"
+          truncate_at = MAX_KEY_BYTESIZE - suffix.bytesize
+          "#{key.byteslice(0, truncate_at)}#{suffix}"
+        else
+          key
+        end
+      end
+
+      # Connects to the Couchbase cluster
+      def build_cluster
+        ::Couchbase::Cluster.connect(
+          @couchbase_options[:connection_string],
+          ::Couchbase::Options::Cluster(authenticator: ::Couchbase::PasswordAuthenticator.new(
+            @couchbase_options[:username], @couchbase_options[:password]
+          ))
+        )
+      end
+
+      # Connects to the Couchbase cluster, opens specified bucket and returns collection object.
+      def build_collection
+        bucket = cluster.bucket(@couchbase_options[:bucket])
+        if @couchbase_options[:scope] && @couchbase_options[:collection]
+          bucket.scope(@couchbase_options[:scope]).collection(@couchbase_options[:collection])
+        else
+          bucket.default_collection
+        end
+      end
+
+      def scope_qualifier
+        if @couchbase_options[:scope] && @couchbase_options[:collection]
+          "`#{@couchbase_options[:bucket]}`.#{@couchbase_options[:scope]}.#{@couchbase_options[:collection]}"
+        else
+          "`#{@couchbase_options[:bucket]}`"
+        end
+      end
+    end
+  end
+end