grpc-descriptor-reflection

A gRPC server reflection service for @grpc/grpc-js that serves raw FileDescriptorProto bytes from a pre-built descriptor set, preserving all extensions and custom options byte-for-byte.

Why?

Existing reflection libraries for Node.js gRPC lose extension fields during serialization:

• @grpc/reflection decodes descriptors through protobufjs and re-encodes them. protobufjs silently drops all extension fields (google.api.http, openapiv2_operation, custom options, etc.) because they are not declared fields on the standard option message types.

• grpc-server-reflection uses google-protobuf which performs a similar decode/re-encode round-trip, with no guarantee of byte-for-byte fidelity.

This means any downstream consumer relying on reflection (API gateways, documentation generators, gRPC-to-HTTP transcoders) will see methods without HTTP bindings, missing OpenAPI annotations, or stripped custom options.

grpc-descriptor-reflection solves this by:

1. Parsing the FileDescriptorSet wire format directly to extract each FileDescriptorProto as a raw byte slice
2. Using @bufbuild/protobuf only for indexing (building symbol and dependency lookups)
3. Serving the original raw bytes to reflection clients without any re-encoding

The result is byte-for-byte identical output to what buf build or protoc produced.

Installation

npm install grpc-descriptor-reflection

Peer dependencies (you likely already have these):

npm install @grpc/grpc-js @grpc/proto-loader

Generating a Descriptor Set

You need a binary FileDescriptorSet file. Generate one with either buf or protoc:

With buf (recommended)

buf build -o descriptor.bin --as-file-descriptor-set

With protoc

protoc \
  --descriptor_set_out=descriptor.bin \
  --include_imports \
  -I ./proto \
  ./proto/**/*.proto

Important: Use --include_imports (protoc) or the default behavior of buf build to include all transitive dependencies. The reflection service needs the full dependency graph to serve complete responses.

Usage

With vanilla @grpc/grpc-js

import * as grpc from "@grpc/grpc-js";
import { DescriptorReflectionService } from "grpc-descriptor-reflection";

const server = new grpc.Server();

// Add your application services...
// server.addService(MyService, myImplementation);

// Add reflection (registers both v1 and v1alpha endpoints)
const reflection = new DescriptorReflectionService("path/to/descriptor.bin");
reflection.addToServer(server);

server.bindAsync("0.0.0.0:50051", grpc.ServerCredentials.createInsecure(), () => {
  console.log("Server listening on port 50051");
});

With NestJS gRPC microservice

import { DescriptorReflectionService } from "grpc-descriptor-reflection";

const reflection = new DescriptorReflectionService(
  join(__dirname, "..", "descriptor.bin"),
);

@Module({
  imports: [
    ClientsModule.register([
      {
        name: "ORDERS_PACKAGE",
        transport: Transport.GRPC,
        options: {
          package: "orders.v1",
          protoPath: join(__dirname, "../proto/orders/v1/orders.proto"),
          url: "0.0.0.0:50051",
          onLoadPackageDefinition: (_pkg, server) => {
            reflection.addToServer(server);
          },
        },
      },
    ]),
  ],
})
export class AppModule {}

Filtering advertised services

By default, all services found in the descriptor set are advertised via ListServices. You can restrict which services are listed:

const reflection = new DescriptorReflectionService("descriptor.bin", {
  services: ["mypackage.MyService", "mypackage.AdminService"],
});

Note: The filter only affects ListServices responses. All symbols remain resolvable via FileContainingSymbol regardless of the filter.

API

new DescriptorReflectionService(descriptorSetPath, options?)

Creates a new reflection service instance.

Parameters:

• descriptorSetPath (string) - Path to a binary-encoded FileDescriptorSet file.
• options (DescriptorReflectionServiceOptions) - Optional configuration.
  • services (string[]) - Restrict which services are advertised via ListServices. If omitted, all services in the descriptor set are advertised.

reflection.addToServer(server)

Registers both grpc.reflection.v1.ServerReflection and grpc.reflection.v1alpha.ServerReflection services on the given server.

Parameters:

• server - A grpc.Server instance or any object with an addService(service, implementation) method.

Supported Reflection Operations

Operation	Description
ListServices	Lists all (or filtered) services
FileContainingSymbol	Returns file descriptors for a fully-qualified symbol
FileByFilename	Returns a file descriptor by its proto filename
FileContainingExtension	Returns the file containing an extension field
AllExtensionNumbersOfType	Returns all extension field numbers for a type

All responses include transitive dependencies.

Comparison with @grpc/reflection

Feature	@grpc/reflection	grpc-descriptor-reflection
Preserves google.api.http	No	Yes
Preserves openapiv2_operation	No	Yes
Preserves custom options	No	Yes
Byte-for-byte fidelity	No	Yes
Input	Proto file paths	Pre-built descriptor set
Encoding library	protobufjs (lossy)	Raw wire format (lossless)

How It Works

1. The constructor reads the binary FileDescriptorSet and parses the protobuf wire format directly to extract each FileDescriptorProto as a raw Uint8Array slice.
2. It then decodes the set with @bufbuild/protobuf (which does preserve extensions) solely to build indexes: symbol-to-file mappings, dependency graphs, and extension registries.
3. When a reflection client requests a file, the service serves the original raw bytes extracted in step 1, along with all transitive dependencies.

Since the raw bytes are never decoded and re-encoded, every extension field, custom option, and annotation is preserved exactly as the proto compiler produced it.

License

MIT