couchbase 4.7.0-dev.1 → 4.7.1

package/deps/couchbase-cxx-client/couchbase/collection.hxx

@@ -35,6 +35,8 @@
 #include <couchbase/lookup_in_specs.hxx>
 #include <couchbase/mutate_in_options.hxx>
 #include <couchbase/mutate_in_specs.hxx>
+#include <couchbase/node_id_for_options.hxx>
+#include <couchbase/node_ids_options.hxx>
 #include <couchbase/query_options.hxx>
 #include <couchbase/remove_options.hxx>
 #include <couchbase/replace_options.hxx>
@@ -1090,6 +1092,77 @@ public:
   [[nodiscard]] auto scan(const scan_type& scan_type, const scan_options& options = {}) const
     -> std::future<std::pair<error, scan_result>>;
 
+  /**
+   * Resolves a document key to the identity of the cluster node that currently
+   * owns it, using the client-side vBucket map (no network round-trip).
+   *
+   * @param document_id the document id to resolve
+   * @param options options to customize the request
+   * @param handler the handler that receives the result
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  void node_id_for(std::string document_id,
+                   const node_id_for_options& options,
+                   node_id_for_handler&& handler) const;
+
+  /**
+   * Resolves a document key to the identity of the cluster node that currently
+   * owns it, using the client-side vBucket map (no network round-trip).
+   *
+   * @param document_id the document id to resolve
+   * @param options options to customize the request
+   * @return future carrying the error (if any) and node_id
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id_for(std::string document_id,
+                                 const node_id_for_options& options = {}) const
+    -> std::future<std::pair<error, node_id>>;
+
+  /**
+   * Returns the set of cluster nodes that currently serve key-value
+   * traffic for this collection's bucket, drawn from the client-side
+   * topology snapshot (no network round-trip).
+   *
+   * Each entry corresponds to one cluster node and is the same node_id
+   * the SDK reports on KV results and errors that touched that node, so
+   * the returned set is directly comparable to the keys of any
+   * application-side state that is keyed by node_id (e.g. a per-node
+   * circuit breaker registry). A periodic sweep that diffs the
+   * registry's keys against this set is the canonical way to retire
+   * tracker state for a node that has been removed from the cluster
+   * topology.
+   *
+   * Nodes that do not expose a key-value port for the configured
+   * transport (TLS or plain) are excluded from the returned set, since
+   * they do not serve KV operations and therefore have no meaningful
+   * identity from the SDK's point of view.
+   *
+   * @param options options to customize the request
+   * @param handler the handler that receives the result
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  void node_ids(const node_ids_options& options, node_ids_handler&& handler) const;
+
+  /**
+   * Returns the set of cluster nodes that currently serve key-value
+   * traffic for this collection's bucket, drawn from the client-side
+   * topology snapshot (no network round-trip).
+   *
+   * @param options options to customize the request
+   * @return future carrying the error (if any) and the set of node_ids
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_ids(const node_ids_options& options = {}) const
+    -> std::future<std::pair<error, std::vector<node_id>>>;
+
   [[nodiscard]] auto query_indexes() const -> collection_query_index_manager;
 
 private:

package/deps/couchbase-cxx-client/couchbase/error.hxx

@@ -18,6 +18,7 @@
 #pragma once
 
 #include <couchbase/error_context.hxx>
+#include <couchbase/node_id.hxx>
 
 #include <memory>
 #include <optional>
@@ -32,12 +33,26 @@ public:
   error() = default;
   error(std::error_code ec, std::string message = {}, error_context ctx = {});
   error(std::error_code ec, std::string message, error_context ctx, error cause);
+  error(std::error_code ec, std::string message, error_context ctx, couchbase::node_id node_id);
 
   [[nodiscard]] auto ec() const -> std::error_code;
   [[nodiscard]] auto message() const -> const std::string&;
   [[nodiscard]] auto ctx() const -> const error_context&;
   [[nodiscard]] auto cause() const -> std::optional<error>;
 
+  /**
+   * Returns the identity of the cluster node where the error occurred.
+   *
+   * The returned node_id is default-constructed (falsy) when the node
+   * could not be determined (e.g. for non-KV errors).
+   *
+   * @return identity of the node that returned the error
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id() const -> const couchbase::node_id&;
+
   explicit operator bool() const;
   auto operator==(const error& other) const -> bool;
 
@@ -46,6 +61,7 @@ private:
   std::string message_{};
   error_context ctx_{};
   std::shared_ptr<error> cause_{};
+  couchbase::node_id node_id_{};
 };
 
 } // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/node_id.hxx

@@ -0,0 +1,123 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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 <cstdint>
+#include <functional>
+#include <string>
+
+namespace couchbase
+{
+
+/**
+ * Uniquely identifies a cluster node.
+ *
+ * On Couchbase Server 8.0.1+ the identifier is the server-assigned node UUID.
+ * On older releases, a stable opaque token is derived from the node's hostname
+ * and management port.
+ *
+ * The type is equality-comparable, ordered, and hashable.
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+class node_id
+{
+public:
+  /**
+   * Creates an empty (invalid) node_id.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  node_id() = default;
+
+  /**
+   * User-facing identifier string.
+   *
+   * Returns node_uuid when the server provides one, otherwise a stable
+   * hex-encoded hash derived from hostname and management port.
+   *
+   * @return opaque identifier string (empty for default-constructed instances)
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto id() const -> const std::string&;
+
+  /**
+   * The server-assigned node UUID (empty on servers before 8.0.1).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_uuid() const -> const std::string&;
+
+  /**
+   * The hostname of the node.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto hostname() const -> const std::string&;
+
+  /**
+   * The port of the node's key-value service.
+   *
+   * This reflects the port actually used by the client: the TLS port when the
+   * cluster connection is TLS-enabled, otherwise the plain port.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto port() const -> std::uint16_t;
+
+  /**
+   * Returns true when the node_id was properly initialized (not default-constructed).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  explicit operator bool() const;
+
+  auto operator==(const node_id& other) const -> bool;
+  auto operator!=(const node_id& other) const -> bool;
+  auto operator<(const node_id& other) const -> bool;
+
+private:
+  friend class internal_node_id;
+
+  node_id(std::string node_uuid, std::string hostname, std::uint16_t port);
+
+  std::string node_uuid_{};
+  std::string hostname_{};
+  std::uint16_t port_{ 0 };
+  // Computed once at construction: node_uuid_ if non-empty, otherwise a
+  // deterministic hex-encoded CRC32 hash of "hostname:port".
+  std::string id_{};
+};
+
+} // namespace couchbase
+
+template<>
+struct std::hash<couchbase::node_id> {
+  auto operator()(const couchbase::node_id& nid) const noexcept -> std::size_t
+  {
+    return std::hash<std::string>{}(nid.id());
+  }
+};

package/deps/couchbase-cxx-client/couchbase/node_id_for_options.hxx

@@ -0,0 +1,61 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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/common_options.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_id_for().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_id_for_options : public common_options<node_id_for_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_id_for_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_id_for_handler = std::function<void(error, node_id)>;
+
+} // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/node_ids_options.hxx

@@ -0,0 +1,62 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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/common_options.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_ids().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_ids_options : public common_options<node_ids_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_ids_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_ids_handler = std::function<void(error, std::vector<node_id>)>;
+
+} // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/result.hxx

@@ -18,6 +18,9 @@
 #pragma once
 
 #include <couchbase/cas.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <utility>
 
 namespace couchbase
 {
@@ -48,6 +51,19 @@ public:
   {
   }
 
+  /**
+   * @param cas
+   * @param node_id identity of the node that served the request
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  result(couchbase::cas cas, couchbase::node_id node_id)
+    : cas_(cas)
+    , node_id_(std::move(node_id))
+  {
+  }
+
   /**
    * @return
    *
@@ -59,8 +75,34 @@ public:
     return cas_;
   }
 
+  /**
+   * Returns the identity of the cluster node that served this request.
+   *
+   * The returned node_id is default-constructed (falsy) when the node
+   * could not be determined.
+   *
+   * @return identity of the serving node
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id() const -> const couchbase::node_id&
+  {
+    return node_id_;
+  }
+
+  /**
+   * @since 1.3.2
+   * @internal
+   */
+  void node_id(couchbase::node_id id)
+  {
+    node_id_ = std::move(id);
+  }
+
 private:
   couchbase::cas cas_{ 0U };
