gentleman: github.com/h2non/gentleman Index | Files | Directories

package gentleman

import "github.com/h2non/gentleman"

Index

Package Files

client.go dispatcher.go request.go response.go version.go

Constants

const (
    // UserAgent represents the static user agent name and version.
    UserAgent = "gentleman/" + Version
)
const Version = "2.0.3"

Version defines the package semantic version

Variables

var (
    // DialTimeout represents the maximum amount of time the network dialer can take.
    DialTimeout = 30 * time.Second

    // DialKeepAlive represents the maximum amount of time too keep alive the socket.
    DialKeepAlive = 30 * time.Second

    // TLSHandshakeTimeout represents the maximum amount of time that
    // TLS handshake can take defined in the default http.Transport.
    TLSHandshakeTimeout = 10 * time.Second

    // RequestTimeout represents the maximum about of time that
    // a request can take, including dial / request / redirect processes.
    RequestTimeout = 60 * time.Second

    // DefaultDialer defines the default network dialer.
    DefaultDialer = &net.Dialer{
        Timeout:   DialTimeout,
        KeepAlive: DialKeepAlive,
    }

    // DefaultTransport stores the default HTTP transport to be used.
    DefaultTransport = NewDefaultTransport(DefaultDialer)
)
var NewContext = context.New

NewContext is a convenient alias to context.New factory.

var NewHandler = context.NewHandler

NewHandler is a convenient alias to context.NewHandler factory.

var NewMiddleware = middleware.New

NewMiddleware is a convenient alias to middleware.New factory.

func NewDefaultTransport Uses

func NewDefaultTransport(dialer *net.Dialer) *http.Transport

NewDefaultTransport returns a new http.Transport with default values based on the given net.Dialer.

type Client Uses

type Client struct {
    // Client entity can inherit behavior from a parent Client.
    Parent *Client

    // Each Client entity has it's own Context that will be inherited by requests or child clients.
    Context *context.Context

    // Client entity has its own Middleware layer to compose and inherit behavior.
    Middleware middleware.Middleware
}

Client represents a high-level HTTP client entity capable with a built-in middleware and context.

func New Uses

func New() *Client

New creates a new high level client entity able to perform HTTP requests.

func (*Client) AddCookie Uses

func (c *Client) AddCookie(cookie *http.Cookie) *Client

AddCookie sets a new cookie field bsaed on the given http.Cookie struct without overwriting any existent cookie.

func (*Client) AddCookies Uses

func (c *Client) AddCookies(data []*http.Cookie) *Client

AddCookies sets a new cookie field based on a list of http.Cookie without overwriting any existent cookie.

func (*Client) AddHeader Uses

func (c *Client) AddHeader(name, value string) *Client

AddHeader adds a new header field by name and value without overwriting any existent header.

func (*Client) BaseURL Uses

func (c *Client) BaseURL(uri string) *Client

BaseURL defines the URL schema and host for client requests. Useful to define at client level the base URL used by client child requests.

func (*Client) CookieJar Uses

func (c *Client) CookieJar() *Client

CookieJar creates a cookie jar to store HTTP cookies when they are sent down.

func (*Client) Delete Uses

func (c *Client) Delete() *Request

Delete creates a new DELETE request.

func (*Client) Get Uses

func (c *Client) Get() *Request

Get creates a new GET request.

func (*Client) Head Uses

func (c *Client) Head() *Request

Head creates a new HEAD request.

func (*Client) Method Uses

func (c *Client) Method(name string) *Client

Method defines a the default HTTP method used by outgoing client requests.

func (*Client) Param Uses

func (c *Client) Param(name, value string) *Client

Param replaces a path param based on the given param name and value.

func (*Client) Params Uses

func (c *Client) Params(params map[string]string) *Client

Params replaces path params based on the given params key-value map.

func (*Client) Patch Uses

func (c *Client) Patch() *Request

Patch creates a new PATCH request.

func (*Client) Path Uses

func (c *Client) Path(path string) *Client

Path defines the URL base path for client requests.

func (*Client) Post Uses

func (c *Client) Post() *Request

Post creates a new POST request.

func (*Client) Put Uses

func (c *Client) Put() *Request

Put creates a new PUT request.

func (*Client) Request Uses

func (c *Client) Request() *Request

Request creates a new Request based on the current Client

func (*Client) SetHeader Uses

func (c *Client) SetHeader(key, value string) *Client

SetHeader sets a new header field by name and value. If another header exists with the same key, it will be overwritten.

func (*Client) SetHeaders Uses

func (c *Client) SetHeaders(fields map[string]string) *Client

SetHeaders adds new header fields based on the given map.

func (*Client) URL Uses

func (c *Client) URL(uri string) *Client

URL defines the URL for client requests. Useful to define at client level the base URL and base path used by child requests.

func (*Client) Use Uses

