feat: Experiment with Vanguard transcoding (#91)

Makefile

@@ -31,4 +31,4 @@ all: check_pkgx stop
 stop:
 	pkgx killport@latest 7233
 	sleep 1
-	pkgx docker-clean stop
+	pkgx docker compose stop

README.md

@@ -118,7 +118,7 @@ pkgx grpcurl \
     "name": "Org 1"
   },
   "profile": {
-    "name": "Kevin Chen"
+    "full_name": "Kevin Chen"
   }
 }
 EOM

cmd/saga/start/app/app.go

@@ -31,9 +31,7 @@ var Module = fx.Options(
 				Handler: handler,
 			}
 		},
-		Services: []string{
-			"temporalv1beta1.TemporalService",
-		},
+		Service: temporalConnect.TemporalServiceName,
 	}),
 	logging.Module,
 	modService.Module,

cmd/svc/license/app/app.go

@@ -30,9 +30,7 @@ var Module = fx.Options(
 				Handler: handler,
 			}
 		},
-		Services: []string{
-			"licensev1beta1.LicenseService",
-		},
+		Service: licenseConnect.LicenseServiceName,
 	}),
 	logging.Module,
 	modService.Module,

cmd/svc/org/app/app.go

@@ -30,9 +30,7 @@ var Module = fx.Options(
 				Handler: handler,
 			}
 		},
-		Services: []string{
-			"orgv1beta1.OrgService",
-		},
+		Service: orgv1beta1connect.OrgServiceName,
 	}),
 	logging.Module,
 	modService.Module,

cmd/svc/profile/app/app.go

@@ -30,9 +30,7 @@ var Module = fx.Options(
 				Handler: handler,
 			}
 		},
-		Services: []string{
-			"profilev1beta1.ProfileService",
-		},
+		Service: profilev1beta1connect.ProfileServiceName,
 	}),
 	logging.Module,
 	modService.Module,

docs/upstreams.md

@@ -8,36 +8,29 @@ Some quick curl commands to communicate with each of the 3 microservices.
 ### Org Service
 
 ```shell
-curl -v http://localhost:9090/org.v1beta1.OrgService/CreateOrg \
-  -H "Content-Type: application/json" \
-  -d '{"name": "Org1"}'
-
-http POST \
+pkgx http POST \
   http://localhost:9090/org.v1beta1.OrgService/CreateOrg \
     name="Org1"
+
+pkgx http http://localhost:9090/orgs/"$(pkgx gum input --placeholder "id")"
 ```
 
 ### Profile Service
 
 ```shell
-curl -v http://localhost:9091/profile.v1beta1.ProfileService/CreateProfile \
-  -H "Content-Type: application/json" \
-  -d '{"full_name": "Kevin Chen"}'
-
-http POST \
+pkgx http POST \
   http://localhost:9091/profile.v1beta1.ProfileService/CreateProfile \
     full_name="Kevin Chen"
+
+pkgx http http://localhost:9091/profiles/"$(pkgx gum input --placeholder "id")"
 ```
 
 ### License Service
 
 ```shell
-curl -v http://localhost:9092/license.v1beta1.LicenseService/CreateLicense \
-  -H "Content-Type: application/json" \
-  -d '{"start": "2023-11-16T12:00:00Z", "end": "2024-01-16T12:00:00Z"}'
-
-http POST \
-  http://localhost:9092/license.v1beta1.LicenseService/CreateLicense \
-    start="2023-11-16T12:00:00Z" \
-    end="2024-01-16T12:00:00Z"
+pkgx http POST \
+  http://localhost:9092/license.v1beta1.LicenseService/GetLicense \
+    id="$(pkgx gum input --placeholder "id")"
+
+pkgx http http://localhost:9092/licenses/"$(pkgx gum input --placeholder "id")"
 ```

go.mod

