v2fasthttp

package module
v0.0.0-...-7a45fd3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 29, 2025 License: MIT Imports: 17 Imported by: 0

README

v2fasthttp

v2fasthttp is a high-performance HTTP client toolkit for Go built directly on top of github.com/valyala/fasthttp.

The focus is:

  • Fast HTTP/1.1 requests using the fasthttp client.
  • Simple, fasthttp-style API: Request, Response, Do, Get, Post, etc.
  • Strong proxy support (HTTP and SOCKS5) with helpers.
  • Multi-client pools for very high QPS workloads.
  • Optional HTTP/2 and HTTP/3 clients built on top of net/http and quic-go, while keeping the fasthttp-style Request / Response API.

Installation

go get github.com/seiffpes/v2fasthttp

Core types

Package v2fasthttp exposes the main fasthttp types:

  • type Client struct{ fasthttp.Client /* + HTTP2/3 client */ }
  • type Request = fasthttp.Request
  • type Response = fasthttp.Response
  • type RequestCtx = fasthttp.RequestCtx
  • type RequestHandler = fasthttp.RequestHandler

There is also a global default client used by package-level helpers.

Quick start

Simple GET using the default client:

package main

import (
	"log"

	v2 "github.com/seiffpes/v2fasthttp"
)

func main() {
	var req v2.Request
	var resp v2.Response

	req.SetRequestURI("https://httpbin.org/get")
	req.Header.SetMethod("GET")

	if err := v2.Do(&req, &resp); err != nil {
		log.Fatal(err)
	}

	log.Printf("status=%d body=%s", resp.StatusCode(), resp.Body())
}

Using the high-level helpers:

body, status, err := v2.GetBytesURL("https://httpbin.org/get")
if err != nil {
	log.Fatal(err)
}
log.Printf("status=%d body=%s", status, string(body))

High-performance client

You can fully control the underlying client via ClientOptions:

opt := v2.ClientOptions{
	HTTPVersion:                  v2.HTTP1, // or v2.HTTP2 / v2.HTTP3
	MaxConnsPerHost:               100000,
	MaxIdleConnDuration:           100 * time.Millisecond,
	ReadBufferSize:                64 * 1024,
	WriteBufferSize:               64 * 1024,
	MaxIdemponentCallAttempts:     1,
	NoDefaultUserAgentHeader:      true,
	DisableHeaderNamesNormalizing: true,
	DisablePathNormalizing:        true,
	MaxConnWaitTimeout:            time.Second,
	TLSConfig: &tls.Config{
		InsecureSkipVerify: true,
	},
}

c := v2.NewClientWithOptions(opt)

For a ready-to-use aggressive configuration there is:

c := v2.NewHighPerfClient("")

This is tuned for very high QPS and is what the benchmark example uses.

HTTP/2 and HTTP/3

ClientOptions has an HTTPVersion field that lets you switch the transport behind the same fasthttp-style API:

// HTTP/2 client with an HTTP proxy
opt := v2.ClientOptions{
	HTTPVersion: v2.HTTP2,
	ProxyHTTP:   "user:pass@127.0.0.1:8080",
	TLSConfig:   &tls.Config{InsecureSkipVerify: true},
}

c := v2.NewClientWithOptions(opt)

var req v2.Request
var resp v2.Response

req.SetRequestURI("https://example.com/")
req.Header.SetMethod("GET")

if err := c.Do(&req, &resp); err != nil {
	log.Fatal(err)
}

HTTP/1.1 (HTTP1) continues to use the native fasthttp.Client. HTTP/2 uses a tuned net/http.Client under the hood, and HTTP/3 uses quic-go's HTTP/3 transport. Proxy helpers (SetProxy, SetProxyHTTP, SetSOCKS5Proxy, SetProxyFromEnvironment) work with HTTP/1.1 and HTTP/2.

If you set HTTPVersion: HTTP3 together with ProxyHTTP or SOCKS5Proxy, the client will automatically fall back to HTTP2, since HTTP/3 over HTTP or SOCKS5 proxies is not supported in this package.

Proxy support

Per-client proxy

On any *Client you can set proxies:

// HTTP proxy, with or without auth.
c.SetProxyHTTP("127.0.0.1:8080")
c.SetProxyHTTP("user:pass@127.0.0.1:8080")

// SOCKS5 proxy.
c.SetSOCKS5Proxy("socks5://127.0.0.1:9050")

// Auto-detect (socks5:// → SOCKS5, otherwise HTTP).
c.SetProxy("user:pass@127.0.0.1:8080")
c.SetProxy("socks5://127.0.0.1:9050")

