http2.go

     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  package http2
    15  
    16  import (
    17  	"bufio"
    18  	"crypto/tls"
    19  	"errors"
    20  	"fmt"
    21  	"net"
    22  	"os"
    23  	"slices"
    24  	"strconv"
    25  	"strings"
    26  	"sync"
    27  	"time"
    28  
    29  	"golang.org/x/net/http/httpguts"
    30  )
    31  
    32  var (
    33  	VerboseLogs    bool
    34  	logFrameWrites bool
    35  	logFrameReads  bool
    36  
    37  	// Enabling extended CONNECT by causes browsers to attempt to use
    38  	// WebSockets-over-HTTP/2. This results in problems when the server's websocket
    39  	// package doesn't support extended CONNECT.
    40  	//
    41  	// Disable extended CONNECT by default for now.
    42  	//
    43  	// Issue #71128.
    44  	disableExtendedConnectProtocol = true
    45  
    46  	inTests = false
    47  )
    48  
    49  func init() {
    50  	e := os.Getenv("GODEBUG")
    51  	if strings.Contains(e, "http2debug=1") {
    52  		VerboseLogs = true
    53  	}
    54  	if strings.Contains(e, "http2debug=2") {
    55  		VerboseLogs = true
    56  		logFrameWrites = true
    57  		logFrameReads = true
    58  	}
    59  	if strings.Contains(e, "http2xconnect=1") {
    60  		disableExtendedConnectProtocol = false
    61  	}
    62  }
    63  
    64  const (
    65  	// ClientPreface is the string that must be sent by new
    66  	// connections from clients.
    67  	ClientPreface = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
    68  
    69  	// SETTINGS_MAX_FRAME_SIZE default
    70  	// https://httpwg.org/specs/rfc7540.html#rfc.section.6.5.2
    71  	initialMaxFrameSize = 16384
    72  
    73  	// NextProtoTLS is the NPN/ALPN protocol negotiated during
    74  	// HTTP/2's TLS setup.
    75  	NextProtoTLS = "h2"
    76  
    77  	// https://httpwg.org/specs/rfc7540.html#SettingValues
    78  	initialHeaderTableSize = 4096
    79  
    80  	initialWindowSize = 65535 // 6.9.2 Initial Flow Control Window Size
    81  
    82  	defaultMaxReadFrameSize = 1 << 20
    83  )
    84  
    85  var (
    86  	clientPreface = []byte(ClientPreface)
    87  )
    88  
    89  type streamState int
    90  
    91  // HTTP/2 stream states.
    92  //
    93  // See http://tools.ietf.org/html/rfc7540#section-5.1.
    94  //
    95  // For simplicity, the server code merges "reserved (local)" into
    96  // "half-closed (remote)". This is one less state transition to track.
    97  // The only downside is that we send PUSH_PROMISEs slightly less
    98  // liberally than allowable. More discussion here:
    99  // https://lists.w3.org/Archives/Public/ietf-http-wg/2016JulSep/0599.html
   100  //
   101  // "reserved (remote)" is omitted since the client code does not
   102  // support server push.
   103  const (
   104  	stateIdle streamState = iota
   105  	stateOpen
   106  	stateHalfClosedLocal
   107  	stateHalfClosedRemote
   108  	stateClosed
   109  )
   110  
   111  var stateName = [...]string{
   112  	stateIdle:             "Idle",
   113  	stateOpen:             "Open",
   114  	stateHalfClosedLocal:  "HalfClosedLocal",
   115  	stateHalfClosedRemote: "HalfClosedRemote",
   116  	stateClosed:           "Closed",
   117  }
   118  
   119  func (st streamState) String() string {
   120  	return stateName[st]
   121  }
   122  
   123  // Setting is a setting parameter: which setting it is, and its value.
   124  type Setting struct {
   125  	// ID is which setting is being set.
   126  	// See https://httpwg.org/specs/rfc7540.html#SettingFormat
   127  	ID SettingID
   128  
   129  	// Val is the value.
   130  	Val uint32
   131  }
   132  
   133  func (s Setting) String() string {
   134  	return fmt.Sprintf("[%v = %d]", s.ID, s.Val)
   135  }
   136  
   137  // Valid reports whether the setting is valid.
   138  func (s Setting) Valid() error {
   139  	// Limits and error codes from 6.5.2 Defined SETTINGS Parameters
   140  	switch s.ID {
   141  	case SettingEnablePush:
   142  		if s.Val != 1 && s.Val != 0 {
   143  			return ConnectionError(ErrCodeProtocol)
   144  		}
   145  	case SettingInitialWindowSize:
   146  		if s.Val > 1<<31-1 {
   147  			return ConnectionError(ErrCodeFlowControl)
   148  		}
   149  	case SettingMaxFrameSize:
   150  		if s.Val < 16384 || s.Val > 1<<24-1 {
   151  			return ConnectionError(ErrCodeProtocol)
   152  		}
   153  	case SettingEnableConnectProtocol:
   154  		if s.Val != 1 && s.Val != 0 {
   155  			return ConnectionError(ErrCodeProtocol)
   156  		}
   157  	}
   158  	return nil
   159  }
   160  
   161  // A SettingID is an HTTP/2 setting as defined in
   162  // https://httpwg.org/specs/rfc7540.html#iana-settings
   163  type SettingID uint16
   164  
   165  const (
   166  	SettingHeaderTableSize       SettingID = 0x1
   167  	SettingEnablePush            SettingID = 0x2
   168  	SettingMaxConcurrentStreams  SettingID = 0x3
   169  	SettingInitialWindowSize     SettingID = 0x4
   170  	SettingMaxFrameSize          SettingID = 0x5
   171  	SettingMaxHeaderListSize     SettingID = 0x6
   172  	SettingEnableConnectProtocol SettingID = 0x8
   173  	SettingNoRFC7540Priorities   SettingID = 0x9
   174  )
   175  
   176  var settingName = map[SettingID]string{
   177  	SettingHeaderTableSize:       "HEADER_TABLE_SIZE",
   178  	SettingEnablePush:            "ENABLE_PUSH",
   179  	SettingMaxConcurrentStreams:  "MAX_CONCURRENT_STREAMS",
   180  	SettingInitialWindowSize:     "INITIAL_WINDOW_SIZE",
   181  	SettingMaxFrameSize:          "MAX_FRAME_SIZE",
   182  	SettingMaxHeaderListSize:     "MAX_HEADER_LIST_SIZE",
   183  	SettingEnableConnectProtocol: "ENABLE_CONNECT_PROTOCOL",
   184  	SettingNoRFC7540Priorities:   "NO_RFC7540_PRIORITIES",
   185  }
   186  
   187  func (s SettingID) String() string {
   188  	if v, ok := settingName[s]; ok {
   189  		return v
   190  	}
   191  	return fmt.Sprintf("UNKNOWN_SETTING_%d", uint16(s))
   192  }
   193  
   194  // validWireHeaderFieldName reports whether v is a valid header field
   195  // name (key). See httpguts.ValidHeaderName for the base rules.
   196  //
   197  // Further, http2 says:
   198  //
   199  //	"Just as in HTTP/1.x, header field names are strings of ASCII
   200  //	characters that are compared in a case-insensitive
   201  //	fashion. However, header field names MUST be converted to
   202  //	lowercase prior to their encoding in HTTP/2. "
   203  func validWireHeaderFieldName(v string) bool {
   204  	if len(v) == 0 {
   205  		return false
   206  	}
   207  	for _, r := range v {
   208  		if !httpguts.IsTokenRune(r) {
   209  			return false
   210  		}
   211  		if 'A' <= r && r <= 'Z' {
   212  			return false
   213  		}
   214  	}
   215  	return true
   216  }
   217  
   218  // TODO: avoid alloc when code is neither 200 nor 404.
   219  func httpCodeString(code int) string {
   220  	switch code {
   221  	case 200:
   222  		return "200"
   223  	case 404:
   224  		return "404"
   225  	}
   226  	return strconv.Itoa(code)
   227  }
   228  
   229  // A closeWaiter is like a sync.WaitGroup but only goes 1 to 0 (open to closed).
   230  type closeWaiter chan struct{}
   231  
   232  // Init makes a closeWaiter usable.
   233  // It exists because so a closeWaiter value can be placed inside a
   234  // larger struct and have the Mutex and Cond's memory in the same
   235  // allocation.
   236  func (cw *closeWaiter) Init() {
   237  	*cw = make(chan struct{})
   238  }
   239  
   240  // Close marks the closeWaiter as closed and unblocks any waiters.
   241  func (cw closeWaiter) Close() {
   242  	close(cw)
   243  }
   244  
   245  // Wait waits for the closeWaiter to become closed.
   246  func (cw closeWaiter) Wait() {
   247  	<-cw
   248  }
   249  
   250  // bufferedWriter is a buffered writer that writes to w.
   251  // Its buffered writer is lazily allocated as needed, to minimize
   252  // idle memory usage with many connections.
   253  type bufferedWriter struct {
   254  	_           incomparable
   255  	conn        net.Conn      // immutable
   256  	bw          *bufio.Writer // non-nil when data is buffered
   257  	byteTimeout time.Duration // immutable, WriteByteTimeout
   258  	werr        error
   259  }
   260  
   261  func newBufferedWriter(conn net.Conn, timeout time.Duration) *bufferedWriter {
   262  	return &bufferedWriter{
   263  		conn:        conn,
   264  		byteTimeout: timeout,
   265  	}
   266  }
   267  
   268  // bufWriterPoolBufferSize is the size of bufio.Writer's
   269  // buffers created using bufWriterPool.
   270  //
   271  // TODO: pick a less arbitrary value? this is a bit under
   272  // (3 x typical 1500 byte MTU) at least. Other than that,
   273  // not much thought went into it.
   274  const bufWriterPoolBufferSize = 4 << 10
   275  
   276  var bufWriterPool = sync.Pool{
   277  	New: func() any {
   278  		return bufio.NewWriterSize(nil, bufWriterPoolBufferSize)
   279  	},
   280  }
   281  
   282  func (w *bufferedWriter) Available() int {
   283  	if w.bw == nil {
   284  		return bufWriterPoolBufferSize
   285  	}
   286  	return w.bw.Available()
   287  }
   288  
   289  func (w *bufferedWriter) Write(p []byte) (n int, err error) {
   290  	if w.werr != nil {
   291  		return 0, w.werr
   292  	}
   293  	if w.bw == nil {
   294  		bw := bufWriterPool.Get().(*bufio.Writer)
   295  		bw.Reset((*bufferedWriterTimeoutWriter)(w))
   296  		w.bw = bw
   297  	}
   298  	n, w.werr = w.bw.Write(p)
   299  	return n, w.werr
   300  }
   301  
   302  func (w *bufferedWriter) Flush() error {
   303  	bw := w.bw
   304  	if bw == nil {
   305  		return nil
   306  	}
   307  	if w.werr != nil {
   308  		return w.werr
   309  	}
   310  	w.werr = bw.Flush()
   311  	bw.Reset(nil)
   312  	bufWriterPool.Put(bw)
   313  	w.bw = nil
   314  	return w.werr
   315  }
   316  
   317  type bufferedWriterTimeoutWriter bufferedWriter
   318  
   319  func (w *bufferedWriterTimeoutWriter) Write(p []byte) (n int, err error) {
   320  	return writeWithByteTimeout(w.conn, w.byteTimeout, p)
   321  }
   322  
   323  // writeWithByteTimeout writes to conn.
   324  // If more than timeout passes without any bytes being written to the connection,
   325  // the write fails.
   326  func writeWithByteTimeout(conn net.Conn, timeout time.Duration, p []byte) (n int, err error) {
   327  	if timeout <= 0 {
   328  		return conn.Write(p)
   329  	}
   330  	for {
   331  		conn.SetWriteDeadline(time.Now().Add(timeout))
   332  		nn, err := conn.Write(p[n:])
   333  		n += nn
   334  		if n == len(p) || nn == 0 || !errors.Is(err, os.ErrDeadlineExceeded) {
   335  			// Either we finished the write, made no progress, or hit the deadline.
   336  			// Whichever it is, we're done now.
   337  			conn.SetWriteDeadline(time.Time{})
   338  			return n, err
   339  		}
   340  	}
   341  }
   342  
   343  func mustUint31(v int32) uint32 {
   344  	if v < 0 || v > 2147483647 {
   345  		panic("out of range")
   346  	}
   347  	return uint32(v)
   348  }
   349  
   350  // bodyAllowedForStatus reports whether a given response status code
   351  // permits a body. See RFC 7230, section 3.3.
   352  func bodyAllowedForStatus(status int) bool {
   353  	switch {
   354  	case status >= 100 && status <= 199:
   355  		return false
   356  	case status == 204:
   357  		return false
   358  	case status == 304:
   359  		return false
   360  	}
   361  	return true
   362  }
   363  
   364  type httpError struct {
   365  	_       incomparable
   366  	msg     string
   367  	timeout bool
   368  }
   369  
   370  func (e *httpError) Error() string   { return e.msg }
   371  func (e *httpError) Timeout() bool   { return e.timeout }
   372  func (e *httpError) Temporary() bool { return true }
   373  
   374  var errTimeout error = &httpError{msg: "http2: timeout awaiting response headers", timeout: true}
   375  
   376  type connectionStater interface {
   377  	ConnectionState() tls.ConnectionState
   378  }
   379  
   380  var sorterPool = sync.Pool{New: func() any { return new(sorter) }}
   381  
   382  type sorter struct {
   383  	v []string // owned by sorter
   384  }
   385  
   386  // Keys returns the sorted keys of h.
   387  //
   388  // The returned slice is only valid until s used again or returned to
   389  // its pool.
   390  func (s *sorter) Keys(h Header) []string {
   391  	keys := s.v[:0]
   392  	for k := range h {
   393  		keys = append(keys, k)
   394  	}
   395  	s.v = keys
   396  	slices.Sort(s.v)
   397  	return keys
   398  }
   399  
   400  // incomparable is a zero-width, non-comparable type. Adding it to a struct
   401  // makes that struct also non-comparable, and generally doesn't add
   402  // any size (as long as it's first).
   403  type incomparable [0]func()
   404
View as plain text