Surf

https://pkg.go.dev/github.com/enetx/surf
Admin
Surf is a powerful HTTP client library for Go that provides browser impersonation, JA3/JA4...
Tokens:57,066
Snippets:722
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install surf Package

Source: https://pkg.go.dev/github.com/enetx/surf

Install the surf package using go get. Requires Go version 1.25+.

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

```

--------------------------------

### Enable DNS-over-TLS (DoT)

Source: https://pkg.go.dev/github.com/enetx/surf

Secure DNS lookups with DNS-over-TLS by using the `DNSOverTLS()` option. This example configures Cloudflare's DoT service.

```go
client := surf.NewClient().
    Builder().
    DNSOverTLS().Cloudflare().  // Cloudflare DoT
    Build().
    Unwrap()


```

--------------------------------

### Create HTTP GET Request

Source: https://pkg.go.dev/github.com/enetx/surf

Use Get to create a new HTTP GET request for retrieving data from a server.

```go
func (c *Client) Get(rawURL g.String) *Request
```

--------------------------------

### Configure Custom DNS Resolver

Source: https://pkg.go.dev/github.com/enetx/surf

Specify a custom DNS resolver using the `DNS(address)` option in the client builder. This example configures the client to use Google DNS at `8.8.8.8:53`.

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


```

--------------------------------

### Add Client Middleware

Source: https://pkg.go.dev/github.com/enetx/surf

Apply client-level middleware to modify the client's configuration. This example demonstrates setting the client's timeout. Middleware functions for the client receive a pointer to the client object.

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

--------------------------------

### File Upload with Form Fields

Source: https://pkg.go.dev/github.com/enetx/surf

Perform a file upload as part of a multipart request. This example shows how to upload a single file and include additional form fields to provide context or metadata for the 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()
```

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

--------------------------------

### Add Response Middleware

Source: https://pkg.go.dev/github.com/enetx/surf

Implement response middleware to process incoming responses. This example logs the response status code and processing time. The middleware function receives the response object and should return an error if any issues occur.

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

--------------------------------

### Basic GET Request with surf

Source: https://pkg.go.dev/github.com/enetx/surf

Perform a basic GET request to a specified URL using surf. Handles potential errors and prints the response body.

```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())
}

```

--------------------------------

### Configure Automatic Retries

Source: https://pkg.go.dev/github.com/enetx/surf

Implement automatic retries for failed requests by configuring the client builder with `Retry(maxRetries, waitDuration)`. This example sets up a maximum of 3 retries with a 2-second wait between attempts.

```go
client := surf.NewClient().
    Builder().
    Retry(3, 2*time.Second).           // Max 3 retries, 2 second wait
    Build().
    Unwrap()

```

--------------------------------

### Impersonate Chrome with Automatic HTTP/3 Detection

Source: https://pkg.go.dev/github.com/enetx/surf

Configure the client to impersonate Chrome and automatically detect and apply appropriate HTTP/3 settings. This example also shows how to retrieve the protocol used.

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

--------------------------------

### File Upload

Source: https://pkg.go.dev/github.com/enetx/surf

Provides examples for uploading single files and files with additional form fields.

```APIDOC
## 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()
```
```

--------------------------------

### Get All Header Values

Source: https://pkg.go.dev/github.com/enetx/surf

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

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

--------------------------------

### Client.Get

Source: https://pkg.go.dev/github.com/enetx/surf

Creates a new HTTP GET request for the specified URL. GET requests are used to retrieve data from a server.

```APIDOC
## Get

### Description
Creates a new HTTP GET request for the specified URL. GET requests are used to retrieve data from a server.

### Method
GET

### Endpoint
/{rawURL}

### Parameters
#### Path Parameters
- **rawURL** (string) - Required - The URL to retrieve data from.

### Response
#### Success Response (200)
- **Request** (*Request) - A Request object representing the GET request.

### Response Example
```json
{
  "request": "..."
}
```
```

--------------------------------

### Get Header Value

Source: https://pkg.go.dev/github.com/enetx/surf

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

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

--------------------------------

### Get Standard net/http.Client

Source: https://pkg.go.dev/github.com/enetx/surf

Std returns a standard net/http.Client that wraps the configured surf client, preserving features like JA3 fingerprinting, HTTP/2, sessions, middleware, and headers. Known limitations include no retry logic, response body caching, or remote address tracking.

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

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

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

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

--------------------------------

### Client.Head

Source: https://pkg.go.dev/github.com/enetx/surf

