fast

package module
v0.0.0-...-f14210d Latest Latest
Warning

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

 Go to latest Published: Jul 26, 2026 License: BSD-3-Clause Imports: 33 Imported by: 0

README

aoni/fast

The Silicon-Paced, Zero-Alloc Titanium Engine for Go Networking

Go Reference License RPS

"Zero compromise. Strict memory geometry. Raw silicon speed."

English • Русский

The Manifesto: Shattering Corporate Myths

For years, corporate frameworks preached a lazy, incompetent dogma:

"If you want a clean, fluent interface with chainable calls, you MUST pay a tax of 50 microseconds and 80 heap allocations per request. If you want high performance, your code MUST be an unreadable mess with no features."

That is a lie. It is the excuse of frameworks that lack the mathematical discipline to design strict memory geometry.

aoni/fast was built to prove the exact opposite. It takes fasthttp, integrates native HTTP/2 and HTTP/3 framing directly over uTLS, and wraps it in the same high-level option/mod interface used across aoni.

Using standard HTTP wrappers is like hiring fifty drunk movers to carry a single paper envelope across town - throwing mud everywhere and demanding a million dollars for gas. aoni/fast is a high-pressure titanium pneumatic tube: you load bytes into one end, pull the lever, and they shoot straight into the socket at the speed of sound without leaving a single speck of dust on the workshop floor.

go get github.com/lemon4ksan/aoni

Feature Matrix

Feature / Capability Standard Go net/http Resty / Wrappers aoni (Base) aoni/fast
Engine Core net/http net/http net/http fasthttp + Native H2/H3
Execution Latency ~50 µs ~50 µs ~60 µs 5.9 µs (8.5x faster)
Zero-Alloc Object Pooling ✗ ✗ ✗ ✓ (sync.Pool Request/Response)
Native HTTP/2 (h2engine) x/net/http2 x/net/http2 x/net/http2 ✓ (Zero-Alloc Byte Engine)
Native HTTP/3 (h3engine) quic-go quic-go quic-go ✓ (QPACK Byte Engine)
uTLS & Fingerprinting ✗ ✗ ✓ ✓ (uTLS over fastDialer)
Custom Header Order (JA4H) ✗ ✗ ✓ ✓ (Zero-Cost Wire Ordering)
http.Client Compatibility Bridge Native ✗ Native ✓ (fast.NewStdClient)

The Subterranean Monorail: fast.NewStdClient & The Bridge

They shouted from every corner: "fasthttp is incompatible with standard Go interfaces! You can't use it in normal HTTP clients!"

We buried a superconducting magnetic monorail right underneath their muddy dirt road:

[ Legacy Code / Third-party SDK ]
               │
               ▼
     *http.Client / RoundTripper
               │
               ▼
    [ aoni/fast.Bridge ]  <-- Seamless Adapter
               │
               ▼
 [ fasthttp + uTLS + Native H2/H3 ] --> [ Direct Socket Write ]

Your legacy SDKs enter fast.NewStdClient, thinking they are slowly crawling through puddles on an old wooden http.RoundTripper cart. Under the hood, aoni.fast engages a native turbojet engine that carries them at 300 mph. They won't even understand why their CPU stopped overheating.

Quick Start

1. Ultra-High Performance Native fast.Client
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/lemon4ksan/aoni"
	"github.com/lemon4ksan/aoni/fast"
	"github.com/lemon4ksan/aoni/fluent"
	"github.com/lemon4ksan/aoni/mod"
	"github.com/lemon4ksan/aoni/option"
)

type UserProfile struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func main() {
	ctx := context.Background()

	// Instantiate the fast engine with browser TLS fingerprints
	client := fast.NewClient(
		option.WithBaseURL("https://api.example.com"),
		option.WithTimeout(10*time.Second),
		option.WithTLSFingerprint(aoni.BrowserChrome),
	)

	// High-level type-safe execution over zero-alloc fasthttp + uTLS
	resp, err := client.Request(ctx, "GET", "/users/123",
		mod.WithHeader("X-High-Load", "true"),
	)
	if err != nil {
		panic(err)
	}
	defer resp.Close() // Returns objects back to sync.Pool

	fmt.Printf("Status: %d, Body: %s\n", resp.StatusCode(), resp.BodyBytes())
}
2. The Monorail Bridge: Turbocharge Standard *http.Client

Seamlessly adapt aoni/fast into any third-party Go library (Resty, AWS SDK, custom REST clients) expecting a standard *http.Client:

package main

import (
	"net/http"

	"github.com/lemon4ksan/aoni"
	"github.com/lemon4ksan/aoni/fast"
	"github.com/lemon4ksan/aoni/option"
)

