@lossless.org/client 1.20.0 → 1.20.2

package/ts/nosqldb/classes.collection.ts

@@ -1842,14 +1842,16 @@ const indexEquivalenceSignature = (indexArg: {
   });
 
 /**
- * MongoDB reports an index collision without naming the index already in the
- * namespace, yet the remedy depends on it: adopt that name in the declaration
- * or drop the index. Only the collision path pays for the extra catalog read.
+ * MongoDB reports an index collision without naming either index, yet the
+ * remedy depends on them: adopt the existing name in the declaration or drop
+ * the index. The declarations are checked in order against the catalog and
+ * against one another, since one command creates them all. Only the collision
+ * path pays for the extra catalog read.
  */
 const describeIndexCollision = async (
   targetCollectionArg: plugins.mongodb.Collection,
   collectionNameArg: string,
-  expectedArg: INormalizedCollectionModelSchema['indexes'][number],
+  expectedIndexesArg: INormalizedCollectionModelSchema['indexes'],
   errorArg: unknown,
 ): Promise<unknown> => {
   if (!isMongoIndexConflictError(errorArg)) {
@@ -1863,31 +1865,49 @@ const describeIndexCollision = async (
     // own error stays the best evidence the caller can act on.
     return errorArg;
   }
-  const equivalentIndex = actualIndexes.find(
-    (actualArg) =>
-      actualArg.name !== expectedArg.name &&
-      stableValue(Object.entries(actualArg.key || {})) ===
-        stableValue(expectedArg.key) &&
-      indexEquivalenceSignature(actualArg) ===
-        indexEquivalenceSignature(expectedArg.options),
-  );
-  if (equivalentIndex) {
-    return new SmartdataPersistenceError(
-      'invalid_configuration',
-      `Collection "${collectionNameArg}" already carries the equivalent index ` +
-        `"${equivalentIndex.name}", so declared index "${expectedArg.name}" ` +
-        'cannot be created. Declare the existing name — an identity declares ' +
-        'it with @unI({ indexName }) — or drop the existing index.',
-      { cause: errorArg },
-    );
-  }
-  if (actualIndexes.some((actualArg) => actualArg.name === expectedArg.name)) {
-    return new SmartdataPersistenceError(
-      'invalid_configuration',
-      `Collection "${collectionNameArg}" already carries an index named ` +
-        `"${expectedArg.name}" with a different key or options.`,
-      { cause: errorArg },
+  for (const [position, expected] of expectedIndexesArg.entries()) {
+    const equivalentIndex = actualIndexes.find(
+      (actualArg) =>
+        actualArg.name !== expected.name &&
+        stableValue(Object.entries(actualArg.key || {})) ===
+          stableValue(expected.key) &&
+        indexEquivalenceSignature(actualArg) ===
+          indexEquivalenceSignature(expected.options),
     );
+    if (equivalentIndex) {
+      return new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Collection "${collectionNameArg}" already carries the equivalent index ` +
+          `"${equivalentIndex.name}", so declared index "${expected.name}" ` +
+          'cannot be created. Declare the existing name — an identity declares ' +
+          'it with @unI({ indexName }) — or drop the existing index.',
+        { cause: errorArg },
+      );
+    }
+    if (actualIndexes.some((actualArg) => actualArg.name === expected.name)) {
+      return new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Collection "${collectionNameArg}" already carries an index named ` +
+          `"${expected.name}" with a different key or options.`,
+        { cause: errorArg },
+      );
+    }
+    const equivalentDeclaration = expectedIndexesArg
+      .slice(0, position)
+      .find(
+        (earlierArg) =>
+          stableValue(earlierArg.key) === stableValue(expected.key) &&
+          indexEquivalenceSignature(earlierArg.options) ===
+            indexEquivalenceSignature(expected.options),
+      );
+    if (equivalentDeclaration) {
+      return new SmartdataPersistenceError(
+        'invalid_configuration',
+        `Collection "${collectionNameArg}" declares the equivalent indexes ` +
+          `"${equivalentDeclaration.name}" and "${expected.name}"; declare one name.`,
+        { cause: errorArg },
+      );
+    }
   }
   // An index over the same key that is not interchangeable with the
   // declaration cannot be adopted by name, and MongoDB's own error already
@@ -2133,20 +2153,22 @@ export class SmartdataCollection<T> {
     if (!modelSchema) {
       return;
     }
-    for (const index of modelSchema.indexes) {
+    // One command for every declared index: the server builds the missing
+    // ones together, or none of them when one collides.
+    if (modelSchema.indexes.length > 0) {
       try {
-        await targetCollection.createIndex(
-          Object.fromEntries(index.key) as plugins.mongodb.IndexSpecification,
-          {
+        await targetCollection.createIndexes(
+          modelSchema.indexes.map((index) => ({
             ...index.options,
+            key: Object.fromEntries(index.key) as plugins.mongodb.IndexDescription['key'],
             name: index.name,
-          },
+          })),
         );
       } catch (errorArg) {
         throw await describeIndexCollision(
           targetCollection,
           this.collectionName,
-          index,
+          modelSchema.indexes,
           errorArg,
         );
       }

package/ts/nosqldb/classes.db.ts

@@ -40,6 +40,7 @@ export type {
 } from './classes.writeobserver.js';
 
 import { logger } from './logging.js';
+import { buildSmartdataConnectionUrl, redactSmartdataConnectionError } from './connectionstring.js';
 import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
 import {
   composeSmartdataCapabilities,
@@ -258,28 +259,11 @@ export class SmartdataDb {
     try { budget?.check(); } catch (errorArg) { budget?.close(); throw errorArg; }
     this.beginLifecycleOperation('init');
     this.transitionLifecycle('connecting');
+    // Read once, so a failure is redacted with the credentials this attempt connected with.
+    const descriptor = this.smartdataOptions;
     let candidateClient: plugins.mongodb.MongoClient | undefined;
     try {
       try {
-        // Safely encode credentials to handle special characters
-        const encodedUser = this.smartdataOptions.mongoDbUser
-          ? encodeURIComponent(this.smartdataOptions.mongoDbUser)
-          : '';
-        const encodedPass = this.smartdataOptions.mongoDbPass
-          ? encodeURIComponent(this.smartdataOptions.mongoDbPass)
-          : '';
-
-        const finalConnectionUrl = this.smartdataOptions.mongoDbUrl
-          .replace('<USERNAME>', encodedUser)
-          .replace('<username>', encodedUser)
-          .replace('<USER>', encodedUser)
-          .replace('<user>', encodedUser)
-          .replace('<PASSWORD>', encodedPass)
-          .replace('<password>', encodedPass)
-          .replace('<DBNAME>', this.smartdataOptions.mongoDbName || '')
-          .replace('<dbname>', this.smartdataOptions.mongoDbName || '');
-
-        const descriptor = this.smartdataOptions;
         const clientOptions: plugins.mongodb.MongoClientOptions = {
           maxPoolSize: descriptor.maxPoolSize ?? 100,
           maxIdleTimeMS: descriptor.maxIdleTimeMS ?? 300000,
@@ -290,7 +274,8 @@ export class SmartdataDb {
           retryWrites: true,
         };
 
-        candidateClient = new plugins.mongodb.MongoClient(finalConnectionUrl, clientOptions);
+        candidateClient = new plugins.mongodb.MongoClient(
+          buildSmartdataConnectionUrl(descriptor), clientOptions);
         this.pendingClient = candidateClient;
         const connectingClient = candidateClient;
         let cancellationCleanup: Promise<void> | undefined;
@@ -347,9 +332,13 @@ export class SmartdataDb {
             ? 'SmartData connection setup and cleanup failed; close must be retried.'
             : 'SmartData connection setup failed or was cancelled.');
         }
-        if (cleanupError) throw new AggregateError([error, cleanupError],
+        const setupError = new SmartdataPersistenceError('unsupported_operation',
+          'SmartData connection setup failed.',
+          { cause: redactSmartdataConnectionError(error, descriptor) });
+        if (cleanupError) throw new AggregateError(
+          [setupError, redactSmartdataConnectionError(cleanupError, descriptor)],
           'SmartData connection setup and cleanup failed; close must be retried.');
-        throw error;
+        throw setupError;
       }
     } finally {
       this.endLifecycleOperation('init');

package/ts/nosqldb/connectionstring.ts

@@ -0,0 +1,243 @@
+import * as plugins from './plugins.js';
+import type { ISmartdataDbOptions } from './classes.db.js';
+
+/** The options that locate and authenticate a database: everything a connection string is built from. */
+export type TSmartdataConnectionStringOptions = Pick<
+  ISmartdataDbOptions,
+  'mongoDbUrl' | 'mongoDbName' | 'mongoDbUser' | 'mongoDbPass'
+>;
+
+const redactionMarker = '<redacted>';
+
+/**
+ * The URL the driver connects with: `mongoDbUrl` with its first `<USERNAME>`/`<USER>`,
+ * `<PASSWORD>` and `<DBNAME>` placeholder of each case replaced by the URL-encoded
+ * user, password and the database name.
+ */
+export const buildSmartdataConnectionUrl = (optionsArg: TSmartdataConnectionStringOptions): string => {
+  const encodedUser = optionsArg.mongoDbUser ? encodeURIComponent(optionsArg.mongoDbUser) : '';
+  const encodedPass = optionsArg.mongoDbPass ? encodeURIComponent(optionsArg.mongoDbPass) : '';
+  return optionsArg.mongoDbUrl
+    .replace('<USERNAME>', encodedUser)
+    .replace('<username>', encodedUser)
+    .replace('<USER>', encodedUser)
+    .replace('<user>', encodedUser)
+    .replace('<PASSWORD>', encodedPass)
+    .replace('<password>', encodedPass)
+    .replace('<DBNAME>', optionsArg.mongoDbName || '')
+    .replace('<dbname>', optionsArg.mongoDbName || '');
+};
+
+/** Replaces every credential in a text an error carries. */
+type TRedact = (textArg: string) => string;
+
+/**
+ * The URI options whose value is a secret, by the driver's option table
+ * (`mongodb/src/connection_string.ts` `OPTIONS`): the `auth` credentials, the
+ * `authMechanismProperties` (for example `AWS_SESSION_TOKEN`), the SOCKS5 proxy
+ * login, the key file password, and the TLS key material the driver passes through.
+ * Lower-cased, because the driver reads option names case-insensitively.
+ */
+const secretUriOptionNames = new Set(
+  [
+    'auth',
+    'authMechanismProperties',
+    'proxyUsername',
+    'proxyPassword',
+    'tlsCertificateKeyFilePassword',
+    'key',
+    'passphrase',
+    'pfx',
+  ].map((nameArg) => nameArg.toLowerCase()),
+);
+
+/** Its value is a `KEY:value,KEY:value` list, and the driver quotes single values of it. */
+const mechanismPropertiesOptionName = 'authmechanismproperties';
+
+/**
+ * The `authMechanismProperties` entries whose value is a secret, by the driver's
+ * `AuthMechanismProperties` (`mongodb/src/cmap/auth/mongo_credentials.ts`).
+ */
+const secretMechanismPropertyNames = new Set(['AWS_SESSION_TOKEN']);
+
+/** A credential as written, URL-encoded, URL-decoded and query-decoded: a driver message may quote any of them. */
+const spellingsOf = (credentialArg: string): string[] => [
+  credentialArg,
+  ...[
+    encodeURIComponent,
+    decodeURIComponent,
+    (textArg: string) => decodeURIComponent(textArg.replaceAll('+', ' ')),
+  ].flatMap((transformArg) => {
+    try {
+      return [transformArg(credentialArg)];
+    } catch {
+      // A spelling the credential cannot be transformed into cannot be quoted either.
+      return [];
+    }
+  }),
+];
+
+/**
+ * The userinfo of a connection string, as a whole and as its user and password halves.
+ * A string the driver refuses is malformed by definition, so it is read generously:
+ * everything between `://` and the last `@`.
+ */
+const userinfoCredentialsOf = (urlArg: string): string[] => {
+  const userinfo = /^[^:/?#]*:\/\/(.*)@/s.exec(urlArg)?.[1];
+  if (userinfo === undefined) return [];
+  const separator = userinfo.indexOf(':');
+  return separator < 0
+    ? [userinfo]
+    : [userinfo, userinfo.slice(0, separator), userinfo.slice(separator + 1)];
+};
+
+interface IUriOption {
+  name: string;
+  value: string;
+}
+
+/**
+ * The `name=value` pairs of a connection string's query, read generously: a pair
+ * starts after any `?`, `&` or `;`, and its value runs to the next `&`, as the driver
+ * splits, and also to the next `;`, the legacy separator, so both readings are covered.
+ */
+const uriOptionsOf = (urlArg: string): IUriOption[] =>
+  [...urlArg.matchAll(/(?<=[?&;])([^?&;=]*)=(?=([^&]*))/g)].flatMap(([, name, value]) =>
+    [value, value.split(';')[0]].map((valueArg) => ({ name, value: valueArg })),
+  );
+
+/** The secret entry values in every spelling of an `authMechanismProperties` value, split as the driver splits it. */
+const secretMechanismPropertyValuesOf = (valueArg: string): string[] =>
+  spellingsOf(valueArg).flatMap((spellingArg) =>
+    spellingArg.split(',').flatMap((entryArg) => {
+      const separator = entryArg.indexOf(':');
+      return separator >= 0 && secretMechanismPropertyNames.has(entryArg.slice(0, separator).toUpperCase())
+        ? [entryArg.slice(separator + 1)]
+        : [];
+    }),
+  );
+
+/** The values of a connection string's secret-bearing URI options, under any spelling of their name. */
+const uriOptionCredentialsOf = (urlArg: string): string[] =>
+  uriOptionsOf(urlArg).flatMap(({ name, value }) => {
+    const names = spellingsOf(name).map((spellingArg) => spellingArg.toLowerCase());
+    if (!names.some((nameArg) => secretUriOptionNames.has(nameArg))) return [];
+    return names.includes(mechanismPropertiesOptionName) ? [value, ...secretMechanismPropertyValuesOf(value)] : [value];
+  });
+
+/**
+ * Every credential spelling the options carry, in the connection string as given and as
+ * built, longest first so the longest credential starting at a position is the one found.
+ */
+const connectionCredentialsOf = (optionsArg: TSmartdataConnectionStringOptions): string[] => {
+  const credentials = [
+    ...[optionsArg.mongoDbUrl, buildSmartdataConnectionUrl(optionsArg)].flatMap((urlArg) => [
+      ...userinfoCredentialsOf(urlArg),
+      ...uriOptionCredentialsOf(urlArg),
+    ]),
+    optionsArg.mongoDbUser,
+    optionsArg.mongoDbPass,
+  ].filter((credentialArg): credentialArg is string => Boolean(credentialArg));
+  return [...new Set(credentials.flatMap(spellingsOf))]
+    .filter((spellingArg) => spellingArg.length > 0)
+    .sort((leftArg, rightArg) => rightArg.length - leftArg.length);
+};
+
+// `RegExp.escape` is ES2025, beyond the ES2024 target.
+const escapeRegExp = (textArg: string): string => textArg.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+
+interface ISpan {
+  start: number;
+  end: number;
+}
+
+/**
+ * Where credentials occur in a text, overlapping occurrences merged into one span.
+ * The pattern only looks ahead, so it reports every start, overlapping ones included.
+ */
+const credentialSpansIn = (textArg: string, occurrenceArg: RegExp): ISpan[] => {
+  const spans: ISpan[] = [];
+  for (const { index, 1: credential } of textArg.matchAll(occurrenceArg)) {
+    const end = index + credential.length;
+    const previous = spans.at(-1);
+    if (previous !== undefined && index < previous.end) previous.end = Math.max(previous.end, end);
+    else spans.push({ start: index, end });
+  }
+  return spans;
+};
+
+const withSpansRedacted = (textArg: string, spansArg: readonly ISpan[]): string => {
+  let redacted = '';
+  let copiedUntil = 0;
+  for (const { start, end } of spansArg) {
+    redacted += textArg.slice(copiedUntil, start) + redactionMarker;
+    copiedUntil = end;
+  }
+  return redacted + textArg.slice(copiedUntil);
+};
+
+/**
+ * Redacts in one pass over the original text, so no credential is matched inside
+ * a marker another credential left and overlapping credentials leave no fragment.
+ */
+const redactorFor = (credentialsArg: readonly string[]): TRedact => {
+  if (credentialsArg.length === 0) return (textArg) => textArg;
+  const occurrence = new RegExp(`(?=(${credentialsArg.map(escapeRegExp).join('|')}))`, 'g');
+  return (textArg) => withSpansRedacted(textArg, credentialSpansIn(textArg, occurrence));
+};
+
+/** The fields a caller branches on: the driver's or Node's `code`, the server's `codeName`, the driver's error labels. */
+interface IPreservedErrorFields {
+  code?: number | string;
+  codeName?: string;
+  errorLabels?: string[];
+}
+
+/** Only these named fields: any other field, such as Node's `ERR_INVALID_URL` `input`, may hold the connection string. */
+const preservedFieldsOf = (errorArg: Error, redactArg: TRedact): IPreservedErrorFields => {
+  const fields: IPreservedErrorFields = {};
+  const code = 'code' in errorArg ? errorArg.code : undefined;
+  if (typeof code === 'number') fields.code = code;
+  if (typeof code === 'string') fields.code = redactArg(code);
+  const codeName = 'codeName' in errorArg ? errorArg.codeName : undefined;
+  if (typeof codeName === 'string') fields.codeName = redactArg(codeName);
+  if (errorArg instanceof plugins.mongodb.MongoError) fields.errorLabels = errorArg.errorLabels.map(redactArg);
+  return fields;
+};
+
+/**
+ * A copy of a thrown value that keeps its error name, its detail, its stack frames,
+ * its preserved fields, its cause chain and its aggregated errors, with every
+ * credential replaced. Only an error that is its own ancestor is left out, so a
+ * cyclic chain still ends.
+ */
+const copyRedacted = (
+  thrownArg: unknown,
+  redactArg: TRedact,
+  ancestorsArg: Set<Error>,
+): Error => {
+  if (!(thrownArg instanceof Error)) return new Error(redactArg(String(thrownArg)));
+  ancestorsArg.add(thrownArg);
+  const copyInner = (innerArg: unknown): Error[] =>
+    innerArg instanceof Error && ancestorsArg.has(innerArg) ? [] : [copyRedacted(innerArg, redactArg, ancestorsArg)];
+  const [cause] = thrownArg.cause === undefined ? [] : copyInner(thrownArg.cause);
+  const options = cause === undefined ? undefined : { cause };
+  const message = redactArg(thrownArg.message);
+  const copy = thrownArg instanceof AggregateError
+    ? new AggregateError(thrownArg.errors.flatMap((innerArg: unknown) => copyInner(innerArg)), message, options)
+    : new Error(message, options);
+  ancestorsArg.delete(thrownArg);
+  copy.name = redactArg(thrownArg.name);
+  if (thrownArg.stack !== undefined) copy.stack = redactArg(thrownArg.stack);
+  return Object.assign(copy, preservedFieldsOf(thrownArg, redactArg));
+};
+
+/**
+ * What a connection failure may show: the driver's error, copied with every
+ * credential of the options replaced by `<redacted>`. The original is never
+ * attached, because printing an error prints its whole cause chain.
+ */
+export const redactSmartdataConnectionError = (
+  thrownArg: unknown,
+  optionsArg: TSmartdataConnectionStringOptions,
+): Error => copyRedacted(thrownArg, redactorFor(connectionCredentialsOf(optionsArg)), new Set());