1// Copyright 2014 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// Package http2 implements the HTTP/2 protocol. 6// 7// This package is low-level and intended to be used directly by very 8// few people. Most users will use it indirectly through the automatic 9// use by the net/http package (from Go 1.6 and later). 10// For use in earlier Go versions see ConfigureServer. (Transport support 11// requires Go 1.6 or later) 12// 13// See https://http2.github.io/ for more information on HTTP/2. 14// 15// See https://http2.golang.org/ for a test server running this code. 16// 17package http2 // import "golang.org/x/net/http2" 18 19import ( 20 "bufio" 21 "crypto/tls" 22 "errors" 23 "fmt" 24 "io" 25 "net/http" 26 "os" 27 "sort" 28 "strconv" 29 "strings" 30 "sync" 31 32 "golang.org/x/net/http/httpguts" 33) 34 35var ( 36 VerboseLogs bool 37 logFrameWrites bool 38 logFrameReads bool 39 inTests bool 40) 41 42func init() { 43 e := os.Getenv("GODEBUG") 44 if strings.Contains(e, "http2debug=1") { 45 VerboseLogs = true 46 } 47 if strings.Contains(e, "http2debug=2") { 48 VerboseLogs = true 49 logFrameWrites = true 50 logFrameReads = true 51 } 52} 53 54const ( 55 // ClientPreface is the string that must be sent by new 56 // connections from clients. 57 ClientPreface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" 58 59 // SETTINGS_MAX_FRAME_SIZE default 60 // http://http2.github.io/http2-spec/#rfc.section.6.5.2 61 initialMaxFrameSize = 16384 62 63 // NextProtoTLS is the NPN/ALPN protocol negotiated during 64 // HTTP/2's TLS setup. 65 NextProtoTLS = "h2" 66 67 // http://http2.github.io/http2-spec/#SettingValues 68 initialHeaderTableSize = 4096 69 70 initialWindowSize = 65535 // 6.9.2 Initial Flow Control Window Size 71 72 defaultMaxReadFrameSize = 1 << 20 73) 74 75var ( 76 clientPreface = []byte(ClientPreface) 77) 78 79type streamState int 80 81// HTTP/2 stream states. 82// 83// See http://tools.ietf.org/html/rfc7540#section-5.1. 84// 85// For simplicity, the server code merges "reserved (local)" into 86// "half-closed (remote)". This is one less state transition to track. 87// The only downside is that we send PUSH_PROMISEs slightly less 88// liberally than allowable. More discussion here: 89// https://lists.w3.org/Archives/Public/ietf-http-wg/2016JulSep/0599.html 90// 91// "reserved (remote)" is omitted since the client code does not 92// support server push. 93const ( 94 stateIdle streamState = iota 95 stateOpen 96 stateHalfClosedLocal 97 stateHalfClosedRemote 98 stateClosed 99) 100 101var stateName = [...]string{ 102 stateIdle: "Idle", 103 stateOpen: "Open", 104 stateHalfClosedLocal: "HalfClosedLocal", 105 stateHalfClosedRemote: "HalfClosedRemote", 106 stateClosed: "Closed", 107} 108 109func (st streamState) String() string { 110 return stateName[st] 111} 112 113// Setting is a setting parameter: which setting it is, and its value. 114type Setting struct { 115 // ID is which setting is being set. 116 // See http://http2.github.io/http2-spec/#SettingValues 117 ID SettingID 118 119 // Val is the value. 120 Val uint32 121} 122 123func (s Setting) String() string { 124 return fmt.Sprintf("[%v = %d]", s.ID, s.Val) 125} 126 127// Valid reports whether the setting is valid. 128func (s Setting) Valid() error { 129 // Limits and error codes from 6.5.2 Defined SETTINGS Parameters 130 switch s.ID { 131 case SettingEnablePush: 132 if s.Val != 1 && s.Val != 0 { 133 return ConnectionError(ErrCodeProtocol) 134 } 135 case SettingInitialWindowSize: 136 if s.Val > 1<<31-1 { 137 return ConnectionError(ErrCodeFlowControl) 138 } 139 case SettingMaxFrameSize: 140 if s.Val < 16384 || s.Val > 1<<24-1 { 141 return ConnectionError(ErrCodeProtocol) 142 } 143 } 144 return nil 145} 146 147// A SettingID is an HTTP/2 setting as defined in 148// http://http2.github.io/http2-spec/#iana-settings 149type SettingID uint16 150 151const ( 152 SettingHeaderTableSize SettingID = 0x1 153 SettingEnablePush SettingID = 0x2 154 SettingMaxConcurrentStreams SettingID = 0x3 155 SettingInitialWindowSize SettingID = 0x4 156 SettingMaxFrameSize SettingID = 0x5 157 SettingMaxHeaderListSize SettingID = 0x6 158) 159 160var settingName = map[SettingID]string{ 161 SettingHeaderTableSize: "HEADER_TABLE_SIZE", 162 SettingEnablePush: "ENABLE_PUSH", 163 SettingMaxConcurrentStreams: "MAX_CONCURRENT_STREAMS", 164 SettingInitialWindowSize: "INITIAL_WINDOW_SIZE", 165 SettingMaxFrameSize: "MAX_FRAME_SIZE", 166 SettingMaxHeaderListSize: "MAX_HEADER_LIST_SIZE", 167} 168 169func (s SettingID) String() string { 170 if v, ok := settingName[s]; ok { 171 return v 172 } 173 return fmt.Sprintf("UNKNOWN_SETTING_%d", uint16(s)) 174} 175 176var ( 177 errInvalidHeaderFieldName = errors.New("http2: invalid header field name") 178 errInvalidHeaderFieldValue = errors.New("http2: invalid header field value") 179) 180 181// validWireHeaderFieldName reports whether v is a valid header field 182// name (key). See httpguts.ValidHeaderName for the base rules. 183// 184// Further, http2 says: 185// "Just as in HTTP/1.x, header field names are strings of ASCII 186// characters that are compared in a case-insensitive 187// fashion. However, header field names MUST be converted to 188// lowercase prior to their encoding in HTTP/2. " 189func validWireHeaderFieldName(v string) bool { 190 if len(v) == 0 { 191 return false 192 } 193 for _, r := range v { 194 if !httpguts.IsTokenRune(r) { 195 return false 196 } 197 if 'A' <= r && r <= 'Z' { 198 return false 199 } 200 } 201 return true 202} 203 204func httpCodeString(code int) string { 205 switch code { 206 case 200: 207 return "200" 208 case 404: 209 return "404" 210 } 211 return strconv.Itoa(code) 212} 213 214// from pkg io 215type stringWriter interface { 216 WriteString(s string) (n int, err error) 217} 218 219// A gate lets two goroutines coordinate their activities. 220type gate chan struct{} 221 222func (g gate) Done() { g <- struct{}{} } 223func (g gate) Wait() { <-g } 224 225// A closeWaiter is like a sync.WaitGroup but only goes 1 to 0 (open to closed). 226type closeWaiter chan struct{} 227 228// Init makes a closeWaiter usable. 229// It exists because so a closeWaiter value can be placed inside a 230// larger struct and have the Mutex and Cond's memory in the same 231// allocation. 232func (cw *closeWaiter) Init() { 233 *cw = make(chan struct{}) 234} 235 236// Close marks the closeWaiter as closed and unblocks any waiters. 237func (cw closeWaiter) Close() { 238 close(cw) 239} 240 241// Wait waits for the closeWaiter to become closed. 242func (cw closeWaiter) Wait() { 243 <-cw 244} 245 246// bufferedWriter is a buffered writer that writes to w. 247// Its buffered writer is lazily allocated as needed, to minimize 248// idle memory usage with many connections. 249type bufferedWriter struct { 250 w io.Writer // immutable 251 bw *bufio.Writer // non-nil when data is buffered 252} 253 254func newBufferedWriter(w io.Writer) *bufferedWriter { 255 return &bufferedWriter{w: w} 256} 257 258// bufWriterPoolBufferSize is the size of bufio.Writer's 259// buffers created using bufWriterPool. 260// 261// TODO: pick a less arbitrary value? this is a bit under 262// (3 x typical 1500 byte MTU) at least. Other than that, 263// not much thought went into it. 264const bufWriterPoolBufferSize = 4 << 10 265 266var bufWriterPool = sync.Pool{ 267 New: func() interface{} { 268 return bufio.NewWriterSize(nil, bufWriterPoolBufferSize) 269 }, 270} 271 272func (w *bufferedWriter) Available() int { 273 if w.bw == nil { 274 return bufWriterPoolBufferSize 275 } 276 return w.bw.Available() 277} 278 279func (w *bufferedWriter) Write(p []byte) (n int, err error) { 280 if w.bw == nil { 281 bw := bufWriterPool.Get().(*bufio.Writer) 282 bw.Reset(w.w) 283 w.bw = bw 284 } 285 return w.bw.Write(p) 286} 287 288func (w *bufferedWriter) Flush() error { 289 bw := w.bw 290 if bw == nil { 291 return nil 292 } 293 err := bw.Flush() 294 bw.Reset(nil) 295 bufWriterPool.Put(bw) 296 w.bw = nil 297 return err 298} 299 300func mustUint31(v int32) uint32 { 301 if v < 0 || v > 2147483647 { 302 panic("out of range") 303 } 304 return uint32(v) 305} 306 307// bodyAllowedForStatus reports whether a given response status code 308// permits a body. See RFC 7230, section 3.3. 309func bodyAllowedForStatus(status int) bool { 310 switch { 311 case status >= 100 && status <= 199: 312 return false 313 case status == 204: 314 return false 315 case status == 304: 316 return false 317 } 318 return true 319} 320 321type httpError struct { 322 msg string 323 timeout bool 324} 325 326func (e *httpError) Error() string { return e.msg } 327func (e *httpError) Timeout() bool { return e.timeout } 328func (e *httpError) Temporary() bool { return true } 329 330var errTimeout error = &httpError{msg: "http2: timeout awaiting response headers", timeout: true} 331 332type connectionStater interface { 333 ConnectionState() tls.ConnectionState 334} 335 336var sorterPool = sync.Pool{New: func() interface{} { return new(sorter) }} 337 338type sorter struct { 339 v []string // owned by sorter 340} 341 342func (s *sorter) Len() int { return len(s.v) } 343func (s *sorter) Swap(i, j int) { s.v[i], s.v[j] = s.v[j], s.v[i] } 344func (s *sorter) Less(i, j int) bool { return s.v[i] < s.v[j] } 345 346// Keys returns the sorted keys of h. 347// 348// The returned slice is only valid until s used again or returned to 349// its pool. 350func (s *sorter) Keys(h http.Header) []string { 351 keys := s.v[:0] 352 for k := range h { 353 keys = append(keys, k) 354 } 355 s.v = keys 356 sort.Sort(s) 357 return keys 358} 359 360func (s *sorter) SortStrings(ss []string) { 361 // Our sorter works on s.v, which sorter owns, so 362 // stash it away while we sort the user's buffer. 363 save := s.v 364 s.v = ss 365 sort.Sort(s) 366 s.v = save 367} 368 369// validPseudoPath reports whether v is a valid :path pseudo-header 370// value. It must be either: 371// 372// *) a non-empty string starting with '/' 373// *) the string '*', for OPTIONS requests. 374// 375// For now this is only used a quick check for deciding when to clean 376// up Opaque URLs before sending requests from the Transport. 377// See golang.org/issue/16847 378// 379// We used to enforce that the path also didn't start with "//", but 380// Google's GFE accepts such paths and Chrome sends them, so ignore 381// that part of the spec. See golang.org/issue/19103. 382func validPseudoPath(v string) bool { 383 return (len(v) > 0 && v[0] == '/') || v == "*" 384} 385