Documentation
¶
Overview ¶
Package client implements a minor extension of the default http.Client.
The primary extensions of this implementation over the standard library are:
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.
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.
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 (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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type SimpleClient ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) Options ¶
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 ¶
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.