http

Documentation

Index

• func Error(w http.ResponseWriter, err error) error
• func ErrorTrailer(w http.ResponseWriter, err error)
• func FilterPEM(pemBlocks []byte, filter func(*pem.Block) bool) ([]byte, error)
• func NewServerMux(config *ServerConfig) *http.ServeMux
• func RetryReader(r io.ReadSeeker) io.ReadSeeker
• type API
• type AuditResponseWriter
  • func (w *AuditResponseWriter) Flush()
  • func (w *AuditResponseWriter) Write(b []byte) (int, error)
  • func (w *AuditResponseWriter) WriteHeader(statusCode int)
• type Certificate
  • func LoadCertificate(certFile, keyFile, password string) (*Certificate, error)
  • func NewCertificate(cert tls.Certificate) *Certificate
  • func (c *Certificate) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (c *Certificate) ReloadAfter(ctx context.Context, interval time.Duration)
• type FlushWriter
  • func NewFlushWriter(w io.Writer) FlushWriter
  • func (w FlushWriter) Flush()
  • func (w FlushWriter) Write(p []byte) (int, error)
• type Retry
  • func (r *Retry) Do(req *http.Request) (*http.Response, error)
  • func (r *Retry) Get(url string) (*http.Response, error)
  • func (r *Retry) Head(url string) (*http.Response, error)
  • func (r *Retry) Post(url, contentType string, body io.Reader) (*http.Response, error)
  • func (r *Retry) PostForm(url string, data url.Values) (*http.Response, error)
• type ServerConfig

Functions

func Error

func Error(w http.ResponseWriter, err error) error

Error sends the given err as JSON error response to w.

If err has a 'Status() int' method then Error sets the response status code to err.Status(). Otherwise, it will send 500 (internal server error).

If err is nil then Error will send the status code 500 and an empty JSON response body - i.e. '{}'.

func ErrorTrailer

func ErrorTrailer(w http.ResponseWriter, err error)

ErrorTrailer sends the given err as JSON error to w as HTTP trailer.

ErrorTrailer should be used to communicate an error to the client if the error occurred after a response has been sent to client.

A caller of ErrorTrailer has to pre-define the:

• Status
• Error

trailers via http.ResponseWriter.Header().Set("Trailer", "Status, Error")

If err has a 'Status() int' method then Error sets the response status code to err.Status(). Otherwise, it will send 500 (internal server error).

If err is nil then ErrorTrailer will send the status code 500 and an empty JSON error - i.e. '{}'.

func FilterPEM

func FilterPEM(pemBlocks []byte, filter func(*pem.Block) bool) ([]byte, error)

FilterPEM applies the filter function on each PEM block in pemBlocks and returns an error if at least one PEM block does not pass the filter.

func NewServerMux

func NewServerMux(config *ServerConfig) *http.ServeMux

NewServerMux returns a new KES server handler that uses the given ServerConfig to implement the KES HTTP API.

func RetryReader

func RetryReader(r io.ReadSeeker) io.ReadSeeker

RetryReader returns an io.ReadSeeker that can be used as request body for retryable requests via Seek(0, io.SeekStart). The returned io.ReadSeeker implements io.Closer.

If r does not implement io.Closer RetryReader returns an io.ReadSeeker that implements io.Closer as nop.

Types

type API

type API struct {
	Method  string        // The HTTP method
	Path    string        // The URI API path.
	MaxBody int64         // The max. body size the API accepts
	Timeout time.Duration // The duration after which an API request times out.
}

API describes a KES server API.

type AuditResponseWriter

type AuditResponseWriter struct {
	http.ResponseWriter

	// Logger will receive the kes.AuditEvent produced
	// on the first invocation of Write resp. WriteHeader.
	Logger *log.Logger

	URL url.URL // The request URL
	IP  net.IP  // The client IP address

	Identity  kes.Identity // The client's X.509 identity
	CreatedAt time.Time    // The time when we receive the request
	// contains filtered or unexported fields
}

AuditResponseWriter is an http.ResponseWriter that writes a kes.AuditEvent to a log.Logger after sending the response status code and before response body.

func (*AuditResponseWriter) Flush

func (w *AuditResponseWriter) Flush()

Flush flushes whatever has been written to w to the receiver.

func (*AuditResponseWriter) Write

func (w *AuditResponseWriter) Write(b []byte) (int, error)

Write writes b to the underlying http.ResponseWriter. If no status code has been sent via WriteHeader, Write sends the status code 200 OK.

func (*AuditResponseWriter) WriteHeader

func (w *AuditResponseWriter) WriteHeader(statusCode int)

WriteHeader writes the given statusCode to the underlying http.ResponseWriter and then writes a kes.AuditEvent to w's log.Logger.

WriteHeader does not produce another kes.AuditEvent when invoked again.

type Certificate

type Certificate struct {
	ErrorLog *xlog.Target
	// contains filtered or unexported fields
}

Certificate is a X.509 TLS certificate.

func LoadCertificate

func LoadCertificate(certFile, keyFile, password string) (*Certificate, error)

LoadCertificate returns a new Certificate from the given certificate and private key files.

The password is used to decrypt the private key if it is encrypted.

func NewCertificate

func NewCertificate(cert tls.Certificate) *Certificate