func (c *Client) Use(p plugin.Plugin) *Client

Use uses a new plugin to the middleware stack.

func (*Client) UseError Uses

func (c *Client) UseError(fn context.HandlerFunc) *Client

UseError uses a new middleware function for error phase.

func (*Client) UseHandler Uses

func (c *Client) UseHandler(phase string, fn context.HandlerFunc) *Client

UseHandler uses a new middleware function for the given phase.

func (*Client) UseParent Uses

func (c *Client) UseParent(parent *Client) *Client

UseParent uses another Client as parent inheriting its middleware stack and configuration.

func (*Client) UseRequest Uses

func (c *Client) UseRequest(fn context.HandlerFunc) *Client

UseRequest uses a new middleware function for request phase.

func (*Client) UseResponse Uses

func (c *Client) UseResponse(fn context.HandlerFunc) *Client

UseResponse uses a new middleware function for response phase.

type Dispatcher Uses

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

Dispatcher dispatches a given request triggering the middleware layer per specific phase and handling the request/response/error states accondingly.

func NewDispatcher Uses

func NewDispatcher(req *Request) *Dispatcher

NewDispatcher creates a new Dispatcher based on the given Context.

func (*Dispatcher) Dispatch Uses

func (d *Dispatcher) Dispatch() *c.Context

Dispatch triggers the middleware chains and performs the HTTP request.

type Request Uses

type Request struct {

    // Optional reference to the gentleman.Client instance
    Client *Client

    // Request scope Context instance
    Context *context.Context

    // Request scope Middleware instance
    Middleware middleware.Middleware
    // contains filtered or unexported fields
}

Request HTTP entity for gentleman. Provides middleware capabilities, built-in context and convenient methods to easily setup request params.

func NewRequest Uses

func NewRequest() *Request

NewRequest creates a new Request entity.

func (*Request) AddCookie Uses

func (r *Request) AddCookie(cookie *http.Cookie) *Request

AddCookie sets a new cookie field bsaed on the given http.Cookie struct without overwriting any existent cookie.

func (*Request) AddCookies Uses

func (r *Request) AddCookies(data []*http.Cookie) *Request

AddCookies sets a new cookie field based on a list of http.Cookie without overwriting any existent cookie.

func (*Request) AddHeader Uses

func (r *Request) AddHeader(name, value string) *Request

AddHeader adds a new header field by name and value without overwriting any existent header.

func (*Request) AddPath Uses

func (r *Request) AddPath(path string) *Request

AddPath defines the request URL path to be used in the outgoing request.

func (*Request) AddQuery Uses

func (r *Request) AddQuery(name, value string) *Request

AddQuery adds a new URL query param field without overwriting any existent query field.

func (*Request) BaseURL Uses

func (r *Request) BaseURL(uri string) *Request

BaseURL parses the given URL and uses the URL schema and host in the outgoing request.

func (*Request) Body Uses

func (r *Request) Body(reader io.Reader) *Request

Body defines the request body based on a io.Reader stream.

func (*Request) BodyString Uses

func (r *Request) BodyString(data string) *Request

BodyString defines the request body based on the given string. If using this method, you should define the proper Content-Type header representing the real content MIME type.

func (*Request) Clone Uses

func (r *Request) Clone() *Request

Clone creates a new side-effects free Request based on the current one.

func (*Request) CookieJar Uses

func (r *Request) CookieJar() *Request

CookieJar creates a cookie jar to store HTTP cookies when they are sent down.

func (*Request) DelHeader Uses

func (r *Request) DelHeader(name string) *Request

DelHeader deletes a header field by its name

func (*Request) Do Uses

func (r *Request) Do() (*Response, error)

Do performs the HTTP request and returns the HTTP response.

func (*Request) File Uses

func (r *Request) File(name string, reader io.Reader) *Request

File serializes and defines the request body as multipart/form-data containing one file field.

func (*Request) Files Uses

func (r *Request) Files(files []multipart.FormFile) *Request

Files serializes and defines the request body as multipart/form-data containing the given file fields.

func (*Request) Form Uses

func (r *Request) Form(data multipart.FormData) *Request

Form serializes and defines the request body as multipart/form-data based on the given form data.

func (*Request) JSON Uses

func (r *Request) JSON(data interface{}) *Request

JSON serializes and defines as request body based on the given input. The proper Content-Type header will be transparently added for you.

func (*Request) Method Uses

func (r *Request) Method(method string) *Request

Method defines the HTTP verb to be used.

func (*Request) Mux Uses

func (r *Request) Mux() *mux.Mux

Mux is a middleware multiplexer for easy plugin composition.

func (*Request) Param Uses

func (r *Request) Param(name, value string) *Request

Param replaces a path param based on the given param name and value.

func (*Request) Params Uses

func (r *Request) Params(params map[string]string) *Request

Params replaces path params based on the given params key-value map.