Creates a new HTTP HEAD request for the specified URL. HEAD requests are identical to GET but without the response body.

```APIDOC
## Head

### Description
Creates a new HTTP HEAD request for the specified URL. HEAD requests are identical to GET but without the response body.

### Method
HEAD

### Endpoint
/{rawURL}

### Parameters
#### Path Parameters
- **rawURL** (string) - Required - The URL for the HEAD request.

### Response
#### Success Response (200)
- **Request** (*Request) - A Request object representing the HEAD request.

### Response Example
```json
{
  "request": "..."
}
```
```

--------------------------------

### Create HTTP HEAD Request

Source: https://pkg.go.dev/github.com/enetx/surf

Use Head to create a new HTTP HEAD request, which is similar to GET but without the response body.

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

--------------------------------

### Get Client Builder

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func (c *Client) Builder() *Builder
```

--------------------------------

### Get Response Body as String

Source: https://pkg.go.dev/github.com/enetx/surf

Retrieves the entire response body content as a g.String. This is a convenient way to access text-based responses.

```go
func (b *Body) String() g.Result[g.String]
```

--------------------------------

### Add Request Middleware

Source: https://pkg.go.dev/github.com/enetx/surf

Implement request middleware to modify outgoing requests before they are sent. This example adds a custom header and logs the request URL. Ensure the middleware function returns an error if processing fails.

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

--------------------------------

### Build Surf Client

Source: https://pkg.go.dev/github.com/enetx/surf

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

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

--------------------------------

### Stream Large HTTP Responses

Source: https://pkg.go.dev/github.com/enetx/surf

For large responses, use `resp.Ok().Body.Stream()` to get an `io.ReadCloser`. This allows you to process the response in chunks, for example, by using a `bufio.Scanner`.

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

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

--------------------------------

### Client Initialization

Source: https://pkg.go.dev/github.com/enetx/surf

Creates a new Surf HTTP client with default configurations.

```APIDOC
## NewClient()

### Description
Creates a new HTTP client with defaults.

### Method
`NewClient()`
```

--------------------------------

### Build

Source: https://pkg.go.dev/github.com/enetx/surf

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

```APIDOC
## Build

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

### Signature
```go
func (b *Builder) Build() g.Result[*Client]
```
```

--------------------------------

### Get Remote Address

Source: https://pkg.go.dev/github.com/enetx/surf

Configures whether the client should get the remote address.

```go
func (b *Builder) GetRemoteAddress() *Builder
```

--------------------------------

### With

Source: https://pkg.go.dev/github.com/enetx/surf

Registers middleware into the client builder with optional priority. It accepts client, request, or response middleware functions.

```APIDOC
## With

### Description
Registers middleware into the client builder with optional priority. It accepts client, request, or response middleware functions.

### Method
`*Builder.With(middleware any, priority ...int)`

### Parameters
- **middleware** (any) - A function matching one of the supported middleware types: `func(*surf.Client) error`, `func(*surf.Request) error`, or `func(*surf.Response) error`.
- **priority** (...int) - Optional integer priority level. Lower values run earlier. Defaults to 0.

### Response
Returns a `*Builder` instance for method chaining.

### Example
```go
// 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.
```

--------------------------------

### HTTP/3 Advanced Configuration

Source: https://pkg.go.dev/github.com/enetx/surf

Configure advanced HTTP/3 settings including QPACK settings, Max Field Section Size, H3 Datagram, and GREASE.

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

--------------------------------

### Set Impersonate to Linux

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the OS to Linux for client impersonation.

```go
func (im *Impersonate) Linux() *Impersonate
```

--------------------------------

### GetRemoteAddress

Source: https://pkg.go.dev/github.com/enetx/surf

GetRemoteAddress configures whether the client should get the remote address.

```APIDOC
## GetRemoteAddress

### Description
GetRemoteAddress configures whether the client should get the remote address.

### Signature
```go
func (b *Builder) GetRemoteAddress() *Builder
```
```

--------------------------------

### Get Textual Representation of Status Code

Source: https://pkg.go.dev/github.com/enetx/surf

Text returns the textual representation of the status code.

```go
func (s StatusCode) Text() string
```

--------------------------------

### Set Impersonate to Windows

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the OS to Windows for client impersonation.

```go
func (im *Impersonate) Windows() *Impersonate
```

--------------------------------

### Configure Connection Reuse for Performance

Source: https://pkg.go.dev/github.com/enetx/surf

