Skip to content
Connect
Created by

gRPC compatibility

Connect fully supports the gRPC and gRPC-Web protocols, including streaming. We validate our implementation of these protocols using an extended version of Google’s own interoperability tests.

Handlers

Section titled “Handlers”

Handlers support the gRPC protocol by default: they work with grpc-go, grpcurl, and any other gRPC client using TLS without any special configuration. To support gRPC clients using HTTP/2 without TLS, use Protocols.SetUnencryptedHTTP2 as described in the deployment documentation.

Handlers also automatically support the binary gRPC-Web protocol directly, without a translating proxy like Envoy. Since modern browsers all support binary payloads, Connect doesn’t support gRPC-Web’s text mode: if you’re using protoc-gen-grpc-web, you must use mode=grpcweb when generating code.

Many gRPC-specific tools depend on server reflection, which lets callers access your service’s Protobuf schema at runtime. Connect supports server reflection with the connectrpc.com/grpcreflect/v2 package. Keep in mind that there are two versions of the gRPC server reflection API, and many tools (including grpcurl) still use the older one — grpcreflect.Register serves both.

Container orchestration and health-checking systems often support the gRPC health checking API. If you’d prefer gRPC-style health checks instead of more traditional HTTP checks, use connectrpc.com/grpchealth/v2 and register a checker with grpchealth.Register.

Clients

Section titled “Clients”

Clients default to using the Connect protocol. To use the gRPC or gRPC-Web protocols, use the connecthttp.WithGRPC or connecthttp.WithGRPCWeb options during transport construction. If the gRPC server is using TLS, Connect clients work with no further configuration. If the gRPC server is using HTTP/2 without TLS, configure your HTTP client using Protocols.SetUnencryptedHTTP2 as described in the deployment documentation.

Migration

Section titled “Migration”

There’s no ironclad guide to migrating an existing grpc-go service to connect-go — every codebase uses a different subset of grpc-go features and will need a slightly different approach. Unlike many RPC framework migrations, remember that you do not need to modify your service’s clients: they can continue to use their current gRPC clients. Your current Protobuf schema will also work without modification.

The particulars of your codebase will be unique, but most migrations include a few common steps:

  1. Begin generating code with protoc-gen-connect-go. During the migration, your code can import connect-go and grpc-go code without any problems.
  2. Change your service implementations to match the Connect handler interfaces. Unary signatures use plain Protobuf messages, much like grpc-go. Rather than grpc-go’s metadata APIs, read and write metadata through the CallInfo in the context.
  3. Where necessary, change your service implementations to return Connect errors. Connect and gRPC use the same error codes, so this is often a straightforward replacement of status.Error with connect.NewError.
  4. Migrate any streaming handlers to use the generated stream types. These are broadly similar to their grpc-go equivalents.
  5. Once you’ve migrated your service implementations to Connect, switch your main function to register the handlers on a connect.NewServer, mount them on a net/http server with connecthttp.Mount, and stop using grpc-go. Remember to use h2c if your service’s clients aren’t using TLS. At this point, you’re halfway done: your service should compile, and you could deploy it without migrating your calls to downstream services.
  6. Next, tackle your downstream calls. Switch to Connect’s generated client types, constructed with connect.NewClient over a connecthttp.NewTransport. Rather than using call options, read and write metadata through the CallInfo from connect.NewClientContext. Don’t forget to use connecthttp.WithGRPC when constructing your transport, and if necessary configure your HTTP clients to use h2c.
  7. Where necessary, switch from status.Code and status.FromError to connect.CodeOf and the standard library’s errors.As.
  8. Migrate any streaming calls to the generated stream types.
  9. You’re done! Unless your service is in the same repository as its clients, you can stop generating code with protoc-gen-go-grpc.