README
¶
🤖👋 Surf: makes HTTP fun and easy!
Surf is a fun, user-friendly, and lightweight Go library that allows you to interact with HTTP services as if you were chatting with them face-to-face! 😄 Imagine if you could make HTTP requests by simply asking a server politely, and receiving responses as if you were having a delightful conversation with a friend. That's the essence of surf!
🌟 Features
- 💬 Simple and Expressive: Surf's API is designed to make your code look like a conversation, making it easier to read and understand.
- 💾 Caching and Streaming: Efficiently cache response bodies and stream data on the fly, like a superhero saving the world from slow internet connections.
- 📉 Limit and Deflate: Limit the amount of data you receive and decompress it on the fly, giving you more control over your HTTP interactions.
- 🎩 Flexible: Customize headers, query parameters, timeouts, and more for a truly tailor-made experience.
- 🔍 Browser Impersonation: Mimic various browsers such as Chrome, Firefox, and others, with a wide range of possible fingerprints for enhanced privacy and compatibility.
💻 Example
Here's a fun and friendly example of how surf makes HTTP requests look like a conversation:
package main
import (
"fmt"
"log"
"github.com/enetx/surf"
)
func main() {
resp, err := surf.NewClient().Get("https://api.example.com/jokes/random").Do() // A simple GET request
if err != nil { log.Fatal(err) }
joke := struct {
ID int `json:"id"`
Setup string `json:"setup"`
Punch string `json:"punch"`
}{}
resp.Body.JSON(&joke)
fmt.Println("Joke of the day:")
fmt.Printf("%s\n%s\n", joke.Setup, joke.Punch)
}
🚀 Getting Started
To start making friends with HTTP services, follow these simple steps:
- Install the surf package using go get:
go get -u github.com/enetx/surf
- Import the package into your project:
import "github.com/enetx/surf"
- Start making requests and have fun! 😄
Give surf a try, and watch your HTTP conversations come to life!
Requires GOEXPERIMENT=rangefunc.
Documentation
¶
Index ¶
- type Client
- func (c *Client) ClientMiddleware(m clientMiddleware) *Client
- func (c *Client) CloseIdleConnections()
- func (c *Client) Delete(rawURL string, data ...any) *Request
- func (c *Client) FileUpload(rawURL, fieldName, filePath string, data ...any) *Request
- func (c *Client) Get(rawURL string, data ...any) *Request
- func (c *Client) GetClient() *http.Client
- func (c *Client) GetDialer() *net.Dialer
- func (c *Client) GetTLSConfig() *tls.Config
- func (c *Client) GetTransport() http.RoundTripper
- func (c *Client) Head(rawURL string) *Request
- func (c *Client) Multipart(rawURL string, multipartValues map[string]string) *Request
- func (c *Client) Patch(rawURL string, data any) *Request
- func (c *Client) Post(rawURL string, data any) *Request
- func (c *Client) Put(rawURL string, data any) *Request
- func (c *Client) Raw(raw, scheme string) *Request
- func (c *Client) RequestMiddleware(m requestMiddleware) *Client
- func (c *Client) ResponseMiddleware(m responseMiddleware) *Client
- func (c *Client) SetOptions(opt *Options) *Client
- type Options
- func (opt *Options) BasicAuth(authentication any) *Options
- func (opt *Options) BearerAuth(authentication string) *Options
- func (opt *Options) CacheBody() *Options
- func (opt *Options) ContentType(contentType string) *Options
- func (opt *Options) DNS(dns string) *Options
- func (opt *Options) DNSOverTLS() *dnsOverTLS
- func (opt *Options) DisableCompression() *Options
- func (opt *Options) DisableKeepAlive() *Options
- func (opt *Options) FollowOnlyHostRedirects() *Options
- func (opt *Options) ForceHTTP1() *Options
- func (opt *Options) ForwardHeadersOnRedirect() *Options
- func (opt *Options) GetRemoteAddress() *Options
- func (opt *Options) H2C() *Options
- func (opt *Options) HTTP2Settings() *http2s
- func (opt *Options) Impersonate() *impersonate
- func (opt *Options) InterfaceAddr(address string) *Options
- func (opt *Options) JA3() *ja3
- func (opt *Options) MaxRedirects(maxRedirects int) *Options
- func (opt *Options) NotFollowRedirects() *Options
- func (opt *Options) Proxy(proxy any) *Options
- func (opt *Options) RedirectPolicy(f func(*http.Request, []*http.Request) error) *Options
- func (opt *Options) Retry(retryMax int, retryWait time.Duration, codes ...int) *Options
- func (opt *Options) Session() *Options
- func (opt *Options) Singleton() *Options
- func (opt Options) String() string
- func (opt *Options) Timeout(timeout time.Duration) *Options
- func (opt *Options) UnixDomainSocket(socketPath string) *Options
- func (opt *Options) UserAgent(userAgent any) *Options
- type Request
- func (req *Request) AddCookies(cookies ...*http.Cookie) *Request
- func (req *Request) AddHeaders(headers any) *Request
- func (req *Request) Do() (*Response, error)
- func (req *Request) GetRequest() *http.Request
- func (req *Request) SetHeaders(headers any) *Request
- func (req *Request) WithContext(ctx context.Context) *Request
- type Response
- func (resp Response) Debug() *debug
- func (resp Response) GetCookies(rawURL string) []*http.Cookie
- func (resp Response) GetResponse() *http.Response
- func (resp Response) Location() string
- func (resp Response) Referer() string
- func (resp Response) RemoteAddress() net.Addr
- func (resp *Response) SetCookies(rawURL string, cookies []*http.Cookie) error
- func (resp Response) TLSGrabber() *tlsData
- type StatusCode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client struct provides a customizable HTTP client with configurable options for making requests, handling connections, and managing TLS settings.
func (*Client) ClientMiddleware ¶
ClientMiddleware add a client middleware.
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) FileUpload ¶
FileUpload creates a new multipart file upload request.
func (*Client) GetTLSConfig ¶
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) Raw ¶
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) RequestMiddleware ¶
RequestMiddleware add a request middleware which hooks before request sent.
func (*Client) ResponseMiddleware ¶
ResponseMiddleware add a response middleware which hooks after response received.
func (*Client) SetOptions ¶
SetOptions sets the provided options 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.
type Options ¶
type Options struct {
// contains filtered or unexported fields
}
func NewOptions ¶
func NewOptions() *Options
NewOptions creates a new Options instance with default values.
func (*Options) BearerAuth ¶
BearerAuth sets the bearer token for the client.
func (*Options) CacheBody ¶
CacheBody configures whether the client should cache the body of the response.
func (*Options) ContentType ¶
ContentType sets the content type for the client.
func (*Options) DNSOverTLS ¶
func (opt *Options) DNSOverTLS() *dnsOverTLS
DNSOverTLS configures the client to use DNS over TLS.
func (*Options) DisableCompression ¶
DisableCompression disables compression for the HTTP client.
func (*Options) DisableKeepAlive ¶
DisableKeepAlive disable keep-alive connections.
func (*Options) FollowOnlyHostRedirects ¶
FollowOnlyHostRedirects configures whether the client should only follow redirects within the same host.
func (*Options) ForceHTTP1 ¶
ForceHTTP1MW configures the client to use HTTP/1.1 forcefully.
func (*Options) ForwardHeadersOnRedirect ¶
ForwardHeadersOnRedirect adds a middleware to the Options object that ensures HTTP headers are forwarded during a redirect.
func (*Options) GetRemoteAddress ¶
GetRemoteAddress configures whether the client should get the remote address.
func (*Options) HTTP2Settings ¶
func (opt *Options) HTTP2Settings() *http2s
HTTP2Settings configures settings related to HTTP/2 and returns an http2s struct.
func (*Options) Impersonate ¶
func (opt *Options) Impersonate() *impersonate
Impersonate configures something related to impersonation and returns an impersonate struct.
func (*Options) InterfaceAddr ¶
InterfaceAddr sets the network interface address for the client.
func (*Options) JA3 ¶
func (opt *Options) JA3() *ja3
JA3 configures the client to use a specific TLS fingerprint.
func (*Options) MaxRedirects ¶
MaxRedirects sets the maximum number of redirects the client should follow.
func (*Options) NotFollowRedirects ¶
NotFollowRedirects disables following redirects for the client.
func (*Options) RedirectPolicy ¶
RedirectPolicy sets a custom redirect policy for the client.
func (*Options) Retry ¶
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 (*Options) Singleton ¶
Singleton configures the client to use a singleton instance, ensuring there's only one client instance. This is needed specifically for JA3 or Impersonate functionalities.
func (*Options) UnixDomainSocket ¶
UnixDomainSocket sets the path for a Unix domain socket in the Options. This allows the HTTP client to connect to the server using a Unix domain socket instead of a traditional TCP/IP connection.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request is a struct that holds information about an HTTP request.
func (*Request) AddCookies ¶
AddCookies adds cookies to the request.
func (*Request) AddHeaders ¶
AddHeaders adds headers to the request, appending to any existing headers with the same name.
func (*Request) Do ¶
Do performs the HTTP request and returns a Response object or an error if the request failed.
func (*Request) GetRequest ¶
GetRequest returns the underlying http.Request of the custom request.
func (*Request) SetHeaders ¶
SetHeaders sets headers for the request, replacing existing ones with the same name.
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 string // User agent string.
Proto 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 // 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 ¶
GetCookies returns the cookies from the response for the given URL.
func (Response) GetResponse ¶
GetResponse returns the underlying http.Response of the custom response.
func (Response) RemoteAddress ¶
RemoteAddress returns the remote address of the response.
func (*Response) SetCookies ¶
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.
Source Files
Directories