Improve performance by reusing HTTP connections. Create a client with `surf.NewClient().Builder().Impersonate().Chrome().Build().Unwrap()` and use it for multiple requests. Remember to close idle connections when done.

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

--------------------------------

### Get Boundary String

Source: https://pkg.go.dev/github.com/enetx/surf/profiles/firefox

Returns a string representing the boundary. This function is part of the Firefox implementation.

```go
func Boundary() g.String
```

--------------------------------

### Get Remote Server Address

Source: https://pkg.go.dev/github.com/enetx/surf

Returns the network address of the server that sent this response, useful for logging and debugging.

```go
func (resp Response) RemoteAddress() net.Addr
```

--------------------------------

### Get Referer Header

Source: https://pkg.go.dev/github.com/enetx/surf

Returns the HTTP Referer header value from the original request, indicating the referring page.

```go
func (resp Response) Referer() g.String
```

--------------------------------

### Get Redirect Location

Source: https://pkg.go.dev/github.com/enetx/surf

Returns the HTTP Location header value, typically used in redirects for 3xx status codes.

```go
func (resp Response) Location() g.String
```

--------------------------------

### Create HTTP OPTIONS Request

Source: https://pkg.go.dev/github.com/enetx/surf

Use Options to create a new HTTP OPTIONS request for describing communication options for a resource.

```go
func (c *Client) Options(rawURL g.String) *Request
```

--------------------------------

### Create New Surf Client

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func NewClient() *Client
```

--------------------------------

### Headers.Get

Source: https://pkg.go.dev/github.com/enetx/surf

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

```APIDOC
## Headers.Get

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

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

### Parameters
#### Path Parameters
- **key** (g.String) - Required - The header key to retrieve.
```

--------------------------------

### DNSOverTLS.Ali

Source: https://pkg.go.dev/github.com/enetx/surf

Ali sets up DNS over TLS with AliDNS.

```APIDOC
## DNSOverTLS.Ali

### Description
Ali sets up DNS over TLS with AliDNS.

### Method
func (*DNSOverTLS) Ali() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Body.String()

Source: https://pkg.go.dev/github.com/enetx/surf

String returns the body's content as a g.String. This is a convenient way to get the entire response body as a string.

```APIDOC
## String()

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

### Returns

- g.Result[g.String] - The body's content as a g.String.
```

--------------------------------

### Get Response Cookies

Source: https://pkg.go.dev/github.com/enetx/surf

Returns all cookies from the response that would be sent to the specified URL, filtering by domain, path, and security attributes.

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

--------------------------------

### Set Basic Authentication for Client

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the basic authentication credentials for the HTTP client. The credentials should be provided as a base64 encoded string.

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

--------------------------------

### Enable HTTP/2 Cleartext (H2C)

Source: https://pkg.go.dev/github.com/enetx/surf

Use HTTP/2 without TLS by enabling H2C with `surf.NewClient().Builder().H2C().Build().Unwrap()`. This is useful for local development or internal services where TLS is not required.

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

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

```

--------------------------------

### HTTP/2 Advanced Configuration

Source: https://pkg.go.dev/github.com/enetx/surf

Configure advanced HTTP/2 settings such as Header Table Size, Enable Push, Initial Window Size, Max Header List Size, and Connection Flow control.

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

--------------------------------

### HTTP/3 Compatibility with Proxies and DNS

Source: https://pkg.go.dev/github.com/enetx/surf

Demonstrates HTTP/3 compatibility and automatic fallbacks with various network configurations, including HTTP proxies, SOCKS5 proxies, and custom DNS settings (including DNS-over-TLS).

```go
// With HTTP proxy - automatically falls back to HTTP/2
client := surf.NewClient().
    Builder().
    Proxy("http://proxy:8080").    // HTTP proxies incompatible with HTTP/3
    ForceHTTP3().                  // 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
    ForceHTTP3().                        // 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
    ForceHTTP3().
    Build().
    Unwrap()

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

--------------------------------

### Client Middleware

Source: https://pkg.go.dev/github.com/enetx/surf

Explains how to apply middleware to modify the client's configuration before it's built.

