connectrpc/vanguard-go v0.5.0

on GitHub

What's new for connect-go v2

Vanguard v0.5 is re-architected for connect-go v2. While the module path remains connectrpc.com/vanguard, this version introduces a breaking change requiring connectrpc.com/connect v2. The v0.4.x release series is the final release line compatible with connect-go v1. Applications continuing to use connect-go v1 should pin connectrpc.com/vanguard@v0.4.

In v0.4, Vanguard operated as an edge proxy translating between REST, Connect, gRPC, and gRPC-Web protocols. Because connect-go v2 natively handles Connect, gRPC, and gRPC-Web through a unified connect.Server, Vanguard now focuses exclusively on REST transcoding.

The vanguard.Mount function registers a connect.Server over HTTP using protobuf google.api.http annotations. The legacy Transcoder, Service, and Protocol types have been removed:

-services := []*vanguard.Service{
-     vanguard.NewService(pingv1connect.PingServiceName, handler),
-}
-transcoder, err := vanguard.NewTranscoder(services)
-if err != nil {
-     return err
-}
-mux.Handle("/", transcoder)
+server := connect.NewServer()
+pingv1connect.RegisterPingServiceHandler(server, &pingServer{})
+connecthttp.Mount(mux, server) // Connect, gRPC, gRPC-Web
+if err := vanguard.Mount(mux, server); err != nil { // REST
+     return err
+}

Incoming REST requests are dispatched through connect.Server.Call. This means interceptors registered on the server now execute uniformly across both REST requests and RPC invocations.

For gRPC server implementations, vanguardgrpc.NewTranscoder(grpcServer) has been replaced by vanguardgrpc.NewServiceRegistrar(server). This allows existing protoc-gen-go-grpc service implementations to be registered directly with a connect.Server:

-grpcServer := grpc.NewServer()
-pingv1grpc.RegisterPingServiceServer(grpcServer, &pingServer{})
-transcoder, err := vanguardgrpc.NewTranscoder(grpcServer)
+server := connect.NewServer()
+pingv1grpc.RegisterPingServiceServer(vanguardgrpc.NewServiceRegistrar(server), &pingServer{})
+connecthttp.Mount(mux, server)
+err := vanguard.Mount(mux, server)

New features

• Client-Side REST Transport: NewTransport returns a connect.Transport configured to communicate with REST endpoints. Generated Connect client stubs can use this transport to invoke REST APIs defined by google.api.http annotations.

• Upstream Forwarding: Forward and ForwardService replace the manual creation of proxy handlers via NewService. These functions register handlers on a connect.Server that forward calls directly to an upstream connect.Client, allowing you to expose REST endpoints in front of a remote service without requiring locally generated service code.

• Chunked REST Streaming: Streaming over REST is supported for unary/stream and stream/unary RPCs when using google.api.HttpBody. Payloads are streamed incrementally and are not buffered entirely in memory. Note that streaming without this message type is not supported and will error on registration.

Option migration

Options have been unified under a single Option type shared between Mount and NewTransport:

The v2 migration guide covers the change. The migration tool doesn't rewrite Vanguard. It flags the import and each v1 call site for you to update by hand. See #203 for details.

Compatibility Rationale: connect-go v1 vs. v2

Packages such as otelconnect (v0.12.0) and validate (v0.9.0) preserved connect-go v1 compatibility to facilitate incremental, per-service upgrades within a single codebase. Because interceptors are configured at the individual service level, a single binary may temporarily require both v1 and v2 interceptor chains.

Vanguard serves as a top-level HTTP ingress adapter wrapping the underlying connect.Server. Therefore, Vanguard is upgraded in lockstep with the server multiplexer. Retaining backwards compatibility would require maintaining the legacy translation engine alongside the v2 adapter architecture with no migration benefit.

If your application cannot yet upgrade to connect-go v2, remain on connectrpc.com/vanguard@v0.4 until all registered services have been migrated.

To upgrade, run:

go get connectrpc.com/vanguard@v0.5.0

Governance

• Add Philip Warren as a maintainer by @emcfarlane in #200 🎉

Enhancements

• Reduce internal message state to a single buffer by @emcfarlane in #185
• Use mime.ParseMediaType for REST Content-Type validation by @neilshweky in #189
• Implement Upload and Download for fileserver example by @emcfarlane in #186
• Rebuild Vanguard as a REST transport for connect-go v2 by @emcfarlane in #203
• Improve query parsing by @emcfarlane in #205
• Improve path parsing by @emcfarlane in #204

Bugfixes

• Fix multi-segment bounded path variables with %2F by @sudorandom in #190
• Fix memory leak potential by not calling op.cancel() by @sudorandom in #191

New Contributors

• @neilshweky made their first contribution in #189
• @sudorandom made their first contribution in #190

Full Changelog: v0.4.0...v0.5.0