grpcui

README

ProtoPeek

Performance-first gRPC workbench with reflection-driven exploration, proto structure visualization, metadata inspection, and lightweight load simulation.

Built by Shreyam Adhikari · Website · Docs · Learn gRPC

Install

curl -fsSL https://raw.githubusercontent.com/shreyam1008/ProtoPeek/master/install.sh | sh

Or with wget:

wget -qO- https://raw.githubusercontent.com/shreyam1008/ProtoPeek/master/install.sh | sh

Go fallback:

go install github.com/shreyam1008/ProtoPeek/cmd/protopeek@latest
go install github.com/shreyam1008/ProtoPeek/cmd/pp@latest

Usage

pp                                # blank launcher — add targets from the browser UI
pp -plaintext localhost:50051     # direct single-target mode

In launcher mode each saved target keeps its own plaintext/TLS settings, authority override, schema source (reflection, proto files, or protoset), and cert paths.

Capabilities

Surface	What it does
Method rail	Search services and methods with streaming badges
Target registry	Save and switch gRPC endpoints without restarting
Payload generator	Scaffold JSON from reflected protobuf schemas
Proto explorer	Browse files, messages, enums, deps; export .proto or catalog JSON
Metadata presets	Editable auth headers and reusable environment profiles
Collections	Save request recipes with notes; import/export as JSON
Response lab	Headers, trailers, payloads, status, and latency in one surface
Assertions	Validate status, latency, metadata, and payload text locally
Simulation	Concurrency sweeps with p50/p95/p99 latency and throughput
Transport lens	gRPC-Web, Envoy bridging, and transport context alongside the console

Development

Requires Bun ≥ 1.3.10 and Go.

bun install --frozen-lockfile     # install frontend deps
bun run test                      # tsgo typecheck + Biome lint + Vitest
bun run build                     # build console + GitHub Pages site
go test ./...                     # Go test suite
make install                      # install protopeek and pp locally

Docker

make docker
docker run --rm -p 8080:8080 shreyam1008/protopeek:dev

Scratch-compatible image: static Go binary, embedded web app, CA certs, non-root user.

Project origin

ProtoPeek originated from a fork of fullstorydev/grpcui. The product, docs, branding, and release flow are now ProtoPeek's own.

Documentation

Overview

Package grpcui provides a gRPC web UI in the form of HTTP handlers that can be added to a web server.

This package provides multiple functions which, all combined, provide a fully functional web UI. Users of this package can use these pieces to embed a UI into any existing web application. The web form sources can be embedded in an existing HTML page, and the HTTP handlers wired up to make the form fully functional.

For users that don't need as much control over layout and style of the web page, instead consider using standalone.Handler, which is an all-in-one handler that includes its own HTML and CSS as well as all other dependencies.

Index

• func AllFilesViaInProcess() ([]*desc.FileDescriptor, error)
• func AllFilesViaReflection(ctx context.Context, cc grpc.ClientConnInterface) ([]*desc.FileDescriptor, error)
• func AllMethodsForServer(svr *grpc.Server) ([]*desc.MethodDescriptor, error)
• func AllMethodsForServices(descs []*desc.ServiceDescriptor) []*desc.MethodDescriptor
• func AllMethodsViaInProcess(svr reflection.GRPCServer) ([]*desc.MethodDescriptor, error)
• func AllMethodsViaReflection(ctx context.Context, cc grpc.ClientConnInterface) ([]*desc.MethodDescriptor, error)
• func RPCInvokeHandler(ch grpc.ClientConnInterface, descs []*desc.MethodDescriptor) http.Handler
• func RPCInvokeHandlerWithOptions(ch grpc.ClientConnInterface, descs []*desc.MethodDescriptor, ...) http.Handler
• func RPCMetadataHandler(methods []*desc.MethodDescriptor, files []*desc.FileDescriptor) http.Handler
• func WebFormContents(invokeURI, metadataURI string, target string, descs []*desc.MethodDescriptor) []byte
• func WebFormContentsWithOptions(invokeURI, metadataURI string, target string, descs []*desc.MethodDescriptor, ...) []byte
• func WebFormSampleCSS() []byte
• func WebFormScript() []byte
• type InvokeOptions
• type WebFormOptions

