gonextcloud/vendor/github.com/levigross/grequests/README.md

777 lines
24 KiB
Markdown
Raw Permalink Normal View History

# GRequests
A Go "clone" of the great and famous Requests library
[![Build Status](https://travis-ci.org/levigross/grequests.svg?branch=master)](https://travis-ci.org/levigross/grequests) [![GoDoc](https://godoc.org/github.com/levigross/grequests?status.svg)](https://godoc.org/github.com/levigross/grequests)
[![Coverage Status](https://coveralls.io/repos/levigross/grequests/badge.svg)](https://coveralls.io/r/levigross/grequests)
[![Join the chat at https://gitter.im/levigross/grequests](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/levigross/grequests?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
License
======
GRequests is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text
Features
========
- Responses can be serialized into JSON and XML
- Easy file uploads
- Easy file downloads
- Support for the following HTTP verbs `GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS`
Install
=======
`go get -u github.com/levigross/grequests`
Usage
======
`import "github.com/levigross/grequests"`
Basic Examples
=========
Basic GET request:
```go
resp, err := grequests.Get("http://httpbin.org/get", nil)
// You can modify the request by passing an optional RequestOptions struct
if err != nil {
log.Fatalln("Unable to make request: ", err)
}
fmt.Println(resp.String())
// {
// "args": {},
// "headers": {
// "Accept": "*/*",
// "Host": "httpbin.org",
```
If an error occurs all of the other properties and methods of a `Response` will be `nil`
Quirks
=======
## Request Quirks
When passing parameters to be added to a URL, if the URL has existing parameters that *_contradict_* with what has been passed within `Params` `Params` will be the "source of authority" and overwrite the contradicting URL parameter.
Lets see how it works...
```go
ro := &RequestOptions{
Params: map[string]string{"Hello": "Goodbye"},
}
Get("http://httpbin.org/get?Hello=World", ro)
// The URL is now http://httpbin.org/get?Hello=Goodbye
```
## Response Quirks
Order matters! This is because `grequests.Response` is implemented as an `io.ReadCloser` which proxies the *http.Response.Body* `io.ReadCloser` interface. It also includes an internal buffer for use in `Response.String()` and `Response.Bytes()`.
Here are a list of methods that consume the *http.Response.Body* `io.ReadCloser` interface.
- Response.JSON
- Response.XML
- Response.DownloadToFile
- Response.Close
- Response.Read
The following methods make use of an internal byte buffer
- Response.String
- Response.Bytes
In the code below, once the file is downloaded the `Response` struct no longer has access to the request bytes
```go
response := Get("http://some-wonderful-file.txt", nil)
if err := response.DownloadToFile("randomFile"); err != nil {
log.Println("Unable to download file: ", err)
}
// At this point the .String and .Bytes method will return empty responses
response.Bytes() == nil // true
response.String() == "" // true
```
But if we were to call `response.Bytes()` or `response.String()` first, every operation will succeed until the internal buffer is cleared:
```go
response := Get("http://some-wonderful-file.txt", nil)
// This call to .Bytes caches the request bytes in an internal byte buffer which can be used again and again until it is cleared
response.Bytes() == `file-bytes`
response.String() == "file-string"
// This will work because it will use the internal byte buffer
if err := resp.DownloadToFile("randomFile"); err != nil {
log.Println("Unable to download file: ", err)
}
// Now if we clear the internal buffer....
response.ClearInternalBuffer()
// At this point the .String and .Bytes method will return empty responses
response.Bytes() == nil // true
response.String() == "" // true
```
# grequests
`import "github.com/levigross/grequests"`
* [Overview](#pkg-overview)
* [Index](#pkg-index)
* [Examples](#pkg-examples)
## <a name="pkg-overview">Overview</a>
Package grequests implements a friendly API over Go's existing net/http library
## <a name="pkg-index">Index</a>
* [Variables](#pkg-variables)
* [func BuildHTTPClient(ro RequestOptions) *http.Client](#BuildHTTPClient)
* [func EnsureTransporterFinalized(httpTransport *http.Transport)](#EnsureTransporterFinalized)
* [func FileUploadFromDisk(fileName string) ([]FileUpload, error)](#FileUploadFromDisk)
* [func FileUploadFromGlob(fileSystemGlob string) ([]FileUpload, error)](#FileUploadFromGlob)
* [type FileUpload](#FileUpload)
* [type RequestOptions](#RequestOptions)
* [type Response](#Response)
* [func Delete(url string, ro *RequestOptions) (*Response, error)](#Delete)
* [func Get(url string, ro *RequestOptions) (*Response, error)](#Get)
* [func Head(url string, ro *RequestOptions) (*Response, error)](#Head)
* [func Options(url string, ro *RequestOptions) (*Response, error)](#Options)
* [func Patch(url string, ro *RequestOptions) (*Response, error)](#Patch)
* [func Post(url string, ro *RequestOptions) (*Response, error)](#Post)
* [func Put(url string, ro *RequestOptions) (*Response, error)](#Put)
* [func (r *Response) Bytes() []byte](#Response.Bytes)
* [func (r *Response) ClearInternalBuffer()](#Response.ClearInternalBuffer)
* [func (r *Response) Close() error](#Response.Close)
* [func (r *Response) DownloadToFile(fileName string) error](#Response.DownloadToFile)
* [func (r *Response) JSON(userStruct interface{}) error](#Response.JSON)
* [func (r *Response) Read(p []byte) (n int, err error)](#Response.Read)
* [func (r *Response) String() string](#Response.String)
* [func (r *Response) XML(userStruct interface{}, charsetReader XMLCharDecoder) error](#Response.XML)
* [type Session](#Session)
* [func NewSession(ro *RequestOptions) *Session](#NewSession)
* [func (s *Session) CloseIdleConnections()](#Session.CloseIdleConnections)
* [func (s *Session) Delete(url string, ro *RequestOptions) (*Response, error)](#Session.Delete)
* [func (s *Session) Get(url string, ro *RequestOptions) (*Response, error)](#Session.Get)
* [func (s *Session) Head(url string, ro *RequestOptions) (*Response, error)](#Session.Head)
* [func (s *Session) Options(url string, ro *RequestOptions) (*Response, error)](#Session.Options)
* [func (s *Session) Patch(url string, ro *RequestOptions) (*Response, error)](#Session.Patch)
* [func (s *Session) Post(url string, ro *RequestOptions) (*Response, error)](#Session.Post)
* [func (s *Session) Put(url string, ro *RequestOptions) (*Response, error)](#Session.Put)
* [type XMLCharDecoder](#XMLCharDecoder)
#### <a name="pkg-examples">Examples</a>
* [Package (AcceptInvalidTLSCert)](#example__acceptInvalidTLSCert)
* [Package (BasicAuth)](#example__basicAuth)
* [Package (BasicGet)](#example__basicGet)
* [Package (BasicGetCustomHTTPClient)](#example__basicGetCustomHTTPClient)
* [Package (Cookies)](#example__cookies)
* [Package (CustomHTTPHeader)](#example__customHTTPHeader)
* [Package (CustomUserAgent)](#example__customUserAgent)
* [Package (DownloadFile)](#example__downloadFile)
* [Package (PostFileUpload)](#example__postFileUpload)
* [Package (PostForm)](#example__postForm)
* [Package (PostJSONAJAX)](#example__postJSONAJAX)
* [Package (PostXML)](#example__postXML)
* [Package (Proxy)](#example__proxy)
* [Package (Session)](#example__session)
* [Package (UrlQueryParams)](#example__urlQueryParams)
#### <a name="pkg-files">Package files</a>
[base.go](/src/github.com/levigross/grequests/base.go) [file_upload.go](/src/github.com/levigross/grequests/file_upload.go) [request.go](/src/github.com/levigross/grequests/request.go) [response.go](/src/github.com/levigross/grequests/response.go) [session.go](/src/github.com/levigross/grequests/session.go) [utils.go](/src/github.com/levigross/grequests/utils.go)
## <a name="pkg-variables">Variables</a>
``` go
var (
// ErrRedirectLimitExceeded is the error returned when the request responded
// with too many redirects
ErrRedirectLimitExceeded = errors.New("grequests: Request exceeded redirect count")
// RedirectLimit is a tunable variable that specifies how many times we can
// redirect in response to a redirect. This is the global variable, if you
// wish to set this on a request by request basis, set it within the
// `RequestOptions` structure
RedirectLimit = 30
// SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user
// doesn't want passed on a redirect. This is the global variable, if you
// wish to set this on a request by request basis, set it within the
// `RequestOptions` structure
SensitiveHTTPHeaders = map[string]struct{}{
"Www-Authenticate": {},
"Authorization": {},
"Proxy-Authorization": {},
}
)
```
## <a name="BuildHTTPClient">func</a> [BuildHTTPClient](/src/target/request.go?s=11478:11530#L405)
``` go
func BuildHTTPClient(ro RequestOptions) *http.Client
```
BuildHTTPClient is a function that will return a custom HTTP client based on the request options provided
the check is in UseDefaultClient
## <a name="EnsureTransporterFinalized">func</a> [EnsureTransporterFinalized](/src/target/utils.go?s=2482:2544#L79)
``` go
func EnsureTransporterFinalized(httpTransport *http.Transport)
```
EnsureTransporterFinalized will ensure that when the HTTP client is GCed
the runtime will close the idle connections (so that they won't leak)
this function was adopted from Hashicorp's go-cleanhttp package
## <a name="FileUploadFromDisk">func</a> [FileUploadFromDisk](/src/target/file_upload.go?s=625:687#L14)
``` go
func FileUploadFromDisk(fileName string) ([]FileUpload, error)
```
FileUploadFromDisk allows you to create a FileUpload struct slice by just specifying a location on the disk
## <a name="FileUploadFromGlob">func</a> [FileUploadFromGlob](/src/target/file_upload.go?s=1068:1136#L27)
``` go
func FileUploadFromGlob(fileSystemGlob string) ([]FileUpload, error)
```
FileUploadFromGlob allows you to create a FileUpload struct slice by just specifying a glob location on the disk
this function will gloss over all errors in the files and only upload the files that don't return errors from the glob
## <a name="FileUpload">type</a> [FileUpload](/src/target/file_upload.go?s=162:512#L2)
``` go
type FileUpload struct {
// Filename is the name of the file that you wish to upload. We use this to guess the mimetype as well as pass it onto the server
FileName string
// FileContents is happy as long as you pass it a io.ReadCloser (which most file use anyways)
FileContents io.ReadCloser
// FieldName is form field name
FieldName string
}
```
FileUpload is a struct that is used to specify the file that a User
wishes to upload.
## <a name="RequestOptions">type</a> [RequestOptions](/src/target/request.go?s=357:4258#L18)
``` go
type RequestOptions struct {
// Data is a map of key values that will eventually convert into the
// query string of a GET request or the body of a POST request.
Data map[string]string
// Params is a map of query strings that may be used within a GET request
Params map[string]string
// QueryStruct is a struct that encapsulates a set of URL query params
// this paramter is mutually exclusive with `Params map[string]string` (they cannot be combined)
// for more information please see https://godoc.org/github.com/google/go-querystring/query
QueryStruct interface{}
// Files is where you can include files to upload. The use of this data
// structure is limited to POST requests
Files []FileUpload
// JSON can be used when you wish to send JSON within the request body
JSON interface{}
// XML can be used if you wish to send XML within the request body
XML interface{}
// Headers if you want to add custom HTTP headers to the request,
// this is your friend
Headers map[string]string
// InsecureSkipVerify is a flag that specifies if we should validate the
// server's TLS certificate. It should be noted that Go's TLS verify mechanism
// doesn't validate if a certificate has been revoked
InsecureSkipVerify bool
// DisableCompression will disable gzip compression on requests
DisableCompression bool
// UserAgent allows you to set an arbitrary custom user agent
UserAgent string
// Host allows you to set an arbitrary custom host
Host string
// Auth allows you to specify a user name and password that you wish to
// use when requesting the URL. It will use basic HTTP authentication
// formatting the username and password in base64 the format is:
// []string{username, password}
Auth []string
// IsAjax is a flag that can be set to make the request appear
// to be generated by browser Javascript
IsAjax bool
// Cookies is an array of `http.Cookie` that allows you to attach
// cookies to your request
Cookies []*http.Cookie
// UseCookieJar will create a custom HTTP client that will
// process and store HTTP cookies when they are sent down
UseCookieJar bool
// Proxies is a map in the following format
// *protocol* => proxy address e.g http => http://127.0.0.1:8080
Proxies map[string]*url.URL
// TLSHandshakeTimeout specifies the maximum amount of time waiting to
// wait for a TLS handshake. Zero means no timeout.
TLSHandshakeTimeout time.Duration
// DialTimeout is the maximum amount of time a dial will wait for
// a connect to complete.
DialTimeout time.Duration
// KeepAlive specifies the keep-alive period for an active
// network connection. If zero, keep-alive are not enabled.
DialKeepAlive time.Duration
// RequestTimeout is the maximum amount of time a whole request(include dial / request / redirect)
// will wait.
RequestTimeout time.Duration
// HTTPClient can be provided if you wish to supply a custom HTTP client
// this is useful if you want to use an OAUTH client with your request.
HTTPClient *http.Client
// SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user
// doesn't want passed on a redirect.
SensitiveHTTPHeaders map[string]struct{}
// RedirectLimit is the acceptable amount of redirects that we should expect
// before returning an error be default this is set to 30. You can change this
// globally by modifying the `RedirectLimit` variable.
RedirectLimit int
// RequestBody allows you to put anything matching an `io.Reader` into the request
// this option will take precedence over any other request option specified
RequestBody io.Reader
// CookieJar allows you to specify a special cookiejar to use with your request.
// this option will take precedence over the `UseCookieJar` option above.
CookieJar http.CookieJar
// Context can be used to maintain state between requests https://golang.org/pkg/context/#Context
Context context.Context
}
```
RequestOptions is the location that of where the data
## <a name="Response">type</a> [Response](/src/target/response.go?s=181:806#L4)
``` go
type Response struct {
// Ok is a boolean flag that validates that the server returned a 2xx code
Ok bool
// This is the Go error flag if something went wrong within the request, this flag will be set.
Error error
// We want to abstract (at least at the moment) the Go http.Response object away. So we are going to make use of it
// internal but not give the user access
RawResponse *http.Response
// StatusCode is the HTTP Status Code returned by the HTTP Response. Taken from resp.StatusCode
StatusCode int
// Header is a net/http/Header structure
Header http.Header
// contains filtered or unexported fields
}
```
Response is what is returned to a user when they fire off a request
### <a name="Delete">func</a> [Delete](/src/target/base.go?s=1221:1283#L22)
``` go
func Delete(url string, ro *RequestOptions) (*Response, error)
```
Delete takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Get">func</a> [Get](/src/target/base.go?s=300:359#L1)
``` go
func Get(url string, ro *RequestOptions) (*Response, error)
```
Get takes 2 parameters and returns a Response Struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Head">func</a> [Head](/src/target/base.go?s=1841:1901#L38)
``` go
func Head(url string, ro *RequestOptions) (*Response, error)
```
Head takes 2 parameters and returns a Response channel. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Options">func</a> [Options](/src/target/base.go?s=2151:2214#L46)
``` go
func Options(url string, ro *RequestOptions) (*Response, error)
```
Options takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Patch">func</a> [Patch](/src/target/base.go?s=910:971#L14)
``` go
func Patch(url string, ro *RequestOptions) (*Response, error)
```
Patch takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Post">func</a> [Post](/src/target/base.go?s=1533:1593#L30)
``` go
func Post(url string, ro *RequestOptions) (*Response, error)
```
Post takes 2 parameters and returns a Response channel. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Put">func</a> [Put](/src/target/base.go?s=604:663#L6)
``` go
func Put(url string, ro *RequestOptions) (*Response, error)
```
Put takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
### <a name="Response.Bytes">func</a> (\*Response) [Bytes](/src/target/response.go?s=4298:4331#L169)
``` go
func (r *Response) Bytes() []byte
```
Bytes returns the response as a byte array
### <a name="Response.ClearInternalBuffer">func</a> (\*Response) [ClearInternalBuffer](/src/target/response.go?s=4920:4960#L198)
``` go
func (r *Response) ClearInternalBuffer()
```
ClearInternalBuffer is a function that will clear the internal buffer that we use to hold the .String() and .Bytes()
data. Once you have used these functions you may want to free up the memory.
### <a name="Response.Close">func</a> (\*Response) [Close](/src/target/response.go?s=1793:1825#L55)
``` go
func (r *Response) Close() error
```
Close is part of our ability to support io.ReadCloser if someone wants to make use of the raw body
### <a name="Response.DownloadToFile">func</a> (\*Response) [DownloadToFile](/src/target/response.go?s=2018:2074#L67)
``` go
func (r *Response) DownloadToFile(fileName string) error
```
DownloadToFile allows you to download the contents of the response to a file
### <a name="Response.JSON">func</a> (\*Response) [JSON](/src/target/response.go?s=3300:3353#L124)
``` go
func (r *Response) JSON(userStruct interface{}) error
```
JSON is a method that will populate a struct that is provided `userStruct` with the JSON returned within the
response body
### <a name="Response.Read">func</a> (\*Response) [Read](/src/target/response.go?s=1551:1603#L45)
``` go
func (r *Response) Read(p []byte) (n int, err error)
```
Read is part of our ability to support io.ReadCloser if someone wants to make use of the raw body
### <a name="Response.String">func</a> (\*Response) [String](/src/target/response.go?s=4568:4602#L186)
``` go
func (r *Response) String() string
```
String returns the response as a string
### <a name="Response.XML">func</a> (\*Response) [XML](/src/target/response.go?s=2792:2874#L101)
``` go
func (r *Response) XML(userStruct interface{}, charsetReader XMLCharDecoder) error
```
XML is a method that will populate a struct that is provided `userStruct` with the XML returned within the
response body
## <a name="Session">type</a> [Session](/src/target/session.go?s=125:314#L1)
``` go
type Session struct {
// RequestOptions is global options
RequestOptions *RequestOptions
// HTTPClient is the client that we will use to request the resources
HTTPClient *http.Client
}
```
Session allows a user to make use of persistent cookies in between
HTTP requests
### <a name="NewSession">func</a> [NewSession](/src/target/session.go?s=532:576#L8)
``` go
func NewSession(ro *RequestOptions) *Session
```
NewSession returns a session struct which enables can be used to maintain establish a persistent state with the
server
This function will set UseCookieJar to true as that is the purpose of using the session
### <a name="Session.CloseIdleConnections">func</a> (\*Session) [CloseIdleConnections](/src/target/session.go?s=4738:4778#L124)
``` go
func (s *Session) CloseIdleConnections()
```
CloseIdleConnections closes the idle connections that a session client may make use of
### <a name="Session.Delete">func</a> (\*Session) [Delete](/src/target/session.go?s=3120:3195#L88)
``` go
func (s *Session) Delete(url string, ro *RequestOptions) (*Response, error)
```
Delete takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Get">func</a> (\*Session) [Get](/src/target/session.go?s=1776:1848#L58)
``` go
func (s *Session) Get(url string, ro *RequestOptions) (*Response, error)
```
Get takes 2 parameters and returns a Response Struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Head">func</a> (\*Session) [Head](/src/target/session.go?s=4022:4095#L108)
``` go
func (s *Session) Head(url string, ro *RequestOptions) (*Response, error)
```
Head takes 2 parameters and returns a Response channel. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Options">func</a> (\*Session) [Options](/src/target/session.go?s=4473:4549#L118)
``` go
func (s *Session) Options(url string, ro *RequestOptions) (*Response, error)
```
Options takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Patch">func</a> (\*Session) [Patch](/src/target/session.go?s=2668:2742#L78)
``` go
func (s *Session) Patch(url string, ro *RequestOptions) (*Response, error)
```
Patch takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Post">func</a> (\*Session) [Post](/src/target/session.go?s=3573:3646#L98)
``` go
func (s *Session) Post(url string, ro *RequestOptions) (*Response, error)
```
Post takes 2 parameters and returns a Response channel. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
### <a name="Session.Put">func</a> (\*Session) [Put](/src/target/session.go?s=2221:2293#L68)
``` go
func (s *Session) Put(url string, ro *RequestOptions) (*Response, error)
```
Put takes 2 parameters and returns a Response struct. These two options are:
1. A URL
2. A RequestOptions struct
If you do not intend to use the `RequestOptions` you can just pass nil
A new session is created by calling NewSession with a request options struct
## <a name="XMLCharDecoder">type</a> [XMLCharDecoder](/src/target/utils.go?s=1529:1605#L42)
``` go
type XMLCharDecoder func(charset string, input io.Reader) (io.Reader, error)
```
XMLCharDecoder is a helper type that takes a stream of bytes (not encoded in
UTF-8) and returns a reader that encodes the bytes into UTF-8. This is done
because Go's XML library only supports XML encoded in UTF-8
- - -
Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)