A high performance fasthttp request router that scales well

Overview

FastHttpRouter

Build Status Coverage Status Go Report Card GoDoc GitHub release

FastHttpRouter is forked from httprouter which is a lightweight high performance HTTP request router (also called multiplexer or just mux for short) for fasthttp.

This router is optimized for high performance and a small memory footprint. It scales well even with very long paths and a large number of routes. A compressing dynamic trie (radix tree) structure is used for efficient matching.

License Related

  • The author of httprouter @julienschmidt did almost all the hard work of this router.
  • I respect the laws of open source. So LICENSE of httprouter is alway stay here: HttpRouterLicense.
  • What I do is just fit for fasthttp. I have no hope to build a huge but toxic go web framwork like iris.
  • I fork this repo is just because there is no router for fasthttp at that time. And fasthttprouter is the FIRST router for fasthttp.
  • fasthttprouter has been used in my online production and processes 17 million requests per day. It is fast and stable, so I decide to release a stable version.

Releases

  • [2016.10.24] v0.1.0 The first release version of fasthttprouter.

Features

Best Performance: FastHttpRouter is one of the fastest go web frameworks in the go-web-framework-benchmark. Even faster than httprouter itself.

  • Basic Test: The first test case is to mock 0 ms, 10 ms, 100 ms, 500 ms processing time in handlers. The concurrency clients are 5000.

  • Concurrency Test: In 30 ms processing time, the test result for 100, 1000, 5000 clients is:

See below for technical details of the implementation.

Only explicit matches: With other routers, like http.ServeMux, a requested URL path could match multiple patterns. Therefore they have some awkward pattern priority rules, like longest match or first registered, first matched. By design of this router, a request can only match exactly one or no route. As a result, there are also no unintended matches, which makes it great for SEO and improves the user experience.

Stop caring about trailing slashes: Choose the URL style you like, the router automatically redirects the client if a trailing slash is missing or if there is one extra. Of course it only does so, if the new path has a handler. If you don't like it, you can turn off this behavior.

