Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
S

surf

> 编程语言
Open source

SURF - Advanced Go HTTP client with Chrome/Firefox browser impersonation, HTTP/3 with QUIC fingerprinting, JA3/JA4 TLS emulation, and anti-bot bypass for web au

1.8K stars0 likes0 views
WebsiteGitHub

About

SURF - Advanced Go HTTP client with Chrome/Firefox browser impersonation, HTTP/3 with QUIC fingerprinting, JA3/JA4 TLS emulation, and anti-bot bypass for web au

Surf - Advanced HTTP Client for Go

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 v152 and Firefox v148 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

bash
go get -u github.com/enetx/surf

Required Go version: 1.27+

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.

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

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

JSON Response Handling

go
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

go
client := surf.NewClient().
    Builder().
    Impersonate().
    Chrome().        // Latest Chrome v152
    Build().
    Unwrap()

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

Firefox with Random OS

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

Platform-Specific Impersonation

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

go
// Automatic HTTP/3 with Chrome fingerprinting
client := surf.NewClient().
    Builder().
    Impersonate().Chrome().
    ForceHTTP3().    // 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

go
// Firefox with HTTP/3 fingerprinting
client := surf.NewClient().
    Builder().
    Impersonate().Firefox().
    ForceHTTP3().    // Auto-detects Firefox and applies Firefox HTTP/3 settings
    Build().
    Unwrap()

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

Manual HTTP/3 Configuration

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

HTTP/3 Compatibility & Fallbacks

HTTP/3 automatically handles compatibility issues:

…

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: ForceHTTP3() works regardless of call order

Advanced Configuration

Custom JA3 Fingerprint

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

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

HTTP/3 Configuration

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

Proxy Configuration

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

go
// HTTP/3 over SOCKS5 UDP proxy
client := surf.NewClient().
    Builder().
    Proxy("socks5://127.0.0.1:1080").
    Impersonate().Chrome().
    ForceHTTP3().  // 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
    ForceHTTP3().                   // HTTP/3 over SOCKS5
    Build().
    Unwrap()

Middleware System

Request Middleware

go
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

go
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

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

Request Types

POST with JSON

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

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

Form Data

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

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

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

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

File Upload

go
// Single file upload
mp := surf.NewMultipart().
    File("file", g.NewFile("/path/to/file.pdf"))

resp := surf.NewClient().
    Post("https://api.example.com/upload").
    Multipart(mp).
    Do()

// With additional form fields
mp := surf.NewMultipart().
    Field("description", "Important document").
    Field("category", "reports").
    File("file", g.NewFile("/path/to/file.pdf"))

resp := surf.NewClient().
    Post("https://api.example.com/upload").
    Multipart(mp).
    Do()

Multipart Form

…

Session Management

Persistent Sessions

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

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

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

Manual Cookie Management

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

go
resp := surf.NewClient().Get("ht

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Go

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集，为前端与全栈提供静态类型
P
Python
通用编程语言，广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言