Categorygithub.com/bufbuild/connect-grpcreflect-go
modulepackage
1.1.0
Repository: https://github.com/bufbuild/connect-grpcreflect-go.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
16
Dependents
13
Files
626 SLOC

# README

connect-grpcreflect-go

Build Report Card GoDoc

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 connect.build (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 "github.com/bufbuild/connect-grpcreflect-go"
)

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: Stable

This module is stable. It supports:

Within those parameters, connect-grpcreflect-go follows semantic versioning. We will not make breaking changes in the 1.x series of releases.

Legal

Offered under the Apache 2 license.

# Functions

IsReflectionStreamBroken returns true if the given error was the result of a [ClientStream] failing.
NewClient returns a client for interacting with the gRPC server reflection service.
NewHandlerV1 constructs an implementation of v1 of the gRPC server reflection API.
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.
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.
NewStaticReflector constructs a simple Reflector that supports a static list of services using information from the package-global Protobuf registry.
WithDescriptorResolver sets the resolver used to find Protobuf type information (typically called a "descriptor").
WithExtensionResolver sets the resolver used to find Protobuf extensions.
WithReflectionHost is an option that allows the caller to provide the hostname that will be included with all requests on the stream.
WithRequestHeaders is an option that allows the caller to provide the request headers that will be sent when a stream is created.

# Constants

ReflectV1AlphaServiceName is the fully-qualified name of the v1alpha version of the reflection service.
ReflectV1ServiceName is the fully-qualified name of the v1 version of the reflection service.

# Structs

Client is a Connect client for the server reflection service.
ClientStream represents a bidirectional stream for downloading reflection information.
Reflector implements the underlying logic for gRPC's protobuf server reflection.

# Interfaces

ClientStreamOption is an option that can be provided when calling [Client.NewStream].
An ExtensionResolver lets server reflection implementations query details about the registered Protobuf extensions.
A Namer lists the fully-qualified Protobuf service names available for reflection (for example, "acme.user.v1.UserService").
An Option configures a Reflector.