httputil

Documentation

Overview

Package httputil provides abstractions around the common needs of HTTP. It also allows swapping in and out the HTTP client.

Index

• Constants
• Variables
• func JSONRequest(r httpdriver.Request) error
• func MultipartRequest(r httpdriver.Request) error
• type Client
  • func NewClient() *Client
  • func (c *Client) Context() context.Context
  • func (c *Client) Copy() *Client
  • func (c *Client) FastRequest(method, url string, opts ...RequestOption) error
  • func (c *Client) MeanwhileMultipart(writer MultipartWriter, method, url string, opts ...RequestOption) (httpdriver.Response, error)
  • func (c *Client) Request(method, url string, opts ...RequestOption) (httpdriver.Response, error)
  • func (c *Client) RequestJSON(to interface{}, method, url string, opts ...RequestOption) error
  • func (c *Client) WithContext(ctx context.Context) *Client
• type DefaultSchema
  • func (d *DefaultSchema) Encode(src interface{}) (url.Values, error)
• type ErrorCode
• type HTTPError
  • func (err HTTPError) Error() string
• type JSONError
  • func (j JSONError) Error() string
  • func (j JSONError) Unwrap() error
• type MultipartWriter
• type RequestError
  • func (r RequestError) Error() string
  • func (r RequestError) Unwrap() error
• type RequestOption
  • func PrependOptions(opts []RequestOption, prepend ...RequestOption) []RequestOption
  • func WithBody(body io.ReadCloser) RequestOption
  • func WithContentType(ctype string) RequestOption
  • func WithHeaders(headers http.Header) RequestOption
  • func WithJSONBody(v interface{}) RequestOption
  • func WithSchema(schema SchemaEncoder, v interface{}) RequestOption
• type ResponseFunc
• type SchemaEncoder

Constants

const StatusTooManyRequests = 429

StatusTooManyRequests is the HTTP status code discord sends on rate-limiting.

Variables

var Retries uint = 5

Retries is the default attempts to retry if the API returns an error before giving up. If the value is smaller than 1, then requests will retry forever.

Functions

func JSONRequest

func JSONRequest(r httpdriver.Request) error

func MultipartRequest

func MultipartRequest(r httpdriver.Request) error

Types

type Client

type Client struct {
	httpdriver.Client
	SchemaEncoder

	// OnRequest, if not nil, will be copied and prefixed on each Request.
	OnRequest []RequestOption

	// OnResponse is called after every Do() call. Response might be nil if Do()
	// errors out. The error returned will override Do's if it's not nil.
	OnResponse []ResponseFunc

	// Timeout is the maximum amount of time the client will wait for a request
	// to finish. If this is 0 or smaller the Client won't time out. Otherwise,
	// the timeout will be used as deadline for context of every request.
	Timeout time.Duration

	// Default to the global Retries variable (5).
	Retries uint
	// contains filtered or unexported fields
}

func NewClient

func NewClient() *Client

func (*Client) Context

func (c *Client) Context() context.Context

Context is a shared context for all future calls. It's Background by default.

func (*Client) Copy

func (c *Client) Copy() *Client

Copy returns a shallow copy of the client.

func (*Client) FastRequest

func (c *Client) FastRequest(method, url string, opts ...RequestOption) error

FastRequest performs a request without waiting for the body.

func (*Client) MeanwhileMultipart

func (c *Client) MeanwhileMultipart(
	writer MultipartWriter,
	method, url string, opts ...RequestOption) (httpdriver.Response, error)

MeanwhileMultipart concurrently encodes and writes the given multipart writer at the same time. The writer will be called in another goroutine, but the writer will be closed when MeanwhileMultipart returns.

func (*Client) Request

func (c *Client) Request(method, url string, opts ...RequestOption) (httpdriver.Response, error)

Request performs a request and returns a response with an unread body. The caller must close it manually.

func (*Client) RequestJSON

func (c *Client) RequestJSON(to interface{}, method, url string, opts ...RequestOption) error

RequestJSON performs a request and unmarshals the JSON body into "to".

func (*Client) WithContext

func (c *Client) WithContext(ctx context.Context) *Client

WithContext returns a client copy of the client with the given context.

type DefaultSchema

type DefaultSchema struct {
	*schema.Encoder
	// contains filtered or unexported fields
}

func (*DefaultSchema) Encode

func (d *DefaultSchema) Encode(src interface{}) (url.Values, error)

type ErrorCode

type ErrorCode uint

type HTTPError

type HTTPError struct {
	Status int    `json:"-"`
	Body   []byte `json:"-"`

	Code    ErrorCode `json:"code"`
	Errors  json.Raw  `json:"errors,omitempty"`
	Message string    `json:"message,omitempty"`
}

HTTPError is returned if the server responds successfully with an error of any kind.

func (HTTPError) Error

func (err HTTPError) Error() string

type JSONError

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

JSONError is returned if the request responds with an invalid JSON.

func (JSONError) Error

func (j JSONError) Error() string

func (JSONError) Unwrap

func (j JSONError) Unwrap() error

type MultipartWriter

type MultipartWriter interface {
	WriteMultipart(body *multipart.Writer) error
}

MultipartWriter is the interface for a data structure that can write into a multipart writer.

type RequestError

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

RequestError is returned if the request fails to be done, i.e. the server is never reached.

func (RequestError) Error

func (r RequestError) Error() string

func (RequestError) Unwrap

func (r RequestError) Unwrap() error

type RequestOption

type RequestOption func(httpdriver.Request) error

func PrependOptions

func PrependOptions(opts []RequestOption, prepend ...RequestOption) []RequestOption

func WithBody

func WithBody(body io.ReadCloser) RequestOption

func WithContentType

func WithContentType(ctype string) RequestOption

func WithHeaders

func WithHeaders(headers http.Header) RequestOption

func WithJSONBody

func WithJSONBody(v interface{}) RequestOption

WithJSONBody inserts a JSON body into the request. This ignores JSON errors.

func WithSchema

func WithSchema(schema SchemaEncoder, v interface{}) RequestOption

type ResponseFunc

type ResponseFunc func(httpdriver.Request, httpdriver.Response) error

type SchemaEncoder

type SchemaEncoder interface {
	Encode(src interface{}) (url.Values, error)
}

SchemaEncoder expects the encoder to read the "schema" tags.