spice-couchbase 2.0.64 → 2.0.65

package/src/index.js

@@ -4,7 +4,15 @@ let _ = require("lodash");
 let couchbase = require("couchbase");
 const { ConflictResolutionType } = require("couchbase");
 const { QueryScanConsistency } = require("couchbase");
-const { parseResourceList, extractStatementResources } = require("./utility");
+const {
+  parseResourceList,
+  extractStatementResources,
+  statementShape,
+  usesManagedIndex,
+  renderIndexKey,
+  BASE_INDEX,
+  MANAGED_INDEX_NAME,
+} = require("./utility");
 const { createHealthMonitor, openHandles } = require("./connectionHealth");
 
 if (!Promise.allSettled) {
@@ -71,6 +79,11 @@ const OPTIMIZE_ENABLED_RESOURCES = parseResourceList(
   process.env.SPICE_COUCHBASE_OPTIMIZE_RESOURCES,
 );
 let autoOptimizePolicy = null;
+// When the application installs a handler, slow statements are handed to it
+// instead of creating indexes here: it owns every index decision, with its
+// own key rules, caps and build windows. Without one, the legacy covering
+// index path below still runs, so other applications keep their behaviour.
+let slowStatementHandler = null;
 
 // One health monitor per process, shared by every copy of this module that
 // ends up loaded. See connectionHealth.js.
@@ -168,9 +181,39 @@ function buildQueryOptions(queryOptions = {}) {
     options.scanWait = numericScanWait;
   }
 
+  // Reported as clientContextID in system:completed_requests, which is how a
+  // slow statement is traced back to the route or job that ran it.
+  const clientContextId =
+    queryOptions.clientContextId ?? queryOptions.client_context_id;
+  if (clientContextId !== undefined && clientContextId !== null && clientContextId !== "") {
+    options.clientContextId = String(clientContextId).slice(0, 64);
+  }
+
   return options;
 }
 
