## 1. Project Overview & Quickstart (valyala/fasthttp) ## File: README.md # fasthttp [](https://pkg.go.dev/github.com/valyala/fasthttp) [](https://goreportcard.com/report/github.com/valyala/fasthttp) Fast HTTP implementation for Go. ## fasthttp might not be for you! fasthttp was designed for some high performance edge cases. **Unless** your server/client needs to handle **thousands of small to medium requests per second** and needs a consistent low millisecond response time fasthttp might not be for you. **For most cases `net/http` is much better** as it's easier to use and can handle more cases. For most cases you won't even notice the performance difference. ## General info and links Currently fasthttp is successfully used by [VertaMedia](https://vertamedia.com/) in a production serving up to 200K rps from more than 1.5M concurrent keep-alive connections per physical server. [TechEmpower Benchmark round 23 results](https://www.techempower.com/benchmarks/#section=data-r23&hw=ph&test=plaintext) [Server Benchmarks](#http-server-performance-comparison-with-nethttp) [Client Benchmarks](#http-client-comparison-with-nethttp) [Install](#install) [Documentation](https://pkg.go.dev/github.com/valyala/fasthttp) [Examples from docs](https://pkg.go.dev/github.com/valyala/fasthttp#pkg-examples) [Code examples](examples) [Awesome fasthttp tools](https://github.com/fasthttp) [Switching from net/http to fasthttp](#switching-from-nethttp-to-fasthttp) [Fasthttp best practices](#fasthttp-best-practices) [Related projects](#related-projects) [FAQ](#faq) ## HTTP server performance comparison with [net/http](https://pkg.go.dev/net/http) In short, fasthttp server is up to 6 times faster than net/http. Below are benchmark results. _GOMAXPROCS=1_ net/http server: ``` $ GOMAXPROCS=1 go test -bench=NetHTTPServerGet -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkNetHTTPServerGet1ReqPerConn 722565 15327 ns/op 3258 B/op 36 allocs/op BenchmarkNetHTTPServerGet2ReqPerConn 990067 11533 ns/op 2817 B/op 28 allocs/op BenchmarkNetHTTPServerGet10ReqPerConn 1376821 8734 ns/op 2483 B/op 23 allocs/op BenchmarkNetHTTPServerGet10KReqPerConn 1691265 7151 ns/op 2385 B/op 21 allocs/op BenchmarkNetHTTPServerGet1ReqPerConn10KClients 643940 17152 ns/op 3529 B/op 36 allocs/op BenchmarkNetHTTPServerGet2ReqPerConn10KClients 868576 14010 ns/op 2826 B/op 28 allocs/op BenchmarkNetHTTPServerGet10ReqPerConn10KClients 1297398 9329 ns/op 2611 B/op 23 allocs/op BenchmarkNetHTTPServerGet100ReqPerConn10KClients 1467963 7902 ns/op 2450 B/op 21 allocs/op ``` fasthttp server: ``` $ GOMAXPROCS=1 go test -bench=kServerGet -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkServerGet1ReqPerConn 4304683 2733 ns/op 0 B/op 0 allocs/op BenchmarkServerGet2ReqPerConn 5685157 2140 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10ReqPerConn 7659729 1550 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10KReqPerConn 8580660 1422 ns/op 0 B/op 0 allocs/op BenchmarkServerGet1ReqPerConn10KClients 4092148 3009 ns/op 0 B/op 0 allocs/op BenchmarkServerGet2ReqPerConn10KClients 5272755 2208 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10ReqPerConn10KClients 7566351 1546 ns/op 0 B/op 0 allocs/op BenchmarkServerGet100ReqPerConn10KClients 8369295 1418 ns/op 0 B/op 0 allocs/op ``` _GOMAXPROCS=4_ net/http server: ``` $ GOMAXPROCS=4 go test -bench=NetHTTPServerGet -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkNetHTTPServerGet1ReqPerConn-4 2670654 4542 ns/op 3263 B/op 36 allocs/op BenchmarkNetHTTPServerGet2ReqPerConn-4 3376021 3559 ns/op 2823 B/op 28 allocs/op BenchmarkNetHTTPServerGet10ReqPerConn-4 4387959 2707 ns/op 2489 B/op 23 allocs/op BenchmarkNetHTTPServerGet10KReqPerConn-4 5412049 2179 ns/op 2386 B/op 21 allocs/op BenchmarkNetHTTPServerGet1ReqPerConn10KClients-4 2226048 5216 ns/op 3289 B/op 36 allocs/op BenchmarkNetHTTPServerGet2ReqPerConn10KClients-4 2989957 3982 ns/op 2839 B/op 28 allocs/op BenchmarkNetHTTPServerGet10ReqPerConn10KClients-4 4383570 2834 ns/op 2514 B/op 23 allocs/op BenchmarkNetHTTPServerGet100ReqPerConn10KClients-4 5315100 2394 ns/op 2419 B/op 21 allocs/op ``` fasthttp server: ``` $ GOMAXPROCS=4 go test -bench=kServerGet -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkServerGet1ReqPerConn-4 7797037 1494 ns/op 0 B/op 0 allocs/op BenchmarkServerGet2ReqPerConn-4 13004892 963.7 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10ReqPerConn-4 22479348 522.6 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10KReqPerConn-4 25899390 451.4 ns/op 0 B/op 0 allocs/op BenchmarkServerGet1ReqPerConn10KClients-4 8421531 1469 ns/op 0 B/op 0 allocs/op BenchmarkServerGet2ReqPerConn10KClients-4 13426772 903.7 ns/op 0 B/op 0 allocs/op BenchmarkServerGet10ReqPerConn10KClients-4 21899584 513.5 ns/op 0 B/op 0 allocs/op BenchmarkServerGet100ReqPerConn10KClients-4 25291686 439.4 ns/op 0 B/op 0 allocs/op ``` ## HTTP client comparison with net/http In short, fasthttp client is up to 4 times faster than net/http. Below are benchmark results. _GOMAXPROCS=1_ net/http client: ``` $ GOMAXPROCS=1 go test -bench='HTTPClient(Do|GetEndToEnd)' -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkNetHTTPClientDoFastServer 885637 13883 ns/op 3384 B/op 44 allocs/op BenchmarkNetHTTPClientGetEndToEnd1TCP 203875 55619 ns/op 6296 B/op 70 allocs/op BenchmarkNetHTTPClientGetEndToEnd10TCP 231290 54618 ns/op 6299 B/op 70 allocs/op BenchmarkNetHTTPClientGetEndToEnd100TCP 202879 58278 ns/op 6304 B/op 69 allocs/op BenchmarkNetHTTPClientGetEndToEnd1Inmemory 396764 26878 ns/op 6216 B/op 69 allocs/op BenchmarkNetHTTPClientGetEndToEnd10Inmemory 396422 28373 ns/op 6209 B/op 68 allocs/op BenchmarkNetHTTPClientGetEndToEnd100Inmemory 363976 33101 ns/op 6326 B/op 68 allocs/op BenchmarkNetHTTPClientGetEndToEnd1000Inmemory 208881 51725 ns/op 8298 B/op 84 allocs/op BenchmarkNetHTTPClientGetEndToEndWaitConn1Inmemory 237 50451765 ns/op 7474 B/op 79 allocs/op BenchmarkNetHTTPClientGetEndToEndWaitConn10Inmemory 237 50447244 ns/op 7434 B/op 77 allocs/op BenchmarkNetHTTPClientGetEndToEndWaitConn100Inmemory 238 50067993 ns/op 8639 B/op 82 allocs/op BenchmarkNetHTTPClientGetEndToEndWaitConn1000Inmemory 1366 7324990 ns/op 4064 B/op 44 allocs/op ``` fasthttp client: ``` $ GOMAXPROCS=1 go test -bench='kClient(Do|GetEndToEnd)' -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkClientGetEndToEnd1TCP 406376 26558 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd10TCP 517425 23595 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd100TCP 474800 25153 ns/op 3 B/op 0 allocs/op BenchmarkClientGetEndToEnd1Inmemory 2563800 4827 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd10Inmemory 2460135 4805 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd100Inmemory 2520543 4846 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd1000Inmemory 2437015 4914 ns/op 2 B/op 0 allocs/op BenchmarkClientGetEndToEnd10KInmemory 2481050 5049 ns/op 9 B/op 0 allocs/op ``` _GOMAXPROCS=4_ net/http client: ``` $ GOMAXPROCS=4 go test -bench='HTTPClient(Do|GetEndToEnd)' -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkNetHTTPClientGetEndToEnd1TCP-4 767133 16175 ns/op 6304 B/op 69 allocs/op BenchmarkNetHTTPClientGetEndToEnd10TCP-4 785198 15276 ns/op 6295 B/op 69 allocs/op BenchmarkNetHTTPClientGetEndToEnd100TCP-4 780464 15605 ns/op 6305 B/op 69 allocs/op BenchmarkNetHTTPClientGetEndToEnd1Inmemory-4 1356932 8772 ns/op 6220 B/op 68 allocs/op BenchmarkNetHTTPClientGetEndToEnd10Inmemory-4 1379245 8726 ns/op 6213 B/op 68 allocs/op BenchmarkNetHTTPClientGetEndToEnd100Inmemory-4 1119213 10294 ns/op 6418 B/op 68 allocs/op BenchmarkNetHTTPClientGetEndToEnd1000Inmemory-4 504194 31010 ns/op 17668 B/op 102 allocs/op ``` fasthttp client: ``` $ GOMAXPROCS=4 go test -bench='kClient(Do|GetEndToEnd)' -benchmem -benchtime=10s cpu: Intel(R) Xeon(R) CPU @ 2.20GHz BenchmarkClientGetEndToEnd1TCP-4 1474552 8143 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd10TCP-4 1710270 7186 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd100TCP-4 1701672 6892 ns/op 4 B/op 0 allocs/op BenchmarkClientGetEndToEnd1Inmemory-4 6797713 1590 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd10Inmemory-4 6663642 1782 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd100Inmemory-4 6608209 1867 ns/op 0 B/op 0 allocs/op BenchmarkClientGetEndToEnd1000Inmemory-4 6254452 2645 ns/op 8 B/op 0 allocs/op BenchmarkClientGetEndToEnd10KInmemory-4 6944584 1966 ns/op 17 B/op 0 allocs/op ``` ## Install ``` go get -u github.com/valyala/fasthttp ``` ## Switching from net/http to fasthttp Unfortunately, fasthttp doesn't provide API identical to net/http. See the [FAQ](#faq) for details. There is [net/http -> fasthttp handler converter](https://pkg.go.dev/github.com/valyala/fasthttp/fasthttpadaptor), but it is better to write fasthttp request handlers by hand in order to use all of the fasthttp advantages (especially high performance :) ). Important points: - Fasthttp works with [RequestHandler functions](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler) instead of objects implementing [Handler interface](https://pkg.go.dev/net/http#Handler). Fortunately, it is easy to pass bound struct methods to fasthttp: ```go type MyHandler struct { foobar string } // request handler in net/http style, i.e. method bound to MyHandler struct. func (h *MyHandler) HandleFastHTTP(ctx *fasthttp.RequestCtx) { // notice that we may access MyHandler properties here - see h.foobar. fmt.Fprintf(ctx, "Hello, world! Requested path is %q. Foobar is %q", ctx.Path(), h.foobar) } // request handler in fasthttp style, i.e. just plain function. func fastHTTPHandler(ctx *fasthttp.RequestCtx) { fmt.Fprintf(ctx, "Hi there! RequestURI is %q", ctx.RequestURI()) } // pass bound struct method to fasthttp myHandler := &MyHandler{ foobar: "foobar", } fasthttp.ListenAndServe(":8080", myHandler.HandleFastHTTP) // pass plain function to fasthttp fasthttp.ListenAndServe(":8081", fastHTTPHandler) ``` - The [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler) accepts only one argument - [RequestCtx](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx). It contains all the functionality required for http request processing and response writing. Below is an example of a simple request handler conversion from net/http to fasthttp. ```go // net/http request handler requestHandler := func(w http.ResponseWriter, r *http.Request) { switch r.URL.Path { case "/foo": fooHandler(w, r) case "/bar": barHandler(w, r) default: http.Error(w, "Unsupported path", http.StatusNotFound) } } ``` ```go // the corresponding fasthttp request handler requestHandler := func(ctx *fasthttp.RequestCtx) { switch string(ctx.Path()) { case "/foo": fooHandler(ctx) case "/bar": barHandler(ctx) default: ctx.Error("Unsupported path", fasthttp.StatusNotFound) } } ``` - Fasthttp allows setting response headers and writing response body in an arbitrary order. There is no 'headers first, then body' restriction like in net/http. The following code is valid for fasthttp: ```go requestHandler := func(ctx *fasthttp.RequestCtx) { // set some headers and status code first ctx.SetContentType("foo/bar") ctx.SetStatusCode(fasthttp.StatusOK) // then write the first part of body fmt.Fprintf(ctx, "this is the first part of body\n") // then set more headers ctx.Response.Header.Set("Foo-Bar", "baz") // then write more body fmt.Fprintf(ctx, "this is the second part of body\n") // then override already written body ctx.SetBody([]byte("this is completely new body contents")) // then update status code ctx.SetStatusCode(fasthttp.StatusNotFound) // basically, anything may be updated many times before // returning from RequestHandler. // // Unlike net/http fasthttp doesn't put response to the wire until // returning from RequestHandler. } ``` - Fasthttp doesn't provide [ServeMux](https://pkg.go.dev/net/http#ServeMux), but there are more powerful third-party routers and web frameworks with fasthttp support: - [fasthttp-routing](https://github.com/qiangxue/fasthttp-routing) - [router](https://github.com/fasthttp/router) - [lu](https://github.com/vincentLiuxiang/lu) - [atreugo](https://github.com/savsgio/atreugo) - [Fiber](https://github.com/gofiber/fiber) - [Gearbox](https://github.com/gogearbox/gearbox) Net/http code with simple ServeMux is trivially converted to fasthttp code: ```go // net/http code m := &http.ServeMux{} m.HandleFunc("/foo", fooHandlerFunc) m.HandleFunc("/bar", barHandlerFunc) m.Handle("/baz", bazHandler) http.ListenAndServe(":80", m) ``` ```go // the corresponding fasthttp code m := func(ctx *fasthttp.RequestCtx) { switch string(ctx.Path()) { case "/foo": fooHandlerFunc(ctx) case "/bar": barHandlerFunc(ctx) case "/baz": bazHandler.HandlerFunc(ctx) default: ctx.Error("not found", fasthttp.StatusNotFound) } } fasthttp.ListenAndServe(":80", m) ``` - Because creating a new channel for every request is just too expensive, so the channel returned by RequestCtx.Done() is only closed when the server is shutting down. ```go func main() { fasthttp.ListenAndServe(":8080", fasthttp.TimeoutHandler(func(ctx *fasthttp.RequestCtx) { select { case <-ctx.Done(): // ctx.Done() is only closed when the server is shutting down. log.Println("context cancelled") return case <-time.After(10 * time.Second): log.Println("process finished ok") } }, time.Second*2, "timeout")) } ``` - net/http -> fasthttp conversion table: - All the pseudocode below assumes w, r and ctx have these types: ```go var ( w http.ResponseWriter r *http.Request ctx *fasthttp.RequestCtx ) ``` - [r.Body](https://pkg.go.dev/net/http#Request) **➜** [ctx.PostBody()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.PostBody) - [r.URL.Path](https://pkg.go.dev/net/url#URL) **➜** [ctx.Path()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Path) - [r.URL](https://pkg.go.dev/net/http#Request) **➜** [ctx.URI()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.URI) - [r.Method](https://pkg.go.dev/net/http#Request) **➜** [ctx.Method()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Method) - [r.Header](https://pkg.go.dev/net/http#Request) **➜** [ctx.Request.Header](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHeader) - [r.Header.Get()](https://pkg.go.dev/net/http#Header.Get) **➜** [ctx.Request.Header.Peek()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHeader.Peek) - [r.Host](https://pkg.go.dev/net/http#Request) **➜** [ctx.Host()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Host) - [r.Form](https://pkg.go.dev/net/http#Request) **➜** [ctx.QueryArgs()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.QueryArgs) + [ctx.PostArgs()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.PostArgs) - [r.PostForm](https://pkg.go.dev/net/http#Request) **➜** [ctx.PostArgs()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.PostArgs) - [r.FormValue()](https://pkg.go.dev/net/http#Request.FormValue) **➜** [ctx.FormValue()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.FormValue) - [r.FormFile()](https://pkg.go.dev/net/http#Request.FormFile) **➜** [ctx.FormFile()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.FormFile) - [r.MultipartForm](https://pkg.go.dev/net/http#Request) **➜** [ctx.MultipartForm()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.MultipartForm) For untrusted multipart input, use [ctx.MultipartFormWithLimit()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.MultipartFormWithLimit) (or a custom [Server.FormValueFunc](https://pkg.go.dev/github.com/valyala/fasthttp#Server)) to enforce a parsing size limit. - [r.RemoteAddr](https://pkg.go.dev/net/http#Request) **➜** [ctx.RemoteAddr()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.RemoteAddr) - [r.RequestURI](https://pkg.go.dev/net/http#Request) **➜** [ctx.RequestURI()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.RequestURI) - [r.TLS](https://pkg.go.dev/net/http#Request) **➜** [ctx.IsTLS()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.IsTLS) - [r.Cookie()](https://pkg.go.dev/net/http#Request.Cookie) **➜** [ctx.Request.Header.Cookie()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHeader.Cookie) - [r.Referer()](https://pkg.go.dev/net/http#Request.Referer) **➜** [ctx.Referer()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Referer) - [r.UserAgent()](https://pkg.go.dev/net/http#Request.UserAgent) **➜** [ctx.UserAgent()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.UserAgent) - [w.Header()](https://pkg.go.dev/net/http#ResponseWriter) **➜** [ctx.Response.Header](https://pkg.go.dev/github.com/valyala/fasthttp#ResponseHeader) - [w.Header().Set()](https://pkg.go.dev/net/http#Header.Set) **➜** [ctx.Response.Header.Set()](https://pkg.go.dev/github.com/valyala/fasthttp#ResponseHeader.Set) - [w.Header().Set("Content-Type")](https://pkg.go.dev/net/http#Header.Set) **➜** [ctx.SetContentType()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.SetContentType) - [w.Header().Set("Set-Cookie")](https://pkg.go.dev/net/http#Header.Set) **➜** [ctx.Response.Header.SetCookie()](https://pkg.go.dev/github.com/valyala/fasthttp#ResponseHeader.SetCookie) - [w.Write()](https://pkg.go.dev/net/http#ResponseWriter) **➜** [ctx.Write()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Write), [ctx.SetBody()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.SetBody), [ctx.SetBodyStream()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.SetBodyStream), [ctx.SetBodyStreamWriter()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.SetBodyStreamWriter) - [w.WriteHeader()](https://pkg.go.dev/net/http#ResponseWriter) **➜** [ctx.SetStatusCode()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.SetStatusCode) - [w.(http.Hijacker).Hijack()](https://pkg.go.dev/net/http#Hijacker) **➜** [ctx.Hijack()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Hijack) - [http.Error()](https://pkg.go.dev/net/http#Error) **➜** [ctx.Error()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Error) - [http.FileServer()](https://pkg.go.dev/net/http#FileServer) **➜** [fasthttp.FSHandler()](https://pkg.go.dev/github.com/valyala/fasthttp#FSHandler), [fasthttp.FS](https://pkg.go.dev/github.com/valyala/fasthttp#FS) - [http.ServeFile()](https://pkg.go.dev/net/http#ServeFile) **➜** [fasthttp.ServeFile()](https://pkg.go.dev/github.com/valyala/fasthttp#ServeFile) - [http.Redirect()](https://pkg.go.dev/net/http#Redirect) **➜** [ctx.Redirect()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Redirect) - [http.NotFound()](https://pkg.go.dev/net/http#NotFound) **➜** [ctx.NotFound()](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.NotFound) - [http.StripPrefix()](https://pkg.go.dev/net/http#StripPrefix) **➜** [fasthttp.PathRewriteFunc](https://pkg.go.dev/github.com/valyala/fasthttp#PathRewriteFunc) - _VERY IMPORTANT!_ Fasthttp disallows holding references to [RequestCtx](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) or to its' members after returning from [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler). Otherwise [data races](http://go.dev/blog/race-detector) are inevitable. Carefully inspect all the net/http request handlers converted to fasthttp whether they retain references to RequestCtx or to its' members after returning. RequestCtx provides the following _band aids_ for this case: - Wrap RequestHandler into [TimeoutHandler](https://pkg.go.dev/github.com/valyala/fasthttp#TimeoutHandler). - Call [TimeoutError](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.TimeoutError) before returning from RequestHandler if there are references to RequestCtx or to its' members. See [the example](https://pkg.go.dev/github.com/valyala/fasthttp#example-RequestCtx-TimeoutError) for more details. Use this brilliant tool - [race detector](http://go.dev/blog/race-detector) - for detecting and eliminating data races in your program. If you detected data race related to fasthttp in your program, then there is high probability you forgot calling [TimeoutError](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.TimeoutError) before returning from [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler). - Blind switching from net/http to fasthttp won't give you performance boost. While fasthttp is optimized for speed, its' performance may be easily saturated by slow [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler). So [profile](http://go.dev/blog/pprof) and optimize your code after switching to fasthttp. For instance, use [quicktemplate](https://github.com/valyala/quicktemplate) instead of [html/template](https://pkg.go.dev/html/template). - See also [fasthttputil](https://pkg.go.dev/github.com/valyala/fasthttp/fasthttputil), [fasthttpadaptor](https://pkg.go.dev/github.com/valyala/fasthttp/fasthttpadaptor) and [expvarhandler](https://pkg.go.dev/github.com/valyala/fasthttp/expvarhandler). ## Performance optimization tips for multi-core systems - Use [reuseport](https://pkg.go.dev/github.com/valyala/fasthttp/reuseport) listener. - Run a separate server instance per CPU core with GOMAXPROCS=1. - Pin each server instance to a separate CPU core using [taskset](http://linux.die.net/man/1/taskset). - Ensure the interrupts of multiqueue network card are evenly distributed between CPU cores. See [this article](https://blog.cloudflare.com/how-to-achieve-low-latency/) for details. - Use the latest version of Go as each version contains performance improvements. ## Fasthttp best practices - Do not allocate objects and `[]byte` buffers - just reuse them as much as possible. Fasthttp API design encourages this. - [sync.Pool](https://pkg.go.dev/sync#Pool) is your best friend. - [Profile your program](http://go.dev/blog/pprof) in production. `go tool pprof --alloc_objects your-program mem.pprof` usually gives better insights for optimization opportunities than `go tool pprof your-program cpu.pprof`. - Write [tests and benchmarks](https://pkg.go.dev/testing) for hot paths. - Avoid conversion between `[]byte` and `string`, since this may result in memory allocation+copy - see [this wiki page](https://github.com/golang/go/wiki/CompilerOptimizations#string-and-byte) for more details. - Verify your tests and production code under [race detector](https://go.dev/doc/articles/race_detector.html) on a regular basis. - Prefer [quicktemplate](https://github.com/valyala/quicktemplate) instead of [html/template](https://pkg.go.dev/html/template) in your webserver. - Set [Client.MaxResponseBodySize](https://pkg.go.dev/github.com/valyala/fasthttp#Client.MaxResponseBodySize) or [HostClient.MaxResponseBodySize](https://pkg.go.dev/github.com/valyala/fasthttp#HostClient.MaxResponseBodySize) to a positive limit when requesting untrusted servers. A non-positive value disables the response body limit and buffered responses may consume unbounded memory. PipelineClient does not provide a response body size limit. ## Unsafe Zero-Allocation Conversions In performance-critical code, converting between `[]byte` and `string` using standard Go allocations can be inefficient. To address this, `fasthttp` uses **unsafe**, zero-allocation helpers: > ⚠️ **Warning:** These conversions break Go's type safety. Use only when you're certain the converted value will not be mutated, as violating immutability can cause undefined behavior. ### `UnsafeString(b []byte) string` Converts a `[]byte` to a `string` **without memory allocation**. ```go // UnsafeString returns a string pointer without allocation func UnsafeString(b []byte) string { // #nosec G103 return *(*string)(unsafe.Pointer(&b)) } ``` ### `UnsafeBytes(s string) []byte` Converts a `string` to a `[]byte` **without memory allocation**. ```go // UnsafeBytes returns a byte pointer without allocation. func UnsafeBytes(s string) []byte { // #nosec G103 return unsafe.Slice(unsafe.StringData(s), len(s)) } ``` ### Use Cases & Caveats - These functions are ideal for performance-sensitive scenarios where allocations must be avoided (e.g., request/response processing loops). - **Do not** mutate the `[]byte` returned from `UnsafeBytes(s string)` if the original string is still in use, as strings are immutable in Go and may be shared across the runtime. - Use samples guarded with `#nosec G103` comments to suppress static analysis warnings about unsafe operations. ## Tricks with `[]byte` buffers The following tricks are used by fasthttp. Use them in your code too. - Standard Go functions accept nil buffers ```go var ( // both buffers are uninitialized dst []byte src []byte ) dst = append(dst, src...) // is legal if dst is nil and/or src is nil copy(dst, src) // is legal if dst is nil and/or src is nil (string(src) == "") // is true if src is nil (len(src) == 0) // is true if src is nil src = src[:0] // works like a charm with nil src // this for loop doesn't panic if src is nil for i, ch := range src { doSomething(i, ch) } ``` So throw away nil checks for `[]byte` buffers from you code. For example, ```go srcLen := 0 if src != nil { srcLen = len(src) } ``` becomes ```go srcLen := len(src) ``` - String may be appended to `[]byte` buffer with `append` ```go dst = append(dst, "foobar"...) ``` - `[]byte` buffer may be extended to its' capacity. ```go buf := make([]byte, 100) a := buf[:10] // len(a) == 10, cap(a) == 100. b := a[:100] // is valid, since cap(a) == 100. ``` - All fasthttp functions accept nil `[]byte` buffer ```go statusCode, body, err := fasthttp.Get(nil, "http://google.com/") uintBuf := fasthttp.AppendUint(nil, 1234) ``` - String and `[]byte` buffers may converted without memory allocations ```go func b2s(b []byte) string { return *(*string)(unsafe.Pointer(&b)) } func s2b(s string) (b []byte) { bh := (*reflect.SliceHeader)(unsafe.Pointer(&b)) sh := (*reflect.StringHeader)(unsafe.Pointer(&s)) bh.Data = sh.Data bh.Cap = sh.Len bh.Len = sh.Len return b } ``` ### Warning: This is an **unsafe** way, the result string and `[]byte` buffer share the same bytes. **Please make sure not to modify the bytes in the `[]byte` buffer if the string still survives!** ## Related projects - [fasthttp](https://github.com/fasthttp) - various useful helpers for projects based on fasthttp. - [fasthttp-routing](https://github.com/qiangxue/fasthttp-routing) - fast and powerful routing package for fasthttp servers. - [http2](https://github.com/dgrr/http2) - HTTP/2 implementation for fasthttp. - [router](https://github.com/fasthttp/router) - a high performance fasthttp request router that scales well. - [fasthttp-auth](https://github.com/casbin/fasthttp-auth) - Authorization middleware for fasthttp using Casbin. - [fastws](https://github.com/fasthttp/fastws) - Bloatless WebSocket package made for fasthttp to handle Read/Write operations concurrently. - [gramework](https://github.com/gramework/gramework) - a web framework made by one of fasthttp maintainers. - [lu](https://github.com/vincentLiuxiang/lu) - a high performance go middleware web framework which is based on fasthttp. - [websocket](https://github.com/fasthttp/websocket) - Gorilla-based websocket implementation for fasthttp. - [websocket](https://github.com/dgrr/websocket) - Event-based high-performance WebSocket library for zero-allocation websocket servers and clients. - [fasthttpsession](https://github.com/phachon/fasthttpsession) - a fast and powerful session package for fasthttp servers. - [atreugo](https://github.com/savsgio/atreugo) - High performance and extensible micro web framework with zero memory allocations in hot paths. - [kratgo](https://github.com/savsgio/kratgo) - Simple, lightweight and ultra-fast HTTP Cache to speed up your websites. - [kit-plugins](https://github.com/wencan/kit-plugins/tree/master/transport/fasthttp) - go-kit transport implementation for fasthttp. - [Fiber](https://github.com/gofiber/fiber) - An Expressjs inspired web framework running on Fasthttp. - [Gearbox](https://github.com/gogearbox/gearbox) - :gear: gearbox is a web framework written in Go with a focus on high performance and memory optimization. - [http2curl](https://github.com/li-jin-gou/http2curl) - A tool to convert fasthttp requests to curl command line. - [OpenTelemetry Golang Compile Time Instrumentation](https://github.com/alibaba/opentelemetry-go-auto-instrumentation) - A tool to monitor fasthttp application without changing any code with OpenTelemetry APIs. - [protoc-gen-httpgo](https://github.com/MUlt1mate/protoc-gen-httpgo) - A protoc plugin that generates fasthttp server and client code. ## FAQ - _Why creating yet another http package instead of optimizing net/http?_ Because net/http API limits many optimization opportunities. For example: - net/http Request object lifetime isn't limited by request handler execution time. So the server must create a new request object per each request instead of reusing existing objects like fasthttp does. - net/http headers are stored in a `map[string][]string`. So the server must parse all the headers, convert them from `[]byte` to `string` and put them into the map before calling user-provided request handler. This all requires unnecessary memory allocations avoided by fasthttp. - net/http client API requires creating a new response object per each request. - _Why fasthttp API is incompatible with net/http?_ Because net/http API limits many optimization opportunities. See the answer above for more details. Also certain net/http API parts are suboptimal for use: - Compare [net/http connection hijacking](https://pkg.go.dev/net/http#Hijacker) to [fasthttp connection hijacking](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Hijack). - Compare [net/http Request.Body reading](https://pkg.go.dev/net/http#Request) to [fasthttp request body reading](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.PostBody). - _Why fasthttp doesn't support HTTP/2.0 and WebSockets?_ [HTTP/2.0 support](https://github.com/fasthttp/http2) is in progress. [WebSockets](https://github.com/fasthttp/websockets) has been done already. Third parties also may use [RequestCtx.Hijack](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.Hijack) for implementing these goodies. - _Are there known net/http advantages comparing to fasthttp?_ Yes: - net/http supports [HTTP/2.0 starting from go1.6](https://pkg.go.dev/golang.org/x/net/http2). - net/http API is stable, while fasthttp API constantly evolves. - net/http handles more HTTP corner cases. - net/http can stream both request and response bodies - net/http can handle bigger bodies as it streams them by default. fasthttp buffers bodies unless streaming is enabled; bound untrusted client responses with `MaxResponseBodySize`. - net/http should contain less bugs, since it is used and tested by much wider audience. - _Why fasthttp API prefers returning `[]byte` instead of `string`?_ Because `[]byte` to `string` conversion isn't free - it requires memory allocation and copy. Feel free wrapping returned `[]byte` result into `string()` if you prefer working with strings instead of byte slices. But be aware that this has non-zero overhead. - _Which GO versions are supported by fasthttp?_ We support the same versions the Go team supports. Currently that is Go 1.25.x and newer. Older versions might work, but won't officially be supported. - _Please provide real benchmark data and server information_ See [this issue](https://github.com/valyala/fasthttp/issues/4). - _Are there plans to add request routing to fasthttp?_ There are no plans to add request routing into fasthttp. Use third-party routers and web frameworks with fasthttp support: - [fasthttp-routing](https://github.com/qiangxue/fasthttp-routing) - [router](https://github.com/fasthttp/router) - [gramework](https://github.com/gramework/gramework) - [lu](https://github.com/vincentLiuxiang/lu) - [atreugo](https://github.com/savsgio/atreugo) - [Fiber](https://github.com/gofiber/fiber) - [Gearbox](https://github.com/gogearbox/gearbox) - _I detected data race in fasthttp!_ Cool! [File a bug](https://github.com/valyala/fasthttp/issues/new). But before doing this check the following in your code: - Make sure there are no references to [RequestCtx](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) or to its' members after returning from [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler). - Make sure you call [TimeoutError](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx.TimeoutError) before returning from [RequestHandler](https://pkg.go.dev/github.com/valyala/fasthttp#RequestHandler) if there are references to [RequestCtx](https://pkg.go.dev/github.com/valyala/fasthttp#RequestCtx) or to its' members, which may be accessed by other goroutines. - _I didn't find an answer for my question here_ Try exploring [these questions](https://github.com/valyala/fasthttp/issues?q=label%3Aquestion). --- ## File: examples/multidomain/README.md # Multidomain using SSL certs example * Prints two messages depending on visited host. # How to build ``` make ``` # How to run ``` ./multidomain ``` --- ## File: examples/host_client/README.md # Host Client Example The HostClient is useful when calling an API from a single host. The example sets `MaxResponseBodySize` so an untrusted response cannot consume unbounded memory. The example also shows how to use URI. You may create the parsed URI once and reuse it in many requests. The URI has a username and password for Basic Auth but you may also set other parts i.e. `SetPath()`, `SetQueryString()`. # How to build and run Start a web server on localhost:8080 then execute: make ./host_client --- ## File: examples/helloworldserver/README.md # HelloWorld server example * Displays various request info. * Sets response headers and cookies. * Supports transparent compression. # How to build ``` make ``` # How to run ``` ./helloworldserver -addr=tcp.addr.to.listen:to ``` --- ## File: examples/fileserver/README.md # Static file server example * Serves files from the given directory. * Supports transparent response compression. * Supports byte range responses. * Generates directory index pages. * Supports TLS (aka SSL or HTTPS). * Supports virtual hosts. * Exports various stats on /stats path. # How to build ``` make ``` # How to run ``` ./fileserver -h ./fileserver -addr=tcp.addr.to.listen:to -dir=/path/to/directory/to/serve ``` # fileserver vs nginx performance comparison Serving default nginx path (`/usr/share/nginx/html` on ubuntu). * nginx ``` $ ./wrk -t 4 -c 16 -d 10 http://localhost:80 Running 10s test @ http://localhost:80 4 threads and 16 connections Thread Stats Avg Stdev Max +/- Stdev Latency 397.76us 1.08ms 20.23ms 95.19% Req/Sec 21.20k 2.49k 31.34k 79.65% 850220 requests in 10.10s, 695.65MB read Requests/sec: 84182.71 Transfer/sec: 68.88MB ``` * fileserver ``` $ ./wrk -t 4 -c 16 -d 10 http://localhost:8080 Running 10s test @ http://localhost:8080 4 threads and 16 connections Thread Stats Avg Stdev Max +/- Stdev Latency 447.99us 1.59ms 27.20ms 94.79% Req/Sec 37.13k 3.99k 47.86k 76.00% 1478457 requests in 10.02s, 1.03GB read Requests/sec: 147597.06 Transfer/sec: 105.15MB ``` 8 pipelined requests * nginx ``` $ ./wrk -s pipeline.lua -t 4 -c 16 -d 10 http://localhost:80 -- 8 Running 10s test @ http://localhost:80 4 threads and 16 connections Thread Stats Avg Stdev Max +/- Stdev Latency 1.34ms 2.15ms 30.91ms 92.16% Req/Sec 33.54k 7.36k 108.12k 76.81% 1339908 requests in 10.10s, 1.07GB read Requests/sec: 132705.81 Transfer/sec: 108.58MB ``` * fileserver ``` $ ./wrk -s pipeline.lua -t 4 -c 16 -d 10 http://localhost:8080 -- 8 Running 10s test @ http://localhost:8080 4 threads and 16 connections Thread Stats Avg Stdev Max +/- Stdev Latency 2.08ms 6.33ms 88.26ms 92.83% Req/Sec 116.54k 14.66k 167.98k 69.00% 4642226 requests in 10.03s, 3.23GB read Requests/sec: 462769.41 Transfer/sec: 329.67MB ``` --- ## File: examples/client/README.md # Client Example The Client is useful when working with multiple hostnames. See the simplest `sendGetRequest()` for GET and more advanced `sendPostRequest()` for a POST request. The `sendPostRequest()` also shows: * Per-request timeout with `DoTimeout()` * Limit buffered response bodies with `MaxResponseBodySize` * Send a body as bytes slice with `SetBodyRaw()`. This is useful if you generated a request body. Otherwise, prefer `SetBody()` which copies it. * Parse JSON from response * Gracefully show error messages i.e. timeouts as warnings and other errors as a failures with detailed error messages. ## How to build and run Start a web server on localhost:8080 then execute: make ./client ## Client vs HostClient Internally the Client creates a dedicated HostClient for each domain/IP address and cleans unused after period of time. So if you have a single heavily loaded API endpoint it's better to use HostClient. See an example in the [examples/host_client](../host_client/) --- ## File: examples/README.md # Code examples * [HelloWorld server](helloworldserver) * [Static file server](fileserver) --- ## File: prefork/README.md # Prefork Server prefork implementation. Preforks master process between several child processes increases performance, because Go doesn't have to share and manage memory between cores. **WARNING: using prefork prevents the use of any global state!. Things like in-memory caches won't work.** - How it works: ```go import ( "github.com/valyala/fasthttp" "github.com/valyala/fasthttp/prefork" ) server := &fasthttp.Server{ // Your configuration } // Wraps the server with prefork preforkServer := prefork.New(server) if err := preforkServer.ListenAndServe(":8080"); err != nil { panic(err) } ``` ## Benchmarks Environment: - Machine: MacBook Pro 13-inch, 2017 - OS: MacOS 10.15.3 - Go: go1.13.6 darwin/amd64 Handler code: ```go func requestHandler(ctx *fasthttp.RequestCtx) { // Simulates some hard work time.Sleep(100 * time.Millisecond) } ``` Test command: ```bash $ wrk -H 'Host: localhost' -H 'Accept: text/plain,text/html;q=0.9,application/xhtml+xml;q=0.9,application/xml;q=0.8,*/*;q=0.7' -H 'Connection: keep-alive' --latency -d 15 -c 512 --timeout 8 -t 4 http://localhost:8080 ``` Results: - prefork ```bash Running 15s test @ http://localhost:8080 4 threads and 512 connections Thread Stats Avg Stdev Max +/- Stdev Latency 4.75ms 4.27ms 126.24ms 97.45% Req/Sec 26.46k 4.16k 71.18k 88.72% Latency Distribution 50% 4.55ms 75% 4.82ms 90% 5.46ms 99% 15.49ms 1581916 requests in 15.09s, 140.30MB read Socket errors: connect 0, read 318, write 0, timeout 0 Requests/sec: 104861.58 Transfer/sec: 9.30MB ``` - **non**-prefork ```bash Running 15s test @ http://localhost:8080 4 threads and 512 connections Thread Stats Avg Stdev Max +/- Stdev Latency 6.42ms 11.83ms 177.19ms 96.42% Req/Sec 24.96k 5.83k 56.83k 82.93% Latency Distribution 50% 4.53ms 75% 4.93ms 90% 6.94ms 99% 74.54ms 1472441 requests in 15.09s, 130.59MB read Socket errors: connect 0, read 265, write 0, timeout 0 Requests/sec: 97553.34 Transfer/sec: 8.65MB ``` --- ## File: tcplisten/README.md # TCPListen Package tcplisten provides customizable TCP net.Listener with various performance-related options: * SO_REUSEPORT. This option allows linear scaling server performance on multi-CPU servers. See https://www.nginx.com/blog/socket-sharding-nginx-release-1-9-1/ for details. * TCP_DEFER_ACCEPT. This option expects the server reads from the accepted connection before writing to them. * TCP_FASTOPEN. See https://lwn.net/Articles/508865/ for details. The package is derived from [go_reuseport](https://github.com/valyala/tcplisten). ## 2. Official Technical Reference & Guides (valyala/docs) # Prometheus Documentation This repository contains both the content and the static-site generator code for the Prometheus documentation site. ## Contributing Changes See [`CONTRIBUTING.md`](CONTRIBUTING.md) for general instructions for new Prometheus contributors. The main documentation contents of this website are located in the [`content/docs`](content/docs) directory. Documentation concerning the Prometheus server is [maintained in the Prometheus server repository](https://github.com/prometheus/prometheus/tree/master/docs) and cloned into the website at build time. As a guideline, please keep the documentation generally applicable and avoid use-case-specific changes. ## Prerequisites You need to have a working Ruby environment set up (including [bundler](https://bundler.io/)) and then install the necessary gems: ```bash cd docs make bundle ``` ## Building To generate the static site, run: ```bash make build ``` The resulting static site will be stored in the `output` directory. Optionally, you can use an API token to avoid rate limits on the API. You can get an API token from https://github.com/settings/tokens/new. ```bash export GITHUB_AUTHENTICATION='-u user:token' ``` ## Development Server To run a local server that displays the generated site, run: ```bash # Rebuild the site whenever relevant files change: make guard # Start the local development server in a separate shell: make serve ``` You should now be able to view the generated site at [http://localhost:3000/](http://localhost:3000). ## License Apache License 2.0, see [LICENSE](LICENSE).