@@ -15,6 +15,7 @@ require (
 	connectrpc.com/grpchealth v1.3.0
 	connectrpc.com/grpcreflect v1.2.0
 	connectrpc.com/otelconnect v0.6.0
+	connectrpc.com/vanguard v0.1.0
 	github.com/bufbuild/protovalidate-go v0.4.3
 	github.com/friendsofgo/errors v0.9.2
 	github.com/google/uuid v1.5.0

go.sum

@@ -779,6 +779,8 @@ connectrpc.com/grpcreflect v1.2.0 h1:Q6og1S7HinmtbEuBvARLNwYmTbhEGRpHDhqrPNlmK+U
 connectrpc.com/grpcreflect v1.2.0/go.mod h1:nwSOKmE8nU5u/CidgHtPYk1PFI3U9ignz7iDMxOYkSY=
 connectrpc.com/otelconnect v0.6.0 h1:VJAdQL9+sgdUw9+7+J+jq8pQo/h1S7tSFv2+vDcR7bU=
 connectrpc.com/otelconnect v0.6.0/go.mod h1:jdcs0uiwXQVmSMgTJ2dAaWR5VbpNd7QKNkuoH7n86RA=
+connectrpc.com/vanguard v0.1.0 h1:2fJzlO4o0Bh3b6A7uQdEe27Gj2mzjAOLwawm4cPIJHw=
+connectrpc.com/vanguard v0.1.0/go.mod h1:VNtMHNwYYDPOhQRmBzojK8WqqkoX3ul9PB0+M+HXO1Y=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
 gioui.org v0.0.0-20210308172011-57750fc8a0a6/go.mod h1:RSH6KIUZ0p2xy5zHDxgAM4zumjgTw83q2ge/PI+yyw8=
 git.sr.ht/~sbinet/gg v0.3.1/go.mod h1:KGYtlADtqsqANL9ueOFkWymvzUvLMQllU5Ixo+8v3pc=

pkg/fxmod/connect/connect.go

@@ -11,6 +11,7 @@ import (
 
 	"connectrpc.com/grpchealth"
 	"connectrpc.com/grpcreflect"
+	"connectrpc.com/vanguard"
 	"github.com/bufbuild/protovalidate-go"
 	"github.com/sethvargo/go-envconfig"
 	"github.com/sirupsen/logrus"
@@ -33,6 +34,7 @@ func CreateModule(opts *ModuleOptions) fx.Option {
 			NewConfig,
 			NewServer,
 			NewValidator,
+			NewTranscoder,
 		),
 		fx.Invoke(
 			Register,
@@ -64,11 +66,10 @@ type ModuleOptions struct {
 	// HandlerProvider - Provides a Connect Go HTTP handler and the path to
 	// mount it on.
 	HandlerProvider any
-	// Services - Fully-qualified protobuf service names.
-	// For example:
-	//   - "acme.user.v1.UserService"
-	//   - "acme.userv1beta.UserService"
-	Services []string
+	// Service - Fully-qualified protobuf service names.
+	// (For example, "acme.user.v1.UserService"). Generated Connect service
+	// files have this declared as a constant.
+	Service string
 }
 
 // Config - Contains env vars for our Connect Go server.
@@ -144,24 +145,44 @@ func NewServer(lifecycle fx.Lifecycle, cfg Config) *http.ServeMux {
 	return mux
 }
 
+// NewTranscoder - Creates a transcoder from the REST protocol to the Connect
+// protocol.
+func NewTranscoder(
+	opts *ModuleOptions,
+	handlerOutput HandlerOutput,
+) (http.Handler, error) {
+	// HTTP transcoding annotations are used to also support REST-ful URI paths for each method.
+	//
+	// The returned handler also acts like a middleware, transparently "upgrading"
+	// the RPC handlers to support incoming request protocols they wouldn't otherwise
+	// support. This can be used to upgrade Connect handlers to support REST requests
+	// (based on HTTP transcoding configuration)
+	handler, err := vanguard.NewTranscoder(
+		[]*vanguard.Service{
+			vanguard.NewService(
+				opts.Service,
+				handlerOutput.Handler,
+			),
+		},
+	)
+	if err != nil {
+		return nil, fmt.Errorf("unable to create connect transcoder: %w", err)
+	}
+
+	return handler, nil
+}
+
 // Register - Registers the Connect Go service to its HTTP handlers.
 func Register(
 	opts *ModuleOptions,
 	mux *http.ServeMux,
 	handlerOutput HandlerOutput,
+	_ http.Handler,
 ) {
-	checker := grpchealth.NewStaticChecker(
-		// protoc-gen-connect-go generates package-level constants
-		// for these fully-qualified protobuf service names, so we'd be able
-		// to reference foov1beta1.FooService as opposed to
-		// foo.v1beta1.FooService.
-		opts.Services...,
-	)
+	checker := grpchealth.NewStaticChecker(opts.Service)
 	mux.Handle(grpchealth.NewHandler(checker))
 
-	reflector := grpcreflect.NewStaticReflector(
-		opts.Services...,
-	)
+	reflector := grpcreflect.NewStaticReflector(opts.Service)
 	mux.Handle(grpcreflect.NewHandlerV1(reflector))
 	// Many tools still expect the older version of the server reflection API,
 	// so most servers should mount both handlers.

taskfiles/run.yml

@@ -19,7 +19,7 @@ tasks:
     run: once
     desc: "Runs Docker Compose infra"
     cmds:
-      - pkgx docker-clean stop
+      - docker compose stop
       - docker compose up -d
       - task: migrate