http

README

ContainerSSH HTTP Library

This library provides a common layer for HTTP clients and servers in use by ContainerSSH.

⚠⚠⚠ Warning: This is a developer documentation. ⚠⚠⚠
The user documentation for ContainerSSH is located at containerssh.io.

Using this library

This library provides a much simplified API for both the HTTP client and server.

Using the client

The client library takes a request object that can be marshalled into JSON format and sends it to the server. It then fills a response object with the response received from the server. In code:

// Logger is from the github.com/containerssh/log package
logger := standard.New()
clientConfig := http.ClientConfiguration{
    URL:        "http://127.0.0.1:8080/",
    Timeout:    2 * time.Second,
    // You can add TLS configuration here:
    CaCert:     "Add expected CA certificate(s) here.",
                // CaCert is is required for https:// URLs on Windows due to golang#16736
    // Optionally, for client authentication:
    ClientCert: "Client certificate in PEM format or file name",
    ClientKey:  "Client key in PEM format or file name",
}
client, err := http.NewClient(clientConfig, logger)
if err != nil {
    // Handle validation error
}

request := yourRequestStruct{}
response := yourResponseStruct{}

responseStatus, err := client.Post(
    context.TODO(),
    "/relative/path/from/base/url",
    &request,
    &response,
)
if err != nil {
    // Handle connection error
    clientError := &http.ClientError{}
    if errors.As(err, clientError) {
        // Grab additional information here
    } else {
    	// This should never happen
    }
}

if responseStatus > 399 {
    // Handle error
}

The logger parameter is a logger from the github.com/containerssh/log package.

Using the server

The server consist of two parts: the HTTP server and the handler. The HTTP server can be used as follows:

server, err := http.NewServer(
    "service name",
    http.ServerConfiguration{
        Listen:       "127.0.0.1:8080",
        // You can also add TLS configuration
        // and certificates here:
        Key:          "PEM-encoded key or file name to cert here.",
        Cert:         "PEM-encoded certificate chain or file name here",
        // Authenticate clients with certificates:
        ClientCACert: "PEM-encoded client CA certificate or file name here",
    },
    handler,
    logger,
    func (url string) {
        fmt.Printf("Server is now ready at %s", url)
    }
)
if err != nil {
    // Handle configuration error
}
// Lifecycle from the github.com/containerssh/service package
lifecycle := service.NewLifecycle(server)
go func() {
    if err := lifecycle.Run(); err != nil {
        // Handle error
    }
}()
// Do something else, then shut down the server.
// You can pass a context for the shutdown deadline.
lifecycle.Shutdown(context.Background())

Like before, the logger parameter is a logger from the github.com/containerssh/log package. The handler is a regular go HTTP handler that satisfies this interface:

type Handler interface {
    ServeHTTP(http.ResponseWriter, *http.Request)
}

The lifecycle object is one from the ContainerSSH service package.

Using a simplified handler

This package also provides a simplified handler that helps with encoding and decoding JSON messages. It can be created as follows:

handler := http.NewServerHandler(yourController, logger)

The yourController variable then only needs to implement the following interface:

type RequestHandler interface {
	OnRequest(request ServerRequest, response ServerResponse) error
}

For example:

type MyRequest struct {
    Message string `json:"message"`
}

type MyResponse struct {
    Message string `json:"message"`
}

type myController struct {
}

func (c *myController) OnRequest(request http.ServerRequest, response http.ServerResponse) error {
    req := MyRequest{}
	if err := request.Decode(&req); err != nil {
		return err
	}
	if req.Message == "Hi" {
		response.SetBody(&MyResponse{
			Message: "Hello world!",
		})
	} else {
        response.SetStatus(400)
		response.SetBody(&MyResponse{
			Message: "Be nice and greet me!",
		})
	}
	return nil
}

In other words, the ServerRequest object gives you the ability to decode the request into a struct of your choice. The ServerResponse, conversely, encodes a struct into the the response body and provides the ability to enter a status code.

Using multiple handlers

This is a very simple handler example. You can use utility like gorilla/mux as an intermediate handler between the simplified handler and the server itself.

Documentation

Index

• Constants
• func NewServerHandler(requestHandler RequestHandler, logger log.Logger) goHttp.Handler
• type CipherSuite
  • func (c CipherSuite) Validate() error
