httputil

Documentation

Overview

Package httputil provides HTTP utility functions, complementing the more common ones in the net/http package

Index

• Constants
• Variables
• func CSRFFailureHandler(w http.ResponseWriter, r *http.Request) error
• func DetailsText(code int) string
• func Do(ctx context.Context, method, endpoint, userAgent string, ...) error
• func HealthCheck(w http.ResponseWriter, r *http.Request)
• func NewError(status int, err error) error
• func NewLoggingClient(base *http.Client, customize ...func(event *zerolog.Event) *zerolog.Event) *http.Client
• func NewLoggingRoundTripper(base http.RoundTripper, customize ...func(event *zerolog.Event) *zerolog.Event) http.RoundTripper
• func NewRouter() *mux.Router
• func NewServer(opt *ServerOptions, h http.Handler, wg *sync.WaitGroup) (*http.Server, error)
• func PomeriumJWTHeaderName(claim string) string
• func Redirect(w http.ResponseWriter, r *http.Request, url string, code int)
• func RedirectHandler() http.Handler
• func RenderJSON(w http.ResponseWriter, code int, v interface{})
• func Shutdown(srv *http.Server)
• func StatusText(code int) string
• type HTTPError
  • func (e *HTTPError) Error() string
  • func (e *HTTPError) ErrorResponse(w http.ResponseWriter, r *http.Request)
  • func (e *HTTPError) Unwrap() error
• type HandlerFunc
  • func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerOptions

Constants

const (
	HeaderReferrer         = "Referer"
	HeaderImpersonateGroup = "Impersonate-Group"
	HeaderUpgrade          = "Upgrade"
)

Standard headers

const (
	// HeaderPomeriumResponse is set when pomerium itself creates a response,
	// as opposed to the upstream application and can be used to distinguish
	// between an application error, and a pomerium related error when debugging.
	// Especially useful when working with single page apps (SPA).
	HeaderPomeriumResponse = "x-pomerium-intercepted-response"
	// HeaderPomeriumJWTAssertion is the header key containing JWT signed user details.
	HeaderPomeriumJWTAssertion = "x-pomerium-jwt-assertion"
	// HeaderPomeriumJWTAssertionFor carries over original user identity from a chain of network calls.
	HeaderPomeriumJWTAssertionFor = "x-pomerium-jwt-assertion-for"
	// HeaderPomeriumReproxyPolicy is the header key containing the policy to reproxy a request to.
	HeaderPomeriumReproxyPolicy = "x-pomerium-reproxy-policy"
	// HeaderPomeriumReproxyPolicyHMAC is an HMAC of the HeaderPomeriumReproxyPolicy header.
	HeaderPomeriumReproxyPolicyHMAC = "x-pomerium-reproxy-policy-hmac"
)

Pomerium headers contain information added to a request.

const (
	HeaderForwardedFor    = "X-Forwarded-For"
	HeaderForwardedHost   = "X-Forwarded-Host"
	HeaderForwardedMethod = "X-Forwarded-Method" // traefik
	HeaderForwardedPort   = "X-Forwarded-Port"
	HeaderForwardedProto  = "X-Forwarded-Proto"
	HeaderForwardedServer = "X-Forwarded-Server"
	HeaderForwardedURI    = "X-Forwarded-Uri"   // traefik
	HeaderOriginalMethod  = "X-Original-Method" // nginx
	HeaderOriginalURL     = "X-Original-Url"    // nginx
	HeaderRealIP          = "X-Real-Ip"
	HeaderSentFrom        = "X-Sent-From"
)

Forward headers contains information from the client-facing side of proxy servers that is altered or lost when a proxy is involved in the path of the request.

https://tools.ietf.org/html/rfc7239 https://en.wikipedia.org/wiki/X-Forwarded-For

const (
	// StatusDeviceUnauthorized is the status code returned when a client's
	// device credential is not authorized to access a page.
	StatusDeviceUnauthorized = 450
	// StatusInvalidClientCertificate is the status code returned when a
	// client's certificate is invalid. This is the same status code used
	// by nginx for this purpose.
	StatusInvalidClientCertificate = 495
)

const AuthorizationTypePomerium = "Pomerium"

AuthorizationTypePomerium is for Authorization: Pomerium JWT... headers

Variables

var ErrTokenRevoked = errors.New("token expired or revoked")

ErrTokenRevoked signifies a token revocation or expiration error

var HeadersContentSecurityPolicy = map[string]string{
	"Content-Security-Policy": "default-src 'none'; style-src 'self' data:; img-src * data:; script-src 'self' 'unsafe-inline'",
	"Referrer-Policy":         "Same-origin",
}

HeadersContentSecurityPolicy are the content security headers added to the service's handlers by default includes profile photo exceptions for supported identity providers. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src

var HeadersXForwarded = []string{
	HeaderForwardedFor,
	HeaderForwardedHost,
	HeaderForwardedMethod,
	HeaderForwardedPort,
	HeaderForwardedProto,
	HeaderForwardedServer,
	HeaderForwardedURI,
	HeaderOriginalMethod,
	HeaderOriginalURL,
	HeaderRealIP,
	HeaderSentFrom,
}