```APIDOC
## 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()
```
```

--------------------------------

### Manual HTTP/3 Configuration

Source: https://pkg.go.dev/github.com/enetx/surf

Manually configure custom HTTP/3 fingerprint settings, including GREASE (Generate Random And Substitute Existing) for enhanced evasion.

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

--------------------------------

### Set Impersonate to Android

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the OS to Android for client impersonation.

```go
func (im *Impersonate) Android() *Impersonate
```

--------------------------------

### Get Buffered Reader for Streaming Body

Source: https://pkg.go.dev/github.com/enetx/surf

Provides a bufio.Reader for streaming the response body content. It's crucial to call this method only once and reuse the returned reader.

```go
func (b *Body) Stream() *StreamReader
```

--------------------------------

### Get Response Body as Byte Slice

Source: https://pkg.go.dev/github.com/enetx/surf

Retrieves the entire response body content as a byte slice. Use this when the entire body needs to be processed in memory.

```go
func (b *Body) Bytes() g.Result[g.Bytes]
```

--------------------------------

### Configure HTTP/3 Settings

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func (b *Builder) HTTP3Settings() *HTTP3Settings
```

--------------------------------

### Body.WithContext()

Source: https://pkg.go.dev/github.com/enetx/surf

WithContext sets the context for cancellation of read operations. Must be called BEFORE reading the body (Bytes(), String(), Stream(), etc.). Silently ignored if reading has already started.

```APIDOC
## WithContext(ctx context.Context)

WithContext sets the context for cancellation of read operations. Must be called BEFORE reading the body (Bytes(), String(), Stream(), etc.). Silently ignored if reading has already started.

### Parameters

- **ctx** (context.Context) - The context to associate with the body operations.

### Returns

- *Body - A pointer to the Body object with the context set.
```

--------------------------------

### Set Impersonate to iOS

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the OS to iOS for client impersonation.

```go
func (im *Impersonate) IOS() *Impersonate
```

--------------------------------

### DNSOverTLS.LibreDNS

Source: https://pkg.go.dev/github.com/enetx/surf

LibreDNS sets up DNS over TLS with LibreDNS.

```APIDOC
## DNSOverTLS.LibreDNS

### Description
LibreDNS sets up DNS over TLS with LibreDNS.

### Method
func (*DNSOverTLS) LibreDNS() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### NewClient

Source: https://pkg.go.dev/github.com/enetx/surf

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

```APIDOC
## NewClient

### Description
Creates a new Client with sensible default settings including default dialer, TLS configuration, HTTP transport, and basic middleware.

### Method
`NewClient()`

### Parameters
None

### Response
Returns a pointer to a new `Client` instance.
```

--------------------------------

### Set Impersonate to macOS

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the OS to macOS for client impersonation.

```go
func (im *Impersonate) MacOS() *Impersonate
```

--------------------------------

### DNSOverTLS.Quad101

Source: https://pkg.go.dev/github.com/enetx/surf

Quad101 sets up DNS over TLS with Quad101 DNS.

```APIDOC
## DNSOverTLS.Quad101

### Description
Quad101 sets up DNS over TLS with Quad101 DNS.

### Method
func (*DNSOverTLS) Quad101() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Create a new QuicPacketConn adapter

Source: https://pkg.go.dev/github.com/enetx/surf/pkg/quicconn

New creates a new QuicPacketConn adapter around a connected transport. The defaultTarget is crucial for EncapRaw mode and serves as a fallback for EncapSocks5. The returned value implements net.PacketConn and can be passed to QUIC dialers.

```go
func New(conn net.Conn, defaultTarget *net.UDPAddr, mode EncapMode) *QuicPacketConn
```

--------------------------------

### Client Configuration - Builder

Source: https://pkg.go.dev/github.com/enetx/surf

Methods for configuring the client using a builder pattern.

```APIDOC
## Builder()

### Description
Returns a new Builder for client configuration.

### Method
`Builder()`
```

```APIDOC
## Impersonate()

### Description
Enable browser impersonation.

### Method
`Impersonate()`
```

```APIDOC
## JA()

### Description
Configure JA3/JA4 fingerprinting.

### Method
`JA()`
```

```APIDOC
## HTTP2Settings()

### Description
Configure HTTP/2 parameters.

### Method
`HTTP2Settings()`
```

```APIDOC
## HTTP3Settings()

### Description
Configure HTTP/3 parameters.

### Method
`HTTP3Settings()`
```

```APIDOC
## H2C()

### Description
Enable HTTP/2 cleartext.

### Method
`H2C()`
```

```APIDOC
## Proxy(proxy)

### Description
Set proxy configuration.

### Method
`Proxy(proxy)`

### Parameters
#### Path Parameters
- **proxy** (string) - Required - The proxy configuration.
```

```APIDOC
## DNS(dns)

### Description
Set custom DNS resolver.

### Method
`DNS(dns)`

### Parameters
#### Path Parameters
- **dns** (string) - Required - The custom DNS resolver.
```

