src, buffer: add --pending-deprecation flag

doc/api/cli.md

@@ -137,6 +137,20 @@ added: v0.11.14
 
 Throw errors for deprecations.
 
+### `--pending-deprecation`
+<!-- YAML
+added: REPLACEME
+-->
+
+Emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `--no-warnings`
 <!-- YAML
 added: v6.0.0
@@ -375,6 +389,20 @@ added: v7.5.0
 
 When set to `1`, process warnings are silenced.
 
+### `NODE_PENDING_DEPRECATION=1`
+<!-- YAML
+added: REPLACEME
+-->
+
+When set to `1`, emit pending deprecation warnings.
+
+*Note*: Pending deprecations are generally identical to a runtime deprecation
+with the notable exception that they are turned *off* by default and will not
+be emitted unless either the `--pending-deprecation` command line flag, or the
+`NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
+are used to provide a kind of selective "early warning" mechanism that
+developers may leverage to detect deprecated API usage.
+
 ### `NODE_PRESERVE_SYMLINKS=1`
 <!-- YAML
 added: v7.1.0

doc/node.1

@@ -115,6 +115,10 @@ Print stack traces for deprecations.
 .BR \-\-throw\-deprecation
 Throw errors for deprecations.
 
+.TP
+.BR \-\-pending\-deprecation
+Emit pending deprecation warnings.
+
 .TP
 .BR \-\-no\-warnings
 Silence all process warnings (including deprecations).
@@ -254,6 +258,10 @@ When set to \fI1\fR, process warnings are silenced.
 .BR NODE_PATH =\fIpath\fR[:\fI...\fR]
 \':\'\-separated list of directories prefixed to the module search path.
 
+.TP
+.BR NODE_PENDING_DEPRECATION = \fI1\fR
+When set to \fI1\fR, emit pending deprecation warnings.
+
 .TP
 .BR NODE_REPL_HISTORY =\fIfile\fR
 Path to the file used to store the persistent REPL history. The default path

lib/buffer.js

@@ -22,19 +22,21 @@
 'use strict';
 
 const binding = process.binding('buffer');
+const config = process.binding('config');
 const { compare: compare_, compareOffset } = binding;
 const { isArrayBuffer, isSharedArrayBuffer, isUint8Array } =
     process.binding('util');
 const bindingObj = {};
 const internalUtil = require('internal/util');
+const pendingDeprecation = !!config.pendingDeprecation;
 
 class FastBuffer extends Uint8Array {
   constructor(arg1, arg2, arg3) {
     super(arg1, arg2, arg3);
   }
 }
-
 FastBuffer.prototype.constructor = Buffer;
+
 Buffer.prototype = FastBuffer.prototype;
 
 exports.Buffer = Buffer;
@@ -84,6 +86,28 @@ function alignPool() {
   }
 }
 
+var bufferWarn = true;
+const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' +
+                      'recommended for use due to security and usability ' +
+                      'concerns. Please use the new Buffer.alloc(), ' +
+                      'Buffer.allocUnsafe(), or Buffer.from() construction ' +
+                      'methods instead.';
+
+function showFlaggedDeprecation() {
+  if (bufferWarn) {
+    // This is a *pending* deprecation warning. It is not emitted by
+    // default unless the --pending-deprecation command-line flag is
+    // used or the NODE_PENDING_DEPRECATION=1 envvar is set.
+    process.emitWarning(bufferWarning, 'DeprecationWarning', 'DEP0005');
+    bufferWarn = false;
+  }
+}
+
+const doFlaggedDeprecation =
+  pendingDeprecation ?
+    showFlaggedDeprecation :
+    function() {};
+
 /**
  * The Buffer() construtor is deprecated in documentation and should not be
  * used moving forward. Rather, developers should use one of the three new
@@ -95,6 +119,7 @@ function alignPool() {
  * Deprecation Code: DEP0005
  **/
 function Buffer(arg, encodingOrOffset, length) {
+  doFlaggedDeprecation();
   // Common case.
   if (typeof arg === 'number') {
     if (typeof encodingOrOffset === 'string') {
@@ -107,6 +132,12 @@ function Buffer(arg, encodingOrOffset, length) {
   return Buffer.from(arg, encodingOrOffset, length);
 }
 
+Object.defineProperty(Buffer, Symbol.species, {
+  enumerable: false,
+  configurable: true,
+  get() { return FastBuffer; }
+});
+
 /**
  * Functionally equivalent to Buffer(arg, encoding) but throws a TypeError
  * if value is a number.

src/node.cc

@@ -209,6 +209,10 @@ bool trace_warnings = false;
 // that is used by lib/module.js
 bool config_preserve_symlinks = false;
 
+// Set by ParseArgs when --pending-deprecation or NODE_PENDING_DEPRECATION
+// is used.
+bool config_pending_deprecation = false;
+
 // Set in node.cc by ParseArgs when --redirect-warnings= is used.
 std::string config_warning_file;  // NOLINT(runtime/string)
 
@@ -3741,6 +3745,8 @@ static void ParseArgs(int* argc,
       short_circuit = true;
     } else if (strcmp(arg, "--zero-fill-buffers") == 0) {
       zero_fill_all_buffers = true;
+    } else if (strcmp(arg, "--pending-deprecation") == 0) {
+      config_pending_deprecation = true;
     } else if (strcmp(arg, "--v8-options") == 0) {
       new_v8_argv[new_v8_argc] = "--help";
       new_v8_argc += 1;
@@ -4263,6 +4269,12 @@ void Init(int* argc,
   V8::SetFlagsFromString(NODE_V8_OPTIONS, sizeof(NODE_V8_OPTIONS) - 1);
 #endif
 
+  {
+    std::string text;
+    config_pending_deprecation =
+        SafeGetenv("NODE_PENDING_DEPRECATION", &text) && text[0] == '1';
+  }
+
   // Allow for environment set preserving symlinks.
   {
     std::string text;

src/node_config.cc

@@ -49,6 +49,9 @@ void InitConfig(Local<Object> target,
   if (config_preserve_symlinks)
     READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
 
+  if (config_pending_deprecation)
+    READONLY_BOOLEAN_PROPERTY("pendingDeprecation");
+
   if (!config_warning_file.empty()) {
     Local<String> name = OneByteString(env->isolate(), "warningFile");
     Local<String> value = String::NewFromUtf8(env->isolate(),

src/node_internals.h

@@ -70,6 +70,10 @@ extern bool config_preserve_symlinks;
 // it to stderr.
 extern std::string config_warning_file;  // NOLINT(runtime/string)
 
+// Set in node.cc by ParseArgs when --pending-deprecation or
+// NODE_PENDING_DEPRECATION is used
+extern bool config_pending_deprecation;
+
 // Tells whether it is safe to call v8::Isolate::GetCurrent().
 extern bool v8_initialized;
 

test/parallel/test-buffer-nopendingdep-map.js

@@ -0,0 +1,14 @@
+// Flags: --no-warnings --pending-deprecation
+'use strict';
+
+const common = require('../common');
+const Buffer = require('buffer').Buffer;
+
+process.on('warning', common.mustNotCall('A warning should not be emitted'));
+
+// With the --pending-deprecation flag, the deprecation warning for
+// new Buffer() should not be emitted when Uint8Array methods are called.
+
+Buffer.from('abc').map((i) => i);
+Buffer.from('abc').filter((i) => i);
+Buffer.from('abc').slice(1, 2);

test/parallel/test-buffer-pending-deprecation.js

@@ -0,0 +1,15 @@
+// Flags: --pending-deprecation --no-warnings
+'use strict';
+
+const common = require('../common');
+const Buffer = require('buffer').Buffer;
+
+const bufferWarning = 'The Buffer() and new Buffer() constructors are not ' +
+                      'recommended for use due to security and usability ' +
+                      'concerns. Please use the new Buffer.alloc(), ' +
+                      'Buffer.allocUnsafe(), or Buffer.from() construction ' +
+                      'methods instead.';
+
+common.expectWarning('DeprecationWarning', bufferWarning);
+
+new Buffer(10);

test/parallel/test-pending-deprecation.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// Tests that --pending-deprecation and NODE_PENDING_DEPRECATION both
+// set the process.binding('config').pendingDeprecation flag that is
+// used to determine if pending deprecation messages should be shown.
+// The test is performed by launching two child processes that run
+// this same test script with different arguments. If those exit with
+// code 0, then the test passes. If they don't, it fails.
+
+const common = require('../common');
+
+const assert = require('assert');
+const config = process.binding('config');
+const fork = require('child_process').fork;
+
+function message(name) {
+  return `${name} did not set the process.binding('config').` +
+         'pendingDeprecation flag.';
+}
+
+switch (process.argv[2]) {
+  case 'env':
+  case 'switch':
+    assert.strictEqual(config.pendingDeprecation, true);
+    break;
+  default:
+    // Verify that the flag is off by default.
+    assert.strictEqual(config.pendingDeprecation, undefined);
+
+    // Test the --pending-deprecation command line switch.
+    fork(__filename, ['switch'], {
+      execArgv: ['--pending-deprecation'],
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('--pending-deprecation'));
+    }));
+
+    // Test the NODE_PENDING_DEPRECATION environment var.
+    fork(__filename, ['env'], {
+      env: {NODE_PENDING_DEPRECATION: 1},
+      silent: true
+    }).on('exit', common.mustCall((code) => {
+      assert.strictEqual(code, 0, message('NODE_PENDING_DEPRECATION'));
+    }));
+}