grpcurl

repository·master·Indexed 11 days ago

A command-line tool for interacting with gRPC servers, serving as a 'curl' equivalent for the gRPC protocol. It allows users to invoke RPC methods using JSON, browse service schemas via reflection or proto files, and describe gRPC symbols. It supports various connection security options including TLS, plaintext, and ALTS.

Tokens: 8.7K
Snippets: 41
Records: 44
Agent score: 96%

What's inside grpcurl

Update the Homebrew recipe for a new release

master

To update the Homebrew formula for grpcurl, you must first download the source archive from GitHub and compute its SHA256 checksum. Then, use the brew bump-formula-pr command to submit a pull request.

1. Compute the SHA256 checksum

# download the source archive from GitHub
URL=https://github.com/fullstorydev/grpcurl/archive/refs/tags/v2.3.4.tar.gz
curl -L -o tmp.tgz $URL
# and compute the SHA
SHA="$(sha256sum < tmp.tgz | awk '{ print $1 }')"

2. Submit the Pull Request

Use your GitHub personal access token to run the bump command:

HOMEBREW_GITHUB_API_TOKEN=abcdef0123456789abcdef \
    brew bump-formula-pr --url $URL --sha256 $SHA grpcurl

# download the source archive from GitHub
URL=https://github.com/fullstorydev/grpcurl/archive/refs/tags/v2.3.4.tar.gz
curl -L -o tmp.tgz $URL
# and compute the SHA
SHA="$(sha256sum < tmp.tgz | awk '{ print $1 }')"

# and then:
HOMEBREW_GITHUB_API_TOKEN=abcdef0123456789abcdef \
    brew bump-formula-pr --url $URL --sha256 $SHA grpcurl

Invoke RPC methods with grpcurl
master
Use grpcurl to call RPC methods on a gRPC server. The tool accepts JSON-encoded messages and converts them to the binary protobuf format used by the server.
Basic Invocation (Empty Request)
If the server supports reflection and uses TLS:
```
grpcurl grpc.server.com:443 my.custom.server.Service/Method
```
For plain-text (no TLS) servers:
```
grpcurl -plaintext grpc.server.com:80 my.custom.server.Service/Method
```
Sending JSON Request Bodies
Use the -d flag. Note: All flags must appear before the server address and method name.
```
grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' grpc.server.com:443 my.custom.server.Service/Method
```
To read the request body from stdin (useful for pipelines with jq or heredocs), use -d @:
```
grpcurl -d @ grpc.server.com:443 my.custom.server.Service/Method <<EOM
{
  "id": 1234,
  "tags": ["foo","bar"]
}
EOM
```
```
grpcurl -d '{"id": 1234, "tags": ["foo","bar"]}' grpc.server.com:443 my.custom.server.Service/Method
```
https://github.com/fullstorydev/grpcurl/blob/master/README.md
List services and methods
master
Use the list verb to discover available services or methods on a server.
Using Server Reflection
If the server supports reflection, you only need the address:
```
grpcurl localhost:8787 list
# To list methods within a specific service:
grpcurl localhost:8787 list my.custom.server.Service
```
Using Protoset Files
If reflection is unavailable, provide a compiled protoset:
```
grpcurl -protoset my-protos.bin list
```
Using Proto Source Files
Provide the .proto files and any necessary import paths:
```
grpcurl -import-path ../protos -proto my-stuff.proto list
```
```
grpcurl localhost:8787 list
```
https://github.com/fullstorydev/grpcurl/blob/master/README.md
Install grpcurl
master
You can install grpcurl using several methods depending on your environment:
Homebrew (macOS)
```
brew install grpcurl
```
Snap
```
snap install grpcurl
```
From Source (Go)
If you have the Go SDK installed, use:
```
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
```
Alternatively, if you have cloned the repository, run:
```
make install
```
Docker
Pull and run the official image:
```
docker pull fullstorydev/grpcurl:latest
docker run fullstorydev/grpcurl api.grpc.me:443 list
```
Docker Pitfalls:
- Loopback access: To access a server on the host's loopback, use host.docker.internal (Mac/Windows) or --network="host" (Linux).
- Proto files: Mount folders containing proto files using -v $(pwd):/protos and adjust import paths.
- Stdin: To use -d @ for stdin, you must include the -i flag in the docker run command.
```
brew install grpcurl
```
https://github.com/fullstorydev/grpcurl/blob/master/README.md
Upload grpcurl snap to the edge channel
master
To upload a built snap package to the edge channel, use the snapcraft upload command.
Note: You must own the package name registration to perform this action.
```
snapcraft upload --release edge ./grpcurl_v[version tag]_amd64.snap
```
https://github.com/fullstorydev/grpcurl/blob/master/snap/README.md
Generate protoset files with protoc
master
For better performance in scripts, you can use compiled protoset files (binary encoded google.protobuf.FileDescriptorSet) instead of parsing .proto files every time.
To create a protoset, use protoc with the --descriptor_set_out and --include_imports flags:
```
protoc --proto_path=. \
    --descriptor_set_out=myservice.protoset \
    --include_imports \
    my/custom/server/service.proto
```
Then, use the file with grpcurl:
```
grpcurl -protoset myservice.protoset list
```
```
protoc --proto_path=. --descriptor_set_out=myservice.protoset --include_imports my/custom/server/service.proto
```
https://github.com/fullstorydev/grpcurl/blob/master/README.md

