cardano-rpc: Implement gRPC server reflection (grpc.reflection.v1 and v1alpha) - #1334
Open
carbolymer wants to merge 2 commits into
Open
cardano-rpc: Implement gRPC server reflection (grpc.reflection.v1 and v1alpha)#1334carbolymer wants to merge 2 commits into
carbolymer wants to merge 2 commits into
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| @@ -0,0 +1,257 @@ | |||
| {- This file was auto-generated from grpc/reflection/v1/reflection.proto by the proto-lens-protoc program. -} | |||
| {-# LANGUAGE ScopedTypeVariables, DataKinds, TypeFamilies, UndecidableInstances, GeneralizedNewtypeDeriving, MultiParamTypeClasses, FlexibleContexts, FlexibleInstances, PatternSynonyms, MagicHash, NoImplicitPrelude, DataKinds, BangPatterns, TypeApplications, OverloadedStrings, DerivingStrategies#-} | |||
| @@ -0,0 +1,257 @@ | |||
| {- This file was auto-generated from grpc/reflection/v1/reflection.proto by the proto-lens-protoc program. -} | |||
| {-# LANGUAGE ScopedTypeVariables, DataKinds, TypeFamilies, UndecidableInstances, GeneralizedNewtypeDeriving, MultiParamTypeClasses, FlexibleContexts, FlexibleInstances, PatternSynonyms, MagicHash, NoImplicitPrelude, DataKinds, BangPatterns, TypeApplications, OverloadedStrings, DerivingStrategies#-} | |||
carbolymer
changed the title
carbolymer
force-pushed
the
mgalazyn/feature/grpc-reflection
branch
from
September 9, 2026 14:00
c15e3df to
8aeebe8
Compare
carbolymer
force-pushed
the
mgalazyn/feature/grpc-reflection
branch
from
September 10, 2026 16:37
8aeebe8 to
4946bf3
Compare
carbolymer
marked this pull request as ready for review
September 10, 2026 16:38
carbolymer
requested review from
CarlosLopezDeLara,
disassembler,
erikd and
palas
as code owners
September 10, 2026 16:38
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The reflection handler’s treatment of all_extension_numbers_of_type as NOT_FOUND (rather than an empty response / UNIMPLEMENTED semantics) and the unexplained cardano-api lower-bound bump should be addressed/justified before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR adds gRPC Server Reflection support to cardano-rpc, serving both grpc.reflection.v1 and legacy grpc.reflection.v1alpha so clients can discover services and schemas from a running node without local .proto files.
Changes:
- Implemented a reflection handler plus a compiled-in descriptor table with symbol lookup and transitive dependency closure.
- Registered both reflection services in the server and derived
list_servicesfrom the same registry used for handler registration. - Added unit tests for descriptor closure/symbol lookup and for v1/v1alpha request/response bridging; updated docs, cabal, and changelog fragment.
File summaries
| File | Description |
|---|---|
| cardano-rpc/test/cardano-rpc-test/Test/Cardano/Rpc/Reflection/DescriptorTable.hs | Unit tests for descriptor table closure, symbol indexing rules, and transitive closure behavior. |
| cardano-rpc/test/cardano-rpc-test/Test/Cardano/Rpc/Reflection.hs | Unit tests for request dispatch, error-path behavior, terminal stream marker, and v1alpha bridging. |
| cardano-rpc/src/Cardano/Rpc/Server/Internal/Reflection/DescriptorTable.hs | Implements descriptor table + symbol index + transitive closure over compiled-in protos. |
| cardano-rpc/src/Cardano/Rpc/Server/Internal/Reflection.hs | Implements v1 reflection bidi handler and v1alpha bridge, plus request dispatch. |
| cardano-rpc/src/Cardano/Rpc/Server.hs | Registers reflection services and centralizes the registered service list used by reflection. |
| cardano-rpc/src/Cardano/Rpc/Proto/Api/Reflection/V1alpha.hs | Exposes v1alpha reflection proto modules and sets grapesy metadata type families. |
| cardano-rpc/src/Cardano/Rpc/Proto/Api/Reflection/V1.hs | Exposes v1 reflection proto modules and sets grapesy metadata type families. |
| cardano-rpc/README.md | Documents reflection support as an additional gRPC service. |
| cardano-rpc/proto/grpc/reflection/v1alpha/reflection.proto | Vendors the upstream v1alpha reflection proto definition. |
| cardano-rpc/proto/grpc/reflection/v1/reflection.proto | Vendors the upstream v1 reflection proto definition. |
| cardano-rpc/gen/Proto/Grpc/Reflection/V1alpha/Reflection.hs | Generated proto-lens bindings for the v1alpha reflection proto. |
| cardano-rpc/gen/Proto/Grpc/Reflection/V1alpha/Reflection_Fields.hs | Generated field lenses for v1alpha reflection messages. |
| cardano-rpc/gen/Proto/Grpc/Reflection/V1/Reflection_Fields.hs | Generated field lenses for v1 reflection messages. |
| cardano-rpc/cardano-rpc.cabal | Adds reflection modules/tests, adds proto-lens-protobuf-types to tests, and bumps cardano-api lower bound. |
| .changes/20260909_cardano_rpc_grpc_reflection.yml | Adds changelog fragment describing the new reflection feature. |
Review details
- Files reviewed: 14/16 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+126
to
+128
| V1.ServerReflectionRequest'AllExtensionNumbersOfType typeName -> | ||
| V1.errorResponse | ||
| .~ mkErrorResponse GrpcNotFound ("no extensions are declared of type: " <> typeName) |
Comment on lines
100
to
+103
| base, | ||
| base16-bytestring, | ||
| bytestring, | ||
| cardano-api >=11.5, | ||
| cardano-api >=11.7, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Implements the gRPC Server Reflection Protocol in cardano-rpc, so clients can discover the available services, methods and message schemas from a running node without local
.protofiles.Closes #1295.
What this adds:
grpc.reflection.v1.ServerReflectionand the oldergrpc.reflection.v1alpha.ServerReflectionare served, so current and legacy probes (grpcurl, Postman, buf, evans) both work.buf generate protopipeline.file_by_filenameandfile_containing_symbolwith the full transitive dependency closure. A unit test asserts the table stays closed under the descriptors'dependencyfield, so adding a proto without updating the table fails the test suite.list_servicesderives its answer from the same service definitions that are registered in the server, so the advertised list cannot drift from what is actually served.file_containing_extension,all_extension_numbers_of_type) answer NOT_FOUND, since none of our protos use extensions.Design note for reviewers: lookup failures are answered with an in-stream
ErrorResponseand the RPC stays OK, as the protocol specifies. A request with an entirely unsetmessage_requestoneof is answered with an in-streamINVALID_ARGUMENTerror response; Go's reference implementation terminates the RPC instead, so this is a deliberate, tested divergence.Testing: the cardano-rpc unit test suite covers the descriptor closure, symbol lookup, error paths, the v1alpha bridge and the terminal stream element (all 123 tests pass under the repo's
-Werrornix check). A wire-level integration test against a running node via cardano-testnet follows in a separate cardano-node PR, which will also add grpcurl to the devshell for manual probes.Context
Additional context for the PR goes here. If the PR fixes a particular issue please provide a link to the issue.
How to trust this PR
Highlight important bits of the PR that will make the review faster. If there are commands the reviewer can run to observe the new behavior, describe them.
Checklist
.changes/