surf

package module
v1.0.172 Latest Latest
Warning

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

 Go to latest Published: Jan 16, 2026 License: MIT Imports: 54 Imported by: 2

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 v144 and Firefox v147 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 fingerprinting
  • 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, SOCKS4 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/enetx/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().
    Unwrap()

// 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, HTTP/3 settings && 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/enetx/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 v144
    Build().
    Unwrap()

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 v147
    Build().
    Unwrap()

Platform-Specific Impersonation

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

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

🚀 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 HTTP/3 settings
    Build().
    Unwrap()

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 HTTP/3 settings
    Build().
    Unwrap()

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

Manual HTTP/3 Configuration

// Custom fingerprint settings
client := surf.NewClient().
    Builder().
    HTTP3Settings().Grease().Set().
    Build().
    Unwrap()

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
    HTTP3().                       // Will use HTTP/2 instead
    Build().
    Unwrap()

// 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
    HTTP3().                             // Will use HTTP/3 over SOCKS5
    Build().
    Unwrap()

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

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

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().
    Unwrap()


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

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

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

HTTP/2 Configuration

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

HTTP/3 Configuration

client := surf.NewClient().
    Builder().
	HTTP3Settings().
	QpackMaxTableCapacity(65536).
	MaxFieldSectionSize(262144).
	QpackBlockedStreams(100).
	H3Datagram(1).
	Grease().
	Set().
    Build().
    Unwrap()

Proxy Configuration

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

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().
    Unwrap()

// 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().
    Unwrap()

🔌 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().
    Unwrap()

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().
    Unwrap()

Client Middleware

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

📤 Request Types

POST with JSON

user := map[string]string{
    "name": "John Doe",
    "email": "[email protected]",
}

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().
    Unwrap()

// 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

// Create a reusable client
client := surf.NewClient().
    Builder().
    Impersonate().
    Chrome().
    Build().
    Unwrap()

// 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().
    Unwrap()

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().
    Unwrap()

🌐 Advanced Features

H2C (HTTP/2 Cleartext)

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

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().
    Unwrap()

Custom DNS Resolver

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

DNS-over-TLS

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

Unix Domain Sockets

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

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().
    Unwrap()

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 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
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

❤️ Support / Sponsorship

If you enjoy Surf and want to help keep development going, you can support the project with crypto donations:

USDT TON SOL BTC ETH

Thank you for your support!

📄 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.

Index

Constants

View Source 
const (
	SETTINGS_QPACK_MAX_TABLE_CAPACITY = 0x01
	SETTINGS_MAX_FIELD_SECTION_SIZE   = 0x06
	SETTINGS_QPACK_BLOCKED_STREAMS    = 0x07
	SETTINGS_ENABLE_CONNECT_PROTOCOL  = 0x08
	SETTINGS_H3_DATAGRAM              = 0x33
	H3_DATAGRAM                       = 0xFFD277
	SETTINGS_ENABLE_WEBTRANSPORT      = 0x2B603742
)

HTTP/3 SETTINGS frame parameter identifiers as defined in RFC 9114.

Variables

This section is empty.

Functions

This section is empty.

Types

type Body added in v1.0.51 

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 added in v1.0.51 

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

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

func (*Body) Close added in v1.0.51 

func (b *Body) Close() error

Close closes the body and returns any error encountered.

func (*Body) Contains added in v1.0.51 

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 added in v1.0.51 

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

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

func (*Body) JSON added in v1.0.51 

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

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

func (*Body) Limit added in v1.0.51 

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

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

func (*Body) MD5 added in v1.0.51 

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

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

func (*Body) SSE added in v1.0.53 

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 added in v1.0.51 

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

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

func (*Body) String added in v1.0.51 

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

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

func (*Body) UTF8 added in v1.0.51 

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 added in v1.0.51 

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

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

type Builder added in v1.0.100 

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 added in v1.0.100 

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

AddCookies adds cookies to the request.

