couchbase 3.5.1 → 3.5.2

data/ext/couchbase/core/error_context/key_value_error_context.hxx

@@ -0,0 +1,235 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-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.
+ */
+
+#pragma once
+
+#include "couchbase/cas.hxx"
+
+#include "base_error_context.hxx"
+#include "key_value_error_map_info.hxx"
+#include "key_value_extended_error_info.hxx"
+#include "key_value_status_code.hxx"
+
+#include <cstdint>
+#include <optional>
+
+namespace couchbase::core
+{
+/**
+ * The error context returned with key/value operations.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class key_value_error_context : public core::base_error_context
+{
+public:
+  /**
+   * Creates empty error context
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  key_value_error_context() = default;
+
+  /**
+   * Creates and initializes error context with given parameters.
+   *
+   * @param operation_id
+   * @param ec
+   * @param last_dispatched_to
+   * @param last_dispatched_from
+   * @param retry_attempts
+   * @param retry_reasons
+   * @param id
+   * @param bucket
+   * @param scope
+   * @param collection
+   * @param opaque
+   * @param status_code
+   * @param cas
+   * @param error_map_info
+   * @param extended_error_info
+   *
+   * @since 1.0.0
+   * @internal
+   */
+  key_value_error_context(std::string operation_id,
+                          std::error_code ec,
+                          std::optional<std::string> last_dispatched_to,
+                          std::optional<std::string> last_dispatched_from,
+                          std::size_t retry_attempts,
+                          std::set<retry_reason> retry_reasons,
+                          std::string id,
+                          std::string bucket,
+                          std::string scope,
+                          std::string collection,
+                          std::uint32_t opaque,
+                          std::optional<key_value_status_code> status_code,
+                          couchbase::cas cas,
+                          std::optional<key_value_error_map_info> error_map_info,
+                          std::optional<key_value_extended_error_info> extended_error_info)
+    : base_error_context{ std::move(operation_id),
+                          ec,
+                          std::move(last_dispatched_to),
+                          std::move(last_dispatched_from),
+                          retry_attempts,
+                          std::move(retry_reasons) }
+    , id_{ std::move(id) }
+    , bucket_{ std::move(bucket) }
+    , scope_{ std::move(scope) }
+    , collection_{ std::move(collection) }
+    , opaque_{ opaque }
+    , status_code_{ status_code }
+    , cas_{ cas }
+    , error_map_info_{ std::move(error_map_info) }
+    , extended_error_info_{ std::move(extended_error_info) }
+  {
+  }
+
+  /**
+   * Returns identifier (key) of the document referenced in the operation.
+   *
+   * @return document identifier
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto id() const -> const std::string&
+  {
+    return id_;
+  }
+
+  /**
+   * Returns name of the bucket.
+   *
+   * @return name of the bucket.
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto bucket() const -> const std::string&
+  {
+    return bucket_;
+  }
+
+  /**
+   * Returns name of the scope of the document.
+   *
+   * @return name of the scope.
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto scope() const -> const std::string&
+  {
+    return scope_;
+  }
+
+  /**
+   * Returns name of the collection of the document.
+   *
+   * @return collection name
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto collection() const -> const std::string&
+  {
+    return collection_;
+  }
+
+  /**
+   * Returns opaque number generated by the SDK and repeated by the server.
+   *
+   * @return opaque number
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto opaque() const -> std::uint32_t
+  {
+    return opaque_;
+  }
+
+  /**
+   * Returns status code from the server response.
+   *
+   * @return protocol status code
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto status_code() const -> const std::optional<key_value_status_code>&
+  {
+    return status_code_;
+  }
+
+  /**
+   * Returns CAS value associated with the document on the server.
+   *
+   * @return CAS value
+   *
+   * @since 1.0.0
+   * @uncommitted
+   */
+  [[nodiscard]] auto cas() const -> couchbase::cas
+  {
+    return cas_;
+  }
+
+  /**
+   * Returns entry from error map, if it was mapped.
+   *
+   * @return optional error map info
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto error_map_info() const -> const std::optional<key_value_error_map_info>&
+  {
+    return error_map_info_;
+  }
+
+  /**
+   * Returns extended error info (if it was rendered in the server response).
+   *
+   * @return optional error info
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto extended_error_info() const
+    -> const std::optional<key_value_extended_error_info>&
+  {
+    return extended_error_info_;
+  }
+
+  [[nodiscard]] auto to_json() const -> std::string;
+
+private:
+  std::string id_{};
+  std::string bucket_{};
+  std::string scope_{};
+  std::string collection_{};
+  std::uint32_t opaque_{};
+  std::optional<key_value_status_code> status_code_{};
+  couchbase::cas cas_{};
+  std::optional<key_value_error_map_info> error_map_info_{};
+  std::optional<key_value_extended_error_info> extended_error_info_{};
+};
+} // namespace couchbase::core

data/ext/couchbase/core/error_context/key_value_error_map_attribute.hxx

@@ -0,0 +1,142 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-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.
+ */
+
+#pragma once
+
+namespace couchbase::core
+{
+/**
+ * This enum defines known attributes, that could be associated with the error code in the error
+ * map. Complete list could be found at
+ * https://github.com/couchbase/kv_engine/blob/master/docs/ErrorMap.md#error-attributes.
+ */
+enum class key_value_error_map_attribute {
+  /**
+   * The operation was successful for those situations where the error code is indicating successful
+   * (i.e. subdocument operations carried out on a deleted document)
+   */
+  success,
+
+  /**
+   * This attribute means that the error is related to a constraint failure regarding the item
+   * itself, i.e. the item does not exist, already exists, or its current value makes the current
+   * operation impossible. Retrying the operation when the item's value or status has changed may
+   * succeed.
+   */
+  item_only,
+
+  /**
+   * This attribute means that a user's input was invalid because it violates the semantics of the
+   * operation, or exceeds some predefined limit.
+   */
+  invalid_input,
+
+  /**
+   * The client's cluster map may be outdated and requires updating. The client should obtain a
+   * newer configuration.
+   */
+  fetch_config,
+
+  /**
+   * The current connection is no longer valid. The client must reconnect to the server. Note that
+   * the presence of other attributes may indicate an alternate remedy to fixing the connection
+   * without a disconnect, but without special remedial action a disconnect is needed.
+   */
+  conn_state_invalidated,
+
+  /**
+   * The operation failed because the client failed to authenticate or is not authorized to perform
+   * this operation. Note that this error in itself does not mean the connection is invalid, unless
+   * conn-state-invalidated is also present.
+   */
+  auth,
+
+  /**
+   * This error code must be handled specially. If it is not handled, the connection must be
+   * dropped.
+   */
+  special_handling,
+
+  /**
+   * The operation is not supported, possibly because the of server version, bucket type, or current
+   * user.
+   */
+  support,
+
+  /**
+   * This error is transient. Note that this does not mean the error is retriable.
+   */
+  temp,
+
+  /**
+   * This is an internal error in the server.
+   */
+  internal,
+
+  /**
+   * The operation may be retried immediately.
+   */
+  retry_now,
+
+  /**
+   * The operation may be retried after some time.
+   */
+  retry_later,
+
+  /**
+   * The error is related to the subdocument subsystem.
+   */
+  subdoc,
+
+  /**
+   * The error is related to the DCP subsystem.
+   */
+  dcp,
+
+  /**
+   * Use retry specifications from the server.
+   */
+  auto_retry,
+
+  /**
+   * This attribute means that the error is related to operating on a locked document.
+   */
+  item_locked,
+
+  /**
+   * This attribute means that the error is related to operating on a soft-deleted document.
+   */
+  item_deleted,
+
+  /**
+   * The error is related to rate limitation for the client (version 2)
+   */
+  rate_limit,
+
+  /**
+   * The error is related to a system-defined hard limit for resource usage.
+   * Retrying the operation will most likely not succeed unless an action was
+   * taken on the server to resolve the issue (version 2)
+   */
+  system_constraint,
+
+  /**
+   * The client should not retry the operation.
+   */
+  no_retry,
+};
+} // namespace couchbase::core

data/ext/couchbase/core/error_context/key_value_error_map_info.hxx

@@ -0,0 +1,139 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-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.
+ */
+
+#pragma once
+
+#include "key_value_error_map_attribute.hxx"
+
+#include <cstdint>
+#include <set>
+#include <string>
+
+namespace couchbase::core
+{
+/**
+ * Entry of the ErrorMap.
+ *
+ * The ErrorMap contains mappings from errors to their attributes, negotiated between the client and
+ * the server.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class key_value_error_map_info
+{
+public:
+  /**
+   * Constructs empty error map entry
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  key_value_error_map_info() = default;
+
+  /**
+   * Constructs and initializes error map entry with given parameters.
+   *
+   * @param code
+   * @param name
+   * @param description
+   * @param attributes
+   *
+   * @since 1.0.0
+   * @internal
+   */
+  key_value_error_map_info(std::uint16_t code,
+                           std::string name,
+                           std::string description,
+                           std::set<key_value_error_map_attribute> attributes)
+    : code_{ code }
+    , name_{ std::move(name) }
+    , description_{ std::move(description) }
+    , attributes_{ std::move(attributes) }
+  {
+  }
+
+  /**
+   * Returns numeric error code.
+   *
+   * @return error code
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto code() const -> std::uint16_t
+  {
+    return code_;
+  }
+
+  /**
+   * Returns symbolic name of the error code.
+   *
+   * @return error name
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto name() const -> const std::string&
+  {
+    return name_;
+  }
+
+  /**
+   * Returns human readable description of the error code.
+   *
+   * @return error description
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto description() const -> const std::string&
+  {
+    return description_;
+  }
+
+  /**
+   * Returns set of the attributes associated with error code.
+   *
+   * @return set of the associated attributes
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto attributes() const -> const std::set<key_value_error_map_attribute>&
+  {
+    return attributes_;
+  }
+
+  /**
+   * @return true if error map info contains retry attribute
+   *
+   * @since 1.0.0
+   * @internal
+   */
+  [[nodiscard]] bool has_retry_attribute() const
+  {
+    return attributes_.count(key_value_error_map_attribute::retry_now) > 0;
+  }
+
+private:
+  std::uint16_t code_{};
+  std::string name_{};
+  std::string description_{};
+  std::set<key_value_error_map_attribute> attributes_{};
+};
+} // namespace couchbase::core