+function wantsScanWaitFallback(query_options) {
+  return (
+    query_options &&
+    typeof query_options === "object" &&
+    (query_options.scan_wait_fallback === true ||
+      query_options.scanWaitFallback === true)
+  );
+}
+
+// The query service reports an expired scan_wait as an index scan timeout
+// (12015), which is a query error, not a connectivity timeout.
+function isScanWaitExpired(error) {
+  const code =
+    error?.cause?.first_error_code ?? error?.context?.first_error_code;
+  const message =
+    error?.cause?.first_error_message ||
+    error?.context?.first_error_message ||
+    error?.message ||
+    "";
+  return code === 12015 || /index scan timed out|scan.{0,20}timed? ?out/i.test(message);
+}
+
 module.exports = class Database {
   constructor(
     connection,
@@ -398,6 +441,38 @@ module.exports = class Database {
     return autoOptimizePolicy;
   }
 
+  /**
+   * Hands slow statements to the application instead of creating covering
+   * indexes here. `handler({ statement, shape, plan, resources, connection,
+   * bucket, scope, collection, duration_ms })` runs in the background, once
+   * per statement shape, after the resource opt-in policy has allowed it and
+   * only when the plan is not already served by a managed index. Pass null to
+   * restore the legacy behaviour.
+   */
+  static setSlowStatementHandler(handler) {
+    if (
+      handler !== null &&
+      handler !== undefined &&
+      typeof handler !== "function"
+    ) {
+      throw new TypeError("Slow statement handler must be a function or null");
+    }
+    slowStatementHandler = handler || null;
+  }
+
+  static getSlowStatementHandler() {
+    return slowStatementHandler;
+  }
+
+  /** The fallback index every collection gets in place of a primary index. */
+  static get BASE_INDEX() {
+    return BASE_INDEX;
+  }
+
+  static get MANAGED_INDEX_NAME() {
+    return MANAGED_INDEX_NAME;
+  }
+
   /**
    * Resources a statement touches, plus this instance's collection: that is
    * the keyspace `optimize()` would create the index on.
@@ -543,7 +618,19 @@ module.exports = class Database {
         if (!collection_exists) {
           await this.createCollection(this.collection_name, this.scope_name);
           await this.wait(2000);
-          await this.createPrimaryIndex(this.scope_name, this.collection_name);
+          // `primary_index: false` on the connection replaces the primary
+          // index with the base secondary index. A new collection is empty,
+          // so building it straight away costs nothing.
+          if (this.db_config?.primary_index === false) {
+            await this.createIndex({
+              ...BASE_INDEX,
+              defer_build: false,
+              collection: this.collection_name,
+              scope: this.scope_name,
+            });
+          } else {
+            await this.createPrimaryIndex(this.scope_name, this.collection_name);
+          }
         }
       }
     } catch (e) {
@@ -656,6 +743,121 @@ module.exports = class Database {
     }
   }
 
+  // Index management. Every statement here is DDL or a catalog read against a
+  // fully qualified keyspace, run at cluster level and outside `query()` so a
+  // slow build never feeds back into the slow-statement path.
+
+  async runDdl(statement, options = {}) {
+    return this.observe(this.cluster.query(statement, options));
+  }
+
+  /**
+   * Every index on a collection, from system:indexes, including the legacy
+   * catalog form of the default collection. Rows carry name, index_key,
+   * condition, state, is_primary, using.
+   */
+  async listIndexes({
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const response = await this.runDdl(
+      `SELECT RAW i FROM system:indexes AS i
+       WHERE i.namespace_id = 'default'
+         AND ((i.bucket_id = $bucket AND i.scope_id = $scope AND i.keyspace_id = $collection)
+           OR ($scope = '_default' AND $collection = '_default'
+             AND i.bucket_id IS MISSING AND i.scope_id IS MISSING AND i.keyspace_id = $bucket))`,
+      {
+        parameters: {
+          bucket: this.db_config.bucket,
+          scope,
+          collection,
+        },
+      },
+    );
+    // A failed or partial inventory is not evidence that no index exists.
+    if (!Array.isArray(response?.rows) || response?.meta?.warnings?.length) {
+      throw new Error(`Cannot read the index inventory for ${scope}.${collection}`);
+    }
+    return response.rows;
+  }
+
+  /**
+   * `CREATE INDEX IF NOT EXISTS`. Deferred by default so several indexes on
+   * one collection can be built together with `buildIndexes`, in one pass
+   * over the data.
+   */
+  async createIndex({
+    name,
+    keys,
+    where,
+    defer_build = true,
+    num_replica,
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    if (!name || !Array.isArray(keys) || keys.length === 0) {
+      throw new TypeError("createIndex needs a name and at least one key");
+    }
+    const withClause = { defer_build: Boolean(defer_build) };
+    if (Number.isInteger(num_replica) && num_replica >= 0) {
+      withClause.num_replica = num_replica;
+    }
+    const statement =
+      `CREATE INDEX IF NOT EXISTS ${this.quoteIdentifier(name)} ` +
+      `ON ${this.collectionPath(scope, collection)}(${keys.map(renderIndexKey).join(", ")})` +
+      (where ? ` WHERE ${where}` : "") +
+      ` WITH ${JSON.stringify(withClause)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  /** Builds deferred indexes on one collection together. */
+  async buildIndexes(names, {
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const list = [...new Set(names || [])];
+    if (list.length === 0) return null;
+    const statement =
+      `BUILD INDEX ON ${this.collectionPath(scope, collection)}` +
+      `(${list.map((name) => this.quoteIdentifier(name)).join(", ")})`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  async dropIndex(name, {
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const statement =
+      `DROP INDEX IF EXISTS ${this.quoteIdentifier(name)} ON ${this.collectionPath(scope, collection)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  async dropPrimaryIndex({
+    collection = this.collection_name,
+    scope = this.scope_name,
+  } = {}) {
+    const statement = `DROP PRIMARY INDEX IF EXISTS ON ${this.collectionPath(scope, collection)}`;
+    await this.runDdl(statement);
+    return statement;
+  }
+
+  /** The plan for a statement, resolved in this instance's scope by default. */
+  async explain(statement, query_scope = this.use_bucket_name ? "cluster" : "scope") {
+    const exec_scope = query_scope === "cluster" ? this.cluster : this.scope;
+    const response = await this.observe(exec_scope.query(`EXPLAIN ${statement}`));
+    return response?.rows?.[0];
+  }
+
+  /** Couchbase's own index advice for a statement (the ADVISE statement). */
+  async advise(statement, query_scope = this.use_bucket_name ? "cluster" : "scope") {
+    const exec_scope = query_scope === "cluster" ? this.cluster : this.scope;
+    const response = await this.observe(exec_scope.query(`ADVISE ${statement}`));
+    return response?.rows?.[0];
+  }
+
   async get(doc_id, { columns = [] } = {}) {
     try {
       const useLookupIn = columns.length > 0;
@@ -1209,9 +1411,31 @@ module.exports = class Database {
     // Start time
     let startTime = process.hrtime.bigint();
     const options = buildQueryOptions(query_options);
-    let response = await this.observe(
-      exec_scope.query(sanitizedQuery, options),
-    );
+    let response;
+    try {
+      response = await this.observe(exec_scope.query(sanitizedQuery, options));
+    } catch (error) {
+      // `scan_wait_fallback`: a request_plus read that could not get a fresh
+      // index snapshot within `scan_wait` runs once more without waiting, for
+      // callers that prefer a slightly stale answer to an error.
+      if (
+        !wantsScanWaitFallback(query_options) ||
+        options.scanConsistency !== QueryScanConsistency.RequestPlus ||
+        options.scanWait === undefined ||
+        !isScanWaitExpired(error)
+      ) {
+        throw error;
+      }
+      console.warn(
+        `[spice-couchbase] index not current within ${options.scanWait}ms; reading without waiting`,
+      );
+      response = await this.observe(
+        exec_scope.query(sanitizedQuery, {
+          ..._.omit(options, ["scanWait"]),
+          scanConsistency: QueryScanConsistency.NotBounded,
+        }),
+      );
+    }
     // End time
     let endTime = process.hrtime.bigint();
     // Calculate duration in microseconds
@@ -1220,11 +1444,49 @@ 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.shouldAutoOptimize(sanitizedQuery, query_options)
     ) {
-      this.optimize(sanitizedQuery, exec_scope).catch(() => {});
+      if (slowStatementHandler) {
+        if (shouldOptimize(statementShape(sanitizedQuery))) {
+          this.reportSlowStatement(
+            sanitizedQuery,
+            exec_scope,
+            Number(durationInMilliseconds),
+          ).catch(() => {});
+        }
+      } else if (shouldOptimize(sanitizedQuery)) {
+        this.optimize(sanitizedQuery, exec_scope).catch(() => {});
+      }
     }
     return response;
   }
+
+  /**
+   * Hands a slow statement to the application's handler, unless its plan is
+   * already served by a managed index. Runs under the same in-flight and
+   * cooldown guard rails as `optimize()`.
+   */
+  async reportSlowStatement(query, exec_scope, duration_ms) {
+    optimizeState.inFlight += 1;
+    try {
+      const explainResponse = await exec_scope.query(`EXPLAIN ${query}`);
+      const plan = explainResponse?.rows?.[0];
+      if (usesManagedIndex(plan)) return;
+      await slowStatementHandler({
+        statement: query,
+        shape: statementShape(query),
+        plan,
+        resources: [...this.statementResources(query)],
+        connection: this.connection_name,
+        bucket: this.bucket,
+        scope: this.scope_name,
+        collection: this.collection_name,
+        duration_ms,
+      });
+    } catch (e) {
+      optimizeState.cooldownUntil = Date.now() + OPTIMIZE_FAILURE_COOLDOWN_MS;
+    } finally {
+      optimizeState.inFlight -= 1;
+    }
+  }
 };

package/src/utility.js

@@ -519,7 +519,85 @@ function extractStatementResources(query) {
   return names;
 }
 
+// Names the application's index manager owns. A statement whose plan already
+// scans one of these is being served by a deliberate index, so the slow-query
+// path leaves it alone. `ix_base` is the per-collection fallback and does not
+// count: a statement that only finds the fallback is exactly what to report.
+const MANAGED_INDEX_NAME = /^ix_(sort|eq|agg|core|obs)_[0-9a-f]{6}_[0-9a-f]{4}$/;
+
+// Replaces the primary index on every collection: usable by any statement
+// because the leading key includes MISSING, and ordered for the default list
+// sort (`created_at DESC`).
+const BASE_INDEX = Object.freeze({
+  name: "ix_base",
+  keys: Object.freeze([
+    Object.freeze({ expr: "`created_at`", desc: true, include_missing: true }),
+    Object.freeze({ expr: "`deleted`" }),
+  ]),
+});
+
+/**
+ * The statement with its literals replaced by `?`, so one query shape is
+ * examined once however many values it runs with. IN lists collapse to `[?]`.
+ * @param {string} query
+ * @returns {string}
+ */
+function statementShape(query) {
+  return String(query ?? "")
+    .replace(/'(?:[^'\\]|\\.|'')*'/g, "?")
+    .replace(/"(?:[^"\\]|\\.)*"/g, "?")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "?")
+    .replace(/\[\s*\?(?:\s*,\s*\?)*\s*\]/g, "[?]")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Names of the indexes an EXPLAIN plan scans.
+ * @param {object} plan
+ * @returns {string[]}
+ */
+function planIndexNames(plan) {
+  const names = new Set();
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (/Scan/.test(String(node["#operator"] || "")) && typeof node.index === "string") {
+      names.add(node.index);
+    }
+    Object.values(node).forEach(visit);
+  };
+  visit(plan);
+  return [...names];
+}
+
+function usesManagedIndex(plan) {
+  return planIndexNames(plan).some((name) => MANAGED_INDEX_NAME.test(name));
+}
+
+/**
+ * Renders one index key. Accepts a ready string or `{ expr, desc, include_missing }`.
+ * @param {string|{expr: string, desc?: boolean, include_missing?: boolean}} key
+ * @returns {string}
+ */
+function renderIndexKey(key) {
+  if (typeof key === "string") return key;
+  if (!key || typeof key.expr !== "string" || !key.expr.trim()) {
+    throw new TypeError("An index key needs an expression");
+  }
+  return `${key.expr}${key.desc ? " DESC" : ""}${key.include_missing ? " INCLUDE MISSING" : ""}`;
+}
+
 module.exports = {
+  MANAGED_INDEX_NAME,
+  BASE_INDEX,
+  statementShape,
+  planIndexNames,
+  usesManagedIndex,
+  renderIndexKey,
   buildCoveringIndex,
   buildCoveringIndexDefinition,
   indexSatisfiesCoveringDefinition,