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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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.
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
internal
|
|
Package middleware defines interfaces that can be implemented by third-party code to intercept RPC method invocations, both on the server-side and client-side.
|
Package middleware defines interfaces that can be implemented by third-party code to intercept RPC method invocations, both on the server-side and client-side. |
Package rpcerror defines an error implementation used to communicate server-side RPC errors to RPC clients.
|
Package rpcerror defines an error implementation used to communicate server-side RPC errors to RPC clients. |
Package runtime contains the API used by code that is generated from Protocol Buffers files.
|
Package runtime contains the API used by code that is generated from Protocol Buffers files. |