gentleman

README

gentleman

Full-featured, plugin-driven, middleware-oriented toolkit to easily create rich, versatile and composable HTTP clients in Go.

gentleman embraces extensibility and composition principles to provide a powerful way to create simple and featured HTTP client layers based on built-in or third-party plugins. For instance, you can provide retry policy capabilities or dynamic server discovery to your HTTP clients simply attaching the retry or consul plugins respectively.

Take a look to the examples or list of supported plugins to get started.

Goals

• Plugin driven architecture.
• Simple, expressive, fluent API.
• Idiomatic built on top of net/http package.
• Context-aware middleware layer supporting all the HTTP life cycle.
• Multiplexer for easy composition capabilities.
• Strong extensibility via plugins.
• Easy to configure and use.
• Ability to easily intercept and modify HTTP traffic.
• Convenient helpers and abstractions over Go's HTTP primitives.
• URL template path params.
• Built-in JSON, XML and multipart bodies serialization and parsing.
• Easy to test via HTTP mocking (e.g: gentleman-mock).
• Data passing across plugins/middleware via context.
• Dependency free.

Installation

go get -u gopkg.in/h2non/gentleman.v1

Plugins

Name	Docs	Status	Description
url			Easily declare URL, base URL and path values in HTTP requests
auth			Declare authorization headers in your requests
body			Easily define bodies based on JSON, XML, strings, buffers or streams
bodytype			Define body MIME type by alias
cookies			Declare and store HTTP cookies easily
compression			Helpers to define enable/disable HTTP compression
headers			Manage HTTP headers easily
multipart			Create multipart forms easily. Supports files and text fields
proxy			Configure HTTP proxy servers
query			Easily manage query params
redirect			Easily configure a custom redirect policy
timeout			Easily configure the HTTP timeouts (request, dial, TLS...)
transport			Define a custom HTTP transport easily
tls			Configure the TLS options used by the HTTP transport
retry			Provide retry policy capabilities to your HTTP clients
mock			Easy HTTP mocking using gock
consul			Consul based server discovery with configurable retry/backoff policy

Send a PR to add your plugin to the list.

Creating plugins

You can create your own plugins for a variety of purposes, such as server discovery, custom HTTP tranport, modify any request/response param, intercept traffic, authentication and so on.

Plugins are essentially a set of middleware function handlers for one or multiple HTTP life cycle phases exposing a concrete interface consumed by gentleman middleware layer.

For more details about plugins see the plugin package and examples.

Also you can take a look to a plugin implementation example.

HTTP entities

gentleman provides two HTTP high level entities: Client and Request.

Each of these entities provides a common API and are middleware capable, giving the ability to plug in logic in any of them.

gentleman was designed to provide strong reusability capabilities, achieved via simple middleware layer inheritance. The following describes how inheritance affects to gentleman's entities.

• Client can inherit from other Client.
• Request can inherit from Client.
• Client is mostly designed for reusability.
• Client can create multiple Request entities who implicitly inherits from the current Client.
• Both Client and Request are full middleware capable interfaces.
• Both Client and Request can be cloned to have a new side-effects free entity.

You can see an inheritance example here.

Middleware

gentleman is completely based on a hierarchical middleware layer based on plugin that executes one or multiple function handlers, providing a simple way to plug in intermediate logic.

It supports multiple phases which represents the full HTTP request/response life cycle, giving you the ability to perform actions before and after an HTTP transaction happen, even intercepting and stopping it.

The middleware stack chain is executed in FIFO order designed for single thread model. Plugins can support goroutines, but plugins implementors should prevent data race issues due to concurrency in multithreading programming.

For more implementation details about the middleware layer, see the middleware package and examples.

Middleware phases

Supported middleware phases triggered by gentleman HTTP dispatcher:

• request - Executed before a request is sent over the network.
• response - Executed when the client receives the response, even if it failed.
• error - Executed in case that an error ocurrs, support both injected or native error.
• stop - Executed in case that the request has been manually stopped via middleware (e.g: after interception).
• intercept - Executed in case that the request has been intercepted before network dialing.
• before dial - Executed before a request is sent over the network.
• after dial - Executed after the request dialing was done and the response has been received.

Note that the middleware layer has been designed for easy extensibility, therefore new phases may be added in the future and/or the developer could be able to trigger custom middleware phases if needed.

Feel free to fill an issue to discuss this capabilities in detail.

API

See godoc reference for detailed API documentation.

Subpackages

• plugin - godoc - Plugin layer for gentleman.
• mux - godoc - HTTP client multiplexer with built-in matchers.
• middleware - godoc - Middleware layer used by gentleman.
• context - godoc - HTTP context implementation for gentleman's middleware.
• utils - godoc - HTTP utilities internally used.

Examples

See examples directory for featured examples.