```APIDOC
## DNSOverTLS()

### Description
Configure DNS-over-TLS.

### Method
`DNSOverTLS()`
```

```APIDOC
## Session()

### Description
Enable cookie jar for sessions.

### Method
`Session()`
```

```APIDOC
## Timeout(duration)

### Description
Set request timeout.

### Method
`Timeout(duration)`

### Parameters
#### Path Parameters
- **duration** (time.Duration) - Required - The timeout duration.
```

```APIDOC
## MaxRedirects(n)

### Description
Set maximum redirects.

### Method
`MaxRedirects(n)`

### Parameters
#### Path Parameters
- **n** (int) - Required - The maximum number of redirects.
```

```APIDOC
## NotFollowRedirects()

### Description
Disable redirect following.

### Method
`NotFollowRedirects()`
```

```APIDOC
## FollowOnlyHostRedirects()

### Description
Only follow same-host redirects.

### Method
`FollowOnlyHostRedirects()`
```

```APIDOC
## ForwardHeadersOnRedirect()

### Description
Forward headers on redirects.

### Method
`ForwardHeadersOnRedirect()`
```

```APIDOC
## RedirectPolicy(fn)

### Description
Custom redirect policy function.

### Method
`RedirectPolicy(fn)`

### Parameters
#### Path Parameters
- **fn** (func) - Required - The custom redirect policy function.
```

```APIDOC
## Retry(max, wait, codes...)

### Description
Configure retry logic.

### Method
`Retry(max, wait, codes...)`

### Parameters
#### Path Parameters
- **max** (int) - Required - Maximum number of retries.
- **wait** (time.Duration) - Required - Wait duration between retries.
- **codes** (...int) - Required - HTTP status codes to retry on.
```

```APIDOC
## CacheBody()

### Description
Enable response body caching.

### Method
`CacheBody()`
```

```APIDOC
## With(middleware, priority...)

### Description
Add middleware.

### Method
`With(middleware, priority...)`

### Parameters
#### Path Parameters
- **middleware** (interface{}) - Required - The middleware to add.
- **priority** (...int) - Optional - Priority for the middleware.
```

```APIDOC
## BasicAuth(auth)

### Description
Set basic authentication.

### Method
`BasicAuth(auth)`

### Parameters
#### Path Parameters
- **auth** (string) - Required - Basic authentication string.
```

```APIDOC
## BearerAuth(token)

### Description
Set bearer token authentication.

### Method
`BearerAuth(token)`

### Parameters
#### Path Parameters
- **token** (string) - Required - Bearer token.
```

```APIDOC
## UserAgent(ua)

### Description
Set custom user agent.

### Method
`UserAgent(ua)`

### Parameters
#### Path Parameters
- **ua** (string) - Required - The user agent string.
```

```APIDOC
## SetHeaders(headers...)

### Description
Set request headers.

### Method
`SetHeaders(headers...)`

### Parameters
#### Path Parameters
- **headers** (...string) - Required - Key-value pairs of headers.
```

```APIDOC
## AddHeaders(headers...)

### Description
Add request headers.

### Method
`AddHeaders(headers...)`

### Parameters
#### Path Parameters
- **headers** (...string) - Required - Key-value pairs of headers to add.
```

```APIDOC
## AddCookies(cookies...)

### Description
Add cookies to the request.

### Method
`AddCookies(cookies...)`

### Parameters
#### Path Parameters
- **cookies** (...http.Cookie) - Required - Cookies to add.
```

```APIDOC
## WithContext(ctx)

### Description
Add context to the client configuration.

### Method
`WithContext(ctx)`

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - The context to add.
```

```APIDOC
## ContentType(type)

### Description
Set content type.

### Method
`ContentType(type)`

### Parameters
#### Path Parameters
- **type** (string) - Required - The content type.
```

```APIDOC
## GetRemoteAddress()

### Description
Track remote address.

### Method
`GetRemoteAddress()`
```

```APIDOC
## DisableKeepAlive()

### Description
Disable keep-alive connections.

### Method
`DisableKeepAlive()`
```

```APIDOC
## DisableCompression()

### Description
Disable response compression.

### Method
`DisableCompression()`
```

```APIDOC
## ForceHTTP1()

### Description
Force the use of HTTP/1.1.

### Method
`ForceHTTP1()`
```

```APIDOC
## ForceHTTP2()

### Description
Force the use of HTTP/2.

### Method
`ForceHTTP2()`
```

