couchbase 4.2.0 → 4.2.2

package/deps/couchbase-cxx-client/examples/async_game_server.cxx

@@ -0,0 +1,314 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2021-Present 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.
+ */
+
+#include <core/logger/logger.hxx>
+#include <couchbase/cluster.hxx>
+
+#include <spdlog/spdlog.h>
+
+#include <asio/io_context.hpp>
+
+#include <functional>
+#include <iostream>
+#include <random>
+#include <string>
+#include <thread>
+
+using namespace couchbase::transactions;
+
+std::string
+make_uuid()
+{
+    static std::random_device dev;
+    static std::mt19937 rng(dev());
+
+    std::uniform_int_distribution<int> dist(0, 15);
+
+    const char* v = "0123456789abcdef";
+    const bool dash_pattern[] = {
+        false, false, false, false, true, false, true, false, true, false, true, false, false, false, false, false,
+    };
+
+    std::string res;
+    for (bool dash : dash_pattern) {
+        if (dash) {
+            res += "-";
+        }
+        res += v[dist(rng)];
+        res += v[dist(rng)];
+    }
+    return res;
+}
+
+struct Player {
+    int experience;
+    int hitpoints;
+    std::string json_type;
+    int level;
+    bool logged_in;
+    std::string name;
+    std::string uuid;
+};
+
+template<>
+struct tao::json::traits<Player> {
+    template<template<typename...> class Traits>
+    static void assign(tao::json::basic_value<Traits>& v, const Player& p)
+    {
+        v = { { "experience", p.experience }, { "hitpoints", p.hitpoints }, { "jsonType", p.json_type }, { "level", p.level },
+              { "loggedIn", p.logged_in },    { "name", p.name },           { "uuid", p.uuid } };
+    }
+
+    template<template<typename...> class Traits>
+    static void to(const tao::json::basic_value<Traits>& v, Player& p)
+    {
+        v.at("experience").to(p.experience);
+        v.at("hitpoints").to(p.hitpoints);
+        v.at("jsonType").to(p.json_type);
+        v.at("level").to(p.level);
+        v.at("loggedIn").to(p.logged_in);
+        v.at("name").to(p.name);
+        v.at("uuid").to(p.uuid);
+    }
+};
+
+struct Monster {
+    int experience_when_killed;
+    int hitpoints;
+    double item_probability;
+    std::string json_type;
+    std::string name;
+    std::string uuid;
+};
+
+template<>
+struct tao::json::traits<Monster> {
+    template<template<typename...> class Traits>
+    static void assign(tao::json::basic_value<Traits>& v, const Monster& m)
+    {
+        v = { { "experienceWhenKilled", m.experience_when_killed },
+              { "hitpoints", m.hitpoints },
+              { "itemProbability", m.item_probability },
+              { "jsonType", m.json_type },
+              { "name", m.name },
+              { "uuid", m.uuid } };
+    }
+
+    template<template<typename...> class Traits>
+    static void to(const tao::json::basic_value<Traits>& v, Monster& m)
+    {
+        v.at("experienceWhenKilled").to(m.experience_when_killed);
+        v.at("hitpoints").to(m.hitpoints);
+        v.at("itemProbability").to(m.item_probability);
+        v.at("jsonType").to(m.json_type);
+        v.at("name").to(m.name);
+        v.at("uuid").to(m.uuid);
+    }
+};
+
+class GameServer
+{
+  private:
+    std::shared_ptr<transactions> transactions_;
+
+  public:
+    explicit GameServer(couchbase::cluster& cluster)
+      : transactions_(cluster.transactions())
+    {
+    }
+
+    [[nodiscard]] int calculate_level_for_experience(int experience) const
+    {
+        return experience / 100;
+    }
+
+    std::future<transaction_result> player_hits_monster(int damage,
+                                                        const couchbase::collection& collection,
+                                                        const std::string& player_id,
+                                                        const std::string& monster_id,
+                                                        std::atomic<bool>& exists)
+    {
+        auto barrier = std::make_shared<std::promise<transaction_result>>();
+        auto f = barrier->get_future();
+        transactions_->run(
+          [this, damage, collection, player_id, monster_id, &exists](async_attempt_context& ctx) {
+              ctx.get(
+                collection,
+                monster_id,
+                [&ctx, this, collection, monster_id, player_id, &exists, damage = std::move(damage)](transaction_get_result_ptr monster) {
+                    if (monster->ctx().ec()) {
+                        if (monster->ctx().ec() == couchbase::errc::transaction_op::document_not_found_exception) {
+                            std::cout << "monster no longer exists" << std::endl;
+                            exists = false;
+                            return;
+                        }
+                    }
+                    auto monster_body = monster->content<Monster>();
+                    auto monster_hitpoints = monster_body.hitpoints;
+                    auto monster_new_hitpoints = monster_hitpoints - damage;
+
+                    std::cout << "Monster " << monster_id << " had " << monster_hitpoints << " hitpoints, took " << damage
+                              << " damage, now has " << monster_new_hitpoints << " hitpoints" << std::endl;
+                    if (monster_new_hitpoints <= 0) {
+                        // Monster is killed. The remove is just for demoing, and a more realistic examples would set a "dead" flag or
+                        // similar.
+                        ctx.remove(monster, [](couchbase::transaction_op_error_context e) {
+                            if (e.ec()) {
+                                std::cout << "error removing monster: " << e.ec().message() << std::endl;
+                            }
+                        });
+                        // also, in parallel, get/update player
+                        ctx.get(
+                          collection, player_id, [&ctx, player_id, monster_id, monster_body, this](transaction_get_result_ptr player) {
+                              if (player->ctx().ec()) {
+                                  std::cout << "error getting player: " << player->ctx().ec().message() << std::endl;
+                                  return;
+                              }
+                              const Player& player_body = player->content<Player>();
+
+                              // the player earns experience for killing the monster
+                              int experience_for_killing_monster = monster_body.experience_when_killed;
+                              int player_experience = player_body.experience;
+                              int player_new_experience = player_experience + experience_for_killing_monster;
+                              int player_new_level = calculate_level_for_experience(player_new_experience);
+
+                              std::cout << "Monster " << monster_id << " was killed. Player " << player_id << " gains "
+                                        << experience_for_killing_monster << " experience, now has level " << player_new_level << std::endl;
+
+                              Player player_new_body = player_body;
+                              player_new_body.experience = player_new_experience;
+                              player_new_body.level = player_new_level;
+                              ctx.replace(player, player_new_body, [](transaction_get_result_ptr res) {
+                                  if (res->ctx().ec()) {
+                                      std::cout << "Error updating player :" << res->ctx().ec().message() << std::endl;
+                                  }
+                              });
+                          });
+                    } else {
+                        std::cout << "Monster " << monster_id << " is damaged but alive" << std::endl;
+
+                        Monster monster_new_body = monster_body;
+                        monster_new_body.hitpoints = monster_new_hitpoints;
+                        ctx.replace(monster, monster_new_body, [monster_new_body](transaction_get_result_ptr res) {
+                            if (res->ctx().ec()) {
+                                std::cout << "Error updating monster :" << res->ctx().ec().message() << std::endl;
+                            } else {
+                                auto body = couchbase::codec::tao_json_serializer::serialize(monster_new_body);
+                                std::cout << "Monster body updated to :" << std::string(reinterpret_cast<char*>(&body.front()), body.size())
+                                          << std::endl;
+                            }
+                        });
+                    }
+                });
+          },
+          [barrier](transaction_result res) { barrier->set_value(res); });
+        return f;
+    }
+};
+
+int
+main()
+{
+    const int NUM_THREADS = 4;
+    couchbase::core::logger::set_log_levels(couchbase::core::logger::level::trace);
+    std::atomic<bool> monster_exists = true;
+    std::string bucket_name = "default";
+    asio::io_context io;
+    auto guard = asio::make_work_guard(io);
+
+    if (!couchbase::core::logger::is_initialized()) {
+        couchbase::core::logger::create_console_logger();
+    }
+
+    std::list<std::thread> io_threads;
+    for (int i = 0; i < 2 * (NUM_THREADS + 1); i++) {
+        io_threads.emplace_back([&io]() { io.run(); });
+    }
+
+    std::uniform_int_distribution<int> hit_distribution(1, 6);
+    std::mt19937 random_number_engine; // pseudorandom number generator
+    auto rand = std::bind(hit_distribution, random_number_engine);
+
+    auto options = couchbase::cluster_options("Administrator", "password");
+    options.transactions().cleanup_config().cleanup_window(std::chrono::seconds(60));
+    options.transactions().durability_level(couchbase::durability_level::majority);
+    options.transactions().cleanup_config().cleanup_lost_attempts(true);
+    options.transactions().cleanup_config().cleanup_client_attempts(true);
+
+    auto [cluster, ec] = couchbase::cluster::connect(io, "couchbase://localhost", options).get();
+    if (ec) {
+        std::cout << "Error opening cluster: " << ec.message() << std::endl;
+        return -1;
+    }
+
+    auto collection = cluster.bucket("default").default_collection();
+
+    std::string player_id{ "player_data" };
+    Player player_data{ 14248, 23832, "player", 141, true, "Jane", make_uuid() };
+
+    std::string monster_id{ "a_grue" };
+    Monster monster_data{ 91, 4000, 0.19239324085462631, "monster", "Grue", make_uuid() };
+
+    // upsert a player document
+    {
+        auto [ctx, resp] = collection.upsert(player_id, player_data, {}).get();
+        if (!ctx.ec()) {
+            std::cout << "Upserted sample player document: " << player_id << "with cas:" << resp.cas().value() << std::endl;
+        }
+    }
+    // upsert a monster document
+    {
+        auto [ctx, resp] = collection.upsert(monster_id, monster_data, {}).get();
+        if (!ctx.ec()) {
+            std::cout << "Upserted sample monster document: " << monster_id << "with cas:" << resp.cas().value() << std::endl;
+        }
+    }
+
+    GameServer game_server(cluster);
+    std::vector<std::thread> threads;
+    for (int i = 0; i < NUM_THREADS; i++) {
+        threads.emplace_back([&rand, player_id, collection, monster_id, &monster_exists, &game_server]() {
+            while (monster_exists.load()) {
+                std::cout << "[thread " << std::this_thread::get_id() << "]Monster exists -- lets hit it!" << std::endl;
+                auto res = game_server.player_hits_monster(rand() % 80, collection, player_id, monster_id, monster_exists).get();
+                if (res.unstaging_complete) {
+                    std::cout << "[thread " << std::this_thread::get_id() << "] success" << std::endl;
+                } else {
+                    std::cout << "[thread " << std::this_thread::get_id() << "] " << res.ctx.ec().message() << std::endl;
+                }
+            }
+        });
+    }
+
+    // wait for all threads to finish...
+    for (auto& t : threads) {
+        if (t.joinable()) {
+            t.join();
+        }
+    }
+
+    // close the cluster...
+    cluster.close();
+
+    // then cleanup asio
+    guard.reset();
+    for (auto& t : io_threads) {
+        if (t.joinable()) {
+            t.join();
+        }
+    }
+}