func (*Builder) AddHeaders added in v1.0.100 

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 added in v1.0.100 

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

BasicAuth sets the basic authentication credentials for the client.

func (*Builder) BearerAuth added in v1.0.100 

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

BearerAuth sets the bearer token for the client.

func (*Builder) Boundary added in v1.0.100 

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

func (*Builder) Build added in v1.0.100 

func (b *Builder) Build() g.Result[*Client]

Build applies all configured settings and returns the client. Returns g.Result with error if any middleware fails.

func (*Builder) CacheBody added in v1.0.100 

func (b *Builder) CacheBody() *Builder

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

func (*Builder) ContentType added in v1.0.100 

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

ContentType sets the content type for the client.

func (*Builder) DNS added in v1.0.100 

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

DNS sets the custom DNS resolver address.

func (*Builder) DNSOverTLS added in v1.0.100 

func (b *Builder) DNSOverTLS() *DNSOverTLS

DNSOverTLS configures the client to use DNS over TLS.

func (*Builder) DisableCompression added in v1.0.100 

func (b *Builder) DisableCompression() *Builder

DisableCompression disables automatic response body decompression.

func (*Builder) DisableKeepAlive added in v1.0.100 

func (b *Builder) DisableKeepAlive() *Builder

DisableKeepAlive disable keep-alive connections.

func (*Builder) FollowOnlyHostRedirects added in v1.0.100 

func (b *Builder) FollowOnlyHostRedirects() *Builder

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

func (*Builder) ForceHTTP1 added in v1.0.100 

func (b *Builder) ForceHTTP1() *Builder

ForceHTTP1 configures the client to use HTTP/1.1 forcefully.

func (*Builder) ForceHTTP2 added in v1.0.147 

func (b *Builder) ForceHTTP2() *Builder

ForceHTTP2 configures the client to use HTTP/2 forcefully.

func (*Builder) ForceHTTP3 added in v1.0.154 

func (b *Builder) ForceHTTP3() *Builder

ForceHTTP3 configures the client to use HTTP/2 forcefully.

func (*Builder) ForwardHeadersOnRedirect added in v1.0.100 

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 added in v1.0.100 

func (b *Builder) GetRemoteAddress() *Builder

GetRemoteAddress configures whether the client should get the remote address.

func (*Builder) H2C added in v1.0.100 

func (b *Builder) H2C() *Builder

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

func (*Builder) HTTP2Settings added in v1.0.100 

func (b *Builder) HTTP2Settings() *HTTP2Settings

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

func (*Builder) HTTP3 added in v1.0.101 

func (b *Builder) HTTP3() *Builder

func (*Builder) HTTP3Settings added in v1.0.101 

func (b *Builder) HTTP3Settings() *HTTP3Settings

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

func (*Builder) Impersonate added in v1.0.100 

func (b *Builder) Impersonate() *Impersonate

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

func (*Builder) InterfaceAddr added in v1.0.100 

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

InterfaceAddr sets the local network interface for outbound connections. Accepts either an IP address (e.g., "192.168.1.100", "::1") or an interface name (e.g., "eth0", "en0").

func (*Builder) JA added in v1.0.100 

func (b *Builder) JA() *JA

JA configures the client to use a specific TLS fingerprint.

func (*Builder) MaxRedirects added in v1.0.100 

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

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

func (*Builder) NotFollowRedirects added in v1.0.100 

func (b *Builder) NotFollowRedirects() *Builder

NotFollowRedirects disables following redirects for the client.

func (*Builder) Proxy added in v1.0.100 

func (b *Builder) Proxy(proxy g.String) *Builder

Proxy sets the proxy URL for the client.

func (*Builder) RedirectPolicy added in v1.0.100 

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

RedirectPolicy sets a custom redirect policy for the client.

func (*Builder) Retry added in v1.0.100 

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 added in v1.0.100 

func (b *Builder) Session() *Builder