```APIDOC
## ForceHTTP3()

### Description
Force the use of HTTP/3.

### Method
`ForceHTTP3()`
```

```APIDOC
## UnixSocket(path)

### Description
Use a Unix domain socket for communication.

### Method
`UnixSocket(path)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the Unix socket.
```

```APIDOC
## InterfaceAddr(addr)

### Description
Bind the client to a specific network interface address.

### Method
`InterfaceAddr(addr)`

### Parameters
#### Path Parameters
- **addr** (string) - Required - The network interface address.
```

```APIDOC
## Boundary(fn)

### Description
Set a custom multipart boundary generator function.

### Method
`Boundary(fn)`

### Parameters
#### Path Parameters
- **fn** (func() string) - Required - The function to generate the boundary.
```

--------------------------------

### Configure HTTP/2 Settings

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func (b *Builder) HTTP2Settings() *HTTP2Settings
```

--------------------------------

### Force HTTP/1.1

Source: https://pkg.go.dev/github.com/enetx/surf

Configures the client to use HTTP/1.1 forcefully.

```go
func (b *Builder) ForceHTTP1() *Builder
```

--------------------------------

### Client.Options

Source: https://pkg.go.dev/github.com/enetx/surf

Creates a new HTTP OPTIONS request for the specified URL. OPTIONS requests are used to describe the communication options for a resource.

```APIDOC
## Options

### Description
Creates a new HTTP OPTIONS request for the specified URL. OPTIONS requests are used to describe the communication options for a resource.

### Method
OPTIONS

### Endpoint
/{rawURL}

### Parameters
#### Path Parameters
- **rawURL** (string) - Required - The URL for the OPTIONS request.

### Response
#### Success Response (200)
- **Request** (*Request) - A Request object representing the OPTIONS request.

### Response Example
```json
{
  "request": "..."
}
```
```

--------------------------------

### Register Middleware with Priority

Source: https://pkg.go.dev/github.com/enetx/surf

With registers middleware into the client builder with optional priority. Middleware can modify the client, intercept requests, or transform responses. Panics if the middleware type is not recognized.

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

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

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

--------------------------------

### Force HTTP/3

Source: https://pkg.go.dev/github.com/enetx/surf

Configures the client to use HTTP/3 forcefully.

```go
func (b *Builder) ForceHTTP3() *Builder
```

--------------------------------

### DNSOverTLS.SB

Source: https://pkg.go.dev/github.com/enetx/surf

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

```APIDOC
## DNSOverTLS.SB

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

### Method
func (*DNSOverTLS) SB() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Multipart Form

Source: https://pkg.go.dev/github.com/enetx/surf

Demonstrates creating multipart forms with fields, files, byte slices, strings, and readers.

```APIDOC
## Multipart Form
```go
// Simple multipart form with fields only
mp := surf.NewMultipart().
    Field("field1", "value1").
    Field("field2", "value2")

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

// Advanced multipart with files from different sources
mp := surf.NewMultipart().
    Field("description", "Multiple files").
    File("document", g.NewFile("/path/to/doc.pdf")).               // Physical file
    FileBytes("data", "data.json", g.Bytes(`{"key": "value"}`)).   // Bytes with custom filename
    FileString("text", "note.txt", "Hello, World!").               // String content
    FileReader("stream", "upload.bin", someReader).                // io.Reader
    ContentType("application/pdf")                                 // Custom Content-Type for last file

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

--------------------------------

### DNSOverTLS.Quad9

Source: https://pkg.go.dev/github.com/enetx/surf

Quad9 sets up DNS over TLS with Quad9 DNS.

```APIDOC
## DNSOverTLS.Quad9

### Description
Quad9 sets up DNS over TLS with Quad9 DNS.

### Method
func (*DNSOverTLS) Quad9() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Create Headers Map

Source: https://pkg.go.dev/github.com/enetx/surf/profiles/firefox

Creates a map of headers for a given method. Supports generic string types for keys and values.

```go
func Headers[T ~string](headers *g.MapOrd[T, T], method string)
```

--------------------------------

### Client.Std

Source: https://pkg.go.dev/github.com/enetx/surf

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.

```APIDOC
## Std

### Description
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.

### Method
GET

### Endpoint
/std

### Response
#### Success Response (200)
- **Client** (*http.Client) - A standard `net/http.Client` instance.

### Response Example
```json
{
  "client": "..."
}
```
```

--------------------------------

### Force HTTP/2

Source: https://pkg.go.dev/github.com/enetx/surf

