Node.js gRPC Library

As of April 2021 this library is deprecated and will no longer receive any updates. We recommend using @grpc/grpc-js instead.

PREREQUISITES

• node: This requires node to be installed, version 4.0 or above. If you instead have the nodejs executable on Debian, you should install the nodejs-legacy package.

• Note: If you installed node via a package manager and the version is still less than 4.0, try directly installing it from nodejs.org.

LATEST VERSIONS SUPPORTED

• Node: 14
• Electron: 11.2

INSTALLATION

Install the gRPC NPM package

npm install grpc

BUILD FROM SOURCE

The following command can be used to build from source when installing the package from npm:

npm install grpc --build-from-source

The --build-from-source option will work even when installing another package that depends on grpc. To build only grpc from source, you can use the argument --build-from-source=grpc.

ABOUT ELECTRON

The official electron documentation recommends to build all of your native packages from source. While the reasons behind this are technically good - many native extensions won't be packaged to work properly with electron - the gRPC source code is fairly difficult to build from source due to its complex nature, and we're also providing working electron pre-built binaries. Therefore, we recommend that you do not follow this model for using gRPC with electron. Also, for the same reason, electron-rebuild will always build from source. We advise you to not use this tool if you are depending on gRPC. Please note that there's not just one way to get native extensions running in electron, and that there's never any silver bullet for anything. The following instructions try to cater about some of the most generic ways, but different edge cases might require different methodologies.

The best way to get gRPC to work with electron is to do this, possibly in the postinstall script of your package.json file:

npm rebuild --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron

Note that the 2.0.0 above is the electron runtime version number. You will need to update this every time you go on a different version of the runtime.

If you have more native dependencies than gRPC, and they work better when built from source, you can explicitely specify which extension to build the following way:

npm rebuild --build-from-source=sqlite3 --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron

This way, if you depend on both grpc and sqlite3, only the sqlite3 package will be rebuilt from source, leaving the grpc package to use its precompiled binaries.

BUILD IN GIT REPOSITORY

1. Clone the grpc-node Git Repository.
2. Run git submodule update --init --recursive from the repository root.
3. Run cd packages/grpc-native-core.

4. Run npm install --build-from-source.

5. Note: On Windows, this might fail due to nodejs issue #4932 in which case, you will see something like the following in npm install's output (towards the very beginning):

     ..
     Building the projects in this solution one at a time. To enable parallel build, please add the "/m" switch.
     WINDOWS_BUILD_WARNING
      "..\IMPORTANT: Due to https:\github.com\nodejs\node\issues\4932, to build this library on Windows, you must first remove C:\Users\jenkins\.node-gyp\4.4.0\include\node\openssl"
      ...
      ..

   To fix this, you will have to delete the folder C:\Users\<username>\.node-gyp\<node_version>\include\node\openssl and retry npm install

CONFIGURE BINARIES' LOCATION

You can configure the location from which the pre-compiled binaries are downloaded during installation.

npm install --grpc_node_binary_host_mirror=https://your-url.com

Or defining grpc_node_binary_host_mirror in your .npmrc.

API DOCUMENTATION

See the API Documentation.

TESTING

To run the test suite, simply run npm test in the install location.

Changes for 1.7.0:

• New feature: death tests are supported on OpenBSD and in iOS simulator now.
• New feature: Google Test now implements a protocol to allow a test runner to detect that a test program has exited prematurely and report it as a failure (before it would be falsely reported as a success if the exit code is 0).
• New feature: Test::RecordProperty() can now be used outside of the lifespan of a test method, in which case it will be attributed to the current test case or the test program in the XML report.
• New feature (potentially breaking): --gtest_list_tests now prints the type parameters and value parameters for each test.
• Improvement: char pointers and char arrays are now escaped properly in failure messages.
• Improvement: failure summary in XML reports now includes file and line information.
• Improvement: the <testsuites> XML element now has a timestamp attribute.
• Improvement: When --gtest_filter is specified, XML report now doesn't contain information about tests that are filtered out.
• Fixed the bug where long --gtest_filter flag values are truncated in death tests.
• Potentially breaking change: RUN_ALL_TESTS() is now implemented as a function instead of a macro in order to work better with Clang.
• Compatibility fixes with C++ 11 and various platforms.
• Bug/warning fixes.

Changes for 1.6.0:

