client

Documentation

Overview

Package client implements a minor extension of the default http.Client.

The primary extensions of this implementation over the standard library are:

1. Integration with the base EasyTLS package, to provide a standardized and simpler interface for configuring and utilizing TLS encryption on an HTTP Client.

2. Explicit exposure and availability of all standard HTTP methods with a common interface. This is helpful when designing RESTful interfaces, where it can be more logically oriented to explicitly call a "Delete" function, rather than needing to create a specific DELETE request and submitting that to a generic "Do" function. This is entirely an interface-type extension, as this package does include a generic "Do". This also allows a small amount of memory safety to be added. There are a number of HTTP methods which do not expect a full HTTP Response with a meaningful body. The standard library expects you to close these response bodies in all cases, while this library will handle closing response bodies for the cases where they are not meaningful. This can help remove a memory leak issue which isn't immediately obvious.

3. Plugin integration via the easy-tls/plugins package. Client/Server application design can be simplified or broken down from monoliths with an easy enough plugin system, which this is intended to provide. The underlying http.Client is safe for concurrent use, therefore the plugin architecture assumes that a single SimpleClient instance can be passed in to any number of plugins and be used by all to communicate with their corresponding server-side logic.

Index

• func NewRequest(Method string, URL *url.URL, Headers map[string][]string, ...) (*http.Request, error)
• type SimpleClient
  • func NewClientHTTP() (*SimpleClient, error)
  • func NewClientHTTPS(TLS *easytls.TLSBundle) (*SimpleClient, error)
  • func (C *SimpleClient) Connect(URL *url.URL, Headers map[string][]string) error
  • func (C *SimpleClient) Delete(URL *url.URL, Headers map[string][]string) error
  • func (C *SimpleClient) DisableTLS()
  • func (C *SimpleClient) Do(req *http.Request) (*http.Response, error)
  • func (C *SimpleClient) EnableTLS(TLS *easytls.TLSBundle) error
  • func (C *SimpleClient) Get(URL *url.URL, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Head(URL *url.URL, Headers map[string][]string) (http.Header, error)
  • func (C *SimpleClient) IsTLS() bool
  • func (C *SimpleClient) Options(URL *url.URL, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Patch(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Post(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) PostMultipart(URL *url.URL, Contents multipart.Reader, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Put(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Trace(URL *url.URL, Headers map[string][]string) (*http.Response, error)

Functions

func NewRequest

func NewRequest(Method string, URL *url.URL, Headers map[string][]string, Contents io.ReadCloser) (*http.Request, error)

NewRequest will create a new HTTP Request, ready to be used by any implementation of an http.Client

Types

type SimpleClient

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

SimpleClient is the primary object of this library. This is the implementation of the simplified HTTP Client provided by this package. The use and functionality of this is opaque to whether or not this is running in HTTP or HTTPS mode, with a basic utility function to check.

func NewClientHTTP

func NewClientHTTP() (*SimpleClient, error)

NewClientHTTP will fully initialize a SimpleClient with TLS settings turned off. These settings CAN be turned on and off as required.

func NewClientHTTPS

func NewClientHTTPS(TLS *easytls.TLSBundle) (*SimpleClient, error)

NewClientHTTPS will fully initialize a SimpleClient with TLS settings turned on. These settings CAN be turned on and off as required.

func (*SimpleClient) Connect

func (C *SimpleClient) Connect(URL *url.URL, Headers map[string][]string) error

Connect is the wrapper function for an HTTP "CONNECT" request. (Not yet Implemented)

func (*SimpleClient) Delete

func (C *SimpleClient) Delete(URL *url.URL, Headers map[string][]string) error

Delete is the wrapper function for an HTTP "DELETE" request. This will create a new DELETE request with an empty body, and the specified headers. The header map can be set to nil if no additional headers are required. This will return ONLY an error, and no HTTP Response components. The internal HTTP Response from the server will be safely closed by this function.

func (*SimpleClient) DisableTLS

func (C *SimpleClient) DisableTLS()

DisableTLS will turn off the TLS settings for a SimpleClient.

func (*SimpleClient) Do

func (C *SimpleClient) Do(req *http.Request) (*http.Response, error)

Do is the wrapper function for a generic pre-generated HTTP request. This is the generic underlying call used by the rest of this library (and reflects similarly to how HTTP Requests are handled in the standard library). This will perform no alterations to the provided request, and no alterations to the returned Response. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) EnableTLS

func (C *SimpleClient) EnableTLS(TLS *easytls.TLSBundle) error

EnableTLS will enable the TLS settings for a SimpleClient based on the provided TLSBundle.

func (*SimpleClient) Get

func (C *SimpleClient) Get(URL *url.URL, Headers map[string][]string) (*http.Response, error)

Get is the wrapper function for an HTTP "GET" request. This will create a GET request with an empty body, and the specified headers. The header map can be set to nil if no additional headers are required. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) Head

func (C *SimpleClient) Head(URL *url.URL, Headers map[string][]string) (http.Header, error)

Head is the wrapper function for an HTTP "HEAD" request. This will create a new HEAD request with an empty body and the specified headers. The header map can be set to nil if no additional headers are required. This will ONLY return the HTTP Response Header map from the server. The overall Response Body (if it exists) will be closed by this function. This function returns an error and nil Header on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) IsTLS

func (C *SimpleClient) IsTLS() bool

IsTLS returne whether the SimpleClient is currently TLS-enabled or not.

func (*SimpleClient) Options

func (C *SimpleClient) Options(URL *url.URL, Headers map[string][]string) (*http.Response, error)

Options is the wrapper function for an HTTP "OPTIONS" request. This will create a new OPTIONS request with an empty body, and the specified headers. The header map can be set to nil if no additional headers are required. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) Patch

func (C *SimpleClient) Patch(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)

Patch is the wrapper function for an HTTP "PATCH" request. This will create a new PATCH request with a body composed of the contents of the io.ReadCloser passed in, and the specified headers. The header map can be set to nil if no additional headers are required. If a nil ReadCloser is passed in, this will create an empty Patch body which is allowed. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) Post

