client

package module
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2025 License: MIT Imports: 13 Imported by: 0

README

http-client

http-client provides a convenient way to interact with the web by creating an API that is wrapped around Go's http.Client

The readme contains documentation for v2.0.0

What started as a simple project for performing basic HTTP Methods with an underlying bytes.Buffer now includes:

  • API's to send urlencoded forms, upload files based on POST, PUT, PATCH
  • Implementation to send data based on different readers
  • []byte
  • byte.Buffer
  • io.Reader
  • string
  • Receive output as a byte.Buffer or write directly to a file
  • Following redirects
  • Keeping HTTP Method when following redirects (optionally)
  • Compression (gzip, deflate and brotli)
  • Custom compression
  • Following redirects and sending payloads to the redirect end point
  • Multipart uploads
  • Additional test cases for new functionality

It has two modes of operation:

  1. Normal HTTP method function calls
  2. A reusable Client

In most cases, the HTTP method function calls are probably what you are looking for.

The reusable client is typically more useful in scenarios where you need to work with cookies, or in scenarios where it will be useful to keep track of past requests. An example could be for writing an API test that might require different headers/cookies to be set and used as part of the testing of each end point.

Note: the Client implementation does not have test cases, nor has been tested properly. Please report issues.

Test cases

Test cases are available in func_test.go

They also provide some useful real-world documentation.

Basic example

package main

import (
	"fmt"
	"log"

	client "github.com/caelisco/http-client"
)

func main() {
	resp, err := client.Get("https://www.caelisco.net/http-client/get/")
	if err != nil || resp.StatusCode != 200 {
		log.Fatalf("There was an error with the request. StatusCode: %d Error: %s", resp.StatusCode, err)
	}
	// output the HTML response
	fmt.Println(resp.String())
}

Options

http-client provides various options that can be sent through with requests.

type Option struct {
	Verbose                  bool                              // Whether logging should be verbose or not
	Logger                   slog.Logger                       // Logging - default uses the slog TextHandler
	Header                   http.Header                       // Headers to be included in the request
	Cookies                  []*http.Cookie                    // Cookies to be included in the request
	ProtocolScheme           string                            // define a custom protocol scheme. It defaults to https
	Compression              CompressionType                   // CompressionType to use: none, gzip, deflate or brotli
	UserAgent                string                            // User Agent to send with requests
	FollowRedirect           bool                              // Disable or enable redirects. Default is true i.e.: follow redirects
	PreserveMethodOnRedirect bool                              // Default is true
	UniqueIdentifierType     UniqueIdentifierType              // Internal trace or identifier for the request
	Transport                *http.Transport                   // Create our own default transport
	ResponseWriter           ResponseWriter                    // Define the type of response writer
	DownloadBufferSize       *int                              // Control the size of the buffer when downloading a file
	OnUploadProgress         func(bytesRead, totalBytes int64) // To monitor and track progress when uploading
	OnDownloadProgress       func(bytesRead, totalBytes int64) // To monitor and track progress when downloading
}

Basic example with headers

package main

import (
	"fmt"
	"log"

	client "github.com/caelisco/http-client"
	"github.com/caelisco/http-client/options"
)

func main() {
	opt := options.New()
	opt.Header.Add("Accept-Format", "xml")
	resp, err := client.Get("https://www.caelisco.net/http-client/get/", opt)
	if err != nil || resp.StatusCode != 200 {
		log.Fatalf("There was an error with the request. StatusCode: %d Error: %s", resp.StatusCode, err)
	}
	// output the HTML response
	fmt.Println(resp.String())
}

Upload a file

The latest version of http-client provides a more powerful interface for sending a payload by changing the payload from a []byte to using any.

The main reason is efficency: converting a file to a []byte would require the entire file to be loaded in to memory first.

Now it is possible to provide a file handle and upload the file automatically.

file, err := os.Open("README.md")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

// Create options with progress tracking if desired
opt := options.New()
opt.OnUploadProgress = func(bytesRead, totalBytes int64) {
    progress := float64(bytesRead) / float64(totalBytes) * 100
    fmt.Printf("Upload progress: %.2f%%\n", progress)
}
// send the file
resp, err := client.Post(url, file, opt)

Similarly, when downloading a file, it can be written directly to a file without needing to buffer it in memory.

The default is to set the file output to bytes.Buffer

options.SetOutput(writerType ResponseWriterType, filepath ...string)
options.SetFileOutput(filepath string)
options.SetBufferOutput()

Compressing a stream

You can specify a compression stream using the options.Compression by providing an option.CompressionType. Compression involves streaming the payload to the server using io.Pipe() and io.Copy() to reduce memory pressure. You can also define a custom buffer size.

http-client supports gzip, deflate and brotli.

const (
	CompressionNone    CompressionType = ""
	CompressionGzip    CompressionType = "gzip"
	CompressionDeflate CompressionType = "deflate"
	CompressionBrotli  CompressionType = "br"
	CompressionCustom  CompressionType = "custom"
)

