client

README

Client

The client module defines a supercharged HTTP Client that simplifies HTTP requests. It aims to minify the code repetition that net/http module creates when dealing with multiple API calls.

This project has been developped by the Aloe team and is now open source.

Overview

Client supercharge the native http client.

The client module provides:

• Unique indication of the target API base URL
• Simple error checking and response body reading
• Ping method with timeout
• Infinite compatibility because it embed a native net/http client
• Proxy of instanciated clients

Concepts

One client by target

One of the main concept is that one client is bound to one API. We do this to simplify HTTP calls by only setting the endpoint path as function parameter and not the base URL + the path.

Status code range

To ease the error checking we've defined a StatusCodeRange struct.

type StatusCodeRange struct {
	Min int // Lower bound
	Max int // Max bound excluded
}

All status code received from target API within the range will be considered as valid response.

Usage

Instanciation

Use the Conf struct then call the FactoryConnector(conf Conf) function to instanciate a new HTTP connector. Don't forget to call the `*Connector.Ping(t int)`` method to verify that the target API is availble.

conf := Conf{
    URL: "https://myserver.com"
    PingEndpoint: "/ping"
}

connector := FactoryConnector(conf)

if err := connector.Ping(10); err != nil {
    return fmt.Errorf("target api is not available: %w", err)
}

Send HTTP requests

Once the connector is instanciates, you can use it to make your HTTP requests.

Example:

Send the GET "https://myserver.com/data" will result in the following code:

responseBody, err := connector.SimpleGet("/data")
if err != nil {
    return nil, fmt.Errorf("can't call /data endpoint: %w", err)
}

// Do what you wan't with the responseBody such as unmarshalling to JSON etc.
fmt.Println(string(responseBody))

Contributing

This section will be added soon.

License

Client is released under the MIT license. See LICENSE.txt.

Documentation

Index

• Variables
• func FactoryHTTPClient() *http.Client
• func ProxyFactoryHTTPClient(key string) *http.Client
• type Conf
• type Connector
  • func FactoryConnector(config Conf) *Connector
  • func (c *Connector) DoWithHeader(method, path string, header *http.Header, body io.Reader, ...) ([]byte, error)
  • func (c *Connector) DoWithStatusCheck(req *http.Request, exceptedStatusCode StatusCodeRange) ([]byte, error)
  • func (c *Connector) Ping(t int) error
  • func (c *Connector) SimpleDelete(path string, body io.Reader) ([]byte, error)
  • func (c *Connector) SimpleDo(method, path string, body io.Reader) ([]byte, error)
  • func (c *Connector) SimpleGet(path string) ([]byte, error)
  • func (c *Connector) SimplePost(path string, body io.Reader) ([]byte, error)
  • func (c *Connector) SimplePut(path string, body io.Reader) ([]byte, error)
• type FailRequestError
  • func (e *FailRequestError) Error() string
• type StatusCodeRange

Variables

var (
	// DefaultStatusRange that encompass most of all success HTTP status code cases.
	DefaultStatusRange = StatusCodeRange{
		Min: http.StatusOK,
		Max: http.StatusBadRequest,
	}
)

Functions

func FactoryHTTPClient

func FactoryHTTPClient() *http.Client

FactoryHTTPClient returns a fresh new http.Client instance.

func ProxyFactoryHTTPClient

func ProxyFactoryHTTPClient(key string) *http.Client

ProxyFactoryHTTPClient creates a new client if it does not exists in `instanciatedClient` map. If the client key is already defined, the function returns the associated client.

Types

type Conf

type Conf struct {
	URL          string `yaml:"url"`           // Base url of the target HTTP server such as https://myserver.com
	PingEndpoint string `yaml:"ping_endpoint"` // Path of the ping endpoint of the target HTTP server
}

Conf for the connector. All parameters are required.

type Connector

type Connector struct {
	*http.Client        // Native http client
	URL          string // Base url of the target HTTP server such as https://myserver.com
	// contains filtered or unexported fields
}

Connector is a supercharged HTTP client. It embeds a native http.Client so it can be used as native client.

func FactoryConnector

func FactoryConnector(config Conf) *Connector

FactoryConnector instantiates and returns a *Connector. Call *Connector.Ping() to ensure that the target API is available.

func (*Connector) DoWithHeader

func (c *Connector) DoWithHeader(method, path string, header *http.Header, body io.Reader, exceptedStatusCode StatusCodeRange) ([]byte, error)

DoWithHeader eases the Connector.DoWithStatusCheck use. You have to specify the method, the path, the header, the body, the excepted status range. The excepted status range Min will be included and Max will be excluded.

func (*Connector) DoWithStatusCheck

func (c *Connector) DoWithStatusCheck(req *http.Request, exceptedStatusCode StatusCodeRange) ([]byte, error)

DoWithStatusCheck a HTTP request with the given request. The caller should use Connector.URL as base URL when building the request. You have to provide a status code range to validate if the request was succesfull.

func (*Connector) Ping

func (c *Connector) Ping(t int) error

Ping sends one ping every 50ms with timeout of t second, it ends if the ping is a success or timeout.

func (*Connector) SimpleDelete

func (c *Connector) SimpleDelete(path string, body io.Reader) ([]byte, error)

SimpleDelete eases the Connector.SimpleDo use. You have to specify the path and the request body as an io.Reader. The StatusCodeRange use in Connector.DoWithStatusCheck will be DefautStatusRange [200,400[.

func (*Connector) SimpleDo

func (c *Connector) SimpleDo(method, path string, body io.Reader) ([]byte, error)

SimpleDo eases the Connector.SimpleDo use. You have to specify the method, the path and the body as an io.Reader. The StatusCodeRange use in Connector.DoWithStatusCheck will be DefautStatusRange [200,400[.

func (*Connector) SimpleGet

func (c *Connector) SimpleGet(path string) ([]byte, error)

SimpleGet eases the Connector.SimpleDo use. You have to specify the path. The StatusCodeRange use in Connector.DoWithStatusCheck will be DefautStatusRange [200,400[.

func (*Connector) SimplePost

func (c *Connector) SimplePost(path string, body io.Reader) ([]byte, error)

SimplePost eases the Connector.SimpleDo use. You have to specify the path and the request body as an io.Reader. The StatusCodeRange use in Connector.DoWithStatusCheck will be DefautStatusRange [200,400[.

func (*Connector) SimplePut

func (c *Connector) SimplePut(path string, body io.Reader) ([]byte, error)

SimplePut eases the Connector.SimpleDo use. You have to specify the path and the request body as an io.Reader. The StatusCodeRange use in Connector.DoWithStatusCheck will be DefautStatusRange [200,400[.

type FailRequestError

type FailRequestError struct {
	Code         int
	ResponseBody []byte
}

func (*FailRequestError) Error

func (e *FailRequestError) Error() string

type StatusCodeRange

type StatusCodeRange struct {
	Min int // Lower bound
	Max int // Max bound excluded
}

StatusCodeRange defines the range of valid status codes. Status codes within the range will be considered as expected codes when received from the target API.