Session configures whether the client should maintain a session.

func (*Builder) SetHeaders added in v1.0.100 

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

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

func (Builder) String added in v1.0.100 

func (b Builder) String() string

String generate a string representation of the ClientBuilder instance.

func (*Builder) Timeout added in v1.0.100 

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

Timeout sets the timeout duration for the client.

func (*Builder) UnixSocket added in v1.0.137 

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 added in v1.0.100 

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

UserAgent sets the user agent for the client.

func (*Builder) With added in v1.0.100 

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 added in v1.0.100 

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 added in v1.0.50 

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) Close added in v1.0.170 

func (c *Client) Close() error

Close completely shuts down the client and releases all resources. After calling Close, the client should not be used.

func (*Client) CloseIdleConnections 

func (c *Client) CloseIdleConnections()

CloseIdleConnections closes idle connections while keeping the client usable. Safe to call periodically to free resources during long-running operations.

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 added in v1.0.100 

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 added in v1.0.100 

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 added in v1.0.100 

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 added in v1.0.100 

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 added in v1.0.51 

type Cookies []*http.Cookie

Cookies represents a list of HTTP Cookies.

func (*Cookies) Contains added in v1.0.51 

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 added in v1.0.100 

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

DNSOverTLS is a configuration struct for DNS over TLS settings.

func (*DNSOverTLS) AdGuard added in v1.0.100 

func (dot *DNSOverTLS) AdGuard() *Builder

AdGuard sets up DNS over TLS with AdGuard DNS.

func (*DNSOverTLS) AddProvider added in v1.0.100 

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 added in v1.0.100 

func (dot *DNSOverTLS) Ali() *Builder

Ali sets up DNS over TLS with AliDNS.

func (*DNSOverTLS) CIRAShield added in v1.0.100 

func (dot *DNSOverTLS) CIRAShield() *Builder

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

func (*DNSOverTLS) Cloudflare added in v1.0.100 

func (dot *DNSOverTLS) Cloudflare() *Builder

Cloudflare sets up DNS over TLS with Cloudflare DNS.

func (*DNSOverTLS) Forge added in v1.0.100 

func (dot *DNSOverTLS) Forge() *Builder

Forge sets up DNS over TLS with DNS Forge.

func (*DNSOverTLS) Google added in v1.0.100 

func (dot *DNSOverTLS) Google() *Builder

Google sets up DNS over TLS with Google Public DNS.

func (*DNSOverTLS) LibreDNS added in v1.0.100 

func (dot *DNSOverTLS) LibreDNS() *Builder

LibreDNS sets up DNS over TLS with LibreDNS.

func (*DNSOverTLS) Quad101 added in v1.0.100 

func (dot *DNSOverTLS) Quad101() *Builder

Quad101 sets up DNS over TLS with Quad101 DNS.

func (*DNSOverTLS) Quad9 added in v1.0.100 

func (dot *DNSOverTLS) Quad9() *Builder

Quad9 sets up DNS over TLS with Quad9 DNS.

func (*DNSOverTLS) SB added in v1.0.100 

func (dot *DNSOverTLS) SB() *Builder

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

func (*DNSOverTLS) Switch added in v1.0.100 

func (dot *DNSOverTLS) Switch() *Builder

Switch sets up DNS over TLS with SWITCH DNS.

type Debug added in v1.0.100 

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

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

func (*Debug) Print added in v1.0.100 

func (d *Debug) Print()

Print prints the debug information.

func (*Debug) Request added in v1.0.100 

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

Request appends the request details to the debug information.

func (*Debug) Response added in v1.0.100 

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

Response appends the response details to the debug information.

type Err101ResponseCode added in v1.0.100 

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 added in v1.0.100 

func (e *Err101ResponseCode) Error() string

type ErrUserAgentType added in v1.0.100 

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 added in v1.0.100 

func (e *ErrUserAgentType) Error() string

