{"id":16767476,"url":"https://github.com/mfridman/protoc-gen-connectclient-go","last_synced_at":"2025-10-29T20:34:24.077Z","repository":{"id":229544832,"uuid":"775978129","full_name":"mfridman/protoc-gen-connectclient-go","owner":"mfridman","description":"Protobuf plugin to generate a Connect Go client, with batteries 🔋","archived":false,"fork":false,"pushed_at":"2024-08-10T19:00:03.000Z","size":1754,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-21T04:23:33.611Z","etag":null,"topics":["buf","connectrpc","proto","protobuf","protoc","rpc","rpc-client"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfridman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-22T12:37:57.000Z","updated_at":"2025-06-20T13:55:46.000Z","dependencies_parsed_at":"2024-06-21T02:24:07.455Z","dependency_job_id":"9c8ea893-795f-4c4a-b4c2-dcece053b3de","html_url":"https://github.com/mfridman/protoc-gen-connectclient-go","commit_stats":null,"previous_names":["mfridman/protoc-gen-connectclient-go"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mfridman/protoc-gen-connectclient-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfridman%2Fprotoc-gen-connectclient-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfridman%2Fprotoc-gen-connectclient-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfridman%2Fprotoc-gen-connectclient-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfridman%2Fprotoc-gen-connectclient-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfridman","download_url":"https://codeload.github.com/mfridman/protoc-gen-connectclient-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfridman%2Fprotoc-gen-connectclient-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272014485,"owners_count":24858709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buf","connectrpc","proto","protobuf","protoc","rpc","rpc-client"],"created_at":"2024-10-13T06:09:14.117Z","updated_at":"2025-10-29T20:34:19.056Z","avatar_url":"https://github.com/mfridman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoc-gen-connectclient-go\n\nA Protobuf plugin that generates a **single Connect Go client** for all services, batteries included\n🔋. For more information, see the [But why?](#but-why) section.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"examples/client-example.png\" width=800px\u003e\n\u003c/p\u003e\n\n[Connect](https://connectrpc.com/) is a simple, yet robust, RPC framework that allows you to define\nservices using Protobuf and generate clients and servers in multiple languages.\n\nThis plugin MUST be generated alongside the [`protoc-gen-go`\nplugin](https://pkg.go.dev/google.golang.org/protobuf/cmd/protoc-gen-go), as it relies on the\ngenerated base types.\n\n\u003e [!NOTE]\n\u003e\n\u003e There's an experimental feature that uses wasm to generate the base types for the client. Which\n\u003e means this plugin is self-contained and all you need.\n\n## Installation\n\n```shell\ngo install github.com/mfridman/protoc-gen-connectclient-go@latest\n```\n\n## Examples\n\nSee the [examples](./examples) directory for a few practical examples against live Connect services.\n\n## Plugin options\n\nThe plugin supports the following options:\n\n| Option                                      | Default |\n| ------------------------------------------- | ------- |\n| [`seperate_packages`](#separate_packages)   | `false` |\n| [`include_base_types`](#include_base_types) | `false` |\n| [`single_file`](#single_file)               | `false` |\n\n### `separate_packages`\n\nWhen set to `true`, the plugin will generate the client into a seperate package with the `client`\nsuffix, importing the base types from the original package. This is useful when you want to keep the\ngenerated code separate from the original package.\n\n### `include_base_types`\n\nWhen set to `true`, the plugin will invoke the `protoc-gen-go` plugin to generate the base types for\nthe client. This is an experimental feature that uses wasm to generate the base types.\n\n(Not yet implemented)\n\n### `single_file`\n\nWhen set to `true`, the plugin will generate all code into a single file instead of splitting it up\nby service.\n\n(Not yet implemented)\n\n## But why?\n\nI find myself writing a lot of Go clients against Connect services, often in CLIs or other small\napplications. But I don't need the full power of the official Connect library.\n\nHere's a quick list of what this library does and does not do:\n\n- No streaming support\n- **No generics, just plain old structs**\n  - Eliminates the need to wrap messages using `connect.NewRequest/Response`\n- Does not generate Service-related code (very lightweight)\n  - Only one runtime dependency: `google.golang.org/protobuf`\n  - All generated code is self-contained\n- No interceptors, just hooks for tapping into the request and response lifecycle\n- No dependence on generated Connect code or `connectrpc.com/connect` library\n  - Simply uses `POST` over HTTP via `http.DefaultClient` (configurable client)\n- No need to maintain a separate client for each service\n  - Just create a single client with `NewClient` and you're good to go, batteries included 🔋\n- Provides functional options for configuring the client, allowing you to:\n  - Attaching a token when creating the client, which will be used for all requests\n  - Attach a logger to debug requests and responses\n  - Use a custom HTTP client, such as\n    [hashicorp/go-retryablehttp](https://github.com/hashicorp/go-retryablehttp)\n\nThe end goal to generate a **simple client for all your services** without writing a lot of\nboilerplate code. It's not meant to be a full replacement for the official Connect plugin or\nlibrary. If you need streaming, interceptors, or other advanced features, you should use the\nofficial library!\n\n## Gotchas\n\n### Errors\n\nThe generated client does not return Connect errors. If a request was sent, it will return an\n`*HTTPError` and the only fields that are guaranteed to be set are `Code` (this is the HTTP status\ncode, 401, 404, etc.) and `Procedure` (the name of the service method that was called).\n\nWhy not `ConnectCode` or `Message`?\n\nConnect services are typically mounted on a `net/http` router. There might be cases where the\nrequest does not reach the RPC layer, and instead gets handled by middleware that doesn't return a\nConnect error. By uniformly returning an `*HTTPError`, you can handle all errors in a consistent\nmanner.\n\n```go\ntype HTTPError struct {\n\tProcedure   string\n\tCode        int\n\tConnectCode string\n\tMessage     string\n}\n```\n\n## Status\n\nThis is a work in progress.\n\nThe plugin is functional and generates code that works. However, there are still a few things that\nneed to be done.\n\n- [ ] Add tests\n- [ ] Add wasm support for generating the base types\n- [ ] Add method-level options, for more granular control\n- [ ] Add logger support with debug and info levels\n- [ ] See if there's low hanging fruit for performance improvements and the client adheres to best\n      practices against Connect services\n- [ ] See if it's possible to make the golden templates a reusable package, maybe one already\n      exists?\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfridman%2Fprotoc-gen-connectclient-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfridman%2Fprotoc-gen-connectclient-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfridman%2Fprotoc-gen-connectclient-go/lists"}