requests

Documentation

Overview

Package requests provides HTTP client implementation.

Index

• Variables
• func NewRequest(url string, opts ...RequestOpt) (*http.Request, error)
• func ReadResponseBody(response *http.Response) ([]byte, error)
• func ReadResponseJSON(response *http.Response, v any) error
• type Client
  • func NewClient(opts ...ClientOpt) *Client
  • func (client *Client) Send(request *http.Request) (*http.Response, error)
• type ClientConfig
• type ClientOpt
  • func Address(address string) ClientOpt
  • func CookieJar(cookieJar http.CookieJar) ClientOpt
  • func MaxRedirects(maxRedirects int) ClientOpt
  • func MaxRetries(maxRetries int) ClientOpt
  • func Network(network string) ClientOpt
  • func RetryDelayFactor(retryDelayFactor time.Duration) ClientOpt
  • func TLSConfig(tlsConfig *tls.Config) ClientOpt
  • func Timeout(timeout time.Duration) ClientOpt
• type RequestConfig
• type RequestOpt
  • func BasicAuth(username, password string) RequestOpt
  • func BearerToken(token string) RequestOpt
  • func Body(body io.Reader) RequestOpt
  • func ContentType(contentType string) RequestOpt
  • func Cookie(cookie *http.Cookie) RequestOpt
  • func FormBody(form *url.Values) RequestOpt
  • func Header(key, value string) RequestOpt
  • func Host(host string) RequestOpt
  • func JSONBody(body interface{}) RequestOpt
  • func Method(method string) RequestOpt
  • func MultipartForm(parts ...*RequestPart) RequestOpt
  • func UserAgent(userAgent string) RequestOpt
• type RequestPart
  • func PartFromData(fieldName, fileName string, data any) *RequestPart
  • func PartFromDiskFile(fieldName, fileName, diskPath string) *RequestPart

Variables

var (
	GET     = Method("GET")
	POST    = Method("POST")
	PUT     = Method("PUT")
	DELETE  = Method("DELETE")
	HEAD    = Method("HEAD")
	TRACE   = Method("TRACE")
	OPTIONS = Method("OPTIONS")
	CONNECT = Method("CONNECT")
)

var (
	// ErrRedirect is return when client reaches its maximum number of redirects when performing HTTP request.
	ErrRedirect = errors.New("redirect limit exceeded")
)

Functions

func NewRequest

func NewRequest(url string, opts ...RequestOpt) (*http.Request, error)

NewRequest constructs a request using given options.

func ReadResponseBody

func ReadResponseBody(response *http.Response) ([]byte, error)

ReadResponseBody extracts the whole request body from the HTTP response.

func ReadResponseJSON

func ReadResponseJSON(response *http.Response, v any) error

ReadResponseJSON extracts the whole request body from the HTTP response and converts it from JSON to the given value.

Types

type Client

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

Client is an HTTP client, capable of executing HTTP requests and performing retries.

func NewClient

func NewClient(opts ...ClientOpt) *Client

NewClient creates an instance of Client using given options.

func (*Client) Send

func (client *Client) Send(request *http.Request) (*http.Response, error)

Send tries to send given HTTP request and return a response. Depending on the configuration specified, requests might be retried on error. If client reaches its maximum number of redirects - both the latest response and ErrRedirect are returned.

type ClientConfig

type ClientConfig struct {
	// Network is a network type to use (default: "tcp").
	Network string

	// Address is an optional property that overwrites network address that clients connect to when sending request.
	// By default, it's empty and the target address is extracted from the URL, and it might differ between requests.
	// Setting Address might be required if the client targets Unix socket.
	// In this case you need to set Network parameter to "unix" and Address to a path to a Unix socket
	// (for example "/run/httpd.sock").
	Address string

	// Timeout is a time after which a request (call to Client.Send()) times out (default: 10s).
	Timeout time.Duration

	// MaxRetries is a maximum number of time the request should be retried when encountering server error.
	// Requests are only retried when send operation returns network error or HTTP server errors (5xx).
	// (default: 0).
	MaxRetries int

	// MaxRedirects is a maximum number of redirects the client will perform before failing with ErrRedirect.
	// (default: 10).
	MaxRedirects int

	// RetryDelayFactor is a factor used to calculate the delay time between subsequent retries.
	// The formula is: retryNumber * RetryDelayFactor.
	// (default: 0).
	RetryDelayFactor time.Duration

	// TLSConfig is an optional TLS configuration to pass when using TLS.
	TLSConfig *tls.Config

	// CookieJar is a collection of cookies to use in all requests initiated by the client.
	CookieJar http.CookieJar
}