type ErrWebSocketUpgrade added in v1.0.100 

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 added in v1.0.100 

func (e *ErrWebSocketUpgrade) Error() string

type HTTP2Settings added in v1.0.100 

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 added in v1.0.100 

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

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

func (*HTTP2Settings) EnablePush added in v1.0.100 

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

EnablePush enables HTTP/2 server push functionality.

func (*HTTP2Settings) HeaderTableSize added in v1.0.100 

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

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

func (*HTTP2Settings) InitialStreamID added in v1.0.150 

func (h *HTTP2Settings) InitialStreamID(id uint32) *HTTP2Settings

InitialStreamID sets the initial stream id for HTTP/2 streams.

func (*HTTP2Settings) InitialWindowSize added in v1.0.100 

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

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

func (*HTTP2Settings) MaxConcurrentStreams added in v1.0.100 

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

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

func (*HTTP2Settings) MaxFrameSize added in v1.0.100 

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

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

func (*HTTP2Settings) MaxHeaderListSize added in v1.0.100 

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

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

func (*HTTP2Settings) NoRFC7540Priorities added in v1.0.166 

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

NoRFC7540Priorities disables RFC 7540 priority signaling in HTTP/2.

func (*HTTP2Settings) PriorityFrames added in v1.0.100 

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

PriorityFrames sets the priority frames for HTTP/2.

func (*HTTP2Settings) PriorityParam added in v1.0.100 

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

PriorityParam sets the priority parameter for HTTP/2.

func (*HTTP2Settings) Set added in v1.0.100 

func (h *HTTP2Settings) Set() *Builder

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

type HTTP3Settings added in v1.0.101 

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

HTTP3Settings provides a fluent interface for configuring HTTP/3 SETTINGS parameters. These settings are sent to the server during connection establishment.

func (*HTTP3Settings) EnableConnectProtocol added in v1.0.155 

func (h *HTTP3Settings) EnableConnectProtocol(num uint64) *HTTP3Settings

EnableConnectProtocol enables the extended CONNECT protocol (RFC 9220).

func (*HTTP3Settings) EnableWebtransport added in v1.0.155 

func (h *HTTP3Settings) EnableWebtransport(num uint64) *HTTP3Settings

EnableWebtransport enables WebTransport support over HTTP/3.

func (*HTTP3Settings) Grease added in v1.0.155 

func (h *HTTP3Settings) Grease() *HTTP3Settings

Grease adds a GREASE parameter with random ID and value to prevent protocol ossification.

func (*HTTP3Settings) H3Datagram added in v1.0.155 

func (h *HTTP3Settings) H3Datagram(num uint64) *HTTP3Settings

H3Datagram sets a custom H3_DATAGRAM value for datagram support.

func (*HTTP3Settings) MaxFieldSectionSize added in v1.0.155 

func (h *HTTP3Settings) MaxFieldSectionSize(num uint64) *HTTP3Settings

MaxFieldSectionSize sets the maximum size of a field section the peer is willing to accept.

func (*HTTP3Settings) QpackBlockedStreams added in v1.0.155 

func (h *HTTP3Settings) QpackBlockedStreams(num uint64) *HTTP3Settings

QpackBlockedStreams sets the maximum number of streams that can be blocked on QPACK.

func (*HTTP3Settings) QpackMaxTableCapacity added in v1.0.155 

func (h *HTTP3Settings) QpackMaxTableCapacity(num uint64) *HTTP3Settings

QpackMaxTableCapacity sets the maximum dynamic table capacity for QPACK.

func (*HTTP3Settings) Set added in v1.0.101 

func (h *HTTP3Settings) Set() *Builder

Set applies the configured HTTP/3 settings to the client's transport.

func (*HTTP3Settings) SettingsH3Datagram added in v1.0.155 

func (h *HTTP3Settings) SettingsH3Datagram(num uint64) *HTTP3Settings

SettingsH3Datagram sets the H3_DATAGRAM setting value.

