node-api: minimal C node_embedding_api function

Co-authored-by: vmoroz <vmorozov@microsoft.com>

Author: alshdavid

doc/api/embedding.md

@@ -172,3 +172,219 @@ int RunNodeInstance(MultiIsolatePlatform* platform,
 [deprecation policy]: deprecations.md
 [embedtest.cc]: https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc
 [src/node.h]: https://github.com/nodejs/node/blob/HEAD/src/node.h
+# C++ embedder API
+
+<!--introduced_in=v12.19.0-->
+
+Node.js provides a number of C++ APIs that can be used to execute JavaScript
+in a Node.js environment from other C++ software.
+
+The documentation for these APIs can be found in [src/node.h][] in the Node.js
+source tree. In addition to the APIs exposed by Node.js, some required concepts
+are provided by the V8 embedder API.
+
+Because using Node.js as an embedded library is different from writing code
+that is executed by Node.js, breaking changes do not follow typical Node.js
+[deprecation policy][] and may occur on each semver-major release without prior
+warning.
+
+## Example embedding application
+
+The following sections will provide an overview over how to use these APIs
+to create an application from scratch that will perform the equivalent of
+`node -e <code>`, i.e. that will take a piece of JavaScript and run it in
+a Node.js-specific environment.
+
+The full code can be found [in the Node.js source tree][embedtest.cc].
+
+### Setting up a per-process state
+
+Node.js requires some per-process state management in order to run:
+
+* Arguments parsing for Node.js [CLI options][],
+* V8 per-process requirements, such as a `v8::Platform` instance.
+
+The following example shows how these can be set up. Some class names are from
+the `node` and `v8` C++ namespaces, respectively.
+
+```cpp
+int main(int argc, char** argv) {
+  argv = uv_setup_args(argc, argv);
+  std::vector<std::string> args(argv, argv + argc);
+  // Parse Node.js CLI options, and print any errors that have occurred while
+  // trying to parse them.
+  std::unique_ptr<node::InitializationResult> result =
+      node::InitializeOncePerProcess(args, {
+        node::ProcessInitializationFlags::kNoInitializeV8,
+        node::ProcessInitializationFlags::kNoInitializeNodeV8Platform
+      });
+
+  for (const std::string& error : result->errors())
+    fprintf(stderr, "%s: %s\n", args[0].c_str(), error.c_str());
+  if (result->early_return() != 0) {
+    return result->exit_code();
+  }
+
+  // Create a v8::Platform instance. `MultiIsolatePlatform::Create()` is a way
+  // to create a v8::Platform instance that Node.js can use when creating
+  // Worker threads. When no `MultiIsolatePlatform` instance is present,
+  // Worker threads are disabled.
+  std::unique_ptr<MultiIsolatePlatform> platform =
+      MultiIsolatePlatform::Create(4);
+  V8::InitializePlatform(platform.get());
+  V8::Initialize();
+
+  // See below for the contents of this function.
+  int ret = RunNodeInstance(
+      platform.get(), result->args(), result->exec_args());
+
+  V8::Dispose();
+  V8::DisposePlatform();
+
+  node::TearDownOncePerProcess();
+  return ret;
+}
+```
+
+### Setting up a per-instance state
+
+<!-- YAML
+changes:
+  - version: v15.0.0
+    pr-url: https://github.com/nodejs/node/pull/35597
+    description:
+      The `CommonEnvironmentSetup` and `SpinEventLoop` utilities were added.
+-->
+
+Node.js has a concept of a “Node.js instance”, that is commonly being referred
+to as `node::Environment`. Each `node::Environment` is associated with:
+
+* Exactly one `v8::Isolate`, i.e. one JS Engine instance,
+* Exactly one `uv_loop_t`, i.e. one event loop,
+* A number of `v8::Context`s, but exactly one main `v8::Context`, and
+* One `node::IsolateData` instance that contains information that could be
+  shared by multiple `node::Environment`s. The embedder should make sure
+  that `node::IsolateData` is shared only among `node::Environment`s that
+  use the same `v8::Isolate`, Node.js does not perform this check.
+
+In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
+to be provided. One possible choice is the default Node.js allocator, which
+can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js
+allocator allows minor performance optimizations when addons use the Node.js
+C++ `Buffer` API, and is required in order to track `ArrayBuffer` memory in
+[`process.memoryUsage()`][].
+
+Additionally, each `v8::Isolate` that is used for a Node.js instance needs to
+be registered and unregistered with the `MultiIsolatePlatform` instance, if one
+is being used, in order for the platform to know which event loop to use
+for tasks scheduled by the `v8::Isolate`.
+
+The `node::NewIsolate()` helper function creates a `v8::Isolate`,
+sets it up with some Node.js-specific hooks (e.g. the Node.js error handler),
+and registers it with the platform automatically.
+
+```cpp
+int RunNodeInstance(MultiIsolatePlatform* platform,
+                    const std::vector<std::string>& args,
+                    const std::vector<std::string>& exec_args) {
+  int exit_code = 0;
+
+  // Setup up a libuv event loop, v8::Isolate, and Node.js Environment.
+  std::vector<std::string> errors;
+  std::unique_ptr<CommonEnvironmentSetup> setup =
+      CommonEnvironmentSetup::Create(platform, &errors, args, exec_args);
+  if (!setup) {
+    for (const std::string& err : errors)
+      fprintf(stderr, "%s: %s\n", args[0].c_str(), err.c_str());
+    return 1;
+  }
+
+  Isolate* isolate = setup->isolate();
+  Environment* env = setup->env();
+
+  {
+    Locker locker(isolate);
+    Isolate::Scope isolate_scope(isolate);
+    HandleScope handle_scope(isolate);
+    // The v8::Context needs to be entered when node::CreateEnvironment() and
+    // node::LoadEnvironment() are being called.
+    Context::Scope context_scope(setup->context());
+
+    // Set up the Node.js instance for execution, and run code inside of it.
+    // There is also a variant that takes a callback and provides it with
+    // the `require` and `process` objects, so that it can manually compile
+    // and run scripts as needed.
+    // The `require` function inside this script does *not* access the file
+    // system, and can only load built-in Node.js modules.
+    // `module.createRequire()` is being used to create one that is able to
+    // load files from the disk, and uses the standard CommonJS file loader
+    // instead of the internal-only `require` function.
+    MaybeLocal<Value> loadenv_ret = node::LoadEnvironment(
+        env,
+        "const publicRequire ="
+        "  require('node:module').createRequire(process.cwd() + '/');"
+        "globalThis.require = publicRequire;"
+        "require('node:vm').runInThisContext(process.argv[1]);");
+
+    if (loadenv_ret.IsEmpty())  // There has been a JS exception.
+      return 1;
+
+    exit_code = node::SpinEventLoop(env).FromMaybe(1);
+
+    // node::Stop() can be used to explicitly stop the event loop and keep
+    // further JavaScript from running. It can be called from any thread,
+    // and will act like worker.terminate() if called from another thread.
+    node::Stop(env);
+  }
+
+  return exit_code;
+}
+```
+
+## C runtime API
+
+<!--introduced_in=REPLACEME-->
+
+While Node.js provides an extensive C++ embedding API that can be used from C++
+applications, the C-based API is useful when Node.js is embedded as a shared
+libnode library into C++ or non-C++ applications.
+
+### API design overview
+
+One of the goals for the C based runtime API is to be ABI stable. It means that
+applications must be able to use newer libnode versions without recompilation.
+The following design principles are targeting to achieve that goal.
+
+* Follow the best practices for the [node-api][] design and build on top of
+  the [node-api][].
+
+### API reference
+
+#### Functions
+
+##### `node_embed_start`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Runs Node.js runtime instance the same way as the Node.js executable.
+
+```c
+int32_t NAPI_CDECL node_embed_start(
+  int32_t argc,
+  char* argv[]);
+```
+
+* `[in] argc`: Number of items in the `argv` array.
+* `[in] argv`: CLI arguments as an array of zero terminated strings.
+  Returns `int32_t` with runtime instance exit code.
+
+[CLI options]: cli.md
+[`process.memoryUsage()`]: process.md#processmemoryusage
+[deprecation policy]: deprecations.md
+[embedtest.cc]: https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc
+[node-api]: n-api.md
+[src/node.h]: https://github.com/nodejs/node/blob/HEAD/src/node.h

node.gyp

@@ -121,6 +121,7 @@
       'src/node_debug.cc',
       'src/node_dir.cc',
       'src/node_dotenv.cc',
+      'src/node_embed_api.cc',
       'src/node_env_var.cc',
       'src/node_errors.cc',
       'src/node_external_reference.cc',
@@ -241,6 +242,7 @@
       'src/module_wrap.h',
       'src/node.h',
       'src/node_api.h',
+      'src/node_api_internals.h',
       'src/node_api_types.h',
       'src/node_binding.h',
       'src/node_blob.h',
@@ -253,6 +255,7 @@
       'src/node_debug.h',
       'src/node_dir.h',
       'src/node_dotenv.h',
+      'src/node_embed_api.h',
       'src/node_errors.h',
       'src/node_exit_code.h',
       'src/node_external_reference.h',
@@ -895,6 +898,7 @@
         '<(SHARED_INTERMEDIATE_DIR)' # for node_natives.h
       ],
       'dependencies': [
+        'tools/v8_gypfiles/abseil.gyp:abseil',
         'node_js2c#host',
       ],
 