• type CipherSuiteList
  • func (c *CipherSuiteList) UnmarshalJSON(data []byte) error
  • func (c *CipherSuiteList) UnmarshalYAML(unmarshal func(interface{}) error) error
  • func (c CipherSuiteList) Validate() error
• type Client
  • func NewClient(config ClientConfiguration, logger log.Logger) (Client, error)
• type ClientConfiguration
  • func (c *ClientConfiguration) Validate() error
• type ECDHCurve
  • func (c ECDHCurve) Validate() error
• type ECDHCurveList
  • func (c *ECDHCurveList) UnmarshalJSON(data []byte) error
  • func (c *ECDHCurveList) UnmarshalYAML(unmarshal func(interface{}) error) error
  • func (c ECDHCurveList) Validate() error
• type RequestHandler
• type Server
  • func NewServer(name string, config ServerConfiguration, handler goHttp.Handler, ...) (Server, error)
• type ServerConfiguration
  • func (config *ServerConfiguration) Validate() error
• type ServerRequest
• type ServerResponse
• type TLSVersion
  • func (t TLSVersion) Validate() error

Constants

const EClientRedirectsDisabled = "HTTP_CLIENT_REDIRECTS_DISABLED"

This message indicates that ContainerSSH is not following a HTTP redirect sent by the server. Use the allowRedirects option to allow following HTTP redirects.

const EFailureConnectionFailed = "HTTP_CLIENT_CONNECTION_FAILED"

This message indicates a connection failure on the network level.

const EFailureDecodeFailed = "HTTP_CLIENT_DECODE_FAILED"

This message indicates that decoding the JSON response has failed. The status code is set for this code.

const EFailureEncodeFailed = "HTTP_CLIENT_ENCODE_FAILED"

This message indicates that JSON encoding the request failed. This is usually a bug.

const MClientRedirect = "HTTP_CLIENT_REDIRECT"

This message indicates that the server responded with a HTTP redirect.

const MClientRequest = "HTTP_CLIENT_REQUEST"

This message indicates that a HTTP request is being sent from ContainerSSH

const MClientResponse = "HTTP_CLIENT_RESPONSE"

This message indicates that ContainerSSH received a HTTP response from a server.

const MServerEncodeFailed = "HTTP_SERVER_ENCODE_FAILED"

The HTTP server failed to encode the response object. This is a bug, please report it.

const MServerResponseWriteFailed = "HTTP_SERVER_RESPONSE_WRITE_FAILED"

The HTTP server failed to write the response.

Functions

func NewServerHandler

func NewServerHandler(
	requestHandler RequestHandler,
	logger log.Logger,
) goHttp.Handler

NewServerHandler creates a new simplified HTTP handler that decodes JSON requests and encodes JSON responses.

Types

type CipherSuite

type CipherSuite string

CipherSuite is the cipher suite used for TLS connections.

const (
	IANA_TLS_AES_128_GCM_SHA256                     CipherSuite = "TLS_AES_128_GCM_SHA256"
	IANA_TLS_AES_256_GCM_SHA384                     CipherSuite = "TLS_AES_256_GCM_SHA384"
	IANA_TLS_CHACHA20_POLY1305_SHA256               CipherSuite = "TLS_CHACHA20_POLY1305_SHA256"
	IANA_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256    CipherSuite = "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
	OpenSSL_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 CipherSuite = "ECDHE-ECDSA-AES128-GCM-SHA256"
	GnuTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256  CipherSuite = "TLS_ECDHE_ECDSA_AES_128_GCM_SHA256"
	IANA_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256      CipherSuite = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
	OpenSSL_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   CipherSuite = "ECDHE-RSA-AES128-GCM-SHA256"
	GnuTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256    CipherSuite = "TLS_ECDHE_RSA_AES_128_GCM_SHA256"
	IANA_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384    CipherSuite = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
	OpenSSL_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 CipherSuite = "ECDHE-ECDSA-AES256-GCM-SHA384"
	GnuTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384  CipherSuite = "TLS_ECDHE_ECDSA_AES_256_GCM_SHA384"
	IANA_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384      CipherSuite = "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
	OpenSSL_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   CipherSuite = "ECDHE-RSA-AES256-GCM-SHA384"
	GnuTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384    CipherSuite = "TLS_ECDHE_RSA_AES_256_GCM_SHA384"
	IANA_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305     CipherSuite = "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305"
	OpenSSL_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305  CipherSuite = "ECDHE-ECDSA-CHACHA20-POLY1305"
	GnuTLS_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305   CipherSuite = "TLS_ECDHE_ECDSA_CHACHA20_POLY1305"
	IANA_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305       CipherSuite = "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305"
	OpenSSL_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    CipherSuite = "ECDHE-RSA-CHACHA20-POLY1305"
	GnuTLS_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305     CipherSuite = "TLS_ECDHE_RSA_CHACHA20_POLY1305"
)

