surf

package module
v1.0.148-mod.1 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2025 License: MIT Imports: 55 Imported by: 0

README

Surf - Advanced HTTP Client for Go

Go Reference Go Report Card Coverage Status Go Ask DeepWiki

Surf is a powerful, feature-rich HTTP client library for Go that makes working with HTTP requests intuitive and enjoyable. With advanced features like browser impersonation, JA3/JA4 fingerprinting, and comprehensive middleware support, Surf provides everything you need for modern web interactions.

✨ Key Features

🎭 Browser Impersonation

  • Chrome & Firefox Support: Accurately mimic Chrome v142 and Firefox v146 browser fingerprints
  • Platform Diversity: Impersonate Windows, macOS, Linux, Android, and iOS devices
  • TLS Fingerprinting: Full JA3/JA4 fingerprint customization for enhanced privacy
  • Automatic Headers: Proper header ordering and browser-specific values
  • WebKit Form Boundaries: Accurate multipart form boundary generation matching real browsers

🔒 Advanced TLS & Security

  • Custom JA3/JA4: Configure precise TLS fingerprints with HelloID and HelloSpec
  • HTTP/3 Support: Full HTTP/3 over QUIC with complete browser-specific QUIC fingerprinting
  • JA4QUIC Fingerprinting: Complete QUIC transport parameter fingerprinting for Chrome and Firefox
  • HTTP/2 & HTTP/3: Full HTTP/2 support with customizable settings (SETTINGS frame, window size, priority)
  • Ordered Headers: Browser-accurate header ordering for perfect fingerprint evasion
  • Certificate Pinning: Custom TLS certificate validation
  • DNS-over-TLS: Enhanced privacy with DoT support
  • Proxy Support: HTTP, HTTPS, and SOCKS5 proxy configurations with UDP support for HTTP/3

🚀 Performance & Reliability

  • Connection Pooling: Efficient connection reuse with singleton pattern
  • Automatic Retries: Configurable retry logic with custom status codes
  • Response Caching: Built-in body caching for repeated access
  • Streaming Support: Efficient handling of large responses and SSE
  • Compression: Automatic decompression of gzip, deflate, brotli, and zstd responses
  • Keep-Alive: Persistent connections with configurable parameters

🛠️ Developer Experience

  • Standard Library Compatible: Convert to net/http.Client for third-party library integration
  • Fluent API: Chainable methods for elegant code
  • Middleware System: Extensible request/response/client middleware with priority support
  • Type Safety: Strong typing with generics support via enetx/g
  • Debug Mode: Comprehensive request/response debugging
  • Error Handling: Result type pattern for better error management
  • Context Support: Full context.Context integration for cancellation and timeouts

📦 Installation

go get -u github.com/adityaphra/surf

Required Go version: 1.24+

🔄 Standard Library Compatibility

Surf provides seamless integration with Go's standard net/http package, allowing you to use Surf's advanced features with any library that expects a standard *http.Client.

// Create a Surf client with advanced features
surfClient := surf.NewClient().
    Builder().
    Impersonate().Chrome().
    Session().
    Build()

// Convert to standard net/http.Client
stdClient := surfClient.Std()

// Use with any third-party library
// Example: AWS SDK, Google APIs, OpenAI client, etc.
resp, err := stdClient.Get("https://api.example.com")

Preserved Features When Using Std():

  • ✅ JA3/TLS fingerprinting
  • ✅ HTTP/2 settings
  • ✅ HTTP/3 & QUIC fingerprinting
  • ✅ Browser impersonation headers
  • ✅ Ordered headers
  • ✅ Cookies and sessions
  • ✅ Proxy configuration
  • ✅ Custom headers and User-Agent
  • ✅ Timeout settings
  • ✅ Redirect policies
  • ✅ Request/Response middleware

Limitations with Std():

  • ❌ Retry logic (implement at application level)
  • ❌ Response body caching
  • ❌ Remote address tracking
  • ❌ Request timing information

🚀 Quick Start

Basic GET Request

package main

import (
    "fmt"
    "log"
    "github.com/adityaphra/surf"
)

func main() {
    resp := surf.NewClient().Get("https://api.github.com/users/github").Do()
    if resp.IsErr() {
        log.Fatal(resp.Err())
    }

    fmt.Println(resp.Ok().Body.String())
}

JSON Response Handling

type User struct {
    Name     string `json:"name"`
    Company  string `json:"company"`
    Location string `json:"location"`
}

resp := surf.NewClient().Get("https://api.github.com/users/github").Do()
if resp.IsOk() {
    var user User
    resp.Ok().Body.JSON(&user)
    fmt.Printf("User: %+v\n", user)
}

🎭 Browser Impersonation

Chrome Impersonation

client := surf.NewClient().
    Builder().
    Impersonate().
    Chrome().        // Latest Chrome v142
    Build()

resp := client.Get("https://example.com").Do()

Firefox with Random OS

client := surf.NewClient().
    Builder().
    Impersonate().
    RandomOS().      // Randomly selects Windows, macOS, Linux, Android, or iOS
    FireFox().       // Latest Firefox v146
    Build()

Platform-Specific Impersonation

// iOS Chrome
client := surf.NewClient().
    Builder().
    Impersonate().
    IOS().
    Chrome().
    Build()

// Android Chrome
client := surf.NewClient().
    Builder().
    Impersonate().
    Android().
    Chrome().
    Build()

🚀 HTTP/3 & Complete QUIC Fingerprinting

Chrome HTTP/3 with Automatic Detection

// Automatic HTTP/3 with Chrome fingerprinting
client := surf.NewClient().
    Builder().
    Impersonate().Chrome().
    HTTP3().        // Auto-detects Chrome and applies appropriate QUIC settings
    Build()

resp := client.Get("https://cloudflare-quic.com/").Do()
if resp.IsOk() {
    fmt.Printf("Protocol: %s\n", resp.Ok().Proto) // HTTP/3.0
}

Firefox HTTP/3

// Firefox with HTTP/3 fingerprinting
client := surf.NewClient().
    Builder().
    Impersonate().FireFox().
    HTTP3().        // Auto-detects Firefox and applies Firefox QUIC settings
    Build()

resp := client.Get("https://cloudflare-quic.com/").Do()

Manual HTTP/3 Configuration

// Custom QUIC fingerprint with Chrome settings
client := surf.NewClient().
    Builder().
    HTTP3Settings().Chrome().Set().
    Build()

// Custom QUIC fingerprint with Firefox settings
client := surf.NewClient().
    Builder().
    HTTP3Settings().Firefox().Set().
    Build()

// Custom QUIC ID
client := surf.NewClient().
    Builder().
    HTTP3Settings().
    SetQUICID(uquic.QUICChrome_115).
    Set().
    Build()

// Custom QUIC Spec
spec, _ := uquic.QUICID2Spec(uquic.QUICFirefox_116)
client := surf.NewClient().
    Builder().
    HTTP3Settings().
    SetQUICSpec(spec).
    Set().
    Build()

HTTP/3 with Complete Fingerprinting

// Combine TLS fingerprinting with HTTP/3 QUIC fingerprinting
client := surf.NewClient().
    Builder().
    JA().Chrome142().               // TLS fingerprint (JA3/JA4)
    HTTP3Settings().Chrome().Set().  // Complete QUIC fingerprint (JA4QUIC)
    Build()

resp := client.Get("https://cloudflare-quic.com/").Do()

HTTP/3 Compatibility & Fallbacks

HTTP/3 automatically handles compatibility issues:

// With HTTP proxy - automatically falls back to HTTP/2
client := surf.NewClient().
    Builder().
    Proxy("http://proxy:8080").     // HTTP proxies incompatible with HTTP/3
    HTTP3Settings().Chrome().Set(). // Will use HTTP/2 instead
    Build()

// With SOCKS5 proxy - HTTP/3 works over UDP
client := surf.NewClient().
    Builder().
    Proxy("socks5://127.0.0.1:1080"). // SOCKS5 UDP proxy supports HTTP/3
    HTTP3Settings().Chrome().Set().   // Will use HTTP/3 over SOCKS5
    Build()