+  couchbase::node_id node_id_{};
 };
 
 } // namespace couchbase

package/dist/binding.d.ts

@@ -2854,6 +2854,7 @@ export interface CppConnection extends CppConnectionAutogen {
         report_id?: string;
         bucket_name?: string;
         services?: CppServiceType[];
+        timeout?: number;
     }, callback: (err: CppError | null, result: {
         version: number;
         id: string;

package/dist/bucket.d.ts

@@ -2,7 +2,7 @@ import { CppConnection } from './binding';
 import { Cluster } from './cluster';
 import { Collection } from './collection';
 import { CollectionManager } from './collectionmanager';
-import { PingOptions, PingResult } from './diagnosticstypes';
+import { PingOptions, PingResult, WaitUntilReadyOptions } from './diagnosticstypes';
 import { Scope } from './scope';
 import { StreamableRowPromise } from './streamablepromises';
 import { Transcoder } from './transcoders';
@@ -96,4 +96,12 @@ export declare class Bucket {
      * @param callback A node-style callback to be invoked after execution.
      */
     ping(options?: PingOptions, callback?: NodeCallback<PingResult>): Promise<PingResult>;
+    /**
+     * Waits until the bucket reaches the desired state or the timeout elapses.
+     *
+     * @param timeout The time in milliseconds to wait for the bucket to become ready.
+     * @param options Optional parameters.
+     * @param callback A callback to be invoked after execution.
+     */
+    waitUntilReady(timeout: number, options?: WaitUntilReadyOptions, callback?: NodeCallback<void>): Promise<void>;
 }

package/dist/bucket.js

@@ -4,6 +4,7 @@ exports.Bucket = void 0;
 const collection_1 = require("./collection");
 const collectionmanager_1 = require("./collectionmanager");
 const diagnosticsexecutor_1 = require("./diagnosticsexecutor");
+const waituntilreadyexecutor_1 = require("./waituntilreadyexecutor");
 const scope_1 = require("./scope");
 const utilities_1 = require("./utilities");
 const viewexecutor_1 = require("./viewexecutor");
@@ -142,5 +143,25 @@ class Bucket {
             bucket: this.name,
         }), callback);
     }