Simple request

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v1"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define base URL
  cli.URL("http://httpbin.org")

  // Create a new request based on the current client
  req := cli.Request()

  // Define the URL path at request level
  req.Path("/headers")

  // Set a new header field
  req.SetHeader("Client", "gentleman")

  // Perform the request
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  // Reads the whole body and returns it as string
  fmt.Printf("Body: %s", res.String())
}

Send JSON body

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v1"
  "gopkg.in/h2non/gentleman.v1/plugins/body"
)

func main() {
  // Create a new client
  cli := gentleman.New()
  
  // Define the Base URL
  cli.URL("http://httpbin.org/post")

  // Create a new request based on the current client
  req := cli.Request()
  
  // Method to be used
  req.Method("POST")

  // Define the JSON payload via body plugin
  data := map[string]string{"foo": "bar"}
  req.Use(body.JSON(data))

  // Perform the request
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}

Composition via multiplexer

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v1"
  "gopkg.in/h2non/gentleman.v1/mux"
  "gopkg.in/h2non/gentleman.v1/plugins/url"
)

func main() {
  // Create a new client
  cli := gentleman.New()

  // Define the server url (must be first)
  cli.Use(url.URL("http://httpbin.org"))

  // Create a new multiplexer based on multiple matchers
  mx := mux.If(mux.Method("GET"), mux.Host("httpbin.org"))

  // Attach a custom plugin on the multiplexer that will be executed if the matchers passes
  mx.Use(url.Path("/headers"))

  // Attach the multiplexer on the main client
  cli.Use(mx)

  // Perform the request
  res, err := cli.Request().Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}

License

MIT - Tomas Aparicio

Documentation

Index

• Constants
• Variables
• func EnsureResponseFinalized(httpResp *Response)
• func NewDefaultTransport(dialer *net.Dialer) *http.Transport
• type Client
  • func New() *Client
  • func (c *Client) AddCookie(cookie *http.Cookie) *Client
  • func (c *Client) AddCookies(data []*http.Cookie) *Client
  • func (c *Client) AddHeader(name, value string) *Client
  • func (c *Client) BaseURL(uri string) *Client
  • func (c *Client) CookieJar() *Client
  • func (c *Client) Delete() *Request
  • func (c *Client) Get() *Request
  • func (c *Client) Head() *Request
  • func (c *Client) Method(name string) *Client
  • func (c *Client) Param(name, value string) *Client
  • func (c *Client) Params(params map[string]string) *Client
  • func (c *Client) Patch() *Request
  • func (c *Client) Path(path string) *Client
  • func (c *Client) Post() *Request
  • func (c *Client) Put() *Request
  • func (c *Client) Request() *Request
  • func (c *Client) SetHeader(key, value string) *Client
  • func (c *Client) SetHeaders(fields map[string]string) *Client
  • func (c *Client) URL(uri string) *Client
  • func (c *Client) Use(p plugin.Plugin) *Client
  • func (c *Client) UseError(fn context.HandlerFunc) *Client
  • func (c *Client) UseHandler(phase string, fn context.HandlerFunc) *Client
  • func (c *Client) UseParent(parent *Client) *Client
  • func (c *Client) UseRequest(fn context.HandlerFunc) *Client
  • func (c *Client) UseResponse(fn context.HandlerFunc) *Client
• type Dispatcher
  • func NewDispatcher(req *Request) *Dispatcher
  • func (d *Dispatcher) Dispatch() *c.Context
• type Request
  • func NewRequest() *Request
  • func (r *Request) AddCookie(cookie *http.Cookie) *Request
  • func (r *Request) AddCookies(data []*http.Cookie) *Request
  • func (r *Request) AddHeader(name, value string) *Request
  • func (r *Request) AddPath(path string) *Request
  • func (r *Request) AddQuery(name, value string) *Request
  • func (r *Request) BaseURL(uri string) *Request
  • func (r *Request) Body(reader io.Reader) *Request
  • func (r *Request) BodyString(data string) *Request
  • func (r *Request) Clone() *Request
  • func (r *Request) CookieJar() *Request
  • func (r *Request) Do() (*Response, error)
  • func (r *Request) File(name string, reader io.Reader) *Request
  • func (r *Request) Files(files []multipart.FormFile) *Request
  • func (r *Request) Form(data multipart.FormData) *Request
  • func (r *Request) JSON(data interface{}) *Request
  • func (r *Request) Method(method string) *Request
  • func (r *Request) Mux() *mux.Mux
  • func (r *Request) Param(name, value string) *Request
  • func (r *Request) Params(params map[string]string) *Request
  • func (r *Request) Path(path string) *Request
  • func (r *Request) Send() (*Response, error)
  • func (r *Request) SetClient(cli *Client) *Request
  • func (r *Request) SetHeader(name, value string) *Request
  • func (r *Request) SetHeaders(fields map[string]string) *Request
  • func (r *Request) SetQuery(name, value string) *Request
  • func (r *Request) SetQueryParams(params map[string]string) *Request
  • func (r *Request) Type(name string) *Request
  • func (r *Request) URL(uri string) *Request
  • func (r *Request) Use(p plugin.Plugin) *Request
  • func (r *Request) UseError(fn context.HandlerFunc) *Request
  • func (r *Request) UseHandler(phase string, fn context.HandlerFunc) *Request
  • func (r *Request) UseRequest(fn context.HandlerFunc) *Request
  • func (r *Request) UseResponse(fn context.HandlerFunc) *Request
  • func (r *Request) XML(data interface{}) *Request
