README
¶
Black Box Router
Package blackbox provides simple to use, extensible, flexible, and easily testable typesafe server routing for your web apps and microservices.
Blackbox does that by utilising a functional approach to request handling, where routing nodes (type Router) provide filtering handling and return an exposed Response instance that can be tested and examined.
- For more information on testing, please see the test folder.
- To see a working example, look at this example.
Why Black Box
- Seamless interop with the standard
net/http.Server:blackbox.Routerimplements thenet/http.Handlerinterface - Pleasure to test: due to the convenient
Handlerinterface definition,blackbox.Handleractually returnsblackbox.Responseinstead of writing it tonet/http.ResponseWriter - Well tested with an average coverage of 85% across all packages
- Extendable architecture: if you need more filters or additional middleware,
just implement your own by implementing interfaces like
blackbox.Filter - As a bonus,
blackbox.Responsesupports JSON serialization out of the box: just callresp.EncodeJSON(object)and you're golden!
Documentation
¶
Overview ¶
Package blackbox provides simple to use, extensible, flexible, and easily testable typesafe server routing for your web apps and microservices.
Blackbox does that by utilising a functional approach to request handling, where routing nodes (type Router) provide filtering handling and return an exposed Response instance that can be tested and examined.
For more information on testing, please see the 'test' folder.
Index ¶
- type Filter
- type FilterFunc
- type Handler
- type HandlerFunc
- type Response
- func (resp *Response) DecodeJSON(data interface{}) error
- func (resp *Response) EncodeJSON(data interface{}) error
- func (resp *Response) Respond(w http.ResponseWriter)
- func (resp *Response) WithCookie(cookie *http.Cookie) *Response
- func (resp *Response) WithHeader(name, value string) *Response
- func (resp *Response) WithStatus(status int) *Response
- func (resp *Response) Write(b []byte) *Response
- func (resp *Response) WriteString(s string) *Response
- type Route
- type Router
- func (rtr *Router) Accepts(r *http.Request) bool
- func (rtr *Router) Handle(r *http.Request) (resp *Response)
- func (rtr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (rtr *Router) Subrouter() (sub *Router)
- func (rtr *Router) WithFilterFuncs(filters ...FilterFunc) *Router
- func (rtr *Router) WithFilters(filters ...Filter) *Router
- func (rtr *Router) WithHandler(handler Handler) *Router
- func (rtr *Router) WithHandlerFunc(f HandlerFunc) *Router
- func (rtr *Router) WithRoute(sub Route) *Router
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Filter ¶
Filter represents any filtering entity that can decide whether it wants to deal with a given net/http.Request through its Accept predicate.
type FilterFunc ¶
FilterFunc is a special function type that implements the Filter interface.
type Handler ¶
Handler interface represents a functional handler that returns the Response instance taking net/http.Request as its only parameter.
type HandlerFunc ¶
HandlerFunc is a special function type that implements the Handler interface.
type Response ¶
type Response struct {
// See https://pkg.go.dev/net/http#pkg-constants for status constants.
Status int
Headers map[string]string
Cookies map[string]*http.Cookie
Body *bytes.Buffer
}
Response represents a standard HTTP response.
func NewResponse ¶
func NewResponse() *Response
NewResponse returns a newly created Response instance with status 200 OK, and pre-allocated Headers map and Body writer.
func (*Response) DecodeJSON ¶
DecodeJSON uses Go's default encoding/json library to decode data from Request.Body as JSON.
func (*Response) EncodeJSON ¶
EncodeJSON uses Go's default encoding/json library to encode data as JSON and write it into Request.Body.
func (*Response) Respond ¶
func (resp *Response) Respond(w http.ResponseWriter)
Respond writes information stored within this Response instance into the given net/http.ResponseWriter, thus, sending it to the client.
Respond helps Response implement Responder interface.
func (*Response) WithCookie ¶
WithCookie sets cookie in Response.Cookies (overwriting any existing cookies with the same name) and returns reference to that same Response.
func (*Response) WithHeader ¶
WithHeader sets header in Response.Headers (overwriting any exising headers with the same name) and returns reference to that same Response.
func (*Response) WithStatus ¶
WithStatus sets Response status and returns reference to that same Response.
func (*Response) Write ¶
Write writes given bytes to Response.Body and returns reference to the Response.
func (*Response) WriteString ¶
WriteString writes given string to Response.Body and returns reference to the Response.
type Route ¶
Route is a filtering entity that has a Handler attached to it in case it decides to accept given net/http.Request.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router is the main feature of the blackbox package. It allows you to build extensible, testable and typesafe routing for your web app or microservice.
Router implements
- net/http.Handler
- Filter
- Handler
- Route
func New ¶
func New() *Router
New returns a newly create Router instance with pre-allocated filters and routes and a default catch-all handler that always responds with status 501 Not Implemented. Feel free to customise it using available methods!
func (*Router) ServeHTTP ¶
func (rtr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP helps Router implement net/http.Handler interface for effective interop with the net/http.Server.
func (*Router) Subrouter ¶
Subrouter adds a newly created subrouter instance to the Router, returning a reference to that subrouter for future modification.
func (*Router) WithFilterFuncs ¶
func (rtr *Router) WithFilterFuncs(filters ...FilterFunc) *Router
WithFilterFuncs accepts mutilple FilterFunc's and adds them to the Router, returning a reference to the same Router instance.
func (*Router) WithFilters ¶
WithFilters accepts multiple Filter's and adds them to the Router, returning a reference to the same Router instance.
func (*Router) WithHandler ¶
WithHandler accepts a Handler and adds it to the Router, returning a reference to the same Router instance.
func (*Router) WithHandlerFunc ¶
func (rtr *Router) WithHandlerFunc(f HandlerFunc) *Router
WithHandlerFunc accepts a HandlerFunc and adds it to the Router, returning a reference to the same Router instance.
Source Files
Directories