// Use HTTP(S)_PROXY / NO_PROXY from the environment.
c.SetProxyFromEnvironment()
c.SetProxyFromEnvironmentTimeout(2 * time.Second)

You can also configure proxies through ClientOptions (ProxyHTTP, SOCKS5Proxy) and build the client with NewClientWithOptions.

Multi-client pools and proxy lists

For high concurrency and proxy lists there is a small pool type:

pool := v2.NewHighPerfClientPool(200, "user:pass@127.0.0.1:8080")

var req v2.Request
var resp v2.Response

req.SetRequestURI("https://httpbin.org/get")
req.Header.SetMethod("GET")

if err := pool.Do(&req, &resp); err != nil {
	log.Fatal(err)
}

To use multiple proxies:

proxies := []string{
	"user:pass@127.0.0.1:8080",
	"127.0.0.1:8081",
	"socks5://127.0.0.1:9050",
}

pool := v2.NewProxyClientPool(proxies, 4)

Or from a string list (newline / comma / space separated):

list := "user:pass@127.0.0.1:8080\n127.0.0.1:8081\nsocks5://127.0.0.1:9050"
pool := v2.NewProxyClientPoolFromString(list, 4)

The pool does round-robin over all clients and proxies.

Byte and JSON helpers

Common helpers on *Client:

  • DoBytes, DoBytesTimeout
  • GetBytes, GetBytesTimeout
  • PostBytes, PostBytesTimeout
  • PostJSON, PostJSONTimeout
  • GetString, GetStringTimeout
  • PostString, PostStringTimeout

And global helpers using the default client:

  • GetBytesURL, GetBytesTimeoutURL
  • PostBytesURL, PostBytesTimeoutURL
  • PostJSONURL, PostJSONTimeoutURL
  • GetStringURL, GetStringTimeoutURL
  • PostStringURL, PostStringTimeoutURL

These keep the fasthttp style but make basic HTTP requests quick to write.

Benchmark example

examples/bench is a small benchmark tool that can hit a URL with many concurrent clients (optionally through a proxy) and print the achieved requests per second.

From the project root:

go run ./examples/bench -url https://httpbin.org/get -total 200000 -concurrency 200

# With an HTTP proxy
go run ./examples/bench -url https://httpbin.org/get -total 200000 -concurrency 200 -proxy user:pass@127.0.0.1:8080
Micro-benchmarks (v2fasthttp vs net/http vs fasthttp)

There is also a small set of micro-benchmarks in bench_test.go that compare:

  • v2fasthttp default client (Do)
  • v2fasthttp high-performance client
  • v2fasthttp GetBytes
  • net/http.Client
  • fasthttp.Client

They run against an in-memory httptest.Server (no external network).

From the project root:

go test -run=^$ -bench=. ./...

This will print benchmark lines for each client (with ns/op, allocations, etc.) so you can compare the relative performance on your machine.

License

Licensed under the MIT License.
Copyright (c) 2025 fpes.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Do 

func Do(req *Request, resp *Response) error

func DoTimeout 

func DoTimeout(req *Request, resp *Response, timeout time.Duration) error

func Get 

func Get(dst []byte, url string) (statusCode int, body []byte, err error)

func GetBytesTimeoutURL 

func GetBytesTimeoutURL(url string, timeout time.Duration) ([]byte, int, error)

func GetBytesURL 

func GetBytesURL(url string) ([]byte, int, error)

func GetStringTimeoutURL 

func GetStringTimeoutURL(url string, timeout time.Duration) (string, int, error)

func GetStringURL 

func GetStringURL(url string) (string, int, error)

func GetTimeout 

func GetTimeout(dst []byte, url string, timeout time.Duration) (statusCode int, body []byte, err error)

func Post 

func Post(dst []byte, url string, postArgs *fasthttp.Args) (statusCode int, body []byte, err error)

func PostBytesTimeoutURL 

func PostBytesTimeoutURL(url string, body []byte, timeout time.Duration) ([]byte, int, error)

func PostBytesURL 

func PostBytesURL(url string, body []byte) ([]byte, int, error)

func PostJSONTimeoutURL 

func PostJSONTimeoutURL(url string, v any, timeout time.Duration) ([]byte, int, error)

func PostJSONURL 

func PostJSONURL(url string, v any) ([]byte, int, error)

func PostStringTimeoutURL 

func PostStringTimeoutURL(url string, body []byte, timeout time.Duration) (string, int, error)

func PostStringURL 

