Documentation ¶
Overview ¶
Package grpchttp implements HTTP/JSON to gRPC transcoding.
To use, define a gRPC service with HTTP bindings:
syntax = "proto3"; // ... import "google/api/annotations.proto"; service Test { rpc GetItem(GetItemRequest) returns(Item) { option (google.api.http) = { get: "/v1/items/{name=*}" }; } } message Item { string name = 1; int64 id = 2; } message GetItemRequest { string name = 1; }
After implememeting the service, the grpchttp package can be used to create a net/http.Handler that translates HTTP/JSON to gRPC:
srv := &myService{} hander, err := grpchttp.NewHandler(&pb.Test_ServiceDesc, srv) if err != nil { // Handle error... } // Listen on port :8080 for HTTP/JSON requests and translate them to be // served by 'srv'. log.Fatal(http.ListenAndServe(":8080", handler))
See google.golang.org/genproto/googleapis/api/annotations.HttpRule for a full list of supported annotation values.
Errors ¶
Errors are supported through gRPC's google.golang.org/grpc/status and google.golang.org/grpc/codes packages. Errors returned to users always use the google.rpc.Status message format, usually wrapping errors with an internal code.
If a method returns a google.golang.org/grpc/status error (for example, by using status.Errorf) the error will be passed back to the user directly:
info := &errdetails.ErrorInfo{ Reason: "STOCKOUT", Domain: "spanner.googleapis.com", Metadata: map[string]string{ "availableRegions": "us-central1,us-east2", }, } any, err := anypb.New(info) if err != nil { // Handle error... } s := &statuspb.Status{ Code: int(codes.ResourceExhausted), Message: "Region out of stock", Details: []&anypb.Any{any}, } return nil, status.FromProto(s) // Response body contains Status message.
See https://google.aip.dev/193 for guidance, details, and RPC status code mappings to HTTP statuses.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler implements HTTP/JSON to gRPC transcoding based on google.api.Http annotations.
func NewHandler ¶
func NewHandler(desc *grpc.ServiceDesc, srv interface{}, opts ...HandlerOption) (*Handler, error)
NewHandler evaluates google.api.Http annotations on a service definition and generates a HTTP handler for the service.
This method returns an error if the service contains RPCs without google.api.http annotations, paths have overlapping templates ("GET /v1/*" and "GET /v1/users"), or annotations aren't well defined (get annotations with bodies).
All service RPCs must have annotations.
type HandlerOption ¶
type HandlerOption interface {
// contains filtered or unexported methods
}
HandlerOption configures an option on the returned handler, such as limiting the number of bytes the handler will read.
func MaxRequestBodySize ¶
func MaxRequestBodySize(m int) HandlerOption
MaxRequestBodySize returns a HandlerOption to set the max message size in bytes the server can receive. If this is not set, the handler uses the default 4MB.