protean

README

Protean

Protean is a framework for building RPC web services based on Protocol Buffers service definitions.

Protean is inspired by Twirp but has different goals. Specifically, Protean is intended to produce RPC services that can be used not only for server-to-server communication, but also by browsers using only standard browser APIs.

Both Protean and Twirp are alternatives to gRPC.

Getting Started

To use Protean, you will need a working knowledge of Protocol Buffers, and generating Go code from .proto files.

Protean includes a protoc plugin called protoc-gen-go-protean. The latest version can be installed by running:

go install github.com/dogmatiq/protean/cmd/protoc-gen-go-protean@latest

Add the --go-protean_out to protoc to generate Protean server interfaces and RPC clients. An example demonstrating how to implement a server and use an RPC client example_test.go.

Project Goals

Goals

• Services to be consumable by web browsers using standard browser APIs.
• Services to be equally easy to consume from other servers in any language.
• Full support for client, server and bidirectional streaming.
• Provide an adequate level of cache control for use with service workers.
• Allow the client to choose the best encoding (protobuf, json or text) on a per-call basis.
• Allow the client to choose the best transport on a per-call basis. Options to include "conventional" HTTP GET and POST requests, websockets, server-sent events (SSE) and JSON-RPC.
• Produce http.Handler implementations that work with Go's standard web server.
• Co-exist with gRPC services built from the same Protocol Buffers definitions.
• HTTP/1.1 and HTTP/2 support.

Non-goals

• Hiding the fact that the server is RPC based.
• Providing RESTful APIs, changing behavior based on HTTP methods.
• Allowing fine-grained control over HTTP-specific behavior, such as setting headers.
• Non-HTTP transports.

Documentation

Overview

Package protean is a framework for building RPC web services based on Protocol Buffers service definitions.

Example

package main

import (
	"context"
	"fmt"
	"net/http/httptest"
	"net/url"
	"strings"
	"time"

	"github.com/dogmatiq/protean"
	"github.com/dogmatiq/protean/internal/stringservice"
)

// serviceImplementation is an implementation of the
// stringservice.ProteanStringService interface, which is generated by
// protoc-gen-go-protean from the ./internal/stringservice/service.proto file.
//
// Note: The .proto file and the generated code are kept in an "internal"
// package path to avoid any possibility of them appearing in Protean's public
// API by accident. The generated code is not committed to the Git repository.
// To see the generated code, please clone this repository and run "make test".
type serviceImplementation struct{}

// ToUpper is an RPC method that returns the uppercase version of a string.
func (serviceImplementation) ToUpper(
	ctx context.Context,
	request *stringservice.ToUpperRequest,
) (*stringservice.ToUpperResponse, error) {
	uppercase := strings.ToUpper(
		request.GetOriginalString(),
	)

	response := &stringservice.ToUpperResponse{
		UppercaseString: uppercase,
	}

	return response, nil
}

func main() {
	// Create the Protean HTTP handler.
	//
	// This is an implementation of Go's standard http.Handler that dispatches
	// calls to RPC services.
	handler := protean.NewHandler()

	// Register our example implementation of the string service with the
	// Protean handler.
	service := serviceImplementation{}
	stringservice.RegisterProteanStringService(handler, service)

	// Start an HTTP server to accept our RPC requests.
	//
	// We use the server from the httptest package so that we can easily listen
	// on a random port, and shut down the server at the end of the example.
	// Typically you would use the Protean handler with Go's regular
	// "production" HTTP server from the http package.
	server := httptest.NewServer(handler)
	defer server.Close()

	// Now that we have a running server, we can create a client and start
	// calling some RPC methods.
	//
	// The test server conveniently provides the URL we can use to connect to
	// it. We use that to construct the base URL for the Protean RPC client.
	baseURL, err := url.Parse(server.URL)
	if err != nil {
		panic(err)
	}

	// Create the client for the string service. The returned client implements
	// the same stringservice.ProteanStringService interface that is used on the
	// server-side.
	client := stringservice.NewProteanStringServiceClient(baseURL)

	// Now we can finally outsource our uppercase conversions to another server!
	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
	defer cancel()

	request := &stringservice.ToUpperRequest{
		OriginalString: "This is the string.",
	}

	response, err := client.ToUpper(ctx, request)
	if err != nil {
		panic(err)
	}

	fmt.Println(response.GetUppercaseString())

}

Output:

THIS IS THE STRING.

Index

• type ClientOption
  • func WithHTTPClient(c *http.Client) ClientOption
  • func WithInputMediaType(mediaType string) ClientOption
  • func WithMediaType(mediaType string) ClientOption
  • func WithOutputMediaType(mediaType string) ClientOption
• type Handler
  • func NewHandler(options ...HandlerOption) Handler
• type HandlerOption

Examples

• Package

Types

type ClientOption

type ClientOption func(*runtime.ClientOptions)

ClientOption is an option that changes the behavior of an RPC client.

func WithHTTPClient

func WithHTTPClient(c *http.Client) ClientOption

WithHTTPClient is a ClientOption that sets the HTTP client to use when making RPC requests.

func WithInputMediaType

func WithInputMediaType(mediaType string) ClientOption

WithInputMediaType is a ClientOption that sets the preferred media-type that the client should use when encoding RPC input messages in HTTP requests.

func WithMediaType

func WithMediaType(mediaType string) ClientOption

WithMediaType is a ClientOption that sets the preferred media-type to use for both RPC input and output messages.

func WithOutputMediaType

func WithOutputMediaType(mediaType string) ClientOption

WithOutputMediaType is a ClientOption that sets the preferred media-type that the server should use when encoding RPC output messages in HTTP responses.

type Handler

type Handler interface {
	http.Handler
	runtime.Registry
}

Handler is an http.Handler that maps HTTP requests to RPC calls.

func NewHandler

func NewHandler(options ...HandlerOption) Handler

NewHandler returns a new HTTP handler that maps HTTP requests to RPC calls.

type HandlerOption

type HandlerOption func(*handlerOptions)

HandlerOption is an option that changes the behavior of an HTTP handler.