HeadersXForwarded is the slice of the header keys used to contain information from the client-facing side of proxy servers that is altered or lost when a proxy is involved in the path of the request.

https://tools.ietf.org/html/rfc7239 https://en.wikipedia.org/wiki/X-Forwarded-For

Functions

func CSRFFailureHandler

func CSRFFailureHandler(w http.ResponseWriter, r *http.Request) error

CSRFFailureHandler sets a HTTP 403 Forbidden status and writes the CSRF failure reason to the response.

func DetailsText

func DetailsText(code int) string

DetailsText returns extra details for an HTTP status code. It returns StatusText if not found.

func Do

func Do(ctx context.Context, method, endpoint, userAgent string, headers map[string]string, params url.Values, response interface{}) error

Do provides a simple helper interface to make HTTP requests

func HealthCheck

func HealthCheck(w http.ResponseWriter, r *http.Request)

HealthCheck is a simple healthcheck handler that responds to GET and HEAD http requests.

func NewError

func NewError(status int, err error) error

NewError returns an error that contains a HTTP status and error.

func NewLoggingClient

func NewLoggingClient(base *http.Client, customize ...func(event *zerolog.Event) *zerolog.Event) *http.Client

NewLoggingClient creates a new http.Client that will log requests.

func NewLoggingRoundTripper

func NewLoggingRoundTripper(base http.RoundTripper, customize ...func(event *zerolog.Event) *zerolog.Event) http.RoundTripper

NewLoggingRoundTripper creates a http.RoundTripper that will log requests.

func NewRouter

func NewRouter() *mux.Router

NewRouter returns a new router instance.

func NewServer

func NewServer(opt *ServerOptions, h http.Handler, wg *sync.WaitGroup) (*http.Server, error)

NewServer creates a new HTTP server given a set of options, handler, and waitgroup. It is the callers responsibility to close the resturned server.

func PomeriumJWTHeaderName

func PomeriumJWTHeaderName(claim string) string

PomeriumJWTHeaderName returns the header name set by pomerium for given JWT claim field.

func Redirect

func Redirect(w http.ResponseWriter, r *http.Request, url string, code int)

Redirect wraps the std libs's redirect method indicating that pomerium is the origin of the response.

func RedirectHandler

func RedirectHandler() http.Handler

RedirectHandler takes an incoming request and redirects to its HTTPS counterpart

func RenderJSON

func RenderJSON(w http.ResponseWriter, code int, v interface{})

RenderJSON replies to the request with the specified struct as JSON and HTTP code. It does not otherwise end the request; the caller should ensure no further writes are done to w. The error message should be application/json.

func Shutdown

func Shutdown(srv *http.Server)

Shutdown attempts to shut down the server when a os interrupt or sigterm signal are received without interrupting any active connections. Shutdown works by first closing all open listeners, then closing all idle connections, and then waiting indefinitely for connections to return to idle and then shut down. If the provided context expires before the shutdown is complete, Shutdown returns the context's error, otherwise it returns any error returned from closing the Server's underlying Listener(s).

When Shutdown is called, Serve, ListenAndServe, and ListenAndServeTLS immediately return ErrServerClosed.

func StatusText

func StatusText(code int) string

StatusText returns a text for the HTTP status code. It returns http.StatusText if not found.

Types

type HTTPError

type HTTPError struct {
	// HTTP status codes as registered with IANA.
	Status int
	// Err is the wrapped error.
	Err error
	// DebugURL is the URL to the debug endpoint.
	DebugURL *url.URL
	// The request ID.
	RequestID string
}

HTTPError contains an HTTP status code and wrapped error.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements the `error` interface.

func (*HTTPError) ErrorResponse

func (e *HTTPError) ErrorResponse(w http.ResponseWriter, r *http.Request)

ErrorResponse replies to the request with the specified error message and HTTP code. It does not otherwise end the request; the caller should ensure no further writes are done to w.

func (*HTTPError) Unwrap

func (e *HTTPError) Unwrap() error

Unwrap implements the `error` Unwrap interface.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request) error

The HandlerFunc type is an adapter to allow the use of ordinary functions as HTTP handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler that calls f.

adapted from std library to suppport error wrapping

func (HandlerFunc) ServeHTTP

func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP calls f(w, r) error.

type ServerOptions

type ServerOptions struct {
	// Addr specifies the host and port on which the server should serve
	// HTTPS requests. If empty, ":443" is used.
	Addr string

	// TLSConfig is the tls configuration used to setup the HTTPS server.
	TLSConfig *tls.Config

	// InsecureServer when enabled disables all transport security.
	// In this mode, Pomerium is susceptible to man-in-the-middle attacks.
	// This should be used only for testing.
	Insecure bool

	// Service is an optional field that helps define what the server's role is.
	Service string

	// Timeouts
	ReadHeaderTimeout time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
}

ServerOptions contains the configurations settings for a http server.