func (C *SimpleClient) Post(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)

Post is the wrapper function for an HTTP "POST" request. This will create a new POST request with a body composed of the contents of the io.ReadCloser passed in, and the specified headers. The header map can be set to nil if no additional headers are required. If a nil ReadCloser is passed in, this will create an empty Post body which is allowed. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

This function "may" support MultiPart POST requests, by way of io.Pipes and multipart.Writers, but this has not been tested, and multipart Post is planned to be an explicit function in the future.

func (*SimpleClient) PostMultipart

func (C *SimpleClient) PostMultipart(URL *url.URL, Contents multipart.Reader, Headers map[string][]string) (*http.Response, error)

PostMultipart is the wrapper function for an HTTP "POST" request with a MultiPart Body. This will create a new POST request with a body composed of the contents of the multipart.Reader passed in, and the specified headers. The header map can be set to nil if no additional headers are required. If a nil multipart.Reader is passed in, this will create an empty Post body which is allowed. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

(Not Yet Implemented)

func (*SimpleClient) Put

func (C *SimpleClient) Put(URL *url.URL, Contents io.ReadCloser, Headers map[string][]string) (*http.Response, error)

Put is the wrapper function for an HTTP "PUT" request. This will create a new PUT request with a body composed of the contents of the io.ReadCloser passed in, and the specified headers. The header map can be set to nil if no additional headers are required. If a nil ReadCloser is passed in, this will create an empty Put body which is allowed. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.

func (*SimpleClient) Trace

func (C *SimpleClient) Trace(URL *url.URL, Headers map[string][]string) (*http.Response, error)

Trace is the wrapper function for an HTTP "TRACE" request. This will create a new TRACE request with an empty body, and the specified headers. The header map can be set to nil if no additional headers are required. This will return the full HTTP Response from the server, unaltered. This function returns an error and nil response on an HTTP StatusCode which is outside the 200 block.