Path auto-correction: Besides detecting the missing or additional trailing slash at no extra cost, the router can also fix wrong cases and remove superfluous path elements (like ../ or //). Is CAPTAIN CAPS LOCK one of your users? FastHttpRouter can help him by making a case-insensitive look-up and redirecting him to the correct URL.

Parameters in your routing pattern: Stop parsing the requested URL path, just give the path segment a name and the router delivers the dynamic value to you. Because of the design of the router, path parameters are very cheap.

Zero Garbage: The matching and dispatching process generates zero bytes of garbage. In fact, the only heap allocations that are made, is by building the slice of the key-value pairs for path parameters. If the request path contains no parameters, not a single heap allocation is necessary.

No more server crashes: You can set a Panic handler to deal with panics occurring during handling a HTTP request. The router then recovers and lets the PanicHandler log what happened and deliver a nice error page.

Perfect for APIs: The router design encourages to build sensible, hierarchical RESTful APIs. Moreover it has builtin native support for OPTIONS requests and 405 Method Not Allowed replies.

Of course you can also set custom NotFound and MethodNotAllowed handlers and serve static files.

Usage

This is just a quick introduction, view the GoDoc for details:

Let's start with a trivial example:

package main

import (
	"fmt"
	"log"

	"github.com/buaazp/fasthttprouter"
	"github.com/valyala/fasthttp"
)

func Index(ctx *fasthttp.RequestCtx) {
	fmt.Fprint(ctx, "Welcome!\n")
}

func Hello(ctx *fasthttp.RequestCtx) {
	fmt.Fprintf(ctx, "hello, %s!\n", ctx.UserValue("name"))
}

func main() {
	router := fasthttprouter.New()
	router.GET("/", Index)
	router.GET("/hello/:name", Hello)

	log.Fatal(fasthttp.ListenAndServe(":8080", router.Handler))
}

Named parameters

As you can see, :name is a named parameter. The values are accessible via RequestCtx.UserValues. You can get the value of a parameter by using the ctx.UserValue("name").

Named parameters only match a single path segment:

Pattern: /user/:user

 /user/gordon              match
 /user/you                 match
 /user/gordon/profile      no match
 /user/                    no match

Note: Since this router has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns /user/new and /user/:user for the same request method at the same time. The routing of different request methods is independent from each other.

Catch-All parameters

The second type are catch-all parameters and have the form *name. Like the name suggests, they match everything. Therefore they must always be at the end of the pattern:

Pattern: /src/*filepath

 /src/                     match
 /src/somefile.go          match
 /src/subdir/somefile.go   match

How does it work?

The router relies on a tree structure which makes heavy use of common prefixes, it is basically a compact prefix tree (or just Radix tree). Nodes with a common prefix also share a common parent. Here is a short example what the routing tree for the GET request method could look like:

Priority   Path             Handle
9          \                *<1>
3          ├s               nil
2          |├earch\         *<2>
1          |└upport\        *<3>
2          ├blog\           *<4>
1          |    └:post      nil
1          |         └\     *<5>
2          ├about-us\       *<6>
1          |        └team\  *<7>
1          └contact\        *<8>

Every *<num> represents the memory address of a handler function (a pointer). If you follow a path trough the tree from the root to the leaf, you get the complete route path, e.g \blog\:post\, where :post is just a placeholder (parameter) for an actual post name. Unlike hash-maps, a tree structure also allows us to use dynamic parts like the :post parameter, since we actually match against the routing patterns instead of just comparing hashes. [As benchmarks show][benchmark], this works very well and efficient.

Since URL paths have a hierarchical structure and make use only of a limited set of characters (byte values), it is very likely that there are a lot of common prefixes. This allows us to easily reduce the routing into ever smaller problems. Moreover the router manages a separate tree for every request method. For one thing it is more space efficient than holding a method->handle map in every single node, for another thing is also allows us to greatly reduce the routing problem before even starting the look-up in the prefix-tree.

For even better scalability, the child nodes on each tree level are ordered by priority, where the priority is just the number of handles registered in sub nodes (children, grandchildren, and so on..). This helps in two ways:

  1. Nodes which are part of the most routing paths are evaluated first. This helps to make as much routes as possible to be reachable as fast as possible.
  2. It is some sort of cost compensation. The longest reachable path (highest cost) can always be evaluated first. The following scheme visualizes the tree structure. Nodes are evaluated from top to bottom and from left to right.
├------------
├---------
├-----
├----
├--
├--
└-

Why doesn't this work with http.Handler?

Because fasthttp doesn't provide http.Handler. See this description.

Fasthttp works with RequestHandler functions instead of objects implementing Handler interface. So a FastHttpRouter provides a Handler interface to implement the fasthttp.ListenAndServe interface.

Just try it out for yourself, the usage of FastHttpRouter is very straightforward. The package is compact and minimalistic, but also probably one of the easiest routers to set up.

Where can I find Middleware X?

This package just provides a very efficient request router with a few extra features. The router is just a fasthttp.RequestHandler, you can chain any fasthttp.RequestHandler compatible middleware before the router. Or you could just write your own, it's very easy!

Have a look at these middleware examples:

Chaining with the NotFound handler

NOTE: It might be required to set Router.HandleMethodNotAllowed to false to avoid problems.

You can use another http.Handler, for example another router, to handle requests which could not be matched by this router by using the Router.NotFound handler. This allows chaining.

Static files

The NotFound handler can for example be used to serve static files from the root path / (like an index.html file along with other assets):

// Serve static files from the ./public directory
router.NotFound = fasthttp.FSHandler("./public", 0)

But this approach sidesteps the strict core rules of this router to avoid routing problems. A cleaner approach is to use a distinct sub-path for serving files, like /static/*filepath or /files/*filepath.

Web Frameworks based on FastHttpRouter

If the HttpRouter is a bit too minimalistic for you, you might try one of the following more high-level 3rd-party web frameworks building upon the HttpRouter package:

  • Waiting for you to do this...
Comments
  • Using original path in router

    Using original path in router

    Router's Handler method is using ctx.Path() to get the path, which is already parsed (normalized) by fasthttp. As a result, router attributes like RedirectTrailingSlash and RedirectFixedPath will never be used, since the paths it gets are always fixed. Also, for example, requests to /path//info can never get to the intended handler (which handles request on path /path/:param/info), since the path are getting normalized to /path/info by fasthttp.

    opened by GilbertGeliba 16
  • Replace Params with ctx.UserValues

    Replace Params with ctx.UserValues

    This PR uses: handle(ctx *fasthttp.RequestCtx) Instead of: handle(ctx *fasthttp.RequestCtx, ps fasthttprouter.Params)

    And

    Replaces Params with RequestCtx.UserValues

    So that:

    1. Chaining of other fasthttp based middleware functions is much easier.
    2. Removes the only major memory allocation that is happening in fasthttprouter and httprouter

    This will break the current API for existing users though...

    opened by yunspace 9
  • Fix query string on trailing slash redirect

    Fix query string on trailing slash redirect

    This commit fixes query string lost on trailing slash redirect.

    Example: handler - router.POST("/v1/info/", myHandler) request - mysite.com/v1/info?id=1 expected - HTTP 301 /v1/info/?id=1 got - HTTP 301 /v1/info/

    opened by bbrodriges 8
  • Ask: how to rewrite body?

    Ask: how to rewrite body?

    If I use router.NotFound = fasthttp.FSHandler("./public", 0) to handle the static files, but I want to add a custom page if the static file not found, what should I do?

    opened by kokizzu 6
  • missing stack trace in case of panic

    missing stack trace in case of panic

    var panicHandler = func(ctx *fasthttp.RequestCtx, p interface{}) {
    	// use runtime to get error stack
    }
    ....
    ....
    
    // intialise router
    router = fasthttprouter.New()
    router.PanicHandler = panicHandler
    

    If panic has occurred inside my code, then in panicHandler I am not able to see the stack trace where panic started, it shows only fasthttp stack. Anyway to see the original stack ?

    opened by devghosh 5
  • Converto type interface to int

    Converto type interface to int

    I want to get integer value: var id = c.UserValue("id") but i got this error : cannot convert c.UserValue("id") (type interface {}) to type int: need type assertion what should I do? Thanks

    opened by araneta 5
  • Static file example?

    Static file example?

    Hi, I'm having no luck trying to implement a static file handler for a given request path. I can see your comment in Readme ...use a distinct sub-path for serving files, like /static/*filepath but I cannot make it work. I tried this without success:

    router.GET("/js/*filepath", fasthttp.FSHandler("../static/js", 0)) 
    

    Could you please add a working example?

    todo 
    opened by nkev 5
  • body size exceeds the given limit

    body size exceeds the given limit

    2017/03/27 16:12:59 error when serving connection "127.0.0.1:8083"<->"127.0.0.1:35588": body size exceeds the given limit

    I got those error when uploading a big picture, how to set maxRequestBodySize?

    opened by kokizzu 3
  • License-related question

    License-related question

    Hi. I'm working on gramework, and tonight I've integrated modified fasthttprouter. I was unable to solve integration problems without rewriting it to use *gramework.Context instead of *fasthttp.RequestCtx. So, first of all, any fasthttprouter-related code placed in fasthttprouter_*.go files. Second, I modified fasthttprouter file headers so now it looks like this:

    // Copyright 2013 Julien Schmidt. All rights reserved.
    // Copyright (c) 2015-2016, 招牌疯子
    // Copyright (c) 2017, Kirill Danshin
    // Use of this source code is governed by a BSD-style license that can be found
    // in the 3rd-Party License/fasthttprouter file.
    

    This header placed in all fasthttprouter_*.go files except fasthttprouter_cache*.go, that I've implemented from scratch.

    Licenses placed in this file earlier, because I've forked fasthttprouter 5 days ago to implement hot paths caching.

    So, I've changed all uses of fasthttp RequestCtx to gramework Context, slightly optimize router, implemented simple cache for hot paths, and changed all tests so they now passed as expected.

    My question is simple: is it ok? Should I change/fix something?

    /cc @julienschmidt

    opened by kirillDanshin 3
  • Support more than one path param

    Support more than one path param

    The library does not support more than one path parameter being used (e.g. /:path/:path2) for a single route, otherwise it gives a gives a param error during startup.

    opened by jadbox 3
  • Add Group and Middleware support

    Add Group and Middleware support

    Hello contributors,

    I am looking for something like this

    router.Use(MiddlewareFunction)
    

    and

    api = router.Group("/api")
    api.Use(APIMiddleware)
    api.GET("/", handle)
    

    Can you add this features? Thanks.

    opened by vinhjaxt 2
  • Abandoned. Use fasthttp/router instead.

    Abandoned. Use fasthttp/router instead.

    See https://github.com/buaazp/fasthttprouter/issues/55 for additional info. Hopefully @buaazp will chime in and either refer people to another project or archive this one.

    opened by jamieson99 1
  • How to make ReverseProxy on fasthttprouter

    How to make ReverseProxy on fasthttprouter

    Is it possible to do the same on fasthttprouter?

    proxy := httputil.NewSingleHostReverseProxy(remote)
    proxy.Transport = new(DebugTransport)
    proxy.ServeHTTP(w, r)
    
    opened by LazarenkoA 1
  • How to init fake RequestCtx for unit test's?

    How to init fake RequestCtx for unit test's?

    Good day, For unit testing need somehow make face RequestCtx struct to use it in testing router handler? The question: how make it nice and easy, maybe already somebody have made router handler's functions test?

    opened by oranze 1
  • Recognize defined path in handler

    Recognize defined path in handler

    Hi!

    Let say I had

    GET("/customer/:id", handler)
    

    How can I find the original path "/customer/:id" inside func handler() ? Thank you

    opened by regorov 1
Releases(v0.1.1)
  • v0.1.1(Dec 20, 2016)

  • v0.1.0(Oct 25, 2016)

    The fasthttprouter is used for fasthttp web applications.

    1. Forked from httprouter
    2. High performance based on fasthttp
    3. Simple and easy to use.
    Source code(tar.gz)
    Source code(zip)
A high performance HTTP request router that scales well

HttpRouter HttpRouter is a lightweight high performance HTTP request router (also called multiplexer or just mux for short) for Go. In contrast to the

Julien Schmidt 13.5k Dec 9, 2021
:tongue: CleverGo is a lightweight, feature rich and high performance HTTP router for Go.

CleverGo CleverGo is a lightweight, feature rich and trie based high performance HTTP request router. go get -u clevergo.tech/clevergo English 简体中文 Fe

CleverGo Web Framework 248 Nov 17, 2022
Bxog is a simple and fast HTTP router for Go (HTTP request multiplexer).

Bxog is a simple and fast HTTP router for Go (HTTP request multiplexer). Usage An example of using the multiplexer: package main import ( "io" "net

Eduard 105 Sep 27, 2022
Go Server/API micro framework, HTTP request router, multiplexer, mux

?? gorouter Go Server/API micro framework, HTTP request router, multiplexer, mux. ?? ABOUT Contributors: Rafał Lorenz Want to contribute ? Feel free t

Rafał Lorenz 139 Nov 27, 2022
Go HTTP request router and web framework benchmark

Go HTTP Router Benchmark This benchmark suite aims to compare the performance of HTTP request routers for Go by implementing the routing structure of

Peter Kieltyka 27 Oct 4, 2022
High-speed, flexible tree-based HTTP router for Go.

httptreemux High-speed, flexible, tree-based HTTP router for Go. This is inspired by Julien Schmidt's httprouter, in that it uses a patricia tree, but

Daniel Imfeld 566 Nov 25, 2022
A benchmark suite aims to compare the performance of HTTP request routers for Go

Go HTTP Router Benchmark This benchmark suite aims to compare the performance of HTTP request routers for Go by implementing the routing structure of

null 3 Oct 25, 2021
Simple Golang HTTP router

Bellt Simple Golang HTTP router Bellt Package implements a request router with the aim of managing controller actions based on fixed and parameterized

Guilherme Caruso 55 Sep 27, 2022
FastRouter is a fast, flexible HTTP router written in Go.

FastRouter FastRouter is a fast, flexible HTTP router written in Go. FastRouter contains some customizable options, such as TrailingSlashesPolicy, Pan

Razon Yang 22 Sep 27, 2022
Go Router + Middleware. Your Contexts.

gocraft/web gocraft/web is a Go mux and middleware package. We deal with casting and reflection so YOUR code can be statically typed. And we're fast.

null 1.5k Nov 23, 2022
:rotating_light: Is a lightweight, fast and extensible zero allocation HTTP router for Go used to create customizable frameworks.

LARS LARS is a fast radix-tree based, zero allocation, HTTP router for Go. view examples. If looking for a more pure Go solution, be sure to check out

Go Playgound 389 Nov 18, 2022
A powerful HTTP router and URL matcher for building Go web servers with 🦍

gorilla/mux https://www.gorillatoolkit.org/pkg/mux Package gorilla/mux implements a request router and dispatcher for matching incoming requests to th

Gorilla Web Toolkit 17.7k Nov 28, 2022
An extremely fast Go (golang) HTTP router that supports regular expression route matching. Comes with full support for building RESTful APIs.

ozzo-routing You may consider using go-rest-api to jumpstart your new RESTful applications with ozzo-routing. Description ozzo-routing is a Go package

Ozzo Framework 445 Nov 15, 2022
Pure is a fast radix-tree based HTTP router

package pure Pure is a fast radix-tree based HTTP router that sticks to the native implementations of Go's "net/http" package; in essence, keeping the

Go Playgound 131 Nov 4, 2022
Echo Inspired Stand Alone URL Router

Vestigo - A Standalone Golang URL Router Abstract Many fast Golang URL routers are often embedded inside frameworks. Vestigo is a stand alone url rout

null 267 Nov 2, 2022
Go HTTP router

violetear Go HTTP router http://violetear.org Design Goals Keep it simple and small, avoiding extra complexity at all cost. KISS Support for static an

Nicolas Embriz 105 Sep 27, 2022
xujiajun/gorouter is a simple and fast HTTP router for Go. It is easy to build RESTful APIs and your web framework.

gorouter xujiajun/gorouter is a simple and fast HTTP router for Go. It is easy to build RESTful APIs and your web framework. Motivation I wanted a sim

徐佳军 532 Oct 30, 2022
lightweight, idiomatic and composable router for building Go HTTP services

chi is a lightweight, idiomatic and composable router for building Go HTTP services. It's especially good at helping you write large REST API services

go-chi 12.6k Nov 24, 2022
Router socks. One port socks for all the others.

Router socks The next step after compromising a machine is to enumerate the network behind. Many tools exist to expose a socks port on the attacker's

null 60 Nov 27, 2022