Configures the client to use HTTP/2 forcefully.

```go
func (b *Builder) ForceHTTP2() *Builder
```

--------------------------------

### DNSOverTLS.AddProvider

Source: https://pkg.go.dev/github.com/enetx/surf

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

```APIDOC
## DNSOverTLS.AddProvider

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

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

### Parameters
- **serverName** (g.String) - The server name for the custom DNS provider.
- **addresses** (...g.String) - A variadic list of IP addresses for the custom DNS provider.

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Convert Surf Client to net/http Client

Source: https://pkg.go.dev/github.com/enetx/surf

Convert a Surf client to a standard net/http.Client for integration with third-party libraries. Preserves features like JA3 fingerprinting, HTTP/2 & HTTP/3 settings, browser impersonation headers, and more.

```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")

```

--------------------------------

### Configure SOCKS5 UDP Proxy with HTTP/3

Source: https://pkg.go.dev/github.com/enetx/surf

Set up an HTTP/3 client to use a SOCKS5 UDP proxy. This configuration is useful for routing traffic through a proxy while leveraging the performance benefits of HTTP/3. Custom DNS resolution can also be specified.

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

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

--------------------------------

### Configure Impersonation

Source: https://pkg.go.dev/github.com/enetx/surf

Configures something related to impersonation and returns an impersonate struct.

```go
func (b *Builder) Impersonate() *Impersonate
```

--------------------------------

### Set Random OS for Impersonation

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func (im *Impersonate) RandomOS() *Impersonate
```

--------------------------------

### Basic Request Methods

Source: https://pkg.go.dev/github.com/enetx/surf

Methods for initiating different types of HTTP requests.

```APIDOC
## Get(url)

### Description
Creates a GET request.

### Method
`Get(url)`

### Endpoint
[URL for the GET request]
```

```APIDOC
## Post(url)

### Description
Creates a POST request.

### Method
`Post(url)`

### Endpoint
[URL for the POST request]
```

```APIDOC
## Put(url)

### Description
Creates a PUT request.

### Method
`Put(url)`

### Endpoint
[URL for the PUT request]
```

```APIDOC
## Patch(url)

### Description
Creates a PATCH request.

### Method
`Patch(url)`

### Endpoint
[URL for the PATCH request]
```

```APIDOC
## Delete(url)

### Description
Creates a DELETE request.

### Method
`Delete(url)`

### Endpoint
[URL for the DELETE request]
```

```APIDOC
## Head(url)

### Description
Creates a HEAD request.

### Method
`Head(url)`

### Endpoint
[URL for the HEAD request]
```

```APIDOC
## Options(url)

### Description
Creates an OPTIONS request.

### Method
`Options(url)`

### Endpoint
[URL for the OPTIONS request]
```

```APIDOC
## Connect(url)

### Description
Creates a CONNECT request.

### Method
`Connect(url)`

### Endpoint
[URL for the CONNECT request]
```

```APIDOC
## Trace(url)

### Description
Creates a TRACE request.

### Method
`Trace(url)`

### Endpoint
[URL for the TRACE request]
```

--------------------------------

### Execute HTTP Request

Source: https://pkg.go.dev/github.com/enetx/surf

Executes the HTTP request with full surf functionality, including middleware, retries, and timing.

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

--------------------------------

### Create HTTP CONNECT Request

Source: https://pkg.go.dev/github.com/enetx/surf

Use Connect to create a new HTTP CONNECT request for establishing a tunnel to a server.

```go
func (c *Client) Connect(rawURL g.String) *Request
```

--------------------------------

### Proxy Configuration (Single Proxy)

Source: https://pkg.go.dev/github.com/enetx/surf

Configure a single HTTP proxy for the client. This is useful for routing traffic through a specific proxy server.

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

--------------------------------

### Configure DNS over TLS

Source: https://pkg.go.dev/github.com/enetx/surf

Configures the client to use DNS over TLS.

```go
func (b *Builder) DNSOverTLS() *DNSOverTLS
```

--------------------------------

### Function Signature for Clone

Source: https://pkg.go.dev/github.com/enetx/surf/internal/specclone

The Clone function accepts a pointer to a utls.ClientHelloSpec and returns a pointer to a new, deeply copied ClientHelloSpec. It returns nil if the input is nil.

```go
func Clone(c *utls.ClientHelloSpec) *utls.ClientHelloSpec
```

--------------------------------

### Configure JA (TLS Fingerprint)

