README
¶
HTTP Client
HTTP Client is a simple HTTP/2 client for Go.
package main
import (
"context"
"net/http"
"net/url"
"github.com/kataras/httpclient"
)
// The BaseURL of our API client.
const BaseURL = "https://api.weatherapi.com/v1"
type (
Options struct {
APIKey string `json:"api_key" yaml:"APIKey" toml:"APIKey"`
}
Client struct {
*httpclient.Client
}
)
func NewClient(opts Options) *Client {
apiKeyParameterSetter := httpclient.RequestParam("key", opts.APIKey)
c := httpclient.New(
httpclient.BaseURL(BaseURL),
httpclient.PersistentRequestOptions(apiKeyParameterSetter),
)
return &Client{c}
}
func (c *Client) GetCurrentByCity(ctx context.Context, city string) (resp Response, err error) {
urlpath := "/current.json"
// ?q=Athens&aqi=no
params := httpclient.RequestQuery(url.Values{
"q": []string{city},
"aqi": []string{"no"},
})
err = c.Client.ReadJSON(ctx, &resp, http.MethodGet, urlpath, nil, params)
return
}
Some of the features HTTP Client offers:
- Rate Limit
- Middleware
- JSON (read & write)
- Forms
- File Upload
- Plain Text
- Debug and more...
📖 Learning HTTP Client
Installation
The only requirement is the Go Programming Language.
Create a new project
$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/httpclient
Install on existing project
$ cd myapp
$ go get github.com/kataras/httpclient
Run
$ go mod tidy
$ go run .
Navigate through _examples folder for more.
📝 License
This project is licensed under the MIT License.
Documentation
¶
Index ¶
- Variables
- func BindResponse(resp *http.Response, dest any) (err error)
- func DecodeError(err error, destPtr any) error
- func DrainResponseBody(resp *http.Response) (err 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 any, ...) (*http.Response, error)
- func (c *Client) DrainResponseBody(resp *http.Response) error
- 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 any, ...) (string, error)
- func (c *Client) JSON(ctx context.Context, method, urlpath string, payload any, ...) (*http.Response, error)
- func (c *Client) NewUploader() *Uploader
- func (c *Client) ReadJSON(ctx context.Context, dest any, method, urlpath string, payload any, ...) error
- func (c *Client) ReadPlain(ctx context.Context, dest any, method, urlpath string, payload any, ...) error
- func (c *Client) RegisterRequestHandler(reqHandlers ...RequestHandler)
- func (c *Client) WriteTo(ctx context.Context, dest io.Writer, method, urlpath string, payload any, ...) (int64, error)
- type DebugLogger
- type Option
- func BaseURL(uri string) Option
- func Debug(logger DebugLogger) Option
- func DialTimeout(timeout time.Duration) Option
- func Handler(h http.Handler) Option
- func PersistentRequestOptions(reqOpts ...RequestOption) Option
- func RateLimit(requestsPerSecond int) Option
- func Timeout(timeout time.Duration) Option
- type RequestHandler
- type RequestOption
- func ClientTrace(clientTrace *httptrace.ClientTrace) 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 IsErrEmptyJSON = func(err error) bool { if err == nil { return false } if errors.Is(err, io.EOF) { return true } if v, ok := err.(*json.SyntaxError); ok { return v.Offset == 0 && v.Error() == "unexpected end of JSON input" } errMsg := err.Error() return strings.Contains(errMsg, "readObjectStart: expect {") || strings.Contains(errMsg, "readArrayStart: expect [") }
IsErrEmptyJSON reports whether the given "err" is caused by a Client.ReadJSON call when the request body was empty or didn't start with { or [.
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 DecodeError ¶
DecodeError binds a json error to the "destPtr".
func DrainResponseBody ¶ added in v0.0.3
DrainResponseBody drains response body and close it, allowing the transport to reuse TCP connections.
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 HTTP Clients. Useful for 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 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 v0.0.5
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 any, 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 any, 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 any, 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 any, method, urlpath string, payload any, opts ...RequestOption) error
ReadJSON binds "dest" to the response's body. After this call, the response body reader is closed.
If the response status code is >= 400 then it returns an APIError. If the response body is expected empty sometimes, you can omit the error through IsErrEmptyJSON.
func (*Client) ReadPlain ¶
func (c *Client) ReadPlain(ctx context.Context, dest any, method, urlpath string, payload any, 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 any, 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 DebugLogger ¶
type DebugLogger interface {
Debugf(string, ...interface{})
}
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 Debug ¶
func Debug(logger DebugLogger) Option
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 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 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 DialTimeout ¶ added in v0.0.9
DialTimeout specifies a time limit for creating connections by this Client. It is the maximum amount of time a dial will wait for a connect to complete. If the connection establishing process takes longer than this value, the dial will be cancelled.
The timeout includes name resolution, if required. When using TCP, and the host in the address parameter resolves to multiple IP addresses, the timeout is spread over each consecutive dial, such that each is given an appropriate fraction of the time to connect.
It overrides the Client's Transport field and the default http.Transport's Dial field, so it can't be used side by side with options like `Handler`.
func Handler ¶
Handler specifies an 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 ClientTrace ¶ added in v0.0.4
func ClientTrace(clientTrace *httptrace.ClientTrace) RequestOption
ClientTrace adds a client trace to the request.
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