protoc-gen-connectclient-go

protoc-gen-connectclient-go

A Protobuf plugin that generates a single Connect Go client for all services, batteries included 🔋. For more information, see the But why? section.

Connect is a simple, yet robust, RPC framework that allows you to define services using Protobuf and generate clients and servers in multiple languages.

This plugin MUST be generated alongside the protoc-gen-go plugin, as it relies on the generated base types.

[!NOTE]

There's an experimental feature that uses wasm to generate the base types for the client. Which means this plugin is self-contained and all you need.

Installation

go install github.com/mfridman/protoc-gen-connectclient-go@latest

Examples

See the examples directory for a few practical examples against live Connect services.

Plugin options

The plugin supports the following options:

separate_packages

When set to true, the plugin will generate the client into a seperate package with the client suffix, importing the base types from the original package. This is useful when you want to keep the generated code separate from the original package.

include_base_types

When set to true, the plugin will invoke the protoc-gen-go plugin to generate the base types for the client. This is an experimental feature that uses wasm to generate the base types.

(Not yet implemented)

single_file

When set to true, the plugin will generate all code into a single file instead of splitting it up by service.

(Not yet implemented)

But why?

I find myself writing a lot of Go clients against Connect services, often in CLIs or other small applications. But I don't need the full power of the official Connect library.

Here's a quick list of what this library does and does not do:

• No streaming support
• No generics, just plain old structs
  • Removes the need to wrap messages using connect.NewRquest and connect.NewRespons
• Does not generate Service-related code (very lightweight)
  • No runtime libraries, all generated code is self-contained
• No interceptors, just hooks for tapping into the request and response lifecycle
• No dependencies on generated Connect code or connectrpc.com/connect library
  • It's just POST and application/json over HTTP using http.DefaultClient (you can override the default client)
  • Only one runtime dependency: google.golang.org/protobuf
• No need to maintain a separate client for each service
  • Just create a single client with NewClient and that's it, batteries included 🔋
• Functional options to tailor the client to your needs
  • Attach a token when the client is created, and it will be used for all requests
  • Attach an optional logger
  • Use a custom HTTP client, such as a retryable client like hashicorp/go-retryablehttp

The end goal to generate a simple client for all your services without writing a lot of boilerplate code. It's not meant to be a full replacement for the official Connect plugin or library. If you need streaming, interceptors, or other advanced features, you should use the official library.

Gotchas

Errors

The generated client does not return Connect errors. If a request was sent, it will return an *HTTPError and the only field that is gauranteed to be set is Code (this is the HTTP status code, 401, 404, etc.).

Connect services are typically mounted on a net/http router and the request maybe not reach the rpc layer, getting handled by middleware which do not return a Connect error.

type HTTPError struct {
	Procedure   string
	Code        int
	ConnectCode string
	Message     string
}

Status

This is a work in progress.

The plugin is functional and generates code that works. However, there are still a few things that need to be done.

• Add tests
• Add wasm support for generating the base types
• Add method-level options, for more granular control
• Add logger support with debug and info levels
• See if there's low hanging fruit for performance improvements and the client adheres to best practices against Connect services
• See if it's possible to make the golden templates a reusable package, maybe one already exists?

License

This project is licensed under the MIT License - see the LICENSE file for details.