Source: https://pkg.go.dev/github.com/enetx/surf

Configures the client to use a specific TLS fingerprint.

```go
func (b *Builder) JA() *JA
```

--------------------------------

### Debug HTTP Requests and Responses

Source: https://pkg.go.dev/github.com/enetx/surf

Enable detailed debugging of requests and responses using `resp.Ok().Debug()`. You can choose to show request details, the response body, or both, and then print the debug information.

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

--------------------------------

### Set Maximum Redirects

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the maximum number of redirects the client should follow.

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

--------------------------------

### Set JA3/4 Fingerprint to Chrome 70

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the JA3/4 fingerprint to mimic Chrome version 70. Returns a Builder to continue request configuration.

```go
func (j *JA) Chrome70() *Builder
```

--------------------------------

### Generate ClientBuilder String Representation

Source: https://pkg.go.dev/github.com/enetx/surf

String generates a string representation of the ClientBuilder instance.

```go
func (b Builder) String() string
```

--------------------------------

### DNSOverTLS.Forge

Source: https://pkg.go.dev/github.com/enetx/surf

Forge sets up DNS over TLS with DNS Forge.

```APIDOC
## DNSOverTLS.Forge

### Description
Forge sets up DNS over TLS with DNS Forge.

### Method
func (*DNSOverTLS) Forge() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### POST with JSON

Source: https://pkg.go.dev/github.com/enetx/surf

Demonstrates how to send a POST request with a JSON payload.

```APIDOC
## POST with JSON
```go
user := map[string]string{
    "name": "John Doe",
    "email": "john@example.com",
}

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

--------------------------------

### Response Middleware

Source: https://pkg.go.dev/github.com/enetx/surf

Illustrates how to use response middleware to inspect and process incoming responses.

```APIDOC
## 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()
```
```

--------------------------------

### Set Custom DNS Resolver

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the custom DNS resolver address.

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

--------------------------------

### Create HTTP POST Request

Source: https://pkg.go.dev/github.com/enetx/surf

Use Post to create a new HTTP POST request for submitting data to a server.

```go
func (c *Client) Post(rawURL g.String) *Request
```

--------------------------------

### DNSOverTLS.Switch

Source: https://pkg.go.dev/github.com/enetx/surf

Switch sets up DNS over TLS with SWITCH DNS.

```APIDOC
## DNSOverTLS.Switch

### Description
Switch sets up DNS over TLS with SWITCH DNS.

### Method
func (*DNSOverTLS) Switch() *Builder

### Returns
- **(*Builder)** - A pointer to the Builder object for chaining.
```

--------------------------------

### Configure H2C

Source: https://pkg.go.dev/github.com/enetx/surf

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

```go
func (b *Builder) H2C() *Builder
```

--------------------------------

### Set Proxy URL

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the proxy URL for the client.

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

--------------------------------

### Surf Client Structure

Source: https://pkg.go.dev/github.com/enetx/surf

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

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

--------------------------------

### Set Custom Redirect Policy

Source: https://pkg.go.dev/github.com/enetx/surf

Sets a custom redirect policy for the client.

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

--------------------------------

### Use Unix Domain Sockets

Source: https://pkg.go.dev/github.com/enetx/surf

Communicate over Unix domain sockets by specifying the socket path with `UnixSocket(path)`. This is commonly used for interacting with services like Docker.

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

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


```

--------------------------------

### Define HTTP3Settings Struct

Source: https://pkg.go.dev/github.com/enetx/surf

Provides a fluent interface for configuring HTTP/3 SETTINGS parameters. These settings are crucial for establishing and managing HTTP/3 connections.

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

--------------------------------

### Enable Response Body Caching

Source: https://pkg.go.dev/github.com/enetx/surf

Optimize repeated access to response bodies by enabling caching with `surf.NewClient().Builder().CacheBody().Build().Unwrap()`. Subsequent reads of the body will be served from the cache without network I/O.

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

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

--------------------------------

### Set JA3/4 Fingerprint to Chrome 58

Source: https://pkg.go.dev/github.com/enetx/surf

Sets the JA3/4 fingerprint to mimic Chrome version 58. Returns a Builder to continue request configuration.

```go
func (j *JA) Chrome58() *Builder
```

--------------------------------

### Make Raw HTTP Request with Surf

Source: https://pkg.go.dev/github.com/enetx/surf

Use the `Raw` method to construct and send a request directly from a raw HTTP string. Specify the scheme (e.g., 'https') for the connection.

```go
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()

```
Tokens:
Raw