surf

package module
v1.0.105 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2025 License: MIT Imports: 54 Imported by: 4

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 v131 and Firefox v131 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 browser-specific QUIC fingerprinting
  • JA4QUIC Fingerprinting: Advanced 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/enetx/surf

Required Go version: 1.25+

🔄 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/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 v131
    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 v131
    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 & QUIC Support

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

// Combine TLS fingerprinting with HTTP/3 QUIC fingerprinting
client := surf.NewClient().
    Builder().
    JA().Chrome131().               // TLS fingerprint (JA3/JA4)
    HTTP3Settings().Chrome().Set().  // 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:

  • ✅ QUIC Fingerprinting: 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 beyond basic JA3/JA4
  • ✅ 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()

// Available browser fingerprints:
// Chrome: Chrome(), Chrome58(), Chrome70(), Chrome83(), Chrome96(), Chrome100(), Chrome102(), Chrome106(), Chrome120(), Chrome131()
// Firefox: Firefox(), Firefox55(), Firefox63(), Firefox99(), Firefox102(), Firefox105(), Firefox120(), Firefox131()
// Edge: Edge(), Edge85(), Edge106()
// Safari: Safari()
// Mobile: IOS(), IOS11(), IOS12(), IOS13(), IOS14(), Android()

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

// SOCKS5H (hostname resolution via proxy)
client := surf.NewClient().
    Builder().
    Proxy("socks5h://proxy:1080").  // Hostname resolved by proxy
    HTTP3().
    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

formData := map[string]string{
    "username": "john",
    "password": "secret",
}

resp := surf.NewClient().
    Post("https://example.com/login", formData).
    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().
    UnixDomainSocket("/var/run/docker.sock").
    Build()

resp := client.Get("http://localhost/v1.24/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 powered by quic-go
  • QUIC fingerprinting using uQUIC
  • TLS fingerprinting powered by uTLS
  • Generic utilities from enetx/g

📞 Support

Made with ❤️ by the Surf contributors

Documentation

Index

Constants

This section is empty.

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 body content.
	// contains filtered or unexported fields
}

Body represents the content and properties of an HTTP response Body.

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

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
}

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() *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 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 compression for the HTTP client.

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

ForceHTTP1MW configures the client to use HTTP/1.1 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

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 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 network interface address for the client.

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 any) *Builder

Proxy sets the proxy settings 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) Singleton added in v1.0.100 

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

func (b *Builder) UnixDomainSocket(socketPath g.String) *Builder

UnixDomainSocket 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 adds middleware to the client. It accepts various types of middleware functions and adds them to the client builder.

Parameters:

  • middleware: The middleware function to add. It can be one of the following types: 1. func(*surf.Client): Client middleware function, which modifies the client itself. 2. func(*surf.Request) error: Request middleware function, which intercepts and potentially modifies outgoing requests. 3. func(*surf.Response) error: Response middleware function, which intercepts and potentially modifies incoming responses.
  • priority (optional): Priority of the middleware. Defaults to 0 if not provided.

If the provided middleware is of an unsupported type, With panics with an error message indicating the invalid middleware type.

Example usage: 

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

// 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 struct provides a customizable HTTP client.

func NewClient 

func NewClient() *Client

NewClient creates a new Client with default settings.

func (*Client) Builder added in v1.0.50 

func (c *Client) Builder() *Builder

Builder creates a new client builder instance with default values

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 DELETE request.

func (*Client) FileUpload 

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

FileUpload creates a new multipart file upload request.

func (*Client) Get 

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

Get creates a new GET request.

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 HEAD request.

func (*Client) IsHTTP3 added in v1.0.101 

func (c *Client) IsHTTP3() bool

IsHTTP3 returns true if the client is configured to use HTTP/3.

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.

func (*Client) Patch 

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

Patch creates a new PATCH request.

func (*Client) Post 

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

Post creates a new POST request.

func (*Client) Put 

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

Put creates a new PUT request.

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

func (dot *DNSOverTLS) Quad9() *Builder

Quad9 sets up DNS over TLS with Quad9 DNS.

func (*DNSOverTLS) Quad101 added in v1.0.100 

func (dot *DNSOverTLS) Quad101() *Builder

Quad101 sets up DNS over TLS with Quad101 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 }

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 }

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 }

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) 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) 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 represents HTTP/3 settings with uQUIC fingerprinting support. https://github.com/refraction-networking/uquic

func (*HTTP3Settings) Chrome added in v1.0.101 

func (h *HTTP3Settings) Chrome() *HTTP3Settings

Chrome configures HTTP/3 settings to mimic Chrome browser.

func (*HTTP3Settings) Firefox added in v1.0.101 

func (h *HTTP3Settings) Firefox() *HTTP3Settings

Firefox configures HTTP/3 settings to mimic Firefox browser.

func (*HTTP3Settings) Set added in v1.0.101 

func (h *HTTP3Settings) Set() *Builder

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

func (*HTTP3Settings) SetQUICID added in v1.0.101 

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

SetQUICID sets a custom QUIC ID for fingerprinting.

func (*HTTP3Settings) SetQUICSpec added in v1.0.101 

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

SetQUICSpec sets a custom QUIC spec for advanced fingerprinting.

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) 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 v.131.

func (*Impersonate) FireFox added in v1.0.100 

func (im *Impersonate) FireFox() *Builder

Firefox impersonates Firefox browser v.131.

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
}

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

func (*JA) Android added in v1.0.100 

func (j *JA) Android() *Builder