func (CipherSuite) Validate

func (c CipherSuite) Validate() error

Validate validates if the cipher suite is supported.

type CipherSuiteList

type CipherSuiteList []CipherSuite

CipherSuiteList is a list of cipher suites. This type is provided for easier unmarshaling from a list or string.

func (*CipherSuiteList) UnmarshalJSON

func (c *CipherSuiteList) UnmarshalJSON(data []byte) error

UnmarshalJSON provides JSON unmarshalling from both a list and a cipher suite string.

func (*CipherSuiteList) UnmarshalYAML

func (c *CipherSuiteList) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML provides YAML unmarshalling from both a list and a cipher suite string.

func (CipherSuiteList) Validate

func (c CipherSuiteList) Validate() error

Validate provides validation for a list of cipher suites.

type Client

type Client interface {
	// Post queries the configured endpoint with the path, sending the requestBody and providing the
	// response in the responseBody structure. It returns the HTTP status code and any potential errors.
	//
	// The returned error is always one of ClientError
	Post(
		path string,
		requestBody interface{},
		responseBody interface{},
	) (statusCode int, err error)
}

Client is a simplified HTTP interface that ensures that a struct is transported to a remote endpoint properly encoded, and the response is decoded into the response struct.

func NewClient

func NewClient(
	config ClientConfiguration,
	logger log.Logger,
) (Client, error)

NewClient creates a new HTTP client with the given configuration.

type ClientConfiguration

type ClientConfiguration struct {
	// URL is the base URL for requests.
	URL string `json:"url" yaml:"url" comment:"Base URL of the server to connect."`

	// AllowRedirects sets if the client should honor HTTP redirects. Defaults to false.
	AllowRedirects bool `json:"allowRedirects" yaml:"allowRedirects" comment:""`

	// Timeout is the time the client should wait for a response.
	Timeout time.Duration `json:"timeout" yaml:"timeout" comment:"HTTP call timeout." default:"2s"`

	// CACert is either the CA certificate to expect on the server in PEM format
	//         or the name of a file containing the PEM.
	CACert string `` /* 168-byte string literal not displayed */

	// ClientCert is a PEM containing an x509 certificate to present to the server or a file name containing the PEM.
	ClientCert string `json:"cert" yaml:"cert" comment:"Client certificate file in PEM format."`

	// ClientKey is a PEM containing a private key to use to connect the server or a file name containing the PEM.
	ClientKey string `json:"key" yaml:"key" comment:"Client key file in PEM format."`

	// TLSVersion is the minimum TLS version to use.
	TLSVersion TLSVersion `json:"tlsVersion" yaml:"tlsVersion" default:"1.3"`

	// ECDHCurves is the list of curve algorithms to support.
	ECDHCurves ECDHCurveList `json:"curves" yaml:"curves" default:"[\"x25519\",\"secp256r1\",\"secp384r1\",\"secp521r1\"]"`

	// CipherSuites is a list of supported cipher suites.
	CipherSuites CipherSuiteList `` /* 212-byte string literal not displayed */
	// contains filtered or unexported fields
}

ClientConfiguration is the configuration structure for HTTP clients

We are adding the JSON and YAML tags to conform to the Operator SDK requirements to tag all fields.

func (*ClientConfiguration) Validate

func (c *ClientConfiguration) Validate() error

Validate validates the client configuration and returns an error if it is invalid.

type ECDHCurve

type ECDHCurve string