func main() {
	// Create fast engine
	fastClient := fast.NewClient(
		option.WithTLSFingerprint(aoni.BrowserChrome),
		option.WithProxyString("socks5://127.0.0.1:1080"),
	)

	// Adapt into standard net/http.Client
	stdClient := fast.NewStdClient(fastClient)

	// Inject into legacy code expecting *http.Client
	resp, err := stdClient.Get("https://api.target.com/data")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

License

Licensed under the BSD 3-Clause License. See LICENSE for details.

Pure physics. Unyielding performance. Take back your CPU.

Documentation

Overview

Package fast provides high-performance fasthttp engine adapters for aoni.Request and aoni.Response.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNilURL indicates an attempt to dispatch an HTTP request without a destination address.
	ErrNilURL = errors.New("fast: request URL is nil")

	// ErrTargetURLEmpty is returned when no target URL is provided for request execution.
	ErrTargetURLEmpty = errors.New("fast: target URL is empty")

	// ErrUTLSHandshakeFailed is returned when uTLS negotiation fails over a fasthttp socket.
	ErrUTLSHandshakeFailed = errors.New("fast: uTLS handshake failed")

	// ErrProxyConnectionFailed is returned when establishing an outbound proxy tunnel fails.
	ErrProxyConnectionFailed = errors.New("fast: proxy connection failed")

	// ErrMaxRedirectsExceeded is returned when the request halts because the maximum redirect threshold was reached.
	ErrMaxRedirectsExceeded = errors.New("fast: maximum redirects limit exceeded")

	// ErrCannotRewind is returned when a stream request body cannot be rewound for a 307/308 redirect.
	ErrCannotRewind = errors.New("fast: cannot rewind request body stream for redirect")

	// ErrHedgingFailed is returned when all hedged request attempts fail to execute.
	ErrHedgingFailed = errors.New("fast: all hedged request attempts failed")

	// ErrNothingWritten indicates a network error occurred before any request bytes reached the socket.
	ErrNothingWritten = errors.New("fast: connection closed before any request bytes were written")
)

Functions

func NewStdClient 

func NewStdClient(c *Client) *http.Client

NewStdClient adapts a fast Client into a standard *http.Client.

Bridges fasthttp with standard library HTTP abstractions.

Types

type Client 

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

Client executes ultra-high-performance HTTP requests over fasthttp, seamlessly multiplexing native H1 (fasthttp), native H2 (h2engine), and native H3 (h3engine).

func NewClient 

func NewClient(opts ...aoni.ClientOption) *Client

NewClient creates a new multiprotocol Client configured with fasthttp, uTLS, native HTTP/2 framing, and native HTTP/3 QUIC support.

func (*Client) Config 

func (c *Client) Config() aoni.Config

Config returns a copy of active client configurations.

func (*Client) DialContext 

func (c *Client) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext establishes a raw L4 connection applying active proxy, DNS, and anti-DPI configurations.

func (*Client) DialPlainForWS 

func (c *Client) DialPlainForWS(ctx context.Context, addr string) (net.Conn, error)

DialPlainForWS satisfies aoni.WSDialer by establishing a plain TCP socket for WebSocket upgrades.

func (*Client) DialTLSContext 

func (c *Client) DialTLSContext(ctx context.Context, network, addr string) (net.Conn, error)

DialTLSContext establishes an encrypted TLS socket connection using uTLS ClientHello specifications.

func (*Client) DialTLSForWS 

func (c *Client) DialTLSForWS(ctx context.Context, addr string) (net.Conn, error)

DialTLSForWS satisfies aoni.WSDialer by establishing an encrypted TLS connection for WebSocket upgrades.

func (*Client) Do 

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

Do executes a prepared aoni.Request contract, routing through the target native protocol engine (H1, H2, or H3).

func (*Client) Engine 

func (c *Client) Engine() *fasthttp.Client

Engine returns the underlying *fasthttp.Client engine instance.

func (*Client) Request 

func (c *Client) Request(
	ctx context.Context,
	method, path string,
	mods ...aoni.RequestModifier,
) (aoni.Response, error)

Request executes an HTTP request across HTTP/1.1, native HTTP/2, or native HTTP/3. Handles redirects, cookies, proxy failover, hedging, response validation, WAF challenges, and telemetry.

Postconditions:

func (*Client) With 

func (c *Client) With(opts ...aoni.ClientOption) *Client

With produces a deep-copied Client with the provided functional options applied.

type HTTPDoer 

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer executes an HTTP request transaction.

type PooledResponse 

type PooledResponse struct {
	*Response
	// contains filtered or unexported fields
}

PooledResponse wraps a fasthttp response and returns instances back to sync.Pool upon Close.

func NewPooledResponse 