NewCertificate returns a new Certificate from the given TLS certificate.

func (*Certificate) GetCertificate

func (c *Certificate) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate returns a X.509 TLS certificate based on the TLS client hello.

func (*Certificate) ReloadAfter

func (c *Certificate) ReloadAfter(ctx context.Context, interval time.Duration)

ReloadAfter reloads the X.509 TLS certificate from its certificate resp. private key file periodically in an infinite loop.

Once the ctx.Done() channel returns ReloadAfter exits.

type FlushWriter

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

A FlushWriter wraps an io.Writer and performs a flush operation after every write call if the wrapped io.Writer implements http.Flusher.

A FlushWriter is useful when (small) data should be sent to the receiver as soon as possible.

A FlushWriter avoids latency added by buffering the data. However, it may impact performance since it may increase the number of OS syscalls.

func NewFlushWriter

func NewFlushWriter(w io.Writer) FlushWriter

NewFlushWriter returns a new FlushWriter that wraps w.

func (FlushWriter) Flush

func (w FlushWriter) Flush()

Flush sends any buffered data to the client.

func (FlushWriter) Write

func (w FlushWriter) Write(p []byte) (int, error)

type Retry

type Retry struct {
	// Client is the underlying HTTP client.
	// Using Client directly bypasses the
	// retry mechanism.
	http.Client

	// N is the number of retry attempts. If a request
	// fails because of a temporary network error or
	// 5xx response code then Retry keeps sending the
	// same request N times before giving up and returning
	// the last error encountered.
	N uint

	// Delay is the duration Retry waits at least before
	// retrying a request.
	Delay time.Duration

	// Jitter is the maximum duration Retry adds to Delay.
	// Retry waits at most Delay + Jitter before retrying
	// a request.
	//
	// In particular, Retry chooses a pseudo-random
	// duration [0, Jitter) and adds it do Delay.
	Jitter time.Duration
}

Retry wraps an HTTP client and retries requests when they fail because of a temporary network error or a 5xx response status code.

Its zero value is a usable client that uses http.DefaultTransport and may retry a request a few times before giving up.

If a request contains a non-nil body then this body must implement io.Seeker. Any io.ReadSeeker can be turned into a request body via the RetryReader function.

Retry retries a request at most N times and waits at least Delay and at most Delay + Jitter before sending the request again. If not specified then Retry uses sane default values for N, Delay and Jitter.

func (*Retry) Do

func (r *Retry) Do(req *http.Request) (*http.Response, error)

Do sends an HTTP request and returns an HTTP response, following policy (such as redirects, cookies, auth) as configured on the client and as specified by http.Client.

If the request fails due to a temporary network error or the server returns a 5xx response then Do retries the request N times.

If non-nil, the request body must implement io.Seeker.

Any returned error will be of type *url.Error. The url.Error value's Timeout method will report true if request timed out or was canceled.

func (*Retry) Get

func (r *Retry) Get(url string) (*http.Response, error)

Get issues a GET to the specified URL as specified by http.Client. It follows redirects after calling the underlying Client's CheckRedirect function.

If the GET fails due to a temporary network error or 5xx server response then GET retries the request N times.

func (*Retry) Head

func (r *Retry) Head(url string) (*http.Response, error)

Head issues a HEAD to the specified URL as specified by http.Client. It follows redirects after calling the underlying Client's CheckRedirect function.

If the HEAD fails due to a temporary network error or 5xx server response then Head retries the request N times.

func (*Retry) Post

func (r *Retry) Post(url, contentType string, body io.Reader) (*http.Response, error)

Post issues a POST to the specified URL as specified by http.Client. The provided body must implement io.Seeker and io.Closer. To obtain an io.Closer from an io.ReadSeeker refer to the RetryReader function.

Caller should close resp.Body when done reading from it.

If the POST fails due to a temporary network error or 5xx server response the Post retries the request N times.

See the Retry.Do method documentation for details on how redirects are handled.

func (*Retry) PostForm

func (r *Retry) PostForm(url string, data url.Values) (*http.Response, error)

PostForm issues a POST to the specified URL as specified by http.Client, with data's keys and values URL-encoded as the request body.

The Content-Type header is set to application/x-www-form-urlencoded.

If the POST fails due to a temporary network error or 5xx server response the Post retries the request N times.

See the Client.Do method documentation for details on how redirects are handled.

type ServerConfig

type ServerConfig struct {
	// Version is the KES server version.
	// If empty, it defaults to v0.0.0-dev.
	Version string

	// Certificate is TLS server certificate.
	Certificate *Certificate

	Vault sys.Vault

	// Proxy is an optional TLS proxy that sits
	// in-front of this server and forwards client
	// requests.
	//
	// A TLS proxy is responsible for forwarding
	// the client certificates via a request
	// header such that this server can apply
	// the corresponding policy.
	Proxy *auth.TLSProxy

	// AuditLog is a log target that receives
	// audit log events.
	AuditLog *xlog.Target

	// ErrorLog is a log target that receives
	// error log events.
	ErrorLog *xlog.Target

	// Metrics gathers various informations about
	// the server.
	Metrics *metric.Metrics

	APIs []API
}

A ServerConfig structure is used to configure a KES server.