README
¶
🤖👋 Human 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 API is designed to make your code look like a conversation, making it easier to read and understand.
- 🚀 Asynchronous magic: With surf built-in async capabilities, you can send multiple requests in parallel and handle them effortlessly.
- 💾 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.
💻 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/x0xO/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/x0xO/surf
- Import the package into your project:
import "github.com/x0xO/surf"
- Start making requests and have fun! 😄
Give surf a try, and watch your HTTP conversations come to life!
Documentation
¶
Index ¶
- type AsyncURL
- type Client
- func (c *Client) ClientMiddleware(m clientMiddleware) *Client
- 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.Transport
- 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(enable ...bool) *Options
- func (opt *Options) ContentType(contentType string) *Options
- func (opt *Options) DNS(dns string) *Options
- func (opt *Options) DNSCache(ttl time.Duration, maxUsage int64) *Options
- func (opt *Options) DNSOverTLS() *dnsOverTLS
- func (opt *Options) DisableCompression() *Options
- func (opt *Options) DisableKeepAlive() *Options
- func (opt *Options) FollowOnlyHostRedirects() *Options
- func (opt *Options) ForwardHeadersOnRedirect() *Options
- func (opt *Options) GetRemoteAddress() *Options
- func (opt *Options) HTTP2(enable ...bool) *Options
- func (opt *Options) History() *Options
- func (opt *Options) InterfaceAddr(address string) *Options
- func (opt *Options) MaxRedirects(maxRedirects int) *Options
- func (opt *Options) OrderPHeaders(pheadersOrder []string) *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) 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 Requests
- type Response
- func (resp Response) Debug() *debug
- func (resp Response) GetCookies(rawURL string) []*http.Cookie
- func (resp Response) GetResponse() *http.Response
- 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AsyncURL ¶
type AsyncURL struct {
// contains filtered or unexported fields
}
AsyncURL struct represents an asynchronous URL with additional information such as context, addHeaders, setHeaders, URL, addCookies, and data.
func NewAsyncURL ¶
NewAsyncURL creates a new AsyncURL object with the provided URL string and returns a pointer to it.
func (*AsyncURL) AddCookies ¶
AddCookies adds cookies to the AsyncURL object and returns a pointer to the updated object.
func (*AsyncURL) AddHeaders ¶
AddHeaders adds headers to the AsyncURL object and returns a pointer to the updated object.
func (*AsyncURL) Context ¶
Context sets the context of the AsyncURL object and returns a pointer to the updated object.
func (*AsyncURL) Data ¶
Data sets the data of the AsyncURL object and returns a pointer to the updated object.
func (*AsyncURL) SetHeaders ¶
SetHeaders sets the headers of the AsyncURL object and returns a pointer to the updated object.
type Client ¶
type Client struct {
Async *async // Asynchronous request handling.
// 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) FileUpload ¶
FileUpload creates a new multipart file upload request.
func (*Client) GetTLSConfig ¶
GetTLSConfig returns the tls.Config used by the Client.
func (*Client) GetTransport ¶
GetTransport returns the http.transport used by the Client.
func (*Client) Raw ¶ added in v1.0.11
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) DNSCache ¶
DNSCache configures the DNS cache settings of the HTTP client.
DNS caching can improve the performance of HTTP clients by caching the DNS lookup results for the specified Time-To-Live (TTL) duration and limiting the usage of the cached DNS result.
Parameters:
- ttl: the TTL duration for the DNS cache. After this duration, the DNS cache for a host will be invalidated.
- maxUsage: the maximum number of times a cached DNS lookup result can be used. After this number is reached, the DNS cache for a host will be invalidated.
Returns the same Options object, allowing for chaining of configuration calls.
Example:
opt := surf.NewOptions().DNSCache(time.Second*30, 10) cli := surf.NewClient().SetOptions(opt)
The client will now use a DNS cache with a 30-second TTL and a maximum usage count of 10.
func (*Options) DNSOverTLS ¶
func (opt *Options) DNSOverTLS() *dnsOverTLS
DNSOverTLS configures the client to use DNS over TLS.
func (*Options) DisableCompression ¶ added in v1.0.16
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) 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) History ¶
History configures whether the client should keep a history of requests (for debugging purposes only). WARNING: use only for debugging, not in async mode, no concurrency safe!!!
func (*Options) InterfaceAddr ¶
InterfaceAddr sets the network interface address for the client.
func (*Options) MaxRedirects ¶
MaxRedirects sets the maximum number of redirects the client should follow.
func (*Options) OrderPHeaders ¶ added in v1.0.16
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) 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 Requests ¶
type Requests struct {
// contains filtered or unexported fields
}
Requests a struct that manages concurrent HTTP requests.
func (*Requests) Do ¶
Do performs all queued requests concurrently, returning channels with results and errors.
func (*Requests) RateLimiter ¶
RateLimiter sets a rate limiter for the concurrent requests, limiting the number of requests per second.
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.
Status string // HTTP status string.
UserAgent string // User agent string.
Proto string // HTTP protocol version.
History history // Response history.
Cookies cookies // Response cookies.
Time time.Duration // Total time taken for the response.
ContentLength int64 // Length of the response content.
StatusCode int // 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.
Source Files
Directories