data/ext/couchbase/core/error_context/key_value_extended_error_info.hxx

@@ -0,0 +1,86 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-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.
+ */
+
+#pragma once
+
+#include <string>
+
+namespace couchbase::core
+{
+/**
+ * Represents extended error information returned by the server in some cases.
+ *
+ * For instance, it might contain unique identifier used by the server in its logs (reference), or
+ * detailed explanation of the cause of the error (context).
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class key_value_extended_error_info
+{
+public:
+  /**
+   * Constructs empty error info.
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  key_value_extended_error_info() = default;
+
+  /**
+   * Constructs error info with given reference and context.
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  key_value_extended_error_info(std::string reference, std::string context)
+    : reference_(std::move(reference))
+    , context_(std::move(context))
+  {
+  }
+
+  /**
+   * Returns error reference, that could be used to match the operation in server logs.
+   *
+   * @return error reference, or empty string
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto reference() const -> const std::string&
+  {
+    return reference_;
+  }
+
+  /**
+   * Returns error context, human readable message explaining cause of the error condition.
+   *
+   * @return error context, or empty string
+   *
+   * @since 1.0.0
+   * @committed
+   */
+  [[nodiscard]] auto context() const -> const std::string&
+  {
+    return context_;
+  }
+
+private:
+  std::string reference_{};
+  std::string context_{};
+};
+} // namespace couchbase::core

