gentleman

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 in order to provide a flexible way to easily create featured HTTP client layers based on built-in or third-party plugins that you can register and reuse across HTTP clients.

As an example, you can easily provide retry policy capabilities or dynamic server discovery in your HTTP clients simply attaching the retry or consul plugins.

Take a look to the examples, list of supported plugins, HTTP entities or middleware layer to get started.

gentleman

Versions

Features

net/http

Installation

Requirements

• Go 1.7+

Plugins

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

Community plugins

Name	Docs	Status	Description
		Easily log requests and responses

Send a PR to add your plugin to the list.

Creating plugins

You can create your own plugins for a wide 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

gentlemanClientRequest

Each of these entities provides a common API and are both middleware capable, giving you the ability to plug in custom components with own logic into any of them.

gentleman

The following list describes how inheritance hierarchy works and is used across gentleman's entities.

ClientClientRequestClientClientClientRequestClientRequestClientRequestClientRequest

You can see an inheritance usage example here.

Middleware

gentleman is completely based on a hierarchical middleware layer based on plugins that executes one or multiple function handlers (aka plugin interface) providing a simple way to plug in intermediate custom logic in your HTTP client.

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

Examples

See examples directory for featured examples.

Simple request

Send JSON body

Composition via multiplexer

License

MIT - Tomas Aparicio