func PostStringURL(url string, body []byte) (string, int, error)

Types

type Client 

type Client struct {
	fasthttp.Client
	// contains filtered or unexported fields
}

func NewClientWithOptions 

func NewClientWithOptions(opt ClientOptions) *Client

func NewHighPerfClient 

func NewHighPerfClient(proxy string) *Client

func (*Client) Do 

func (c *Client) Do(req *Request, resp *Response) error

func (*Client) DoBytes 

func (c *Client) DoBytes(method, url string, body []byte) ([]byte, int, error)

func (*Client) DoBytesTimeout 

func (c *Client) DoBytesTimeout(method, url string, body []byte, timeout time.Duration) ([]byte, int, error)

func (*Client) DoTimeout 

func (c *Client) DoTimeout(req *Request, resp *Response, timeout time.Duration) error

func (*Client) GetBytes 

func (c *Client) GetBytes(url string) ([]byte, int, error)

func (*Client) GetBytesTimeout 

func (c *Client) GetBytesTimeout(url string, timeout time.Duration) ([]byte, int, error)

func (*Client) GetString 

func (c *Client) GetString(url string) (string, int, error)

func (*Client) GetStringTimeout 

func (c *Client) GetStringTimeout(url string, timeout time.Duration) (string, int, error)

func (*Client) PostBytes 

func (c *Client) PostBytes(url string, body []byte) ([]byte, int, error)

func (*Client) PostBytesTimeout 

func (c *Client) PostBytesTimeout(url string, body []byte, timeout time.Duration) ([]byte, int, error)

func (*Client) PostJSON 

func (c *Client) PostJSON(url string, v any) ([]byte, int, error)

func (*Client) PostJSONTimeout 

func (c *Client) PostJSONTimeout(url string, v any, timeout time.Duration) ([]byte, int, error)

func (*Client) PostString 

func (c *Client) PostString(url string, body []byte) (string, int, error)

func (*Client) PostStringTimeout 

func (c *Client) PostStringTimeout(url string, body []byte, timeout time.Duration) (string, int, error)

func (*Client) SetProxy 

func (c *Client) SetProxy(proxy string)

func (*Client) SetProxyFromEnvironment 

func (c *Client) SetProxyFromEnvironment()

func (*Client) SetProxyFromEnvironmentTimeout 

func (c *Client) SetProxyFromEnvironmentTimeout(timeout time.Duration)

func (*Client) SetProxyHTTP 

func (c *Client) SetProxyHTTP(proxy string)

func (*Client) SetSOCKS5Proxy 

func (c *Client) SetSOCKS5Proxy(proxyAddr string)

type ClientOptions 

type ClientOptions struct {
	HTTPVersion                   HTTPVersion
	MaxConnsPerHost               int
	MaxIdleConnDuration           time.Duration
	MaxConnDuration               time.Duration
	MaxIdemponentCallAttempts     int
	ReadBufferSize                int
	WriteBufferSize               int
	ReadTimeout                   time.Duration
	WriteTimeout                  time.Duration
	MaxResponseBodySize           int
	NoDefaultUserAgentHeader      bool
	DisableHeaderNamesNormalizing bool
	DisablePathNormalizing        bool
	MaxConnWaitTimeout            time.Duration
	TLSConfig                     *tls.Config
	ProxyHTTP                     string
	SOCKS5Proxy                   string
}

type ClientPool 

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

func NewClientPool 

func NewClientPool(size int, factory func() *Client) *ClientPool

func NewHighPerfClientPool 

func NewHighPerfClientPool(size int, proxy string) *ClientPool

func NewProxyClientPool 

func NewProxyClientPool(proxies []string, perProxy int) *ClientPool

func NewProxyClientPoolFromString 

func NewProxyClientPoolFromString(list string, perProxy int) *ClientPool

func (*ClientPool) Do 

func (p *ClientPool) Do(req *Request, resp *Response) error

func (*ClientPool) Next 

func (p *ClientPool) Next() *Client

type HTTPVersion 

type HTTPVersion int
const (
	HTTP1 HTTPVersion = iota + 1
	HTTP2
	HTTP3
)

type Request 

type Request = fasthttp.Request

type RequestCtx 

type RequestCtx = fasthttp.RequestCtx

type RequestHandler 

type RequestHandler = fasthttp.RequestHandler

type Response 

type Response = fasthttp.Response

Source Files

View all Source files

Directories

Path Synopsis
examples
all_features command
bench command
helpers command
http1_basic command
http1_proxy command
http2_proxy command
http3_basic command
pool_proxies command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.