// With DNS settings - works seamlessly
client := surf.NewClient().
    Builder().
    DNS("8.8.8.8:53").             // Custom DNS works with HTTP/3
    HTTP3Settings().Chrome().Set().
    Build()

// With DNS-over-TLS - works seamlessly
client := surf.NewClient().
    Builder().
    DNSOverTLS().Google().          // DoT works with HTTP/3
    HTTP3Settings().Chrome().Set().
    Build()

Key HTTP/3 Features:

  • ✅ Complete QUIC Fingerprinting: Full Chrome and Firefox QUIC transport parameter matching
  • ✅ Header Ordering: Perfect browser-like header sequence preservation
  • ✅ SOCKS5 UDP Support: HTTP/3 works seamlessly over SOCKS5 UDP proxies
  • ✅ Automatic Fallback: Smart fallback to HTTP/2 when HTTP proxies are configured
  • ✅ DNS Integration: Custom DNS and DNS-over-TLS support
  • ✅ JA4QUIC Support: Advanced QUIC fingerprinting with Initial Packet + TLS ClientHello
  • ✅ Order Independence: HTTP3() works regardless of call order

🔧 Advanced Configuration

Custom JA3 Fingerprint

// Use specific browser versions
client := surf.NewClient().
    Builder().
    JA().
    Chrome().     // Latest Chrome
    Build()


// Randomized fingerprints for evasion
client := surf.NewClient().
    Builder().
    JA().
    Randomized().    // Random TLS fingerprint
    Build()

// With custom HelloID
client := surf.NewClient().
    Builder().
    JA().
    SetHelloID(utls.HelloChrome_Auto).
    Build()

// With custom HelloSpec
client := surf.NewClient().
    Builder().
    JA().
    SetHelloSpec(customSpec).
    Build()

HTTP/2 Configuration

client := surf.NewClient().
    Builder().
    HTTP2Settings().
    HeaderTableSize(65536).
    EnablePush(0).
    InitialWindowSize(6291456).
    MaxHeaderListSize(262144).
    ConnectionFlow(15663105).
    Set().
    Build()

HTTP/3 Configuration

// Automatic browser detection
client := surf.NewClient().
    Builder().
    Impersonate().Chrome().
    HTTP3().
    Build()

// Manual configuration
client := surf.NewClient().
    Builder().
    HTTP3Settings().Chrome().Set().
    Build()

Proxy Configuration

// Single proxy
client := surf.NewClient().
    Builder().
    Proxy("http://proxy.example.com:8080").
    Build()

// Rotating proxies
proxies := []string{
    "http://proxy1.example.com:8080",
    "http://proxy2.example.com:8080",
    "socks5://proxy3.example.com:1080",
}

client := surf.NewClient().
    Builder().
    Proxy(proxies).  // Randomly selects from list
    Build()

SOCKS5 UDP Proxy Support

Surf supports HTTP/3 over SOCKS5 UDP proxies, combining the benefits of modern QUIC protocol with proxy functionality:

// HTTP/3 over SOCKS5 UDP proxy
client := surf.NewClient().
    Builder().
    Proxy("socks5://127.0.0.1:1080").
    Impersonate().Chrome().
    HTTP3().  // Uses HTTP/3 over SOCKS5 UDP
    Build()

// SOCKS5 with custom DNS resolution
client := surf.NewClient().
    Builder().
    DNS("8.8.8.8:53").              // Custom DNS resolver
    Proxy("socks5://proxy:1080").   // SOCKS5 UDP proxy
    HTTP3().                        // HTTP/3 over SOCKS5
    Build()

🔌 Middleware System

Request Middleware

client := surf.NewClient().
    Builder().
    With(func(req *surf.Request) error {
        req.AddHeaders("X-Custom-Header", "value")
        fmt.Printf("Request to: %s\n", req.GetRequest().URL)
        return nil
    }).
    Build()

Response Middleware

client := surf.NewClient().
    Builder().
    With(func(resp *surf.Response) error {
        fmt.Printf("Response status: %d\n", resp.StatusCode)
        fmt.Printf("Response time: %v\n", resp.Time)
        return nil
    }).
    Build()

Client Middleware

client := surf.NewClient().
    Builder().
    With(func(client *surf.Client) {
        // Modify client configuration
        client.GetClient().Timeout = 30 * time.Second
    }).
    Build()

📤 Request Types

POST with JSON

user := map[string]string{
    "name": "John Doe",
    "email": "john@example.com",
}

resp := surf.NewClient().
    Post("https://api.example.com/users", user).
    Do()

Form Data

// Standard form data (field order not guaranteed)
formData := map[string]string{
    "username": "john",
    "password": "secret",
}

resp := surf.NewClient().
    Post("https://example.com/login", formData).
    Do()

// Ordered form data (preserves field insertion order)
orderedForm := g.NewMapOrd[string, string]()
orderedForm.Set("username", "john")
orderedForm.Set("password", "secret")
orderedForm.Set("remember_me", "true")

resp := surf.NewClient().
    Post("https://example.com/login", orderedForm).
    Do()

File Upload

// Single file upload
resp := surf.NewClient().
    FileUpload(
        "https://api.example.com/upload",
        "file",                    // field name
        "/path/to/file.pdf",       // file path
    ).Do()

// With additional form fields
extraData := g.MapOrd[string, string]{
    "description": "Important document",
    "category": "reports",
}

resp := surf.NewClient().
    FileUpload(
        "https://api.example.com/upload",
        "file",
        "/path/to/file.pdf",
        extraData,
    ).Do()

Multipart Form

fields := g.NewMapOrd[g.String, g.String]()
fields.Set("field1", "value1")
fields.Set("field2", "value2")

resp := surf.NewClient().
    Multipart("https://api.example.com/form", fields).
    Do()

🔄 Session Management

Persistent Sessions

client := surf.NewClient().
    Builder().
    Session().        // Enable cookie jar
    Build()

// Login
client.Post("https://example.com/login", credentials).Do()

// Subsequent requests will include session cookies
resp := client.Get("https://example.com/dashboard").Do()

// Set cookies
cookies := []*http.Cookie{
    {Name: "session", Value: "abc123"},
    {Name: "preference", Value: "dark_mode"},
}

resp := surf.NewClient().
    Get("https://example.com").
    AddCookies(cookies...).
    Do()

// Get cookies from response
if resp.IsOk() {
    for _, cookie := range resp.Ok().Cookies {
        fmt.Printf("Cookie: %s = %s\n", cookie.Name, cookie.Value)
    }
}

📊 Response Handling

Status Code Checking

resp := surf.NewClient().Get("https://api.example.com/data").Do()

if resp.IsOk() {
    switch {
    case resp.Ok().StatusCode.IsSuccess():
        fmt.Println("Success!")
    case resp.Ok().StatusCode.IsRedirect():
        fmt.Println("Redirected to:", resp.Ok().Location())
    case resp.Ok().StatusCode.IsClientError():
        fmt.Println("Client error:", resp.Ok().StatusCode)
    case resp.Ok().StatusCode.IsServerError():
        fmt.Println("Server error:", resp.Ok().StatusCode)
    }
}

Body Processing

resp := surf.NewClient().Get("https://example.com/data").Do()
if resp.IsOk() {
    body := resp.Ok().Body

    // As string
    content := body.String()

    // As bytes
    data := body.Bytes()

    // MD5 hash
    hash := body.MD5()

    // UTF-8 conversion
    utf8Content := body.UTF8()

    // Check content
    if body.Contains("success") {
        fmt.Println("Request succeeded!")
    }

    // Save to file
    err := body.Dump("response.html")
}

Streaming Large Responses

resp := surf.NewClient().Get("https://example.com/large-file").Do()
if resp.IsOk() {
    reader := resp.Ok().Body.Stream()

    scanner := bufio.NewScanner(reader)
    for scanner.Scan() {
        fmt.Println(scanner.Text())
    }
}

Server-Sent Events (SSE)

resp := surf.NewClient().Get("https://example.com/events").Do()
if resp.IsOk() {
    resp.Ok().Body.SSE(func(event *sse.Event) bool {
        fmt.Printf("Event: %s, Data: %s\n", event.Name, event.Data)
        return true  // Continue reading (false to stop)
    })
}