func NewPooledResponse(fastReq *fasthttp.Request, fastResp *fasthttp.Response) *PooledResponse

NewPooledResponse acquires a pooled PooledResponse adapter wrapping fastReq and fastResp. The caller is responsible for releasing the request and response objects.

func (*PooledResponse) Close 

func (r *PooledResponse) Close() error

Close releases underlying fasthttp objects and returns PooledResponse to memory pool.

type Request 

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

Request adapts a high-performance *fasthttp.Request to the unified aoni.Request contract.

func NewRequest 

func NewRequest(req *fasthttp.Request) *Request

NewRequest acquires a pooled Request adapter wrapping req. The caller is responsible for releasing the request object.

func (*Request) AddHeader 

func (f *Request) AddHeader(key, value string)

AddHeader appends value to header key.

func (*Request) AddHeaderBytes 

func (f *Request) AddHeaderBytes(key, value []byte)

AddHeaderBytes appends value to header key using byte slices.

func (*Request) AddQueryParam 

func (f *Request) AddQueryParam(key, value string)

AddQueryParam appends a key-value query parameter to the URI.

func (*Request) AddQueryParamBytes 

func (f *Request) AddQueryParamBytes(key, value []byte)

AddQueryParamBytes appends a key-value query parameter using byte slices.

func (*Request) BodyBytes 

func (f *Request) BodyBytes() []byte

BodyBytes yields direct access to internal fasthttp request body byte slice.

func (*Request) BodyStream 

func (f *Request) BodyStream() io.Reader

BodyStream yields an io.Reader for the request body.

func (*Request) Context 

func (f *Request) Context() context.Context

Context yields the execution context, defaulting to context.Background.

func (*Request) DelHeader 

func (f *Request) DelHeader(key string)

DelHeader removes header key.

func (*Request) DelHeaderBytes 

func (f *Request) DelHeaderBytes(key []byte)

DelHeaderBytes removes header key using a byte slice.

func (*Request) EngineRequest 

func (f *Request) EngineRequest() any

EngineRequest yields the underlying *fasthttp.Request cast to any.

func (*Request) FastHTTPRequest 

func (f *Request) FastHTTPRequest() *fasthttp.Request

FastHTTPRequest yields the underlying *fasthttp.Request instance.

func (*Request) GetBody 

func (f *Request) GetBody() (io.ReadCloser, error)

GetBody generates a fresh ReadCloser for replaying the request payload stream.

func (*Request) HTTPRequest 

func (f *Request) HTTPRequest() *http.Request

HTTPRequest yields nil for fasthttp request adapters.

func (*Request) Header 

func (f *Request) Header(key string) string

Header yields the header value for key as a string.

func (*Request) HeaderBytes 

func (f *Request) HeaderBytes(key []byte) []byte

HeaderBytes yields direct access to internal header buffer bytes.

func (*Request) Method 

func (f *Request) Method() string

Method yields the HTTP method string.

func (*Request) Path 

func (f *Request) Path() string

Path yields the path component of the URL.

func (*Request) RawQuery 

func (f *Request) RawQuery() string

RawQuery yields the raw query string.

func (*Request) Release 

func (f *Request) Release()

Release returns the Request adapter back to the pool.

func (*Request) ResetHeaders 

func (f *Request) ResetHeaders()

ResetHeaders removes all headers from the request.

func (*Request) SetBodyBytes 

func (f *Request) SetBodyBytes(body []byte)

SetBodyBytes sets request body to a raw byte slice.

func (*Request) SetBodyStream 

func (f *Request) SetBodyStream(r io.Reader, contentLength int64)

SetBodyStream assigns a streaming reader as request body and sets up rewind capabilities if supported.

func (*Request) SetContext 

func (f *Request) SetContext(ctx context.Context)

SetContext assigns the execution context to the request adapter.

func (*Request) SetGetBody 

func (f *Request) SetGetBody(fn func() (io.ReadCloser, error))

SetGetBody assigns a custom generator for rewinding body streams during retries and 307/308 redirects.

func (*Request) SetHeader 

func (f *Request) SetHeader(key, value string)

SetHeader sets header key to value.

func (*Request) SetHeaderBytes 

func (f *Request) SetHeaderBytes(key, value []byte)

SetHeaderBytes sets header key to value using byte slices.

func (*Request) SetMethod 

func (f *Request) SetMethod(method string)

SetMethod assigns the HTTP method string.

func (*Request) SetMethodBytes 

func (f *Request) SetMethodBytes(method []byte)

SetMethodBytes assigns the HTTP method from a byte slice without allocations.

func (*Request) SetPath 

func (f *Request) SetPath(path string)

SetPath assigns the path component of the URL.

func (*Request) SetQueryParam 

