Registry / http-networking / grpc-node-server-reflection

grpc-node-server-reflection

library1.0.2jsnpmunverified

This package provides an implementation of gRPC Server Reflection for Node.js applications, specifically designed to work with the `@grpc/grpc-js` library. It enables gRPC clients, such as `grpccurl` or `Postman`, to dynamically discover the services, methods, and message types exposed by a gRPC server at runtime, without needing pre-compiled `.proto` files on the client side. The current stable version is 1.0.2. As a utility library, its release cadence is primarily driven by updates to its core dependency, `@grpc/grpc-js`, or bug fixes, rather than a fixed schedule. Its key differentiator is its straightforward integration method, requiring only a single function call to wrap an existing `@grpc/grpc-js` server instance, thereby abstracting the complex details of implementing the `grpc.reflection.v1alpha.ServerReflection` service manually. Currently, it fully supports `ListServices` and `FileContainingSymbol` requests but explicitly notes that `FileByFilename` and `FileContainingExtension` requests are not yet implemented.

http-networking

npm install grpc-node-server-reflection

github ↗package ↗

INSTALL

IMPORT

SIG · GRPC-NODE-SERVER-R

grpc-node-server-reflection

http-networkingjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

wrapServerWithReflection

✓ import wrapServerWithReflection from 'grpc-node-server-reflection';

✗ import { wrapServerWithReflection } from 'grpc-node-server-reflection';

The `wrapServerWithReflection` function is exported as a default export. Ensure you import it without curly braces. For CommonJS, `const wrapServerWithReflection = require('grpc-node-server-reflection');` is the correct pattern, not `require().wrapServerWithReflection`.

Demonstrates how to integrate server reflection into an existing `@grpc/grpc-js` server instance, ensuring services are discoverable via tools like `grpcurl`.

import * as grpc from '@grpc/grpc-js'; import wrapServerWithReflection from 'grpc-node-server-reflection'; // A minimal example service for demonstration const exampleServiceDefinition = { ExampleService: { sayHello: { path: '/example.ExampleService/SayHello', requestStream: false, responseStream: false, requestType: { deserializeBinary: () => ({ name: '' }) }, responseType: { serializeBinary: () => Buffer.from('') } } } }; const exampleServiceImplementation = { sayHello: (call, callback) => { callback(null, { message: `Hello, ${call.request.name || 'Guest'}!` }); } }; function main() { const server = new grpc.Server(); // IMPORTANT: Wrap the server with reflection *before* adding any services. const reflectedServer = wrapServerWithReflection(server); reflectedServer.addService(exampleServiceDefinition.ExampleService, exampleServiceImplementation); reflectedServer.bindAsync( '0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), (err, port) => { if (err) { console.error(`Server bind failed: ${err}`); return; } reflectedServer.start(); console.log(`Server running at http://0.0.0.0:${port}`); console.log('Try: grpcurl -plaintext localhost:50051 list'); console.log('Or: grpcurl -plaintext localhost:50051 describe example.ExampleService'); } ); } main();

Debug

Known issues

breakingApplication services added to the gRPC server *before* calling `wrapServerWithReflection` will not be correctly registered or discoverable via the reflection service. The wrapper intercepts `addService` calls.

fix

Always ensure you call `wrapServerWithReflection(yourServerInstance)` on your `grpc.Server` instance *before* adding any application-specific services using `yourServerInstance.addService(...)`.

affects: >=1.0.0

gotchaThe library explicitly states that `FileByFilename` and `FileContainingExtension` reflection request types are not supported. Attempting to use these specific reflection queries will result in an error or unexpected behavior.

fix

Clients should avoid sending `FileByFilename` or `FileContainingExtension` requests. Consult the package documentation for the supported reflection request types (`ListServices`, `FileContainingSymbol`).

affects: >=1.0.0

Errors

Common errors & fixes

grpcurl: rpc error: code = Unimplemented desc = Unknown method

The gRPC server reflection service itself has not been correctly added to the server, or the server is not running/accessible.

fix

Verify that `wrapServerWithReflection` has been successfully called on your `grpc.Server` instance. Also, confirm that your gRPC server is properly started and listening on the expected port.

grpcurl: rpc error: code = Internal desc = Reflection service could not find symbol: [your_service_name]

Your application's gRPC services were added to the server instance *before* `wrapServerWithReflection` was called. The reflection wrapper needs to intercept `addService` calls to track them.

fix

Reorder your server initialization. Call `wrapServerWithReflection(server)` first, then use the returned (wrapped) server object (`reflectedServer.addService(...)`) to register your application's services.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredRequired runtime dependency for gRPC server functionality.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/papajuanito/grpc-node-server-reflection ↗

packagehttps://www.npmjs.com/package/grpc-node-server-reflection ↗