spice-couchbase 2.0.61 → 2.0.63

package/src/index.js

@@ -4,6 +4,8 @@ let _ = require("lodash");
 let couchbase = require("couchbase");
 const { ConflictResolutionType } = require("couchbase");
 const { QueryScanConsistency } = require("couchbase");
+const { parseResourceList, extractStatementResources } = require("./utility");
+const { createHealthMonitor, openHandles } = require("./connectionHealth");
 
 if (!Promise.allSettled) {
   Promise.allSettled = (promises) =>
@@ -50,6 +52,58 @@ const optimizeState = {
   seen: new Set(),
   cooldownUntil: 0,
 };
+// Auto cover indexing is opt-in per resource. A resource is the collection a
+// Database instance serves (scoped deployments) or the `type = '...'` literal
+// legacy bucket mode adds to every statement; raw statements also count their
+// FROM / JOIN keyspaces. Names are case-insensitive. A slow statement is
+// optimised when, in order of precedence:
+//   1. the call says so:        query_options.auto_optimize (true / false)
+//   2. the instance says so:    constructor option or connection config
+//                               `auto_optimize` (true / false)
+//   3. the application policy:  Database.setAutoOptimizePolicy(fn), where
+//                               fn(resource, context) returns true / false, or
+//                               undefined to defer to the static lists
+//   4. a static list names a resource it touches: comma-separated
+//      SPICE_COUCHBASE_OPTIMIZE_RESOURCES (`*` = every resource, which is the
+//      pre-2.0.62 behaviour), or connection config / constructor option
+//      `auto_optimize_resources`.
+const OPTIMIZE_ENABLED_RESOURCES = parseResourceList(
+  process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES,
+);
+let autoOptimizePolicy = null;
+
+// One health monitor per process, shared by every copy of this module that
+// ends up loaded. See connectionHealth.js.
+const HEALTH_MONITOR_KEY = Symbol.for("spice-couchbase.health-monitor");
+const health =
+  globalThis[HEALTH_MONITOR_KEY] ||
+  (globalThis[HEALTH_MONITOR_KEY] = createHealthMonitor());
+
+// Cluster handles live on the `spice.database` globals, which a reconnect
+// replaces. Instances read them at call time instead of copying them.
+const HANDLE_GLOBALS = {
+  cluster: "clusters",
+  connection: "connections",
+  scope: "scopes",
+  bucket_handle: "buckets",
+};
+
+function globalHandle(kind, connection_name) {
+  if (typeof spice === "undefined") return undefined;
+  return spice?.database?.[HANDLE_GLOBALS[kind]]?.[connection_name];
+}
+
+function requestedAutoOptimize(query_options) {
+  if (
+    !query_options ||
+    typeof query_options !== "object" ||
+    Array.isArray(query_options)
+  ) {
+    return undefined;
+  }
+  const value = query_options.auto_optimize ?? query_options.optimize;
+  return typeof value === "boolean" ? value : undefined;
+}
 
 function shouldOptimize(query) {
   if (!AUTO_OPTIMIZE_ENABLED) return false;
@@ -126,17 +180,15 @@ module.exports = class Database {
       scope,
       query_scope = "cluster",
       auto_create_collection,
+      auto_optimize,
+      auto_optimize_resources,
     } = {},
   ) {
     if (connection) {
       this.connection_name = connection;
-      this.connection = spice.database.connections[connection];
       this.query_scope = query_scope;
-      this.cluster = spice.database.clusters[connection];
       this.bucket = this.connection._scope._bucket._name;
       this.db_config = spice.config.database.connections[connection];
-      this.collection_manager =
-        spice.database.buckets[connection].collections();
       this.auto_create_collection =
         auto_create_collection ||
         ((collection ||
@@ -162,14 +214,11 @@ module.exports = class Database {
         scope ||
         spice.config.database.connections[connection].scope ||
         "_default";
-      this.scope = spice.database.scopes[connection];
       this.full_text_index =
         spice.config.database.connections[connection].full_text_index ||
         full_text_index;
       this.N1qlQuery = couchbase.N1qlQuery;
       this.SearchQuery = couchbase.SearchQuery;
-      this.collection = this.scope.collection(this.collection_name);
-      this.userManager = this.getUserManager(connection);
       if (!spice?.db?.collections) {
         spice.db = spice.db || {};
         spice.db.collections = new Set();
@@ -181,7 +230,225 @@ module.exports = class Database {
       this.use_bucket_name =
         spice.config.database.connections[this.connection_name].scope ==
         undefined;
+
+      // Auto cover indexing. See OPTIMIZE_ENABLED_RESOURCES for precedence.
+      const configured_auto_optimize =
+        auto_optimize ?? this.db_config.auto_optimize;
+      this.auto_optimize =
+        typeof configured_auto_optimize === "boolean"
+          ? configured_auto_optimize
+          : undefined;
+      this.enabled_resources = parseResourceList([
+        ...parseResourceList(this.db_config.auto_optimize_resources),
+        ...parseResourceList(auto_optimize_resources),
+      ]);
+    }
+  }
+
+  // Handles resolve from the globals on every access, so an instance created
+  // before a reconnect uses the new cluster afterwards. Assigning one pins it
+  // on that instance instead (tests, custom wiring).
+  pinHandle(kind, value) {
+    if (!Object.prototype.hasOwnProperty.call(this, "_pinned_handles")) {
+      Object.defineProperty(this, "_pinned_handles", {
+        value: {},
+        enumerable: false,
+        writable: true,
+      });
+    }
+    this._pinned_handles[kind] = value;
+  }
+
+  pinnedHandle(kind) {
+    const pinned = this._pinned_handles;
+    return pinned && kind in pinned ? { value: pinned[kind] } : null;
+  }
+
+  handle(kind) {
+    const pinned = this.pinnedHandle(kind);
+    return pinned ? pinned.value : globalHandle(kind, this.connection_name);
+  }
+
+  get cluster() {
+    return this.handle("cluster");
+  }
+  set cluster(value) {
+    this.pinHandle("cluster", value);
+  }
+
+  get connection() {
+    return this.handle("connection");
+  }
+  set connection(value) {
+    this.pinHandle("connection", value);
+  }
+
+  get scope() {
+    return this.handle("scope");
+  }
+  set scope(value) {
+    this.pinHandle("scope", value);
+  }
+
+  get collection() {
+    const pinned = this.pinnedHandle("collection");
+    if (pinned) return pinned.value;
+    const scope = this.scope;
+    if (!scope) return undefined;
+    // Collection handles are cheap but not free; cache one per scope object,
+    // which changes exactly when the connection is replaced.
+    if (this._collection_cache?.scope !== scope) {
+      Object.defineProperty(this, "_collection_cache", {
+        value: { scope, collection: scope.collection(this.collection_name) },
+        enumerable: false,
+        writable: true,
+        configurable: true,
+      });
+    }
+    return this._collection_cache.collection;
+  }
+  set collection(value) {
+    this.pinHandle("collection", value);
+  }
+
+  get collection_manager() {
+    const pinned = this.pinnedHandle("collection_manager");
+    if (pinned) return pinned.value;
+    return this.handle("bucket_handle")?.collections();
+  }
+  set collection_manager(value) {
+    this.pinHandle("collection_manager", value);
+  }
+
+  get userManager() {
+    const pinned = this.pinnedHandle("userManager");
+    if (pinned) return pinned.value;
+    return this.cluster?.users();
+  }
+  set userManager(value) {
+    this.pinHandle("userManager", value);
+  }
+
+  /**
+   * Reports a finished operation to the health monitor. Only connectivity
+   * errors (timeouts, cancelled requests, service not available) count.
+   */
+  recordOutcome(error) {
+    health.recordOutcome(this.connection_name, error);
+  }
+
+  recordSettled(results) {
+    for (const result of results) {
+      if (result?.status === "rejected") this.recordOutcome(result.reason);
+    }
+  }
+
+  async observe(operation) {
+    try {
+      return await operation;
+    } catch (error) {
+      this.recordOutcome(error);
+      throw error;
+    }
+  }
+
+  /** Per-connection health: healthy, reconnecting, generation, last error. */
+  static healthStatus() {
+    return health.status();
+  }
+
+  /** Probes a connection now and reconnects it if the probe fails. */
+  static checkHealth(connection_name = "default") {
+    return health.check(connection_name);
+  }
+
+  /** Opens a fresh cluster for a connection and swaps it in. */
+  static forceReconnect(connection_name = "default") {
+    return health.reconnect(connection_name);
+  }
+
+  /**
+   * Stops probing and reconnecting and closes replaced clusters still in
+   * their grace period. Call before closing `spice.database.clusters` on
+   * shutdown so a reconnect cannot race it.
+   */
+  static stopHealthMonitor() {
+    return health.stop();
+  }
+
+  /**
+   * Lets the application decide per resource whether slow statements may
+   * create covering indexes, e.g. from a per-resource setting an operator
+   * toggles at runtime. `policy(resource, { query, connection, collection })`
+   * returns true or false, or undefined to defer to the static lists. It is
+   * synchronous because it runs on the query path. Pass null to clear.
+   */
+  static setAutoOptimizePolicy(policy) {
+    if (
+      policy !== null &&
+      policy !== undefined &&
+      typeof policy !== "function"
+    ) {
+      throw new TypeError("Auto-optimize policy must be a function or null");
+    }
+    autoOptimizePolicy = policy || null;
+  }
+
+  static getAutoOptimizePolicy() {
+    return autoOptimizePolicy;
+  }
+
+  /**
+   * Resources a statement touches, plus this instance's collection: that is
+   * the keyspace `optimize()` would create the index on.
+   */
+  statementResources(query) {
+    const resources = extractStatementResources(query);
+    if (this.collection_name && this.collection_name !== "_default") {
+      resources.add(String(this.collection_name).toLowerCase());
     }
+    return resources;
+  }
+
+  /**
+   * True when a slow statement may create a covering index. See
+   * OPTIMIZE_ENABLED_RESOURCES for the order of precedence.
+   */
+  shouldAutoOptimize(query, query_options = {}) {
+    const requested = requestedAutoOptimize(query_options);
+    if (requested !== undefined) return requested;
+    if (typeof this.auto_optimize === "boolean") return this.auto_optimize;
+
+    const resources = this.statementResources(query);
+    if (typeof autoOptimizePolicy === "function" && resources.size > 0) {
+      let deferred = false;
+      for (const resource of resources) {
+        let verdict;
+        try {
+          verdict = autoOptimizePolicy(resource, {
+            query,
+            connection: this.connection_name,
+            collection: this.collection_name,
+          });
+        } catch (e) {
+          // A broken policy must not create indexes nobody asked for.
+          verdict = false;
+        }
+        if (verdict === true) return true;
+        if (verdict === undefined || verdict === null) deferred = true;
+      }
+      if (!deferred) return false;
+    }
+
+    const enabled = new Set([
+      ...OPTIMIZE_ENABLED_RESOURCES,
+      ...(this.enabled_resources || []),
+    ]);
+    if (enabled.has("*")) return true;
+    for (const resource of resources) {
+      if (enabled.has(resource)) return true;
+    }
+    return false;
   }
 
   setGlobalConnectionObject(collection) {
@@ -203,26 +470,9 @@ module.exports = class Database {
   }
 
   async connect(connection_name, config) {
-    let connectOptions = {
-      username: config.username,
-      password: config.password,
-    };
-    if (config.configProfile) {
-      connectOptions.configProfile = config.configProfile;
-    }
-
-    let cluster = await couchbase.connect(config.nodes, connectOptions);
-    let bucket = cluster.bucket(config.bucket);
-    let collection;
-    let scope_name = this.scope_name || config.scope || "_default";
-    let collection_name =
-      this.collection_name || config.collection || "_default";
-    let scope = bucket.scope(scope_name);
-
-    collection = bucket
-      .scope(scope_name)
-      .collection(collection_name || "_default");
-
+    const { cluster, bucket, scope, collection } = await openHandles(config);
+    // Watch the connection from here on and replace it if it wedges.
+    health.register(connection_name, config);
     return {
       connection: connection_name,
       bucket,
@@ -233,7 +483,7 @@ module.exports = class Database {
   }
 
   getUserManager(connection) {
-    return spice.database.clusters[connection].users();
+    return globalHandle("cluster", connection).users();
   }
 
   async assignUserPermission() {
@@ -413,7 +663,7 @@ module.exports = class Database {
         this.use_bucket_name ? this.connection : this.collection;
 
       if (!useLookupIn) {
-        let response = await collection.get(doc_id);
+        let response = await this.observe(collection.get(doc_id));
         return { id: doc_id, ...response.content };
       }
 
@@ -428,6 +678,7 @@ module.exports = class Database {
       });
 
       const batchResults = await Promise.allSettled(batchPromises);
+      this.recordSettled(batchResults);
 
       // Merge results from all batches
       batchResults.forEach((result, batchIndex) => {
@@ -449,12 +700,14 @@ module.exports = class Database {
 
   async insert(doc_id, document, expiry) {
     try {
-      await (this.use_bucket_name ? this.connection : this.collection).insert(
-        doc_id,
-        document,
-        {
-          expiry: expiry,
-        },
+      await this.observe(
+        (this.use_bucket_name ? this.connection : this.collection).insert(
+          doc_id,
+          document,
+          {
+            expiry: expiry,
+          },
+        ),
       );
     } catch (e) {
       console.log(e.message, e, doc_id);
@@ -463,38 +716,45 @@ module.exports = class Database {
   }
 
   async touch(doc_id, expiry = 0) {
-    await (this.use_bucket_name ? this.connection : this.collection).touch(
-      doc_id,
-      expiry,
+    await this.observe(
+      (this.use_bucket_name ? this.connection : this.collection).touch(
+        doc_id,
+        expiry,
+      ),
     );
     return await this.get(doc_id);
   }
 
   async count(doc_id, adjustment, initial_value) {
-    let res = await (
-      this.use_bucket_name ?
-        this.connection
-      : this.collection).counter(doc_id, adjustment, {
-      initial: initial_value,
-    });
+    let res = await this.observe(
+      (this.use_bucket_name ? this.connection : this.collection).counter(
+        doc_id,
+        adjustment,
+        {
+          initial: initial_value,
+        },
+      ),
+    );
     return res.value;
   }
 
   async update(doc_id, document, expiry) {
-    let res = await (
-      this.use_bucket_name ?
-        this.connection
-      : this.collection).replace(doc_id, document, {
-      expiry: expiry,
-    });
+    let res = await this.observe(
+      (this.use_bucket_name ? this.connection : this.collection).replace(
+        doc_id,
+        document,
+        {
+          expiry: expiry,
+        },
+      ),
+    );
     return res.value;
   }
 
   async delete(doc_id) {
-    let res = await (
-      this.use_bucket_name ?
-        this.connection
-      : this.collection).remove(doc_id);
+    let res = await this.observe(
+      (this.use_bucket_name ? this.connection : this.collection).remove(doc_id),
+    );
     return res.value;
   }
 
@@ -511,6 +771,7 @@ module.exports = class Database {
         // Regular get - no batching needed
         let functions = _.map(keys, (key) => collection.get(key));
         let returned_all = await Promise.allSettled(functions);
+        this.recordSettled(returned_all);
 
         let responses = _.flatten(
           _.map(returned_all, (returned_obj) => returned_obj?.value),
@@ -549,6 +810,7 @@ module.exports = class Database {
           });
 
           const batchResults = await Promise.allSettled(batchPromises);
+          this.recordSettled(batchResults);
 
           // Merge results from all batches
           batchResults.forEach((result, batchIndex) => {
@@ -947,7 +1209,9 @@ module.exports = class Database {
     // Start time
     let startTime = process.hrtime.bigint();
     const options = buildQueryOptions(query_options);
-    let response = await exec_scope.query(sanitizedQuery, options);
+    let response = await this.observe(
+      exec_scope.query(sanitizedQuery, options),
+    );
     // End time
     let endTime = process.hrtime.bigint();
     // Calculate duration in microseconds
@@ -956,6 +1220,7 @@ module.exports = class Database {
     // declared at the top of this file. Never awaited, never allowed to reject.
     if (
       durationInMilliseconds > SLOW_QUERY_MS &&
+      this.shouldAutoOptimize(sanitizedQuery, query_options) &&
       shouldOptimize(sanitizedQuery)
     ) {
       this.optimize(sanitizedQuery, exec_scope).catch(() => {});

package/src/utility.js

@@ -458,10 +458,73 @@ function indexSatisfiesCoveringDefinition(index, candidate) {
   return requiredKeys.slice(candidate.accessKeyCount).every((key) => existingFields.has(key.field));
 }
 
+/**
+ * Normalizes an exemption list into a Set of lower-case resource names.
+ * Accepts an array, a Set, or a comma-separated string (the env var form).
+ * Surrounding whitespace and backticks are ignored; empty entries are dropped.
+ * @param {string|string[]|Set<string>} value
+ * @returns {Set<string>}
+ */
+function parseResourceList(value) {
+  const names = new Set();
+  let items = [];
+  if (Array.isArray(value) || value instanceof Set) {
+    items = [...value];
+  } else if (typeof value === "string") {
+    items = value.split(",");
+  }
+  for (const item of items) {
+    if (typeof item !== "string") continue;
+    const name = item.trim().replace(/^`+|`+$/g, "").trim().toLowerCase();
+    if (name) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * Extracts the resource names a statement touches, lower-cased:
+ * - the last path segment of every FROM / JOIN keyspace, unquoted, so
+ *   `default`:`bucket`.`scope`.`users` and users both yield "users";
+ * - every `type = '...'` literal, which is how legacy bucket-mode
+ *   deployments distinguish resources that share one keyspace.
+ * Only simple identifiers are recognised; subqueries and expressions are skipped.
+ * @param {string} query
+ * @returns {Set<string>}
+ */
+function extractStatementResources(query) {
+  const names = new Set();
+  if (typeof query !== "string") return names;
+
+  const identifier = "(?:`(?:[^`]|``)+`|[A-Za-z_][\\w$-]*)";
+  const keyspacePattern = new RegExp(
+    `\\b(?:FROM|JOIN)\\s+(${identifier}(?:\\s*[.:]\\s*${identifier})*)`,
+    "gi",
+  );
+  const segmentPattern = new RegExp(identifier, "g");
+  for (const match of query.matchAll(keyspacePattern)) {
+    const segments = match[1].match(segmentPattern) || [];
+    const last = (segments[segments.length - 1] || "").trim();
+    const name = last.startsWith("`")
+      ? last.slice(1, -1).replace(/``/g, "`")
+      : last;
+    if (name) names.add(name.toLowerCase());
+  }
+
+  const typePattern = /(?:`type`|\btype)\s*=\s*'((?:[^']|'')*)'/gi;
+  for (const match of query.matchAll(typePattern)) {
+    const name = match[1].replace(/''/g, "'").trim();
+    if (name) names.add(name.toLowerCase());
+  }
+
+  return names;
+}
+
 module.exports = {
   buildCoveringIndex,
   buildCoveringIndexDefinition,
   indexSatisfiesCoveringDefinition,
+  parseResourceList,
+  extractStatementResources,
   extractWhereFields,
   extractSelectFields,
   extractGroupByFields,

package/src/utility.test.js

@@ -8,6 +8,8 @@ const {
   extractGroupByFields,
   extractOrderByFields,
   generateHash,
+  parseResourceList,
+  extractStatementResources,
 } = require("./utility");
 
 // Test utilities
@@ -1046,6 +1048,73 @@ test("field order: WHERE -> GROUP BY -> ORDER BY -> SELECT", () => {
   assert.ok(createdAtIndex < emailIndex);  // ORDER BY before SELECT
 });
 
+// ============================================
+// Tests for parseResourceList / extractStatementResources
+// ============================================
+console.log("\n--- parseResourceList tests ---");
+
+test("parses a comma-separated string, trimming, unquoting and lower-casing", () => {
+  const result = parseResourceList(" Users, `Audit_Log` ,, sessions ");
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "sessions", "users"]);
+});
+
+test("accepts arrays and Sets and ignores non-strings", () => {
+  assert.deepStrictEqual([...parseResourceList(["Users", 42, null, " logs "])].sort(), ["logs", "users"]);
+  assert.deepStrictEqual([...parseResourceList(new Set(["A", "b"]))].sort(), ["a", "b"]);
+});
+
+test("returns an empty set for undefined, empty or unsupported input", () => {
+  assert.strictEqual(parseResourceList(undefined).size, 0);
+  assert.strictEqual(parseResourceList("").size, 0);
+  assert.strictEqual(parseResourceList(", ,").size, 0);
+  assert.strictEqual(parseResourceList({ users: true }).size, 0);
+});
+
+console.log("\n--- extractStatementResources tests ---");
+
+test("extracts a bare FROM keyspace", () => {
+  assert.deepStrictEqual([...extractStatementResources("SELECT name FROM users WHERE x = 1")], ["users"]);
+});
+
+test("extracts the last segment of a qualified or quoted keyspace", () => {
+  assert.deepStrictEqual(
+    [...extractStatementResources("SELECT name FROM `default`:`saturn`.`app`.`Users` AS u")],
+    ["users"],
+  );
+  assert.deepStrictEqual(
+    [...extractStatementResources("SELECT name FROM saturn.app.logs")],
+    ["logs"],
+  );
+});
+
+test("extracts JOIN keyspaces alongside FROM", () => {
+  const result = extractStatementResources(
+    "SELECT u.name FROM users AS u JOIN `orders` AS o ON o.user_id = META(u).id",
+  );
+  assert.deepStrictEqual([...result].sort(), ["orders", "users"]);
+});
+
+test("extracts type literals used by legacy bucket mode", () => {
+  const result = extractStatementResources(
+    "SELECT actor FROM `saturn` WHERE type = 'Audit_Log' AND deleted = false",
+  );
+  assert.deepStrictEqual([...result].sort(), ["audit_log", "saturn"]);
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE `type`='x'").has("x"));
+  assert.ok(extractStatementResources("SELECT a FROM b WHERE type = 'it''s'").has("it's"));
+});
+
+test("does not treat META() arguments, subqueries or column names as keyspaces", () => {
+  const result = extractStatementResources(
+    "SELECT META(`users`).id AS id, from_date FROM (SELECT * FROM users) AS sub WHERE status = 'from'",
+  );
+  assert.deepStrictEqual([...result], ["users"]);
+});
+
+test("handles non-string input", () => {
+  assert.strictEqual(extractStatementResources(undefined).size, 0);
+  assert.strictEqual(extractStatementResources(null).size, 0);
+});
+
 // ============================================
 // Summary
 // ============================================