data/ext/couchbase/core/error_context/key_value_json.hxx

@@ -0,0 +1,83 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024. 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
+
+#include "core/fmt/key_value_status_code.hxx"
+#include <couchbase/fmt/retry_reason.hxx>
+
+#include "key_value_error_context.hxx"
+
+#include <fmt/format.h>
+#include <tao/json/forward.hpp>
+
+namespace tao::json
+{
+template<>
+struct traits<couchbase::core::key_value_error_context> {
+  template<template<typename...> class Traits>
+  static void assign(tao::json::basic_value<Traits>& v,
+                     const couchbase::core::key_value_error_context& ctx)
+  {
+    std::vector<tao::json::basic_value<Traits>> reasons{};
+    for (couchbase::retry_reason r : ctx.retry_reasons()) {
+      reasons.emplace_back(fmt::format("{}", r));
+    }
+    v["retry_attempts"] = ctx.retry_attempts();
+    v["retry_reasons"] = reasons;
+    if (ctx.last_dispatched_to()) {
+      v["last_dispatched_to"] = ctx.last_dispatched_to().value();
+    }
+    if (ctx.last_dispatched_from()) {
+      v["last_dispatched_from"] = ctx.last_dispatched_from().value();
+    }
+    if (!ctx.operation_id().empty()) {
+      v["operation_id"] = ctx.operation_id();
+    }
+    if (!ctx.id().empty()) {
+      v["id"] = ctx.id();
+    }
+    if (ctx.opaque() > 0) {
+      v["opaque"] = ctx.opaque();
+    }
+    if (!ctx.bucket().empty()) {
+      v["bucket"] = ctx.bucket();
+    }
+    if (!ctx.scope().empty()) {
+      v["scope"] = ctx.scope();
+    }
+    if (!ctx.collection().empty()) {
+      v["collection"] = ctx.collection();
+    }
+    if (ctx.status_code()) {
+      v["status"] = fmt::format("{}", ctx.status_code().value());
+    }
+    if (ctx.error_map_info()) {
+      tao::json::basic_value<Traits> error_map_info;
+      error_map_info["name"] = ctx.error_map_info()->name();
+      error_map_info["desc"] = ctx.error_map_info()->description();
+      v["error_map_info"] = error_map_info;
+    }
+    if (ctx.extended_error_info()) {
+      tao::json::basic_value<Traits> extended_error_info;
+      extended_error_info["ref"] = ctx.extended_error_info()->reference();
+      extended_error_info["context"] = ctx.extended_error_info()->context();
+      v["extended_error_info"] = extended_error_info;
+    }
+  }
+};
+} // namespace tao::json