🔍 Debugging

Request/Response Debugging

resp := surf.NewClient().
    Get("https://api.example.com").
    Do()

if resp.IsOk() {
    resp.Ok().Debug().
        Request().      // Show request details
        Response(true). // Show response with body
        Print()
}

TLS Information

resp := surf.NewClient().Get("https://example.com").Do()
if resp.IsOk() {
    if tlsInfo := resp.Ok().TLSGrabber(); tlsInfo != nil {
        fmt.Printf("TLS Version: %s\n", tlsInfo.Version)
        fmt.Printf("Cipher Suite: %s\n", tlsInfo.CipherSuite)
        fmt.Printf("Server Name: %s\n", tlsInfo.ServerName)

        for _, cert := range tlsInfo.PeerCertificates {
            fmt.Printf("Certificate CN: %s\n", cert.Subject.CommonName)
        }
    }
}

⚡ Performance Optimization

Connection Reuse with Singleton

// Create a reusable client
client := surf.NewClient().
    Builder().
    Singleton().      // Enable connection pooling
    Impersonate().
    Chrome().
    Build()

// Reuse for multiple requests
for i := 0; i < 100; i++ {
    resp := client.Get("https://api.example.com/data").Do()
    // Process response
}

// Clean up when done
defer client.CloseIdleConnections()

Response Caching

client := surf.NewClient().
    Builder().
    CacheBody().      // Enable body caching
    Build()

resp := client.Get("https://api.example.com/data").Do()
if resp.IsOk() {
    // First access reads from network
    data1 := resp.Ok().Body.Bytes()

    // Subsequent accesses use cache
    data2 := resp.Ok().Body.Bytes()  // No network I/O
}

Retry Configuration

client := surf.NewClient().
    Builder().
    Retry(3, 2*time.Second).           // Max 3 retries, 2 second wait
    RetryCodes(http.StatusTooManyRequests, http.StatusServiceUnavailable).
    Build()

🌐 Advanced Features

H2C (HTTP/2 Cleartext)

// Enable HTTP/2 without TLS
client := surf.NewClient().
    Builder().
    H2C().
    Build()

resp := client.Get("http://localhost:8080/h2c-endpoint").Do()

Custom Headers Order

// Control exact header order for fingerprinting evasion
headers := g.NewMapOrd[g.String, g.String]()
headers.Set("User-Agent", "Custom/1.0")
headers.Set("Accept", "*/*")
headers.Set("Accept-Language", "en-US")
headers.Set("Accept-Encoding", "gzip, deflate")

client := surf.NewClient().
    Builder().
    SetHeaders(headers).  // Headers will be sent in this exact order
    Build()

Custom DNS Resolver

client := surf.NewClient().
    Builder().
    Resolver("8.8.8.8:53").  // Use Google DNS
    Build()

DNS-over-TLS

client := surf.NewClient().
    Builder().
    DNSOverTLS("1.1.1.1:853").  // Cloudflare DoT
    Build()

Unix Domain Sockets

client := surf.NewClient().
    Builder().
    UnixSocket("/var/run/docker.sock").
    Build()

resp := client.Get("http://localhost/v1.41/containers/json").Do()

Network Interface Binding

client := surf.NewClient().
    Builder().
    InterfaceAddr("192.168.1.100").  // Bind to specific IP
    Build()

Raw HTTP Requests

rawRequest := `GET /api/data HTTP/1.1
Host: example.com
User-Agent: Custom/1.0
Accept: application/json

`

resp := surf.NewClient().
    Raw(g.String(rawRequest), "https").
    Do()

📚 API Reference

Client Methods

Method Description
NewClient() Creates a new HTTP client with defaults
Get(url, params...) Creates a GET request
Post(url, data) Creates a POST request
Put(url, data) Creates a PUT request
Patch(url, data) Creates a PATCH request
Delete(url, data...) Creates a DELETE request
Head(url) Creates a HEAD request
FileUpload(url, field, path, data...) Creates a multipart file upload
Multipart(url, fields) Creates a multipart form request
Raw(raw, scheme) Creates a request from raw HTTP

Builder Methods

Method Description
Impersonate() Enable browser impersonation
JA() Configure JA3/JA4 fingerprinting
HTTP2Settings() Configure HTTP/2 parameters
HTTP3Settings() Configure HTTP/3 & QUIC parameters
HTTP3() Enable HTTP/3 with automatic browser detection
H2C() Enable HTTP/2 cleartext
Proxy(proxy) Set proxy configuration (string, []string for rotation)
DNS(dns) Set custom DNS resolver
DNSOverTLS() Configure DNS-over-TLS
Session() Enable cookie jar for sessions
Singleton() Enable connection pooling (reuse client)
Timeout(duration) Set request timeout
MaxRedirects(n) Set maximum redirects
NotFollowRedirects() Disable redirect following
FollowOnlyHostRedirects() Only follow same-host redirects
ForwardHeadersOnRedirect() Forward headers on redirects
RedirectPolicy(fn) Custom redirect policy function
Retry(max, wait, codes...) Configure retry logic
CacheBody() Enable response body caching
With(middleware, priority...) Add middleware
BasicAuth(auth) Set basic authentication
BearerAuth(token) Set bearer token authentication
UserAgent(ua) Set custom user agent
SetHeaders(headers...) Set request headers
AddHeaders(headers...) Add request headers
AddCookies(cookies...) Add cookies
WithContext(ctx) Add context
ContentType(type) Set content type
GetRemoteAddress() Track remote address
DisableKeepAlive() Disable keep-alive
DisableCompression() Disable compression
ForceHTTP1() Force HTTP/1.1
UnixDomainSocket(path) Use Unix socket
InterfaceAddr(addr) Bind to network interface
Boundary(fn) Custom multipart boundary generator
Std() Convert to standard net/http.Client

Request Methods

Method Description
Do() Execute the request
WithContext(ctx) Add context to request
SetHeaders(headers...) Set request headers
AddHeaders(headers...) Add request headers
AddCookies(cookies...) Add cookies to request

Response Properties

Property Type Description
StatusCode StatusCode HTTP status code
Headers Headers Response headers
Cookies Cookies Response cookies
Body *Body Response body
URL *url.URL Final URL after redirects
Time time.Duration Request duration
ContentLength int64 Content length
Proto string HTTP protocol version
Attempts int Number of retry attempts

Body Methods

Method Description
String() Get body as string
Bytes() Get body as bytes
JSON(v) Decode JSON into struct
XML(v) Decode XML into struct
MD5() Calculate MD5 hash
UTF8() Convert to UTF-8
Stream() Get buffered reader
SSE(fn) Process Server-Sent Events
Dump(file) Save to file
Contains(pattern) Check if contains pattern
Limit(n) Limit body size
Close() Close body reader

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with enetx/http for enhanced HTTP functionality
  • HTTP/3 support and complete QUIC fingerprinting powered by uQUIC
  • TLS fingerprinting powered by uTLS
  • Generic utilities from enetx/g

📞 Support

Made with ❤️ by the Surf contributors

Documentation

Overview

Package surf provides a comprehensive HTTP client library with advanced features for web scraping, automation, and HTTP/3 support with various browser fingerprinting capabilities.

Package surf provides HTTP/3 support with full uQUIC fingerprinting for advanced web scraping and automation. This file implements HTTP/3 transport with complete QUIC Initial Packet + TLS ClientHello fingerprinting, SOCKS5 proxy support, and automatic fallback to HTTP/2 for non-SOCKS5 proxies.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Body 

type Body struct {
	Reader io.ReadCloser // ReadCloser for accessing the raw body content
	// contains filtered or unexported fields
}

Body represents an HTTP response body with enhanced functionality and automatic caching. Provides convenient methods for parsing common data formats (JSON, XML, text) and includes features like automatic decompression, content caching, character set detection, and size limits.

func (*Body) Bytes 

func (b *Body) Bytes() g.Bytes

Bytes returns the body's content as a byte slice.

func (*Body) Close 

func (b *Body) Close() error