func (*Request) Path Uses

func (r *Request) Path(path string) *Request

Path defines the request URL path to be used in the outgoing request.

func (*Request) Send Uses

func (r *Request) Send() (*Response, error)

Send is an alias to Do(), which executes the current request and returns the response.

func (*Request) SetClient Uses

func (r *Request) SetClient(cli *Client) *Request

SetClient Attach a client to the current Request This is mostly done internally.

func (*Request) SetHeader Uses

func (r *Request) SetHeader(name, value string) *Request

SetHeader sets a new header field by name and value. If another header exists with the same key, it will be overwritten.

func (*Request) SetHeaders Uses

func (r *Request) SetHeaders(fields map[string]string) *Request

SetHeaders adds new header fields based on the given map.

func (*Request) SetQuery Uses

func (r *Request) SetQuery(name, value string) *Request

SetQuery sets a new URL query param field. If another query param exists with the same key, it will be overwritten.

func (*Request) SetQueryParams Uses

func (r *Request) SetQueryParams(params map[string]string) *Request

SetQueryParams sets URL query params based on the given map.

func (*Request) Type Uses

func (r *Request) Type(name string) *Request

Type defines the Content-Type header field based on the given type name alias or value. You can use the following content type aliases: json, xml, form, html, text and urlencoded.

func (*Request) URL Uses

func (r *Request) URL(uri string) *Request

URL parses and defines the URL to be used in the outgoing request.

func (*Request) Use Uses

func (r *Request) Use(p plugin.Plugin) *Request

Use uses a new plugin in the middleware stack.

func (*Request) UseError Uses

func (r *Request) UseError(fn context.HandlerFunc) *Request

UseError uses an error middleware handler.

func (*Request) UseHandler Uses

func (r *Request) UseHandler(phase string, fn context.HandlerFunc) *Request

UseHandler uses an new middleware handler for the given phase.

func (*Request) UseRequest Uses

func (r *Request) UseRequest(fn context.HandlerFunc) *Request

UseRequest uses a request middleware handler.

func (*Request) UseResponse Uses

func (r *Request) UseResponse(fn context.HandlerFunc) *Request

UseResponse uses a response middleware handler.

func (*Request) XML Uses

func (r *Request) XML(data interface{}) *Request

XML serializes and defines the request body based on the given input. The proper Content-Type header will be transparently added for you.

type Response Uses

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

    // Sugar to check if the response status code is a client error (4xx).
    ClientError bool

    // Sugar to check if the response status code is a server error (5xx).
    ServerError bool

    // StatusCode is the HTTP Status Code returned by the HTTP Response. Taken from resp.StatusCode.
    StatusCode int

    // Header stores the response headers as http.Header interface.
    Header http.Header

    // Cookies stores the parsed response cookies.
    Cookies []*http.Cookie

    // Expose the native Go http.Response object for convenience.
    RawResponse *http.Response

    // Expose the native Go http.Request object for convenience.
    RawRequest *http.Request

    // Expose original request Context for convenience.
    Context *context.Context
    // contains filtered or unexported fields
}

Response provides a more convenient and higher level Response struct. Implements an io.ReadCloser interface.

func (*Response) Bytes Uses

func (r *Response) Bytes() []byte

Bytes returns the response as a byte array.

func (*Response) ClearInternalBuffer Uses

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.

func (*Response) Close Uses

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.

func (*Response) JSON Uses

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.

func (*Response) Read Uses

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.

func (*Response) SaveToFile Uses

func (r *Response) SaveToFile(fileName string) error

SaveToFile allows you to download the contents of the response to a file.

func (*Response) String Uses

func (r *Response) String() string

String returns the response as a string.

func (*Response) XML Uses

func (r *Response) XML(userStruct interface{}, charsetReader utils.XMLCharDecoder) error

XML is a method that will populate a struct that is provided `userStruct` with the XML returned within the response body.

Directories

PathSynopsis
contextPackage context implements a request-aware HTTP context used by plugins and exposed by the middleware layer, designed to share polymorfic data types across plugins in the middleware call chain.
middlewarePackage middleware implements an HTTP client domain-specific phase-oriented middleware layer used internally by gentleman packages.
muxPackage mux implements an HTTP domain-specific traffic multiplexer with built-in matchers and features for easy plugin composition and activable logic.
pluginPackage plugin implements a plugin layer for gentleman components.
plugins/auth
plugins/body
plugins/bodytype
plugins/compression
plugins/cookies
plugins/headers
plugins/multipart
plugins/proxy
plugins/query
plugins/redirect
plugins/timeout
plugins/tls
plugins/transport
plugins/url
utilsPackage utils provides a set of reusable HTTP client utilities used internally in gentleman for required functionality and testing.

Package gentleman imports 21 packages (graph) and is imported by 1 packages. Updated 2019-01-30. Refresh now. Tools for package owners.