router

Documentation

Overview

Package router defines what an HTTP server is and a default implementation of it.

The package defines what a web server router does in Trails through Router and a default implementation of it: DefaultRouter. DefaultRouter utilizes github.com/gorilla/mux.Mux for most of its implementation.

A Router leverages a standardized data model - a Route - when registering how requests should be routed. A path and an HTTP method comprise a Route. An implementation of http.Handler is the function called when a request matches a Route. Before a request gets to a handler, though, any middlewares added to the Route are called in the order they appear.

It is often the case that many routes for a web server share identical middleware stacks, which aid in directing, redirecting, or adding contextual information to a request. It is also often the case that small errors can lead to registering a route incorrectly, thereby unintentionally exposing a resource or not collecting data necessary for actually handling a request. Thus, a Router provides conveniences for making a single call to register many logically associated Routes.

A Router expects two such groups of routes: those pointing to resources, alternatively, outside of or behind authentication barriers. The UnauthedRoutes and AuthedRoutes methods ensure routes are registered in the appropriate way, consequently.

Index

• type DefaultRouter
  • func (r *DefaultRouter) AuthedRoutes(key ctx.CtxKeyable, loginUrl string, logoffUrl string, routes []Route, ...)
  • func (r *DefaultRouter) Handle(route Route)
  • func (r *DefaultRouter) HandleNotFound(handler http.HandlerFunc)
  • func (r *DefaultRouter) HandleRoutes(routes []Route, middlewares ...middleware.Adapter)
  • func (r *DefaultRouter) OnEveryRequest(middlewares ...middleware.Adapter)
  • func (r *DefaultRouter) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *DefaultRouter) Subrouter(prefix string) Router
  • func (r *DefaultRouter) UnauthedRoutes(key ctx.CtxKeyable, routes []Route, middlewares ...middleware.Adapter)
• type Route
• type Router
  • func NewRouter(env string) Router

Types

type DefaultRouter

type DefaultRouter struct {
	Env string

	*mux.Router
	// contains filtered or unexported fields
}

The DefaultRouter handles HTTP requests to any Routes it is configured with.

DefaultRouter applies the middleware.ReportPanic handler to all registered routes.

DefaultRouter routes requests for assets to their location in a standard trails app layout. DefaultRouter applies a "Cache-Control" header to responses for assets.

func (*DefaultRouter) AuthedRoutes

func (r *DefaultRouter) AuthedRoutes(
	key ctx.CtxKeyable,
	loginUrl string,
	logoffUrl string,
	routes []Route,
	middlewares ...middleware.Adapter,
)

AuthedRoutes registers the set of Routes as those requiring authentication.

func (*DefaultRouter) Handle

func (r *DefaultRouter) Handle(route Route)

Handle applies the Route to the Router, wrapping the Handler in middleware.ReportPanic.

func (*DefaultRouter) HandleNotFound

func (r *DefaultRouter) HandleNotFound(handler http.HandlerFunc)

HandleNotFound sets the provided http.HandlerFunc as the default function for when no other registered Route is matched.

func (*DefaultRouter) HandleRoutes

func (r *DefaultRouter) HandleRoutes(routes []Route, middlewares ...middleware.Adapter)

HandleRoutes registers the set of Routes on the Router and includes all the middleware.Adapters on each Route. Any middleware.Adapters already assigned to a Route are appended to middlewares, so are called after the default set.

func (*DefaultRouter) OnEveryRequest

func (r *DefaultRouter) OnEveryRequest(middlewares ...middleware.Adapter)

OnEveryRequest sets a middleware stack to be applied to every request.

func (*DefaultRouter) ServeHTTP

func (r *DefaultRouter) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP responds to an HTTP request.

func (*DefaultRouter) Subrouter

func (r *DefaultRouter) Subrouter(prefix string) Router

Subrouter constructs a Router that handles requests to endpoints matching the prefix.

e.g., r.Subrouter("/api/v1") handles requests to endpoints like /api/v1/users

func (*DefaultRouter) UnauthedRoutes

func (r *DefaultRouter) UnauthedRoutes(key ctx.CtxKeyable, routes []Route, middlewares ...middleware.Adapter)

UnauthedRoutes registers the set of Routes as those requiring unauthenticated users.

type Route

type Route struct {
	Path        string
	Method      string
	Handler     http.HandlerFunc
	Middlewares []middleware.Adapter
}

A Route maps a path and HTTP method to an http.HandlerFunc. Additional middleware.Adapters can be called when a server handles a request matching the Route.

type Router

type Router interface {
	// AuthedRoutes registers the set of Routes as those requiring authentication.
	AuthedRoutes(key ctx.CtxKeyable, loginUrl string, logoffUrl string, routes []Route, middlewares ...middleware.Adapter)

	// Handle applies the Route to the Router
	Handle(route Route)

	// HandleNotFound sets the provided http.HandlerFunc as the default function
	// for when no other registered Route is matched.
	HandleNotFound(handler http.HandlerFunc)

	// HandleRoutes registers the set of Routes.
	// HandleRoutes calls the provided middlewares before sending a request to the Route.
	HandleRoutes(routes []Route, middlewares ...middleware.Adapter)

	// OnEveryRequest sets the middleware stack to be applied before every request
	//
	// Other methods applying a set of middleware.Adapters will always apply theirs
	// after the set defined by OnEveryRequest.
	OnEveryRequest(middlewares ...middleware.Adapter)

	// Subrouter prefixes a Router's handling with the provided string
	Subrouter(prefix string) Router

	// UnauthedRoutes handles the set of Routes
	UnauthedRoutes(key ctx.CtxKeyable, routes []Route, middlewares ...middleware.Adapter)

	http.Handler
}

A Router handles many Routes, directing HTTP requests to the appropriate endpoint.

func NewRouter

func NewRouter(env string) Router

NewRouter constructs an implementation of Router using DefaultRouter for the given environment.

TODO(dlk): use provided fs.FS and http.FS instead of http.FileServer.