ECDHCurve is an elliptic curve algorithm.

const (
	ECDHCurveX25519       ECDHCurve = "x25519"
	ECDHCurveX25519Alt    ECDHCurve = "X25519"
	ECDHCurveSecP256r1    ECDHCurve = "secp256r1"
	ECDHCurveSecP256r1Alt ECDHCurve = "prime256v1"
	ECDHCurveSecP384r1    ECDHCurve = "secp384r1"
	ECDHCurveSecP521r1    ECDHCurve = "secp521r1"
)

Elliptic curve algorithms.

func (ECDHCurve) Validate

func (c ECDHCurve) Validate() error

Validate validates the TLS curve for a valid value.

type ECDHCurveList

type ECDHCurveList []ECDHCurve

ECDHCurveList is a list of supported ECDHCurve

func (*ECDHCurveList) UnmarshalJSON

func (c *ECDHCurveList) UnmarshalJSON(data []byte) error

UnmarshalJSON provides JSON unmarshalling from both a list and a string with ECDH curves.

func (*ECDHCurveList) UnmarshalYAML

func (c *ECDHCurveList) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML provides YAML unmarshalling from both a list and a string with ECDH curves.

func (ECDHCurveList) Validate

func (c ECDHCurveList) Validate() error

Validate provides validation for a list of cipher suites.

type RequestHandler

type RequestHandler interface {
	// OnRequest is a method receiving a request and is able to respond.
	OnRequest(request ServerRequest, response ServerResponse) error
}

RequestHandler is an interface containing a simple controller receiving a request and providing a response.

type Server

type Server interface {
	service.Service
}

Server is an interface that specifies the minimum requirements for the server.

func NewServer

func NewServer(
	name string,
	config ServerConfiguration,
	handler goHttp.Handler,
	logger log.Logger,
	onReady func(string),
) (Server, error)

NewServer creates a new HTTP server with the given configuration and calling the provided handler.

type ServerConfiguration

type ServerConfiguration struct {
	// Listen contains the IP and port to listen on.
	Listen string `json:"listen" yaml:"listen" default:"0.0.0.0:8080"`
	// Key contains either a file name to a private key, or the private key itself in PEM format to use as a server key.
	Key string `json:"key" yaml:"key"`
	// Cert contains either a file to a certificate, or the certificate itself in PEM format to use as a server
	// certificate.
	Cert string `json:"cert" yaml:"cert"`
	// ClientCACert contains either a file or a certificate in PEM format to verify the connecting clients by.
	ClientCACert string `json:"clientcacert" yaml:"clientcacert"`

	// TLSVersion is the minimum TLS version to use.
	TLSVersion TLSVersion `json:"tlsVersion" yaml:"tlsVersion" default:"1.3"`

	// ECDHCurves is the list of curve algorithms to support.
	ECDHCurves ECDHCurveList `json:"curves" yaml:"curves" default:"[\"x25519\",\"secp256r1\",\"secp384r1\",\"secp521r1\"]"`

	// CipherSuites is a list of supported cipher suites.
	CipherSuites CipherSuiteList `` /* 212-byte string literal not displayed */
	// contains filtered or unexported fields
}

ServerConfiguration is a structure to configure the simple HTTP server by.

func (*ServerConfiguration) Validate

func (config *ServerConfiguration) Validate() error

Validate validates the server configuration.

type ServerRequest

type ServerRequest interface {
	// Decode decodes the raw request into the provided target from a JSON format. It provides an
	//        error if the decoding failed, which should be passed back through the request handler.
	Decode(target interface{}) error
}

ServerRequest is a data structure providing decoding from the raw request.

type ServerResponse

type ServerResponse interface {
	// SetStatus sets the HTTP status code
	SetStatus(statusCode uint16)
	// SetBody sets the object of the response which will be encoded as JSON.
	SetBody(interface{})
}

ServerResponse is a response structure that can be used by the RequestHandler to set the response details.

type TLSVersion

type TLSVersion string

TLSVersion is the version of the TLS protocol to use.

const (
	TLSVersion12 TLSVersion = "1.2"
	TLSVersion13 TLSVersion = "1.3"
)

func (TLSVersion) Validate

func (t TLSVersion) Validate() error

Validate validates the TLS version