Proto RPC

This project provides a simple and easy-to-use library for working
with multiple proto-over-http RPC protocols.

Introduction

There are many proto-over-http RPC protocols, such as prpc and
Twirp. Each protocol uses its own framework and runtime library.
However, most of these protocols only differ on the URL structure,
HTTP headers, and the error format. By making these features
customizable by the application, a single library can support
multiple wire protocols with great usability and minimum complexity.

Design

Most proto-over-http frameworks ues protoc plugins to generate the
client and the server libraries. While such libraries provide type
safety and ease of use, they also put restrictions on many use cases,
such as mandating the URL structure. The protoc plugins also add
complexity to the build system, and introduce compatibility issues.

This library uses a different API design pattern to avoid the
code generation, while provide good type safety, flexibility and
usability, see the following below:

With code generation

stub := NewStub(...)
request := &FooRequest{...}
response, err := stub.Foo(ctx, request)

Without code generation

client := NewClient(...)
request := &FooRequest{...}
response := &FooResponse{}
err := client.Call(ctx, "Foo", request, response)

Conceptually, we use printf() like experience for making RPC
calls. By having an extra parameter to specify the method name,
we can avoid codegen completely. While printf() may not provide
type safety, developers rarely use it wrong. This library brings
the same experience to RPC calls.

Protocol Support

All proto-over-http protocols have the following general
semantics:

URL Request -> ( Response | Error )

This library supports any proto-over-http protocol that meets
these requirements:

• Each RPC endpoint is identified by a unique HTTP URL, which is
  published by API documentation or API service discovery. This
  library does not impose any restriction on the URL structure.

• Each RPC request is sent using an HTTP POST method. Other HTTP
  methods can be supported if needed.

• The request messages are passed via HTTP request body.

• The response messages and the error payloads are passed via
  HTTP response body.

• Only proto JSON and proto binary encodings are supported, but
  proto text and proto yaml can be added if needed. The encoding
  format must be specified by the Content-Type HTTP header.

• Protocol-specific metadata can be passed via HTTP headers.

Status

Currently, this repository only contains the Go client implementation.
It can be seamlessly integrated with an auth library for real use
cases. Please see the example directory on how to use the library.

Since the library has much less than 200 lines of code, it can be
easily transcoded into other programming languages where proto is
supported.