node-api: include experimental feature flags in add-on version reported at runtime

[gabrielschulhof]

This only applies to features that change the behaviour of existing APIs.

We currently have two flags for each experimental behaviour-changing API:

1. A feature flag indicating that it is available within the NAPI_EXPERIMENTAL portion of the API.
2. An opt-out flag indicating that, although the add-on chose to use NAPI_EXPERIMENTAL it does not wish to use this particular feature of the experimental bundle.

In order to avoid going down the experimental code path when running an add-on that chose to opt out of an experimental feature, we need to encode that choice in the version reported to the add-on loader.

If NAPI_EXPERIMENTAL is defined, all experimental features are turned on, unless, for any given feature, its opt-out flag is given.

We can include experimental flags in the version number reported at runtime as follows:

highest 16 bits				lowest 16 bits
feature 1	feature 2	...	feature 16	NAPI_VERSION (latest released, i.e. 8, 9, 10, etc.)
or
NAPI_VERSION_EXPERIMENTAL (2147483647) All experimental features are requested

This value ends up on napi_env. At runtime we can check against the bits of this value to decide on the code path. We should probably create a family of macros for making decisions based on the feature flags.

At our Node-API meeting we concluded that we should introduce behaviour-changing features extremely sparingly, because, in order to ensure we do not break our users, even those that have opted into NAPI_EXPERIMENTAL, the testing complexity doubles with each feature we introduce.

[gabrielschulhof]

@nodejs/node-api

[KevinEady]

Hi @gabrielschulhof ,

Just wanted a clarification with an example. Say we add a new Node-API, node_api_x(). Since this is not a behavior change, we would continue with our current flow (ie. guard declaration via #ifdef NAPI_EXPERIMENTAL, then update to #if NAPI_VERSION >= x on stable release, etc etc following https://github.com/nodejs/node/blob/main/doc/contributing/adding-new-napi-api.md), correct?

[gabrielschulhof]

@KevinEady that's a good question. I think we would still add a feature flag, so we'd know the feature was available, though not an opt-out flag. I think assembling the version to report would be encoded using a series of macro calls starting with NAPI_VERSION and adding each successive feature bit. Thus we could, for non-behaviour-changing features, avoid updating this series of macro calls with a call to setting the feature bit for the non-behaviour-changing feature. That way, a feature bit would not be reserved for the feature, since it's not needed at runtime anyway.

[github-actions]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the never-stale Mark issue so that it is never considered stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment.
For more information on how the project manages feature requests, please consult the feature request management document.