process: Add code to warnings, assign codes to deprecations #10116

jasnell · 2016-12-04T21:10:15Z

Checklist

make -j8 test (UNIX), or vcbuild test nosign (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

process, lib

Description of change

As discussed at the Node.js Interactive Collaboration Summit in Austin last week, this PR adds a few new capabilities that should make it easier to make dealing with runtime deprecation warnings in Node.js easier.

A static identifier code can be assigned to all process warnings. These are specified as either a new optional argument to process.emitWarning() or as a code property on an Error object passed into process.emitWarning(). Within the process.on('warning') event handler, these can be accessed via the code property on the warning object.
A new --redirect-warnings=file command line argument and matching NODE_REDIRECT_WARNINGS=file environment variable is added to allow process warning output to be printed to the given file as opposed to dumping to stderr. This will allow, for instance, npm and other applications spawning node process instances to capture warning output with less noise to the console.
Every runtime and documentation-only deprecation in Node.js is assigned a static identifier code.
A new deprecations.md file is added to the API documentation that lists each of the runtime and documentation-only deprecation codes assigned. For future work (perhaps a good first contribution for new Node.js contributors), it would be helpful to expand the details in deprecations.md to include links to the relevant sections in other parts of the API documentation as well as expanded descriptions of why the APIs are deprecated and what the alternatives are. /cc @nodejs/documentation

Note: This PR is currently semver-major because it adds improved type checking to the input on process.emitWarning() to ensure that both the warning name and the identifier code are strings.
If this PR is backported to older Node.js release streams, the backport can be landed as a semver-minor if and only if the additional type checking on the name argument is removed.

/cc @ashleygwilliams

jasnell · 2016-12-04T21:11:35Z

CI: https://ci.nodejs.org/job/node-test-pull-request/5176/

addaleax · 2016-12-04T21:20:18Z

doc/api/cli.md

+-->
+
+Write process warnings to the given file instead of printing to stderr but
+only if the file does not already exist.


Why “only if the file does not already exist”? I’m not sure I’d expect that, and it sounds a bit like that might interfere with programmatic use of the API.

Is this about multiple node processes sharing the same env var?

I'm not entirely sure about the only if the file does not already exist part either. For now I have it this way just to ensure that something important isn't accidentally overwritten.

Maybe we should just append?

Just appending works also. Doing so is pretty safe when dealing with multiple node processes since the warning output includes the pid

addaleax · 2016-12-04T21:22:13Z

doc/api/deprecations.md

+`OutgoingMessage.prototype.flushHeaders()` instead.
+
+<a id="DEP00002"></a>
+### DEP00002: require('_linklist')


This should probably be \_linklist (including the \)

addaleax · 2016-12-04T21:24:09Z

doc/api/process.md

 <!-- YAML
 added: v6.0.0
 -->

 * `warning` {String | Error} The warning to emit.
 * `name` {String} When `warning` is a String, `name` is the name to use
  for the warning. Default: `Warning`.
+* `code` {String} A unique identifier for the warning.


I’m not sure the semantic difference between name and code is obvious here?

Name may be better as "type"?

type is a good option

Name may be better as "type"?

Remember that .name is inherited from the Error classes – I don’t think we can change that.

I’m also not worried that much about the naming, a bit of clarification might be all that’s needed

The argument can be called type with name still used on the error object. I'm not overly concerned about the difference there.

addaleax · 2016-12-04T21:24:59Z

lib/buffer.js

+ * The Buffer() construtor is deprecated in documentation and should not be
+ * used moving forward. Rather, developers should use one of the three new
+ * factory APIs: Buffer.from(), Buffer.allocUnsafe() or Buffer.alloc() based on
+ * their specific needs. There is no hard deprecation because of the extent to


nit: Runtime deprecation? ;)

addaleax · 2016-12-04T21:25:07Z

lib/buffer.js

+ * used moving forward. Rather, developers should use one of the three new
+ * factory APIs: Buffer.from(), Buffer.allocUnsafe() or Buffer.alloc() based on
+ * their specific needs. There is no hard deprecation because of the extent to
+ * which the Buffer constructor is used in the ecosystem currently -- a hard