ClientConfig holds a configuration for Client.

type ClientOpt

type ClientOpt = func(*ClientConfig)

ClientOpt is an option to be passed to NewClient.

func Address

func Address(address string) ClientOpt

Address is an optional property that overwrites network address that clients connect to when sending request. By default, it's empty and the target address is extracted from the URL, and it might differ between requests. Setting Address might be required if the client targets Unix socket. In this case you need to set Network parameter to "unix" and Address to a path to a Unix socket (for example "/run/httpd.sock").

func CookieJar

func CookieJar(cookieJar http.CookieJar) ClientOpt

CookieJar is a collection of cookies to use in all requests initiated by the client.

func MaxRedirects

func MaxRedirects(maxRedirects int) ClientOpt

MaxRedirects is a maximum number of redirects the client will perform before failing with ErrRedirect.

func MaxRetries

func MaxRetries(maxRetries int) ClientOpt

MaxRetries is a maximum number of time the request should be retried when encountering server error. Requests are only retried when send operation returns network error or HTTP server errors (5xx).

func Network

func Network(network string) ClientOpt

Network is a network type to use.

func RetryDelayFactor

func RetryDelayFactor(retryDelayFactor time.Duration) ClientOpt

RetryDelayFactor is a factor used to calculate the delay time between subsequent retries. The formula is: retryNumber * RetryDelayFactor.

func TLSConfig

func TLSConfig(tlsConfig *tls.Config) ClientOpt

TLSConfig is an optional TLS configuration to pass when using TLS.

func Timeout

func Timeout(timeout time.Duration) ClientOpt

Timeout is a time after which a request (call to Client.Do()) times out.

type RequestConfig

type RequestConfig struct {
	// contains filtered or unexported fields
}

RequestConfig holds a configuration for request while it's constructed.

type RequestOpt

type RequestOpt = func(*RequestConfig) error

RequestOpt is an option to be specified to NewRequest.

func BasicAuth

func BasicAuth(username, password string) RequestOpt

BasicAuth sets Authorization request header to "Basic base64(%username%:%password%)".

func BearerToken

func BearerToken(token string) RequestOpt

BearerToken sets Authorization request header to "Bearer %token%".

func Body

func Body(body io.Reader) RequestOpt

Body is an optional body to be included in the request.

func ContentType

func ContentType(contentType string) RequestOpt

ContentType sets Content-Type request header.

func Cookie

func Cookie(cookie *http.Cookie) RequestOpt

Cookie adds HTTP request cookie.

func FormBody

func FormBody(form *url.Values) RequestOpt

FormBody is an optional form data to be included in the request.

func Header

func Header(key, value string) RequestOpt

Header sets a request header specified by the given key.

func Host

func Host(host string) RequestOpt

Host overwrites the Host header value. If not provided, the host is extracted from the URL.

func JSONBody

func JSONBody(body interface{}) RequestOpt

JSONBody is an optional body to be included in the request. Given value is first converted to JSON and then appended to the request.

func Method

func Method(method string) RequestOpt

Method is a method of the HTTP request (default: "GET").

func MultipartForm

func MultipartForm(parts ...*RequestPart) RequestOpt

MultipartForm is an optional multipart form data to be included in the request.

func UserAgent

func UserAgent(userAgent string) RequestOpt

UserAgent sets User-Agent request header.

type RequestPart

type RequestPart struct {
	// contains filtered or unexported fields
}

RequestPart represents a single part of the HTTP multipart form.

func PartFromData

func PartFromData(fieldName, fileName string, data any) *RequestPart

PartFromData creates a part of multipart form from the in-memory buffer.

func PartFromDiskFile

func PartFromDiskFile(fieldName, fileName, diskPath string) *RequestPart

PartFromDiskFile creates a part of multipart form from the disk file.