func (*JA) Chrome added in v1.0.100 

func (j *JA) Chrome() *Builder

func (*JA) Chrome58 added in v1.0.100 

func (j *JA) Chrome58() *Builder

func (*JA) Chrome62 added in v1.0.100 

func (j *JA) Chrome62() *Builder

func (*JA) Chrome70 added in v1.0.100 

func (j *JA) Chrome70() *Builder

func (*JA) Chrome72 added in v1.0.100 

func (j *JA) Chrome72() *Builder

func (*JA) Chrome83 added in v1.0.100 

func (j *JA) Chrome83() *Builder

func (*JA) Chrome87 added in v1.0.100 

func (j *JA) Chrome87() *Builder

func (*JA) Chrome96 added in v1.0.100 

func (j *JA) Chrome96() *Builder

func (*JA) Chrome100 added in v1.0.100 

func (j *JA) Chrome100() *Builder

func (*JA) Chrome102 added in v1.0.100 

func (j *JA) Chrome102() *Builder

func (*JA) Chrome106 added in v1.0.100 

func (j *JA) Chrome106() *Builder

func (*JA) Chrome120 added in v1.0.100 

func (j *JA) Chrome120() *Builder

func (*JA) Chrome120PQ added in v1.0.100 

func (j *JA) Chrome120PQ() *Builder

func (*JA) Chrome131 added in v1.0.100 

func (j *JA) Chrome131() *Builder

func (*JA) Edge added in v1.0.100 

func (j *JA) Edge() *Builder

func (*JA) Edge85 added in v1.0.100 

func (j *JA) Edge85() *Builder

func (*JA) Edge106 added in v1.0.100 

func (j *JA) Edge106() *Builder

func (*JA) Firefox added in v1.0.100 

func (j *JA) Firefox() *Builder

func (*JA) Firefox55 added in v1.0.100 

func (j *JA) Firefox55() *Builder

func (*JA) Firefox56 added in v1.0.100 

func (j *JA) Firefox56() *Builder

func (*JA) Firefox63 added in v1.0.100 

func (j *JA) Firefox63() *Builder

func (*JA) Firefox65 added in v1.0.100 

func (j *JA) Firefox65() *Builder

func (*JA) Firefox99 added in v1.0.100 

func (j *JA) Firefox99() *Builder

func (*JA) Firefox102 added in v1.0.100 

func (j *JA) Firefox102() *Builder

func (*JA) Firefox105 added in v1.0.100 

func (j *JA) Firefox105() *Builder

func (*JA) Firefox120 added in v1.0.100 

func (j *JA) Firefox120() *Builder

func (*JA) Firefox131 added in v1.0.100 

func (j *JA) Firefox131() *Builder

func (*JA) IOS added in v1.0.100 

func (j *JA) IOS() *Builder

func (*JA) IOS11 added in v1.0.100 

func (j *JA) IOS11() *Builder

func (*JA) IOS12 added in v1.0.100 

func (j *JA) IOS12() *Builder

func (*JA) IOS13 added in v1.0.100 

func (j *JA) IOS13() *Builder

func (*JA) IOS14 added in v1.0.100 

func (j *JA) IOS14() *Builder

func (*JA) Randomized added in v1.0.100 

func (j *JA) Randomized() *Builder

func (*JA) RandomizedALPN added in v1.0.100 

func (j *JA) RandomizedALPN() *Builder

func (*JA) RandomizedNoALPN added in v1.0.100 

func (j *JA) RandomizedNoALPN() *Builder

func (*JA) Safari added in v1.0.100 

func (j *JA) Safari() *Builder

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 is a struct that holds information about an HTTP request.

func (*Request) AddCookies 

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

AddCookies adds cookies to the request.

func (*Request) AddHeaders 

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

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

func (*Request) Do 

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

Do performs the HTTP request and returns a Response object or an error if the request failed.

func (*Request) GetRequest 

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

GetRequest returns the underlying http.Request of the custom request.

func (*Request) SetHeaders 

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

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

func (*Request) WithContext 

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

WithContext associates the provided context with the request.

type Response 

type Response struct {
	*Client // Client is the associated client for the response.

	URL *url.URL // URL of the response.

	Body *Body // Response body.

	Headers       Headers       // Response headers.
	UserAgent     g.String      // User agent string.
	Proto         g.String      // HTTP protocol version.
	Cookies       Cookies       // Response cookies.
	Time          time.Duration // Total time taken for the response.
	ContentLength int64         // Length of the response content.
	StatusCode    StatusCode    // HTTP status code.
	Attempts      int           // Number of attempts made.
	// contains filtered or unexported fields
}

Response represents a custom response structure.

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 the cookies from the response for the given URL.

func (Response) GetResponse 

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

GetResponse returns the underlying http.Response of the custom response.

func (Response) Location added in v1.0.47 

func (resp Response) Location() g.String

Location returns the location of the response.

func (Response) Referer 

func (resp Response) Referer() g.String

Referer returns the referer of the response.

func (Response) RemoteAddress 

func (resp Response) RemoteAddress() net.Addr

RemoteAddress returns the remote address of the response.

func (*Response) SetCookies 

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

SetCookies sets cookies for the given URL in the response.

func (Response) TLSGrabber 

func (resp Response) TLSGrabber() *TLSData

TLSGrabber returns a tlsData struct containing information about the TLS connection if it exists.

type StatusCode added in v1.0.47 

type StatusCode int

StatusCode represents an HTTP status code.

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

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.