rootdown

README

rootdown

The internet demanded another Go router

Documentation

Overview

Package rootdown is the only HTTP router for Go.

Index

• func Get(r *http.Request, path string, args ...interface{}) (ok bool)
• type Middleware
• type MiddlewareStack
  • func (stack MiddlewareStack) AsMiddleware() Middleware
  • func (stack MiddlewareStack) Clone() MiddlewareStack
  • func (stack *MiddlewareStack) Push(mw Middleware)
• type Router
  • func (rr *Router) Get(path string, h http.HandlerFunc, middlewares ...Middleware)
  • func (rr *Router) Mount(path, root string, fsys fs.FS, middlewares ...Middleware) error
  • func (rr *Router) NotFound(h http.HandlerFunc, middlewares ...Middleware)
  • func (rr *Router) Post(path string, h http.HandlerFunc, middlewares ...Middleware)
  • func (rr *Router) Route(method, path string, h http.HandlerFunc, middlewares ...Middleware)
  • func (rr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

Examples

• MiddlewareStack

Functions

func Get

func Get(r *http.Request, path string, args ...interface{}) (ok bool)

Get gets a path segment from a request path by looking for wildcards (*) in the path and assigning the corresponding request path segement to the argument pointer. Arguments may be pointers to strings, []byte, or int. Byte slice pointer arguments are Base-64 decoded. If the path cannot be matched or there is an error decoding a byte slice or int path, Get returns false.

Types

type Middleware

type Middleware = func(h http.Handler) http.Handler

Middleware is any function that wraps an http.Handler returning a new http.Handler.

var RedirectFromSlash Middleware = redirectFromSlash

RedirectFromSlash returns a permanent redirect when a request path has a trailing slash.

var RedirectToSlash Middleware = redirectToSlash

RedirectToSlash returns a permanent redirect when a request path does not have a trailing slash.

type MiddlewareStack

type MiddlewareStack []Middleware

MiddlewareStack is a slice of Middleware for use with Router.

Example

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/carlmjohnson/rootdown"
)

func main() {
	mw1 := func(h http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			fmt.Println("middleware 1 start")
			h.ServeHTTP(w, r)
			fmt.Println("middleware 1 end")
		})
	}
	mw2 := func(h http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			fmt.Println("middleware 2 start")
			h.ServeHTTP(w, r)
			fmt.Println("middleware 2 end")
		})
	}

	h := func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("running handler")
		fmt.Fprintln(w, "hello, world")
	}

	var middlewares rootdown.MiddlewareStack
	middlewares.Push(mw1)
	middlewares.Push(mw2)

	var rr rootdown.Router
	rr.Get("/", h, middlewares...)

	req := httptest.NewRequest(http.MethodGet, "/", nil)
	rr.ServeHTTP(&httptest.ResponseRecorder{}, req)
}

Output:

middleware 1 start
middleware 2 start
running handler
middleware 2 end
middleware 1 end

func (MiddlewareStack) AsMiddleware

func (stack MiddlewareStack) AsMiddleware() Middleware

As Middleware returns a Middleware which applies each of the members of the stack to its handlers.

func (MiddlewareStack) Clone

func (stack MiddlewareStack) Clone() MiddlewareStack

Clone returns a shallow copy of the stack.

func (*MiddlewareStack) Push

func (stack *MiddlewareStack) Push(mw Middleware)

Push adds a Middleware to end of the stack.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router is an HTTP request router. See rr.Route for details on routing.

func (*Router) Get

func (rr *Router) Get(path string, h http.HandlerFunc, middlewares ...Middleware)

Get is a shortcut for rr.Route(http.MethodGet, ...).

func (*Router) Mount

func (rr *Router) Mount(path, root string, fsys fs.FS, middlewares ...Middleware) error

Mount mounts fsys at the given path by walking the filesystem starting at root and adding a Get entry for every file it finds. As a result, if new files are added to fsys at runtime, they won't be picked up. Mount returns an error if any occur in the process of walking the fsys.

func (*Router) NotFound

func (rr *Router) NotFound(h http.HandlerFunc, middlewares ...Middleware)

NotFound is a shortcut for rr.Route("*", "/...", ...).

func (*Router) Post

func (rr *Router) Post(path string, h http.HandlerFunc, middlewares ...Middleware)

Post is a shortcut for rr.Route(http.MethodPost, ...).

func (*Router) Route

func (rr *Router) Route(method, path string, h http.HandlerFunc, middlewares ...Middleware)

Route adds a route to the Router. Optional middleware is wrapped around the handler at add time.

Methods are case sensitive and should be uppercase. A wildcard (*) will match any method.

Paths are matched without regard to the presence or absence of trailing slashes. (See the redirect middleware to enforce the presence/absence of a slash.) If a path contains a wildcard (*), any string may be present in that path segment. If a request path cannot be matched, the Router looks for the closest parent route that has a ... path added and routes to that handler.

func (*Router) ServeHTTP

func (rr *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP fulfills the http.Handler interface.