• New feature: ADD_FAILURE_AT() for reporting a test failure at the given source location -- useful for writing testing utilities.
• New feature: the universal value printer is moved from Google Mock to Google Test.
• New feature: type parameters and value parameters are reported in the XML report now.
• A gtest_disable_pthreads CMake option.
• Colored output works in GNU Screen sessions now.
• Parameters of value-parameterized tests are now printed in the textual output.
• Failures from ad hoc test assertions run before RUN_ALL_TESTS() are now correctly reported.
• Arguments of ASSERT_XY and EXPECT_XY no longer need to support << to ostream.
• More complete handling of exceptions.
• GTEST_ASSERT_XY can be used instead of ASSERT_XY in case the latter name is already used by another library.
• --gtest_catch_exceptions is now true by default, allowing a test program to continue after an exception is thrown.
• Value-parameterized test fixtures can now derive from Test and WithParamInterface<T> separately, easing conversion of legacy tests.
• Death test messages are clearly marked to make them more distinguishable from other messages.
• Compatibility fixes for Android, Google Native Client, MinGW, HP UX, PowerPC, Lucid autotools, libCStd, Sun C++, Borland C++ Builder (Code Gear), IBM XL C++ (Visual Age C++), and C++0x.
• Bug fixes and implementation clean-ups.
• Potentially incompatible changes: disables the harmful 'make install' command in autotools.

Changes for 1.5.0:

• New feature: assertions can be safely called in multiple threads where the pthreads library is available.
• New feature: predicates used inside EXPECT_TRUE() and friends can now generate custom failure messages.
• New feature: Google Test can now be compiled as a DLL.
• New feature: fused source files are included.
• New feature: prints help when encountering unrecognized Google Test flags.
• Experimental feature: CMake build script (requires CMake 2.6.4+).
• Experimental feature: the Pump script for meta programming.
• double values streamed to an assertion are printed with enough precision to differentiate any two different values.
• Google Test now works on Solaris and AIX.
• Build and test script improvements.

• Bug fixes and implementation clean-ups.

  Potentially breaking changes:

• Stopped supporting VC++ 7.1 with exceptions disabled.

• Dropped support for 'make install'.

Changes for 1.4.0:

• New feature: the event listener API
• New feature: test shuffling
• New feature: the XML report format is closer to junitreport and can be parsed by Hudson now.
• New feature: when a test runs under Visual Studio, its failures are integrated in the IDE.
• New feature: /MD(d) versions of VC++ projects.
• New feature: elapsed time for the tests is printed by default.
• New feature: comes with a TR1 tuple implementation such that Boost is no longer needed for Combine().
• New feature: EXPECT_DEATH_IF_SUPPORTED macro and friends.
• New feature: the Xcode project can now produce static gtest libraries in addition to a framework.
• Compatibility fixes for Solaris, Cygwin, minGW, Windows Mobile, Symbian, gcc, and C++Builder.
• Bug fixes and implementation clean-ups.

Changes for 1.3.0:

• New feature: death tests on Windows, Cygwin, and Mac.
• New feature: ability to use Google Test assertions in other testing frameworks.
• New feature: ability to run disabled test via --gtest_also_run_disabled_tests.
• New feature: the --help flag for printing the usage.
• New feature: access to Google Test flag values in user code.
• New feature: a script that packs Google Test into one .h and one .cc file for easy deployment.
• New feature: support for distributing test functions to multiple machines (requires support from the test runner).
• Bug fixes and implementation clean-ups.

Changes for 1.2.1:

• Compatibility fixes for Linux IA-64 and IBM z/OS.
• Added support for using Boost and other TR1 implementations.
• Changes to the build scripts to support upcoming release of Google C++ Mocking Framework.
• Added Makefile to the distribution package.
• Improved build instructions in README.

Changes for 1.2.0:

• New feature: value-parameterized tests.
• New feature: the ASSERT/EXPECT_(NON)FATAL_FAILURE(ONALL_THREADS) macros.
• Changed the XML report format to match JUnit/Ant's.
• Added tests to the Xcode project.
• Added scons/SConscript for building with SCons.
• Added src/gtest-all.cc for building Google Test from a single file.
• Fixed compatibility with Solaris and z/OS.
• Enabled running Python tests on systems with python 2.3 installed, e.g. Mac OS X 10.4.
• Bug fixes.

Changes for 1.1.0:

• New feature: type-parameterized tests.
• New feature: exception assertions.
• New feature: printing elapsed time of tests.
• Improved the robustness of death tests.
• Added an Xcode project and samples.
• Adjusted the output format on Windows to be understandable by Visual Studio.
• Minor bug fixes.

Changes for 1.0.1:

• Added project files for Visual Studio 7.1.
• Fixed issues with compiling on Mac OS X.
• Fixed issues with compiling on Cygwin.

Changes for 1.0.0:

• Initial Open Source release of Google Test