httpz

Documentation

Index

• Constants
• func IsContentType(actual string, expected ...string) bool
• func MergeURLPathAndQuery(baseURL *url.URL, extraPath string, query url.Values) string
• func RemoveConnectionHeaders(h http.Header)
• 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 Limiter
• type RateLimitingRoundTripper
  • func (r *RateLimitingRoundTripper) RoundTrip(request *http.Request) (*http.Response, error)
• 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

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

Functions

func IsContentType

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

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