MongoDB Shell (mongosh)

When a user enters a command in the mongosh CLI REPL (e.g., db.coll.find({})) and presses enter, the code undergoes a multi-stage transformation and execution process involving several components:

1. Async REPL: A customized REPLServer.eval function intercepts the input to manage interrupts and error handling.
2. Mongosh Node REPL: Acts as the orchestrator, managing the Shell API abstraction and history, then forwarding input to the Shell Evaluator.
3. Shell Evaluator: Determines if the input is a special shell command (like show dbs) or JavaScript code.
   • Shell Commands: Executed immediately without further transformation.
   • JavaScript Code: Passed to the Async Rewriter.
4. Async Rewriter: Transforms synchronous-style JavaScript into asynchronous code by automatically inserting await statements for Shell API promises.
5. Final Evaluation: The rewritten code is evaluated in the Shell API context using the original REPLServer.eval function.

In a standard Node.js REPL, CTRL-C only interrupts synchronous code (like while(true) {}). Once code becomes asynchronous (e.g., using await, Promises, or timeouts), the standard interrupt handling fails to stop execution.

mongosh solves this by:

1. Wrapping Shell API functions: Every Shell API function is wrapped in a Promise.race. This race pits the actual API call against an interruptPromise. If CTRL-C is pressed, the interruptPromise rejects, causing the API call to fail immediately.
2. Force-closing connections: When a SIGINT is received, mongosh force-closes all MongoClient instances. This terminates operations currently running on the MongoDB server (requires MongoDB > 4.2).
3. Preventing error swallowing: To prevent user try-catch blocks from accidentally catching the interrupt signal and continuing execution, the async-rewriter rewrites user code to ensure that MongoshInterruptedError is immediately re-thrown and cannot be caught by standard error handlers.

To ensure asynchronous Shell API calls (like db.collection.find()) are interrupted when the user hits CTRL-C, mongosh uses a pattern where the API call is raced against an interruptor.

Conceptually, the wrapping logic looks like this:

const interruptPromise = interruptor.checkInterrupt(); // Throws if CTRL-C happened, or rejects on CTRL-C

try {
  return result = Promise.race([
    interruptPromise.promise(),   // Rejects on CTRL-C
    Collection.find(args)         // The actual Shell API call
  ]);
} catch {
  // Handle interruption
} finally {
  interruptPromise.destroy(); // Cleanup to prevent memory leaks
}

const interruptPromise = interruptor.checkInterrupt(); // will throw immediately if CTRL-C already happened
                                                       // otherwise the contained promise is rejected on CTRL-C

try {
  return result = Promise.race([
    interruptPromise.promise(),   // this is never resolved but only rejected on CTRL-C!
    Collection.find(args)         // here we call the original function
  ]);
} catch {
  ... // throw an appropriate error (see below for exception handling details)
} finally {
  interruptPromise.destroy(); // we make sure to de-register ourselves to not leak memory
}

The async-rewriter2 uses a three-step transformation process to enable implicit awaiting without a global symbol table:

1. IIFE wrapping: The input code is wrapped in an Immediately Invoked Function Expression (IIFE). This ensures that identifiers (like top-level functions) remain accessible in the outer environment while the execution logic is encapsulated.

2. Uncatchable exceptions: To support shell features like Ctrl+C, the rewriter transforms try/catch/finally blocks to use a special type of exception marked with Symbol.for('@@mongosh.uncatchable'). These exceptions are designed to bypass userland catch blocks so the shell can intercept them.

3. Async function wrapping:

   • Shorthand arrow functions are converted to statement bodies.
   • Original functions are turned into async functions, but a non-async wrapper is generated to manage execution state. This wrapper forwards synchronous results immediately and handles the transition to asynchronous execution.
   • Expressions are wrapped with checks that look for a specific Symbol property (set by the API). If the property is present, the expression is awaited; otherwise, it is returned as-is.

Note on limitations: This approach does not currently support situations where implicit async functions cannot be used, such as inside class constructors or synchronous generator functions. It also does not prevent conflicts with top-level variable names (e.g., naming a variable db).

The CLI REPL listens to several events via a message bus. These events are logged to the user's local log file in ~/.mongodb/mongosh/ in NDJSON format using pino. This is useful for telemetry, debugging, and auditing shell activity.

Available Bus Events:

• mongosh:connect: Emitted when a connection is established. Carries driverUri.
• mongosh:error: Emitted when an error is thrown. Carries an Error object.
• mongosh:rewritten-async-input: Used for debugging the async-rewriter. Carries original and rewritten strings.
• mongosh:use: Emitted when the use command is called. Carries the db name.
• mongosh:show: Emitted when a show command is used. Carries the method name.
• mongosh:it: Emitted when the it command is called.
• mongosh:api-call: Emitted when an API call is made. Carries details about the method, class, database, collection, and arguments (e.g., pipeline, query, options). Note: To keep logs clean, documents returned by calls like insert() are typically not included in the arguments.