Close closes the body and returns any error encountered.

func (*Body) Contains 

func (b *Body) Contains(pattern any) bool

Contains checks if the body's content contains the provided pattern (byte slice, string, or *regexp.Regexp) and returns a boolean.

func (*Body) Dump 

func (b *Body) Dump(filename g.String) error

Dump dumps the body's content to a file with the given filename.

func (*Body) JSON 

func (b *Body) JSON(data any) error

JSON decodes the body's content as JSON into the provided data structure.

func (*Body) Limit 

func (b *Body) Limit(limit int64) *Body

Limit sets the body's size limit and returns the modified body.

func (*Body) MD5 

func (b *Body) MD5() g.String

MD5 returns the MD5 hash of the body's content as a HString.

func (*Body) SSE 

func (b *Body) SSE(fn func(event *sse.Event) bool) error

SSE reads the body's content as Server-Sent Events (SSE) and calls the provided function for each event. It expects the function to take an *sse.Event pointer as its argument and return a boolean value. If the function returns false, the SSE reading stops.

func (*Body) Stream 

func (b *Body) Stream() *bufio.Reader

Stream returns the body's bufio.Reader for streaming the content.

func (*Body) String 

func (b *Body) String() g.String

String returns the body's content as a g.String.

func (*Body) UTF8 

func (b *Body) UTF8() g.String

UTF8 converts the body's content to UTF-8 encoding and returns it as a string.

func (*Body) XML 

func (b *Body) XML(data any) error

XML decodes the body's content as XML into the provided data structure.

type Builder 

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

Builder provides a fluent interface for configuring HTTP clients with various advanced features including proxy settings, TLS fingerprinting, HTTP/2 and HTTP/3 support, retry logic, redirect handling, and browser impersonation capabilities.

func (*Builder) AddCookies 

func (b *Builder) AddCookies(cookies ...*http.Cookie) *Builder

AddCookies adds cookies to the request.

func (*Builder) AddHeaders 

func (b *Builder) AddHeaders(headers ...any) *Builder

AddHeaders adds headers to the request, appending to any existing headers with the same name.

func (*Builder) BasicAuth 

func (b *Builder) BasicAuth(authentication g.String) *Builder

BasicAuth sets the basic authentication credentials for the client.

func (*Builder) BearerAuth 

func (b *Builder) BearerAuth(authentication g.String) *Builder

BearerAuth sets the bearer token for the client.

func (*Builder) Boundary 

func (b *Builder) Boundary(boundary func() g.String) *Builder

func (*Builder) Build 

func (b *Builder) Build() *Client

Build sets the provided settings for the client and returns the updated client. It configures various settings like HTTP2, sessions, keep-alive, dial TLS, resolver, interface address, timeout, and redirect policy.

func (*Builder) CacheBody 

func (b *Builder) CacheBody() *Builder

CacheBody configures whether the client should cache the body of the response.

func (*Builder) ContentType 

func (b *Builder) ContentType(contentType g.String) *Builder

ContentType sets the content type for the client.

func (*Builder) DNS 

func (b *Builder) DNS(dns g.String) *Builder

DNS sets the custom DNS resolver address.

func (*Builder) DNSOverTLS 

func (b *Builder) DNSOverTLS() *DNSOverTLS

DNSOverTLS configures the client to use DNS over TLS.

func (*Builder) DisableCompression 

func (b *Builder) DisableCompression() *Builder

DisableCompression disables compression for the HTTP client.

func (*Builder) DisableKeepAlive 

func (b *Builder) DisableKeepAlive() *Builder

DisableKeepAlive disable keep-alive connections.

func (*Builder) FollowOnlyHostRedirects 

func (b *Builder) FollowOnlyHostRedirects() *Builder

FollowOnlyHostRedirects configures whether the client should only follow redirects within the same host.

func (*Builder) ForceHTTP1 

func (b *Builder) ForceHTTP1() *Builder

ForceHTTP1MW configures the client to use HTTP/1.1 forcefully.

func (*Builder) ForceHTTP2 

func (b *Builder) ForceHTTP2() *Builder

ForceHTTP2MW configures the client to use HTTP/2 forcefully.

func (*Builder) ForwardHeadersOnRedirect 

func (b *Builder) ForwardHeadersOnRedirect() *Builder

ForwardHeadersOnRedirect adds a middleware to the ClientBuilder object that ensures HTTP headers are forwarded during a redirect.

func (*Builder) GetRemoteAddress 

func (b *Builder) GetRemoteAddress() *Builder

GetRemoteAddress configures whether the client should get the remote address.

func (*Builder) H2C 

func (b *Builder) H2C() *Builder

H2C configures the client to handle HTTP/2 Cleartext (h2c).

func (*Builder) HTTP2Settings 

func (b *Builder) HTTP2Settings() *HTTP2Settings

HTTP2Settings configures settings related to HTTP/2 and returns an http2s struct.

func (*Builder) HTTP3 

func (b *Builder) HTTP3() *Builder

HTTP3 enables HTTP/3 with automatic browser detection. Settings are applied lazily in Build() based on the impersonated browser. Usage: surf.NewClient().Builder().Impersonate().Chrome().HTTP3().Build()

func (*Builder) HTTP3Settings 

func (b *Builder) HTTP3Settings() *HTTP3Settings

HTTP3Settings configures settings related to HTTP/3 and returns an http3s struct.

func (*Builder) Impersonate 

func (b *Builder) Impersonate() *Impersonate

Impersonate configures something related to impersonation and returns an impersonate struct.

func (*Builder) InterfaceAddr 

func (b *Builder) InterfaceAddr(address g.String) *Builder

InterfaceAddr sets the network interface address for the client.

func (*Builder) JA 

func (b *Builder) JA() *JA

JA configures the client to use a specific TLS fingerprint.

func (*Builder) MaxRedirects 

func (b *Builder) MaxRedirects(maxRedirects int) *Builder

MaxRedirects sets the maximum number of redirects the client should follow.

func (*Builder) NotFollowRedirects 

func (b *Builder) NotFollowRedirects() *Builder

NotFollowRedirects disables following redirects for the client.

func (*Builder) Proxy 

func (b *Builder) Proxy(proxy any) *Builder

Proxy sets the proxy settings for the client. Supports both static proxy configurations and dynamic proxy provider functions.

Static proxy examples: 

.Proxy("socks5://127.0.0.1:9050")
.Proxy([]string{"socks5://proxy1", "http://proxy2"})

Dynamic proxy example: 

.Proxy(func() g.String {
  // Your proxy rotation logic here
  return "socks5://127.0.0.1:9050"
})

func (*Builder) RedirectPolicy 

func (b *Builder) RedirectPolicy(fn func(*http.Request, []*http.Request) error) *Builder

RedirectPolicy sets a custom redirect policy for the client.

func (*Builder) Retry 

func (b *Builder) Retry(retryMax int, retryWait time.Duration, codes ...int) *Builder

Retry configures the retry behavior of the client.

Parameters: 

retryMax: Maximum number of retries to be attempted.
retryWait: Duration to wait between retries.
codes: Optional list of HTTP status codes that trigger retries.
       If no codes are provided, default codes will be used
       (500, 429, 503 - Internal Server Error, Too Many Requests, Service Unavailable).

func (*Builder) Session 

func (b *Builder) Session() *Builder

Session configures whether the client should maintain a session.

func (*Builder) SetDialer 

func (b *Builder) SetDialer(dialer *net.Dialer) *Builder

setCustomDialer of the ClientBuilder instance.

func (*Builder) SetHeaders 

func (b *Builder) SetHeaders(headers ...any) *Builder

SetHeaders sets headers for the request, replacing existing ones with the same name.

func (*Builder) Singleton 

func (b *Builder) Singleton() *Builder

Singleton configures the client to use a singleton instance, ensuring there's only one client instance. This is needed specifically for JA or Impersonate functionalities. 

cli := surf.NewClient().
	Builder().
	Singleton(). // for reuse client
	Impersonate().
	FireFox().
	Build()

defer cli.CloseIdleConnections()

func (Builder) String 

func (b Builder) String() string

String generate a string representation of the ClientBuilder instance.

