{"id":11397,"library":"nice-grpc-server-reflection","title":"nice-grpc Server Reflection","description":"nice-grpc-server-reflection is a package within the nice-grpc ecosystem that provides gRPC server reflection capabilities for Node.js servers built with nice-grpc. Currently at version 3.0.4, it enables external gRPC tools like `grpcurl`, Postman, or client libraries to dynamically discover and introspect the server's exposed services, methods, and their protobuf message definitions at runtime without requiring pre-compiled `.proto` files on the client side. The library integrates seamlessly with the `nice-grpc` server, accepting a pre-generated protobuf descriptor set (.bin file) and a list of fully-qualified service names. As part of the actively maintained `nice-grpc` monorepo, it receives frequent updates, leveraging nice-grpc's TypeScript-first design, modern Promises/Async Iterables API, and robust middleware support. Its primary differentiator is its tight integration and idiomatic usage within the `nice-grpc` framework, providing a clear path for enabling standard gRPC reflection in TypeScript-based Node.js gRPC services.","status":"active","version":"3.0.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","grpc","nice-grpc","server-reflection","typescript"],"install":[{"cmd":"npm install nice-grpc-server-reflection","lang":"bash","label":"npm"},{"cmd":"yarn add nice-grpc-server-reflection","lang":"bash","label":"yarn"},{"cmd":"pnpm add nice-grpc-server-reflection","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core gRPC server library that this reflection package extends.","package":"nice-grpc","optional":false}],"imports":[{"note":"This is the gRPC service definition for reflection, typically added directly to the nice-grpc server. ESM is preferred since nice-grpc v3.","wrong":"const { ServerReflectionService } = require('nice-grpc-server-reflection')","symbol":"ServerReflectionService","correct":"import { ServerReflectionService } from 'nice-grpc-server-reflection'"},{"note":"This is a factory function that constructs the reflection service implementation, requiring a descriptor set buffer and service names. It is a named export.","wrong":"import ServerReflection from 'nice-grpc-server-reflection'","symbol":"ServerReflection","correct":"import { ServerReflection } from 'nice-grpc-server-reflection'"},{"note":"While not from nice-grpc-server-reflection directly, this is the core server class from nice-grpc to which the reflection service is added.","symbol":"GrpcServer","correct":"import { Server as GrpcServer } from 'nice-grpc'"}],"quickstart":{"code":"import { Server as GrpcServer, ServiceDefinition, UntypedServiceImplementation } from 'nice-grpc';\nimport { ServerReflectionService, ServerReflection } from 'nice-grpc-server-reflection';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\n// 1. Define your .proto file (e.g., proto/greeting.proto):\n//    syntax = \"proto3\";\n//    package greeting;\n//    service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {} }\n//    message HelloRequest { string name = 1; }\n//    message HelloReply { string message = 1; }\n\n// 2. Generate the descriptor set using protoc:\n//    `protoc --descriptor_set_out=./proto/bundle.bin --include_imports -I./proto ./proto/greeting.proto`\n\n// 3. Define your gRPC service implementation\nconst greeterService: ServiceDefinition & UntypedServiceImplementation = {\n  path: '/greeting.Greeter/SayHello',\n  requestStream: false,\n  responseStream: false,\n  requestType: {} as any, // In a real app, these would be generated types\n  responseType: {} as any, // In a real app, these would be generated types\n  async handler(request: { name: string }) {\n    return { message: `Hello, ${request.name}!` };\n  }\n};\n\nconst main = async () => {\n  const server = new GrpcServer();\n\n  // Load the generated protobuf descriptor set\n  const protoset = fs.readFileSync(path.join(__dirname, '../proto/bundle.bin'));\n\n  // Add your application service\n  server.add('greeting.Greeter', greeterService);\n\n  // Add the server reflection service\n  // Pass the protoset and a list of fully-qualified service names to expose\n  server.add(\n    ServerReflectionService,\n    ServerReflection(\n      protoset,\n      ['greeting.Greeter']\n    )\n  );\n\n  const port = 50051;\n  await server.listen(`0.0.0.0:${port}`);\n  console.log(`nice-grpc server with reflection listening on port ${port}`);\n\n  // You can now use grpcurl to inspect and call services:\n  // `grpcurl -plaintext localhost:50051 list`\n  // `grpcurl -plaintext localhost:50051 describe greeting.Greeter`\n  // `grpcurl -plaintext -d '{\"name\": \"World\"}' localhost:50051 greeting.Greeter/SayHello`\n};\n\nmain().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates how to set up a nice-grpc server, define a simple gRPC service, generate a protobuf descriptor set, and enable the gRPC Server Reflection service. It includes the necessary `protoc` command to create the `.bin` file and shows how to integrate it with `nice-grpc`, allowing tools like `grpcurl` to inspect the running server's API."},"warnings":[{"fix":"Ensure `nice-grpc`, `@grpc/grpc-js`, and `nice-grpc-server-reflection` are updated to compatible versions, ideally the latest stable releases. If using `ts-proto`, verify your `ts_proto_opt` settings include `outputServices=nice-grpc` and other recommended options for consistency. Review GitHub issues on the `nice-grpc` monorepo (e.g., #611) for specific version conflicts.","message":"Type compatibility issues can arise between nice-grpc-server-reflection's IServerReflectionService and nice-grpc's expected ServiceDefinition (or CompatServiceDefinition) when using specific TypeScript versions, gRPC-js versions, or certain protobuf code generation configurations (e.g., older ts-proto options). This typically manifests as a TypeScript compilation error.","severity":"breaking","affected_versions":">=2.0.7"},{"fix":"Always use `protoc --descriptor_set_out=path/to/output.bin --include_imports -I./proto_dir your_service.proto` ensuring `proto_dir` contains all imported `.proto` files.","message":"Generating the protobuf descriptor set (`.bin` file) requires specific `protoc` flags. Incorrectly generating this file, such as omitting `--descriptor_set_out` or `--include_imports`, or failing to include all relevant `.proto` files, will lead to the reflection service not being able to expose correct API information or failing to load entirely.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Limit exposure of the reflection service to internal networks, development environments, or authorized clients only. Use appropriate network segmentation, firewalls, or authentication mechanisms to control access.","message":"Exposing the gRPC reflection service on publicly accessible endpoints can be a security concern, as it allows anyone to discover the full API surface, including all services, methods, and message structures. This is analogous to exposing an OpenAPI document for a REST API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check that the string array provided to `ServerReflection` contains the exact fully-qualified service names as defined in your protobuf schemas. For example, `package my.app; service MyService {}` would be `['my.app.MyService']`.","message":"The list of fully-qualified service names passed to the `ServerReflection` constructor must precisely match the package and service names defined in your `.proto` files (e.g., 'your.package.YourService'). Mismatches will result in those services not being discoverable via reflection.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update `nice-grpc` and `nice-grpc-server-reflection` to compatible versions. If `ts-proto` is used, ensure `outputServices=nice-grpc,outputServices=generic-definitions` and `esModuleInterop=true` are configured during proto generation.","cause":"Type incompatibility between `nice-grpc-server-reflection`'s service definition and the `nice-grpc` server's expected service definition, often due to differing versions of `nice-grpc`, `@grpc/grpc-js`, or specific `ts-proto` generation configurations.","error":"Argument of type 'IServerReflectionService' is not assignable to parameter of type 'CompatServiceDefinition'."},{"fix":"Verify the `protoc` command used to generate `protoset.bin` includes `--descriptor_set_out=path/to/protoset.bin` and crucially, `--include_imports`. Ensure all `.proto` files, including any imported dependencies, are correctly passed to `protoc` in the compilation step.","cause":"The provided `protoset.bin` file is either corrupted, incomplete, or incorrectly generated, often missing definitions for types referenced within the reflected services.","error":"Could not load server reflection. Details: no such Type or Enum '...' in Type '...'"},{"fix":"Review your `protoc` command. Ensure `-I` flags point to the root directories where your `.proto` files reside without overlap, and avoid listing the same `.proto` file multiple times as input. Use a consistent directory structure for your protos.","cause":"This error typically occurs during protobuf descriptor set generation when the `protoc` compiler encounters the same `.proto` file (or one it imports) multiple times, often due to overlapping `I` (include) paths or duplicate file arguments.","error":"proto: file appears multiple times: \"path/to/some_file.proto\" running at ..."}],"ecosystem":"npm"}