connectaip

README

connect-aip

Connect RPC → Google AIP-shaped REST codegen for Go, TypeScript, and Python.

Motivation

Connect RPC speaks gRPC, gRPC-Web, and JSON-over-POST out of the box. None of these is the REST shape that browsers, third-party API consumers, and AIP-aligned API gateways expect: collection-rooted paths, AIP-160 filtering, AIP-158 pagination, idiomatic HTTP verbs.

connect-aip fills the gap with three protoc plugins (protoc-gen-aip-go, protoc-gen-aip-ts, protoc-gen-aip-py) that read google.api.http annotations and emit AIP-130-style REST handlers and clients in three languages, plus a small Go and Python runtime that does the request forwarding.

The codegen is opinionated toward Google AIP conventions. Non-AIP google.api.http rules may technically work but are not the supported path; the design choice is reflected in the project's name.

Server-streaming methods are routed through firetiger-oss/connect-sse so browsers can consume them over plain fetch.

Install

Go (codegen + runtime)

go install github.com/firetiger-oss/connect-aip/cmd/protoc-gen-aip-go@latest

Prebuilt binaries for linux/{amd64,arm64} and darwin/{amd64,arm64} are attached to each GitHub Release.

TypeScript (codegen only — runtime is inlined)

go install github.com/firetiger-oss/connect-aip/cmd/protoc-gen-aip-ts@latest

Python (codegen + runtime)

go install github.com/firetiger-oss/connect-aip/cmd/protoc-gen-aip-py@latest
pip install connectaip

Usage

Annotate your Connect RPC service with google.api.http rules, then run any of the plugins via buf:

# buf.gen.yaml
plugins:
  - local: protoc-gen-aip-go
    out: proto/go
    opt: [paths=source_relative]
    strategy: all

For each service with at least one usable HTTP rule, the Go plugin emits a *_aip.connect.go file alongside the standard *.connect.go, exposing NewServiceAIPHandler (an iter.Seq2[string, http.Handler] for http.ServeMux) and NewServiceAIPClient (a typed REST client wrapping connect.HTTPClient).

The TypeScript plugin emits *_aip.ts with a *AIPClient class per service. The runtime is inlined into each generated file (no separate npm package).

The Python plugin emits *_aip.py with a *AIPClient class per service that uses httpx for transport. Install the connectaip runtime alongside.

License

Apache 2.0

Documentation

Overview

Package connectaip provides the runtime for AIP-shaped REST endpoints generated by the protoc-gen-aip-{go,ts,py} plugins.

The runtime forwards HTTP requests received on AIP-style routes (e.g. POST /v1/resources, GET /v1/resources/{name}) to the corresponding Connect RPC procedure handlers. Server-streaming methods are forwarded to a connect-sse Server (see github.com/firetiger-oss/connect-sse).

Most users will not import this package directly; instead, run protoc-gen-aip-go on services with google.api.http annotations and call the generated NewServiceAIPHandler / NewServiceAIPClient constructors.

Index

• func Forward[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler)
• func ForwardWithBody[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler, ...)
• func ForwardWithPathVars[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler, ...)
• func Handle(mux *http.ServeMux, handlers iter.Seq2[string, http.Handler])
• func NewLoopbackTransport(handler http.Handler) http.RoundTripper
• func NewSSEClient(httpClient connect.HTTPClient, rawURL string, ...) connect.HTTPClient
• func SSEProcedureURL(baseURL, procedure string) string
• func SplitMultiWildcard(val, prefix, sep string, idx int) string
• type Client
  • func NewClient[Req, Resp any](httpClient connect.HTTPClient, baseURL string, spec MethodSpec, ...) *Client[Req, Resp]
  • func (c *Client[Req, Resp]) Call(ctx context.Context, req *Req) (*Resp, error)
• type ClientOption
  • func WithHeader(key, value string) ClientOption
  • func WithInterceptors(interceptors ...connect.UnaryInterceptorFunc) ClientOption
• type MethodSpec
• type PathVar

Functions

func Forward

func Forward[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler)

Forward clones the request, rewrites URL/method, and forwards to the ConnectRPC handler. Used for POST/PATCH with body: "*" and no path variables.

func ForwardWithBody

func ForwardWithBody[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler, reqMsg Req)