func (*Builder) Timeout 

func (b *Builder) Timeout(timeout time.Duration) *Builder

Timeout sets the timeout duration for the client.

func (*Builder) UnixSocket 

func (b *Builder) UnixSocket(address g.String) *Builder

UnixSocket sets the path for a Unix domain socket. This allows the HTTP client to connect to the server using a Unix domain socket instead of a traditional TCP/IP connection.

func (*Builder) UserAgent 

func (b *Builder) UserAgent(userAgent any) *Builder

UserAgent sets the user agent for the client.

func (*Builder) With 

func (b *Builder) With(middleware any, priority ...int) *Builder

With registers middleware into the client builder with optional priority.

It accepts one of the following middleware function types:

  • func(*surf.Client) error — client middleware, modifies or initializes the client
  • func(*surf.Request) error — request middleware, intercepts or transforms outgoing requests
  • func(*surf.Response) error — response middleware, intercepts or transforms incoming responses

Parameters:

  • middleware: A function matching one of the supported middleware types.
  • priority (optional): Integer priority level. Lower values run earlier. Defaults to 0.

Middleware with the same priority are executed in order of insertion (FIFO). If the middleware type is not recognized, With panics with an informative error.

Example: 

// Adding client middleware to modify client settings.
.With(func(client *surf.Client) error {
    // Custom logic to modify the client settings.
    return nil
})

// Adding request middleware to intercept outgoing requests.
.With(func(req *surf.Request) error {
    // Custom logic to modify outgoing requests.
    return nil
})

// Adding response middleware to intercept incoming responses.
.With(func(resp *surf.Response) error {
    // Custom logic to handle incoming responses.
    return nil
})

Note: Ensure that middleware functions adhere to the specified function signatures to work correctly with the With method.

func (*Builder) WithContext 

func (b *Builder) WithContext(ctx context.Context) *Builder

WithContext associates the provided context with the request.

type Client 

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

Client represents a highly configurable HTTP client with middleware support, advanced transport options (HTTP/1.1, HTTP/2, HTTP/3), proxy handling, TLS fingerprinting, and comprehensive request/response processing capabilities.

func NewClient 

func NewClient() *Client

NewClient creates a new Client with sensible default settings including default dialer, TLS configuration, HTTP transport, and basic middleware.

func (*Client) Builder 

func (c *Client) Builder() *Builder

Builder returns a new Builder instance associated with this client. The builder allows for method chaining to configure various client options.

func (*Client) CloseIdleConnections 

func (c *Client) CloseIdleConnections()

CloseIdleConnections removes all entries from the cached transports. Specifically used when Singleton is enabled for JA3 or Impersonate functionalities.

func (*Client) Delete 

func (c *Client) Delete(rawURL g.String, data ...any) *Request

Delete creates a new HTTP DELETE request with the specified URL. Optional data parameter can be provided for request body.

func (*Client) FileUpload 

func (c *Client) FileUpload(rawURL, fieldName, filePath g.String, data ...any) *Request

FileUpload creates a new multipart file upload request. It uploads a file from filePath using the specified fieldName in the form. Optional data can include additional form fields (g.MapOrd) or custom reader (io.Reader).

func (*Client) Get 

func (c *Client) Get(rawURL g.String, data ...any) *Request

Get creates a new HTTP GET request with the specified URL. Optional data parameter can be provided for query parameters.

func (*Client) GetClient 

func (c *Client) GetClient() *http.Client

GetClient returns http.Client used by the Client.

func (*Client) GetDialer 

func (c *Client) GetDialer() *net.Dialer

GetDialer returns the net.Dialer used by the Client.

func (*Client) GetTLSConfig 

func (c *Client) GetTLSConfig() *tls.Config

GetTLSConfig returns the tls.Config used by the Client.

func (*Client) GetTransport 

func (c *Client) GetTransport() http.RoundTripper

GetTransport returns the http.transport used by the Client.

func (*Client) Head 

func (c *Client) Head(rawURL g.String) *Request

Head creates a new HTTP HEAD request with the specified URL. HEAD requests are identical to GET but only return response headers.

func (*Client) Multipart 

func (c *Client) Multipart(rawURL g.String, multipartData g.MapOrd[g.String, g.String]) *Request

Multipart creates a new multipart form data request with the specified form fields. The multipartData map contains field names and their corresponding values.

func (*Client) Patch 

func (c *Client) Patch(rawURL g.String, data any) *Request

Patch creates a new HTTP PATCH request with the specified URL and data. PATCH requests typically apply partial modifications to a resource.

func (*Client) Post 

func (c *Client) Post(rawURL g.String, data any) *Request

Post creates a new HTTP POST request with the specified URL and data. Data can be of various types (string, map, struct) and will be encoded appropriately.

func (*Client) Put 

func (c *Client) Put(rawURL g.String, data any) *Request

Put creates a new HTTP PUT request with the specified URL and data. PUT requests typically replace the entire resource at the specified URL.

func (*Client) Raw 

func (c *Client) Raw(raw, scheme g.String) *Request

Raw creates a new HTTP request using the provided raw data and scheme. The raw parameter should contain the raw HTTP request data as a string. The scheme parameter specifies the scheme (e.g., http, https) for the request.

func (*Client) Std 

func (c *Client) Std() *_http.Client

Std returns a standard net/http.Client that wraps the configured surf client. This is useful for integrating with third-party libraries that expect a standard net/http.Client while preserving most surf features.

Supported features:

  • JA3/TLS fingerprinting
  • HTTP/2 settings
  • Cookies and sessions
  • Request/Response middleware
  • Headers (User-Agent, custom headers)
  • Proxy configuration
  • Timeout settings
  • Redirect policies
  • Impersonate browser headers

Known limitations:

  • Retry logic is NOT supported (implemented in Request.Do(), not in transport)
  • Response body caching is NOT supported
  • Remote address tracking is NOT supported
  • Request timing information is NOT available

For applications requiring retry logic, consider implementing it at the application level or use surf.Client directly for those specific requests.

Example usage: 

surfClient := surf.NewClient().
	Builder().
	JA3().Chrome().
	Session().
	Build()

// For libraries expecting net/http.Client
stdClient := surfClient.Std()

botClient := &BaseBotClient{
	Client: *stdClient,
}

type CookieJarAdapter 

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

CookieJarAdapter adapts github.com/enetx/http.CookieJar to net/http.CookieJar. It provides bidirectional cookie conversion between the two HTTP packages, ensuring cookies set through either interface work correctly.

func (*CookieJarAdapter) Cookies 

func (c *CookieJarAdapter) Cookies(u *url.URL) []*_http.Cookie

Cookies implements http.CookieJar interface. It retrieves cookies from the underlying surf cookie jar and converts them to standard net/http cookie format.

func (*CookieJarAdapter) SetCookies 

func (c *CookieJarAdapter) SetCookies(u *url.URL, _cookies []*_http.Cookie)

SetCookies implements http.CookieJar interface. It converts standard net/http cookies to enetx/http format and delegates to the underlying surf cookie jar.

type Cookies 

type Cookies []*http.Cookie

Cookies represents a list of HTTP Cookies.

func (*Cookies) Contains 

func (cs *Cookies) Contains(pattern any) bool

Contains checks if the cookies collection contains a cookie that matches the provided pattern. The pattern parameter can be either a string or a pointer to a regexp.Regexp object. The method returns true if a matching cookie is found and false otherwise.

type DNSOverTLS 

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

DNSOverTLS is a configuration struct for DNS over TLS settings.

func (*DNSOverTLS) AdGuard 

func (dot *DNSOverTLS) AdGuard() *Builder

AdGuard sets up DNS over TLS with AdGuard DNS.

func (*DNSOverTLS) AddProvider 

func (dot *DNSOverTLS) AddProvider(serverName g.String, addresses ...g.String) *Builder

AddProvider sets up DNS over TLS with a custom DNS provider. It configures a custom net.Resolver using the resolver method.

func (*DNSOverTLS) Ali 

func (dot *DNSOverTLS) Ali() *Builder

Ali sets up DNS over TLS with AliDNS.

