README
¶
connect-grpcreflect-go
connect-grpcreflect-go adds support for gRPC's server reflection API to any
net/http server — including those built with Connect. With
server reflection enabled, ad-hoc debugging tools can call your gRPC-compatible
handlers and print the responses without a copy of the schema.
The exposed reflection API is wire compatible with Google's gRPC implementations, so it works with grpcurl, grpcui, BloomRPC, and many other tools.
For more on Connect, see the announcement blog post, the documentation
on connectrpc.com (especially the Getting Started guide for Go), the
connect-go repo, or the demo service.
Example
package main
import (
"net/http"
"golang.org/x/net/http2"
"golang.org/x/net/http2/h2c"
grpcreflect "connectrpc.com/grpcreflect"
)
func main() {
mux := http.NewServeMux()
reflector := grpcreflect.NewStaticReflector(
"acme.user.v1.UserService",
"acme.group.v1.GroupService",
// protoc-gen-connect-go generates package-level constants
// for these fully-qualified protobuf service names, so you'd more likely
// reference userv1.UserServiceName and groupv1.GroupServiceName.
)
mux.Handle(grpcreflect.NewHandlerV1(reflector))
// Many tools still expect the older version of the server reflection API, so
// most servers should mount both handlers.
mux.Handle(grpcreflect.NewHandlerV1Alpha(reflector))
// If you don't need to support HTTP/2 without TLS (h2c), you can drop
// x/net/http2 and use http.ListenAndServeTLS instead.
http.ListenAndServe(
":8080",
h2c.NewHandler(mux, &http2.Server{}),
)
}
Status
Like connect-go, this module is a beta: we rely on it in
production, but we may make a few changes as we gather feedback from early
adopters. We're planning to tag a stable v1 in October, soon after the Go 1.19
release.
Support and Versioning
connect-grpcreflect-go supports:
- The two most recent major releases of Go, with a minimum of Go 1.18.
- APIv2 of protocol buffers in Go (
google.golang.org/protobuf).
Within those parameters, it follows semantic versioning.
Legal
Offered under the Apache 2 license.
Documentation
¶
Overview ¶
Package grpcreflect enables any net/http server, including those built with Connect, to handle gRPC's server reflection API. This lets ad-hoc debugging tools call your Protobuf services and print the responses without a copy of the schema.
The exposed reflection API is wire compatible with Google's gRPC implementations, so it works with grpcurl, grpcui, BloomRPC, and many other tools.
The core Connect package is connectrpc.com/connect. Documentation is available at https://connectrpc.com.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewHandlerV1 ¶
NewHandlerV1 constructs an implementation of v1 of the gRPC server reflection API. It returns an HTTP handler and the path on which to mount it.
Note that because the reflection API requires bidirectional streaming, the returned handler doesn't support HTTP/1.1. If your server must also support older tools that use the v1alpha server reflection API, see NewHandlerV1Alpha.
func NewHandlerV1Alpha ¶
func NewHandlerV1Alpha(reflector *Reflector, options ...connect.HandlerOption) (string, http.Handler)
NewHandlerV1Alpha constructs an implementation of v1alpha of the gRPC server reflection API, which is useful to support tools that haven't updated to the v1 API. It returns an HTTP handler and the path on which to mount it.
Like NewHandlerV1, the returned handler doesn't support HTTP/1.1.
Types ¶
type ExtensionResolver ¶
type ExtensionResolver interface {
protoregistry.ExtensionTypeResolver
RangeExtensionsByMessage(protoreflect.FullName, func(protoreflect.ExtensionType) bool)
}
An ExtensionResolver lets server reflection implementations query details about the registered Protobuf extensions. protoregistry.GlobalTypes implements ExtensionResolver.
ExtensionResolvers must be safe to call concurrently.
type Namer ¶
type Namer interface {
Names() []string
}
A Namer lists the fully-qualified Protobuf service names available for reflection (for example, "acme.user.v1.UserService"). Namers must be safe to call concurrently.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures a Reflector.
func WithDescriptorResolver ¶
WithExtensionResolver sets the resolver used to find Protobuf type information (typically called a "descriptor"). By default, Reflectors use protoregistry.GlobalFiles.
func WithExtensionResolver ¶
func WithExtensionResolver(resolver ExtensionResolver) Option
WithExtensionResolver sets the resolver used to find Protobuf extensions. By default, Reflectors use protoregistry.GlobalTypes.
type Reflector ¶
type Reflector struct {
// contains filtered or unexported fields
}
Reflectors implement the underlying logic for gRPC's protobuf server reflection. They're configurable, so they can support straightforward process-local reflection or more complex proxying.
Keep in mind that by default, Reflectors expose every protobuf type and extension compiled into your binary. Think twice before including the default Reflector in a public API.
For more information, see https://github.com/grpc/grpc-go/blob/master/Documentation/server-reflection-tutorial.md, https://github.com/grpc/grpc/blob/master/doc/server-reflection.md, and https://github.com/fullstorydev/grpcurl.
func NewReflector ¶
NewReflector constructs a highly configurable Reflector: it can serve a dynamic list of services, proxy reflection requests to other backends, or use an alternate source of extension information.
To build a simpler Reflector that supports a static list of services using information from the package-global Protobuf registry, use NewStaticReflector.
func NewStaticReflector ¶
NewStaticReflector constructs a simple Reflector that supports a static list of services using information from the package-global Protobuf registry. For a more configurable Reflector, use NewReflector.
The supplied strings should be fully-qualified Protobuf service names (for example, "acme.user.v1.UserService"). Generated Connect service files have this declared as a constant.
Source Files
Directories