From c4aca9fb35202da41e9febc0496cf7194c30bbe1 Mon Sep 17 00:00:00 2001
From: legendecas <legendecas@gmail.com>
Date: Sun, 16 Feb 2020 17:20:57 +0800
Subject: [PATCH] util: add private fields preview support

`util.previewValue` may reveal private fields of an object.
---
 doc/api/errors.md                        |   7 +
 doc/api/util.md                          |  43 +++++
 lib/internal/errors.js                   |   1 +
 lib/internal/util/inspect.js             | 201 ++++++++++++++++++++++-
 lib/util.js                              |   4 +-
 test/parallel/test-util-preview-value.js |  94 +++++++++++
 6 files changed, 348 insertions(+), 2 deletions(-)
 create mode 100644 test/parallel/test-util-preview-value.js

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 8f3af6fcb6a9d6..f03ba215b0b620 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -1689,6 +1689,13 @@ object.
 
 An attempt was made to `require()` an [ES Module][].
 
+<a id="ERR_PREVIEW_FAILURE"></a>
+### `ERR_PREVIEW_FAILURE`
+
+> Stability: 1 - Experimental
+
+An attempt of previewing a JavaScript value was failed.
+
 <a id="ERR_SCRIPT_EXECUTION_INTERRUPTED"></a>
 ### `ERR_SCRIPT_EXECUTION_INTERRUPTED`
 