func (*DNSOverTLS) CIRAShield 

func (dot *DNSOverTLS) CIRAShield() *Builder

CIRAShield sets up DNS over TLS with CIRA Canadian Shield DNS.

func (*DNSOverTLS) Cloudflare 

func (dot *DNSOverTLS) Cloudflare() *Builder

Cloudflare sets up DNS over TLS with Cloudflare DNS.

func (*DNSOverTLS) Forge 

func (dot *DNSOverTLS) Forge() *Builder

Forge sets up DNS over TLS with DNS Forge.

func (*DNSOverTLS) Google 

func (dot *DNSOverTLS) Google() *Builder

Google sets up DNS over TLS with Google Public DNS.

func (*DNSOverTLS) LibreDNS 

func (dot *DNSOverTLS) LibreDNS() *Builder

LibreDNS sets up DNS over TLS with LibreDNS.

func (*DNSOverTLS) Quad101 

func (dot *DNSOverTLS) Quad101() *Builder

Quad101 sets up DNS over TLS with Quad101 DNS.

func (*DNSOverTLS) Quad9 

func (dot *DNSOverTLS) Quad9() *Builder

Quad9 sets up DNS over TLS with Quad9 DNS.

func (*DNSOverTLS) SB 

func (dot *DNSOverTLS) SB() *Builder

SB sets up DNS over TLS with Secure DNS (dot.sb).

func (*DNSOverTLS) Switch 

func (dot *DNSOverTLS) Switch() *Builder

Switch sets up DNS over TLS with SWITCH DNS.

type Debug 

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

Debug is a struct that holds debugging information for an HTTP response.

func (*Debug) Print 

func (d *Debug) Print()

Print prints the debug information.

func (*Debug) Request 

func (d *Debug) Request(verbos ...bool) *Debug

Request appends the request details to the debug information.

func (*Debug) Response 

func (d *Debug) Response(verbos ...bool) *Debug

Response appends the response details to the debug information.

type Err101ResponseCode 

type Err101ResponseCode struct{ Msg string }

Err101ResponseCode indicates a 101 Switching Protocols response was received. This error is used to handle HTTP 101 responses that require protocol upgrades.

func (*Err101ResponseCode) Error 

func (e *Err101ResponseCode) Error() string

type ErrUserAgentType 

type ErrUserAgentType struct{ Msg string }

ErrUserAgentType indicates an invalid user agent type was provided. This error is returned when the user agent parameter is not of a supported type (string, g.String, slices, etc.).

func (*ErrUserAgentType) Error 

func (e *ErrUserAgentType) Error() string

type ErrWebSocketUpgrade 

type ErrWebSocketUpgrade struct{ Msg string }

ErrWebSocketUpgrade indicates that a request received a WebSocket upgrade response. This error is returned when the server responds with HTTP 101 Switching Protocols for WebSocket connections, which require special handling.

func (*ErrWebSocketUpgrade) Error 

func (e *ErrWebSocketUpgrade) Error() string

type HTTP2Settings 

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

HTTP2Settings represents HTTP/2 settings. https://lwthiker.com/networks/2022/06/17/http2-fingerprinting.html

func (*HTTP2Settings) ConnectionFlow 

func (h *HTTP2Settings) ConnectionFlow(size uint32) *HTTP2Settings

ConnectionFlow sets the flow control for the HTTP/2 connection.

func (*HTTP2Settings) EnablePush 

func (h *HTTP2Settings) EnablePush(size uint32) *HTTP2Settings

EnablePush enables HTTP/2 server push functionality.

func (*HTTP2Settings) HeaderTableSize 

func (h *HTTP2Settings) HeaderTableSize(size uint32) *HTTP2Settings

HeaderTableSize sets the header table size for HTTP/2 settings.

func (*HTTP2Settings) InitialWindowSize 

func (h *HTTP2Settings) InitialWindowSize(size uint32) *HTTP2Settings

InitialWindowSize sets the initial window size for HTTP/2 streams.

func (*HTTP2Settings) MaxConcurrentStreams 

func (h *HTTP2Settings) MaxConcurrentStreams(size uint32) *HTTP2Settings

MaxConcurrentStreams sets the maximum number of concurrent streams in HTTP/2.

func (*HTTP2Settings) MaxFrameSize 

func (h *HTTP2Settings) MaxFrameSize(size uint32) *HTTP2Settings

MaxFrameSize sets the maximum frame size for HTTP/2 frames.

func (*HTTP2Settings) MaxHeaderListSize 

func (h *HTTP2Settings) MaxHeaderListSize(size uint32) *HTTP2Settings

MaxHeaderListSize sets the maximum size of the header list in HTTP/2.

func (*HTTP2Settings) PriorityFrames 

func (h *HTTP2Settings) PriorityFrames(priorityFrames []http2.PriorityFrame) *HTTP2Settings

PriorityFrames sets the priority frames for HTTP/2.

func (*HTTP2Settings) PriorityParam 

func (h *HTTP2Settings) PriorityParam(priorityParam http2.PriorityParam) *HTTP2Settings

PriorityParam sets the priority parameter for HTTP/2.

func (*HTTP2Settings) Set 

func (h *HTTP2Settings) Set() *Builder

Set applies the accumulated HTTP/2 settings. It configures the HTTP/2 settings for the surf client.

type HTTP3Settings 

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

HTTP3Settings represents HTTP/3 settings with uQUIC fingerprinting support.

func (*HTTP3Settings) Chrome 

func (h *HTTP3Settings) Chrome() *HTTP3Settings

Chrome configures HTTP/3 settings to mimic Chrome browser.

func (*HTTP3Settings) Firefox 

func (h *HTTP3Settings) Firefox() *HTTP3Settings

Firefox configures HTTP/3 settings to mimic Firefox browser.

func (*HTTP3Settings) Set 

func (h *HTTP3Settings) Set() *Builder

Set applies the accumulated HTTP/3 settings. It configures the uQUIC transport for the surf client.

func (*HTTP3Settings) SetQUICID 

func (h *HTTP3Settings) SetQUICID(quicID uquic.QUICID) *HTTP3Settings

SetQUICID sets a custom QUIC ID for fingerprinting.

func (*HTTP3Settings) SetQUICSpec 

func (h *HTTP3Settings) SetQUICSpec(quicSpec uquic.QUICSpec) *HTTP3Settings

SetQUICSpec sets a custom QUIC spec for advanced fingerprinting.

type Headers 

type Headers http.Header

Headers represents a collection of HTTP Headers.

func (Headers) Clone 

func (h Headers) Clone() Headers

Clone returns a copy of Headers or nil if Headers is nil.

func (Headers) Contains 

func (h Headers) Contains(header g.String, patterns any) bool

Contains checks if the header contains any of the specified patterns. It accepts a header name and a pattern (or list of patterns) and returns a boolean value indicating whether any of the patterns are found in the header values. The patterns can be a string, a slice of strings, or a slice of *regexp.Regexp.

func (Headers) Get 

func (h Headers) Get(key g.String) g.String

Get returns the first value associated with a specified header key. It wraps the Get method from the textproto.MIMEHeader type.

func (Headers) Values 

func (h Headers) Values(key g.String) g.Slice[g.String]

Values returns the values associated with a specified header key. It wraps the Values method from the textproto.MIMEHeader type.

type Impersonate 

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

func (*Impersonate) Android 

func (im *Impersonate) Android() *Impersonate

Android sets the OS to Android.

func (*Impersonate) Chrome 

func (im *Impersonate) Chrome() *Builder

Chrome impersonates Chrome browser v142.

func (*Impersonate) FireFox 

func (im *Impersonate) FireFox() *Builder

FireFox impersonates Firefox browser v146.

func (*Impersonate) FireFoxPrivate 

func (im *Impersonate) FireFoxPrivate() *Builder

FireFoxPrivate impersonates Firefox private browser v146.

func (*Impersonate) IOS 

func (im *Impersonate) IOS() *Impersonate

IOS sets the OS to iOS.

func (*Impersonate) Linux 

func (im *Impersonate) Linux() *Impersonate

Linux sets the OS to Linux.

func (*Impersonate) MacOS 

