http.go

     1  // Copyright 2016 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:generate bundle -o=h2_bundle.go -prefix=http2 -tags=!nethttpomithttp2 golang.org/x/net/http2
     6  
     7  package http
     8  
     9  import (
    10  	"io"
    11  	"strconv"
    12  	"strings"
    13  	"time"
    14  	"unicode/utf8"
    15  
    16  	"golang.org/x/net/http/httpguts"
    17  )
    18  
    19  // Protocols is a set of HTTP protocols.
    20  // The zero value is an empty set of protocols.
    21  //
    22  // The supported protocols are:
    23  //
    24  //   - HTTP1 is the HTTP/1.0 and HTTP/1.1 protocols.
    25  //     HTTP1 is supported on both unsecured TCP and secured TLS connections.
    26  //
    27  //   - HTTP2 is the HTTP/2 protcol over a TLS connection.
    28  //
    29  //   - UnencryptedHTTP2 is the HTTP/2 protocol over an unsecured TCP connection.
    30  type Protocols struct {
    31  	bits uint8
    32  }
    33  
    34  const (
    35  	protoHTTP1 = 1 << iota
    36  	protoHTTP2
    37  	protoUnencryptedHTTP2
    38  )
    39  
    40  // HTTP1 reports whether p includes HTTP/1.
    41  func (p Protocols) HTTP1() bool { return p.bits&protoHTTP1 != 0 }
    42  
    43  // SetHTTP1 adds or removes HTTP/1 from p.
    44  func (p *Protocols) SetHTTP1(ok bool) { p.setBit(protoHTTP1, ok) }
    45  
    46  // HTTP2 reports whether p includes HTTP/2.
    47  func (p Protocols) HTTP2() bool { return p.bits&protoHTTP2 != 0 }
    48  
    49  // SetHTTP2 adds or removes HTTP/2 from p.
    50  func (p *Protocols) SetHTTP2(ok bool) { p.setBit(protoHTTP2, ok) }
    51  
    52  // UnencryptedHTTP2 reports whether p includes unencrypted HTTP/2.
    53  func (p Protocols) UnencryptedHTTP2() bool { return p.bits&protoUnencryptedHTTP2 != 0 }
    54  
    55  // SetUnencryptedHTTP2 adds or removes unencrypted HTTP/2 from p.
    56  func (p *Protocols) SetUnencryptedHTTP2(ok bool) { p.setBit(protoUnencryptedHTTP2, ok) }
    57  
    58  func (p *Protocols) setBit(bit uint8, ok bool) {
    59  	if ok {
    60  		p.bits |= bit
    61  	} else {
    62  		p.bits &^= bit
    63  	}
    64  }
    65  
    66  func (p Protocols) String() string {
    67  	var s []string
    68  	if p.HTTP1() {
    69  		s = append(s, "HTTP1")
    70  	}
    71  	if p.HTTP2() {
    72  		s = append(s, "HTTP2")
    73  	}
    74  	if p.UnencryptedHTTP2() {
    75  		s = append(s, "UnencryptedHTTP2")
    76  	}
    77  	return "{" + strings.Join(s, ",") + "}"
    78  }
    79  
    80  // incomparable is a zero-width, non-comparable type. Adding it to a struct
    81  // makes that struct also non-comparable, and generally doesn't add
    82  // any size (as long as it's first).
    83  type incomparable [0]func()
    84  
    85  // maxInt64 is the effective "infinite" value for the Server and
    86  // Transport's byte-limiting readers.
    87  const maxInt64 = 1<<63 - 1
    88  
    89  // aLongTimeAgo is a non-zero time, far in the past, used for
    90  // immediate cancellation of network operations.
    91  var aLongTimeAgo = time.Unix(1, 0)
    92  
    93  // omitBundledHTTP2 is set by omithttp2.go when the nethttpomithttp2
    94  // build tag is set. That means h2_bundle.go isn't compiled in and we
    95  // shouldn't try to use it.
    96  var omitBundledHTTP2 bool
    97  
    98  // TODO(bradfitz): move common stuff here. The other files have accumulated
    99  // generic http stuff in random places.
   100  
   101  // contextKey is a value for use with context.WithValue. It's used as
   102  // a pointer so it fits in an interface{} without allocation.
   103  type contextKey struct {
   104  	name string
   105  }
   106  
   107  func (k *contextKey) String() string { return "net/http context value " + k.name }
   108  
   109  // Given a string of the form "host", "host:port", or "[ipv6::address]:port",
   110  // return true if the string includes a port.
   111  func hasPort(s string) bool { return strings.LastIndex(s, ":") > strings.LastIndex(s, "]") }
   112  
   113  // removeEmptyPort strips the empty port in ":port" to ""
   114  // as mandated by RFC 3986 Section 6.2.3.
   115  func removeEmptyPort(host string) string {
   116  	if hasPort(host) {
   117  		return strings.TrimSuffix(host, ":")
   118  	}
   119  	return host
   120  }
   121  
   122  func isNotToken(r rune) bool {
   123  	return !httpguts.IsTokenRune(r)
   124  }
   125  
   126  // stringContainsCTLByte reports whether s contains any ASCII control character.
   127  func stringContainsCTLByte(s string) bool {
   128  	for i := 0; i < len(s); i++ {
   129  		b := s[i]
   130  		if b < ' ' || b == 0x7f {
   131  			return true
   132  		}
   133  	}
   134  	return false
   135  }
   136  
   137  func hexEscapeNonASCII(s string) string {
   138  	newLen := 0
   139  	for i := 0; i < len(s); i++ {
   140  		if s[i] >= utf8.RuneSelf {
   141  			newLen += 3
   142  		} else {
   143  			newLen++
   144  		}
   145  	}
   146  	if newLen == len(s) {
   147  		return s
   148  	}
   149  	b := make([]byte, 0, newLen)
   150  	var pos int
   151  	for i := 0; i < len(s); i++ {
   152  		if s[i] >= utf8.RuneSelf {
   153  			if pos < i {
   154  				b = append(b, s[pos:i]...)
   155  			}
   156  			b = append(b, '%')
   157  			b = strconv.AppendInt(b, int64(s[i]), 16)
   158  			pos = i + 1
   159  		}
   160  	}
   161  	if pos < len(s) {
   162  		b = append(b, s[pos:]...)
   163  	}
   164  	return string(b)
   165  }
   166  
   167  // NoBody is an [io.ReadCloser] with no bytes. Read always returns EOF
   168  // and Close always returns nil. It can be used in an outgoing client
   169  // request to explicitly signal that a request has zero bytes.
   170  // An alternative, however, is to simply set [Request.Body] to nil.
   171  var NoBody = noBody{}
   172  
   173  type noBody struct{}
   174  
   175  func (noBody) Read([]byte) (int, error)         { return 0, io.EOF }
   176  func (noBody) Close() error                     { return nil }
   177  func (noBody) WriteTo(io.Writer) (int64, error) { return 0, nil }
   178  
   179  var (
   180  	// verify that an io.Copy from NoBody won't require a buffer:
   181  	_ io.WriterTo   = NoBody
   182  	_ io.ReadCloser = NoBody
   183  )
   184  
   185  // PushOptions describes options for [Pusher.Push].
   186  type PushOptions struct {
   187  	// Method specifies the HTTP method for the promised request.
   188  	// If set, it must be "GET" or "HEAD". Empty means "GET".
   189  	Method string
   190  
   191  	// Header specifies additional promised request headers. This cannot
   192  	// include HTTP/2 pseudo header fields like ":path" and ":scheme",
   193  	// which will be added automatically.
   194  	Header Header
   195  }
   196  
   197  // Pusher is the interface implemented by ResponseWriters that support
   198  // HTTP/2 server push. For more background, see
   199  // https://tools.ietf.org/html/rfc7540#section-8.2.
   200  type Pusher interface {
   201  	// Push initiates an HTTP/2 server push. This constructs a synthetic
   202  	// request using the given target and options, serializes that request
   203  	// into a PUSH_PROMISE frame, then dispatches that request using the
   204  	// server's request handler. If opts is nil, default options are used.
   205  	//
   206  	// The target must either be an absolute path (like "/path") or an absolute
   207  	// URL that contains a valid host and the same scheme as the parent request.
   208  	// If the target is a path, it will inherit the scheme and host of the
   209  	// parent request.
   210  	//
   211  	// The HTTP/2 spec disallows recursive pushes and cross-authority pushes.
   212  	// Push may or may not detect these invalid pushes; however, invalid
   213  	// pushes will be detected and canceled by conforming clients.
   214  	//
   215  	// Handlers that wish to push URL X should call Push before sending any
   216  	// data that may trigger a request for URL X. This avoids a race where the
   217  	// client issues requests for X before receiving the PUSH_PROMISE for X.
   218  	//
   219  	// Push will run in a separate goroutine making the order of arrival
   220  	// non-deterministic. Any required synchronization needs to be implemented
   221  	// by the caller.
   222  	//
   223  	// Push returns ErrNotSupported if the client has disabled push or if push
   224  	// is not supported on the underlying connection.
   225  	Push(target string, opts *PushOptions) error
   226  }
   227  
   228  // HTTP2Config defines HTTP/2 configuration parameters common to
   229  // both [Transport] and [Server].
   230  type HTTP2Config struct {
   231  	// MaxConcurrentStreams optionally specifies the number of
   232  	// concurrent streams that a peer may have open at a time.
   233  	// If zero, MaxConcurrentStreams defaults to at least 100.
   234  	MaxConcurrentStreams int
   235  
   236  	// MaxDecoderHeaderTableSize optionally specifies an upper limit for the
   237  	// size of the header compression table used for decoding headers sent
   238  	// by the peer.
   239  	// A valid value is less than 4MiB.
   240  	// If zero or invalid, a default value is used.
   241  	MaxDecoderHeaderTableSize int
   242  
   243  	// MaxEncoderHeaderTableSize optionally specifies an upper limit for the
   244  	// header compression table used for sending headers to the peer.
   245  	// A valid value is less than 4MiB.
   246  	// If zero or invalid, a default value is used.
   247  	MaxEncoderHeaderTableSize int
   248  
   249  	// MaxReadFrameSize optionally specifies the largest frame
   250  	// this endpoint is willing to read.
   251  	// A valid value is between 16KiB and 16MiB, inclusive.
   252  	// If zero or invalid, a default value is used.
   253  	MaxReadFrameSize int
   254  
   255  	// MaxReceiveBufferPerConnection is the maximum size of the
   256  	// flow control window for data received on a connection.
   257  	// A valid value is at least 64KiB and less than 4MiB.
   258  	// If invalid, a default value is used.
   259  	MaxReceiveBufferPerConnection int
   260  
   261  	// MaxReceiveBufferPerStream is the maximum size of
   262  	// the flow control window for data received on a stream (request).
   263  	// A valid value is less than 4MiB.
   264  	// If zero or invalid, a default value is used.
   265  	MaxReceiveBufferPerStream int
   266  
   267  	// SendPingTimeout is the timeout after which a health check using a ping
   268  	// frame will be carried out if no frame is received on a connection.
   269  	// If zero, no health check is performed.
   270  	SendPingTimeout time.Duration
   271  
   272  	// PingTimeout is the timeout after which a connection will be closed
   273  	// if a response to a ping is not received.
   274  	// If zero, a default of 15 seconds is used.
   275  	PingTimeout time.Duration
   276  
   277  	// WriteByteTimeout is the timeout after which a connection will be
   278  	// closed if no data can be written to it. The timeout begins when data is
   279  	// available to write, and is extended whenever any bytes are written.
   280  	WriteByteTimeout time.Duration
   281  
   282  	// PermitProhibitedCipherSuites, if true, permits the use of
   283  	// cipher suites prohibited by the HTTP/2 spec.
   284  	PermitProhibitedCipherSuites bool
   285  
   286  	// CountError, if non-nil, is called on HTTP/2 errors.
   287  	// It is intended to increment a metric for monitoring.
   288  	// The errType contains only lowercase letters, digits, and underscores
   289  	// (a-z, 0-9, _).
   290  	CountError func(errType string)
   291  }
   292
View as plain text