DOCSEARCHbyAlgolia
Submit Docs

grpcui

repository·master·Indexed 27 days ago

https://github.com/fullstorydev/grpcui

A tool for interacting with gRPC servers through a web interface. It allows users to discover RPC schemas via Server Reflection, proto files, or protoset files, and invoke methods using a dynamic HTML form or raw JSON. It supports streaming RPCs, response inspection of headers and trailers, and can be embedded into Go HTTP servers using the grpcui and standalone packages.

Tokens
4.9K
Snippets
13
Records
35
Agent score
91%

What's inside grpcui

  1. Embed grpcui into a Go HTTP server

    master

    grpcui provides two library packages for embedding the web UI into your own Go applications:

    1. github.com/fullstorydev/grpcui: Provides the building blocks for embedding a gRPC web form. It includes functions to access the HTML form, the JavaScript logic, and CSS for styling.
    2. github.com/fullstorydev/grpcui/standalone: Provides a single, ready-to-use HTTP handler that supplies the complete UI, including the enclosing HTML page, jQuery, jQuery-UI, and necessary CSS/images. This is the easiest way to replicate the standalone CLI experience within your own server.

  2. Release to Docker Hub

    master

    To manually build and push a specific version of the grpcui Docker image to Docker Hub, follow these steps from the root of the repository:

    1. Write the version to a VERSION file.
    2. Build the image with the version tag.
    3. Push the versioned tag.
    4. Tag the versioned image as latest and push that as well.
    # from the root of the repo
echo v2.3.4 > VERSION
docker build -t fullstorydev/grpcui:v2.3.4 .
# now that we have it built, push to Docker Hub
docker push fullstorydev/grpcui:v2.3.4
# push "latest" tag, too
docker tag fullstorydev/grpcui:v2.3.4 fullstorydev/grpcui:latest
docker push fullstorydev/grpcui:latest

  3. Perform a GitHub-only release

    master

    If you need to create only a GitHub release (without Docker or Homebrew steps), use the make release command. You must first tag the current commit with the target version using git tag.

    # from the root of the repo
git tag v2.3.4
GITHUB_TOKEN=abcdef0123456789abcdef \
    GO111MODULE=on \
    make release

  5. Create a new grpcui release

    master

    To create a full release of grpcui, use the do-release.sh script from the root of the repository. This automates git tagging, cross-compiling binaries, creating a GitHub release, building/pushing Docker images, and submitting a Homebrew PR.

    Prerequisites:

    • A version number in semver format (e.g., v2.3.4).
    • A GitHub personal access token with write access to the fullstorydev/grpcui repository.

    Post-release step: After the script runs, the GitHub release will contain provisional notes based on commit descriptions. You must manually edit the release on GitHub to provide formatted release notes following the project's RELEASE_NOTES.md template.

    # from the root of the repo
GITHUB_TOKEN=abcdef0123456789abcd \
    ./releasing/do-release.sh v2.3.4

  6. Update Homebrew formula

    master

    To update the Homebrew recipe for grpcui, you must first download the source archive and compute its SHA256 checksum, then use brew bump-formula-pr to submit a pull request.

    Steps:

    1. Download the .tar.gz archive from the GitHub tags URL.
    2. Calculate the SHA256 checksum.
    3. Run brew bump-formula-pr using your HOMEBREW_GITHUB_API_TOKEN.
    # 1. Download and compute SHA
URL=https://github.com/fullstorydev/grpcui/archive/refs/tags/v2.3.4.tar.gz
curl -L -o tmp.tgz $URL
SHA="$(sha256sum < tmp.tgz | awk '{ print $1 }')"

# 2. Create the brew PR
HOMEBREW_GITHUB_API_TOKEN=abcdef0123456789abcdef \
    brew bump-formula-pr --url $URL --sha256 $SHA grpcui

  7. Install grpcui

    master

    You can install grpcui using Homebrew on MacOS or Linux, or by using the Go toolchain.

    Homebrew

    brew install grpcui

    Go install

    go install github.com/fullstorydev/grpcui/cmd/grpcui@latest

    If you have cloned the repository and want to build from source, navigate to the repository directory and run:

    make install

    If you encounter compilation errors due to outdated dependencies, run:

    make updatedeps
    brew install grpcui
go install github.com/fullstorydev/grpcui/cmd/grpcui@latest
make install
make updatedeps

  8. Use Protoset Files as descriptor sources

    master

    You can use compiled protoset files (binary encoded google.protobuf.FileDescriptorSet) to provide the RPC schema. To use a protoset with grpcui, provide the file via the command line.

    To generate a compatible protoset file using protoc, you must use the --descriptor_set_out flag and include the --include_imports flag to ensure all dependencies are captured.

  9. Use grpcui to interact with gRPC servers

    master

    grpcui is a CLI tool that provides a web-based GUI for interacting with gRPC servers. It allows you to browse service schemas (via reflection, .proto files, or protoset files), construct requests using a dynamic HTML form or raw JSON, and view responses including metadata (headers/trailers) and message bodies.

    Basic Usage

    Run the tool against your server address. If your server does not use TLS, use the -plaintext flag.

    grpcui -plaintext localhost:12345

    Once running, the tool will output a URL (e.g., http://127.0.0.1:60551/...) which you can open in a browser to access the Web UI.

    Key Features

    • Dynamic Web Form: Automatically generates a form based on the protobuf message structure, including support for nested messages, oneof fields, maps, and repeated fields.
    • Well-known Types: Provides specialized UI for types like google.protobuf.Timestamp (date picker) and google.protobuf.StringValue (simple textbox).
    • JSON Input: A dedicated tab allows you to paste or edit the entire request as a raw JSON object using standard Protobuf JSON mapping.
    • Streaming Support: Supports streaming RPCs by allowing you to define a sequence of messages (rendered as a list/array in the UI).
    • Response Inspection: Displays response headers, trailers, and the response body (or error messages with gRPC status codes) in a human-readable table format.

  10. Use Proto Source Files as descriptor sources

    master
    If your server does not support reflection, you can provide .proto source files directly. Use the -proto flag to point to the relevant proto files. If your proto files have dependencies, use the -import-path flag to specify the directories where those dependencies can be found. Note that standard Google 'well-known types' (package google.protobuf) do not require an import path as they are built into the grpcui binary.

  11. Use Server Reflection as a descriptor source

    master
    By default, grpcui attempts to use gRPC Server Reflection to discover the RPC schema. If your server supports reflection, you do not need to provide any additional command-line flags to use it.

  12. Use grpcui CLI to start a web UI

    master

    The grpcui command starts a simple web server that provides a web form for making gRPC requests. You must provide the address of the gRPC server as a positional argument.

    Usage:

    grpcui [flags] [address]

    Address Format:

    • Typically host:port (e.g., localhost:50051).
    • For IPv6, use brackets: [2001:db8::1]:50051.
    • For Unix domain sockets, use the path to the socket (requires -unix=true or similar logic, though the CLI help suggests the address itself is the path if a Unix socket is detected).