fullstorydev/grpcui v1.3.0

on GitHub

Changes

This release includes numerous new features and some bug fixes. The release binaries on GitHub and the published docker images also now include options for arm64 architecture.

Web UI

These changes impact usage of both the command-line tool and the Go packages.

• The UI will now show error details. Error details consist of zero or more google.protobuf.Any messages that may be attached to any RPC error. Previously, if an error contained details, the UI would not show them.
• The UI now provides the option to load a file to populate bytes fields.
• The UI now includes support for "Examples", similar to collections in postman. These can be loaded programmatically, when using the Go packages, or via a new command-line option for the command-line tool (see more below). When examples are included, they appear as a list on the left. Clicking an item in the list loads the form with the contents of that example.
• The "History" tab of the UI includes a new "Save History" button, for saving all of the requests in the history to a downloaded JSON file. This JSON file is in the same format used to provide examples (see above).
• The UI now can show more information about the service and method selected. There is a small arrow button to the right of the drop-downs that can be used to show and hide this extra information. This description resembles the original proto source for the service and method, including showing any options as well as comments.
  • Caveat: the comments may only be shown when using proto source files to obtain descriptors. This is because most runtimes discard this information for descriptors that are generated and linked into a program (to reduce binary sizes and memory footprint). So when using server reflection to get descriptors, comments likely will not appear.
• The UI now includes tool tips for fields in the request form, that shows more information. Like the service and method information, this description resembles the original proto source, including options as comments. (Same caveat regarding comments as above.)
• Trying to enable (via checkbox) a field of type google.protobuf.Value would result in the UI continuing to show "unset", instead of providing a text input for defining the value. This has been fixed.
• Entering values for google.protobuf.Timestamp fields would cause errors in Safari browsers, due to the use of a date format that was not universally accepted by all browsers. This has been fixed.
• All static resources would previously be served using "public" cache control headers. However, the main index page may include RPC service and method names that are not public. Furthermore, if extra assets were added (using options for the standalone Go package), they would also be served using "public" cache control headers.
  • This is a privacy issue and has been fixed. All assets that may contain non-public data (custom assets and the index page) are now served using a "private" cache control header.
  • There was also a caching issue if the same host and port were used to connect to different backend gRPC servers. In this case, when reloading the index page for a different backend server, the cache directive would allow the browser to use a stale cached copy of the index page, with incorrect services and methods. This could lead to runtime errors until a forced-reload was performed. The index page now uses a "must-revalidate" cache control header to prevent the use of an incorrect stale cached resource.

Command-line tool

This release adds some additional command-line flags:

• A new -base-path flag allows the UI to be served from a path other than /. This can be useful when grpcui is behind a reverse proxy, so / gets routed to other servers and some other sub-path can be routed to grpcui.
• The -H, -rpc-header, and -expand-header flags supported by grpcurl are now also supported by grpcui. Headers defined this way will not appear in the web form UI, but will be added to the RPC request.
• The -use-reflection flag supported by grpcurl is now also supported by grpcui. This allows the UI augment the set of descriptors retrieved from a server (via service reflection) with local proto sources. This can be useful for the UI to understand extensions and custom options that the server may not actually be aware of.
• A new -preserve-header flag has been added that allows the "invoke" XHR endpoint to propagate HTTP headers it receives as request metadata to the server. This can be useful if grpcui is behind an authenticating proxy, like where a JWT (or other credential) header is transparently added to each request which should be forwarded to backend RPC servers.
• The -vvv flag previously would log the body of all HTTP requests and responses that the grpcui web server received. When the body was binary and the log was streaming to a terminal, this could result in unpleasant output -- not only because the binary data is unreadable, but also because some binary data could be interpreted as control/escape sequences by the terminal. Binary responses are now hex-encoded in the log.
• New -extra-js and -extra-css flags can be used to inject custom JS and CSS resources into the index page. This allows for a wide variety of customizations not previously possible without a browser extension.
• A new -also-serve flag can be used to have the grpcui web server host other files/assets. This can be useful, for example, if a custom CSS resource is used which references things like custom fonts or images.
• A new -examples flag allows configuring the UI to show a library of canned "example" requests, loaded from a JSON file.

Go package "github.com/fullstorydev/grpcui"

• Two new functions, AllMethodsViaInProcess and AllFilesViaInProcess, have been added to further simplify the use case where a gRPC UI is embedded into a Go gRPC server. They populate the list of exposed services and file descriptors using the actual services registered with a *grpc.Server and can utilize every proto file generated and linked into the program (even those that are not used or imported by the files that define the services).

Go package "github.com/fullstorydev/grpcui/standalone"

• Numerous new options have been added for the standalone handler that allow serving custom assets without having to load them all into memory: AddJSFile, AddCSSFile, and ServeAssetFile (similar to existing functions AddJS, AddCSS, and ServeAsset). Furthermore, a new ServeAssetDirectory allows easily adding an entire folder of static resources to be served by the handler.
• Two new options, WithExamples and WithExampleData, allow specifying a library of canned "example" requests, which will be shown in the UI.