diff --git a/doc/api/util.md b/doc/api/util.md
index b702d5adba3a2c..319afaf8782f26 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -885,6 +885,49 @@ Otherwise, returns `false`.
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
+### `util.previewValue(value[, opts])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `object` {any} Any JavaScript primitive or `Object`.
+* `options` {Object}
+  * `breakLength` {integer} The length at which input values are split across
+    multiple lines. Set to `Infinity` to format the input as a single line
+    (in combination with `compact` set to `true` or any number >= `1`).
+    **Default:** `80`.
+  * `colors` {boolean} If `true`, the output is styled with ANSI color
+    codes. Colors are customizable. See [Customizing `util.inspect` colors][].
+    **Default:** `false`.
+  * `compact` {boolean|integer} Setting this to `false` causes each object key
+    to be displayed on a new line. It will also add new lines to text that is
+    longer than `breakLength`. If set to a number, the most `n` inner elements
+    are united on a single line as long as all properties fit into
+    `breakLength`. Short array elements are also grouped together. No
+    text will be reduced below 16 characters, no matter the `breakLength` size.
+    For more information, see the example below. **Default:** `3`.
+* Returns: {Promise<string>} A promise of the representation of `object`.
+
+> Stability: 1 - Experimental
+
+The `util.previewValue` method returns promise of a string representation
+of `object` that is intended for debugging. The output of `util.previewValue`
+may change at any time and should not be depended upon programmatically.
+Additional `options` may be passed that alter the result. `util.previewValue()`
+will use the constructor's name make an identifiable tag for an inspected value.
+
+The difference of this method with `util.inspect` is `util.previewValue` can
+reveal target own private fields.
+
+```javascript
+class Foo { #bar = 'baz' }
+
+util.previewValue(new Foo())
+  .then((preview) => {
+    console.log(preview); // 'Foo { #bar: "baz" }'
+  });
+```
+
 ## `util.promisify(original)`
 <!-- YAML
 added: v8.0.0
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
index e0668e2f827e5f..7a1fa4f47e4a46 100644
--- a/lib/internal/errors.js
+++ b/lib/internal/errors.js
@@ -1280,6 +1280,7 @@ E('ERR_PACKAGE_PATH_NOT_EXPORTED', (pkgPath, subpath, base = undefined) => {
       pkgPath} imported from ${base}`;
   }
 }, Error);
+E('ERR_PREVIEW_FAILURE', 'Preview value failed for reason: "%s"', Error);
 E('ERR_REQUIRE_ESM',
   (filename, parentPath = null, packageJsonPath = null) => {
     let msg = `Must use import to load ES Module: ${filename}`;
diff --git a/lib/internal/util/inspect.js b/lib/internal/util/inspect.js
index f59e7db3a9782c..59bdd8dd3370d3 100644
--- a/lib/internal/util/inspect.js
+++ b/lib/internal/util/inspect.js
@@ -36,6 +36,7 @@ const {
   ObjectPrototypeHasOwnProperty,
   ObjectPrototypePropertyIsEnumerable,
   ObjectSeal,
+  Promise,
   RegExp,
   RegExpPrototypeToString,
   Set,
@@ -73,7 +74,8 @@ const {
 
 const {
   codes: {
-    ERR_INVALID_ARG_TYPE
+    ERR_INVALID_ARG_TYPE,
+    ERR_PREVIEW_FAILURE
   },
   isStackOverflowError
 } = require('internal/errors');
@@ -120,6 +122,12 @@ const assert = require('internal/assert');
 
 const { NativeModule } = require('internal/bootstrap/loaders');
 
+const { hasInspector } = internalBinding('config');
+
+let inspector;
+let privateInspectionSession;
+let privatePreviewSessionCount = 0;
+
 const setSizeGetter = uncurryThis(
   ObjectGetOwnPropertyDescriptor(SetPrototype, 'size').get);
 const mapSizeGetter = uncurryThis(
@@ -2027,11 +2035,202 @@ function stripVTControlCharacters(str) {
   return str.replace(ansi, '');
 }
 
+async function previewValue(target, opts) {
+  const ctx = {
+    budget: {},
+    indentationLvl: 0,
+    currentDepth: 0,
+    stylize: stylizeNoColor,
+    compact: inspectDefaultOptions.compact,
+    breakLength: inspectDefaultOptions.breakLength,
+  };
+  if (opts) {
+    const optKeys = ObjectKeys(opts);
+    for (const key of optKeys) {
+      if (ObjectPrototypeHasOwnProperty(inspectDefaultOptions, key)) {
+        ctx[key] = opts[key];
+      } else if (ctx.userOptions === undefined) {
+        // This is required to pass through the actual user input.
+        ctx.userOptions = opts;
+      }
+    }
+  }
+  if (ctx.colors) {
+    ctx.stylize = stylizeWithColor;
+  }
+
+  return previewRaw(ctx, target);
+}
+
+async function previewRaw(ctx, target) {
+  if (typeof target !== 'object' &&
+      typeof target !== 'function' &&
+      !isUndetectableObject(target)) {
+    return formatPrimitive(ctx.stylize, target, ctx);
+  }
+  if (target === null) {
+    return ctx.stylize('null', 'null');
+  }
+  if (typeof target === 'function') {
+    return formatRaw(ctx, target);
+  }
+
+  const preview = await getValuePreviewAsync(target);
+  if (preview == null) {
+    return undefined;
+  }
+  return formatInspectorPropertyPreview(ctx, target, preview);
+}
+
+function previewPrelude() {
+  if (!hasInspector) {
+    return false;
+  }
+  if (privateInspectionSession == null) {
+    inspector = require('inspector');
+    privateInspectionSession = new inspector.Session();
+    privateInspectionSession.connect();
+  }
+  return true;
+}
+
+function getValuePreviewAsync(target) {
+  if (!previewPrelude()) {
+    return undefined;
+  }
+  if (privatePreviewSessionCount === 0) {
+    privateInspectionSession.post('Runtime.enable');
+    privateInspectionSession.post('Debugger.enable');
+  }
+  privatePreviewSessionCount++;
+
+  return new Promise((resolve, reject) => {
+    privateInspectionSession.once('Debugger.paused', (pausedContext) => {
+      const callFrames = pausedContext.params.callFrames;
+      /** USED */target;
+      privateInspectionSession.post(
+        'Debugger.evaluateOnCallFrame', {
+          /**
+           * 0. inspector.dispatch,
+           * 1. inspector.post,
+           * 2. new Promise,
+           * 3. previewValueAsync
+           */
+          callFrameId: callFrames[3].callFrameId,
+          expression: 'target',
+        }, (err, result) => {
+          if (err) {
+            return reject(err);
+          }
+          const { result: evalResult } = result;
+
+          if (evalResult.type !== 'object') {
+            return resolve();
+          }
+          if (evalResult.subtype === 'error') {
+            return reject(ERR_PREVIEW_FAILURE(evalResult.description));
+          }
+          resolve(getValuePreviewByObjectIdAsync(evalResult.objectId));
+        });
+    });
+    privateInspectionSession.post('Debugger.pause', () => {
+      /* pause doesn't return anything. */
+    });
+  }).finally(() => {
+    privatePreviewSessionCount--;
+    if (privatePreviewSessionCount === 0) {
+      privateInspectionSession.post('Runtime.disable');
+      privateInspectionSession.post('Debugger.disable');
+    }
+  });
+}
+
+function getValuePreviewByObjectIdAsync(objectId, options = {}) {
+  return new Promise((resolve, reject) => {
+    privateInspectionSession.post('Runtime.getProperties', {
+      objectId: objectId,
+      ownProperties: true,
+      ...options
+    }, (err, result) => {
+      if (err) {
+        return reject(err);
+      }
+      resolve(result);
+    });
+  });
+}
+
+async function formatInspectorPropertyPreview(
+  ctx, target, preview, isJsValue = true
+) {
+  const { result, privateProperties } = preview;
+
+  const output = [];
+  for (var item of [
+    // __proto__ is an own property
+    ...result.filter((it) => it.name !== '__proto__'),
+    ...(privateProperties ?? [])
+  ]) {
+    const valueDescriptor = item.value;
+    const valueType = valueDescriptor.type;
+    const subtype = valueDescriptor.subtype;
+    const stylize = ctx.stylize;
+    let str;
+    if (valueType === 'string') {
+      str = stylize(strEscape(valueDescriptor.value), valueType);
+    } else if (valueType === 'number') {
+      str = stylize(
+        // -0 is unserializable to JSON representation
+        valueDescriptor.value ?? valueDescriptor.unserializableValue,
+        valueType);
+    } else if (valueType === 'boolean') {
+      str = stylize(valueDescriptor.value, valueType);
+    } else if (valueType === 'symbol') {
+      str = stylize(valueDescriptor.description, valueType);
+    } else if (valueType === 'undefined') {
+      str = stylize(valueType, valueType);
+    } else if (subtype === 'null') {
+      str = stylize(subtype, 'null');
+    } else if (valueType === 'bigint') {
+      str = stylize(valueDescriptor.unserializableValue, valueType);
+    } else if (valueType === 'function') {
+      str = await previewFunction(ctx, valueDescriptor.objectId);
+    } else if (valueType === 'object') {
+      // TODO(legendecas): Inspect the whole object, not only the class name.
+      str = `#[${valueDescriptor.className}]`;
+    } else {
+      /* c8 ignore next */
+      assert.fail(`Unknown value type '${valueType}'`);
+    }
+    output.push(`${item.name}: ${str}`);
+  }
+
+  const constructor = isJsValue ?
+    getConstructorName(target, ctx, 0) :
+    target.className;
+  const braces = [`${getPrefix(constructor, '', 'Object')}{`, '}'];
+  const base = '';
+  const res = reduceToSingleString(
+    ctx, output, base, braces, kObjectType, ctx.currentDepth);
+  return res;
+}
+
+async function previewFunction(ctx, objectId) {
+  const { result } = await getValuePreviewByObjectIdAsync(
+    objectId, { ownProperties: false });
+  const nameDesc = result.find((it) => it.name === 'name');
+  if (nameDesc == null) {
+    return ctx.stylize('[Function]', 'function');
+  }
+  return ctx.stylize(`[Function: ${nameDesc.value.value}]`, 'function');
+}
+
 module.exports = {
   inspect,
   format,
   formatWithOptions,
   getStringWidth,
   inspectDefaultOptions,
+  previewValue,
   stripVTControlCharacters
 };
