pingo

package module
v2.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2024 License: MIT Imports: 20 Imported by: 0

README

Pingo

GitHub release (latest by date) Go Reference

Pingo is a general purpose, high level request library implemented in Go. It is built on top of the standard net/http package and aims to make working with requests more convenient.

Features

  • Zero dependencies
  • Chainable API
  • Context support
  • Logging and debugging options
  • Reusable clients
  • Tweak options both at client and request level
  • Convenient methods to send raw, JSON, XML, form URL encoded, multipart form requests or provide a callback function to create the request body
  • Async requests
  • Easily access response headers and body
  • Streamed response support

Installation

go get -u github.com/mauserzjeh/pingo/v2

Tests

go test -v

Usage

Check the documentation and tests for available methods and examples

Documentation

Index

Constants

View Source 
const (
	Fshortfile = 1 << iota // short file name and line number: file.go:123
	Flongfile              // full file name and line number: a/b/c/file.go:123
	Ftime                  // whether to include date-time in the log message
	FtimeUTC               // if [Ftime] is set then use UTC

	ContentTypeJson            = "application/json"
	ContentTypeXml             = "application/xml"
	ContentTypeFormUrlEncoded  = "application/x-www-form-urlencoded"
	ContentTypeTextEventStream = "text/event-stream"
)

Variables

View Source 
var (
	ErrRequestTimedOut = errors.New("request timed out")
)

Functions

func NewMultipartFormFile 

func NewMultipartFormFile(name string, filePath string) multipartFormFile

NewMultipartFormFile creates a new multipartform file by reading the file from the given filepath

func NewMultipartFormFileReader 

func NewMultipartFormFileReader(name, fileName string, r io.Reader) multipartFormFile

NewMultipartFormFileReader creates a new multipartform file by using the given io.Reader

Types

type AsyncResponse added in v2.2.0 

type AsyncResponse struct {
	Response *Response // response data
	Err      error     // error of the request
}

AsyncResponse is a structure holding response data for async request

type Client 

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

Client is the client used by the package

func NewClient 

func NewClient() *Client

NewClient creates a new client with the default settings

func (*Client) AddHeader 

func (c *Client) AddHeader(key, value string) *Client

AddHeader adds a single header value

func (*Client) AddHeaders 

func (c *Client) AddHeaders(headers http.Header) *Client

AddHeaders adds the header values

func (*Client) AddQueryParam 

func (c *Client) AddQueryParam(key, value string) *Client

AddQueryParam adds a single query parameter

func (*Client) AddQueryParams 

func (c *Client) AddQueryParams(queryParams url.Values) *Client

AddQueryParams adds the query parameters

func (*Client) NewRequest 

func (c *Client) NewRequest() *Request

NewRequest creates a new request

func (*Client) SetBaseUrl 

func (c *Client) SetBaseUrl(baseUrl string) *Client

SetBaseUrl sets the base URL

func (*Client) SetClient 

func (c *Client) SetClient(client *http.Client) *Client

SetClient sets the underlying net/http.Client

func (*Client) SetDebug 

func (c *Client) SetDebug(debug, includeBody bool) *Client

SetDebug sets the debug mode

func (*Client) SetHeader 

func (c *Client) SetHeader(key, value string) *Client

SetHeader sets a single header value

func (*Client) SetHeaders 

func (c *Client) SetHeaders(headers http.Header) *Client

SetHeaders sets the header values

func (*Client) SetLogEnabled 

func (c *Client) SetLogEnabled(enable bool) *Client

SetLogEnabled sets the log mode

func (*Client) SetLogFlags 

func (c *Client) SetLogFlags(flag int) *Client

SetLogFlags sets the log flags

func (*Client) SetLogOutput 

func (c *Client) SetLogOutput(w io.Writer) *Client

SetLogOutput sets the log output to the given io.Writer

func (*Client) SetLogTimeFormat 

func (c *Client) SetLogTimeFormat(layout string) *Client

SetLogTimeFormat sets the log time format if Ftime flag is given

func (*Client) SetQueryParam 

func (c *Client) SetQueryParam(key, value string) *Client

