process: cleanup and document the bootstrap process in bootstrap/node.js

lib/internal/bootstrap/cache.js

@@ -18,10 +18,9 @@ const cannotBeRequired = [
   'internal/v8_prof_polyfill',
   'internal/v8_prof_processor',
 
-  'internal/per_context',
-
   'internal/test/binding',
 
+  'internal/bootstrap/context',
   'internal/bootstrap/primordials',
   'internal/bootstrap/loaders',
   'internal/bootstrap/node'

lib/internal/bootstrap/node.js

@@ -1,25 +1,46 @@
 // Hello, and welcome to hacking node.js!
 //
-// This file is invoked by node::LoadEnvironment in src/node.cc, and is
-// responsible for bootstrapping the node.js core. As special caution is given
-// to the performance of the startup process, many dependencies are invoked
-// lazily.
+// This file is invoked by `node::RunBootstrapping()` in `src/node.cc`, and is
+// responsible for setting up node.js core before executing main scripts
+// under `lib/internal/main/`.
+// This file is currently run to bootstrap both the main thread and the worker
+// threads. Some setups are conditional, controlled with isMainThread and
+// ownsProcessState.
+// This file is expected not to perform any asynchronous operations itself
+// when being executed - those should be done in either
+// `lib/internal/bootstrap/pre_execution.js` or in main scripts. The majority
+// of the code here focus on setting up the global proxy and the process
+// object in a synchronous manner.
+// As special caution is given to the performance of the startup process,
+// many dependencies are invoked lazily.
 //
-// Before this file is run, lib/internal/bootstrap/loaders.js gets run first
-// to bootstrap the internal binding and module loaders, including
-// process.binding(), process._linkedBinding(), internalBinding() and
-// NativeModule. And then { internalBinding, NativeModule } will be passed
-// into this bootstrapper to bootstrap Node.js core.
+// Scripts run before this file:
+// - `lib/internal/bootstrap/context.js`: to setup the v8::Context with
+//   Node.js-specific tweaks - this is also done in vm contexts.
+// - `lib/internal/bootstrap/primordials.js`: to save copies of JavaScript
+//   builtins that won't be affected by user land monkey-patching for internal
+//   modules to use.
+// - `lib/internal/bootstrap/loaders.js`: to setup internal binding and
+//   module loaders, including `process.binding()`, `process._linkedBinding()`,
+//   `internalBinding()` and `NativeModule`.
+//
+// After this file is run, one of the main scripts under `lib/internal/main/`
+// will be selected by C++ to start the actual execution. The main scripts may
+// run additional setups exported by `lib/internal/bootstrap/pre_execution.js`,
+// depending on the execution mode.
+
 'use strict';
 
 // This file is compiled as if it's wrapped in a function with arguments
-// passed by node::LoadEnvironment()
+// passed by node::RunBootstrapping()
 /* global process, loaderExports, isMainThread, ownsProcessState */
+/* global primordials */
 
 const { internalBinding, NativeModule } = loaderExports;
-
+const { Object, Symbol } = primordials;
 const { getOptionValue } = NativeModule.require('internal/options');
 const config = internalBinding('config');
+const { deprecate } = NativeModule.require('internal/util');
 
 setupTraceCategoryState();
 
@@ -43,7 +64,11 @@ setupProcessObject();
     hasUncaughtExceptionCaptureCallback;
 }
 
-setupGlobalVariables();
+setupGlobalProxy();
+setupBuffer();
+
+process.domain = null;
+process._exiting = false;
 
 // Bootstrappers for all threads, including worker threads and main thread
 const perThreadSetup = NativeModule.require('internal/process/per_thread');
@@ -222,7 +247,6 @@ Object.defineProperty(process, 'allowedNodeEnvironmentFlags', {
   configurable: true
 });
 
-const { deprecate } = NativeModule.require('internal/util');
 // process.assert
 process.assert = deprecate(
   perThreadSetup.assert,
@@ -337,6 +361,13 @@ function setupProcessObject() {
   const origProcProto = Object.getPrototypeOf(process);
   Object.setPrototypeOf(origProcProto, EventEmitter.prototype);
   EventEmitter.call(process);
+  // Make process globally available to users by putting it on the global proxy
+  Object.defineProperty(global, 'process', {
+    value: process,
+    enumerable: false,
+    writable: true,
+    configurable: true
+  });
 }
 
 function setupProcessStdio(getStdout, getStdin, getStderr) {
@@ -364,29 +395,22 @@ function setupProcessStdio(getStdout, getStdin, getStderr) {
   };
 }
 
-function setupGlobalVariables() {
+function setupGlobalProxy() {
   Object.defineProperty(global, Symbol.toStringTag, {
     value: 'global',
     writable: false,
     enumerable: false,
     configurable: true
   });
-  Object.defineProperty(global, 'process', {
-    value: process,
-    enumerable: false,
-    writable: true,
-    configurable: true
-  });
-  const util = NativeModule.require('util');
 
   function makeGetter(name) {
-    return util.deprecate(function() {
+    return deprecate(function() {
       return this;
     }, `'${name}' is deprecated, use 'global'`, 'DEP0016');
   }
 
   function makeSetter(name) {
-    return util.deprecate(function(value) {
+    return deprecate(function(value) {
       Object.defineProperty(this, name, {
         configurable: true,
         writable: true,
@@ -408,7 +432,9 @@ function setupGlobalVariables() {
       set: makeSetter('root')
     }
   });
+}
 
+function setupBuffer() {
   const { Buffer } = NativeModule.require('buffer');
   const bufferBinding = internalBinding('buffer');
 
@@ -423,9 +449,6 @@ function setupGlobalVariables() {
     writable: true,
     configurable: true
   });
-
-  process.domain = null;
-  process._exiting = false;
 }
 
 function setupGlobalTimeouts() {

lib/internal/bootstrap/primordials.js

@@ -72,7 +72,8 @@ primordials.SafePromise = makeSafe(
   'Function',
   'Object',
   'RegExp',
-  'String'
+  'String',
+  'Symbol',
 ].forEach((name) => {
   const target = primordials[name] = Object.create(null);
   copyProps(global[name], target);

node.gyp

@@ -25,7 +25,7 @@
     'node_lib_target_name%': 'node_lib',
     'node_intermediate_lib_type%': 'static_library',
     'library_files': [
-      'lib/internal/per_context.js',
+      'lib/internal/bootstrap/context.js',
       'lib/internal/bootstrap/primordials.js',
       'lib/internal/bootstrap/cache.js',
       'lib/internal/bootstrap/loaders.js',

src/api/environment.cc

@@ -192,15 +192,15 @@ Local<Context> NewContext(Isolate* isolate,
                            True(isolate));
 
   {
-    // Run lib/internal/per_context.js
+    // Run lib/internal/bootstrap/context.js
     Context::Scope context_scope(context);
 
     std::vector<Local<String>> parameters = {
         FIXED_ONE_BYTE_STRING(isolate, "global")};
     Local<Value> arguments[] = {context->Global()};
     MaybeLocal<Function> maybe_fn =
         per_process::native_module_loader.LookupAndCompile(
-            context, "internal/per_context", &parameters, nullptr);
+            context, "internal/bootstrap/context", &parameters, nullptr);
     if (maybe_fn.IsEmpty()) {
       return Local<Context>();
     }