src: deprecate legacy node::MakeCallback

[ofrobots]

The legacy MakeCallback functions do not provide a mechanism to
propagate async context. This means that any native modules using these
directly is likely breaking async debugging & tracing tools. For
example it is possible that such a module will cause incorrect async
stack traces to be reported (even when the module is not on the stack).

We've had context preserving versions of MakeCallback available since Node 8.x.

Ref: #13254, specifically #13254 (comment).
Related: nodejs/nan#729

This doesn't fit into any of the categories of deprecations as defined in our Deprecation policy. This is an API available to native modules via node.h. It is not otherwise documented. Chances are high that any given native module would be using this API. The migration path is fairly easy though.

We will now give a compile time warning when a module using the deprecated API is being compiled against Node 10. There is no runtime impact at this point. From this point of view, I guess this is closest to a Documentation-only deprecation.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• commit message follows commit guidelines

Affected core subsystem(s)

src, async_hooks

/cc @nodejs/async_hooks @nodejs/addon-api @nodejs/diagnostics

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

[vsemozhetbyt]

Nit: a `async_context` -> an `async_context`

[ofrobots]

Done.

[ofrobots]

As a semver-major this needs two @nodejs/tsc approvals.

[AndreasMadsen]

LGTM. Although, I think we need to declare C++ AsyncHooks Embedder API stable before we can do this. But I'm okay with that.

[ofrobots]

@AndreasMadsen

Although, I think we need to declare C++ AsyncHooks Embedder API stable before we can do this. But I'm okay with that.

This would have been an ideal way of doing things, but it should not be a requirement IMHO:

• We would want to have some feedback on the C++ AsyncHooks Embedder API before we move it out of experimental. It has been available since Node 8.x, and approximately 0% of modules are using it.
• This is a compile-time warning only. People are not prevented from using the deprecated functions. It does encourage modules to switch to the C++ API, and that will drive feedback for the AsyncHooks embedder API.

IOW, we need this change if we want to move the C++ AsynchHooks Embedder API to move out of experimental.

[AndreasMadsen]

@ofrobots Yeah, there is definitely conflicting interests. I think this will be for the TSC to decide.

The issue with deprecating it before the C++ Embedder API is marked stable, is that there will be no API for calling a callback that isn't either deprecated or experimental.

[ofrobots]

@AndreasMadsen there are prior examples of that. For example, Domains are deprecated even though there is no stable alternative to them (still).

there will be no API for calling a callback that isn't either deprecated or experimental.

To be pedantic, MakeCallback is not experimental. It is always possible for people to pass in a nullary async_context.

[addaleax]

This is a compile-time warning only. People are not prevented from using the deprecated functions. It does encourage modules to switch to the C++ API, and that will drive feedback for the AsyncHooks embedder API.

Maybe we could just set a time frame for the actual removal that is far enough in the future, or even better, indicate that we will never actually remove these functions?

[BridgeAR]

Landed in a570aca 🎉

[apapirovski]

Should this really have landed with a tsc-review label on it? 😕

[BridgeAR]

Uh, gosh... I missed that... Hm, I am going to force push it out again as it is only a few minutes ago.

[ofrobots]

@nodejs/tsc, this has the tsc-review label so please review.

Specifically @AndreasMadsen added the label around this question: #18632 (comment). He has LGTM'd this PR, so there isn't a conflict here, I think the intent is to make sure that the TSC is aware that this is happening. @AndreasMadsen please correct me if I misinterpreted your intent here. There are already the requisite 2 TSC LGTMs on this PR required for semver majors.

This is time sensitive, and should get into Node 10. As a semver major, it would be good to get this in before March. I am OOO starting next week, so I would like to make progress on this this week.

[apapirovski]

Perhaps something that could be discussed at the Diagnostics Summit even, given that @AndreasMadsen is in attendance, I believe.

[ofrobots]

@apapirovski We already have an LGTM from @AndreasMadsen. There is nothing to discuss. Unless if some questions/concerns come from the TSC as a result of the tsc-review label.

[MylesBorins]

I think discussing how this API will be handled long term doesn't require blocking this deprecation landing if there is already consensus on doing so.

Unless someone has an explicit -1 I feel like perhaps this should land and an issue to discuss long term deprecation should be opened.

[ofrobots]

Removing tsc-review as the tsc has been adequately pinged. I will land this later today.

[sam-github]

Unlike a docs-only deprecation, when native addons are installed, they will start printing compiler warnings about deprecated APIs to the console, where the installer of the addon (who is probably only installing it indirectly via a npm dep, and can't do anything about this) will see them, right? This strikes me as slightly more similar to a run-time deprecation that a doc deprecation.

I agree the problematic functions should be completely dropped ASAP so context propagation is preserved.

[ofrobots]

@sam-github You're right. I guess it is somewhere in the middle. Compile warnings show up at npm install time, for modules that don't ship pre-compiled blobs. A runtime deprecation, on the other hand, would show up each time the app is run.

[ofrobots]

Landed as efb3259.