README
¶
Taxi 🚕
Taxi is a lightweight, remote procedure call (RPC) framework for services written in Go. Requests are sent as JSON over HTTP, making it easy to interact with Taxi-based services. Taxi does not impose any particular URL scheme or request structure, and responses are fully-customisable, giving you full control over the design of your API.
Installation
go get github.com/jakewright/taxi
Usage
Taxi is made up of two components: a client for dispatching RPCs to a remote service, and a router for handling incoming RPCs.
Client
Creating a new client
// Create a new client
client := taxi.NewClient()
// Taxi uses an http.Client{} to send requests.
// You can provide your own if you wish using
// NewClientUsing(doer Doer).
type Doer interface {
Do(r *http.Request) (*http.Response, error)
}
custom := &http.Client{Timeout: 30 * time.Second}
client := taxi.NewClientUsing(custom)
Mock client
It's useful in tests to use a mock client. The mock client has an http.Handler that it uses to serve requests. Set this to an instance of TestFixture to create a handler that expects and responds to particular requests.
Router
Use the router to build a server that responds to RPCs.
// Create a new router (optionally set a logger)
router := taxi.NewRouter().WithLogger(log.Printf)
// Set global middleware
router.UseMiddleware(...)
// Register a handler
router.RegisterHandlerFund("GET", "/foo", fooHandler)
func fooHandler(ctx context.Context, decode taxi.Decoder) (interface{}, error) {
body := &sruct{
Bar string `json:"bar"`
}{}
if err := decode(bar); err != nil {
return err
}
...
}
Documentation
¶
Index ¶
- func DecodeRequest(r *http.Request, v interface{}) error
- func WriteError(w http.ResponseWriter, err error) error
- func WriteSuccess(w http.ResponseWriter, v interface{}) error
- type Client
- func (c *Client) Delete(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *Client) Dispatch(ctx context.Context, rpc *RPC) *Future
- func (c *Client) Get(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *Client) Patch(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *Client) Post(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *Client) Put(ctx context.Context, url string, body interface{}, v interface{}) error
- type Decoder
- type Dispatcher
- type Doer
- type Future
- type Handler
- type HandlerFunc
- type Middleware
- type MockClient
- func (c *MockClient) Delete(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *MockClient) Dispatch(ctx context.Context, rpc *RPC) *Future
- func (c *MockClient) Get(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *MockClient) Patch(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *MockClient) Post(ctx context.Context, url string, body interface{}, v interface{}) error
- func (c *MockClient) Put(ctx context.Context, url string, body interface{}, v interface{}) error
- type RPC
- type Router
- func (r *Router) Handle(method, path string, handler Handler)
- func (r *Router) HandleFunc(method, path string, ...)
- func (r *Router) HandleRaw(method, path string, handler http.Handler)
- func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
- func (r *Router) UseMiddleware(mw ...Middleware)
- func (r *Router) WithLogger(f func(format string, v ...interface{})) *Router
- type Stub
- func (s *Stub) Expect(n int) *Stub
- func (s *Stub) Match(r *http.Request) bool
- func (s *Stub) MatchBody(body interface{}) *Stub
- func (s *Stub) MatchMethod(method string) *Stub
- func (s *Stub) MatchPartialBody(body interface{}, fields []string) *Stub
- func (s *Stub) MatchPath(path string) *Stub
- func (s *Stub) RespondWith(v interface{}) *Stub
- func (s *Stub) RespondWithError(err error) *Stub
- func (s *Stub) RunAssertions()
- func (s *Stub) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Stub) WithAssertion(f func(t *testing.T, requests []*http.Request)) *Stub
- func (s *Stub) WithMatcher(f func(r *http.Request) bool) *Stub
- type TestFixture
- func (f *TestFixture) Allow(rpc rpcProvider, fields ...string) *Stub
- func (f *TestFixture) Expect(n int, rpc rpcProvider, fields ...string) *Stub
- func (f *TestFixture) ExpectOne(rpc rpcProvider, fields ...string) *Stub
- func (f *TestFixture) NewStub() *Stub
- func (f *TestFixture) RunAssertions()
- func (f *TestFixture) ServeHTTP(w http.ResponseWriter, r *http.Request)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeRequest ¶
DecodeRequest unmarshals URL parameters and the JSON body of the given request into the value pointed to by v. It is exported because it might be useful, e.g. in middleware.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error) error
WriteError writes the error to the ResponseWriter. If the error is an oops.Error, the status code is taken from that, otherwise a status code of 500 is set.
func WriteSuccess ¶
func WriteSuccess(w http.ResponseWriter, v interface{}) error
WriteSuccess writes the data to the ResponseWriter. A status code of 200 is set.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client dispatches RPC requests
func NewClientUsing ¶
NewClientUsing returns an initialised client, using the given Doer to make the HTTP requests. The standard http.Client implements the Doer interface.
func (*Client) Dispatch ¶
Dispatch makes a request and returns a Future that represents the in-flight request
type Decoder ¶
type Decoder func(v interface{}) error
Decoder is a function that decodes a request body into the given interface
type Dispatcher ¶
type Dispatcher interface {
Dispatch(ctx context.Context, rpc *RPC) *Future
Get(ctx context.Context, url string, body interface{}, v interface{}) error
Post(ctx context.Context, url string, body interface{}, v interface{}) error
Put(ctx context.Context, url string, body interface{}, v interface{}) error
Patch(ctx context.Context, url string, body interface{}, v interface{}) error
Delete(ctx context.Context, url string, body interface{}, v interface{}) error
}
Dispatcher is the interface for making remote procedure calls
type Future ¶
type Future struct {
// contains filtered or unexported fields
}
Future represents an in-flight remote procedure call
func (*Future) DecodeResponse ¶
DecodeResponse will block until the response has been received, and then decode the JSON body into the given argument.
type HandlerFunc ¶
HandlerFunc is a type that allows normal functions to be used as Handlers
type Middleware ¶
Middleware is a function that takes a handler and returns a new handler
type MockClient ¶
MockClient dispatches RPCs by passing the request directly to an internal http.Handler. It does not make network requests. This is useful in unit tests as it allows endpoints to be mocked.
func (*MockClient) Delete ¶
func (c *MockClient) Delete(ctx context.Context, url string, body interface{}, v interface{}) error
Delete dispatches a DELETE RPC
func (*MockClient) Dispatch ¶
func (c *MockClient) Dispatch(ctx context.Context, rpc *RPC) *Future
Dispatch converts the RPC into an http request and gives it to the client's handler to handle. It returns a Future which will resolve to the response given by the handler.
func (*MockClient) Get ¶
func (c *MockClient) Get(ctx context.Context, url string, body interface{}, v interface{}) error
Get dispatches a GET RPC
func (*MockClient) Patch ¶
func (c *MockClient) Patch(ctx context.Context, url string, body interface{}, v interface{}) error
Patch dispatches a PATCH RPC
type RPC ¶
RPC represents a remote procedure call
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router registers routes and handlers to handle RPCs over HTTP.
func (*Router) HandleFunc ¶
func (r *Router) HandleFunc(method, path string, handler func(context.Context, Decoder) (interface{}, error))
HandleFunc registers a new route
func (*Router) ServeHTTP ¶
func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP dispatches requests to the appropriate handler
func (*Router) UseMiddleware ¶
func (r *Router) UseMiddleware(mw ...Middleware)
UseMiddleware adds the given middleware to the router. The middleware functions are executed in the order given.
func (*Router) WithLogger ¶
WithLogger sets a log function for the router to use when something goes. wrong. If not set, no logs will be output.
type Stub ¶
type Stub struct {
// contains filtered or unexported fields
}
Stub is an http.Handler to use with a TestFixture. It can be configured to match requests based on arbitrary rules, and make assertions based on the requests that were received.
func (*Stub) MatchMethod ¶
MatchMethod adds a matcher that matches on the request method
func (*Stub) MatchPartialBody ¶
MatchPartialBody adds a matcher that matches on the request body but only compares fields that are set in the fields slice.
func (*Stub) RespondWith ¶
RespondWith sets the data that should be returned by the stub when handling requests. The interface will be marshaled to JSON and wrapped in a data field.
func (*Stub) RespondWithError ¶
RespondWithError sets the error that should be returned by the stub when handling requests. The error will be converted to a string and sent in the error field of the JSON payload.
func (*Stub) RunAssertions ¶
func (s *Stub) RunAssertions()
RunAssertions runs the stub's assertions
func (*Stub) ServeHTTP ¶
func (s *Stub) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP tracks that the request was received by the stub, and calls the stub's serve function if not nil.
func (*Stub) WithAssertion ¶
WithAssertion adds a custom assertion
type TestFixture ¶
type TestFixture struct {
// contains filtered or unexported fields
}
TestFixture is an http.Handler that can be used in testing. It dispatches requests to one of a set of Stubs that match based on arbitrary details about the request. Assertions can be run to assert that expected requests were received.
func NewTestFixture ¶
func NewTestFixture(t *testing.T) *TestFixture
NewTestFixture returns an initialised TestFixture
func (*TestFixture) Allow ¶
func (f *TestFixture) Allow(rpc rpcProvider, fields ...string) *Stub
Allow returns a new stub that matches on the method and path but does not care how many times it is called.
func (*TestFixture) Expect ¶
func (f *TestFixture) Expect(n int, rpc rpcProvider, fields ...string) *Stub
Expect returns a new stub that matches on the RPC, and asserts that it is called n times.
func (*TestFixture) ExpectOne ¶
func (f *TestFixture) ExpectOne(rpc rpcProvider, fields ...string) *Stub
ExpectOne returns a new stub that matches on the RPC, and asserts that it is called exactly once.
func (*TestFixture) NewStub ¶
func (f *TestFixture) NewStub() *Stub
NewStub returns a new empty stub
func (*TestFixture) RunAssertions ¶
func (f *TestFixture) RunAssertions()
RunAssertions runs all of the stubs' assertions
func (*TestFixture) ServeHTTP ¶
func (f *TestFixture) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP dispatches requests to the first stub that matches
Source Files