grpchttp

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.