README
¶
Fetch - HTTP Client
HTTP Client for Go, inspired by the Fetch API, and Axios + Got (Sindre Sorhus).
Features
Main API
- Make HTTP requests
- Easy JSON Response
- GZip support
- Decode GZip response
- Encode GZip request (Upload File with GZip)
- HTTP/2 support
- TLS
- Custom TLS Ca Certificate (Self signed certificate) Example
- Custom Client Cert and Key for two-way authentication (Client Cert and Key)
- Custom TLS Ca Certificate (Self signed certificate) Example
- Simple Auth Methods
- Basic Auth
- Bearer Auth
- Support cancel (using context)
Timeouts and retries
- Support timeout
- Support retry on failure
Progress
- Support progress and progress events
File upload and download
- Download files easily
- Upload files easily
Cache, Proxy and UNIX sockets
- RFC compliant caching
- Proxy support
- Environment variables (HTTP_PROXY/HTTPS_PROXY/SOCKS_PROXY)
- Custom proxy
- UNIX Domain Sockets
WebDAV
- WebDAV protocol support
Advanced creation
- Plugin system
- Middleware system
Installation
To install the package, run:
go get github.com/go-zoox/fetch
Methods
- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
- OPTIONS
- TRACE
- CONNECT
Getting Started
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, _ := fetch.Get("https://httpbin.zcorky.com/get")
url := response.Get("url")
method := response.Get("method")
fmt.Println(url, method)
}
Examples
Get
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Get("https://httpbin.zcorky.com/get")
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Post
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, _ := fetch.Post("https://httpbin.zcorky.com/post", &fetch.Config{
Body: map[string]interface{}{
"foo": "bar",
"foo2": "bar2",
"number": 1,
"boolean": true,
"array": []string{
"foo3",
"bar3",
},
"nest": map[string]string{
"foo4": "bar4",
},
},
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Put
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Put("https://httpbin.zcorky.com/put", &fetch.Config{
Body: map[string]interface{}{
"foo": "bar",
"foo2": "bar2",
"number": 1,
"boolean": true,
"array": []string{
"foo3",
"bar3",
},
"nest": map[string]string{
"foo4": "bar4",
},
},
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Delete
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Delete("https://httpbin.zcorky.com/Delete", &fetch.Config{
Body: map[string]interface{}{
"foo": "bar",
"foo2": "bar2",
"number": 1,
"boolean": true,
"array": []string{
"foo3",
"bar3",
},
"nest": map[string]string{
"foo4": "bar4",
},
},
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Timeout
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Get("https://httpbin.zcorky.com/get", &fetch.Config{
Timeout: 5 * time.Second,
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Proxy
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Get("https://httpbin.zcorky.com/ip", &fetch.Config{
Proxy: "http://127.0.0.1:17890",
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Basic Auth
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Get("https://httpbin.zcorky.com/ip", &fetch.Config{
BasicAuth: &fetch.BasicAuth{
Username: "foo",
Password: "bar",
},
})
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Download
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
response, err := fetch.Download("https://httpbin.zcorky.com/image", "/tmp/image.webp")
if err != nil {
panic(err)
}
}
Upload
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
file, _ := os.Open("go.mod")
response, err := Upload("https://httpbin.zcorky.com/upload", file)
if err != nil {
panic(err)
}
fmt.Println(response.JSON())
}
Cancel
package main
import (
"github.com/go-zoox/fetch"
)
func main() {
file, _ := os.Open("go.mod")
ctx, cancel := context.WithCancel(context.Background())
f := fetch.New()
f.SetBaseURL("https://httpbin.zcorky.com")
f.SetURL("/delay/3")
f.SetContext(ctx)
go func() {
_, err := f.Execute()
fmt.Println(err)
}()
cancel()
}
Depencencies
- gjson - Get JSON Whenever You Need, you don't define type first。
Inspired By
- sindresorhus/got - 🌐 Human-friendly and powerful HTTP request library for Node.js
- axios/axios - Promise based HTTP client for the browser and node.js
- mozillazg/request - A developer-friendly HTTP request library for Gopher
- monaco-io/request - go request, go http client
License
GoZoox is released under the MIT License.
Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultUserAgent() string
- func SetBaseURL(url string)
- func SetTimeout(timeout time.Duration)
- func SetUserAgent(userAgent string)
- type BasicAuth
- type Body
- type Config
- type DataSource
- type Fetch
- func (f *Fetch) Clone() *Fetch
- func (f *Fetch) Config() (*Config, error)
- func (f *Fetch) Delete(url string, config ...*Config) *Fetch
- func (f *Fetch) Download(url string, filepath string, config ...*Config) *Fetch
- func (f *Fetch) Execute() (*Response, error)
- func (f *Fetch) Get(url string, config ...*Config) *Fetch
- func (f *Fetch) Head(url string, config ...*Config) *Fetch
- func (f *Fetch) Patch(url string, config ...*Config) *Fetch
- func (f *Fetch) Post(url string, config ...*Config) *Fetch
- func (f *Fetch) Put(url string, config ...*Config) *Fetch
- func (f *Fetch) Retry(before func(f *Fetch)) (*Response, error)
- func (f *Fetch) Send() (*Response, error)
- func (f *Fetch) SetAccept(accept string) *Fetch
- func (f *Fetch) SetAcceptEncoding(acceptEncoding string) *Fetch
- func (f *Fetch) SetAcceptLanguage(acceptLanguage string) *Fetch
- func (f *Fetch) SetAuthorization(token string) *Fetch
- func (f *Fetch) SetBaseURL(url string) *Fetch
- func (f *Fetch) SetBasicAuth(username, password string) *Fetch
- func (f *Fetch) SetBearToken(token string) *Fetch
- func (f *Fetch) SetBody(body Body) *Fetch
- func (f *Fetch) SetCacheControl(cacheControl string) *Fetch
- func (f *Fetch) SetConfig(configs ...*Config) *Fetch
- func (f *Fetch) SetContentType(contentType string) *Fetch
- func (f *Fetch) SetContext(ctx context.Context) *Fetch
- func (f *Fetch) SetCookie(key, value string) *Fetch
- func (f *Fetch) SetDownloadFilePath(filepath string) *Fetch
- func (f *Fetch) SetHeader(key, value string) *Fetch
- func (f *Fetch) SetMethod(method string) *Fetch
- func (f *Fetch) SetParam(key, value string) *Fetch
- func (f *Fetch) SetProgressCallback(callback func(percent int64, current, total int64)) *Fetch
- func (f *Fetch) SetProxy(proxy string) *Fetch
- func (f *Fetch) SetQuery(key, value string) *Fetch
- func (f *Fetch) SetReferrer(referrer string) *Fetch
- func (f *Fetch) SetTimeout(timeout time.Duration) *Fetch
- func (f *Fetch) SetURL(url string) *Fetch
- func (f *Fetch) SetUserAgent(userAgent string) *Fetch
- func (f *Fetch) Stream(url string, config ...*Config) *Fetch
- func (f *Fetch) Upload(url string, file io.Reader, config ...*Config) *Fetch
- type Headers
- type OnProgress
- type Params
- type Progress
- type Query
- type Response
- func Delete(url string, config *Config) (*Response, error)
- func Download(url string, filepath string, config ...interface{}) (*Response, error)
- func Get(url string, config ...interface{}) (*Response, error)
- func Head(url string, config ...interface{}) (*Response, error)
- func Patch(url string, config *Config) (*Response, error)
- func Post(url string, config *Config) (*Response, error)
- func Put(url string, config *Config) (*Response, error)
- func Stream(url string, config ...interface{}) (*Response, error)
- func Upload(url string, file io.Reader, config ...interface{}) (*Response, error)
- func (r *Response) AcceptRanges() string
- func (r *Response) ContentEncoding() string
- func (r *Response) ContentLanguage() string
- func (r *Response) ContentLength() int
- func (r *Response) ContentType() string
- func (r *Response) Error() error
- func (r *Response) Get(key string) gjson.Result
- func (r *Response) JSON() (string, error)
- func (r *Response) Location() string
- func (r *Response) Ok() bool
- func (r *Response) SetCookie() string
- func (r *Response) StatusCode() int
- func (r *Response) StatusText() string
- func (r *Response) String() string
- func (r *Response) TransferEncoding() string
- func (r *Response) UnmarshalJSON(v interface{}) error
- func (r *Response) UnmarshalYAML(v interface{}) error
- func (r *Response) Value() gjson.Result
- func (r *Response) XPoweredBy() string
- func (r *Response) XRequestID() string
Constants ¶
const DELETE = "DELETE"
DELETE is request method DELETE
const EnvDEBUG = "GO_ZOOX_FETCH_DEBUG"
EnvDEBUG is the DEBUG env name
const GET = "GET"
GET is request method GET
const HEAD = "HEAD"
HEAD is request method HEAD
const PATCH = "PATCH"
PATCH is request method PATCH
const POST = "POST"
POST is request method POST
const PUT = "PUT"
PUT is request method PUT
Variables ¶
var BaseURL = ""
BaseURL is the default base url
var ErrCannotCopyFile = errors.New("cannot copy file")
ErrCannotCopyFile is the error when the file cannot be copied
var ErrCannotCreateFormFile = errors.New("cannot create form file")
ErrCannotCreateFormFile is the error when the form file cannot be created
var ErrCannotCreateRequest = errors.New("cannot create request")
ErrCannotCreateRequest is the error when the request cannot be created
var ErrCannotSendBodyWithGet = errors.New("cannot send body with GET method")
ErrCannotSendBodyWithGet is the error when the body cannot be sent with GET method
var ErrCookieEmptyKey = errors.New("empty key")
ErrCookieEmptyKey is the error when the key is empty
var ErrInvalidBodyMultipart = errors.New("invalid body multipart")
ErrInvalidBodyMultipart is the error when the body is invalid for multipart
var ErrInvalidContentType = errors.New("invalid content type")
ErrInvalidContentType is the error when the content type is invalid
var ErrInvalidJSONBody = errors.New("error marshalling body")
ErrInvalidJSONBody is the error when the body is not a valid JSON
var ErrInvalidMethod = errors.New("invalid method")
ErrInvalidMethod is the error when the method is invalid
var ErrInvalidURLFormEncodedBody = errors.New("invalid url form encoded body")
ErrInvalidURLFormEncodedBody is the error when the body is invalid for url form encoded
var ErrReadingResponse = errors.New("error reading response")
ErrReadingResponse is the error when the response cannot be read
var ErrSendingRequest = errors.New("error sending request")
ErrSendingRequest is the error when the request cannot be sent
var ErrTooManyArguments = errors.New("too many arguments")
ErrTooManyArguments is the error when the number of arguments is too many
var ErrorInvalidBody = errors.New("invalid body")
ErrorInvalidBody is the error when the body is invalid
METHODS is the list of supported methods
var Timeout = 60 * time.Second
Timeout is the default timeout
var UserAgent = fmt.Sprintf("GoFetch/%s (github.com/go-zoox/fetch)", Version)
UserAgent is the default user agent
var Version = "1.8.1"
Version is the version of this package
Functions ¶
func DefaultUserAgent ¶
func DefaultUserAgent() string
DefaultUserAgent returns the default user agent
Types ¶
type Config ¶
type Config struct {
URL string
Method string
Headers Headers
Query Query
Params Params
Body Body
//
BaseURL string
Timeout time.Duration
//
DownloadFilePath string
//
Proxy string
//
IsStream bool
//
IsSession bool
//
HTTP2 bool
// TLS Ca Cert
TLSCaCert []byte
TLSCaCertFile string
// TLS Cert
TLSCert []byte
TLSCertFile string
// TLS Client Private Key
TLSKey []byte
TLSKeyFile string
// TLSInsecureSkipVerify means ignore verify tls certificate
// use carefully, becuase it may cause security problems,
// which means maybe server certificate has been hacked
TLSInsecureSkipVerify bool
// UnixDomainSocket socket like /var/run/docker.sock
UnixDomainSocket string
//
Context context.Context
//
OnProgress OnProgress
//
BasicAuth BasicAuth
//
Username string
Password string
}
Config is the configuration for the fetch
type DataSource ¶ added in v1.1.0
DataSource defines the interface for loading data from a data source.
type Fetch ¶
type Fetch struct {
Errors []error
// contains filtered or unexported fields
}
Fetch is the Fetch Client
func Create ¶ added in v1.4.0
Create creates a new fetch with base url Specially useful for Client SDK
func (*Fetch) SetAcceptEncoding ¶ added in v1.4.0
SetAcceptEncoding sets the accept encoding
func (*Fetch) SetAcceptLanguage ¶ added in v1.4.0
SetAcceptLanguage sets the accept language
func (*Fetch) SetAuthorization ¶ added in v1.1.1
SetAuthorization sets the authorization token
func (*Fetch) SetBaseURL ¶
SetBaseURL sets the base url
func (*Fetch) SetBasicAuth ¶ added in v1.1.1
SetBasicAuth sets the basic auth username and password
func (*Fetch) SetBearToken ¶ added in v1.1.1
SetBearToken sets the bear token
func (*Fetch) SetCacheControl ¶ added in v1.4.0
SetCacheControl sets the cache control
func (*Fetch) SetContentType ¶ added in v1.4.0
SetContentType ...
func (*Fetch) SetContext ¶ added in v1.5.1
SetContext sets the context
func (*Fetch) SetDownloadFilePath ¶ added in v1.1.8
SetDownloadFilePath sets the download file path
func (*Fetch) SetProgressCallback ¶ added in v1.5.4
SetProgressCallback sets the progress callback
func (*Fetch) SetProxy ¶ added in v1.2.0
SetProxy sets the proxy
support http, https, socks5 example: http://127.0.0.1:17890 https://127.0.0.1:17890 socks5://127.0.0.1:17890
func (*Fetch) SetReferrer ¶ added in v1.4.0
SetReferrer sets the referrer
func (*Fetch) SetTimeout ¶
SetTimeout sets the timeout
func (*Fetch) SetUserAgent ¶
SetUserAgent sets the user agent
type Headers ¶ added in v1.4.3
Headers is the headers of the request
type OnProgress ¶ added in v1.8.0
OnProgress is the progress callback
func (*OnProgress) MarshalJSON ¶ added in v1.8.0
func (op *OnProgress) MarshalJSON() ([]byte, error)
MarshalJSON returns the json string
func (*OnProgress) UnmarshalJSON ¶ added in v1.8.0
func (op *OnProgress) UnmarshalJSON(data []byte) error
UnmarshalJSON unmarshals the json string
type Params ¶ added in v1.4.3
Params is the params of the request
type Progress ¶ added in v1.5.4
type Progress struct {
Reporter func(percent int64, current, total int64)
Total int64
Current int64
}
Progress is a progress event
type Query ¶ added in v1.4.3
Query is the query of the request
type Response ¶
type Response struct {
Status int
Headers http.Header
Body []byte
//
Request *Config
//
Stream io.ReadCloser
// contains filtered or unexported fields
}
Response is the fetch response
func (*Response) AcceptRanges ¶ added in v1.4.9
AcceptRanges returns x-accept-ranges of the response
func (*Response) ContentEncoding ¶ added in v1.4.4
ContentEncoding returns content encoding of the response
func (*Response) ContentLanguage ¶ added in v1.4.4
ContentLanguage returns content language of the response
func (*Response) ContentLength ¶ added in v1.4.4
ContentLength returns content length of the response
func (*Response) ContentType ¶ added in v1.4.4
ContentType returns content type of the response
func (*Response) StatusCode ¶ added in v1.4.4
StatusCode returns status code of the response
func (*Response) StatusText ¶ added in v1.4.4
StatusText returns status text of the response
func (*Response) TransferEncoding ¶ added in v1.4.4
TransferEncoding returns transfer encoding of the response
func (*Response) UnmarshalJSON ¶ added in v1.1.4
UnmarshalJSON unmarshals body to json struct
@TODO bug when lint (go vet) method UnmarshalJSON(v interface{}) error should have signature UnmarshalJSON([]byte) error
func (*Response) UnmarshalYAML ¶ added in v1.1.4
UnmarshalYAML unmarshals body to yaml struct
func (*Response) XPoweredBy ¶ added in v1.4.4
XPoweredBy returns x-powered-by of the response
func (*Response) XRequestID ¶ added in v1.4.4
XRequestID returns x-request-id of the response
Source Files