google.api.Http annotation support

[rauanmayemir]

Describe the solution you'd like
I would like to switch over to connect from grpc json transcoding, but prefer to hide grpc implementation details that heavily leak when you have your consumers call /package.Service/Method.

It would be great if connect supported some subset of google.api annotations or maybe come up with its own protobuf extension (the latter would be even better).

     service Messaging {
       rpc GetMessage(GetMessageRequest) returns (Message) {
         option (google.api.http) = {
             get: "/v1/{name=messages/*}"
         };
       }
     }

[bufdev]

We have part of the solution to this already, and the remainder is on our roadmap:

• The Connect protocol allows you to POST requests as JSON, alongside our gRPC (and gRPC-Web) support. See our documentation on browsers and cURL for additional details.
• In addition, we're looking to extend the Connect protocol to include GET support for endpoints with no side effects. See future extensions for more details.

[nico151999]

As outlined in issue #313 I opened before being guided to this one I would appreciate support for configurable REST calls defined in the proto files as well. As I was asked to explain why I think this makes sense I would like to share my points with you. Many users prefer REST over gRPC. Even though I really like gRPC many others still prefer REST over gRPC since it's easier and quicker to apply in some fields. I realised that it is not possible to enforce gRPC-APIs in any environment due to technical obstacles or simply some people's preferences. A co-existence of REST and gRPC would be a good solution to the problem in my opinion. POST-only HTTP endpoints are not really what a REST API consumer would expect. It works and it does its job if I want to debug an API with curl for example. However, in usual REST-APIs there are more individual requirements when it comes to the path and the HTTP method. Consequently, this should be configurable. This does not necessarily need to replace the connect protocol's HTTP POST endpoint if configured but can alternatively be configured to co-exist (the default connect protocol endpoint and optionally the REST endpoint if defined in the proto file). The existence of the connect protocol's endpoint would still be valid. An option that can be passed to the protoc plugin that decides if the connect protocol and the configured REST endpoint should co-exist or if configured REST endpoints should replace the connect endpoints would be a potential solution. I'd really appreciate to read your opinion. Thanks!

[akshayjshah]

I'd love to learn more about what you mean by this:

However, in usual REST-APIs there are more individual requirements when it comes to the path and the HTTP method.

Is there a technical problem you're running into that requires configurable paths & HTTP verbs? We understand that many developers have a preference for RESTful paths and HTTP verbs, but we're also trying to identify the technical requirements that people have.

[nico151999]

I wouldn't call it a technical problem that I'm facing. The connect protocol understands HTTP so one can technically use the connect protocol with a usual HTTP client. Considering that the connect protocol is an individual protocol that only makes use of HTTP but does not follow its semantics this is absolutely fine but it's not sufficient if one wants to have a REST API. RFC7231 defines the semantics one would expect from a REST API. This includes suitably chosen HTTP methods and paths for each endpoint. We should look at connect and REST as two different protocols that can co-exist just like gRPC, gRPC Web and connect co-exist in connect-go already. They are all based on HTTP. The significant difference to the co-existence of gRPC and connect is that both REST and connect can communicate with a usual HTTP client like curl.

[lixin9311]

There is already grpc-gateway.
You can easily integrate it in to your http handler.

[nico151999]

Right, there is. In some cases I even want to use some kind of gateway. In such cases Envoy can also do a great job. But in a minimal setup I might not want to rely on intermediate components. Then, direct support would be a helpful option. It would definitely improve the flexibility if one could decide on one's own where to do the REST translation.

[anhnmt]

I found this project, hope it helps you https://github.com/johanbrandhorst/connect-gateway-example

[p1ass]

Does the existence of users_grpc.pb.go mean that we also need to generate grpc-go, not just connect-go?

[vallahaye]

Hello everyone !

We may have done what you're looking for, which is something to easily bind Connect handlers to the Google API HTTP request specifications defined with your services' RPCs.

To do this, we wrote a very simple code generator to produce all the boilerplate needed to bind local gRPC Gateway handlers with Connect handlers. No network communication, no request re-encoding, just simple function calls like so:

Pros:

• Not reinventing the wheel
• All gRPC Gateway features are supported

Cons:

• You need to generate the grpc-gateway and the grpc-go codegens in addition to the connect-go codegens
• No support for streaming calls

Here is the link to our repository: https://github.com/vallahaye/connect-gateway

@bufdev I've seen this feature requested many times in the past. If you're satisfied with our implementation, feel free to link our repository next time someone asks for "Google API HTTP annotations support" 😉

[emcfarlane]

I have a project that wraps gRPC servers with HTTP annotations called larking. It works wrapping the expected grpc.ServiceRegistrar and building up the mux on the fly without codegen.

I was hoping to start a port to connect-go. My library would greatly benefit removing the gRPC server stack as it already uses the (experimental) gRPC ServeHTTP option for cloud run support. For the implementation I'd currently need to take the string response from the connect generated: NewMux() (string, http.ServeMux) and then pass that to a func like:

// svc == /service.Name/` and ss is the connect implementation
func (m *Mux) RegisterConnectService(svc string, ss any) {}

Which could lookup the service descriptors, then with reflection access the server implementation. It would be nice for the generated code to describe the mapping like grpc.ServiceDesc{...} and for the generated code to provide the register hook for typesafety. Would be great to get feedback and any other approaches!

[emcfarlane]

Vanguard has just been released! It implements RPC & REST protocol transcoding as a simple http handler and supports connect out of the box. See the docs for creating a REST to RPC transcoder.