func (im *Impersonate) MacOS() *Impersonate

MacOS sets the OS to macOS.

func (*Impersonate) RandomOS 

func (im *Impersonate) RandomOS() *Impersonate

RandomOS selects a random OS (Windows, macOS, Linux, Android, or iOS) for the impersonate.

func (*Impersonate) Tor 

func (im *Impersonate) Tor() *Builder

Tor impersonates Tor browser v14.5.6.

func (*Impersonate) TorPrivate 

func (im *Impersonate) TorPrivate() *Builder

TorPrivate impersonates Tor private browser v14.5.6.

func (*Impersonate) Windows 

func (im *Impersonate) Windows() *Impersonate

Windows sets the OS to Windows.

type ImpersonateOS 

type ImpersonateOS int

ImpersonateOS defines the operating system to impersonate in User-Agent strings.

type JA 

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

JA provides JA3/4 TLS fingerprinting capabilities for HTTP clients. JA is a method for creating SSL/TLS client fingerprints to identify and classify malware or other applications. This struct allows configuring various TLS ClientHello specifications to mimic different browsers and applications for advanced HTTP client behavior.

Reference: https://lwthiker.com/networks/2022/06/17/tls-fingerprinting.html

func (*JA) Android 

func (j *JA) Android() *Builder

Android sets the JA3/4 fingerprint to mimic Android 11 OkHttp client.

func (*JA) Chrome 

func (j *JA) Chrome() *Builder

Chrome sets the JA3/4 fingerprint to mimic the latest Chrome browser (auto-detection).

func (*JA) Chrome100 

func (j *JA) Chrome100() *Builder

Chrome100 sets the JA3/4 fingerprint to mimic Chrome version 100.

func (*JA) Chrome102 

func (j *JA) Chrome102() *Builder

Chrome102 sets the JA3/4 fingerprint to mimic Chrome version 102.

func (*JA) Chrome106 

func (j *JA) Chrome106() *Builder

Chrome106 sets the JA3/4 fingerprint to mimic Chrome version 106 with shuffled extensions.

func (*JA) Chrome120 

func (j *JA) Chrome120() *Builder

Chrome120 sets the JA3/4 fingerprint to mimic Chrome version 120.

func (*JA) Chrome120PQ 

func (j *JA) Chrome120PQ() *Builder

Chrome120PQ sets the JA3/4 fingerprint to mimic Chrome version 120 with post-quantum cryptography support.

func (*JA) Chrome142 

func (j *JA) Chrome142() *Builder

Chrome142 sets the JA3/4 fingerprint to mimic Chrome version 142.

func (*JA) Chrome58 

func (j *JA) Chrome58() *Builder

Chrome58 sets the JA3/4 fingerprint to mimic Chrome version 58.

func (*JA) Chrome62 

func (j *JA) Chrome62() *Builder

Chrome62 sets the JA3/4 fingerprint to mimic Chrome version 62.

func (*JA) Chrome70 

func (j *JA) Chrome70() *Builder

Chrome70 sets the JA3/4 fingerprint to mimic Chrome version 70.

func (*JA) Chrome72 

func (j *JA) Chrome72() *Builder

Chrome72 sets the JA3/4 fingerprint to mimic Chrome version 72.

func (*JA) Chrome83 

func (j *JA) Chrome83() *Builder

Chrome83 sets the JA3/4 fingerprint to mimic Chrome version 83.

func (*JA) Chrome87 

func (j *JA) Chrome87() *Builder

Chrome87 sets the JA3/4 fingerprint to mimic Chrome version 87.

func (*JA) Chrome96 

func (j *JA) Chrome96() *Builder

Chrome96 sets the JA3/4 fingerprint to mimic Chrome version 96.

func (*JA) Edge 

func (j *JA) Edge() *Builder

Edge sets the JA3/4 fingerprint to mimic Microsoft Edge version 85.

func (*JA) Edge106 

func (j *JA) Edge106() *Builder

Edge106 sets the JA3/4 fingerprint to mimic Microsoft Edge version 106.

func (*JA) Edge85 

func (j *JA) Edge85() *Builder

Edge85 sets the JA3/4 fingerprint to mimic Microsoft Edge version 85.

func (*JA) Firefox 

func (j *JA) Firefox() *Builder

Firefox sets the JA3/4 fingerprint to mimic the latest Firefox browser (auto-detection).

func (*JA) Firefox102 

func (j *JA) Firefox102() *Builder

Firefox102 sets the JA3/4 fingerprint to mimic Firefox version 102.

func (*JA) Firefox105 

func (j *JA) Firefox105() *Builder

Firefox105 sets the JA3/4 fingerprint to mimic Firefox version 105.

func (*JA) Firefox120 

func (j *JA) Firefox120() *Builder

Firefox120 sets the JA3/4 fingerprint to mimic Firefox version 120.

func (*JA) Firefox141 

func (j *JA) Firefox141() *Builder

Firefox141 sets the JA3/4 fingerprint to mimic Firefox version 141.

func (*JA) Firefox146 

func (j *JA) Firefox146() *Builder

Firefox146 sets the JA3/4 fingerprint to mimic Firefox version 146.

func (*JA) Firefox55 

func (j *JA) Firefox55() *Builder

Firefox55 sets the JA3/4 fingerprint to mimic Firefox version 55.

func (*JA) Firefox56 

func (j *JA) Firefox56() *Builder

Firefox56 sets the JA3/4 fingerprint to mimic Firefox version 56.

func (*JA) Firefox63 

func (j *JA) Firefox63() *Builder

Firefox63 sets the JA3/4 fingerprint to mimic Firefox version 63.

func (*JA) Firefox65 

func (j *JA) Firefox65() *Builder

Firefox65 sets the JA3/4 fingerprint to mimic Firefox version 65.

func (*JA) Firefox99 

func (j *JA) Firefox99() *Builder

Firefox99 sets the JA3/4 fingerprint to mimic Firefox version 99.

func (*JA) FirefoxPrivate146 

func (j *JA) FirefoxPrivate146() *Builder

FirefoxPrivate146 sets the JA3/4 fingerprint to mimic Firefox private version 146.

func (*JA) IOS 

func (j *JA) IOS() *Builder

IOS sets the JA3/4 fingerprint to mimic the latest iOS Safari browser (auto-detection).

func (*JA) IOS11 

func (j *JA) IOS11() *Builder

IOS11 sets the JA3/4 fingerprint to mimic iOS 11.1 Safari.

func (*JA) IOS12 

func (j *JA) IOS12() *Builder

IOS12 sets the JA3/4 fingerprint to mimic iOS 12.1 Safari.

func (*JA) IOS13 

func (j *JA) IOS13() *Builder

IOS13 sets the JA3/4 fingerprint to mimic iOS 13 Safari.

func (*JA) IOS14 

func (j *JA) IOS14() *Builder

IOS14 sets the JA3/4 fingerprint to mimic iOS 14 Safari.

func (*JA) Randomized 

func (j *JA) Randomized() *Builder

Randomized sets a completely randomized JA3/4 fingerprint.

func (*JA) RandomizedALPN 

func (j *JA) RandomizedALPN() *Builder

RandomizedALPN sets a randomized JA3/4 fingerprint with ALPN (Application-Layer Protocol Negotiation).

func (*JA) RandomizedNoALPN 

func (j *JA) RandomizedNoALPN() *Builder

RandomizedNoALPN sets a randomized JA3/4 fingerprint without ALPN.

func (*JA) Safari 

func (j *JA) Safari() *Builder

Safari sets the JA3/4 fingerprint to mimic the latest Safari browser (auto-detection).

func (*JA) SetHelloID 

func (j *JA) SetHelloID(id utls.ClientHelloID) *Builder

SetHelloID sets a ClientHelloID for the TLS connection.

The provided ClientHelloID is used to customize the TLS handshake. This should be a valid identifier that can be mapped to a specific ClientHelloSpec.

It returns a pointer to the Options struct for method chaining. This allows additional configuration methods to be called on the result.

Example usage: 

JA().SetHelloID(utls.HelloChrome_Auto)

func (*JA) SetHelloSpec 