+    /**
+     * Waits until the bucket reaches the desired state or the timeout elapses.
+     *
+     * @param timeout The time in milliseconds to wait for the bucket to become ready.
+     * @param options Optional parameters.
+     * @param callback A callback to be invoked after execution.
+     */
+    waitUntilReady(timeout, options, callback) {
+        if (options instanceof Function) {
+            callback = arguments[1];
+            options = undefined;
+        }
+        if (!options) {
+            options = {};
+        }
+        const exec = new waituntilreadyexecutor_1.WaitUntilReadyExecutor(this._cluster, this.name);
+        const timeout_ = timeout;
+        const options_ = options;
+        return utilities_1.PromiseHelper.wrapAsync(() => exec.waitUntilReady(timeout_, options_), callback);
+    }
 }
 exports.Bucket = Bucket;

package/dist/cluster.d.ts

@@ -5,7 +5,7 @@ import { Authenticator } from './authenticators';
 import { CppConnection } from './binding';
 import { Bucket } from './bucket';
 import { BucketManager } from './bucketmanager';
-import { DiagnosticsOptions, DiagnosticsResult, PingOptions, PingResult } from './diagnosticstypes';
+import { DiagnosticsOptions, DiagnosticsResult, PingOptions, PingResult, WaitUntilReadyOptions } from './diagnosticstypes';
 import { EventingFunctionManager } from './eventingfunctionmanager';
 import { CouchbaseLogger, Logger } from './logger';
 import { Meter } from './metrics';
