feat(gateway): add gRPC server reflection

Signed-off-by: Krzysztof Malczuk <kmalczuk@redhat.com>

Author: 2000krysztof

Cargo.lock

@@ -19,6 +19,7 @@ tokio = { version = "1.43", features = ["full"] }
 # gRPC/Protobuf
 tonic = "0.14"
 tonic-types = "0.14"
+tonic-reflection = "0.14"
 tonic-prost = "0.14"
 tonic-prost-build = "0.14"
 prost = "0.14"

Cargo.toml

@@ -183,6 +183,23 @@ Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall ba
 
 See the [full documentation](https://docs.nvidia.com/openshell/latest) for command guides, tutorials, and reference material.
 
+### Test the gRPC API with grpcurl
+
+The gateway serves the gRPC reflection v1 protocol. After starting a local
+plaintext gateway, use `grpcurl` without checking out or supplying the proto
+files:
+
+```shell
+grpcurl -plaintext localhost:18080 list
+grpcurl -plaintext localhost:18080 describe openshell.v1.OpenShell
+grpcurl -plaintext -d '{}' localhost:18080 openshell.v1.OpenShell/Health
+```
+
+The service list contains the public `openshell.v1.OpenShell` API. Reflection
+does not advertise the gateway's internal compute-driver, credential-driver,
+interceptor, or middleware services. For a TLS gateway, omit `-plaintext` and
+supply the CA and client certificate options required by the deployment.
+
 ## Terminal UI
 
 OpenShell includes a real-time terminal dashboard for monitoring gateways, sandboxes, and providers — inspired by [k9s](https://k9scli.io/).

README.md

@@ -106,6 +106,11 @@ Docker and Podman drivers. Operator-granted listener capabilities for external
 drivers are tracked in
 [#2539](https://github.com/NVIDIA/OpenShell/issues/2539).
 
+The primary listener serves the gRPC reflection v1 protocol without application
+authentication. It advertises only the public `openshell.v1.OpenShell` service.
+TLS and client-certificate requirements still apply at the transport layer.
+Callback-only listeners reject reflection before authentication.
+
 Operators can configure a gateway-wide gRPC request rate limit. The limit is
 applied only to gRPC API traffic after protocol multiplexing; health, metrics,
 and local sandbox-service HTTP routes are not rate limited by this control.

architecture/gateway.md

@@ -39,6 +39,7 @@ libc = "0.2"
 
 # gRPC
 tonic = { workspace = true, features = ["channel", "tls-native-roots"] }
+tonic-reflection = { workspace = true }
 prost = { workspace = true }
 prost-reflect = { workspace = true }
 prost-types = { workspace = true }

crates/openshell-server/Cargo.toml

@@ -32,7 +32,8 @@ use tracing::{debug, error, info, warn};
 /// These are structural bypasses for gRPC infrastructure that doesn't map to a
 /// single RPC method. Per-method bypasses (e.g. `Health`) are declared at the
 /// handler with `auth_mode: "unauthenticated"` in the proto annotation.
-const UNAUTHENTICATED_PREFIXES: &[&str] = &["/grpc.reflection.", "/grpc.health."];
+const UNAUTHENTICATED_PREFIXES: &[&str] =
+    &[crate::multiplex::REFLECTION_PATH_PREFIX, "/grpc.health."];
 
 /// Returns `true` if the method needs no authentication at all.
 pub fn is_unauthenticated_method(path: &str) -> bool {
@@ -1209,10 +1210,13 @@ mod tests {
     #[test]
     fn reflection_is_unauthenticated() {
         assert!(is_unauthenticated_method(
+            "/grpc.reflection.v1.ServerReflection/ServerReflectionInfo"
+        ));
+        assert!(!is_unauthenticated_method(
             "/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo"
         ));
-        assert!(is_unauthenticated_method(
-            "/grpc.reflection.v1.ServerReflection/ServerReflectionInfo"
+        assert!(!is_unauthenticated_method(
+            "/grpc.reflection.v2.ServerReflection/ServerReflectionInfo"
         ));
     }