Describe gRPC symbols

master

The describe verb prints the type and a proto-source snippet for a specific symbol (service, method, message, etc.).

Using Server Reflection

grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

Using Protoset Files

grpcurl -protoset my-protos.bin describe my.custom.server.Service.MethodOne

Using Proto Source Files

grpcurl -import-path ../protos -proto my-stuff.proto describe my.custom.server.Service.MethodOne

grpcurl localhost:8787 describe my.custom.server.Service.MethodOne

Create a new release of gRPCurl
master
To create a full release of grpcurl, use the do-release.sh script located in the releasing/ directory. This script automates building binaries for multiple platforms, creating a GitHub release with provisional notes, building and pushing a Docker image to Docker Hub, and submitting a Homebrew pull request.
Prerequisites
- A version number in semantic versioning format (e.g., v2.3.4).
- A GitHub personal access token with write access to the fullstorydev/grpcurl repository.
Execution
Run the script from the root of the repository by providing the GITHUB_TOKEN environment variable and the target version:
```
# from the root of the repo
GITHUB_TOKEN=abcdef0123456789abcd \
    ./releasing/do-release.sh v2.3.4
```
Finalizing Release Notes
The script generates provisional release notes based on commit descriptions. After the script completes, you must manually update the release notes on GitHub to follow the project's recommended format (defined in releasing/RELEASE_NOTES.md).
```
# from the root of the repo
GITHUB_TOKEN=abcdef0123456789abcd \
    ./releasing/do-release.sh v2.3.4
```
https://github.com/fullstorydev/grpcurl/blob/master/releasing/README.md
Perform a GitHub-only release
master
If you need to create only a GitHub release (without Docker or Homebrew steps), you can use the make release command. This requires a git tag corresponding to the version you are releasing.
Note: The release target requires that the current SHA has a semantic version tag. If a release attempt fails, it is recommended to release a new patch version rather than deleting assets from a botched release to maintain immutability.
```
# from the root of the repo
git tag v2.3.4
GITHUB_TOKEN=abcdef0123456789abcdef \
    GO111MODULE=on \
    make release
```
https://github.com/fullstorydev/grpcurl/blob/master/releasing/README.md
Pack and install grpcurl as a Snap package
master
You can build a snap package from the current branch and install it locally for development or testing using snapcraft. Note that local installation requires --devmode.
```
# Pack the current branch to a snap package
snapcraft pack

# Install the package locally
snap install ./grpcurl_v[version tag]_amd64.snap --devmode
```
https://github.com/fullstorydev/grpcurl/blob/master/snap/README.md
What is a DescriptorSource and how to use it
master
A DescriptorSource is an interface used to retrieve protobuf descriptor information (schemas). It abstracts where the schema comes from, allowing you to use the same logic whether the schema is loaded from local files or queried from a remote gRPC server via reflection.
Common use cases for a DescriptorSource include:
- Listing all services available in a schema.
- Finding a specific symbol (message, service, method, etc.) by its fully-qualified name.
- Retrieving all extensions for a specific message type.
If you attempt to use a DescriptorSource that relies on gRPC reflection (like one created from a server) on a server that does not support it, operations will return ErrReflectionNotSupported.
```
type DescriptorSource interface {
	ListServices() ([]string, error)
	FindSymbol(fullyQualifiedName string) (desc.Descriptor, error)
	AllExtensionsForType(typeName string) ([]*desc.FieldDescriptor, error)
}
```
https://github.com/fullstorydev/grpcurl/blob/master/desc_source.go
Provide protobuf schemas to grpcurl
master
If the server does not support gRPC reflection, you must provide the schema manually using one of these methods:
- Protoset files: Use -protoset <file> to provide an encoded FileDescriptorSet. You can provide multiple files via multiple -protoset flags.
- Proto source files: Use -proto <file> to provide raw .proto files. You can provide multiple files via multiple -proto flags.
- Import paths: If using -proto, use -import-path <path> to specify directories where imports can be resolved.
Note: It is an error to use both -protoset and -proto simultaneously.
```
# Use a protoset file
grpcurl -protoset ./myschema.protoset localhost:50051 list

# Use proto source files with import paths
grpcurl -proto ./api/service.proto -import-path ./api localhost:50051 list
```
https://github.com/fullstorydev/grpcurl/blob/master/cmd/grpcurl/grpcurl.go

grpcurl

What's inside grpcurl

1. Compute the SHA256 checksum

2. Submit the Pull Request

Basic Invocation (Empty Request)

Sending JSON Request Bodies

Using Server Reflection

Using Protoset Files

Using Proto Source Files

Homebrew (macOS)

Snap

From Source (Go)

Docker

Using Server Reflection

Using Protoset Files

Using Proto Source Files

Prerequisites

Execution

Finalizing Release Notes