addaleax · 2016-12-04T21:27:33Z

lib/internal/process/warning.js

 const prefix = `(${process.release.name}:${process.pid}) `;

 exports.setup = setupProcessWarnings;

+var fd;
+function acquireFd() {
+  if (!fd) {


Nit: fd === undefined

addaleax · 2016-12-04T21:29:49Z

lib/internal/process/warning.js

+    }
+    if (code && typeof code !== 'string')
+      throw new TypeError('`code` must be a String');
+    if (name && typeof name !== 'string')


nit: name !== undefined and code !== undefined

addaleax · 2016-12-04T21:30:12Z

lib/internal/util.js

@@ -51,11 +51,18 @@ exports._deprecate = function(fn, msg) {
    return fn;
  }

+  if (code && typeof code !== 'string')


addaleax · 2016-12-04T21:30:47Z

src/node_config.cc

@@ -44,6 +45,16 @@ void InitConfig(Local<Object> target,

  if (config_preserve_symlinks)
    READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
+
+  if (config_warning_file != NULL) {


nit: nullptr

jasnell · 2016-12-04T22:20:52Z

@addaleax @Fishrock123 ... updated to address the nits. Updated the --redirect-warnings to append and renamed the emitWarning() name argument to type

silverwind · 2016-12-05T00:44:25Z

doc/api/process.md

@@ -706,14 +706,15 @@ console.log(process.env.test);
 // => 1
 ```

-## process.emitWarning(warning[, name][, ctor])
+## process.emitWarning(warning[, type[, code]][, ctor])


I think a options object {type, code, ctor} is in order here.

I think this is basically just intended for internal use, so doesn't need a nice API, and changing the call signature would cause a fair amount of internal churn.

Honestly, I don't think it should be an API at all, maybe we can deprecate it? Seriously, why do we want to expose this to users of node? We expect them to be using it to emit their own warnings?

Honestly, I don't think it should be an API at all, maybe we can deprecate it? Seriously, why do we want to expose this to users of node? We expect them to be using it to emit their own warnings?

Fwiw it was deliberately added as an outward-facing API in c6656db (released in v6.0.0) with that intention, yes. I don’t mind it being there.

It was exposed this way because we had users asking to be able to use it also. I'm definitely -1 on deprecating it as I have found it to be quite useful

OK, then I agree with @silverwind, its become an ugly API, with three strings in a row, 2 of which are optional, and remembering the arg order isn't reasonably possible. @addaleax the problem with APIs is they rot with time, becoming harder and harder to use and support, like this one is now, which is why I am generally in favour of not adding unnecessary APIs, even if when they are useful. I guess given the alternative of adding a second options-based call pattern, and supporting the old 3 argument call for backwards compatibility, and documenting both of them, or just adding another optional string arg, better to do the latter. If we ever add a 4th string, though, it will no longer be reasonable.

@sam-github My thoughts exactly. Supporting two call signatures is easy and enables easier future additons.

The API already supports two call signatures. The first argument can be passed in as a pre-constructed Error object with all of the relevant properties set:

const warning = new Error('This is a warning'); warning.name = 'CustomWarning'; warning.code = 'ABC123'; process.emitWarning(warning);

is equivalent to:

process.emitWarning('This is a warning', 'CustomWarning', 'ABC123');

Having an options object when we can already pass in an Error object would be rather pointless, IMO

That Error behaviour isn't well documented. I read carefully, and I see now that its implied by by the "If warning is passed as an Error object, it will be passed through .... unmodified" sentence.

I think the docs could be clearer, but that's an aside from this PR.

It's not just implied, it's explicitly stated in the arguments list that warning can be a string or an Error, and an example of passing an Error is shown immediately following the If warning is passed as an Error object... sentence. Immediately following the example is a clear statement that a TypeError will be thrown is warning is anything other than a string or Error object. The docs seem pretty explicit about it.

jasnell · 2016-12-05T01:15:59Z

I disagree. The method already has the option of passing in a Error object as the first parameter. Switching to an options object would just add confusion, I think.

…

On Sun, Dec 4, 2016 at 4:44 PM silverwind ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In doc/api/process.md <#10116 (review)>: > @@ -706,14 +706,15 @@ console.log(process.env.test); // => 1 ``` -## process.emitWarning(warning[, name][, ctor]) +## process.emitWarning(warning[, type[, code]][, ctor]) I think a options object is in order here. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#10116 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa2ec-j0kNP2A0JnuBeKN3ejbShHNY-ks5rE15ugaJpZM4LDsqo> .

thefourtheye · 2016-12-05T03:56:00Z

doc/api/deprecations.md

+
+Type: Documentation-only
+
+The `Buffer()` and `new Buffer()` constructors are considered to be deprecated


Buffer() is not considered as a constructor

thefourtheye · 2016-12-05T03:56:47Z

doc/api/deprecations.md

+As an alternative, use of the following methods of constructing `Buffer` objects
+is strongly recommended:
+
+* `Buffer.alloc(size[, fill[, encoding]])` - Create a `Buffer` with


Providing links to these methods will be helpful.

thefourtheye · 2016-12-05T04:00:06Z

doc/api/deprecations.md

+
+Type: Runtime
+
+The `crypto.Credentials` class is deprecated. Please Uuse `tls.SecureContext`


thefourtheye · 2016-12-05T04:01:07Z

doc/api/deprecations.md

+Type: Runtime
+
+The `constants` module has been deprecated. When requiring access to constants
+relevant to specific Node.js built in modules, developers should instead refer


thefourtheye · 2016-12-05T04:02:23Z

doc/api/deprecations.md

+
+Type: Runtime
+
+The `fs.read()` legacy String interface is deprecated. Use the Buffer API as


We explicitly ask the readers to refer documentation, it would be better if we had the link here.

thefourtheye · 2016-12-05T04:10:25Z

doc/api/deprecations.md

+
+Type: Documentation-only
+
+The `require.extensions` API has been deprecated.


property or API

thefourtheye · 2016-12-05T04:16:47Z

lib/constants.js

@@ -1,8 +1,9 @@
 'use strict';

-// This module is soft-deprecated. Users should be directed towards using
+// This module is deprecate in docs. Users should be directed towards using


doc-deprecated?

thefourtheye · 2016-12-05T04:54:56Z

lib/internal/process/warning.js

+        if (warning.code) {
+          output(`${prefix}[${warning.code}] ${toString.apply(warning)}`);
+        } else {
+          output(`${prefix}${toString.apply(warning)}`);


Should there be a space after ${prefix}?

No, the ${prefix} includes a space already

thefourtheye · 2016-12-05T05:00:14Z

src/node_config.cc

+  if (config_warning_file != nullptr) {
+    target->DefineOwnProperty(env->context(),
+                              OneByteString(env->isolate(), "warningFile"),
+                              String::NewFromUtf8(env->isolate(),


Can we split them into multiple variables?

thefourtheye · 2016-12-05T05:01:50Z

test/parallel/test-process-redirect-warnings-env.js

+fork(warnmod, {env: {NODE_REDIRECT_WARNINGS: warnpath}})
+  .on('exit', common.mustCall(() => {
+    fs.stat(warnpath, common.mustCall((err, stat) => {
+      assert(!err);


assert.ifError

silverwind · 2016-12-05T06:06:57Z

Switching to an options object would just add confusion, I think.

It's more of a general adivce to design APIs in a extendable way. I think that once a function takes 3 or more arguments, it gets to a point where the user has to lookup the arguments on less-frequently used functions, which could've been avoided if it would be designed with a options object from the start.

Fishrock123 · 2016-12-05T15:10:11Z

What do we do about things we have to un-deprecate? Just remove them from the doc? Or mark them as no longer deprecated?

jasnell · 2016-12-05T16:00:02Z

I'd leave them in the doc and label them as undeprecated. The codes should increase monotonically so leaving them in the doc will avoid collisions

…

On Mon, Dec 5, 2016 at 7:10 AM Jeremiah Senkpiel ***@***.***> wrote: What do we do about things we have to un-deprecate? Just remove them from the doc? Or mark them as no longer deprecated? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#10116 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa2eWrYaP8LINcM1uUgqt8HFsZHXYIaks5rFClXgaJpZM4LDsqo> .

jasnell · 2016-12-05T18:13:09Z

@silverwind ... I don't disagree, but as I said, this API already provides the option of passing in an Error object as the first argument. Given that, I don't see significant value in providing an options object

jasnell · 2016-12-05T18:14:00Z

@thefourtheye ... updated to address your feedback. I squashed and force pushed to keep things organized.

jasnell · 2016-12-05T18:25:36Z

New CI: https://ci.nodejs.org/job/node-test-pull-request/5211/

jasnell · 2016-12-06T20:56:39Z

@nodejs/ctc ... thoughts on this?

trevnorris · 2016-12-09T22:11:12Z

@jasnell there a way to automatically track the next deprecation code? feel it could be error prone or frustrating to grep all the current ones to find the next.

jasnell · 2016-12-09T22:12:57Z

There might be, but we need to make sure they stay static once assigned. Best bet would be to check the deprecations.md and assign the next highest, then make sure that doc always gets updated with a new deprecation

…

On Fri, Dec 9, 2016 at 2:11 PM Trevor Norris ***@***.***> wrote: @jasnell <https://github.com/jasnell> there a way to automatically track the next deprecation code? feel it could be error prone or frustrating to grep all the current ones to find the next. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#10116 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa2efCdwqCpSxTV1JESmkYNkFF7MQHwks5rGdIEgaJpZM4LDsqo> .

trevnorris · 2016-12-09T22:22:16Z

@jasnell ah. missed deprecations.md b/c github refrained from loading it. okay, seems reasonable enough.

sam-github · 2017-07-21T20:49:47Z

I backported 03e89b3 to 6.x, the other commits look semver-major to me, as they add deprecation code and change the output format. Do I misunderstand?

The --redirect-warnings command line argument allows process warnings to be written to a specified file rather than printed to stderr. Also adds an equivalent NODE_REDIRECT_WARNINGS environment variable. If the specified file cannot be opened or written to for any reason, the argument is ignored and the warning is printed to stderr. If the file already exists, it will be appended to. PR-URL: nodejs#10116 Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Michal Zasso <[email protected]> Reviewed-By: Fedor Indutny <[email protected]>

The --redirect-warnings command line argument allows process warnings to be written to a specified file rather than printed to stderr. Also adds an equivalent NODE_REDIRECT_WARNINGS environment variable. If the specified file cannot be opened or written to for any reason, the argument is ignored and the warning is printed to stderr. If the file already exists, it will be appended to. Backport-PR-URL: #14418 PR-URL: #10116 Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Michal Zasso <[email protected]> Reviewed-By: Fedor Indutny <[email protected]>

The --redirect-warnings command line argument allows process warnings to be written to a specified file rather than printed to stderr. Also adds an equivalent NODE_REDIRECT_WARNINGS environment variable. If the specified file cannot be opened or written to for any reason, the argument is ignored and the warning is printed to stderr. If the file already exists, it will be appended to. Backport-PR-URL: nodejs#14418 PR-URL: nodejs#10116 Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Michal Zasso <[email protected]> Reviewed-By: Fedor Indutny <[email protected]>

The --redirect-warnings command line argument allows process warnings to be written to a specified file rather than printed to stderr. Also adds an equivalent NODE_REDIRECT_WARNINGS environment variable. If the specified file cannot be opened or written to for any reason, the argument is ignored and the warning is printed to stderr. If the file already exists, it will be appended to. PR-URL: nodejs#10116 Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Michal Zasso <[email protected]> Reviewed-By: Fedor Indutny <[email protected]>

The --redirect-warnings command line argument allows process warnings to be written to a specified file rather than printed to stderr. Also adds an equivalent NODE_REDIRECT_WARNINGS environment variable. If the specified file cannot be opened or written to for any reason, the argument is ignored and the warning is printed to stderr. If the file already exists, it will be appended to. Backport-PR-URL: #12677 PR-URL: #10116 Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Michal Zasso <[email protected]> Reviewed-By: Fedor Indutny <[email protected]>

Notable Changes: * assert: - assert.fail() can now take one or two arguments (Rich Trott) #12293 * crypto: - add sign/verify support for RSASSA-PSS (Tobias Nießen) #11705 * deps: - upgrade openssl sources to 1.0.2m (Shigeki Ohtsu) #16691 - upgrade libuv to 1.15.0 (cjihrig) #15745 - upgrade libuv to 1.14.1 (cjihrig) #14866 - upgrade libuv to 1.13.1 (cjihrig) #14117 - upgrade libuv to 1.12.0 (cjihrig) #13306 * fs: - Add support for fs.write/fs.writeSync(fd, buffer, cb) and fs.write/fs.writeSync(fd, buffer, offset, cb) as documented (Andreas Lind) #7856 * inspector: - enable --inspect-brk (Refael Ackermann) #12615 * process: - add --redirect-warnings command line argument (James M Snell) #10116 * src: - allow CLI args in env with NODE_OPTIONS (Sam Roberts) #12028) - --abort-on-uncaught-exception in NODE_OPTIONS (Sam Roberts) #13932 - allow --tls-cipher-list in NODE_OPTIONS (Sam Roberts) #13172 - use SafeGetenv() for NODE_REDIRECT_WARNINGS (Sam Roberts) #12677 * test: - remove common.fail() (Rich Trott) #12293 PR-URL: #16263

jasnell added lib / src Issues and PRs related to general changes in the lib or src directory. process Issues and PRs related to the process subsystem. semver-major PRs that contain breaking changes and should be released in the next major version. labels Dec 4, 2016

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. labels Dec 4, 2016

addaleax reviewed Dec 4, 2016

View reviewed changes

jasnell force-pushed the warning-additions branch 2 times, most recently from 5bf38a7 to 3b98c43 Compare December 4, 2016 22:19

silverwind reviewed Dec 5, 2016

View reviewed changes

thefourtheye reviewed Dec 5, 2016

View reviewed changes

jasnell force-pushed the warning-additions branch 2 times, most recently from d6799a0 to eea42cb Compare December 5, 2016 18:11

jasnell force-pushed the warning-additions branch 2 times, most recently from 658588a to e5d79fd Compare December 5, 2016 18:24

jasnell force-pushed the warning-additions branch from e5d79fd to 3a19ece Compare December 5, 2016 19:57

jasnell requested review from mscdex and ofrobots December 11, 2016 00:55

sam-github mentioned this pull request Jul 21, 2017

(v6.x backport) process: add --redirect-warnings command line argument #14418

Merged

4 tasks

sam-github mentioned this pull request Jul 25, 2017

(v6.x backport) process: add --redirect-warnings command line argument #14480

Closed

4 tasks

MylesBorins mentioned this pull request Oct 17, 2017

v6.12.0 proposal #16263

Merged

MylesBorins mentioned this pull request Nov 3, 2017

v4.8.6 proposal #16500

Merged

tniessen added the deprecations Issues and PRs related to deprecations. label Sep 7, 2018

targos removed their assignment Oct 31, 2021


		Type: Documentation-only

		The `Buffer()` and `new Buffer()` constructors are considered to be deprecated


		Type: Runtime

		The `crypto.Credentials` class is deprecated. Please Uuse `tls.SecureContext`


		Type: Runtime

		The `fs.read()` legacy String interface is deprecated. Use the Buffer API as


		Type: Documentation-only

		The `require.extensions` API has been deprecated.

process: Add code to warnings, assign codes to deprecations #10116

process: Add code to warnings, assign codes to deprecations #10116

Conversation

jasnell commented Dec 4, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

jasnell commented Dec 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Dec 4, 2016

silverwind Dec 5, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Dec 5, 2016 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Dec 5, 2016 • edited Loading

Fishrock123 commented Dec 5, 2016

jasnell commented Dec 5, 2016 via email

jasnell commented Dec 5, 2016

jasnell commented Dec 5, 2016

jasnell commented Dec 5, 2016

jasnell commented Dec 6, 2016

trevnorris commented Dec 9, 2016

jasnell commented Dec 9, 2016 via email

trevnorris commented Dec 9, 2016

sam-github commented Jul 21, 2017

jasnell commented Dec 4, 2016 •

edited

Loading

silverwind Dec 5, 2016 •

edited

Loading

silverwind commented Dec 5, 2016 •

edited

Loading