httpz

Documentation

Index

• Constants
• func HasHeaderValue(h http.Header, key, value string) bool
• func IsContentType(actual string, expected ...string) bool
• func IterHeaderValues(h http.Header, key string) iter.Seq[string]
• func MergeURLPathAndQuery(baseURL *url.URL, extraPath string, query url.Values) string
• func RemoveConnectionHeaders(h http.Header)
• func RemoveHeaderValue(h http.Header, key string, f func(s string) bool)
• func RunServer(ctx context.Context, srv *http.Server, listener net.Listener, ...) error
• func RunServerWithUpgradeSupport(ctx context.Context, srv *http.Server, listener net.Listener, ...) error
• type ContextConn
  • func NewContextConn(conn net.Conn) *ContextConn
  • func (c *ContextConn) Close() error
  • func (c *ContextConn) CloseOnDone(ctx context.Context)
• type ControlFunc
  • func NewSafeNetDialerControl(cfg *SafeNetControlConfig) ControlFunc
• type Limiter
• type RateLimitingRoundTripper
  • func (r *RateLimitingRoundTripper) RoundTrip(request *http.Request) (*http.Response, error)
• type SafeNetControlConfig
• type UpgradeRoundTripper
  • func (u *UpgradeRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
• type WriteTimeoutConn
  • func (c *WriteTimeoutConn) Write(b []byte) (int, error)

Constants

const (
	ConnectionHeader                    = "Connection" // https://datatracker.ietf.org/doc/html/rfc9110#section-7.6.1
	ProxyConnectionHeader               = "Proxy-Connection"
	KeepAliveHeader                     = "Keep-Alive"
	HostHeader                          = "Host"
	ProxyAuthenticateHeader             = "Proxy-Authenticate"
	ProxyAuthorizationHeader            = "Proxy-Authorization"
	TeHeader                            = "Te"      // canonicalized version of "TE"
	TrailerHeader                       = "Trailer" // not Trailers as per rfc2616; See errata https://www.rfc-editor.org/errata_search.php?eid=4522
	TransferEncodingHeader              = "Transfer-Encoding"
	UpgradeHeader                       = "Upgrade" // https://datatracker.ietf.org/doc/html/rfc9110#section-7.8
	UserAgentHeader                     = "User-Agent"
	AuthorizationHeader                 = "Authorization" // https://datatracker.ietf.org/doc/html/rfc9110#section-11.6.2
	CookieHeader                        = "Cookie"        // https://datatracker.ietf.org/doc/html/rfc6265#section-5.4
	SetCookieHeader                     = "Set-Cookie"    // https://datatracker.ietf.org/doc/html/rfc6265#section-4.1
	ContentTypeHeader                   = "Content-Type"  // https://datatracker.ietf.org/doc/html/rfc9110#section-8.3
	AcceptHeader                        = "Accept"        // https://datatracker.ietf.org/doc/html/rfc9110#section-12.5.1
	ServerHeader                        = "Server"        // https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.4
	ViaHeader                           = "Via"           // https://datatracker.ietf.org/doc/html/rfc9110#section-7.6.3
	GitlabAgentIDHeader                 = "Gitlab-Agent-Id"
	GitlabAgentIDQueryParam             = "gitlab-agent-id"
	GitlabUnauthorizedHeader            = "Gitlab-Unauthorized"
	GitlabAgentVersionHeader            = "Gitlab-Agent-Version"
	CSRFTokenHeader                     = "X-Csrf-Token"                     //nolint: gosec
	CSRFTokenQueryParam                 = "gitlab-csrf-token"                //nolint: gosec
	AccessControlAllowOriginHeader      = "Access-Control-Allow-Origin"      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
	AccessControlAllowHeadersHeader     = "Access-Control-Allow-Headers"     // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers
	AccessControlAllowCredentialsHeader = "Access-Control-Allow-Credentials" // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials
	AccessControlAllowMethodsHeader     = "Access-Control-Allow-Methods"     // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods
	AccessControlMaxAgeHeader           = "Access-Control-Max-Age"           // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age
	AccessControlRequestHeadersHeader   = "Access-Control-Request-Headers"   // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers
	VaryHeader                          = "Vary"                             // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary
	OriginHeader                        = "Origin"                           // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin
	RequestIDHeader                     = "X-Request-Id"
	WarningHeader                       = "Warning"                // https://datatracker.ietf.org/doc/html/rfc2068#section-14.45
	SecWebSocketProtocolHeader          = "Sec-Websocket-Protocol" // https://datatracker.ietf.org/doc/html/rfc6455#section-11.3.4
	NELHeader                           = "Nel"                    // https://w3c.github.io/network-error-logging/#dfn-nel
	ReportToHeader                      = "Report-To"              // https://w3c.github.io/network-error-logging/#the-report_to-member

	// TLSNextProtoH2 is the NPN/ALPN protocol negotiated during HTTP/2's TLS setup.
	TLSNextProtoH2 = "h2"
	TLSNextProtoH1 = "http/1.1"

	// H2ClientPreface is the string that must be sent by new
	// connections from clients.
	H2ClientPreface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
)

These headers must be in their canonical form. Only add headers used in production code, don't bother with tests. Make sure to update the expectedNumberOfDefinedHeaders constant in the test file when adding or removing a header constant.

Functions

func HasHeaderValue

func HasHeaderValue(h http.Header, key, value string) bool

func IsContentType

func IsContentType(actual string, expected ...string) bool

func IterHeaderValues

func IterHeaderValues(h http.Header, key string) iter.Seq[string]

IterHeaderValues returns an iterator to iterate all values for the given header key. The key must be in canonical format.

func MergeURLPathAndQuery

func MergeURLPathAndQuery(baseURL *url.URL, extraPath string, query url.Values) string

func RemoveConnectionHeaders

func RemoveConnectionHeaders(h http.Header)

RemoveConnectionHeaders removes hop-by-hop headers listed in the "Connection" header of h. See https://datatracker.ietf.org/doc/html/rfc7230#section-6.1

func RemoveHeaderValue

func RemoveHeaderValue(h http.Header, key string, f func(s string) bool)

RemoveHeaderValue removes all values in for given header key. If no values are left for that key, the key is removed entirely. All values for the given key will be merged into a single appearance of key in h.

func RunServer

func RunServer(ctx context.Context, srv *http.Server, listener net.Listener, listenerGracePeriod, shutdownTimeout time.Duration) error

func RunServerWithUpgradeSupport

func RunServerWithUpgradeSupport(ctx context.Context, srv *http.Server, listener net.Listener, listenerGracePeriod, shutdownTimeout time.Duration) error

RunServerWithUpgradeSupport runs the HTTP server, tracking lifetimes of all hijacked connections. http.Server#Close() and http.Server#Shutdown() do not shut down hijacked connections. This helper should be used to run servers that support HTTP connection upgrade. Note: this function does not unblock read or write calls on the underlying network connection, it only cancels the connection's context. Calling code is responsible for reacting to context cancellation, potentially by calling Close() on the hijacked network connection.

Types

type ContextConn

type ContextConn struct {
	net.Conn
	// contains filtered or unexported fields
}

ContextConn is a wrapper around net.Conn that can be used to tie connection lifetime to context cancellation.

func NewContextConn

func NewContextConn(conn net.Conn) *ContextConn

func (*ContextConn) Close

func (c *ContextConn) Close() error

func (*ContextConn) CloseOnDone

func (c *ContextConn) CloseOnDone(ctx context.Context)

type ControlFunc

type ControlFunc func(network, address string, c syscall.RawConn) error

func NewSafeNetDialerControl

func NewSafeNetDialerControl(cfg *SafeNetControlConfig) ControlFunc

NewSafeNetDialerControl creates a safe Control function that can be used in a net.Dialer. Safe means: - prevent access to not allowed network types. Allowed are tcp4 and tcp6 connections. - prevent access to not allowed ports (configurable). - prevent access to not allowed IP addresses:

• prevent access to loopback
• prevent access to IPv4 broadcast (non global unicast address)
• prevent access to multicast (non global unicast address)
• prevent access to link local unicast (non global unicast address)
• prevent access to private addresses as specified by RFC 1918 (IPv4 addresses) and RFC 4193 (IPv6 addresses).

This function takes owner ship of the passed SafeNetControlConfig. Do not modify it once passed and only use it once.

type Limiter

type Limiter interface {
	// Wait blocks until limiter permits an event to happen.
	// It returns an error if the Context is
	// canceled, or the expected wait time exceeds the Context's Deadline.
	Wait(context.Context) error
}

Limiter defines the interface to perform client-side request rate limiting. You can use golang.org/x/time/rate.Limiter as an implementation of this interface.

type RateLimitingRoundTripper

type RateLimitingRoundTripper struct {
	Delegate http.RoundTripper
	Limiter  Limiter
}

func (*RateLimitingRoundTripper) RoundTrip

func (r *RateLimitingRoundTripper) RoundTrip(request *http.Request) (*http.Response, error)

type SafeNetControlConfig

type SafeNetControlConfig struct {
	// AllowedPorts use to explicitly allow a set of ports.
	// If not set, will default to defaultAllowedPorts.
	AllowedPorts []uint16
	// AllowedIPs use to explicitly allow a set of specific IPs.
	AllowedIPs []netip.Addr
	// AllowedIPCIDRs use to explicitly allow a set of specific IP CIDRs.
	AllowedIPCIDRs []netip.Prefix
	// BlockedIPs use to explicitly block a set of specific IPs.
	// This takes precedence over all other IP-based checks.
	BlockedIPs []netip.Addr
	// BlockedIPCIDRs use to explicitly block a set of specific IP CIDRs.
	// This takes precedence over all other IP-based checks.
	BlockedIPCIDRs []netip.Prefix
}

type UpgradeRoundTripper

type UpgradeRoundTripper struct {
	// Dialer is the dialer used to connect.
	Dialer *net.Dialer

	// TLSDialer is the dialer used to connect over TLS.
	TLSDialer *tls.Dialer

	// Conn is the underlying network connection to the remote server.
	Conn net.Conn

	// ConnReader is a buffered reader for Conn.
	// It may contain some data that has been buffered from Conn while reading the server's response.
	ConnReader *bufio.Reader
}

UpgradeRoundTripper allows to access the underlying network connection after round tripping a request/response. A http.RoundTripper must be safe for concurrent use by multiple goroutines, but this implementation is not. It does not pool network connections so it's not worth the complexity. Instead, the using code must use a new instance for each request. See https://pkg.go.dev/net/http#RoundTripper.

func (*UpgradeRoundTripper) RoundTrip

func (u *UpgradeRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

type WriteTimeoutConn

type WriteTimeoutConn struct {
	net.Conn
	Timeout time.Duration
}

func (*WriteTimeoutConn) Write

func (c *WriteTimeoutConn) Write(b []byte) (int, error)