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 := surf.NewClient().Get("https://api.example.com/jokes/random").Do() // A simple GET request
if r.IsErr() { log.Fatal(r.Err()) }
joke := struct {
ID int `json:"id"`
Setup string `json:"setup"`
Punch string `json:"punch"`
}{}
resp.Ok().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 Body
- func (b *Body) Bytes() g.Bytes
- func (b *Body) Close() error
- func (b *Body) Contains(pattern any) bool
- func (b *Body) Dump(filename string) error
- func (b *Body) JSON(data any) error
- func (b *Body) Limit(limit int64) *Body
- func (b *Body) MD5() g.String
- func (b *Body) SSE(fn func(event *sse.Event) bool) error
- func (b *Body) Stream() *bufio.Reader
- func (b *Body) String() g.String
- func (b *Body) UTF8() g.String
- func (b *Body) XML(data any) error
- type Client
- func (c *Client) Builder() *builder
- 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
- type Cookies
- type Headers
- type Request
- func (req *Request) AddCookies(cookies ...*http.Cookie) *Request
- func (req *Request) AddHeaders(headers any) *Request
- func (req *Request) Do() g.Result[*Response]
- 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) Release()
- 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 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) Contains ΒΆ added in v1.0.51
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
Dump dumps the body's content to a file with the given filename.
func (*Body) JSON ΒΆ added in v1.0.51
JSON decodes the body's content as JSON into the provided data structure.
func (*Body) Limit ΒΆ added in v1.0.51
Limit sets the body's size limit and returns the modified body.
func (*Body) SSE ΒΆ added in v1.0.53
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
Stream returns the body's bufio.Reader for streaming the content.
type Client ΒΆ
type Client struct {
// contains filtered or unexported fields
}
Client struct provides a customizable HTTP client.
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) 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.
type Cookies ΒΆ added in v1.0.51
Cookies represents a list of HTTP Cookies.
type Headers ΒΆ added in v1.0.51
Headers represents a collection of HTTP Headers.
func (Headers) Contains ΒΆ added in v1.0.51
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.
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 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) Release ΒΆ added in v1.0.51
func (resp *Response) Release()
Release releases the Response object back to the response pool.
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.