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 "easytls" package, to provide a standardized and simpler interface for configuring and utilizing TLS encryption on an HTTP Client.

   This also provides the capability to downgrade from HTTPS to HTTP if the server responds with HTTP, and to allow the client to reset back to HTTPS after the request.

2. Explicit exposure and availability of all standard HTTP methods with a standardized calling convention. By default, the standard HTTP package only provides Get() and Post() as dedicated functions, and defers to Do() for all other request types. This works, but becomes unhelpful when interacting with more complex services that use the other methods.

3. Plugin integration via the easy-tls/plugins package. Client/Server application design can be broken down 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 string, Headers http.Header, Contents io.Reader) (*http.Request, error)
• func NewRequestWithContext(ctx context.Context, Method string, URL string, Headers http.Header, ...) (*http.Request, error)
• type SimpleClient
  • func NewClient(C *http.Client) *SimpleClient
  • func NewClientHTTP() *SimpleClient
  • func NewClientHTTPS(TLS *easytls.TLSBundle) (*SimpleClient, error)
  • func (C *SimpleClient) CloneTLSConfig() (*tls.Config, error)
  • func (C *SimpleClient) Delete(URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) DeleteContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) DisableTLS()
  • func (C *SimpleClient) Do(req *http.Request) (*http.Response, error)
  • func (C *SimpleClient) EnableTLS(TLS ...*easytls.TLSBundle) (err error)
  • func (C *SimpleClient) Get(URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) GetContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Head(URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) HeadContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) IsTLS() bool
  • func (C *SimpleClient) Logger() *log.Logger
  • func (C *SimpleClient) MakeURL(Hostname string, Port uint16, PathSegments ...string) *url.URL
  • func (C *SimpleClient) Options(URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) OptionsContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) Patch(URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) PatchContext(ctx context.Context, URL string, Contents io.Reader, ...) (*http.Response, error)
  • func (C *SimpleClient) Post(URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) PostContext(ctx context.Context, URL string, Contents io.Reader, ...) (*http.Response, error)
  • func (C *SimpleClient) PostMultipart(URL string, Contents multipart.Reader, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) PostMultipartContext(ctx context.Context, URL string, Contents multipart.Reader, ...) (*http.Response, error)
  • func (C *SimpleClient) Put(URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) PutContext(ctx context.Context, URL string, Contents io.Reader, ...) (*http.Response, error)
  • func (C *SimpleClient) SetLogger(logger *log.Logger)
  • func (C *SimpleClient) Trace(URL string, Headers map[string][]string) (*http.Response, error)
  • func (C *SimpleClient) TraceContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

Functions

func NewRequest

func NewRequest(Method string, URL string, Headers http.Header, Contents io.Reader) (*http.Request, error)

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

func NewRequestWithContext

func NewRequestWithContext(ctx context.Context, Method string, URL string, Headers http.Header, Contents io.Reader) (*http.Request, error)

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

Types

type SimpleClient

type SimpleClient struct {
	*http.Client
	// 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 transparent to whether or not this is running in HTTP or HTTPS mode, with a basic utility function to check.

func NewClient

func NewClient(C *http.Client) *SimpleClient

NewClient will wrap an existing http.Client as a SimpleClient.

func NewClientHTTP

func NewClientHTTP() *SimpleClient

NewClientHTTP will fully initialize a SimpleClient with TLS settings turned off. These settings CAN be turned on and off as required, either by providing a TLSBundle, or by reusing one passed in earlier.

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) CloneTLSConfig

func (C *SimpleClient) CloneTLSConfig() (*tls.Config, error)

CloneTLSConfig will form a proper clone of the underlying tls.Config.

func (*SimpleClient) Delete

func (C *SimpleClient) Delete(URL string, Headers map[string][]string) (*http.Response, 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 ONLY any errors encountered, and no HTTP Response. The internal HTTP Response from the server will be safely closed by this function.

func (*SimpleClient) DeleteContext

func (C *SimpleClient) DeleteContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

DeleteContext 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 ONLY any errors encountered, and no HTTP Response. 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.

func (*SimpleClient) EnableTLS

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

EnableTLS will enable the TLS settings for a SimpleClient based on the provided TLSBundle. If the client previously had a TLS bundle provided, this will fall back and attempt to use that if none is given. If no TLSBundles are given, and the Client has no previous TLSBundle, this will fail, as there are no TLS resources to work with.

func (*SimpleClient) Get

func (C *SimpleClient) Get(URL string, 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) GetContext

func (C *SimpleClient) GetContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

GetContext 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 string, Headers map[string][]string) (*http.Response, 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) HeadContext

func (C *SimpleClient) HeadContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

HeadContext 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 returns whether the SimpleClient is currently TLS-enabled or not.

func (*SimpleClient) Logger

func (C *SimpleClient) Logger() *log.Logger

Logger will return the internal logger used by the client.

func (*SimpleClient) MakeURL

func (C *SimpleClient) MakeURL(Hostname string, Port uint16, PathSegments ...string) *url.URL

MakeURL will create a HTTP URL, ready to be used to build a Request.

func (*SimpleClient) Options

func (C *SimpleClient) Options(URL string, 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) OptionsContext

func (C *SimpleClient) OptionsContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

OptionsContext 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 string, Contents io.Reader, 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.Reader 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) PatchContext

func (C *SimpleClient) PatchContext(ctx context.Context, URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)

PatchContext 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.Reader 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 string, Contents io.Reader, 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.Reader 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.

NOTE: 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) PostContext

func (C *SimpleClient) PostContext(ctx context.Context, URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)

PostContext 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.Reader 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.

NOTE: 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 string, 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.

NOTE: This has not yet been implemented.

func (*SimpleClient) PostMultipartContext

func (C *SimpleClient) PostMultipartContext(ctx context.Context, URL string, Contents multipart.Reader, Headers map[string][]string) (*http.Response, error)

PostMultipartContext 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.

NOTE: This has not yet been implemented.

func (*SimpleClient) Put

func (C *SimpleClient) Put(URL string, Contents io.Reader, 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.Reader 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) PutContext

func (C *SimpleClient) PutContext(ctx context.Context, URL string, Contents io.Reader, Headers map[string][]string) (*http.Response, error)

PutContext 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.Reader 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) SetLogger

func (C *SimpleClient) SetLogger(logger *log.Logger)

SetLogger will update the logger used by the client from the default to the given output.

func (*SimpleClient) Trace

func (C *SimpleClient) Trace(URL string, 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.

func (*SimpleClient) TraceContext

func (C *SimpleClient) TraceContext(ctx context.Context, URL string, Headers map[string][]string) (*http.Response, error)

TraceContext 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.