standalone

Documentation

Overview

Package standalone provides a stand-alone HTTP handler that provides a complete gRPC web UI that includes both the web page and relevant server-side handlers. The web page includes HTML, CSS, and JS sources, which can be customized only regarding the "target" in the page header (which is intended to show the server to which RPC requests are directed). The actual list of methods exposed via the form is also customizable.

This is the same web content that the `grpcui` command-line program exposes. It starts up a web server that includes only this stand-alone handler. If you need more control over the page in which the UI form gets embedded or over the CSS/styling of the page, instead use the various functions in the "github.com/fullstorydev/grpcui" package to assemble your own web UI.

Note that this package bundles the JS dependencies of the web form. It provides jQuery 3.3.1 and jQuery-UI 1.12.1.

An example of using the package with a server supporting reflection:

cc, err := grpc.DialContext(ctx, "dns:///my-grpc-server:8080", grpc.WithBlock())
if err != nil {
	return err
}
h, err := standalone.HandlerViaReflection(ctx, cc, "dns:///my-grpc-server:8080")
if err != nil {
	return err
}
http.ListenAndServe(":8080", h)

Index

• func Handler(ch grpcdynamic.Channel, target string, methods []*desc.MethodDescriptor, ...) http.Handler
• func HandlerViaReflection(ctx context.Context, cc grpc.ClientConnInterface, target string, ...) (http.Handler, error)
• type HandlerOption
  • func AddCSS(filename string, css []byte) HandlerOption
  • func AddJS(filename string, js []byte) HandlerOption
  • func ServeAsset(filename string, contents []byte) HandlerOption
  • func WithCSS(css []byte) HandlerOption
  • func WithDebug(debug bool) HandlerOption
  • func WithDefaultMetadata(headers []string) HandlerOption
  • func WithIndexTemplate(tmpl *template.Template) HandlerOption
• type WebFormContainerTemplateData

Functions

func Handler

func Handler(ch grpcdynamic.Channel, target string, methods []*desc.MethodDescriptor, files []*desc.FileDescriptor, opts ...HandlerOption) http.Handler

Handler returns an HTTP handler that provides a fully-functional gRPC web UI, including the main index (with the HTML form), all needed CSS and JS assets, and the handlers that provide schema metadata and perform RPC invocations. The HTML index, CSS, and JS files can be customized and augmented with opts.

All RPC invocations are sent to the given channel. The given target is shown in the header of the web UI, to show the user where their requests are being sent. The given methods enumerate all supported RPC methods, and the given files enumerate all known protobuf (for enumerating all supported message types, to support the use of google.protobuf.Any messages).

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

func HandlerViaReflection

func HandlerViaReflection(ctx context.Context, cc grpc.ClientConnInterface, target string, opts ...HandlerOption) (http.Handler, error)

HandlerViaReflection tries to query the provided connection for all services and methods supported by the server, and constructs a handler to serve the UI.

The handler has the same properties as the one returned by Handler.

Types

type HandlerOption

type HandlerOption interface {
	// contains filtered or unexported methods
}

HandlerOption instances allow for configuration of the standalone Handler.

func AddCSS

func AddCSS(filename string, css []byte) HandlerOption

AddCSS adds a CSS file to Handler, serving the supplied contents at the URI "/s/<filename>" with a Content-Type of "text/css; charset=UTF-8". It will also be added to the AddlResources field of the WebFormContainerTemplateData so that it is rendered into the HEAD of the HTML page.

It is safe to pass in multiple AddCSS Opts to Handler. Each will be rendered in the order they are passed.

func AddJS

func AddJS(filename string, js []byte) HandlerOption

AddJS adds a JS file to Handler, serving the supplied contents at the URI "/s/<filename>" with a Content-Type of "text/javascript; charset=UTF-8". It will also be added to the AddlResources field of the WebFormContainerTemplateData so that it is rendered into the HEAD of the HTML page.

It is safe to pass in multiple AddJS Opts to Handler. Each will be rendered in the order they are passed.

func ServeAsset

func ServeAsset(filename string, contents []byte) HandlerOption

ServeAsset will add an additional file to Hadler, serving the supplied contents at the URI "/s/<filename>" with a Content-Type that is computed based on the given filename's extension.

These assets could be images or other files referenced by a custom index template. Unlike files added via AddJS or AddCSS, they will NOT be provided to the template in the AddlResources field of the WebFormContainerTemplateData.

func WithCSS

func WithCSS(css []byte) HandlerOption

WithCSS entirely replaces the WebFormCSS bytes used by default in Handler.

func WithDebug

func WithDebug(debug bool) HandlerOption

WithDebug enables console logging in the client JS. This prints extra information as the UI processes user input.

func WithDefaultMetadata

func WithDefaultMetadata(headers []string) HandlerOption

WithDefaultMetadata sets the default metadata in the web form to the given values. Each string should be in the form "name: value".

func WithIndexTemplate

func WithIndexTemplate(tmpl *template.Template) HandlerOption

WithIndexTemplate replace the default HTML template used in Handler with the one given. The template will be provided an instance of WebFormContainerTemplateData as the data to render.

type WebFormContainerTemplateData

type WebFormContainerTemplateData struct {
	// Target is the name of the machine we are making requests to (for display purposes).
	Target string

	// WebFormContents is the generated form HTML from your ServiceDescriptors.
	WebFormContents template.HTML

	// AddlResources are additional CSS and JS files, in the form of <link> and <script>
	// tags, that we want to append to the HEAD of the index template.
	AddlResources []template.HTML
}

WebFormContainerTemplateData is the param type for templates that embed the webform HTML. If you use WithIndexTemplate to provide an alternate HTML template for Handler, the template should expect a value of this type.