func (j *JA) SetHelloSpec(spec utls.ClientHelloSpec) *Builder

SetHelloSpec sets a custom ClientHelloSpec for the TLS connection.

This method allows you to set a custom ClientHelloSpec to be used during the TLS handshake. The provided spec should be a valid ClientHelloSpec.

It returns a pointer to the Options struct for method chaining. This allows additional configuration methods to be called on the result.

Example usage: 

JA().SetHelloSpec(spec)

func (*JA) Tor 

func (j *JA) Tor() *Builder

Tor sets the JA3/4 fingerprint to mimic Tor Browser version 14.5.6.

func (*JA) TorPrivate 

func (j *JA) TorPrivate() *Builder

TorPrivate sets the JA3/4 fingerprint to mimic Tor Browser private version 14.5.6.

type Request 

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

Request represents an HTTP request with additional surf-specific functionality. It wraps the standard http.Request and provides enhanced features like middleware support, retry capabilities, remote address tracking, and structured error handling.

func (*Request) AddCookies 

func (req *Request) AddCookies(cookies ...*http.Cookie) *Request

AddCookies adds one or more HTTP cookies to the request. Cookies are added to the request headers and will be sent with the HTTP request. Returns the request for method chaining.

func (*Request) AddHeaders 

func (req *Request) AddHeaders(headers ...any) *Request

AddHeaders adds HTTP headers to the request, appending to any existing headers with the same name. Unlike SetHeaders, this method preserves existing headers and adds new values. Supports the same input formats as SetHeaders. Returns the request for method chaining.

func (*Request) Do 

func (req *Request) Do() g.Result[*Response]

Do executes the HTTP request and returns a Response wrapped in a Result type. This is the main method that performs the actual HTTP request with full surf functionality: - Applies request middleware (authentication, headers, tracing, etc.) - Preserves request body for potential retries - Implements retry logic with configurable status codes and delays - Measures request timing for performance analysis - Handles request preparation errors and write errors

func (*Request) GetRequest 

func (req *Request) GetRequest() *http.Request

GetRequest returns the underlying standard http.Request. Provides access to the wrapped HTTP request for advanced use cases.

func (*Request) SetHeaders 

func (req *Request) SetHeaders(headers ...any) *Request

SetHeaders sets HTTP headers for the request, replacing any existing headers with the same name. Supports multiple input formats: - Two arguments: key, value (string or g.String) - Single argument: http.Header, Headers, map types, or g.Map types Maintains header order for fingerprinting purposes when using g.MapOrd. Returns the request for method chaining.

func (*Request) WithContext 

func (req *Request) WithContext(ctx context.Context) *Request

WithContext associates a context with the request for cancellation and deadlines. The context can be used to cancel the request, set timeouts, or pass request-scoped values. Returns the request for method chaining. If ctx is nil, the request is unchanged.

type Response 

type Response struct {
	*Client // Embedded client provides access to all client functionality

	URL *url.URL // Final URL after following redirects

	Body *Body // Enhanced response body with compression support and caching

	Headers       Headers       // Response headers with convenience methods
	UserAgent     g.String      // User agent that was used for the request
	Proto         g.String      // HTTP protocol version (HTTP/1.1, HTTP/2, HTTP/3)
	Cookies       Cookies       // Response cookies with enhanced functionality
	Time          time.Duration // Total request duration including retries
	ContentLength int64         // Content-Length header value (-1 if not specified)
	StatusCode    StatusCode    // HTTP status code with convenience methods
	Attempts      int           // Number of retry attempts made for this request
	// contains filtered or unexported fields
}

Response represents an HTTP response with enhanced functionality and metadata. It wraps the standard http.Response and provides additional features like timing information, retry attempts tracking, enhanced cookie management, and convenient access methods.

func (Response) Debug 

func (resp Response) Debug() *Debug

Debug returns a debug instance associated with a Response.

func (Response) GetCookies 

func (resp Response) GetCookies(rawURL g.String) []*http.Cookie

GetCookies returns all cookies from the response that would be sent to the specified URL. Filters cookies based on domain, path, and security attributes.

func (Response) GetResponse 

func (resp Response) GetResponse() *http.Response

GetResponse returns the underlying standard http.Response. Provides access to the wrapped HTTP response for advanced use cases.

func (Response) Location 

func (resp Response) Location() g.String

Location returns the HTTP Location header value, typically used in redirects. Contains the URL that the client should redirect to for 3xx status codes.

func (Response) Referer 

func (resp Response) Referer() g.String

Referer returns the HTTP Referer header value from the original request. This indicates which page linked to the resource being requested.

func (Response) RemoteAddress 

func (resp Response) RemoteAddress() net.Addr

RemoteAddress returns the network address of the server that sent this response. Useful for logging, debugging, or connection analysis.

func (*Response) SetCookies 

func (resp *Response) SetCookies(rawURL g.String, cookies []*http.Cookie) error

SetCookies stores cookies in the client's cookie jar for the specified URL. This allows the cookies to be automatically sent with future requests to matching URLs.

func (Response) TLSGrabber 

func (resp Response) TLSGrabber() *TLSData

TLSGrabber extracts TLS connection information from the response. Returns detailed TLS connection data including certificates, cipher suites, and protocol version if the response was received over a TLS connection. Returns nil for non-TLS connections.

type StatusCode 

type StatusCode int

StatusCode represents an HTTP status code with convenient classification methods. Extends the basic integer status code with methods to easily identify the response category.

func (StatusCode) IsClientError 

func (s StatusCode) IsClientError() bool

IsClientError returns true if the status code indicates a client error [400, 500].

func (StatusCode) IsInformational 

func (s StatusCode) IsInformational() bool

IsInformational returns true if the status code is in the informational range [100, 200].

func (StatusCode) IsRedirection 

func (s StatusCode) IsRedirection() bool

IsRedirection returns true if the status code indicates a redirection [300, 400].

func (StatusCode) IsServerError 

func (s StatusCode) IsServerError() bool

IsServerError returns true if the status code indicates a server error [500, ∞].

func (StatusCode) IsSuccess 

func (s StatusCode) IsSuccess() bool

IsSuccess returns true if the status code indicates a successful response [200, 300].

func (StatusCode) Text 

func (s StatusCode) Text() string

Text returns the textual representation of the status code.

type TLSData 

type TLSData struct {
	ExtensionServerName      string   // Server name extension of the TLS certificate.
	FingerprintSHA256        string   // SHA-256 fingerprint of the certificate.
	FingerprintSHA256OpenSSL string   // SHA-256 fingerprint compatible with OpenSSL.
	TLSVersion               string   // TLS version used.
	CommonName               []string // List of common names associated with the certificate.
	DNSNames                 []string // List of DNS names associated with the certificate.
	Emails                   []string // List of email addresses associated with the certificate.
	IssuerCommonName         []string // List of common names of the certificate issuer.
	IssuerOrg                []string // List of organizations of the certificate issuer.
	Organization             []string // List of organizations associated with the certificate.
}

TLSData represents information about a TLS certificate.

type TransportAdapter 

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

TransportAdapter adapts surf.Client to net/http.RoundTripper It uses the full surf pipeline including middleware

func (*TransportAdapter) CloseIdleConnections 

func (s *TransportAdapter) CloseIdleConnections()

func (*TransportAdapter) RoundTrip 

func (s *TransportAdapter) RoundTrip(req *_http.Request) (*_http.Response, error)

RoundTrip implements net/http.RoundTripper interface using surf's full pipeline

Source Files

View all Source files

Directories

Path Synopsis
std command
internal
drainbody
specclone
Package specclone provides deep cloning functionality for uTLS ClientHelloSpec structures.
 Package specclone provides deep cloning functionality for uTLS ClientHelloSpec structures.
pkg
connectproxy
quicconn
Package quicconn provides a net.PacketConn adapter for feeding QUIC stacks (such as quic-go) with datagrams originating from a generic net.Conn.
 Package quicconn provides a net.PacketConn adapter for feeding QUIC stacks (such as quic-go) with datagrams originating from a generic net.Conn.
sse
profiles
chrome
firefox

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.