grpc-web: github.com/improbable-eng/grpc-web/go/grpcweb Index | Files

package grpcweb

import "github.com/improbable-eng/grpc-web/go/grpcweb"

`grpcweb` implements the gRPC-Web spec as a wrapper around a gRPC-Go Server.

It allows web clients (see companion JS library) to talk to gRPC-Go servers over the gRPC-Web spec. It supports HTTP/1.1 and HTTP2 encoding of a gRPC stream and supports unary and server-side streaming RPCs. Bi-di and client streams are unsupported due to limitations in browser protocol support.

See https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md for the protocol specification.

Here's an example of how to use it inside an existing gRPC Go server on a separate http.Server that serves over TLS:

grpcServer := grpc.Server()
wrappedGrpc := grpcweb.WrapServer(grpcServer)
tlsHttpServer.Handler = http.HandlerFunc(func(resp http.ResponseWriter, req *http.Request) {
	if grpcweb.IsGrpcRequest(req) {
		wrappedGrpc.ServeHTTP(resp, req)
	}
	// Fall back to other servers.
	http.DefaultServeMux.ServeHTTP(resp, req)
})

If you'd like to have a standalone binary, please take a look at `grpcwebproxy`.

Index

Package Files

doc.go grpc_web_response.go helpers.go options.go wrapper.go

func ListGRPCResources Uses

func ListGRPCResources(server *grpc.Server) []string

ListGRPCResources is a helper function that lists all URLs that are registered on gRPC server.

This makes it easy to register all the relevant routes in your HTTP router of choice.

type Option Uses

type Option func(*options)

func WithAllowedRequestHeaders Uses

func WithAllowedRequestHeaders(headers []string) Option

WithAllowedResponseHeaders allows for customizing what gRPC request headers a browser can add.

This is controlling the CORS pre-flight `Access-Control-Allow-Headers` method and applies to *all* gRPC handlers. However, a special `*` value can be passed in that allows the browser client to provide *any* header, by explicitly whitelisting all `Access-Control-Request-Headers` of the pre-flight request.

The default behaviour is `[]string{'*'}`, allowing all browser client headers. This option overrides that default, while maintaining a whitelist for gRPC-internal headers.

Unfortunately, since the CORS pre-flight happens independently from gRPC handler execution, it is impossible to automatically discover it from the gRPC handler itself.

The relevant CORS pre-flight docs: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers

func WithCorsForRegisteredEndpointsOnly Uses

func WithCorsForRegisteredEndpointsOnly(onlyRegistered bool) Option

WithCorsForRegisteredEndpointsOnly allows for customizing whether OPTIONS requests with the `X-GRPC-WEB` header will only be accepted if they match a registered gRPC endpoint.

This should be set to false to allow handling gRPC requests for unknown endpoints (e.g. for proxying).

The default behaviour is `true`, i.e. only allows CORS requests for registered endpoints.

func WithOriginFunc Uses

func WithOriginFunc(originFunc func(origin string) bool) Option

WithOriginFunc allows for customizing what CORS Origin requests are allowed.

This is controlling the CORS pre-flight `Access-Control-Allow-Origin`. This mechanism allows you to limit the availability of the APIs based on the domain name of the calling website (Origin). You can provide a function that filters the allowed Origin values.

The default behaviour is `*`, i.e. to allow all calling websites.

The relevant CORS pre-flight docs: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin

type WrappedGrpcServer Uses

type WrappedGrpcServer struct {
    // contains filtered or unexported fields
}

func WrapServer Uses

func WrapServer(server *grpc.Server, options ...Option) *WrappedGrpcServer

WrapServer takes a gRPC Server in Go and returns a WrappedGrpcServer that provides gRPC-Web Compatibility.

The internal implementation fakes out a http.Request that carries standard gRPC, and performs the remapping inside http.ResponseWriter, i.e. mostly the re-encoding of Trailers (that carry gRPC status).

You can control the behaviour of the wrapper (e.g. modifying CORS behaviour) using `With*` options.

func (*WrappedGrpcServer) HandleGrpcWebRequest Uses

func (w *WrappedGrpcServer) HandleGrpcWebRequest(resp http.ResponseWriter, req *http.Request)

HandleGrpcWebRequest takes a HTTP request that is assumed to be a gRPC-Web request and wraps it with a compatibility layer to transform it to a standard gRPC request for the wrapped gRPC server and transforms the response to comply with the gRPC-Web protocol.

func (*WrappedGrpcServer) IsAcceptableGrpcCorsRequest Uses

func (w *WrappedGrpcServer) IsAcceptableGrpcCorsRequest(req *http.Request) bool

IsAcceptableGrpcCorsRequest determines if a request is a CORS pre-flight request for a gRPC-Web request and that this request is acceptable for CORS.

You can control the CORS behaviour using `With*` options in the WrapServer function.

func (*WrappedGrpcServer) IsGrpcWebRequest Uses

func (w *WrappedGrpcServer) IsGrpcWebRequest(req *http.Request) bool

IsGrpcWebRequest determines if a request is a gRPC-Web request by checking that the "content-type" is "application/grpc-web" and that the method is POST.

func (*WrappedGrpcServer) ServeHTTP Uses

func (w *WrappedGrpcServer) ServeHTTP(resp http.ResponseWriter, req *http.Request)

ServeHTTP takes a HTTP request and if it is a gRPC-Web request wraps it with a compatibility layer to transform it to a standard gRPC request for the wrapped gRPC server and transforms the response to comply with the gRPC-Web protocol.

The gRPC-Web compatibility is only invoked if the request is a gRPC-Web request as determined by IsGrpcWebRequest or the request is a pre-flight (CORS) request as determined by IsAcceptableGrpcCorsRequest.

You can control the CORS behaviour using `With*` options in the WrapServer function.

Package grpcweb imports 9 packages (graph) and is imported by 2 packages. Updated 2017-05-14. Refresh now. Tools for package owners.