Functions

func AllFilesViaInProcess

func AllFilesViaInProcess() ([]*desc.FileDescriptor, error)

AllFilesViaInProcess returns a slice that contains all file descriptors known to this server process. This collects descriptors for all files registered with protoregistry.GlobalFiles, which includes all compiled proto files linked into the current program.

func AllFilesViaReflection

func AllFilesViaReflection(ctx context.Context, cc grpc.ClientConnInterface) ([]*desc.FileDescriptor, error)

AllFilesViaReflection returns a slice that contains the file descriptors for all methods exposed by the server on the other end of the given connection. This returns an error if the server does not support service reflection. (See "google.golang.org/grpc/reflection" for more on service reflection.)

func AllMethodsForServer

func AllMethodsForServer(svr *grpc.Server) ([]*desc.MethodDescriptor, error)

AllMethodsForServer returns a slice that contains the method descriptors for all methods exposed by the given gRPC server.

func AllMethodsForServices

func AllMethodsForServices(descs []*desc.ServiceDescriptor) []*desc.MethodDescriptor

AllMethodsForServices returns a slice that contains the method descriptors for all methods in the given services.

func AllMethodsViaInProcess

func AllMethodsViaInProcess(svr reflection.GRPCServer) ([]*desc.MethodDescriptor, error)

AllMethodsViaInProcess returns a slice that contains the method descriptors for all methods exposed by the given server. This automatically skips the reflection service, since it is assumed this is not a desired inclusion.

func AllMethodsViaReflection

func AllMethodsViaReflection(ctx context.Context, cc grpc.ClientConnInterface) ([]*desc.MethodDescriptor, error)

AllMethodsViaReflection returns a slice that contains the method descriptors for all methods exposed by the server on the other end of the given connection. This returns an error if the server does not support service reflection. (See "google.golang.org/grpc/reflection" for more on service reflection.) This automatically skips the reflection service, since it is assumed this is not a desired inclusion.

func RPCInvokeHandler

func RPCInvokeHandler(ch grpc.ClientConnInterface, descs []*desc.MethodDescriptor) http.Handler

RPCInvokeHandler returns an HTTP handler that can be used to invoke RPCs. The request includes request data, header metadata, and an optional timeout.

The handler accepts POST requests with JSON bodies and returns a JSON payload in response. The URI path should name an RPC method ("/service/method"). The format of the request and response bodies matches the formats sent and expected by the JavaScript client code embedded in WebFormContents.

The returned handler expects to serve "/". If it will instead be handling a sub-path (e.g. handling "/rpc/invoke/") then use http.StripPrefix.

Note that the returned handler does not implement any CSRF protection. To provide that, you will need to wrap the returned handler with one that first enforces CSRF checks.

func RPCInvokeHandlerWithOptions

func RPCInvokeHandlerWithOptions(ch grpc.ClientConnInterface, descs []*desc.MethodDescriptor, options InvokeOptions) http.Handler

RPCInvokeHandlerWithOptions is the same as RPCInvokeHandler except that it accepts an additional argument, options. This can be used to add extra request metadata to all RPCs invoked.

func RPCMetadataHandler

func RPCMetadataHandler(methods []*desc.MethodDescriptor, files []*desc.FileDescriptor) http.Handler

RPCMetadataHandler returns an HTTP handler that can be used to get metadata for a specified method.

The handler accepts GET requests, using a query parameter to indicate the method whose schema metadata should be fetched. The response payload will be JSON. The format of the response body matches the format expected by the JavaScript client code embedded in WebFormContents.

func WebFormContents

func WebFormContents(invokeURI, metadataURI string, target string, descs []*desc.MethodDescriptor) []byte

WebFormContents returns an HTML form that can be embedded into a web UI to provide an interactive form for issuing RPCs.

For a fully self-contained handler that provides both an HTML UI and the needed server handlers, see grpcui.UIHandler instead.

The given invokeURI and metadataURI indicate the URI paths where server handlers are registered for invoking RPCs and querying RPC metadata, respectively. Handlers for these endpoints are provided via the RPCInvokeHandler and RPCMetadataHandler functions:

// This example uses "/rpcs" as the base URI.
pageHandler := func(w http.ResponseWriter, r *http.Request) {
  webForm := grpcui.WebFormContents("/rpcs/invoke/", "/rpcs/metadata", descs)
  webFormJs := grpcui.WebFormScript()
  generateHTMLPage(w, r, webForm, webFormJs)
}

// Make sure the RPC handlers are registered at the same URI paths
// that were used in the call to WebFormContents:
rpcInvokeHandler := http.StripPrefix("/rpcs/invoke", grpcui.RPCInvokeHandler(conn, descs))
mux.Handle("/rpcs/invoke/", rpcInvokeHandler)
mux.Handle("/rpcs/metadata", grpcui.RPCMetadataHandler(descs))
mux.HandleFunc("/rpcs/index.html", pageHandler)

The given descs is a slice of methods which are exposed through the web form. You can use AllMethodsForServices, AllMethodsForServer, and AllMethodsViaReflection helper functions to build this list.

The returned HTML form requires that the contents of WebFormScript() have already been loaded as a script in the page.

func WebFormContentsWithOptions

func WebFormContentsWithOptions(invokeURI, metadataURI string, target string, descs []*desc.MethodDescriptor, opts WebFormOptions) []byte

WebFormContentsWithOptions is the same as WebFormContents except that it accepts an additional argument, options. This can be used to toggle the JS code into debug logging and can also be used to define the set of metadata to show in the web form by default (empty if unspecified).

func WebFormSampleCSS

func WebFormSampleCSS() []byte

WebFormSampleCSS returns a CSS stylesheet for styling the HTML web form returned by WebFormContents. It is possible for uses of the web form to supply their own stylesheet, but this makes it simple to use default styling.

func WebFormScript

func WebFormScript() []byte

WebFormScript returns the JavaScript that powers the web form returned by WebFormContents.

The returned JavaScript requires that jQuery and jQuery UI libraries already be loaded in the container HTML page. It includes JavaScript code that relies on the "$" symbol.

Note that the script, by default, does not handle CSRF protection. To add that, the enclosing page, in which the script is embedded, can use jQuery to configure this. For example, you can use the $.ajaxSend() jQuery function to intercept RPC invocations and automatically add a CSRF token header. To then check the token on the server-side, you will need to create a wrapper handler that first verifies the CSRF token header before delegating to a RPCInvokeHandler.

Types

type InvokeOptions

type InvokeOptions struct {
	// The set of metadata to add to all outgoing RPCs. If the invocation
	// request includes conflicting metadata, these values override, and the
	// values in the request will not be sent.
	ExtraMetadata []string
	// The set of HTTP header names that will be preserved. These are HTTP
	// request headers included in the invocation request that will be added as
	// request metadata when invoking the RPC. If the invocation request
	// includes conflicting metadata, the values in the HTTP request headers
	// will override, and the values in the request will not be sent.
	PreserveHeaders []string
	// Whether or not default values should be emitted in the JSON response
	EmitDefaults bool
	// If verbosity is greater than zero, the handler may log events, such as
	// cases where the request included metadata that conflicts with the
	// ExtraMetadata and PreserveHeaders fields above. It is an int, instead
	// of a bool "verbose" flag, so that additional logs may be added in the
	// future and the caller control how detailed those logs will be.
	Verbosity int
}

InvokeOptions contains optional arguments when creating a gRPCui invocation handler.

type WebFormOptions

type WebFormOptions struct {
	// The set of metadata to show in the web form by default. Each value in
	// the slice should be in the form "name: value"
	DefaultMetadata []string
	// If non-nil and true, the web form JS code will log debug information
	// to the JS console. If nil, whether debug is enabled or not depends on
	// an environment variable: GRPC_WEBFORM_DEBUG (if it's not blank, then
	// debug is enabled).
	Debug *bool
	// Any options that will be rendered before grpcurl in the grpccurl/raw request box
	GRPCurlOptions []string
}

WebFormOptions contains optional arguments when creating a gRPCui web form.