Documentation ¶
Overview ¶
package phi is a small, idiomatic and composable router for building HTTP services.
phi requires Go 1.10 or newer.
Example:
package main import ( "net/http" "go.philip.id/phi" "go.philip.id/phi/middleware" ) func main() { r := phi.NewRouter() r.Use(middleware.Logger) r.Use(middleware.Recoverer) r.Get("/", func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("root.")) }) http.ListenAndServe(":3333", r) }
See github.com/go-phi/phi/_examples/ for more in-depth examples.
URL patterns allow for easy matphing of path components in HTTP requests. The matphing components can then be accessed using phi.URLParam(). All patterns must begin with a slash.
A simple named placeholder {name} matches any sequence of characters up to the next / or the end of the URL. Trailing slashes on paths must be handled explicitly.
A placeholder with a name followed by a colon allows a regular expression match, for example {number:\\d+}. The regular expression syntax is Go's normal regexp RE2 syntax, except that regular expressions including { or } are not supported, and / will never be matched. An anonymous regexp pattern is allowed, using an empty string before the colon in the placeholder, such as {:\\d+}
The special placeholder of asterisk matches the rest of the requested URL. Any trailing characters in the pattern are ignored. This is the only placeholder which will match / characters.
Examples:
"/user/{name}" matches "/user/jsmith" but not "/user/jsmith/info" or "/user/jsmith/" "/user/{name}/info" matches "/user/jsmith/info" "/page/*" matches "/page/intro/latest" "/page/*/index" also matches "/page/intro/latest" "/date/{yyyy:\\d\\d\\d\\d}/{mm:\\d\\d}/{dd:\\d\\d}" matches "/date/2017/04/01"
Index ¶
- Variables
- func RegisterMethod(method string)
- func SetErrorHandler(fn ErrorHandlerFunc) error
- func URLParam(r *http.Request, key string) string
- func URLParamFromCtx(ctx context.Context, key string) string
- func Walk(r Routes, walkFn WalkFunc) error
- type ChainHandler
- type Context
- type Error
- type ErrorHandlerFunc
- type Handler
- type Map
- type Middlewares
- type Mux
- func (mx *Mux) Connect(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) DELETE(pattern string, handler Handler)
- func (mx *Mux) Delete(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) GET(pattern string, handler Handler)
- func (mx *Mux) Get(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Group(fn func(r Router)) Router
- func (mx *Mux) Handle(pattern string, handler http.Handler)
- func (mx *Mux) HandleFunc(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Head(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Match(rctx *Context, method, path string) bool
- func (mx *Mux) Method(method, pattern string, handler http.Handler)
- func (mx *Mux) MethodFunc(method, pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) MethodNotAllowed(handlerFn http.HandlerFunc)
- func (mx *Mux) MethodNotAllowedHandler() http.HandlerFunc
- func (mx *Mux) Middlewares() Middlewares
- func (mx *Mux) Mount(pattern string, handler http.Handler)
- func (mx *Mux) NotFound(handlerFn http.HandlerFunc)
- func (mx *Mux) NotFoundHandler() http.HandlerFunc
- func (mx *Mux) Options(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) POST(pattern string, handler Handler)
- func (mx *Mux) PUT(pattern string, handler Handler)
- func (mx *Mux) Patch(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Post(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Put(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Route(pattern string, fn func(r Router)) Router
- func (mx *Mux) Routes() []Route
- func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (mx *Mux) Trace(pattern string, handlerFn http.HandlerFunc)
- func (mx *Mux) Use(middlewares ...func(http.Handler) http.Handler)
- func (mx *Mux) With(middlewares ...func(http.Handler) http.Handler) Router
- type Request
- type Response
- func (w Response) Error(err error) *Error
- func (w Response) ErrorCustomStatus(err error, statusCode int) *Error
- func (w Response) JSON(data interface{}) *Error
- func (w Response) Redirect(req *http.Request, location string, code int) *Error
- func (w Response) Response(data []byte, contentType string) *Error
- type Route
- type RouteParams
- type Router
- type Routes
- type WalkFunc
Constants ¶
This section is empty.
Variables ¶
var ErrorHandler = defaultErrorHandler
Defines a function which accepts a ResponseWriter, Request and a phi.Error this function is used to handle errors thrown by any handler/route
can be set by SetErrorHandler
var (
// RouteCtxKey is the context.Context key to store the request context.
RouteCtxKey = &contextKey{"RouteContext"}
)
Functions ¶
func RegisterMethod ¶
func RegisterMethod(method string)
RegisterMethod adds support for custom HTTP method handlers, available via Router#Method and Router#MethodFunc
func SetErrorHandler ¶
func SetErrorHandler(fn ErrorHandlerFunc) error
func URLParamFromCtx ¶
URLParamFromCtx returns the url parameter from a http.Request Context.
Types ¶
type ChainHandler ¶
type ChainHandler struct { Endpoint http.Handler Middlewares Middlewares // contains filtered or unexported fields }
ChainHandler is a http.Handler with support for handler composition and execution.
func (*ChainHandler) ServeHTTP ¶
func (c *ChainHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Context ¶
type Context struct { Routes Routes // Routing path/method override used during the route search. // See Mux#routeHTTP method. RoutePath string RouteMethod string // URLParams are the stack of routeParams captured during the // routing lifecycle across a stack of sub-routers. URLParams RouteParams // Routing pattern stack throughout the lifecycle of the request, // across all connected routers. It is a record of all matphing // patterns across a stack of sub-routers. RoutePatterns []string // contains filtered or unexported fields }
Context is the default routing context set on the root node of a request context to track route patterns, URL parameters and an optional routing path.
func NewRouteContext ¶
func NewRouteContext() *Context
NewRouteContext returns a new routing Context object.
func RouteContext ¶
RouteContext returns phi's routing Context object from a http.Request Context.
func (*Context) RoutePattern ¶
RoutePattern builds the routing pattern string for the particular request, at the particular point during routing. This means, the value will change throughout the execution of a request in a router. That is why its advised to only use this value after calling the next handler.
For example,
func Instrument(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { next.ServeHTTP(w, r) routePattern := phi.RouteContext(r.Context()).RoutePattern() measure(w, r, routePattern) }) }
type Error ¶
func BodyParameterError ¶ added in v0.1.0
Body Parameter error for error handling regarding parameter missing POST body = { "data": "123"} -> data = body parameter
func QueryParameterError ¶ added in v0.1.0
Query Parameter error for error handling regarding parameter missing /yeet?id=1337 -> id = query parameter
func URLParameterError ¶ added in v0.1.0
Parameter error for error handling regarding parameter missing /yeet/{cid} -> cid = parameter
func UnknownError ¶ added in v0.1.0
Unknown error for generic error handling
func Validate ¶ added in v0.1.0
Validate post bodies Example:
type Body struct { Data string `json:"data,required"` // required Dutu string `json:"dutu"` // optional }
func ValidatingError ¶ added in v0.1.0
Validation error can be used for validating post bodies
type ErrorHandlerFunc ¶
type ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, e *Error)
set custom error handler
type Map ¶ added in v0.1.0
type Map map[string]interface{}
Helper for easily defining a map[string]interface{} in JSON responses.
type Middlewares ¶
Middlewares type is a slice of standard middleware handlers with methods to compose middleware chains and http.Handler's.
func Chain ¶
func Chain(middlewares ...func(http.Handler) http.Handler) Middlewares
Chain returns a Middlewares type from a slice of middleware handlers.
func (Middlewares) Handler ¶
func (mws Middlewares) Handler(h http.Handler) http.Handler
Handler builds and returns a http.Handler from the chain of middlewares, with `h http.Handler` as the final handler.
func (Middlewares) HandlerFunc ¶
func (mws Middlewares) HandlerFunc(h http.HandlerFunc) http.Handler
HandlerFunc builds and returns a http.Handler from the chain of middlewares, with `h http.Handler` as the final handler.
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux is a simple HTTP route multiplexer that parses a request path, records any URL params, and executes an end handler. It implements the http.Handler interface and is friendly with the standard library.
Mux is designed to be fast, minimal and offer a powerful API for building modular and composable HTTP services with a large set of handlers. It's particularly useful for writing large REST API services that break a handler into many smaller parts composed of middlewares and end handlers.
func NewMux ¶
func NewMux() *Mux
NewMux returns a newly initialized Mux object that implements the Router interface.
func NewRouter ¶
func NewRouter() *Mux
NewRouter returns a new Mux object that implements the Router interface.
func (*Mux) Connect ¶
func (mx *Mux) Connect(pattern string, handlerFn http.HandlerFunc)
Connect adds the route `pattern` that matches a CONNECT http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) DELETE ¶
Get adds the route `pattern` that matches a GET http method to execute the `handlerFn` http.HandlerFunc wrapped into errorHandler functionality.
func (*Mux) Delete ¶
func (mx *Mux) Delete(pattern string, handlerFn http.HandlerFunc)
Delete adds the route `pattern` that matches a DELETE http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) GET ¶
Get adds the route `pattern` that matches a GET http method to execute the `handlerFn` http.HandlerFunc wrapped into errorHandler functionality.
func (*Mux) Get ¶
func (mx *Mux) Get(pattern string, handlerFn http.HandlerFunc)
Get adds the route `pattern` that matches a GET http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Group ¶
Group creates a new inline-Mux with a fresh middleware stack. It's useful for a group of handlers along the same routing path that use an additional set of middlewares. See _examples/.
func (*Mux) Handle ¶
Handle adds the route `pattern` that matches any http method to execute the `handler` http.Handler.
func (*Mux) HandleFunc ¶
func (mx *Mux) HandleFunc(pattern string, handlerFn http.HandlerFunc)
HandleFunc adds the route `pattern` that matches any http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Head ¶
func (mx *Mux) Head(pattern string, handlerFn http.HandlerFunc)
Head adds the route `pattern` that matches a HEAD http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Match ¶
Match searches the routing tree for a handler that matches the method/path. It's similar to routing a http request, but without executing the handler thereafter.
Note: the *Context state is updated during execution, so manage the state carefully or make a NewRouteContext().
func (*Mux) Method ¶
Method adds the route `pattern` that matches `method` http method to execute the `handler` http.Handler.
func (*Mux) MethodFunc ¶
func (mx *Mux) MethodFunc(method, pattern string, handlerFn http.HandlerFunc)
MethodFunc adds the route `pattern` that matches `method` http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) MethodNotAllowed ¶
func (mx *Mux) MethodNotAllowed(handlerFn http.HandlerFunc)
MethodNotAllowed sets a custom http.HandlerFunc for routing paths where the method is unresolved. The default handler returns a 405 with an empty body.
func (*Mux) MethodNotAllowedHandler ¶
func (mx *Mux) MethodNotAllowedHandler() http.HandlerFunc
MethodNotAllowedHandler returns the default Mux 405 responder whenever a method cannot be resolved for a route.
func (*Mux) Middlewares ¶
func (mx *Mux) Middlewares() Middlewares
Middlewares returns a slice of middleware handler functions.
func (*Mux) Mount ¶
Mount attaches another http.Handler or phi Router as a subrouter along a routing path. It's very useful to split up a large API as many independent routers and compose them as a single service using Mount. See _examples/.
Note that Mount() simply sets a wildcard along the `pattern` that will continue routing at the `handler`, which in most cases is another phi.Router. As a result, if you define two Mount() routes on the exact same pattern the mount will panic.
func (*Mux) NotFound ¶
func (mx *Mux) NotFound(handlerFn http.HandlerFunc)
NotFound sets a custom http.HandlerFunc for routing paths that could not be found. The default 404 handler is `http.NotFound`.
func (*Mux) NotFoundHandler ¶
func (mx *Mux) NotFoundHandler() http.HandlerFunc
NotFoundHandler returns the default Mux 404 responder whenever a route cannot be found.
func (*Mux) Options ¶
func (mx *Mux) Options(pattern string, handlerFn http.HandlerFunc)
Options adds the route `pattern` that matches a OPTIONS http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) POST ¶
Get adds the route `pattern` that matches a GET http method to execute the `handlerFn` http.HandlerFunc wrapped into errorHandler functionality.
func (*Mux) PUT ¶
Get adds the route `pattern` that matches a GET http method to execute the `handlerFn` http.HandlerFunc wrapped into errorHandler functionality.
func (*Mux) Patch ¶
func (mx *Mux) Patch(pattern string, handlerFn http.HandlerFunc)
Patch adds the route `pattern` that matches a PATCH http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Post ¶
func (mx *Mux) Post(pattern string, handlerFn http.HandlerFunc)
Post adds the route `pattern` that matches a POST http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Put ¶
func (mx *Mux) Put(pattern string, handlerFn http.HandlerFunc)
Put adds the route `pattern` that matches a PUT http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Route ¶
Route creates a new Mux with a fresh middleware stack and mounts it along the `pattern` as a subrouter. Effectively, this is a short-hand call to Mount. See _examples/.
func (*Mux) Routes ¶
Routes returns a slice of routing information from the tree, useful for traversing available routes of a router.
func (*Mux) ServeHTTP ¶
func (mx *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP is the single method of the http.Handler interface that makes Mux interoperable with the standard library. It uses a sync.Pool to get and reuse routing contexts for each request.
func (*Mux) Trace ¶
func (mx *Mux) Trace(pattern string, handlerFn http.HandlerFunc)
Trace adds the route `pattern` that matches a TRACE http method to execute the `handlerFn` http.HandlerFunc.
func (*Mux) Use ¶
Use appends a middleware handler to the Mux middleware stack.
The middleware stack for any Mux will execute before searphing for a matphing route to a specific handler, which provides opportunity to respond early, change the course of the request execution, or set request-scoped values for the next http.Handler.
type Request ¶ added in v0.1.0
func (*Request) QueryParam ¶ added in v0.1.0
/yeet?id=1337 -> id = query parameter
type Response ¶ added in v0.1.0
type Response struct {
http.ResponseWriter
}
func (Response) ErrorCustomStatus ¶ added in v0.1.0
send error response with custom status code
type RouteParams ¶
type RouteParams struct {
Keys, Values []string
}
RouteParams is a structure to track URL routing parameters efficiently.
func (*RouteParams) Add ¶
func (s *RouteParams) Add(key, value string)
Add will append a URL parameter to the end of the route param
type Router ¶
type Router interface { http.Handler Routes // Use appends one or more middlewares onto the Router stack. Use(middlewares ...func(http.Handler) http.Handler) // With adds inline middlewares for an endpoint handler. With(middlewares ...func(http.Handler) http.Handler) Router // Group adds a new inline-Router along the current routing // path, with a fresh middleware stack for the inline-Router. Group(fn func(r Router)) Router // Route mounts a sub-Router along a `pattern“ string. Route(pattern string, fn func(r Router)) Router // Mount attaches another http.Handler along ./pattern/* Mount(pattern string, h http.Handler) // Handle and HandleFunc adds routes for `pattern` that matches // all HTTP methods. Handle(pattern string, h http.Handler) HandleFunc(pattern string, h http.HandlerFunc) // Method and MethodFunc adds routes for `pattern` that matches // the `method` HTTP method. Method(method, pattern string, h http.Handler) MethodFunc(method, pattern string, h http.HandlerFunc) // HTTP-method routing along `pattern` Connect(pattern string, h http.HandlerFunc) Delete(pattern string, h http.HandlerFunc) Get(pattern string, h http.HandlerFunc) Head(pattern string, h http.HandlerFunc) Options(pattern string, h http.HandlerFunc) Patch(pattern string, h http.HandlerFunc) Post(pattern string, h http.HandlerFunc) Put(pattern string, h http.HandlerFunc) Trace(pattern string, h http.HandlerFunc) // HTTP-method with error handling functionality GET(pattern string, h Handler) POST(pattern string, h Handler) PUT(pattern string, h Handler) DELETE(pattern string, h Handler) // NotFound defines a handler to respond whenever a route could // not be found. NotFound(h http.HandlerFunc) // MethodNotAllowed defines a handler to respond whenever a method is // not allowed. MethodNotAllowed(h http.HandlerFunc) }
Router consisting of the core routing methods used by phi's Mux, using only the standard net/http.
type Routes ¶
type Routes interface { // Routes returns the routing tree in an easily traversable structure. Routes() []Route // Middlewares returns the list of middlewares in use by the router. Middlewares() Middlewares // Match searches the routing tree for a handler that matches // the method/path - similar to routing a http request, but without // executing the handler thereafter. Match(rctx *Context, method, path string) bool }
Routes interface adds two methods for router traversal, which is also used by the `docgen` subpackage to generation documentation for Routers.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
_examples
|
|
fileserver
FileServer =========== This example demonstrates how to serve static files from your filesystem.
|
FileServer =========== This example demonstrates how to serve static files from your filesystem. |
limits
Limits ====== This example demonstrates the use of Timeout, and Throttle middlewares.
|
Limits ====== This example demonstrates the use of Timeout, and Throttle middlewares. |
logging
Custom Structured Logger ======================== This example demonstrates how to use middleware.RequestLogger, middleware.LogFormatter and middleware.LogEntry to build a structured logger using the amazing sirupsen/logrus package as the logging backend.
|
Custom Structured Logger ======================== This example demonstrates how to use middleware.RequestLogger, middleware.LogFormatter and middleware.LogEntry to build a structured logger using the amazing sirupsen/logrus package as the logging backend. |
todos-resource
Todos Resource ============== This example demonstrates a project structure that defines a subrouter and its handlers on a struct, and mounting them as subrouters to a parent router.
|
Todos Resource ============== This example demonstrates a project structure that defines a subrouter and its handlers on a struct, and mounting them as subrouters to a parent router. |
versions
Versions ======== This example demonstrates the use of the render subpackage, with a quick concept for how to support multiple api versions.
|
Versions ======== This example demonstrates the use of the render subpackage, with a quick concept for how to support multiple api versions. |
cors package is net/http handler to handle CORS related requests as defined by http://www.w3.org/TR/cors/
|
cors package is net/http handler to handle CORS related requests as defined by http://www.w3.org/TR/cors/ |
_examples
cors example
|
cors example |