@@ -955,9 +959,6 @@
             'src/node_snapshot_stub.cc',
           ]
         }],
-        [ 'node_use_bundled_v8!="false"', {
-          'dependencies': [ 'tools/v8_gypfiles/abseil.gyp:abseil' ],
-        }],
         [ 'node_shared_gtest=="false"', {
           'dependencies': [
             'deps/googletest/googletest.gyp:gtest_prod',
@@ -1278,6 +1279,7 @@
 
       'dependencies': [
         '<(node_lib_target_name)',
+        'tools/v8_gypfiles/abseil.gyp:abseil',
       ],
 
       'includes': [
@@ -1311,9 +1313,6 @@
         [ 'node_shared_gtest=="true"', {
           'libraries': [ '-lgtest_main' ],
         }],
-        [ 'node_use_bundled_v8!="false"', {
-          'dependencies': [ 'tools/v8_gypfiles/abseil.gyp:abseil' ],
-        }],
         [ 'node_shared_hdr_histogram=="false"', {
           'dependencies': [
             'deps/histogram/histogram.gyp:histogram',
@@ -1410,6 +1409,8 @@
       'sources': [
         'src/node_snapshot_stub.cc',
         'test/embedding/embedtest.cc',
+        'test/embedding/embedtest_c_api_main.c',
+        'test/embedding/embedtest_main.cc',
       ],
 
       'conditions': [
@@ -1552,7 +1553,7 @@
         [ 'OS=="mac"', {
           'libraries': [ '-framework CoreFoundation -framework Security' ],
         }],
-        [ 'node_shared_simdutf=="false" and node_use_bundled_v8!="false"', {
+        [ 'node_shared_simdutf=="false"', {
           'dependencies': [ 'tools/v8_gypfiles/v8.gyp:simdutf#host' ],
         }],
         [ 'node_shared_libuv=="false"', {

src/node_embed_api.cc

@@ -0,0 +1,25 @@
+//
+// Description: C-based API for embedding Node.js.
+//
+// !!! WARNING !!! WARNING !!! WARNING !!!
+// This is a new API and is subject to change.
+// While it is C-based, it is not ABI safe yet.
+// Consider all functions and data structures as experimental.
+// !!! WARNING !!! WARNING !!! WARNING !!!
+//
+// This file contains the C-based API for embedding Node.js in a host
+// application. The API is designed to be used by applications that want to
+// embed Node.js as a shared library (.so or .dll) and can interop with
+// C-based API.
+//
+
+#include "node_embed_api.h"
+#include "node.h"
+
+EXTERN_C_START
+
+int32_t NAPI_CDECL node_embed_start(int32_t argc, char* argv[]) {
+  return node::Start(argc, argv);
+}
+
+EXTERN_C_END

src/node_embed_api.h

@@ -0,0 +1,28 @@
+//
+// Description: C-based API for embedding Node.js.
+//
+// !!! WARNING !!! WARNING !!! WARNING !!!
+// This is a new API and is subject to change.
+// While it is C-based, it is not ABI safe yet.
+// Consider all functions and data structures as experimental.
+// !!! WARNING !!! WARNING !!! WARNING !!!
+//
+// This file contains the C-based API for embedding Node.js in a host
+// application. The API is designed to be used by applications that want to
+// embed Node.js as a shared library (.so or .dll) and can interop with
+// C-based API.
+//
+
+#ifndef SRC_NODE_EMBED_API_H_
+#define SRC_NODE_EMBED_API_H_
+
+#include "node_api.h"
+
+EXTERN_C_START
+
+// Runs Node.js start function. It is the same as running Node.js from CLI.
+NAPI_EXTERN int32_t NAPI_CDECL node_embed_start(int32_t argc, char* argv[]);
+
+EXTERN_C_END
+
+#endif  // SRC_NODE_EMBED_API_H_

test/embedding/embedtest.cc

@@ -3,8 +3,8 @@
 #endif
 #include <assert.h>
 #include "cppgc/platform.h"
-#include "executable_wrapper.h"
 #include "node.h"
+#include "uv.h"
 
 #include <algorithm>
 
@@ -28,10 +28,7 @@ static int RunNodeInstance(MultiIsolatePlatform* platform,
                            const std::vector<std::string>& args,
                            const std::vector<std::string>& exec_args);
 
-NODE_MAIN(int argc, node::argv_type raw_argv[]) {
-  char** argv = nullptr;
-  node::FixupMain(argc, raw_argv, &argv);
-
+int32_t test_main_cpp_api(int32_t argc, char* argv[]) {
   std::vector<std::string> args(argv, argv + argc);
   std::shared_ptr<node::InitializationResult> result =
       node::InitializeOncePerProcess(

test/embedding/embedtest_c_api_main.c

@@ -0,0 +1,8 @@
+#include "node_embed_api.h"
+
+// The simplest Node.js embedding scenario where the Node.js start function is
+// invoked from the libnode shared library as it would be run from the Node.js
+// CLI.
+int32_t test_main_c_api_nodejs_main(int32_t argc, char* argv[]) {
+  return node_embed_start(argc, argv);
+}