type Headers added in v1.0.51 

type Headers http.Header

Headers represents a collection of HTTP Headers.

func (Headers) Clone added in v1.0.52 

func (h Headers) Clone() Headers

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

func (Headers) Contains added in v1.0.51 

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) Del added in v1.0.164 

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

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

func (Headers) Get added in v1.0.51 

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 added in v1.0.51 

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 added in v1.0.100 

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

func (*Impersonate) Android added in v1.0.100 

func (im *Impersonate) Android() *Impersonate

Android sets the OS to Android.

func (*Impersonate) Chrome added in v1.0.100 

func (im *Impersonate) Chrome() *Builder

Chrome impersonates Chrome browser v144.

func (*Impersonate) Firefox added in v1.0.156 

func (im *Impersonate) Firefox() *Builder

Firefox impersonates Firefox browser v147.

func (*Impersonate) FirefoxPrivate added in v1.0.156 

func (im *Impersonate) FirefoxPrivate() *Builder

FirefoxPrivate impersonates Firefox private browser v147.

func (*Impersonate) IOS added in v1.0.100 

func (im *Impersonate) IOS() *Impersonate

IOS sets the OS to iOS.

func (*Impersonate) Linux added in v1.0.100 

func (im *Impersonate) Linux() *Impersonate

Linux sets the OS to Linux.

func (*Impersonate) MacOS added in v1.0.100 

func (im *Impersonate) MacOS() *Impersonate

MacOS sets the OS to macOS.

func (*Impersonate) RandomOS added in v1.0.100 

func (im *Impersonate) RandomOS() *Impersonate

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

func (*Impersonate) Windows added in v1.0.100 

func (im *Impersonate) Windows() *Impersonate

Windows sets the OS to Windows.

type ImpersonateOS added in v1.0.100 

type ImpersonateOS int

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

type JA added in v1.0.100 

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 added in v1.0.100 

func (j *JA) Android() *Builder

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

func (*JA) Chrome added in v1.0.100 

func (j *JA) Chrome() *Builder

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

func (*JA) Chrome100 added in v1.0.100 

func (j *JA) Chrome100() *Builder

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

func (*JA) Chrome102 added in v1.0.100 

func (j *JA) Chrome102() *Builder

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

func (*JA) Chrome106 added in v1.0.100 

func (j *JA) Chrome106() *Builder

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

func (*JA) Chrome120 added in v1.0.100 

func (j *JA) Chrome120() *Builder

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

func (*JA) Chrome120PQ added in v1.0.100 

func (j *JA) Chrome120PQ() *Builder

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

func (*JA) Chrome144 added in v1.0.167 

func (j *JA) Chrome144() *Builder

Chrome144 sets the JA3/4 fingerprint to mimic Chrome version 144.

func (*JA) Chrome58 added in v1.0.100 

func (j *JA) Chrome58() *Builder

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

func (*JA) Chrome62 added in v1.0.100 

func (j *JA) Chrome62() *Builder

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

func (*JA) Chrome70 added in v1.0.100 

func (j *JA) Chrome70() *Builder

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

func (*JA) Chrome72 added in v1.0.100 

func (j *JA) Chrome72() *Builder

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

func (*JA) Chrome83 added in v1.0.100 

func (j *JA) Chrome83() *Builder

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

func (*JA) Chrome87 added in v1.0.100 

func (j *JA) Chrome87() *Builder

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

func (*JA) Chrome96 added in v1.0.100 

func (j *JA) Chrome96() *Builder

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

func (*JA) Edge added in v1.0.100 

func (j *JA) Edge() *Builder

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

func (*JA) Edge106 added in v1.0.100 

func (j *JA) Edge106() *Builder

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

func (*JA) Edge85 added in v1.0.100 

func (j *JA) Edge85() *Builder

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

func (*JA) Firefox added in v1.0.100 

func (j *JA) Firefox() *Builder

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