• type Response
  • func (r *Response) Bytes() []byte
  • func (r *Response) ClearInternalBuffer()
  • func (r *Response) Close() error
  • func (r *Response) JSON(userStruct interface{}) error
  • func (r *Response) Read(p []byte) (n int, err error)
  • func (r *Response) SaveToFile(fileName string) error
  • func (r *Response) String() string
  • func (r *Response) XML(userStruct interface{}, charsetReader utils.XMLCharDecoder) error

Constants

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

const Version = "1.0.0"

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.

Functions

func EnsureResponseFinalized

func EnsureResponseFinalized(httpResp *Response)

EnsureResponseFinalized will ensure that when the Response is GCed the request body is closed so we aren't leaking fds.

func NewDefaultTransport

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

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

Types

type Client

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

func New() *Client

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

func (*Client) AddCookie

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

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

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

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

func (c *Client) CookieJar() *Client

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

func (*Client) Delete

func (c *Client) Delete() *Request

Delete creates a new DELETE request.

func (*Client) Get

func (c *Client) Get() *Request

Get creates a new GET request.

func (*Client) Head

func (c *Client) Head() *Request

Head creates a new HEAD request.

func (*Client) Method

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

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

func (*Client) Param

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

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

func (*Client) Params

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

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

func (*Client) Patch

func (c *Client) Patch() *Request

Patch creates a new PATCH request.

func (*Client) Path

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

Path defines the URL base path for client requests.

func (*Client) Post

func (c *Client) Post() *Request

Post creates a new POST request.

func (*Client) Put

func (c *Client) Put() *Request

Put creates a new PUT request.

func (*Client) Request

func (c *Client) Request() *Request

Request creates a new Request based on the current Client

func (*Client) SetHeader

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

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

SetHeaders adds new header fields based on the given map.

func (*Client) URL

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

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

Use uses a new plugin to the middleware stack.

func (*Client) UseError

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

UseError uses a new middleware function for error phase.

func (*Client) UseHandler

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

UseHandler uses a new middleware function for the given phase.

func (*Client) UseParent

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

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

func (*Client) UseRequest

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

UseRequest uses a new middleware function for request phase.

func (*Client) UseResponse

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

UseResponse uses a new middleware function for response phase.

type Dispatcher

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

func NewDispatcher(req *Request) *Dispatcher

NewDispatcher creates a new Dispatcher based on the given Context.

func (*Dispatcher) Dispatch

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

Dispatch triggers the middleware chains and performs the HTTP request.

type Request

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

func NewRequest() *Request

NewRequest creates a new Request entity.

func (*Request) AddCookie

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

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

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

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

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

func (*Request) AddQuery

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

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

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

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

func (*Request) BodyString

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

func (r *Request) Clone() *Request

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

func (*Request) CookieJar

func (r *Request) CookieJar() *Request

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

func (*Request) Do

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

Do performs the HTTP request and returns the HTTP response.

func (*Request) File

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

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

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

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

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

Method defines the HTTP verb to be used.

func (*Request) Mux

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

Mux is a middleware multiplexer for easy plugin composition.

func (*Request) Param

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

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

func (*Request) Params

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

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

func (*Request) Path

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

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

func (*Request) Send

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

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

func (*Request) SetClient

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

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

func (*Request) SetHeader

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

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

SetHeaders adds new header fields based on the given map.

func (*Request) SetQuery

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

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

SetQueryParams sets URL query params based on the given map.

func (*Request) Type

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

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

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

func (*Request) Use

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

Use uses a new plugin in the middleware stack.

func (*Request) UseError

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

UseError uses an error middleware handler.

func (*Request) UseHandler

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

UseHandler uses an new middleware handler for the given phase.

func (*Request) UseRequest

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

UseRequest uses a request middleware handler.

func (*Request) UseResponse

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

UseResponse uses a response middleware handler.

func (*Request) XML

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

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

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

Bytes returns the response as a byte array.

func (*Response) ClearInternalBuffer

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

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

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

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

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

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

func (*Response) String

func (r *Response) String() string

String returns the response as a string.

func (*Response) XML

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.