ForwardWithBody clones the request, applies path vars and query params, and forwards. Used for GET/DELETE requests.

func ForwardWithPathVars

func ForwardWithPathVars[Req, Resp proto.Message](w http.ResponseWriter, req *http.Request, path string, handler http.Handler, pathVarsMsg Req)

ForwardWithPathVars clones the request, merges path variables into the body, and forwards. Used for POST/PATCH with body: "*" and path variables.

func Handle

func Handle(mux *http.ServeMux, handlers iter.Seq2[string, http.Handler])

Handle registers all handlers from the iterator with the mux.

func NewLoopbackTransport

func NewLoopbackTransport(handler http.Handler) http.RoundTripper

NewLoopbackTransport returns an http.RoundTripper that dispatches every request directly to the provided handler, bypassing the network. This lets in-process callers use a generated REST client (which speaks HTTP) to invoke the same mux that the external API handlers are registered on — no TCP, no port binding, no startup ordering gymnastics.

Wrap it in &http.Client{Transport: ...} at the call site. Returning the transport (not a *http.Client) keeps the primitive composable with other RoundTripper middleware (auth, tracing, retry) and avoids inheriting default-Client behaviors like redirect following and a cookie jar that don't make sense for loopback traffic.

Use this to wire REST clients to the api_server's own mux for service-to-service calls that used to be in-process ConnectRPC calls.

func NewSSEClient

func NewSSEClient(httpClient connect.HTTPClient, rawURL string, pathVarFn func([]byte) iter.Seq2[string, string], opts ...ClientOption) connect.HTTPClient

NewSSEClient creates a connect.HTTPClient suitable for server-streaming REST calls via SSE. rawURL is the full target URL (e.g. baseURL+"/v2/query"); url.Parse is used to decode it. pathVarFn, if non-nil, is called with the JSON-encoded message from each request to substitute path-variable placeholders (e.g. "{name}") in the URL.

func SSEProcedureURL

func SSEProcedureURL(baseURL, procedure string) string

SSEProcedureURL returns the URL to pass to connect.NewClient for server-streaming REST methods. It strips any path component from baseURL so that the Connect procedure path is not prefixed in the nested SSE request (which would break handler dispatch).

func SplitMultiWildcard

func SplitMultiWildcard(val, prefix, sep string, idx int) string

SplitMultiWildcard extracts one segment from a multi-wildcard resource name. It trims prefix from val, splits on sep, and returns the element at idx. If the split produces fewer parts than idx+1 (malformed name), it returns "".

This is used in generated PathVars helpers for patterns like {name=agents/*/slos/*}.

Types

type Client

type Client[Req, Resp any] struct {
	// contains filtered or unexported fields
}

Client is a generic REST client for a single method. It uses connect.HTTPClient for compatibility with ConnectRPC clients.

func NewClient

func NewClient[Req, Resp any](
	httpClient connect.HTTPClient,
	baseURL string,
	spec MethodSpec,
	pathVarFn func(*Req) map[string]string,
	queryFn func(*Req) map[string]string,
	opts ...ClientOption,
) *Client[Req, Resp]

NewClient creates a new REST method client.

func (*Client[Req, Resp]) Call

func (c *Client[Req, Resp]) Call(ctx context.Context, req *Req) (*Resp, error)

Call executes the REST request.

type ClientOption

type ClientOption func(*clientOptions)

ClientOption configures a Client.

func WithHeader

func WithHeader(key, value string) ClientOption

WithHeader adds a header to all requests made by the client.

func WithInterceptors

func WithInterceptors(interceptors ...connect.UnaryInterceptorFunc) ClientOption

WithInterceptors adds interceptors that run before each request. Interceptors see a connect.AnyRequest with the proto message and HTTP headers, and can modify headers (e.g., inject Authorization) before the request is sent. This matches the ConnectRPC connect.WithInterceptors() pattern.

type MethodSpec

type MethodSpec struct {
	HTTPMethod string    // GET, POST, PATCH, DELETE, PUT
	URLPattern string    // e.g., "/v1/credentials/{name}"
	PathVars   []PathVar // path variable extraction info
}

MethodSpec describes a REST method's HTTP configuration.

type PathVar

type PathVar struct {
	Placeholder string // e.g., "{name}"
	Prefix      string // e.g., "credentials/" to strip from value
}

PathVar describes how to extract a path variable from a request.