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 mux.Mux for its implementation, and so functions as thin wrapper around that pacakge.

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(loginUrl, logoffUrl string, routes []Route, middlewares ...middleware.Adapter)
  • func (r *DefaultRouter) CatchAll(handler http.HandlerFunc)
  • 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) SubrouterHost(host string) Router
  • func (r *DefaultRouter) UnauthedRoutes(routes []Route, middlewares ...middleware.Adapter)
• type Route
• type Router
  • func New(env string, logReq middleware.Adapter) 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(
	loginUrl,
	logoffUrl string,
	routes []Route,
	middlewares ...middleware.Adapter,
)

AuthedRoutes registers the set of Routes as those requiring authentication. AuthedRoutes applies the given middlewares before performing that check, using middleware.RequireAuthed.

middleware.RequireAuthed requires loginUrl and logoffUrl to appropriately redirect applicable requests. middlweare.RequireAuthed uses key to check whether a user is authenticated or not.

key ought to be the one returned by your keyring.Keyringable.CurrentUserKey.

func (*DefaultRouter) CatchAll

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

CatchAll sets up a handler for all routes to funnel to for e.g. maintenace mode.

func (*DefaultRouter) Handle

func (r *DefaultRouter) Handle(route Route)

Handle applies the Route to the Router.

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.Adapter on each Route. Any middleware.Adapter already assigned to a Route is appended to middlewares, so are called after the default set.

func (*DefaultRouter) OnEveryRequest

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

OnEveryRequest appends the middlewares to the existing stack that the *DefaultRouter will apply 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) SubrouterHost

func (r *DefaultRouter) SubrouterHost(host string) Router

func (*DefaultRouter) UnauthedRoutes

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

UnauthedRoutes registers the set of Routes as those requiring unauthenticated users. It applies the given middlewares before performing that check.

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.Adapter 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(loginUrl string, logoffUrl string, routes []Route, middlewares ...middleware.Adapter)

	// CatchAll sets up a handler for all routes to funnel to for e.g. maintenace mode.
	CatchAll(handler http.HandlerFunc)

	// 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.Adapter] 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

	SubrouterHost(host string) Router

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

	http.Handler
}

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

func New

func New(env string, logReq middleware.Adapter) 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.