func (f *Request) SetQueryParam(key, value string)

SetQueryParam sets or replaces a query parameter in the URI.

func (*Request) SetQueryParamBytes 

func (f *Request) SetQueryParamBytes(key, value []byte)

SetQueryParamBytes sets or replaces a query parameter using byte slices.

func (*Request) SetRawQuery 

func (f *Request) SetRawQuery(query string)

SetRawQuery assigns the raw query string.

func (*Request) SetRawQueryBytes 

func (f *Request) SetRawQueryBytes(query []byte)

SetRawQueryBytes assigns the raw query string from a byte slice.

func (*Request) SetURIBytes 

func (f *Request) SetURIBytes(uri []byte)

SetURIBytes assigns the destination address from a byte slice.

func (*Request) SetURL 

func (f *Request) SetURL(urlStr string)

SetURL assigns the destination address string.

func (*Request) URL 

func (f *Request) URL() string

URL yields the full target URL string.

type Response 

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

Response adapts a high-performance *fasthttp.Response to the unified aoni.Response contract.

func NewResponse 

func NewResponse(resp *fasthttp.Response) *Response

NewResponse wraps resp into a unified aoni.Response adapter. The caller is responsible for releasing the response object.

func (*Response) BodyBytes 

func (f *Response) BodyBytes() []byte

BodyBytes returns an independent, memory-safe copy of the response body bytes.

Postconditions:

  • The returned slice is safe to retain or mutate beyond response pool recycling.

func (*Response) BodyStream 

func (f *Response) BodyStream() io.ReadCloser

BodyStream yields an io.ReadCloser wrapping the response body stream or bytes.

func (*Response) Close 

func (f *Response) Close() error

Close releases resources bound to the response wrapper and slurps unread stream bytes to preserve sockets.

func (*Response) EngineResponse 

func (f *Response) EngineResponse() any

EngineResponse yields the underlying *fasthttp.Response cast to any.

func (*Response) FastHTTPResponse 

func (f *Response) FastHTTPResponse() *fasthttp.Response

FastHTTPResponse yields the underlying *fasthttp.Response instance.

func (*Response) HTTPResponse 

func (f *Response) HTTPResponse() *http.Response

HTTPResponse yields nil for fasthttp response adapters.

func (*Response) Header 

func (f *Response) Header(key string) string

Header yields single value for header key as a string.

func (*Response) HeaderBytes 

func (f *Response) HeaderBytes(key []byte) []byte

HeaderBytes yields direct access to header value byte slice inside internal buffers.

func (*Response) Headers 

func (f *Response) Headers() map[string][]string

Headers yields all response headers as a key-value map.

func (*Response) Release 

func (f *Response) Release()

Release returns the Response adapter back to memory pool.

func (*Response) SetTrailers 

func (f *Response) SetTrailers(trailers map[string][]string)

SetTrailers registers HTTP trailers captured during frame execution.

func (*Response) SetUncompressed 

func (f *Response) SetUncompressed(v bool)

SetUncompressed records whether the response payload was transparently decompressed by the client.

func (*Response) Status 

func (f *Response) Status() string

Status yields the response status text.

func (*Response) StatusBytes 

func (f *Response) StatusBytes() []byte

StatusBytes yields status text as a byte slice.

func (*Response) StatusCode 

func (f *Response) StatusCode() int

StatusCode yields the HTTP status code.

func (*Response) Trailers 

func (f *Response) Trailers() map[string][]string

Trailers returns HTTP trailers parsed after the body stream.

func (*Response) Uncompressed 

func (f *Response) Uncompressed() bool

Uncompressed reports whether the response body was transparently decompressed by the client.

func (*Response) UnsafeBodyBytes 

func (f *Response) UnsafeBodyBytes() []byte

UnsafeBodyBytes provides zero-allocation direct access to internal response buffers.

Warning:

  • Points directly to volatile internal buffers managed by sync.Pool.
  • MUST NOT be referenced, mutated, or retained after closing or recycling the response.

type Transport 

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

Transport adapts a fast Client to satisfy the standard http.RoundTripper contract.

func NewTransport 

func NewTransport(c *Client) *Transport

NewTransport constructs an http.RoundTripper adapter backed by a fast Client.

func (*Transport) RoundTrip 

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip satisfies http.RoundTripper, executing standard requests over fasthttp.

Postconditions:

  • Request bodies are streamed directly without buffering full payloads in RAM.

Source Files

View all Source files

Directories

Path Synopsis
Package h2engine provides an HTTP/2 client multiplexer.
 Package h2engine provides an HTTP/2 client multiplexer.
Package h3engine provides HTTP/3 client functionality using fasthttp.
 Package h3engine provides HTTP/3 client functionality using fasthttp.

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.