https://github.com/vallahaye/connect-gateway
gRPC-Gateway to Connect local binding generator
https://github.com/vallahaye/connect-gateway
connect go golang grpc-gateway protobuf protocol-buffers
Last synced: 9 months ago
JSON representation
gRPC-Gateway to Connect local binding generator
- Host: GitHub
- URL: https://github.com/vallahaye/connect-gateway
- Owner: vallahaye
- License: apache-2.0
- Created: 2023-03-09T19:02:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-11T15:49:03.000Z (over 1 year ago)
- Last Synced: 2024-11-12T23:35:12.708Z (over 1 year ago)
- Topics: connect, go, golang, grpc-gateway, protobuf, protocol-buffers
- Language: Go
- Homepage: https://go.vallahaye.net/connect-gateway
- Size: 58.6 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Connect-Gateway
[](https://pkg.go.dev/go.vallahaye.net/connect-gateway)
[](https://goreportcard.com/report/go.vallahaye.net/connect-gateway)
The Connect-Gateway introduces direct binding from [gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) local handlers to [Connect](https://connectrpc.com/) service handlers. It addresses the recurring request to support Google API HTTP annotations in Connect:
- [Service option for Connect HTTP path #468](https://github.com/connectrpc/connect-go/issues/468)
- [`google.api.Http` annotation support #274](https://github.com/connectrpc/connect-go/issues/274)
We provide a complete solution for the two to communicate seamlessly through simple function calls, without relying on network communications. All of which is done by reusing as much of the code from both projects as possible and mimicking the [connect-go](https://github.com/connectrpc/connect-go) implementation, i.e. reducing code generation as much as possible, with most of the logic being provided in a library.
### Features
- Unary calls support
- Connect interceptors support
- Bidirectional gRPC metadata transmission
- Connect errors to gRPC errors convertion
### Limitations
- No support for streaming calls as [it is not yet supported by the gRPC-Gateway's "in-process" transport mode](https://github.com/grpc-ecosystem/grpc-gateway/blob/main/protoc-gen-grpc-gateway/internal/gengateway/template.go#L621)
- Uninitialized [Request.Peer](https://pkg.go.dev/connectrpc.com/connect#Request.Peer) and [Request.Spec](https://pkg.go.dev/connectrpc.com/connect#Request.Spec) properties on Connect requests as it cannot be set externally
## Getting started
### Install tools
First, we'll need to install the `protoc-gen-connect-gateway` code generation tool:
```
$ go install go.vallahaye.net/connect-gateway/cmd/protoc-gen-connect-gateway@latest
```
Make sure that the binary is accessible from your `PATH`:
```
$ which protoc-gen-connect-gateway
/go/bin/protoc-gen-connect-gateway
```
### Generate code
Assuming [Buf code generation](https://buf.build/docs/generate/overview) is already configured for [Protocol Buffers](https://buf.build/protocolbuffers/go), [gRPC](https://buf.build/grpc/go), the [gRPC-Gateway](https://buf.build/grpc-ecosystem/gateway) and [Connect](https://buf.build/connectrpc/go), add the Connect-Gateway plugin to your `buf.gen.yaml` file:
```yaml
version: v2
plugins:
- local: protoc-gen-connect-gateway
out: gen
opt: paths=source_relative
```
Then run the `buf generate` command to generate code.
Applying this configuration to the [Connect Greet service example](https://connectrpc.com/docs/go/getting-started/#define-a-service) produces the following output, where the `greet.connect.gw.go` file contains the adapter to interface the gRPC gateway with the Connect server handlers for the `GreetService`:
```shell
gen
└── greet
└── v1
├── greet_grpc.pb.go
├── greet.pb.go
├── greet.pb.gw.go
└── greetv1connect
├── greet.connect.go
└── greet.connect.gw.go
```
### Implement handler
We use the code generated by instantiating a [gRPC-Gateway router](https://pkg.go.dev/github.com/grpc-ecosystem/grpc-gateway/v2/runtime#ServeMux) and registering Connect server handlers with it, using the helper function generated by the Connect-Gateway plugin:
```go
package main
import (
"context"
"fmt"
"log"
"net/http"
"connectrpc.com/connect"
"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
greetv1 "example/gen/greet/v1"
"example/gen/greet/v1/greetv1connect"
)
type GreetServer struct{}
func (s *GreetServer) Greet(
ctx context.Context,
req *connect.Request[greetv1.GreetRequest],
) (*connect.Response[greetv1.GreetResponse], error) {
log.Println("Request headers: ", req.Header())
res := connect.NewResponse(&greetv1.GreetResponse{
Greeting: fmt.Sprintf("Hello, %s!", req.Msg.Name),
})
res.Header().Set("Greet-Version", "v1")
return res, nil
}
func main() {
greeter := &GreetServer{}
mux := runtime.NewServeMux()
greetv1connect.RegisterGreetServiceHandlerGatewayServer(mux, greeter)
http.ListenAndServe(":8080", mux)
}
```