You can also define your own custom compression assuming the server is able to work with the compressed data.

opt := options.New()
// set the compression to custom
opt.SetCompression(options.CompressionCustom)
// create a writer to compress the stream
opt.CustomCompressor = func(w *io.PipeWriter) (io.WriteCloser, error) {
	return snappy.NewWriter(w), nil
}
// define the compression type to be used with the content-encoding
opt.CustomCompressionType = options.CompressionType("snappy")
// perform the request
resp, err := client.Post(url, data, opt)

Progress

http-client includes progress reporting for both uploading and downloading content.

An example also exists in progress/progress.go.

file, err := os.Open("README.md")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

// Create options with progress tracking if desired
opt := options.New()
opt.OnUploadProgress = func(bytesRead, totalBytes int64) {
    progress := float64(bytesRead) / float64(totalBytes) * 100
    fmt.Printf("Upload progress: %.2f%%\n", progress)
}
// send the file
resp, err := client.Post(url, file, opt)

Documentation

Index

Constants

View Source 
const (
	SchemeHTTP      string = "http://"
	SchemeHTTPS     string = "https://"
	SchemeWS        string = "ws://"
	SchemeWSS       string = "wss://"
	ContentType     string = "Content-Type"
	ContentEncoding string = "Content-Encoding"
	URLencoded      string = "application/x-www-form-urlencoded"
)

Variables

This section is empty.

Functions

func Connect 

func Connect(url string, opts ...*options.Option) (response.Response, error)

Connect performs an HTTP CONNECT to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func Custom 

func Custom(method string, url string, payload any, opts ...*options.Option) (response.Response, error)

Custom performs a custom HTTP method to the specified URL with the given payload. It accepts the HTTP method as its first argument, the URL string as the second argument, the payload as the third argument, and optionally additional Options to customize the request. Returns the HTTP response and an error if any.

func Delete 

func Delete(url string, opts ...*options.Option) (response.Response, error)

Delete performs an HTTP DELETE to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func Get 

func Get(url string, opts ...*options.Option) (response.Response, error)

Get performs an HTTP GET to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any. 

func Head(url string, opts ...*options.Option) (response.Response, error)

Head performs an HTTP HEAD to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func MultipartUpload 

func MultipartUpload(method, url string, payload map[string]any, opts ...*options.Option) (response.Response, error)

MultipartUpload performs a multipart form-data upload request to the specified URL. It supports file uploads and other form fields.

Parameters:

  • method: The HTTP method to use for the request (e.g., "POST", "PUT", "PATCH").
  • url: The target URL for the upload.
  • payload: A map containing the form fields and file pointers to upload. For file uploads, use *os.File as the value.
  • opts: Optional parameters for the request (e.g., headers, timeout).

Returns:

  • response.Response: The response from the server.
  • error: Any error encountered during the request.

func Options 

func Options(url string, opts ...*options.Option) (response.Response, error)

Options performs an HTTP OPTIONS to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func Patch 

func Patch(url string, payload any, opts ...*options.Option) (response.Response, error)

Patch performs an HTTP PATCH to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PatchFile 

func PatchFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PatchFile uploads a file to the specified URL using an HTTP PATCH request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PatchFormData 

func PatchFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PatchFormData performs an HTTP PATCH as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PatchMultipartUpload 

func PatchMultipartUpload(url string, payload map[string]interface{}, opts ...*options.Option) (response.Response, error)

PatchMultipartUpload performs a PATCH multipart form-data upload request to the specified URL. This method can be used for partial updates to a resource, which might include updating or adding new file attachments.

Parameters:

  • url: The target URL for the upload.
  • payload: A map containing the form fields and file pointers to upload. For file uploads, use *os.File as the value.
  • opts: Optional parameters for the request (e.g., headers, timeout).

Returns:

  • response.Response: The response from the server.
  • error: Any error encountered during the request.

func Post 

func Post(url string, payload any, opts ...*options.Option) (response.Response, error)

Post performs an HTTP POST to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PostFile 

func PostFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PostFile uploads a file to the specified URL using an HTTP POST request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PostFormData 

func PostFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PostFormData performs an HTTP POST as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PostMultipartUpload 

func PostMultipartUpload(url string, payload map[string]interface{}, opts ...*options.Option) (response.Response, error)

PostMultipartUpload performs a POST multipart form-data upload request to the specified URL. This is the most common method for file uploads and creating new resources with file attachments.

Parameters:

  • url: The target URL for the upload.
  • payload: A map containing the form fields and file pointers to upload. For file uploads, use *os.File as the value.
  • opts: Optional parameters for the request (e.g., headers, timeout).

Returns:

  • response.Response: The response from the server.
  • error: Any error encountered during the request.

func Put 

func Put(url string, payload any, opts ...*options.Option) (response.Response, error)

Put performs an HTTP PUT to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PutFile 

func PutFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PutFile uploads a file to the specified URL using an HTTP PUT request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PutFormData 

func PutFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PutFormData performs an HTTP PUT as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func PutMultipartUpload 

func PutMultipartUpload(url string, payload map[string]interface{}, opts ...*options.Option) (response.Response, error)

PutMultipartUpload performs a PUT multipart form-data upload request to the specified URL. This method is less common but can be used when updating an entire resource with new data, including file attachments.

Parameters:

  • url: The target URL for the upload.
  • payload: A map containing the form fields and file pointers to upload. For file uploads, use *os.File as the value.
  • opts: Optional parameters for the request (e.g., headers, timeout).

Returns:

  • response.Response: The response from the server.
  • error: Any error encountered during the request.

func Trace 

func Trace(url string, opts ...*options.Option) (response.Response, error)

Trace performs an HTTP TRACE to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

Types

type Client 

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

Client represents an HTTP client.

func New 

func New(opts ...*options.Option) *Client

New returns a reusable Client. It is possible to include a global RequestOptions which will be used on all subsequent requests.

func NewCustom 

func NewCustom(client *http.Client, opts ...*options.Option) *Client

NewCustom returns a reusable client with a custom defined *http.Client This is useful in scenarios where you want to change any configurations for the http.Client

func (*Client) AddGlobalOptions 

func (c *Client) AddGlobalOptions(opts *options.Option)

AddGlobalOptions adds the provided options to the client's global options

func (*Client) Clear 

func (c *Client) Clear()

Clear clears any Responses that have already been made and kept.

func (*Client) CloneGlobalOptions 

func (c *Client) CloneGlobalOptions() *options.Option

CloneGlobalOptions clones the global RequestOptions of the client.

func (*Client) Connect 

func (c *Client) Connect(url string, opts ...*options.Option) (response.Response, error)

Connect performs an HTTP CONNECT to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Custom 

func (c *Client) Custom(method string, url string, payload any, opts ...*options.Option) (response.Response, error)

Custom performs a custom HTTP method to the specified URL with the given payload. It accepts the HTTP method as its first argument, the URL string as the second argument, the payload as the third argument, and optionally additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Delete 

func (c *Client) Delete(url string, opts ...*options.Option) (response.Response, error)

Delete performs an HTTP DELETE to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Get 

func (c *Client) Get(url string, opts ...*options.Option) (response.Response, error)

Get performs an HTTP GET to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) GetGlobalOptions 

func (c *Client) GetGlobalOptions() *options.Option

GetGlobalOptions returns the global RequestOptions of the client.

func (*Client) Head 

func (c *Client) Head(url string, opts ...*options.Option) (response.Response, error)

Head performs an HTTP HEAD to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Options 

func (c *Client) Options(url string, opts ...*options.Option) (response.Response, error)

Options performs an HTTP OPTIONS to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Patch 

func (c *Client) Patch(url string, payload any, opts ...*options.Option) (response.Response, error)

Patch performs an HTTP PATCH to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PatchFile 

func (c *Client) PatchFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PatchFile uploads a file to the specified URL using an HTTP PATCH request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PatchFormData 

func (c *Client) PatchFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PatchFormData performs an HTTP PATCH as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Post 

func (c *Client) Post(url string, payload any, opts ...*options.Option) (response.Response, error)

Post performs an HTTP POST to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PostFile 

func (c *Client) PostFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PostFile uploads a file to the specified URL using an HTTP POST request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PostFormData 

func (c *Client) PostFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PostFormData performs an HTTP POST as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Put 

func (c *Client) Put(url string, payload any, opts ...*options.Option) (response.Response, error)

Put performs an HTTP PUT to the specified URL with the given payload. It accepts the URL string as its first argument and the payload as the second argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PutFile 

func (c *Client) PutFile(url string, filename string, opts ...*options.Option) (response.Response, error)

PutFile uploads a file to the specified URL using an HTTP PUT request. It accepts the URL string as its first argument and the filename as the second argument. The file is read from the specified filename and uploaded as the request payload. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) PutFormData 

func (c *Client) PutFormData(url string, payload map[string]string, opts ...*options.Option) (response.Response, error)

PutFormData performs an HTTP PUT as an x-www-form-urlencoded payload to the specified URL. It accepts the URL string as its first argument and a map[string]string the payload. The map is converted to a url.QueryEscaped k/v pair that is sent to the server. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) Responses 

func (c *Client) Responses() []response.Response

Responses returns a slice of responses made by this Client

func (*Client) Trace 

func (c *Client) Trace(url string, opts ...*options.Option) (response.Response, error)

Trace performs an HTTP TRACE to the specified URL. It accepts the URL string as its first argument. Optionally, you can provide additional Options to customize the request. Returns the HTTP response and an error if any.

func (*Client) UpdateGlobalOptions 

func (c *Client) UpdateGlobalOptions(opts *options.Option)

UpdateGlobalOptions updates the global RequestOptions of the client.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