SetQueryParam sets a single query parameter

func (*Client) SetQueryParams 

func (c *Client) SetQueryParams(queryParams url.Values) *Client

SetQueryParams sets the query parameters

func (*Client) SetTimeout 

func (c *Client) SetTimeout(timeout time.Duration) *Client

SetTimeout sets the timeout

type Request 

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

Request is the request created by calling NewRequest

func NewRequest 

func NewRequest() *Request

NewRequest creates a new request on the default client

func (*Request) AddHeader 

func (r *Request) AddHeader(key, value string) *Request

AddHeader adds a single header value

func (*Request) AddHeaders 

func (r *Request) AddHeaders(headers http.Header) *Request

AddHeaders adds the header values

func (*Request) AddQueryParam 

func (r *Request) AddQueryParam(key, value string) *Request

AddQueryParam adds a single query parameter

func (*Request) AddQueryParams 

func (r *Request) AddQueryParams(queryParams url.Values) *Request

AddQueryParams adds the query parameters

func (*Request) BodyCustom 

func (r *Request) BodyCustom(f func() (*bytes.Buffer, error)) *Request

BodyCustom prepares the body with the given callback function

func (*Request) BodyFormUrlEncoded 

func (r *Request) BodyFormUrlEncoded(data url.Values) *Request

BodyFormUrlEncoded prepares the body as a form URL encoded request with the given data. Content-Type header is automatically set to "application/x-www-form-urlencoded"

func (*Request) BodyJson 

func (r *Request) BodyJson(data any) *Request

BodyJson prepares the body as a JSON request with the given data. Content-Type header is automatically set to "application/json"

func (*Request) BodyMultipartForm 

func (r *Request) BodyMultipartForm(data map[string]any, files ...multipartFormFile) *Request

BodyMultipartForm prepares the body as a multipartform request with the given data and files. Content-Type header is automatically set to "multipart/form-data" with the proper boundary. Use NewMultipartFormFile or NewMultipartFormFileReader to pass files for file upload

func (*Request) BodyRaw 

func (r *Request) BodyRaw(data []byte) *Request

BodyRaw prepares the body with the given raw data bytes

func (*Request) BodyXml 

func (r *Request) BodyXml(data any) *Request

BodyXml prepares the body as an XML request with the given data. Content-Type header is automatically set to "application/xml"

func (*Request) Do 

func (r *Request) Do() (*Response, error)

Do performs the request using context.Background

func (*Request) DoAsync added in v2.2.0 

func (r *Request) DoAsync() <-chan AsyncResponse

DoAsync performs an async request using context.Background. It returns an AsyncResponse channel which will receive the response when the request completes

func (*Request) DoAsyncCtx added in v2.2.0 

func (r *Request) DoAsyncCtx(ctx context.Context) <-chan AsyncResponse

DoAsyncCtx performs an async request with the given context.Context. It returns an AsyncResponse channel which will receive the response when the request completes

func (*Request) DoCtx 

func (r *Request) DoCtx(ctx context.Context) (*Response, error)

DoCtx performs the request with the given context.Context and returns a response

func (*Request) DoStream 

func (r *Request) DoStream(ctx context.Context) (*ResponseStream, error)

DoStream performs a request using the given context.Context and returns a streaming response

func (*Request) SetBaseUrl 

func (r *Request) SetBaseUrl(baseUrl string) *Request

SetBaseUrl sets the base URL

func (*Request) SetDebug 

func (r *Request) SetDebug(debug, includeBody bool) *Request

SetDebug sets the debug mode

func (*Request) SetHeader 

func (r *Request) SetHeader(key, value string) *Request

SetHeader sets a single header value

func (*Request) SetHeaders 

func (r *Request) SetHeaders(headers http.Header) *Request

SetHeaders sets the header values

func (*Request) SetLogEnabled 

func (r *Request) SetLogEnabled(enabled bool) *Request

SetLogEnabled sets the log mode

func (*Request) SetMethod 

func (r *Request) SetMethod(method string) *Request

SetMethod sets the request method e.g.: "GET", "POST", "PUT"

