httputil

Documentation

Overview

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

Index

• Constants
• Variables
• func AddBrandingOptionsToMap(dst map[string]any, brandingOptions BrandingOptions)
• func CSRFFailureHandler(_ http.ResponseWriter, r *http.Request) error
• func DashboardSubrouter(parent *mux.Router) *mux.Router
• func DetailsText(code int) string
• func Do(ctx context.Context, method, endpoint, userAgent string, ...) error
• func GetClientIP(r *http.Request) string
• func GetClientIPAddress(r *http.Request) string
• func GetInsecureTransport() *http.Transport
• func GetSignedOutRedirectURICookie(w http.ResponseWriter, r *http.Request) (string, bool)
• func NewLoggingClient(base *http.Client, name string, ...) *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 any)
• func SetSignedOutRedirectURICookie(w http.ResponseWriter, redirectURI string)
• func Shutdown(srv *http.Server)
• func StatusText(code int) string
• type BrandingOptions
• type CookieChunker
  • func NewCookieChunker(options ...CookieChunkerOption) *CookieChunker
  • func (cc *CookieChunker) LoadCookie(r *http.Request, name string) (*http.Cookie, error)
  • func (cc *CookieChunker) SetCookie(w http.ResponseWriter, cookie *http.Cookie) error
• type CookieChunkerOption
  • func WithCookieChunkerChunkSize(chunkSize int) CookieChunkerOption
  • func WithCookieChunkerMaxChunks(maxChunks int) CookieChunkerOption
• type HTTPError
  • func NewError(status int, err error) *HTTPError
  • func (e *HTTPError) Error() string
  • func (e *HTTPError) ErrorResponse(ctx context.Context, w http.ResponseWriter, r *http.Request)
  • func (e *HTTPError) Unwrap() error
  • func (e *HTTPError) WithDescription(description string) *HTTPError
• type HandlerFunc
  • func (f HandlerFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerOptions

Constants

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

Standard headers

const (
	// HeaderPomeriumAuthorization is the header key for a pomerium authorization JWT. It
	// can be used in place of the standard authorization header if that header is being
	// used by upstream applications.
	HeaderPomeriumAuthorization = "x-pomerium-authorization"
	// 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"
	// HeaderPomeriumRoutingKey is a string used for routing user requests to a consistent upstream server.
	HeaderPomeriumRoutingKey = "x-pomerium-routing-key"
)

Pomerium headers contain information added to a request.

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 CanonicalHeaderKey = log.CanonicalHeaderKey

CanonicalHeaderKey re-exports the log.CanonicalHeaderKey function to avoid an import cycle.

var ErrCookieTooLarge = errors.New("cookie too large")

ErrCookieTooLarge indicates that a cookie is too large.

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' 'unsafe-inline' data:; img-src * data:; script-src 'self' 'unsafe-inline'; font-src data:",
	"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

Functions

func AddBrandingOptionsToMap

func AddBrandingOptionsToMap(dst map[string]any, brandingOptions BrandingOptions)

AddBrandingOptionsToMap adds the branding options to the map.

func CSRFFailureHandler

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

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

func DashboardSubrouter

func DashboardSubrouter(parent *mux.Router) *mux.Router

DashboardSubrouter returns the .pomerium sub router.

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 any) error

Do provides a simple helper interface to make HTTP requests

func GetClientIP

func GetClientIP(r *http.Request) string

GetClientIP returns the client IP address from the request.

func GetClientIPAddress

func GetClientIPAddress(r *http.Request) string

GetClientIPAddress gets a client's IP address for an HTTP request.

func GetInsecureTransport

func GetInsecureTransport() *http.Transport

GetInsecureTransport gets an insecure HTTP transport.

func GetSignedOutRedirectURICookie

func GetSignedOutRedirectURICookie(w http.ResponseWriter, r *http.Request) (string, bool)

GetSignedOutRedirectURICookie gets the redirect uri cookie for the signed-out page.

func NewLoggingClient

func NewLoggingClient(base *http.Client, name string, 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 any)

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 SetSignedOutRedirectURICookie

func SetSignedOutRedirectURICookie(w http.ResponseWriter, redirectURI string)

SetSignedOutRedirectURICookie sets the redirect uri cookie for the signed-out page.

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 BrandingOptions

type BrandingOptions interface {
	GetPrimaryColor() string
	GetSecondaryColor() string
	GetDarkmodePrimaryColor() string
	GetDarkmodeSecondaryColor() string
	GetLogoUrl() string
	GetFaviconUrl() string
	GetErrorMessageFirstParagraph() string
}

The BrandingOptions customize the user info and error pages.

type CookieChunker

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

A CookieChunker breaks up a large cookie into multiple pieces.

func NewCookieChunker

func NewCookieChunker(options ...CookieChunkerOption) *CookieChunker

NewCookieChunker creates a new CookieChunker.

func (*CookieChunker) LoadCookie

func (cc *CookieChunker) LoadCookie(r *http.Request, name string) (*http.Cookie, error)

LoadCookie loads a chunked cookie.

func (*CookieChunker) SetCookie

func (cc *CookieChunker) SetCookie(w http.ResponseWriter, cookie *http.Cookie) error

SetCookie sets a chunked cookie.

type CookieChunkerOption

type CookieChunkerOption func(cfg *cookieChunkerConfig)

A CookieChunkerOption customizes the cookie chunker.

func WithCookieChunkerChunkSize

func WithCookieChunkerChunkSize(chunkSize int) CookieChunkerOption

WithCookieChunkerChunkSize sets the chunk size for the cookie chunker.

func WithCookieChunkerMaxChunks

func WithCookieChunkerMaxChunks(maxChunks int) CookieChunkerOption

WithCookieChunkerMaxChunks sets the maximum number of chunks for the cookie chunker.

type HTTPError

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

	BrandingOptions BrandingOptions
}

HTTPError contains an HTTP status code and wrapped error.

func NewError

func NewError(status int, err error) *HTTPError

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

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements the `error` interface.

func (*HTTPError) ErrorResponse

func (e *HTTPError) ErrorResponse(ctx context.Context, 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.

func (*HTTPError) WithDescription

func (e *HTTPError) WithDescription(description string) *HTTPError

WithDescription sets the description in the HTTP error.

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