feat(NODE-4964): support range indexes

[baileympearson]

This PR adds range index support in explicit encryption.

Changes included

• ClientEncryption.encrypt() logic was refactored to a private helper to be shared between encrypt() and encryptExpression()
• A new option, expressionMode, is passed down from _encrypt() into the bindings. This toggles whether or not we are encrypting an expression or a regular bson value.
• maybeCallback was copied into the bindings
• documentation was generated

JIRA LINK
https://jira.mongodb.org/browse/NODE-4964

[baileympearson]

I recommend hiding whitespace changes for this diff

[addaleax]

Note that this will make exceptions from the callback result in an unhandled rejection rather than an uncaught exception; that’s a visible behavioral change. You may want to do something like this instead:

Suggested change

	result => callback(undefined, result),
	error => callback(error)
	result => process.nextTick(callback, undefined, result),
	error => process.nextTick(callback, error)

[baileympearson]

Neal and I looked at this for a while and, while we believe you're right, we actually couldn't reproduce the issue.

async function wait() {
  await setTimeout(1000);
}
maybeCallback(() => wait(), () => { throw new Error("crashed process") });

Doesn't result in an UnhandledPromiseRejection

[addaleax]

Are you sure? Running this code (as node test.js with Node.js 16 through 19 at least) results in the unhandled rejection handler being called:

function maybeCallback(promiseFn, callback) {
  const promise = promiseFn();
  if (callback == null) {
    return promise;
  }

  promise.then(
    result => callback(undefined, result),
    error => callback(error)
  );
  return;
}

async function wait() {
  await setTimeout(1000);
}

process.on('unhandledRejection', (...args) => console.log('unhandledRejection', args));

maybeCallback(() => wait(), () => { throw new Error("crashed process") });

[nbbeeken]

ah, we were looking for the unhandledRejection console log message, ty! We should make this improvement here, we'll want to file a follow up to replicate it elsewhere we've wrapped callbacks

[baileympearson]

Yup, you're right. For some reason, the unhandled promise isn't being printed as an unhandled promise (we should have listened for unhandled promises).

We filed a follow up ticket for the driver and legacy driver: https://jira.mongodb.org/browse/NODE-4996

[addaleax]

The default mode for unhandled rejections was changed to throwing in Node.js 15, which is why I think you weren’t seeing this printed as a warning: https://github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V15.md#throw-on-unhandled-rejections---33021

[baileympearson]

We compared it with just rejecting a promise. It's interesting because there is a difference between the output when we just reject the promise and when we crash the process in maybe callback.

Maybe the error thrown inside the maybeCallback hits a different codepath than the promise rejection here. Maybe I'll try running NodeJS source and stepping through with a debugger 🤔.

But regardless, they're both unhandled promise rejections (and you can test this by adding back the unhandled rejection listener).

const { setTimeout } = require('timers/promises');

function maybeCallback(promiseFn, callback) {
  const promise = promiseFn();
  if (callback == null) {
    return promise;
  }

  promise.then(
    result => callback(undefined, result),
    error => callback(error)
  );
  return;
}


setTimeout(1000).then(() => console.log('program continued'));

maybeCallback(() => setTimeout(200), () => { throw new Error("crashed process") });

// (function rejects() {
	// return Promise.reject();
// })()	

[baileympearson]

I linted our d.ts file, which might make the diff hard to read. It's in its own commit, so the changes to that file can either be viewed in other commits or I can revert that commit.