Feature Request: Readme change to explain when to use vanguard-go vs connect-go

[evanmoran]

Hi there! I think this vanguard-go README (and maybe website docs) should have a section at the top explaining when vanguard-go vs connect-go is needed. I spent a little too long trying to figure this out and know that I understand better what vanguard-go is for I suspect most new users of connectrpc would be better off using connect-go by default. Thank you for all your great work, connect is really powerful so far.

Thanks!
-Evan

[nicksnyder]

Hi Evan, based on what you learned from your experience, how would you describe the difference of when to use each? I am curious for your perspective since that would help us understand how we could improve the docs in a way that would have helped you.

[evanmoran]

Hi @nicksnyder! My current understanding came from a response to a question I asked in the Buf slack (thank you, btw :) that if you're writing a service from scratch you're best off using connect-go and then ensuring your clients also use connect-es, connect-swift, etc, so all can use the connect protocol (or grpc if you prefer). The key insight is that vanguard wasn't needed to use connectrpc (and this is idea that I'd make a note of at the top of the vanguard readme).

This makes me guess that if Vanguard wasn't needed for a new connectrpc service then it's purpose must be about existing grpc clients or rest client compatibility, or some need to keep an additional proxy for reasons I don't know of? Not sure! Here's the reddit post I saw that perhaps led me astray. Now that I read it back, it is more likely that they are connect + vanguard is a substitute for grpcgateway, but at the time I was just trying to grok the best way to start a connectrpc project.

https://www.reddit.com/r/golang/comments/1cxpxob/grpcgateway_or_connectrpc_for_a_new_project/

Hope that helps!

[jhump]

@evanmoran, the first line of that Reddit post is the key:

Going to need both gRPC (backend) and REST (frontend) for a new project.

If you need to support a REST API for clients, then connect-go by itself can't necessarily do that. While unary RPCs can appear to be REST-ful POST endpoints if you squint your eyes, this is actually referring to the use of HTTP annotations to expose the endpoints in a more "proper" REST-ful manner, like allowing use of GET, DELETE, PATCH, etc verbs and being able to encode resource names/IDs in the URI path. So if you want to do that, you need to use either gRPC-Gateway, Vanguard (this repo), or Envoy's gRPC-JSON transcoding plugin. The only comment I see in that Reddit thread that mentions vanguard-go suggests using both connect-go and vanguard-go, which is what we recommend for that solution, too.

On re-reading the README, I do see that the opening paragraph could be a little more explicit in terms of context around what it does and maybe include a diagram to make Vanguard's role in a solution more clear. It is meant to be used with connect-go, grpc-go, or in a proxy. It cannot replace connect-go or grpc-go as its purpose is protocol translation, not server RPC implementations.