README
¶
gRPCurl
grpcurl is a command-line tool that lets you interact with gRPC servers. It's
basically curl for gRPC servers.
The main purpose for this tool is to invoke RPC methods on a gRPC server from the
command-line. gRPC servers use a binary encoding on the wire
(protocol buffers, or "protobufs"
for short). So they are basically impossible to interact with using regular curl
(and older versions of curl that do not support HTTP/2 are of course non-starters).
This program accepts messages using JSON encoding, which is much more friendly for both
humans and scripts.
With this tool you can also browse the schema for gRPC services, either by querying
a server that supports service reflection
or by loading in "protoset" files (files that contain encoded file
descriptor protos).
In fact, the way the tool transforms JSON request data into a binary encoded protobuf
is using that very same schema. So, if the server you interact with does not support
reflection, you will need to build "protoset" files that grpcurl can use.
This code for this tool is also a great example of how to use the various packages of the protoreflect library, and shows off what they can do.
Features
grpcurl supports all kinds of RPC methods, including streaming methods. You can even
operate bi-directional streaming methods interactively by running grpcurl from an
interactive terminal and using stdin as the request body!
grpcurl supports both plain-text and TLS servers and has numerous options for TLS
configuration. It also supports mutual TLS, where the client is required to present a
client certificate.
As mentioned above, grpcurl works seamlessly if the server supports the reflection
service. If not, you must use protoc to build protoset files and provide those to
grpcurl.
Example Usage
Invoking an RPC on a trusted server (e.g. TLS without self-signed key or custom CA)
that requires no client certs and supports service reflection is the simplest thing to
do with grpcurl. This minimal invocation sends an empty request body:
grpcurl grpc.server.com:443 my.custom.server.Service/Method
To list all services exposed by a server, use the "list" verb. When using protoset files instead of server reflection, this lists all services defined in the protoset files.
grpcurl localhost:8787 list
grpcurl -protoset my-protos.bin list
The "list" verb also lets you see all methods in a particular service:
grpcurl localhost:8787 list my.custom.server.Service
The "describe" verb will print the type of any symbol that the server knows about or that is found in a given protoset file and also print the full descriptor for the symbol, in JSON.
grpcurl localhost:8787 describe my.custom.server.Service.MethodOne
grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne
The usage doc for the tool explains the numerous options:
grpcurl -help
Protoset Files
To use grpcurl on servers that do not support reflection, you need to compile the
*.proto files that describe the service into files containing encoded
FileDescriptorSet protos, also known as "protoset" files.
protoc --proto_path=. \
--descriptor_set_out=myservice.protoset \
--include_imports \
my/custom/server/service.proto
The --descriptor_set_out argument is what tells protoc to produce a protoset,
and the --include_imports arguments is necessary for the protoset to contain
everything that grpcurl needs to process and understand the schema.
Documentation
¶
Overview ¶
Package grpcurl provides the core functionality exposed by the grpcurl command, for dynamically connecting to a server, using the reflection service to inspect the server, and invoking RPCs. The grpcurl command-line tool constructs a DescriptorSource, based on the command-line parameters, and supplies an InvocationEventHandler to supply request data (which can come from command-line args or the process's stdin) and to log the events (to the process's stdout).
Index ¶
- Variables
- func BlockingDial(ctx context.Context, address string, creds credentials.TransportCredentials, ...) (*grpc.ClientConn, error)
- func ClientTransportCredentials(insecureSkipVerify bool, cacertFile, clientCertFile, clientKeyFile string) (credentials.TransportCredentials, error)
- func EnsureExtensions(source DescriptorSource, msg proto.Message) proto.Message
- func GetDescriptorText(dsc desc.Descriptor, descSource DescriptorSource) (string, error)
- func InvokeRpc(ctx context.Context, source DescriptorSource, cc *grpc.ClientConn, ...) error
- func ListMethods(source DescriptorSource, serviceName string) ([]string, error)
- func ListServices(source DescriptorSource) ([]string, error)
- func MetadataFromHeaders(headers []string) metadata.MD
- func MetadataToString(md metadata.MD) string
- func ServerTransportCredentials(cacertFile, serverCertFile, serverKeyFile string, requireClientCerts bool) (credentials.TransportCredentials, error)
- type DescriptorSource
- type InvocationEventHandler
- type RequestMessageSupplier
Constants ¶
This section is empty.
Variables ¶
var ErrReflectionNotSupported = errors.New("server does not support the reflection API")
ErrReflectionNotSupported is returned by DescriptorSource operations that rely on interacting with the reflection service when the source does not actually expose the reflection service. When this occurs, an alternate source (like file descriptor sets) must be used.
Functions ¶
func BlockingDial ¶
func BlockingDial(ctx context.Context, address string, creds credentials.TransportCredentials, opts ...grpc.DialOption) (*grpc.ClientConn, error)
BlockingDial is a helper method to dial the given address, using optional TLS credentials, and blocking until the returned connection is ready. If the given credentials are nil, the connection will be insecure (plain-text).
func ClientTransportCredentials ¶
func ClientTransportCredentials(insecureSkipVerify bool, cacertFile, clientCertFile, clientKeyFile string) (credentials.TransportCredentials, error)
ClientTransportCredentials builds transport credentials for a GRPC client using the given properties. If cacertFile is blank, only standard trusted certs are used to verify the server certs. If clientCertFile is blank, the client will not use a client certificate. If clientCertFile is not blank then clientKeyFile must not be blank.
func EnsureExtensions ¶
func EnsureExtensions(source DescriptorSource, msg proto.Message) proto.Message
EnsureExtensions uses the given descriptor source to download extensions for the given message. It returns a copy of the given message, but as a dynamic message that knows about all extensions known to the given descriptor source.
func GetDescriptorText ¶
func GetDescriptorText(dsc desc.Descriptor, descSource DescriptorSource) (string, error)
GetDescriptorText returns a string representation of the given descriptor.
func InvokeRpc ¶
func InvokeRpc(ctx context.Context, source DescriptorSource, cc *grpc.ClientConn, methodName string, headers []string, handler InvocationEventHandler, requestData RequestMessageSupplier) error
InvokeRpc uses te given GRPC connection to invoke the given method. The given descriptor source is used to determine the type of method and the type of request and response message. The given headers are sent as request metadata. Methods on the given event handler are called as the invocation proceeds.
The given requestData function supplies the actual data to send. It should return io.EOF when there is no more request data. If it returns a nil error then the returned JSON message should not be blank. If the method being invoked is a unary or server-streaming RPC (e.g. exactly one request message) and there is no request data (e.g. the first invocation of the function returns io.EOF), then a blank request message is sent, as if the request data were an empty object: "{}".
If the requestData function and the given event handler coordinate or share any state, they should be thread-safe. This is because the requestData function may be called from a different goroutine than the one invoking event callbacks. (This only happens for bi-directional streaming RPCs, where one goroutine sends request messages and another consumes the response messages).
func ListMethods ¶
func ListMethods(source DescriptorSource, serviceName string) ([]string, error)
ListMethods uses the given descriptor source to return a sorted list of method names for the specified fully-qualified service name.
func ListServices ¶
func ListServices(source DescriptorSource) ([]string, error)
ListServices uses the given descriptor source to return a sorted list of fully-qualified service names.
func MetadataFromHeaders ¶
MetadataFromHeaders converts a list of header strings (each string in "Header-Name: Header-Value" form) into metadata. If a string has a header name without a value (e.g. does not contain a colon), the value is assumed to be blank. Binary headers (those whose names end in "-bin") should be base64-encoded. But if they cannot be base64-decoded, they will be assumed to be in raw form and used as is.
func MetadataToString ¶
MetadataToString returns a string representation of the given metadata, for displaying to users.
func ServerTransportCredentials ¶
func ServerTransportCredentials(cacertFile, serverCertFile, serverKeyFile string, requireClientCerts bool) (credentials.TransportCredentials, error)
ServerTransportCredentials builds transport credentials for a GRPC server using the given properties. If cacertFile is blank, the server will not request client certs unless requireClientCerts is true. When requireClientCerts is false and cacertFile is not blank, the server will verify client certs when presented, but will not require client certs. The serverCertFile and serverKeyFile must both not be blank.
Types ¶
type DescriptorSource ¶
type DescriptorSource interface {
// ListServices returns a list of fully-qualified service names. It will be all services in a set of
// descriptor files or the set of all services exposed by a GRPC server.
ListServices() ([]string, error)
// FindSymbol returns a descriptor for the given fully-qualified symbol name.
FindSymbol(fullyQualifiedName string) (desc.Descriptor, error)
// AllExtensionsForType returns all known extension fields that extend the given message type name.
AllExtensionsForType(typeName string) ([]*desc.FieldDescriptor, error)
}
DescriptorSource is a source of protobuf descriptor information. It can be backed by a FileDescriptorSet proto (like a file generated by protoc) or a remote server that supports the reflection API.
func DescriptorSourceFromFileDescriptorSet ¶
func DescriptorSourceFromFileDescriptorSet(files *descriptor.FileDescriptorSet) (DescriptorSource, error)
DescriptorSourceFromFileDescriptorSet creates a DescriptorSource that is backed by the FileDescriptorSet.
func DescriptorSourceFromProtoSets ¶
func DescriptorSourceFromProtoSets(fileNames ...string) (DescriptorSource, error)
DescriptorSourceFromProtoSets creates a DescriptorSource that is backed by the named files, whose contents are encoded FileDescriptorSet protos.
func DescriptorSourceFromServer ¶
func DescriptorSourceFromServer(ctx context.Context, refClient *grpcreflect.Client) DescriptorSource
DescriptorSourceFromServer creates a DescriptorSource that uses the given GRPC reflection client to interrogate a server for descriptor information. If the server does not support the reflection API then the various DescriptorSource methods will return ErrReflectionNotSupported
type InvocationEventHandler ¶
type InvocationEventHandler interface {
// OnResolveMethod is called with a descriptor of the method that is being invoked.
OnResolveMethod(*desc.MethodDescriptor)
// OnSendHeaders is called with the request metadata that is being sent.
OnSendHeaders(metadata.MD)
// OnReceiveHeaders is called when response headers have been received.
OnReceiveHeaders(metadata.MD)
// OnReceiveResponse is called for each response message received.
OnReceiveResponse(proto.Message)
// OnReceiveTrailers is called when response trailers and final RPC status have been received.
OnReceiveTrailers(*status.Status, metadata.MD)
}
InvocationEventHandler is a bag of callbacks for handling events that occur in the course of invoking an RPC. The handler also provides request data that is sent. The callbacks are generally called in the order they are listed below.
type RequestMessageSupplier ¶
RequestMessageSupplier is a function that is called to retrieve request messages for a GRPC operation. The message contents must be valid JSON. If the supplier has no more messages, it should return nil, io.EOF.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
grpcurl
Command grpcurl makes GRPC requests (a la cURL, but HTTP/2).
|
Command grpcurl makes GRPC requests (a la cURL, but HTTP/2). |
|
testserver
Command testserver spins up a test GRPC server.
|
Command testserver spins up a test GRPC server. |