couchbase 3.8.2 → 3.9.1

data/ext/couchbase/core/protostellar/component.hxx

@@ -0,0 +1,391 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2026. 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
+
+// Views are deprecated in the core API but still routable over couchbase2, so the component names
+// document_view_request in its interface. Suppress the core-deprecation attribute for this header's
+// includes and declarations (portable convention shared with cluster.cxx). push/pop the macro so an
+// including translation unit that already defined it keeps its state restored.
+#pragma push_macro("COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS")
+#define COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS
+
+// The Protostellar KV component: the couchbase2 counterpart to the MCBP data-plane. It owns the
+// gRPC stubs over a channel and executes core KV operations by encoding the request (kv_converter),
+// dispatching it through the gRPC<->asio bridge, and decoding the reply plus a mapped error
+// context. cluster_impl routes KV ops here when the cluster was opened with couchbase2://.
+
+#include "core/cluster_credentials.hxx"
+#include "core/io/mcbp_traits.hxx"
+#include "core/operations/document_analytics.hxx"
+#include "core/operations/document_append.hxx"
+#include "core/operations/document_decrement.hxx"
+#include "core/operations/document_exists.hxx"
+#include "core/operations/document_get.hxx"
+#include "core/operations/document_get_and_lock.hxx"
+#include "core/operations/document_get_and_touch.hxx"
+#include "core/operations/document_get_projected.hxx"
+#include "core/operations/document_increment.hxx"
+#include "core/operations/document_insert.hxx"
+#include "core/operations/document_prepend.hxx"
+#include "core/operations/document_query.hxx"
+#include "core/operations/document_remove.hxx"
+#include "core/operations/document_replace.hxx"
+#include "core/operations/document_search.hxx"
+#include "core/operations/document_touch.hxx"
+#include "core/operations/document_unlock.hxx"
+#include "core/operations/document_upsert.hxx"
+#include "core/operations/document_view.hxx"
+#include "core/operations/management/bucket_create.hxx"
+#include "core/operations/management/bucket_drop.hxx"
+#include "core/operations/management/bucket_flush.hxx"
+#include "core/operations/management/bucket_get.hxx"
+#include "core/operations/management/bucket_get_all.hxx"
+#include "core/operations/management/bucket_update.hxx"
+#include "core/operations/management/collection_create.hxx"
+#include "core/operations/management/collection_drop.hxx"
+#include "core/operations/management/collection_update.hxx"
+#include "core/operations/management/query_index_build_deferred.hxx"
+#include "core/operations/management/query_index_create.hxx"
+#include "core/operations/management/query_index_drop.hxx"
+#include "core/operations/management/query_index_get_all.hxx"
+#include "core/operations/management/scope_create.hxx"
+#include "core/operations/management/scope_drop.hxx"
+#include "core/operations/management/scope_get_all.hxx"
+#include "core/operations/management/search_index_analyze_document.hxx"
+#include "core/operations/management/search_index_control_ingest.hxx"
+#include "core/operations/management/search_index_control_plan_freeze.hxx"
+#include "core/operations/management/search_index_control_query.hxx"
+#include "core/operations/management/search_index_drop.hxx"
+#include "core/operations/management/search_index_get.hxx"
+#include "core/operations/management/search_index_get_all.hxx"
+#include "core/operations/management/search_index_get_documents_count.hxx"
+#include "core/operations/management/search_index_upsert.hxx"
+#include "core/protostellar/compression_settings.hxx"
+#include "core/protostellar/dispatcher.hxx"
+#include "core/timeout_defaults.hxx"
+#include "core/utils/movable_function.hxx"
+
+#include <asio/io_context.hpp>
+
+#include <chrono>
+#include <memory>
+#include <string>
+
+namespace couchbase::core::protostellar
+{
+
+// Per-service defaults, used when a request does not carry its own timeout. Each field is defaulted
+// from timeout_defaults rather than left value-initialised: a zero here no longer means "no limit"
+// but "budget already spent", so a default-constructed aggregate would reject every request that
+// relies on the default instead of running it.
+struct component_timeouts {
+  std::chrono::milliseconds key_value{ timeout_defaults::key_value_timeout };
+  std::chrono::milliseconds query{ timeout_defaults::query_timeout };
+  std::chrono::milliseconds analytics{ timeout_defaults::analytics_timeout };
+  std::chrono::milliseconds search{ timeout_defaults::search_timeout };
+  std::chrono::milliseconds view{ timeout_defaults::view_timeout };
+  std::chrono::milliseconds management{ timeout_defaults::management_timeout };
+  std::chrono::milliseconds key_value_durable{ timeout_defaults::key_value_durable_timeout };
+};
+
+// Construction parameters for `component`, grouped so that adding one is a source-compatible
+// change. Every field a caller can reasonably omit carries a default, so a new trailing field
+// leaves existing initialisers compiling instead of silently shifting a positional argument onto
+// the wrong parameter -- which is the failure this shape exists to prevent, the constructor having
+// gained and lost trailing parameters repeatedly as services were added.
+struct component_config {
+  std::shared_ptr<grpc::Channel> channel{};
+  cluster_credentials credentials{};
+  component_timeouts timeouts{};
+  kv::compression_settings compression{};
+};
+
+// The core KV request types the component can execute over couchbase2. cluster_impl routes only
+// these to the component; any other KV request is answered with feature_not_available.
+template<typename Request>
+inline constexpr bool component_supports_v = false;
+template<>
+inline constexpr bool component_supports_v<operations::get_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::get_projected_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::upsert_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::insert_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::replace_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::remove_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::touch_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::exists_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::get_and_lock_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::unlock_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::get_and_touch_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::increment_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::decrement_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::append_request> = true;
+template<>
+inline constexpr bool component_supports_v<operations::prepend_request> = true;
+
+// Resolves the effective timeout for a KV operation: the request's own timeout if set, else the
+// per-service default — the durable default for a synchronous-durability mutation (RFC 77
+// KvDurableTimeout), the standard KV default otherwise. Free function so it is unit-testable.
+//
+// No lower bound is imposed on an explicit request timeout. The MCBP path raises a durable
+// operation's timeout to a 1500ms floor, which it needs because it has no durable default at all
+// and a durable write there inherits the 2.5s KV budget; resolving KvDurableTimeout is the
+// RFC-specified mechanism for that, and neither RFC 59 nor RFC 77 states a floor. A caller who
+// names a timeout gets the one they named.
+[[nodiscard]] inline auto
+resolve_kv_timeout(std::optional<std::chrono::milliseconds> request_timeout,
+                   couchbase::durability_level level,
+                   const component_timeouts& timeouts) -> std::chrono::milliseconds
+{
+  const auto fallback =
+    (level == couchbase::durability_level::none) ? timeouts.key_value : timeouts.key_value_durable;
+  return request_timeout.value_or(fallback);
+}
+
+// The durability level a request asks for, or `none` for a request type that cannot carry one.
+// Lets a caller generic over the request type apply the rule above without knowing which types
+// have the member; `supports_durability_v` is the same trait the MCBP path keys its own durability
+// handling on, so the two transports agree on which operations are durable.
+template<class Request>
+[[nodiscard]] auto
+requested_durability(const Request& request) -> couchbase::durability_level
+{
+  if constexpr (io::mcbp_traits::supports_durability_v<Request>) {
+    return request.durability_level;
+  } else {
+    static_cast<void>(request);
+    return couchbase::durability_level::none;
+  }
+}
+
+class component
+{
+public:
+  component(asio::io_context& io, component_config config);
+  component(const component&) = delete;
+  component(component&&) = delete;
+  auto operator=(const component&) -> component& = delete;
+  auto operator=(component&&) -> component& = delete;
+  // Out of line: `stubs` is incomplete here, so its deleter cannot be instantiated in this header.
+  ~component();
+
+  // The channel every call of this component is issued on.
+  [[nodiscard]] auto channel() const -> const std::shared_ptr<grpc::Channel>&;
+
+  auto execute(const operations::get_request& request,
+               utils::movable_function<void(operations::get_response)>&& handler) -> pending_call;
+  auto execute(const operations::get_projected_request& request,
+               utils::movable_function<void(operations::get_projected_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::upsert_request& request,
+               utils::movable_function<void(operations::upsert_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::insert_request& request,
+               utils::movable_function<void(operations::insert_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::replace_request& request,
+               utils::movable_function<void(operations::replace_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::remove_request& request,
+               utils::movable_function<void(operations::remove_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::touch_request& request,
+               utils::movable_function<void(operations::touch_response)>&& handler) -> pending_call;
+  auto execute(const operations::exists_request& request,
+               utils::movable_function<void(operations::exists_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::get_and_lock_request& request,
+               utils::movable_function<void(operations::get_and_lock_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::unlock_request& request,
+               utils::movable_function<void(operations::unlock_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::get_and_touch_request& request,
+               utils::movable_function<void(operations::get_and_touch_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::increment_request& request,
+               utils::movable_function<void(operations::increment_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::decrement_request& request,
+               utils::movable_function<void(operations::decrement_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::append_request& request,
+               utils::movable_function<void(operations::append_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::prepend_request& request,
+               utils::movable_function<void(operations::prepend_response)>&& handler)
+    -> pending_call;
+
+  // N1QL query over the couchbase2 server-streaming transport. Rows are buffered into the response
+  // when no callback is provided, or delivered incrementally to row_callback when present; the
+  // terminal message carries the metadata.
+  auto execute(const operations::query_request& request,
+               utils::movable_function<void(operations::query_response)>&& handler) -> pending_call;
+
+  // Analytics over the couchbase2 server-streaming transport; same shape as query.
+  auto execute(const operations::analytics_request& request,
+               utils::movable_function<void(operations::analytics_response)>&& handler)
+    -> pending_call;
+
+  // FTS search over the couchbase2 server-streaming transport. Hits are buffered into the response.
+  auto execute(const operations::search_request& request,
+               utils::movable_function<void(operations::search_response)>&& handler)
+    -> pending_call;
+
+  // Map/reduce views over the couchbase2 server-streaming transport.
+  auto execute(const operations::document_view_request& request,
+               utils::movable_function<void(operations::document_view_response)>&& handler)
+    -> pending_call;
+
+  // Bucket management (unary admin RPCs over admin.bucket.v1).
+  auto execute(
+    const operations::management::bucket_get_all_request& request,
+    utils::movable_function<void(operations::management::bucket_get_all_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::management::bucket_get_request& request,
+               utils::movable_function<void(operations::management::bucket_get_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::bucket_create_request& request,
+    utils::movable_function<void(operations::management::bucket_create_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::bucket_update_request& request,
+    utils::movable_function<void(operations::management::bucket_update_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::bucket_drop_request& request,
+    utils::movable_function<void(operations::management::bucket_drop_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::bucket_flush_request& request,
+    utils::movable_function<void(operations::management::bucket_flush_response)>&& handler)
+    -> pending_call;
+
+  // Scope/collection management (unary admin RPCs over admin.collection.v1).
+  auto execute(
+    const operations::management::scope_get_all_request& request,
+    utils::movable_function<void(operations::management::scope_get_all_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::scope_create_request& request,
+    utils::movable_function<void(operations::management::scope_create_response)>&& handler)
+    -> pending_call;
+  auto execute(const operations::management::scope_drop_request& request,
+               utils::movable_function<void(operations::management::scope_drop_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::collection_create_request& request,
+    utils::movable_function<void(operations::management::collection_create_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::collection_update_request& request,
+    utils::movable_function<void(operations::management::collection_update_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::collection_drop_request& request,
+    utils::movable_function<void(operations::management::collection_drop_response)>&& handler)
+    -> pending_call;
+
+  // Query index management (unary admin RPCs over admin.query.v1).
+  auto execute(
+    const operations::management::query_index_get_all_request& request,
+    utils::movable_function<void(operations::management::query_index_get_all_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::query_index_create_request& request,
+    utils::movable_function<void(operations::management::query_index_create_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::query_index_drop_request& request,
+    utils::movable_function<void(operations::management::query_index_drop_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::query_index_build_deferred_request& request,
+    utils::movable_function<void(operations::management::query_index_build_deferred_response)>&&
+      handler) -> pending_call;
+
+  // Search index management (unary admin RPCs over admin.search.v1).
+  auto execute(
+    const operations::management::search_index_upsert_request& request,
+    utils::movable_function<void(operations::management::search_index_upsert_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::search_index_get_request& request,
+    utils::movable_function<void(operations::management::search_index_get_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::search_index_get_all_request& request,
+    utils::movable_function<void(operations::management::search_index_get_all_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::search_index_drop_request& request,
+    utils::movable_function<void(operations::management::search_index_drop_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::search_index_analyze_document_request& request,
+    utils::movable_function<void(operations::management::search_index_analyze_document_response)>&&
+      handler) -> pending_call;
+  auto execute(const operations::management::search_index_get_documents_count_request& request,
+               utils::movable_function<
+                 void(operations::management::search_index_get_documents_count_response)>&& handler)
+    -> pending_call;
+  auto execute(
+    const operations::management::search_index_control_ingest_request& request,
+    utils::movable_function<void(operations::management::search_index_control_ingest_response)>&&
+      handler) -> pending_call;
+  auto execute(
+    const operations::management::search_index_control_query_request& request,
+    utils::movable_function<void(operations::management::search_index_control_query_response)>&&
+      handler) -> pending_call;
+  auto execute(const operations::management::search_index_control_plan_freeze_request& request,
+               utils::movable_function<
+                 void(operations::management::search_index_control_plan_freeze_response)>&& handler)
+    -> pending_call;
+
+private:
+  // The generated gRPC stubs are held behind an opaque pointer so the generated protobuf and gRPC
+  // surface stays out of every translation unit that includes this header -- none of it appears in
+  // the interface, and the stub count grows with every service the transport learns to speak.
+  struct stubs;
+
+  asio::io_context& io_;
+  std::unique_ptr<stubs> stubs_;
+  std::string authorization_;
+  component_timeouts timeouts_;
+  kv::compression_settings compression_;
+  // Declared last, so it is destroyed first: ~dispatcher() cancels and drains the calls issued
+  // through the stubs above, which must therefore still be alive while it runs.
+  dispatcher dispatcher_;
+};
+
+} // namespace couchbase::core::protostellar
+
+#pragma pop_macro("COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS")

data/ext/couchbase/core/{columnar/bootstrap_notification_subscriber.hxx → protostellar/compression_settings.hxx}

@@ -1,6 +1,6 @@
 /* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *   Copyright 2020-Present Couchbase, Inc.
+ *   Copyright 2026. Couchbase, Inc.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
  *   you may not use this file except in compliance with the License.
@@ -17,16 +17,17 @@
 
 #pragma once
 
-#include "core/impl/bootstrap_error.hxx"
+#include <cstddef>
 
-namespace couchbase::core::columnar
+namespace couchbase::core::protostellar::kv
 {
 
-class bootstrap_notification_subscriber
-{
-public:
-  virtual ~bootstrap_notification_subscriber() = default;
-  virtual void notify_bootstrap_error(const core::impl::bootstrap_error& error) = 0;
-  virtual void notify_bootstrap_success(const std::string& session_id) = 0;
+// The user's compression knobs. Defaults mirror the classic SDK (enabled; snappy applied only when
+// the value is at least min_size and shrinks below min_ratio).
+struct compression_settings {
+  bool enabled{ true };
+  std::size_t min_size{ 32 };
+  double min_ratio{ 0.83 };
 };
-} // namespace couchbase::core::columnar
+
+} // namespace couchbase::core::protostellar::kv

data/ext/couchbase/core/protostellar/credentials.cxx

@@ -0,0 +1,233 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2026. 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/protostellar/credentials.hxx"
+
+#include "core/capella_ca.hxx"
+#include "core/cluster_credentials.hxx"
+#include "core/cluster_options.hxx"
+#include "core/logger/logger.hxx"
+#include "core/mozilla_ca_bundle.hxx"
+#include "core/platform/base64.h"
+#include "core/protostellar/dispatcher.hxx"
+#include "core/tls_verify_mode.hxx"
+
+#include <grpcpp/create_channel.h>
+#include <grpcpp/security/tls_certificate_provider.h>
+#include <grpcpp/security/tls_credentials_options.h>
+
+#include <fstream>
+#include <optional>
+#include <sstream>
+#include <stdexcept>
+#include <utility>
+#include <vector>
+
+namespace couchbase::core::protostellar
+{
+namespace
+{
+// Read a PEM file that the caller has explicitly configured. Fails closed: a configured but
+// unreadable/empty trust or certificate file is an error, never a silent fall-back to the system
+// trust store (which would broaden the accepted-issuer set beyond the operator's intent).
+auto
+read_required_file(const std::string& path) -> std::string
+{
+  const std::ifstream stream{ path, std::ios::binary };
+  if (!stream) {
+    throw std::runtime_error("couchbase2: cannot read configured TLS file: " + path);
+  }
+  std::ostringstream buffer;
+  buffer << stream.rdbuf();
+  auto contents = buffer.str();
+  if (contents.empty()) {
+    throw std::runtime_error("couchbase2: configured TLS file is empty: " + path);
+  }
+  return contents;
+}
+
+// The default trust material, concatenated into a single PEM as gRPC's pem_root_certs expects: the
+// Couchbase Capella root, plus the bundled Mozilla roots unless the operator disabled them. RFC 77
+// (Bootstrapping -> Security) requires that "the set of Root CAs that SDKs trust by default for
+// couchbase2 must be identical to the one used for Classic", and the Capella root is what this path
+// was missing -- MCBP's configure_tls_context() adds it unconditionally whenever no explicit trust
+// material is configured.
+//
+// Why the platform trust store is not also folded in, unlike MCBP's set_default_verify_paths():
+// gRPC accepts trust material only as one PEM blob and treats a non-empty pem_root_certs as the
+// entire store -- "If this parameter is empty, the default roots will be used" -- so there is
+// nothing to layer onto and no incremental API to layer with. Snapshotting the platform store into
+// that blob would not reproduce MCBP anyway: under OpenSSL/BoringSSL "system roots" is not a
+// defined set the way the JVM's trust store or .NET's X509Chain is, but whatever the host happens
+// to ship, relocatable at run time through SSL_CERT_FILE/SSL_CERT_DIR, and BoringSSL compiles in
+// different default paths again. The two sets this SDK ships and can therefore guarantee are the
+// Capella root and the Mozilla bundle, so those are what the default trusts. A private or corporate
+// CA is configured explicitly, which replaces this set outright -- exactly as it does for MCBP.
+//
+// For reference, the other SDKs land in the same place by different routes: Java trusts its Capella
+// root plus the JVM trust store (SecurityConfig::defaultCaCertificates), .NET accepts whatever the
+// platform validated and adds its Capella root to the chain's ExtraStore, and Go trusts only
+// x509.SystemCertPool() and ships no Capella root at all.
+auto
+default_root_certs(bool include_mozilla_bundle) -> std::string
+{
+  std::string pem{ default_ca::capellaCaCert };
+  if (!pem.empty() && pem.back() != '\n') {
+    pem.push_back('\n');
+  }
+  if (include_mozilla_bundle) {
+    for (const auto& cert : default_ca::mozilla_ca_certs()) {
+      pem.append(cert.body);
+      if (pem.back() != '\n') {
+        pem.push_back('\n');
+      }
+    }
+  }
+  return pem;
+}
+
+// The configured client certificate/key pair for mTLS, as {private_key, certificate_chain}.
+// Returns nullopt when neither is set; throws when only one is set, since a half-configured
+// identity produces an opaque connect-time failure rather than a clear misconfiguration error.
+auto
+read_client_identity(const cluster_credentials& credentials)
+  -> std::optional<std::pair<std::string, std::string>>
+{
+  const bool have_cert = !credentials.certificate_path.empty();
+  const bool have_key = !credentials.key_path.empty();
+  if (!have_cert && !have_key) {
+    return std::nullopt;
+  }
+  if (have_cert != have_key) {
+    throw std::invalid_argument("couchbase2: client certificate authentication requires both a "
+                                "certificate and a private key; only one was configured");
+  }
+  return std::pair{ read_required_file(credentials.key_path),
+                    read_required_file(credentials.certificate_path) };
+}
+} // namespace
+
+auto
+build_ssl_options(const cluster_options& options, const cluster_credentials& credentials)
+  -> grpc::SslCredentialsOptions
+{
+  grpc::SslCredentialsOptions ssl;
+  if (!options.trust_certificate_value.empty()) {
+    ssl.pem_root_certs = options.trust_certificate_value;
+  } else if (!options.trust_certificate.empty()) {
+    ssl.pem_root_certs = read_required_file(options.trust_certificate);
+  } else {
+    // Never left empty: gRPC's own fallback is the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment
+    // variable, else a process-wide override hook, else roots bundled in the gRPC installation --
+    // none of which is the platform trust store, and all of which are outside this SDK's control.
+    // Disabling the Mozilla bundle drops that layer only; the Capella root stays, matching MCBP,
+    // where disable_mozilla_ca_certificates likewise gates just the bundle loop.
+    ssl.pem_root_certs = default_root_certs(!options.disable_mozilla_ca_certificates);
+  }
+
+  if (auto identity = read_client_identity(credentials)) {
+    ssl.pem_private_key = identity->first;
+    ssl.pem_cert_chain = identity->second;
+  }
+  return ssl;
+}
+
+auto
+basic_auth_value(const std::string& username, const std::string& password) -> std::string
+{
+  return "Basic " + base64::encode(username + ":" + password);
+}
+
+auto
+bearer_auth_value(const std::string& jwt_token) -> std::string
+{
+  return "Bearer " + jwt_token;
+}
+
+auto
+authorization_header(const cluster_credentials& credentials) -> std::string
+{
+  if (credentials.uses_jwt()) {
+    return bearer_auth_value(credentials.jwt_token);
+  }
+  if (credentials.uses_password()) {
+    return basic_auth_value(credentials.username, credentials.password);
+  }
+  return {};
+}
+
+auto
+tls_peer_verification_disabled(const cluster_options& options) -> bool
+{
+  return options.enable_tls && options.tls_verify == tls_verify_mode::none;
+}
+
+auto
+make_channel_credentials(const cluster_options& options, const cluster_credentials& credentials)
+  -> std::shared_ptr<grpc::ChannelCredentials>
+{
+  if (!options.enable_tls) {
+    // Fail closed: never let username/password or a JWT ride a plaintext channel (base64 is not
+    // encryption). couchbase2:// implies TLS; a programmatic config that disables it while
+    // carrying credentials is a misconfiguration, not a downgrade we perform silently.
+    if (credentials.uses_password() || credentials.uses_jwt() ||
+        !credentials.certificate_path.empty() || !credentials.key_path.empty()) {
+      throw std::invalid_argument(
+        "couchbase2: refusing to send credentials over a plaintext channel; enable TLS");
+    }
+    return grpc::InsecureChannelCredentials();
+  }
+  if (tls_peer_verification_disabled(options)) {
+    // Encrypt the channel but skip server-certificate and hostname verification. Used against
+    // dev/test gateways whose certificate cannot be chained to a trusted CA (e.g. the CNG cert
+    // served by the Couchbase operator on a k8s NodePort).
+    //
+    // Warn here rather than only at the call site: this is the one point every couchbase2 channel
+    // passes through, including callers that build a component directly without going through
+    // cluster::open. A deployment that enabled this by accident has to be able to see it.
+    CB_LOG_WARNING("couchbase2: TLS certificate verification is DISABLED (tls_verify=none); the "
+                   "connection is encrypted but unauthenticated and can be intercepted. Do not use "
+                   "this outside development.");
+    grpc::experimental::TlsChannelCredentialsOptions tls;
+    tls.set_verify_server_certs(false);
+    tls.set_check_call_host(false);
+    tls.set_certificate_verifier(std::make_shared<grpc::experimental::NoOpCertificateVerifier>());
+    // Still present the configured client identity (mTLS) so certificate auth works even when the
+    // gateway's server certificate cannot be verified. Skipping server verification does not imply
+    // skipping our own authentication.
+    if (auto identity = read_client_identity(credentials)) {
+      tls.set_certificate_provider(
+        std::make_shared<grpc::experimental::StaticDataCertificateProvider>(
+          std::vector<grpc::experimental::IdentityKeyCertPair>{
+            { identity->first, identity->second } }));
+      tls.watch_identity_key_cert_pairs();
+    }
+    return grpc::experimental::TlsCredentials(tls);
+  }
+  return grpc::SslCredentials(build_ssl_options(options, credentials));
+}
+
+auto
+make_channel(const std::string& endpoint,
+             const cluster_options& options,
+             const cluster_credentials& credentials) -> std::shared_ptr<grpc::Channel>
+{
+  return grpc::CreateCustomChannel(
+    endpoint, make_channel_credentials(options, credentials), default_channel_arguments());
+}
+
+} // namespace couchbase::core::protostellar