From 7e882c8a7c2c227c76bc6dab6b7223f14769f605 Mon Sep 17 00:00:00 2001 From: Joshua Humphries Date: Thu, 31 May 2018 12:48:30 -0400 Subject: [PATCH] update README.md (#36) - Adds a travis CI badge at the top. - Adds an "installation" section that should address #30 - Adds content about using proto source files. --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ddf6558..31e9671 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ # gRPCurl +[![Build Status](https://travis-ci.org/fullstorydev/grpcurl.svg?branch=master)](https://travis-ci.org/fullstorydev/grpcurl/branches) + `grpcurl` is a command-line tool that lets you interact with gRPC servers. It's basically `curl` for gRPC servers. @@ -18,7 +20,9 @@ In fact, the way the tool transforms JSON request data into a binary encoded pro 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 +This repo also provides a library package, `github.com/fullstorydev/grpcurl`, that has +functions for simplifying the construction of other command-line tools that dynamically +invoke gRPC endpoints. This code is a great example of how to use the various packages of the [protoreflect](https://godoc.org/github.com/jhump/protoreflect) library, and shows off what they can do. @@ -32,50 +36,95 @@ configuration. It also supports mutual TLS, where the client is required to pres 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`. +service. If not, you can supply the `.proto` source files or you can supply protoset +files (containing compiled descriptors, produced by `protoc`) to `grpcurl`. + +## Installation +You can use the `go` tool to install `grpcurl`: +```shell +go get github.com/fullstorydev/grpcurl +go install github.com/fullstorydev/grpcurl/cmd/grpcurl +``` + +This installs the command into the `bin` sub-folder of wherever your `$GOPATH` +environment variable points. If this directory is already in your `$PATH`, then +you should be good to go. + +If you have already pulled down this repo to a location that is not in your +`$GOPATH` and want to build from the sources, you can `cd` into the repo and then +run `make install`. + +If you encounter compile errors, you could have out-dated versions of `grpcurl`'s +dependencies. You can update the dependencies by running `make updatedeps`. ## 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: -``` +```shell 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. -``` +To list all services exposed by a server, use the "list" verb. When using `.proto` source +or protoset files instead of server reflection, this lists all services defined in the +source or protoset files. +```shell +# Server supports reflection grpcurl localhost:8787 list +# Using compiled protoset files grpcurl -protoset my-protos.bin list + +# Using proto sources +grpcurl -import-path ../protos -proto my-stuff.proto list ``` The "list" verb also lets you see all methods in a particular service: -``` +```shell 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. -``` +```shell +# Server supports reflection grpcurl localhost:8787 describe my.custom.server.Service.MethodOne +# Using compiled protoset files grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne + +# Using proto sources +grpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne ``` The usage doc for the tool explains the numerous options: -``` +```shell 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. +## Proto Source Files +To use `grpcurl` on servers that do not support reflection, you can use `.proto` source +files. -``` +In addition to using `-proto` flags to point `grpcurl` at the relevant proto source file(s), +you may also need to supply `-import-path` flags to tell `grpcurl` the folders from which +dependencies can be imported. + +Just like when compiling with `protoc`, you do *not* need to provide an import path for the +location of the standard protos included with `protoc` (which contain various "well-known +types" with a package definition of `google.protobuf`). These files are "known" by `grpcurl` +as a snapshot of their descriptors is built into the `grpcurl` binary. + +## Protoset Files +You can also use compiled protoset files with `grpcurl`. If you are scripting `grpcurl` and +need to re-use the same proto sources for many invocations, you will see better performance +by using protoset files (since it skips the parsing and compilation steps with each +invocation). + +Protoset files contain binary encoded `google.protobuf.FileDescriptorSet` protos. To create +a protoset file, invoke `protoc` with the `*.proto` files that describe the service: +```shell protoc --proto_path=. \ --descriptor_set_out=myservice.protoset \ --include_imports \ @@ -83,5 +132,5 @@ protoc --proto_path=. \ ``` 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 +and the `--include_imports` argument is necessary for the protoset to contain everything that `grpcurl` needs to process and understand the schema.