diff --git a/lib/util.js b/lib/util.js
index f9337598e69dc2..ac8a22803cea11 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -47,7 +47,8 @@ const {
 const {
   format,
   formatWithOptions,
-  inspect
+  inspect,
+  previewValue
 } = require('internal/util/inspect');
 const { debuglog } = require('internal/util/debuglog');
 const { validateNumber } = require('internal/validators');
@@ -269,6 +270,7 @@ module.exports = {
   isFunction,
   isPrimitive,
   log,
+  previewValue,
   promisify,
   TextDecoder,
   TextEncoder,
diff --git a/test/parallel/test-util-preview-value.js b/test/parallel/test-util-preview-value.js
new file mode 100644
index 00000000000000..ebb215aeebd19e
--- /dev/null
+++ b/test/parallel/test-util-preview-value.js
@@ -0,0 +1,94 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+const util = require('util');
+const { previewValue } = util;
+
+(async function() {
+  // Primitives
+  assert.strictEqual(
+    await previewValue(-0),
+    '-0'
+  );
+  assert.strictEqual(
+    await previewValue(0n),
+    '0n'
+  );
+  assert.strictEqual(
+    await previewValue(undefined),
+    'undefined'
+  );
+  assert.strictEqual(
+    await previewValue(null),
+    'null'
+  );
+  assert.strictEqual(
+    await previewValue('foo'),
+    "'foo'"
+  );
+  assert.strictEqual(
+    await previewValue(Symbol('foo')),
+    'Symbol(foo)'
+  );
+
+  // Private fields
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = 'bar'; }()),
+    "Foo { #val: 'bar' }"
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = 0; }()),
+    'Foo { #val: 0 }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = -0; }()),
+    'Foo { #val: -0 }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = 0n; }()),
+    'Foo { #val: 0n }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = -0n; }()),
+    'Foo { #val: 0n }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = Symbol('bar'); }()),
+    'Foo { #val: Symbol(bar) }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = true; }()),
+    'Foo { #val: true }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = undefined; }()),
+    'Foo { #val: undefined }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = null; }()),
+    'Foo { #val: null }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = () => {}; }()),
+    'Foo { #val: [Function: #val] }'
+  );
+  assert.strictEqual(
+    await previewValue(new class Foo { #val = {}; }()),
+    'Foo { #val: #[Object] }'
+  );
+
+  // Functions
+  assert.strictEqual(
+    await previewValue(function foo() {}),
+    '[Function: foo]'
+  );
+
+  // Nested objects
+  {
+    class Bar { val = 'public'; }
+    assert.strictEqual(
+      await previewValue(new class Foo { #val = new Bar(); }()),
+      'Foo { #val: #[Bar] }'
+    );
+  }
+})();