Documentation
¶
Index ¶
- Variables
- func BindResponse(resp *http.Response, dest interface{}) (err error)
- func Debug(c *Client)
- func DecodeError(err error, destPtr interface{}) error
- func GetErrorCode(err error) int
- func RegisterRequestHandler(reqHandlers ...RequestHandler)
- type APIError
- type Client
- func (c *Client) Clone(opts ...Option) *Client
- func (c *Client) Do(ctx context.Context, method, urlpath string, payload interface{}, ...) (*http.Response, error)
- func (c *Client) DrainResponseBody(resp *http.Response)
- func (c *Client) Form(ctx context.Context, method, urlpath string, formValues url.Values, ...) (*http.Response, error)
- func (c *Client) GetPlainUnquote(ctx context.Context, method, urlpath string, payload interface{}, ...) (string, error)
- func (c *Client) JSON(ctx context.Context, method, urlpath string, payload interface{}, ...) (*http.Response, error)
- func (c *Client) NewUploader() *Uploader
- func (c *Client) ReadJSON(ctx context.Context, dest interface{}, method, urlpath string, ...) error
- func (c *Client) ReadPlain(ctx context.Context, dest interface{}, method, urlpath string, ...) error
- func (c *Client) RegisterRequestHandler(reqHandlers ...RequestHandler)
- func (c *Client) WriteTo(ctx context.Context, dest io.Writer, method, urlpath string, ...) (int64, error)
- type Option
- type RequestHandler
- type RequestOption
- func RequestAuthorization(value string) RequestOption
- func RequestAuthorizationBearer(accessToken string) RequestOption
- func RequestHeader(overridePrev bool, key string, values ...string) RequestOption
- func RequestParam(key string, values ...string) RequestOption
- func RequestQuery(query url.Values) RequestOption
- type Uploader
- func (u *Uploader) AddField(key, value string) error
- func (u *Uploader) AddFile(key, filename string) error
- func (u *Uploader) AddFileSource(key, filename string, source io.Reader) error
- func (u *Uploader) Upload(ctx context.Context, method, urlpath string, opts ...RequestOption) (*http.Response, error)
Constants ¶
This section is empty.
Variables ¶
var NoOption = func(c *Client) { c.opts = make([]Option, 0) }
NoOption is a helper function that clears the previous options in the chain. See `Client.Clone` method.
Functions ¶
func BindResponse ¶
BindResponse consumes the response's body and binds the result to the "dest" pointer, closing the response's body is up to the caller.
The "dest" will be binded based on the response's content type header. Note that this is strict in order to catch bad actioners fast, e.g. it wont try to read plain text if not specified on the response headers and the dest is a *string.
func Debug ¶
func Debug(c *Client)
Debug enables the client's debug logger. It fires right before request is created and right after a response from the server is received.
Example Output for request:
[DBUG] 2022/03/01 21:54 Iris HTTP Client: POST / HTTP/1.1
Host: 127.0.0.1:50948
User-Agent: Go-http-client/1.1
Content-Length: 22
Accept: application/json
Content-Type: application/json
Accept-Encoding: gzip
{"firstname":"Makis"}
Example Output for response:
[DBUG] 2022/03/01 21:54 Iris HTTP Client: HTTP/1.1 200 OK
Content-Length: 27
Content-Type: application/json; charset=utf-8
Date: Tue, 01 Mar 2022 19:54:03 GMT
{
"firstname": "Makis"
}
func DecodeError ¶
DecodeError binds a json error to the "destPtr".
func GetErrorCode ¶
GetErrorCode reads an error, which should be a type of APIError, and returns its status code. If the given "err" is nil or is not an APIError it returns 200, acting as we have no error.
func RegisterRequestHandler ¶
func RegisterRequestHandler(reqHandlers ...RequestHandler)
RegisterRequestHandler registers one or more request handlers to be ran before and after of each request on all newly created Iris HTTP Clients. Useful for Iris HTTP Client 3rd-party libraries e.g. on init register a custom request-response lifecycle logging.
Types ¶
type APIError ¶
type APIError struct {
Response *http.Response
Body json.RawMessage // may be any []byte, response body is closed at this point.
}
APIError errors that may return from the Client.
func ExtractError ¶
ExtractError returns the response wrapped inside an APIError.
type Client ¶
type Client struct {
HTTPClient *http.Client
// BaseURL prepends to all requests.
BaseURL string
// A list of persistent request options.
PersistentRequestOptions []RequestOption
// contains filtered or unexported fields
}
A Client is an HTTP client. Initialize with the New package-level function.
func New ¶
New returns a new Iris HTTP Client. Available options: - BaseURL - Timeout - PersistentRequestOptions - RateLimit
Look the Client.Do/JSON/... methods to send requests and ReadXXX methods to read responses.
The default content type to send and receive data is JSON.
func (*Client) Clone ¶ added in v12.2.9
Clone returns a new Client with the same options as the original. If you want to override the options from the base "c" Client, use the `NoOption` variable as the 1st argument.
func (*Client) Do ¶
func (c *Client) Do(ctx context.Context, method, urlpath string, payload interface{}, opts ...RequestOption) (*http.Response, error)
Do sends an HTTP request and returns an HTTP response.
The payload can be: - io.Reader - raw []byte - JSON raw message - string - struct (JSON).
If method is empty then it defaults to "GET". The final variadic, optional input argument sets the custom request options to use before the request.
Any HTTP returned error will be of type APIError or a timeout error if the given context was canceled.
func (*Client) DrainResponseBody ¶
DrainResponseBody drains response body and close it, allowing the transport to reuse TCP connections. It's automatically called on Client.ReadXXX methods on the end.
func (*Client) Form ¶
func (c *Client) Form(ctx context.Context, method, urlpath string, formValues url.Values, opts ...RequestOption) (*http.Response, error)
JSON writes form data to the server.
func (*Client) GetPlainUnquote ¶
func (c *Client) GetPlainUnquote(ctx context.Context, method, urlpath string, payload interface{}, opts ...RequestOption) (string, error)
GetPlainUnquote reads the response body as raw text and tries to unquote it, useful when the remote server sends a single key as a value but due to backend mistake it sends it as JSON (quoted) instead of plain text.
func (*Client) JSON ¶
func (c *Client) JSON(ctx context.Context, method, urlpath string, payload interface{}, opts ...RequestOption) (*http.Response, error)
JSON writes data as JSON to the server.
func (*Client) NewUploader ¶
NewUploader returns a structure which is responsible for sending file and form data to the server.
func (*Client) ReadJSON ¶
func (c *Client) ReadJSON(ctx context.Context, dest interface{}, method, urlpath string, payload interface{}, opts ...RequestOption) error
ReadJSON binds "dest" to the response's body. After this call, the response body reader is closed.
func (*Client) ReadPlain ¶
func (c *Client) ReadPlain(ctx context.Context, dest interface{}, method, urlpath string, payload interface{}, opts ...RequestOption) error
ReadPlain like ReadJSON but it accepts a pointer to a string or byte slice or integer and it reads the body as plain text.
func (*Client) RegisterRequestHandler ¶
func (c *Client) RegisterRequestHandler(reqHandlers ...RequestHandler)
RegisterRequestHandler registers one or more request handlers to be ran before and after of each new request.
Request handler's BeginRequest method run after each request constructed and right before sent to the server.
Request handler's EndRequest method run after response each received and right before methods return back to the caller.
Any request handlers MUST be set right after the Client's initialization.
func (*Client) WriteTo ¶
func (c *Client) WriteTo(ctx context.Context, dest io.Writer, method, urlpath string, payload interface{}, opts ...RequestOption) (int64, error)
WriteTo reads the response and then copies its data to the "dest" writer. If the "dest" is a type of HTTP response writer then it writes the content-type and content-length of the original request.
Returns the amount of bytes written to "dest".
type Option ¶
type Option = func(*Client)
func BaseURL ¶
BaseURL registers the base URL of this client. All of its methods will prepend this url.
func Handler ¶
Handler specifies an iris.Application or any http.Handler instance which can be tested using this Client.
It registers a custom HTTP client transport which allows "fake calls" to the "h" server. Use it for testing.
func PersistentRequestOptions ¶
func PersistentRequestOptions(reqOpts ...RequestOption) Option
PersistentRequestOptions adds one or more persistent request options that all requests made by this Client will respect.
type RequestHandler ¶
type RequestHandler interface {
BeginRequest(context.Context, *http.Request) error
EndRequest(context.Context, *http.Response, error) error
}
RequestHandler can be set to each Client instance and it should be responsible to handle the begin and end states of each request. Its BeginRequest fires right before the client talks to the server and its EndRequest fires right after the client receives a response from the server. If one of them return a non-nil error then the execution of client will stop and return that error.
type RequestOption ¶
RequestOption declares the type of option one can pass to the Do methods(JSON, Form, ReadJSON...). Request options run before request constructed.
func RequestAuthorization ¶
func RequestAuthorization(value string) RequestOption
RequestAuthorization sets an Authorization request header. Note that we could do the same with a Transport RoundDrip too.
func RequestAuthorizationBearer ¶
func RequestAuthorizationBearer(accessToken string) RequestOption
RequestAuthorizationBearer sets an Authorization: Bearer $token request header.
func RequestHeader ¶
func RequestHeader(overridePrev bool, key string, values ...string) RequestOption
RequestHeader adds or sets (if overridePrev is true) a header to the request.
func RequestParam ¶
func RequestParam(key string, values ...string) RequestOption
RequestParam sets a single URL query parameter to the request.
func RequestQuery ¶
func RequestQuery(query url.Values) RequestOption
RequestQuery adds a set of URL query parameters to the request.
type Uploader ¶
Uploader holds the necessary information for upload requests.
Look the Client.NewUploader method.
func (*Uploader) AddFileSource ¶
AddFileSource adds a form file to the uploader with the given key.
Source Files