func (*JA) Firefox102 added in v1.0.100 

func (j *JA) Firefox102() *Builder

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

func (*JA) Firefox105 added in v1.0.100 

func (j *JA) Firefox105() *Builder

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

func (*JA) Firefox120 added in v1.0.100 

func (j *JA) Firefox120() *Builder

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

func (*JA) Firefox141 added in v1.0.122 

func (j *JA) Firefox141() *Builder

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

func (*JA) Firefox147 added in v1.0.167 

func (j *JA) Firefox147() *Builder

Firefox147 sets the JA3/4 fingerprint to mimic Firefox version 147.

func (*JA) Firefox55 added in v1.0.100 

func (j *JA) Firefox55() *Builder

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

func (*JA) Firefox56 added in v1.0.100 

func (j *JA) Firefox56() *Builder

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

func (*JA) Firefox63 added in v1.0.100 

func (j *JA) Firefox63() *Builder

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

func (*JA) Firefox65 added in v1.0.100 

func (j *JA) Firefox65() *Builder

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

func (*JA) Firefox99 added in v1.0.100 

func (j *JA) Firefox99() *Builder

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

func (*JA) FirefoxPrivate147 added in v1.0.167 

func (j *JA) FirefoxPrivate147() *Builder

FirefoxPrivate147 sets the JA3/4 fingerprint to mimic Firefox private version 147.

func (*JA) IOS added in v1.0.100 

func (j *JA) IOS() *Builder

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

func (*JA) IOS11 added in v1.0.100 

func (j *JA) IOS11() *Builder

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

func (*JA) IOS12 added in v1.0.100 

func (j *JA) IOS12() *Builder

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

func (*JA) IOS13 added in v1.0.100 

func (j *JA) IOS13() *Builder

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

func (*JA) IOS14 added in v1.0.100 

func (j *JA) IOS14() *Builder

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

func (*JA) Randomized added in v1.0.100 

func (j *JA) Randomized() *Builder

Randomized sets a completely randomized JA3/4 fingerprint.

func (*JA) RandomizedALPN added in v1.0.100 

func (j *JA) RandomizedALPN() *Builder

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

func (*JA) RandomizedNoALPN added in v1.0.100 

func (j *JA) RandomizedNoALPN() *Builder

RandomizedNoALPN sets a randomized JA3/4 fingerprint without ALPN.

func (*JA) Safari added in v1.0.100 

func (j *JA) Safari() *Builder

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

func (*JA) SetHelloID added in v1.0.100 

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 added in v1.0.100 

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)

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 {
	Headers   Headers  // Response headers with convenience methods
	Cookies   Cookies  // Response cookies with enhanced functionality
	UserAgent g.String // User agent that was used for the request
	Proto     g.String // HTTP protocol version (HTTP/1.1, HTTP/2, HTTP/3)

	*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

	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 added in v1.0.47 

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 added in v1.0.47 

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 added in v1.0.47 

func (s StatusCode) IsClientError() bool

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

func (StatusCode) IsInformational added in v1.0.47 

func (s StatusCode) IsInformational() bool

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

func (StatusCode) IsRedirection added in v1.0.47 

func (s StatusCode) IsRedirection() bool

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

func (StatusCode) IsServerError added in v1.0.47 

func (s StatusCode) IsServerError() bool

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

func (StatusCode) IsSuccess added in v1.0.47 

func (s StatusCode) IsSuccess() bool

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

func (StatusCode) Text added in v1.0.47 

func (s StatusCode) Text() string

Text returns the textual representation of the status code.

type TLSData added in v1.0.100 

type TLSData struct {
	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.
	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.
}

TLSData represents information about a TLS certificate.

type TransportAdapter added in v1.0.100 

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 added in v1.0.100 

func (s *TransportAdapter) CloseIdleConnections()

func (*TransportAdapter) RoundTrip added in v1.0.100 

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.
socks4
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.