r2

README

R2

A minimalist HTTP request routing helper for Go.

The name "R2" stands for "Request Routing". That's all, R2 is just a capable little helper for HTTP request routing, not another fancy web framework that wraps net/http.

Features

• Extremely easy to use
• Router
  • Blazing fast
  • Based on the Radix Tree
  • Zero dynamic memory allocations
  • Sub-router support
  • Path parameter support
  • Path auto-correction support
• Middleware
• Zero third-party dependencies
• 100% code coverage

Installation

Open your terminal and execute

$ go get github.com/aofei/r2

done.

The only requirement is the Go, at least v1.13.

Hello, 世界

Create a file named hello.go

package main

import (
	"fmt"
	"net/http"

	"github.com/aofei/r2"
)

func main() {
	r := &r2.Router{}
	r.Handle("", "/hello/:name", http.HandlerFunc(handleHello))
	http.ListenAndServe("localhost:8080", r)
}

func handleHello(rw http.ResponseWriter, req *http.Request) {
	fmt.Fprintf(rw, "Hello, %s\n", r2.PathParams(req).Get("name"))
}

and run it

$ go run hello.go

then visit http://localhost:8080/hello/世界.

Community

If you want to discuss R2, or ask questions about it, simply post questions or ideas here.

Contributing

If you want to help build R2, simply follow this to send pull requests here.

License

This project is licensed under the MIT License.

License can be found here.

Documentation

Overview

Package r2 implements a minimalist HTTP request routing helper for Go.

Index

• func Defer(req *http.Request, f func())
• func PathParams(req *http.Request) url.Values
• func Values(req *http.Request) map[interface{}]interface{}
• type Middleware
• type MiddlewareFunc
  • func (mwf MiddlewareFunc) ChainHTTPHandler(next http.Handler) http.Handler
• type Router
  • func (r *Router) Handle(method, path string, h http.Handler, ms ...Middleware)
  • func (r *Router) Handler(req *http.Request) http.Handler
  • func (r *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (r *Router) Sub(pathPrefix string, ms ...Middleware) *Router

Functions

func Defer

func Defer(req *http.Request, f func())

Defer pushes the `f` onto the stack of functions that will be called after the matched `http.Handler` for the `req` returns.

func PathParams

func PathParams(req *http.Request) url.Values

PathParams returns parsed path parameters of the `req`.

Note that the returned `url.Values` is always non-nil, unless the `req` is not from the `http.Handler` returned by the `Router.Handler`.

func Values

func Values(req *http.Request) map[interface{}]interface{}

Values returns request scoped arbitrary values of the `req`.

Note that the returned `map[interface{}]interface{}` is always non-nil, unless the `req` is not from the `http.Handler` returned by the `Router.Handler`.

Types

type Middleware

type Middleware interface {
	// ChainHTTPHandler chains the `next` to the returned `http.Handler`.
	//
	// Typically, the returned `http.Handler` is a closure which does
	// something with the `http.ResponseWriter` and `http.Request` passed to
	// it, and then calls the `next`.
	ChainHTTPHandler(next http.Handler) http.Handler
}

Middleware is used by the `Router` to chain the `http.Handler`s.

type MiddlewareFunc

type MiddlewareFunc func(next http.Handler) http.Handler

MiddlewareFunc is an adapter to allow the use of an ordinary function as a `Middleware`.

func (MiddlewareFunc) ChainHTTPHandler

func (mwf MiddlewareFunc) ChainHTTPHandler(next http.Handler) http.Handler

ChainHTTPHandler implements the `Middleware`.

type Router

type Router struct {
	// Parent is the parent `Router`.
	Parent *Router

	// PathPrefix is the path prefix of all routes to be registered.
	PathPrefix string

	// Middlewares is the `Middleware` chain that performs after routing.
	Middlewares []Middleware

	// NotFoundHandler writes 404 not found responses.
	//
	// If the `NotFoundHandler` is nil, a default one is used.
	//
	// Note that the `NotFoundHandler` will be ignored when the `Parent` is
	// not nil.
	NotFoundHandler http.Handler

	// MethodNotAllowedHandler writes 405 method not allowed responses.
	//
	// If the `MethodNotAllowedHandler` is nil, a default one is used.
	//
	// Note that the `MethodNotAllowedHandler` will be ignored when the
	// `Parent` is not nil.
	MethodNotAllowedHandler http.Handler

	// TSRHandler writes TSR (trailing slash redirect) responses.
	//
	// If the `TSRHandler` is nil, a default one is used.
	//
	// Note that the `TSRHandler` will be ignored when the `Parent` is not
	// nil.
	TSRHandler http.Handler
	// contains filtered or unexported fields
}

Router is the registry of all registered routes for request matching.

func (*Router) Handle

func (r *Router) Handle(method, path string, h http.Handler, ms ...Middleware)

Handle registers a new route for the `method` ("" means any) and `path` with the matching `h` and optional `ms`.

Note that a ':' followed by a name in the `path` declares a path parameter that matches all characters except '/'. And an '*' in the `path` declares a wildcard path parameter that greedily matches all characters, with "*" as its name. The `PathParams` can be used to get those declared path parameters after a request is matched.

func (*Router) Handler

func (r *Router) Handler(req *http.Request) http.Handler

Handler returns a matched `http.Handler` for the `req`.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements the `http.Handler`.

func (*Router) Sub

func (r *Router) Sub(pathPrefix string, ms ...Middleware) *Router

Sub returns a new instance of the `Router` inherited from the `r` with the `pathPrefix` and optional `ms`.