Source file src/net/http/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 -import=golang.org/x/net/internal/httpcommon=net/http/internal/httpcommon 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 // isToken reports whether v is a valid token (https://www.rfc-editor.org/rfc/rfc2616#section-2.2). 123 func isToken(v string) bool { 124 // For historical reasons, this function is called ValidHeaderFieldName (see issue #67031). 125 return httpguts.ValidHeaderFieldName(v) 126 } 127 128 // stringContainsCTLByte reports whether s contains any ASCII control character. 129 func stringContainsCTLByte(s string) bool { 130 for i := 0; i < len(s); i++ { 131 b := s[i] 132 if b < ' ' || b == 0x7f { 133 return true 134 } 135 } 136 return false 137 } 138 139 func hexEscapeNonASCII(s string) string { 140 newLen := 0 141 for i := 0; i < len(s); i++ { 142 if s[i] >= utf8.RuneSelf { 143 newLen += 3 144 } else { 145 newLen++ 146 } 147 } 148 if newLen == len(s) { 149 return s 150 } 151 b := make([]byte, 0, newLen) 152 var pos int 153 for i := 0; i < len(s); i++ { 154 if s[i] >= utf8.RuneSelf { 155 if pos < i { 156 b = append(b, s[pos:i]...) 157 } 158 b = append(b, '%') 159 b = strconv.AppendInt(b, int64(s[i]), 16) 160 pos = i + 1 161 } 162 } 163 if pos < len(s) { 164 b = append(b, s[pos:]...) 165 } 166 return string(b) 167 } 168 169 // NoBody is an [io.ReadCloser] with no bytes. Read always returns EOF 170 // and Close always returns nil. It can be used in an outgoing client 171 // request to explicitly signal that a request has zero bytes. 172 // An alternative, however, is to simply set [Request.Body] to nil. 173 var NoBody = noBody{} 174 175 type noBody struct{} 176 177 func (noBody) Read([]byte) (int, error) { return 0, io.EOF } 178 func (noBody) Close() error { return nil } 179 func (noBody) WriteTo(io.Writer) (int64, error) { return 0, nil } 180 181 var ( 182 // verify that an io.Copy from NoBody won't require a buffer: 183 _ io.WriterTo = NoBody 184 _ io.ReadCloser = NoBody 185 ) 186 187 // PushOptions describes options for [Pusher.Push]. 188 type PushOptions struct { 189 // Method specifies the HTTP method for the promised request. 190 // If set, it must be "GET" or "HEAD". Empty means "GET". 191 Method string 192 193 // Header specifies additional promised request headers. This cannot 194 // include HTTP/2 pseudo header fields like ":path" and ":scheme", 195 // which will be added automatically. 196 Header Header 197 } 198 199 // Pusher is the interface implemented by ResponseWriters that support 200 // HTTP/2 server push. For more background, see 201 // https://tools.ietf.org/html/rfc7540#section-8.2. 202 type Pusher interface { 203 // Push initiates an HTTP/2 server push. This constructs a synthetic 204 // request using the given target and options, serializes that request 205 // into a PUSH_PROMISE frame, then dispatches that request using the 206 // server's request handler. If opts is nil, default options are used. 207 // 208 // The target must either be an absolute path (like "/path") or an absolute 209 // URL that contains a valid host and the same scheme as the parent request. 210 // If the target is a path, it will inherit the scheme and host of the 211 // parent request. 212 // 213 // The HTTP/2 spec disallows recursive pushes and cross-authority pushes. 214 // Push may or may not detect these invalid pushes; however, invalid 215 // pushes will be detected and canceled by conforming clients. 216 // 217 // Handlers that wish to push URL X should call Push before sending any 218 // data that may trigger a request for URL X. This avoids a race where the 219 // client issues requests for X before receiving the PUSH_PROMISE for X. 220 // 221 // Push will run in a separate goroutine making the order of arrival 222 // non-deterministic. Any required synchronization needs to be implemented 223 // by the caller. 224 // 225 // Push returns ErrNotSupported if the client has disabled push or if push 226 // is not supported on the underlying connection. 227 Push(target string, opts *PushOptions) error 228 } 229 230 // HTTP2Config defines HTTP/2 configuration parameters common to 231 // both [Transport] and [Server]. 232 type HTTP2Config struct { 233 // MaxConcurrentStreams optionally specifies the number of 234 // concurrent streams that a client may have open at a time. 235 // If zero, MaxConcurrentStreams defaults to at least 100. 236 // 237 // This parameter only applies to Servers. 238 MaxConcurrentStreams int 239 240 // StrictMaxConcurrentRequests controls whether an HTTP/2 server's 241 // concurrency limit should be respected across all connections 242 // to that server. 243 // If true, new requests sent when a connection's concurrency limit 244 // has been exceeded will block until an existing request completes. 245 // If false, an additional connection will be opened if all 246 // existing connections are at their limit. 247 // 248 // This parameter only applies to Transports. 249 StrictMaxConcurrentRequests bool 250 251 // MaxDecoderHeaderTableSize optionally specifies an upper limit for the 252 // size of the header compression table used for decoding headers sent 253 // by the peer. 254 // A valid value is less than 4MiB. 255 // If zero or invalid, a default value is used. 256 MaxDecoderHeaderTableSize int 257 258 // MaxEncoderHeaderTableSize optionally specifies an upper limit for the 259 // header compression table used for sending headers to the peer. 260 // A valid value is less than 4MiB. 261 // If zero or invalid, a default value is used. 262 MaxEncoderHeaderTableSize int 263 264 // MaxReadFrameSize optionally specifies the largest frame 265 // this endpoint is willing to read. 266 // A valid value is between 16KiB and 16MiB, inclusive. 267 // If zero or invalid, a default value is used. 268 MaxReadFrameSize int 269 270 // MaxReceiveBufferPerConnection is the maximum size of the 271 // flow control window for data received on a connection. 272 // A valid value is at least 64KiB and less than 4MiB. 273 // If invalid, a default value is used. 274 MaxReceiveBufferPerConnection int 275 276 // MaxReceiveBufferPerStream is the maximum size of 277 // the flow control window for data received on a stream (request). 278 // A valid value is less than 4MiB. 279 // If zero or invalid, a default value is used. 280 MaxReceiveBufferPerStream int 281 282 // SendPingTimeout is the timeout after which a health check using a ping 283 // frame will be carried out if no frame is received on a connection. 284 // If zero, no health check is performed. 285 SendPingTimeout time.Duration 286 287 // PingTimeout is the timeout after which a connection will be closed 288 // if a response to a ping is not received. 289 // If zero, a default of 15 seconds is used. 290 PingTimeout time.Duration 291 292 // WriteByteTimeout is the timeout after which a connection will be 293 // closed if no data can be written to it. The timeout begins when data is 294 // available to write, and is extended whenever any bytes are written. 295 WriteByteTimeout time.Duration 296 297 // PermitProhibitedCipherSuites, if true, permits the use of 298 // cipher suites prohibited by the HTTP/2 spec. 299 PermitProhibitedCipherSuites bool 300 301 // CountError, if non-nil, is called on HTTP/2 errors. 302 // It is intended to increment a metric for monitoring. 303 // The errType contains only lowercase letters, digits, and underscores 304 // (a-z, 0-9, _). 305 CountError func(errType string) 306 } 307