package/deps/couchbase-cxx-client/examples/channels.cxx

@@ -0,0 +1,50 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2021-Present 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.
+ */
+
+#include <asio.hpp>
+#include <asio/experimental/concurrent_channel.hpp>
+
+#include <iostream>
+
+int
+main()
+{
+    asio::io_context io;
+
+    asio::experimental::concurrent_channel<void(std::error_code, int)> ch{ io, 1 };
+
+    ch.async_send(std::error_code(), 42, [](std::error_code error) {
+        if (!error) {
+            std::cout << "Sent "
+                      << "\n";
+        } else {
+            std::cout << "send error " << error << ", " << error.message() << "\n";
+        }
+    });
+
+    ch.async_receive([](std::error_code error, int i) {
+        if (!error) {
+            std::cout << "Received " << i << "\n";
+        } else {
+            std::cout << "receive error " << error << ", " << error.message() << "\n";
+        }
+    });
+
+    io.run();
+
+    return 0;
+}

package/deps/couchbase-cxx-client/examples/distributed_mutex.cxx

@@ -0,0 +1,186 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2021-Present 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.
+ */
+
+#include "core/logger/logger.hxx"
+
+#include <couchbase/cluster.hxx>
+
+#include <asio.hpp>
+#include <fmt/chrono.h>
+#include <fmt/format.h>
+
+#include <system_error>
+#include <thread>
+
+static constexpr auto connection_string{ "couchbase://127.0.0.1" };
+static constexpr auto username{ "Administrator" };
+static constexpr auto password{ "password" };
+static constexpr auto bucket_name{ "default" };
+static constexpr auto scope_name{ couchbase::scope::default_name };
+static constexpr auto collection_name{ couchbase::collection::default_name };
+
+class lock_aware_retry_strategy : public couchbase::best_effort_retry_strategy
+{
+  public:
+    lock_aware_retry_strategy(couchbase::backoff_calculator calculator)
+      : couchbase::best_effort_retry_strategy(calculator)
+      , calculator_{ calculator }
+    {
+    }
+
+    auto retry_after(const couchbase::retry_request& request, couchbase::retry_reason reason) -> couchbase::retry_action override
+    {
+        if (reason == couchbase::retry_reason::key_value_locked) {
+            // here we use the same calculator as best_effort_retry_strategy, but it could be different one
+            auto backoff_duration = calculator_(request.retry_attempts());
+            fmt::print("retrying in {} because of \"key_value_locked\", attempt {}\n", backoff_duration, request.retry_attempts());
+            return couchbase::retry_action{ backoff_duration };
+        }
+        return couchbase::best_effort_retry_strategy::retry_after(request, reason);
+    }
+
+  private:
+    couchbase::backoff_calculator calculator_;
+};
+
+/**
+ * This is simple demo class showing how couchbase mutex could be implemented using pessimistic.
+ *
+ * @note this class serves for demonstration purpose. Production-ready solution should have more checks, tests and features.
+ *
+ * @note that the server will automatically release the lock after some time.
+ *
+ * Class implements `BasicLockable` requirement (but might also implement `Lockable` or even `TimedLockable`.
+ * For example, if TimedLockable will be implemented, then we could tie it to lock_duration.
+ *
+ * @see https://en.cppreference.com/w/cpp/named_req/BasicLockable
+ *
+ * This mutex will give up if the lock cannot be aquired in given timeout interval, and raise an exception.
+ *
+ * Alternative implementation might use optimistic locking or more complex coordination mechanisms.
+ *
+ * @see https://docs.couchbase.com/dotnet-sdk/current/howtos/concurrent-document-mutations.html
+ */
+class couchbase_mutex
+{
+  public:
+    static constexpr std::chrono::seconds default_lock_duration{ 15 };
+    static constexpr std::chrono::seconds default_timeout{ 10 };
+
+    couchbase_mutex(couchbase::collection collection,
+                    std::string document_id,
+                    std::chrono::seconds lock_duration = default_lock_duration,
+                    std::chrono::seconds timeout = default_timeout)
+      : collection_{ std::move(collection) }
+      , document_id_{ std::move(document_id) }
+      , lock_duration_{ lock_duration }
+      , timeout_{ timeout }
+    {
+        auto options = couchbase::upsert_options{}.retry_strategy(retry_strategy_).timeout(timeout_);
+        auto [ctx, resp] = collection_.upsert(document_id_, content_, options).get();
+        if (ctx.ec()) {
+            throw std::system_error(ctx.ec(),
+                                    fmt::format(R"(unable to create mutex "{}" (retries: {}))", document_id_, ctx.retry_attempts()));
+        }
+        cas_ = resp.cas();
+        fmt::print(
+          "[created ] \"{}\", cas: {}, retries: {}, lock_duration: {}\n", document_id_, cas_.value(), ctx.retry_attempts(), lock_duration);
+    }
+
+    void lock()
+    {
+        std::scoped_lock lock(mutex_);
+        auto options = couchbase::get_and_lock_options{}.retry_strategy(retry_strategy_).timeout(timeout_);
+        auto [ctx, resp] = collection_.get_and_lock(document_id_, lock_duration_, options).get();
+        if (ctx.ec()) {
+            throw std::system_error(ctx.ec(),
+                                    fmt::format(R"(unable to lock mutex "{}" (retries: {}))", document_id_, ctx.retry_attempts()));
+        }
+        cas_ = resp.cas();
+        fmt::print("[locked  ] \"{}\", cas: {}, retries: {}\n", document_id_, cas_.value(), ctx.retry_attempts());
+    }
+
+    void unlock()
+    {
+        std::scoped_lock lock(mutex_);
+        auto options = couchbase::unlock_options{}.timeout(timeout_);
+        auto ctx = collection_.unlock(document_id_, cas_, options).get();
+        if (ctx.ec()) {
+            throw std::system_error(ctx.ec(),
+                                    fmt::format(R"(unable to unlock mutex "{}" (retries: {}))", document_id_, ctx.retry_attempts()));
+        }
+        fmt::print("[unlocked] \"{}\", cas: {}, retries: {}\n", document_id_, cas_.value(), ctx.retry_attempts());
+    }
+
+  private:
+    couchbase::collection collection_;
+    std::string document_id_;
+    std::chrono::seconds lock_duration_;
+    std::chrono::seconds timeout_;
+    couchbase::cas cas_;
+    const std::string content_{ "__couchbase_mutex__" };
+    mutable std::mutex mutex_{}; // regular mutex to protect internal state
+    std::shared_ptr<lock_aware_retry_strategy> retry_strategy_{ std::make_shared<lock_aware_retry_strategy>(
+      couchbase::controlled_backoff) }; // see also couchbase::exponential_backoff calculator
+};
+
+int
+main()
+{
+    asio::io_context io;
+    auto guard = asio::make_work_guard(io);
+    std::thread io_thread([&io]() { io.run(); });
+
+    auto options = couchbase::cluster_options(username, password);
+    options.apply_profile("wan_development");
+    auto [cluster, ec] = couchbase::cluster::connect(io, connection_string, options).get();
+    auto collection = cluster.bucket(bucket_name).scope(scope_name).collection(collection_name);
+
+    // Obtain thread_id for simplicity. Could be pid_id, if it was more portable.
+    auto writer_id = fmt::format("thread:{}", std::hash<std::thread::id>()(std::this_thread::get_id()));
+
+    // Create distributed mutex to protect modification of document "order:42".
+    couchbase_mutex mutex(collection, "demo_mutex");
+    {
+        std::scoped_lock lock(mutex);
+
+        // while lock is kept, other process cannot modify "order:42"
+        const std::string document_id{ "order:42" };
+        const tao::json::value basic_doc{ { "type", "book" },
+                                          { "name", "Alice in Wonderland" },
+                                          { "author", "Lewis Carroll" },
+                                          { "price_usd", 4.0 },
+                                          { "writer_id", writer_id } };
+        auto [ctx, resp] = collection.upsert(document_id, basic_doc, {}).get();
+        fmt::print("[stored  ] \"{}\", ec: {}, id: \"{}\", CAS: {}, writer_id: \"{}\"\n",
+                   document_id,
+                   ctx.ec() ? ctx.ec().message() : "success",
+                   document_id,
+                   resp.cas().value(),
+                   writer_id);
+
+        fmt::print(stderr, "[wait    ] pretend to do some work for 7 seconds (distributed mutex still locked)\n");
+        std::this_thread::sleep_for(std::chrono::seconds{ 7 });
+    }
+
+    cluster.close();
+    guard.reset();
+
+    io_thread.join();
+
+    return 0;
+}