@@ -521,6 +521,15 @@ export declare class Cluster {
      * @param callback A node-style callback to be invoked after execution.
      */
     ping(options?: PingOptions, callback?: NodeCallback<PingResult>): Promise<PingResult>;
+    /**
+     * Waits until the cluster reaches the desired state or the timeout elapses.
+     * The default desired state is ClusterState.Online.
+     *
+     * @param timeout The time in milliseconds to wait for the cluster to become ready.
+     * @param options Optional parameters for this operation.
+     * @param callback A callback to be invoked after execution.
+     */
+    waitUntilReady(timeout: number, options?: WaitUntilReadyOptions, callback?: NodeCallback<void>): Promise<void>;
     /**
      * Shuts down this cluster object.  Cleaning up all resources associated with it.
      *

package/dist/cluster.js

@@ -13,6 +13,7 @@ const bucketmanager_1 = require("./bucketmanager");
 const configProfile_1 = require("./configProfile");
 const connspec_1 = require("./connspec");
 const diagnosticsexecutor_1 = require("./diagnosticsexecutor");
+const waituntilreadyexecutor_1 = require("./waituntilreadyexecutor");
 const eventingfunctionmanager_1 = require("./eventingfunctionmanager");
 const logger_1 = require("./logger");
 const loggingmeter_1 = require("./loggingmeter");
@@ -487,6 +488,27 @@ class Cluster {
         const options_ = options;
         return utilities_1.PromiseHelper.wrapAsync(() => exec.ping(options_), callback);
     }
+    /**
+     * Waits until the cluster reaches the desired state or the timeout elapses.
+     * The default desired state is ClusterState.Online.
+     *
+     * @param timeout The time in milliseconds to wait for the cluster to become ready.
+     * @param options Optional parameters for this operation.
+     * @param callback A callback to be invoked after execution.
+     */
+    waitUntilReady(timeout, options, callback) {
+        if (options instanceof Function) {
+            callback = arguments[1];
+            options = undefined;
+        }
+        if (!options) {
+            options = {};
+        }
+        const exec = new waituntilreadyexecutor_1.WaitUntilReadyExecutor(this);
+        const timeout_ = timeout;
+        const options_ = options;
+        return utilities_1.PromiseHelper.wrapAsync(() => exec.waitUntilReady(timeout_, options_), callback);
+    }
     /**
      * Shuts down this cluster object.  Cleaning up all resources associated with it.
      *

package/dist/collection.d.ts

@@ -8,7 +8,7 @@ import { CouchbaseList, CouchbaseMap, CouchbaseQueue, CouchbaseSet } from './dat
 import { DurabilityLevel, ReadPreference, StoreSemantics } from './generaltypes';
 import { MutationState } from './mutationstate';
 import { ObservableRequestHandler } from './observabilityhandler';
-import { ObservabilityInstruments } from './observabilitytypes';
+import { KeyValueOp, ObservabilityInstruments } from './observabilitytypes';
 import { CollectionQueryIndexManager } from './queryindexmanager';
 import { RangeScan, SamplingScan, PrefixScan } from './rangeScan';
 import { Scope } from './scope';
@@ -578,7 +578,7 @@ export declare class Collection {
     /**
      * @internal
      */
-    _getReplica(key: string, obsReqHandler: ObservableRequestHandler, options: {
+    _getReplica(key: string, opType: KeyValueOp, obsReqHandler: ObservableRequestHandler | null, options: {
         transcoder?: Transcoder;
         timeout?: number;
         readPreference?: ReadPreference;
@@ -718,7 +718,7 @@ export declare class Collection {
     /**
      * @internal
      */
-    _lookupInReplica(key: string, obsReqHandler: ObservableRequestHandler, specs: LookupInSpec[], options: {
+    _lookupInReplica(key: string, opType: KeyValueOp, obsReqHandler: ObservableRequestHandler | null, specs: LookupInSpec[], options: {
         timeout?: number;
         readPreference?: ReadPreference;
         parentSpan?: RequestSpan;