func (*Request) SetPath 

func (r *Request) SetPath(path string) *Request

SetPath sets the request path

func (*Request) SetQueryParam 

func (r *Request) SetQueryParam(key, value string) *Request

SetQueryParam sets a single query parameter

func (*Request) SetQueryParams 

func (r *Request) SetQueryParams(queryParams url.Values) *Request

SetQueryParams sets the query parameters

func (*Request) SetTimeout 

func (r *Request) SetTimeout(timeout time.Duration) *Request

SetTimeout sets the timeout

type Response 

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

Response holds the response data

func (*Response) BodyRaw 

func (r *Response) BodyRaw() []byte

BodyRaw returns the response body as a byte slice

func (*Response) BodyString 

func (r *Response) BodyString() string

BodyString returns the response body as string

func (*Response) GetHeader 

func (r *Response) GetHeader(key string) string

GetHeader is a convenience method to retrieve a single response header value

func (*Response) Headers 

func (r *Response) Headers() http.Header

Headers returns the response headers

func (*Response) IsError 

func (r *Response) IsError() error

IsError returns a non nil error if the response is considered as an error based on the status code. The error's type will be *ResponseError

func (*Response) Status 

func (r *Response) Status() string

Status returns the status of a response

func (*Response) StatusCode 

func (r *Response) StatusCode() int

StatusCode returns the status code of a response

func (*Response) Unmarshal 

func (r *Response) Unmarshal(u ResponseUnmarshaler) error

Unmarshal is a convenience method that can receive a ResponseUnmarshaler callback function that performs the unmarshalling of the response body

type ResponseError added in v2.1.0 

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

ResponseError holds data of response that is considered to be an error

func (*ResponseError) BodyRaw added in v2.1.0 

func (r *ResponseError) BodyRaw() []byte

BodyRaw returns the response body as a byte slice

func (*ResponseError) BodyString added in v2.1.0 

func (r *ResponseError) BodyString() string

BodyString returns the response body as string

func (ResponseError) Error added in v2.1.0 

func (r ResponseError) Error() string

Error implements the error interface

func (*ResponseError) GetHeader added in v2.1.0 

func (r *ResponseError) GetHeader(key string) string

GetHeader is a convenience method to retrieve a single response header value

func (*ResponseError) Headers added in v2.1.0 

func (r *ResponseError) Headers() http.Header

Headers returns the response headers

func (*ResponseError) Status added in v2.1.0 

func (r *ResponseError) Status() string

Status returns the status of a response

func (*ResponseError) StatusCode added in v2.1.0 

func (r *ResponseError) StatusCode() int

StatusCode returns the status code of a response

type ResponseStream 

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

ResponseStream is a streamed response

func (*ResponseStream) Close 

func (r *ResponseStream) Close()

Close closes the streamed response body and additionally frees up any resources associated with the context.Context used to perform the streamed request

func (*ResponseStream) GetHeader 

func (r *ResponseStream) GetHeader(key string) string

GetHeader is a convenience method to retrieve a single response header value

func (*ResponseStream) Headers 

func (r *ResponseStream) Headers() http.Header

Headers returns the response headers

func (*ResponseStream) Recv 

func (r *ResponseStream) Recv(n uint) ([]byte, error)

Recv reads up to n bytes from a streamed response body

func (*ResponseStream) RecvFunc 

func (r *ResponseStream) RecvFunc(sr StreamReceiver) error

RecvFunc can receive a StreamReceiver callback function that performs the stream reading of the streamed response body

func (*ResponseStream) Status 

func (r *ResponseStream) Status() string

Status returns the status of a response

func (*ResponseStream) StatusCode 

func (r *ResponseStream) StatusCode() int

StatusCode returns the status code of a response

type ResponseUnmarshaler 

type ResponseUnmarshaler func(r *Response) error

ResponseUnmarshaler is a function that can be used to unmarshal a response

type StreamReceiver 

type StreamReceiver func(r *bufio.Reader) error

StreamReceiver is a function that can be used to read from a streamed response

Source Files

View all Source files

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.