chi: github.com/pressly/chi Index | Files | Directories

package chi

import "github.com/pressly/chi"

Package chi is a small, idiomatic and composable router for building HTTP services.

chi requires Go 1.7 or newer.

Example:

package main

import (
	"net/http"

	"github.com/pressly/chi"
	"github.com/pressly/chi/middleware"
)

func main() {
	r := chi.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/pressly/chi/_examples/ for more in-depth examples.

Index

Package Files

chain.go chi.go context.go mux.go tree.go

Variables

var (
    RouteCtxKey = &contextKey{"RouteContext"}
)

func ServerBaseContext Uses

func ServerBaseContext(h http.Handler, baseCtx context.Context) http.Handler

ServerBaseContext wraps an http.Handler to set the request context to the `baseCtx`.

func URLParam Uses

func URLParam(r *http.Request, key string) string

URLParam returns the url parameter from a http.Request object.

func URLParamFromCtx Uses

func URLParamFromCtx(ctx context.Context, key string) string

URLParamFromCtx returns the url parameter from a http.Request Context.

type ChainHandler Uses

type ChainHandler struct {
    Middlewares Middlewares
    Endpoint    http.Handler
    // contains filtered or unexported fields
}

func (*ChainHandler) ServeHTTP Uses

func (c *ChainHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Context Uses

type Context struct {
    // URL routing parameter key and values.
    URLParams params

    // Routing path override used by subrouters.
    RoutePath string

    // Routing pattern matching the path.
    RoutePattern string

    // Routing patterns throughout the lifecycle of the request,
    // across all connected routers.
    RoutePatterns []string
}

Context is the default routing context set on the root node of a request context to track URL parameters and an optional routing path.

func NewRouteContext Uses

func NewRouteContext() *Context

NewRouteContext returns a new routing Context object.

func RouteContext Uses

func RouteContext(ctx context.Context) *Context

RouteContext returns chi's routing Context object from a http.Request Context.

type Middlewares Uses

type Middlewares []func(http.Handler) http.Handler

Middlewares type is a slice of standard middleware handlers with methods to compose middleware chains and http.Handler's.

func Chain Uses

func Chain(middlewares ...func(http.Handler) http.Handler) Middlewares

Chain returns a Middlewares type from a slice of middleware handlers.

func (Middlewares) Handler Uses

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 Uses

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 Uses

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 Uses

func NewMux() *Mux

NewMux returns a newly initialized Mux object that implements the Router interface.

func NewRouter Uses

func NewRouter() *Mux

NewRouter returns a new Mux object that implements the Router interface.

func (*Mux) Connect Uses

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 Uses

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) FileServer Uses

func (mx *Mux) FileServer(path string, root http.FileSystem)

FileServer conveniently sets up a http.FileServer handler to serve static files from a http.FileSystem.

func (*Mux) Get Uses

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 Uses

func (mx *Mux) Group(fn func(r Router)) Router

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 Uses

func (mx *Mux) Handle(pattern string, handler http.Handler)

Handle adds the route `pattern` that matches any http method to execute the `handler` http.Handler.

func (*Mux) HandleFunc Uses

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 Uses

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) MethodNotAllowed Uses

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 Uses

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 Uses

func (mx *Mux) Middlewares() Middlewares

func (*Mux) Mount Uses

func (mx *Mux) Mount(pattern string, handler http.Handler)

Mount attaches another http.Handler or chi 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 chi.Router. As a result, if you define two Mount() routes on the exact same pattern the mount will panic.

func (*Mux) NotFound Uses

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 Uses

func (mx *Mux) NotFoundHandler() http.HandlerFunc

NotFoundHandler returns the default Mux 404 responder whenever a route cannot be found.

func (*Mux) Options Uses

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) Patch Uses

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 Uses

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 Uses

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 Uses

func (mx *Mux) Route(pattern string, fn func(r Router)) Router

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 Uses

func (mx *Mux) Routes() []Route

func (*Mux) ServeHTTP Uses

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 Uses

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 Uses

func (mx *Mux) Use(middlewares ...func(http.Handler) http.Handler)

Use appends a middleware handler to the Mux middleware stack.

The middleware stack for any Mux will execute before searching for a matching 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.

func (*Mux) With Uses

func (mx *Mux) With(middlewares ...func(http.Handler) http.Handler) Router

With adds inline middlewares for an endpoint handler.

type Route Uses

type Route struct {
    Pattern   string
    Handlers  map[string]http.Handler
    SubRoutes Routes
}

type Router Uses

type Router interface {
    http.Handler
    Routes

    // Use appends one of 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)

    // 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)

    // 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 chi's Mux, using only the standard net/http.

type Routes Uses

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
}

Routes interface adds two methods for router traversal, which is also used by the `docgen` subpackage to generation documentation for Routers.

Directories

PathSynopsis
docgen
middleware
render

Package chi imports 7 packages (graph) and is imported by 45 packages. Updated 2017-03-18. Refresh now. Tools for package owners.