Source file src/net/http/request.go

     1  // Copyright 2009 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  // HTTP Request reading and parsing.
     6  
     7  package http
     8  
     9  import (
    10  	"bufio"
    11  	"bytes"
    12  	"context"
    13  	"crypto/tls"
    14  	"encoding/base64"
    15  	"errors"
    16  	"fmt"
    17  	"io"
    18  	"mime"
    19  	"mime/multipart"
    20  	"net/http/httptrace"
    21  	"net/http/internal/ascii"
    22  	"net/textproto"
    23  	"net/url"
    24  	urlpkg "net/url"
    25  	"strconv"
    26  	"strings"
    27  	"sync"
    28  
    29  	"golang.org/x/net/http/httpguts"
    30  	"golang.org/x/net/idna"
    31  )
    32  
    33  const (
    34  	defaultMaxMemory = 32 << 20 // 32 MB
    35  )
    36  
    37  // ErrMissingFile is returned by FormFile when the provided file field name
    38  // is either not present in the request or not a file field.
    39  var ErrMissingFile = errors.New("http: no such file")
    40  
    41  // ProtocolError represents an HTTP protocol error.
    42  //
    43  // Deprecated: Not all errors in the http package related to protocol errors
    44  // are of type ProtocolError.
    45  type ProtocolError struct {
    46  	ErrorString string
    47  }
    48  
    49  func (pe *ProtocolError) Error() string { return pe.ErrorString }
    50  
    51  // Is lets http.ErrNotSupported match errors.ErrUnsupported.
    52  func (pe *ProtocolError) Is(err error) bool {
    53  	return pe == ErrNotSupported && err == errors.ErrUnsupported
    54  }
    55  
    56  var (
    57  	// ErrNotSupported indicates that a feature is not supported.
    58  	//
    59  	// It is returned by ResponseController methods to indicate that
    60  	// the handler does not support the method, and by the Push method
    61  	// of Pusher implementations to indicate that HTTP/2 Push support
    62  	// is not available.
    63  	ErrNotSupported = &ProtocolError{"feature not supported"}
    64  
    65  	// Deprecated: ErrUnexpectedTrailer is no longer returned by
    66  	// anything in the net/http package. Callers should not
    67  	// compare errors against this variable.
    68  	ErrUnexpectedTrailer = &ProtocolError{"trailer header without chunked transfer encoding"}
    69  
    70  	// ErrMissingBoundary is returned by Request.MultipartReader when the
    71  	// request's Content-Type does not include a "boundary" parameter.
    72  	ErrMissingBoundary = &ProtocolError{"no multipart boundary param in Content-Type"}
    73  
    74  	// ErrNotMultipart is returned by Request.MultipartReader when the
    75  	// request's Content-Type is not multipart/form-data.
    76  	ErrNotMultipart = &ProtocolError{"request Content-Type isn't multipart/form-data"}
    77  
    78  	// Deprecated: ErrHeaderTooLong is no longer returned by
    79  	// anything in the net/http package. Callers should not
    80  	// compare errors against this variable.
    81  	ErrHeaderTooLong = &ProtocolError{"header too long"}
    82  
    83  	// Deprecated: ErrShortBody is no longer returned by
    84  	// anything in the net/http package. Callers should not
    85  	// compare errors against this variable.
    86  	ErrShortBody = &ProtocolError{"entity body too short"}
    87  
    88  	// Deprecated: ErrMissingContentLength is no longer returned by
    89  	// anything in the net/http package. Callers should not
    90  	// compare errors against this variable.
    91  	ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
    92  )
    93  
    94  func badStringError(what, val string) error { return fmt.Errorf("%s %q", what, val) }
    95  
    96  // Headers that Request.Write handles itself and should be skipped.
    97  var reqWriteExcludeHeader = map[string]bool{
    98  	"Host":              true, // not in Header map anyway
    99  	"User-Agent":        true,
   100  	"Content-Length":    true,
   101  	"Transfer-Encoding": true,
   102  	"Trailer":           true,
   103  }
   104  
   105  // A Request represents an HTTP request received by a server
   106  // or to be sent by a client.
   107  //
   108  // The field semantics differ slightly between client and server
   109  // usage. In addition to the notes on the fields below, see the
   110  // documentation for [Request.Write] and [RoundTripper].
   111  type Request struct {
   112  	// Method specifies the HTTP method (GET, POST, PUT, etc.).
   113  	// For client requests, an empty string means GET.
   114  	Method string
   115  
   116  	// URL specifies either the URI being requested (for server
   117  	// requests) or the URL to access (for client requests).
   118  	//
   119  	// For server requests, the URL is parsed from the URI
   120  	// supplied on the Request-Line as stored in RequestURI.  For
   121  	// most requests, fields other than Path and RawQuery will be
   122  	// empty. (See RFC 7230, Section 5.3)
   123  	//
   124  	// For client requests, the URL's Host specifies the server to
   125  	// connect to, while the Request's Host field optionally
   126  	// specifies the Host header value to send in the HTTP
   127  	// request.
   128  	URL *url.URL
   129  
   130  	// The protocol version for incoming server requests.
   131  	//
   132  	// For client requests, these fields are ignored. The HTTP
   133  	// client code always uses either HTTP/1.1 or HTTP/2.
   134  	// See the docs on Transport for details.
   135  	Proto      string // "HTTP/1.0"
   136  	ProtoMajor int    // 1
   137  	ProtoMinor int    // 0
   138  
   139  	// Header contains the request header fields either received
   140  	// by the server or to be sent by the client.
   141  	//
   142  	// If a server received a request with header lines,
   143  	//
   144  	//	Host: example.com
   145  	//	accept-encoding: gzip, deflate
   146  	//	Accept-Language: en-us
   147  	//	fOO: Bar
   148  	//	foo: two
   149  	//
   150  	// then
   151  	//
   152  	//	Header = map[string][]string{
   153  	//		"Accept-Encoding": {"gzip, deflate"},
   154  	//		"Accept-Language": {"en-us"},
   155  	//		"Foo": {"Bar", "two"},
   156  	//	}
   157  	//
   158  	// For incoming requests, the Host header is promoted to the
   159  	// Request.Host field and removed from the Header map.
   160  	//
   161  	// HTTP defines that header names are case-insensitive. The
   162  	// request parser implements this by using CanonicalHeaderKey,
   163  	// making the first character and any characters following a
   164  	// hyphen uppercase and the rest lowercase.
   165  	//
   166  	// For client requests, certain headers such as Content-Length
   167  	// and Connection are automatically written when needed and
   168  	// values in Header may be ignored. See the documentation
   169  	// for the Request.Write method.
   170  	Header Header
   171  
   172  	// Body is the request's body.
   173  	//
   174  	// For client requests, a nil body means the request has no
   175  	// body, such as a GET request. The HTTP Client's Transport
   176  	// is responsible for calling the Close method.
   177  	//
   178  	// For server requests, the Request Body is always non-nil
   179  	// but will return EOF immediately when no body is present.
   180  	// The Server will close the request body. The ServeHTTP
   181  	// Handler does not need to.
   182  	//
   183  	// Body must allow Read to be called concurrently with Close.
   184  	// In particular, calling Close should unblock a Read waiting
   185  	// for input.
   186  	Body io.ReadCloser
   187  
   188  	// GetBody defines an optional func to return a new copy of
   189  	// Body. It is used for client requests when a redirect requires
   190  	// reading the body more than once. Use of GetBody still
   191  	// requires setting Body.
   192  	//
   193  	// For server requests, it is unused.
   194  	GetBody func() (io.ReadCloser, error)
   195  
   196  	// ContentLength records the length of the associated content.
   197  	// The value -1 indicates that the length is unknown.
   198  	// Values >= 0 indicate that the given number of bytes may
   199  	// be read from Body.
   200  	//
   201  	// For client requests, a value of 0 with a non-nil Body is
   202  	// also treated as unknown.
   203  	ContentLength int64
   204  
   205  	// TransferEncoding lists the transfer encodings from outermost to
   206  	// innermost. An empty list denotes the "identity" encoding.
   207  	// TransferEncoding can usually be ignored; chunked encoding is
   208  	// automatically added and removed as necessary when sending and
   209  	// receiving requests.
   210  	TransferEncoding []string
   211  
   212  	// Close indicates whether to close the connection after
   213  	// replying to this request (for servers) or after sending this
   214  	// request and reading its response (for clients).
   215  	//
   216  	// For server requests, the HTTP server handles this automatically
   217  	// and this field is not needed by Handlers.
   218  	//
   219  	// For client requests, setting this field prevents re-use of
   220  	// TCP connections between requests to the same hosts, as if
   221  	// Transport.DisableKeepAlives were set.
   222  	Close bool
   223  
   224  	// For server requests, Host specifies the host on which the
   225  	// URL is sought. For HTTP/1 (per RFC 7230, section 5.4), this
   226  	// is either the value of the "Host" header or the host name
   227  	// given in the URL itself. For HTTP/2, it is the value of the
   228  	// ":authority" pseudo-header field.
   229  	// It may be of the form "host:port". For international domain
   230  	// names, Host may be in Punycode or Unicode form. Use
   231  	// golang.org/x/net/idna to convert it to either format if
   232  	// needed.
   233  	// To prevent DNS rebinding attacks, server Handlers should
   234  	// validate that the Host header has a value for which the
   235  	// Handler considers itself authoritative. The included
   236  	// ServeMux supports patterns registered to particular host
   237  	// names and thus protects its registered Handlers.
   238  	//
   239  	// For client requests, Host optionally overrides the Host
   240  	// header to send. If empty, the Request.Write method uses
   241  	// the value of URL.Host. Host may contain an international
   242  	// domain name.
   243  	Host string
   244  
   245  	// Form contains the parsed form data, including both the URL
   246  	// field's query parameters and the PATCH, POST, or PUT form data.
   247  	// This field is only available after ParseForm is called.
   248  	// The HTTP client ignores Form and uses Body instead.
   249  	Form url.Values
   250  
   251  	// PostForm contains the parsed form data from PATCH, POST
   252  	// or PUT body parameters.
   253  	//
   254  	// This field is only available after ParseForm is called.
   255  	// The HTTP client ignores PostForm and uses Body instead.
   256  	PostForm url.Values
   257  
   258  	// MultipartForm is the parsed multipart form, including file uploads.
   259  	// This field is only available after ParseMultipartForm is called.
   260  	// The HTTP client ignores MultipartForm and uses Body instead.
   261  	MultipartForm *multipart.Form
   262  
   263  	// Trailer specifies additional headers that are sent after the request
   264  	// body.
   265  	//
   266  	// For server requests, the Trailer map initially contains only the
   267  	// trailer keys, with nil values. (The client declares which trailers it
   268  	// will later send.)  While the handler is reading from Body, it must
   269  	// not reference Trailer. After reading from Body returns EOF, Trailer
   270  	// can be read again and will contain non-nil values, if they were sent
   271  	// by the client.
   272  	//
   273  	// For client requests, Trailer must be initialized to a map containing
   274  	// the trailer keys to later send. The values may be nil or their final
   275  	// values. The ContentLength must be 0 or -1, to send a chunked request.
   276  	// After the HTTP request is sent the map values can be updated while
   277  	// the request body is read. Once the body returns EOF, the caller must
   278  	// not mutate Trailer.
   279  	//
   280  	// Few HTTP clients, servers, or proxies support HTTP trailers.
   281  	Trailer Header
   282  
   283  	// RemoteAddr allows HTTP servers and other software to record
   284  	// the network address that sent the request, usually for
   285  	// logging. This field is not filled in by ReadRequest and
   286  	// has no defined format. The HTTP server in this package
   287  	// sets RemoteAddr to an "IP:port" address before invoking a
   288  	// handler.
   289  	// This field is ignored by the HTTP client.
   290  	RemoteAddr string
   291  
   292  	// RequestURI is the unmodified request-target of the
   293  	// Request-Line (RFC 7230, Section 3.1.1) as sent by the client
   294  	// to a server. Usually the URL field should be used instead.
   295  	// It is an error to set this field in an HTTP client request.
   296  	RequestURI string
   297  
   298  	// TLS allows HTTP servers and other software to record
   299  	// information about the TLS connection on which the request
   300  	// was received. This field is not filled in by ReadRequest.
   301  	// The HTTP server in this package sets the field for
   302  	// TLS-enabled connections before invoking a handler;
   303  	// otherwise it leaves the field nil.
   304  	// This field is ignored by the HTTP client.
   305  	TLS *tls.ConnectionState
   306  
   307  	// Cancel is an optional channel whose closure indicates that the client
   308  	// request should be regarded as canceled. Not all implementations of
   309  	// RoundTripper may support Cancel.
   310  	//
   311  	// For server requests, this field is not applicable.
   312  	//
   313  	// Deprecated: Set the Request's context with NewRequestWithContext
   314  	// instead. If a Request's Cancel field and context are both
   315  	// set, it is undefined whether Cancel is respected.
   316  	Cancel <-chan struct{}
   317  
   318  	// Response is the redirect response which caused this request
   319  	// to be created. This field is only populated during client
   320  	// redirects.
   321  	Response *Response
   322  
   323  	// ctx is either the client or server context. It should only
   324  	// be modified via copying the whole Request using Clone or WithContext.
   325  	// It is unexported to prevent people from using Context wrong
   326  	// and mutating the contexts held by callers of the same request.
   327  	ctx context.Context
   328  
   329  	// The following fields are for requests matched by ServeMux.
   330  	pat         *pattern          // the pattern that matched
   331  	matches     []string          // values for the matching wildcards in pat
   332  	otherValues map[string]string // for calls to SetPathValue that don't match a wildcard
   333  }
   334  
   335  // Context returns the request's context. To change the context, use
   336  // [Request.Clone] or [Request.WithContext].
   337  //
   338  // The returned context is always non-nil; it defaults to the
   339  // background context.
   340  //
   341  // For outgoing client requests, the context controls cancellation.
   342  //
   343  // For incoming server requests, the context is canceled when the
   344  // client's connection closes, the request is canceled (with HTTP/2),
   345  // or when the ServeHTTP method returns.
   346  func (r *Request) Context() context.Context {
   347  	if r.ctx != nil {
   348  		return r.ctx
   349  	}
   350  	return context.Background()
   351  }
   352  
   353  // WithContext returns a shallow copy of r with its context changed
   354  // to ctx. The provided ctx must be non-nil.
   355  //
   356  // For outgoing client request, the context controls the entire
   357  // lifetime of a request and its response: obtaining a connection,
   358  // sending the request, and reading the response headers and body.
   359  //
   360  // To create a new request with a context, use [NewRequestWithContext].
   361  // To make a deep copy of a request with a new context, use [Request.Clone].
   362  func (r *Request) WithContext(ctx context.Context) *Request {
   363  	if ctx == nil {
   364  		panic("nil context")
   365  	}
   366  	r2 := new(Request)
   367  	*r2 = *r
   368  	r2.ctx = ctx
   369  	return r2
   370  }
   371  
   372  // Clone returns a deep copy of r with its context changed to ctx.
   373  // The provided ctx must be non-nil.
   374  //
   375  // For an outgoing client request, the context controls the entire
   376  // lifetime of a request and its response: obtaining a connection,
   377  // sending the request, and reading the response headers and body.
   378  func (r *Request) Clone(ctx context.Context) *Request {
   379  	if ctx == nil {
   380  		panic("nil context")
   381  	}
   382  	r2 := new(Request)
   383  	*r2 = *r
   384  	r2.ctx = ctx
   385  	r2.URL = cloneURL(r.URL)
   386  	if r.Header != nil {
   387  		r2.Header = r.Header.Clone()
   388  	}
   389  	if r.Trailer != nil {
   390  		r2.Trailer = r.Trailer.Clone()
   391  	}
   392  	if s := r.TransferEncoding; s != nil {
   393  		s2 := make([]string, len(s))
   394  		copy(s2, s)
   395  		r2.TransferEncoding = s2
   396  	}
   397  	r2.Form = cloneURLValues(r.Form)
   398  	r2.PostForm = cloneURLValues(r.PostForm)
   399  	r2.MultipartForm = cloneMultipartForm(r.MultipartForm)
   400  
   401  	// Copy matches and otherValues. See issue 61410.
   402  	if s := r.matches; s != nil {
   403  		s2 := make([]string, len(s))
   404  		copy(s2, s)
   405  		r2.matches = s2
   406  	}
   407  	if s := r.otherValues; s != nil {
   408  		s2 := make(map[string]string, len(s))
   409  		for k, v := range s {
   410  			s2[k] = v
   411  		}
   412  		r2.otherValues = s2
   413  	}
   414  	return r2
   415  }
   416  
   417  // ProtoAtLeast reports whether the HTTP protocol used
   418  // in the request is at least major.minor.
   419  func (r *Request) ProtoAtLeast(major, minor int) bool {
   420  	return r.ProtoMajor > major ||
   421  		r.ProtoMajor == major && r.ProtoMinor >= minor
   422  }
   423  
   424  // UserAgent returns the client's User-Agent, if sent in the request.
   425  func (r *Request) UserAgent() string {
   426  	return r.Header.Get("User-Agent")
   427  }
   428  
   429  // Cookies parses and returns the HTTP cookies sent with the request.
   430  func (r *Request) Cookies() []*Cookie {
   431  	return readCookies(r.Header, "")
   432  }
   433  
   434  // ErrNoCookie is returned by Request's Cookie method when a cookie is not found.
   435  var ErrNoCookie = errors.New("http: named cookie not present")
   436  
   437  // Cookie returns the named cookie provided in the request or
   438  // [ErrNoCookie] if not found.
   439  // If multiple cookies match the given name, only one cookie will
   440  // be returned.
   441  func (r *Request) Cookie(name string) (*Cookie, error) {
   442  	if name == "" {
   443  		return nil, ErrNoCookie
   444  	}
   445  	for _, c := range readCookies(r.Header, name) {
   446  		return c, nil
   447  	}
   448  	return nil, ErrNoCookie
   449  }
   450  
   451  // AddCookie adds a cookie to the request. Per RFC 6265 section 5.4,
   452  // AddCookie does not attach more than one [Cookie] header field. That
   453  // means all cookies, if any, are written into the same line,
   454  // separated by semicolon.
   455  // AddCookie only sanitizes c's name and value, and does not sanitize
   456  // a Cookie header already present in the request.
   457  func (r *Request) AddCookie(c *Cookie) {
   458  	s := fmt.Sprintf("%s=%s", sanitizeCookieName(c.Name), sanitizeCookieValue(c.Value))
   459  	if c := r.Header.Get("Cookie"); c != "" {
   460  		r.Header.Set("Cookie", c+"; "+s)
   461  	} else {
   462  		r.Header.Set("Cookie", s)
   463  	}
   464  }
   465  
   466  // Referer returns the referring URL, if sent in the request.
   467  //
   468  // Referer is misspelled as in the request itself, a mistake from the
   469  // earliest days of HTTP.  This value can also be fetched from the
   470  // [Header] map as Header["Referer"]; the benefit of making it available
   471  // as a method is that the compiler can diagnose programs that use the
   472  // alternate (correct English) spelling req.Referrer() but cannot
   473  // diagnose programs that use Header["Referrer"].
   474  func (r *Request) Referer() string {
   475  	return r.Header.Get("Referer")
   476  }
   477  
   478  // multipartByReader is a sentinel value.
   479  // Its presence in Request.MultipartForm indicates that parsing of the request
   480  // body has been handed off to a MultipartReader instead of ParseMultipartForm.
   481  var multipartByReader = &multipart.Form{
   482  	Value: make(map[string][]string),
   483  	File:  make(map[string][]*multipart.FileHeader),
   484  }
   485  
   486  // MultipartReader returns a MIME multipart reader if this is a
   487  // multipart/form-data or a multipart/mixed POST request, else returns nil and an error.
   488  // Use this function instead of [Request.ParseMultipartForm] to
   489  // process the request body as a stream.
   490  func (r *Request) MultipartReader() (*multipart.Reader, error) {
   491  	if r.MultipartForm == multipartByReader {
   492  		return nil, errors.New("http: MultipartReader called twice")
   493  	}
   494  	if r.MultipartForm != nil {
   495  		return nil, errors.New("http: multipart handled by ParseMultipartForm")
   496  	}
   497  	r.MultipartForm = multipartByReader
   498  	return r.multipartReader(true)
   499  }
   500  
   501  func (r *Request) multipartReader(allowMixed bool) (*multipart.Reader, error) {
   502  	v := r.Header.Get("Content-Type")
   503  	if v == "" {
   504  		return nil, ErrNotMultipart
   505  	}
   506  	if r.Body == nil {
   507  		return nil, errors.New("missing form body")
   508  	}
   509  	d, params, err := mime.ParseMediaType(v)
   510  	if err != nil || !(d == "multipart/form-data" || allowMixed && d == "multipart/mixed") {
   511  		return nil, ErrNotMultipart
   512  	}
   513  	boundary, ok := params["boundary"]
   514  	if !ok {
   515  		return nil, ErrMissingBoundary
   516  	}
   517  	return multipart.NewReader(r.Body, boundary), nil
   518  }
   519  
   520  // isH2Upgrade reports whether r represents the http2 "client preface"
   521  // magic string.
   522  func (r *Request) isH2Upgrade() bool {
   523  	return r.Method == "PRI" && len(r.Header) == 0 && r.URL.Path == "*" && r.Proto == "HTTP/2.0"
   524  }
   525  
   526  // Return value if nonempty, def otherwise.
   527  func valueOrDefault(value, def string) string {
   528  	if value != "" {
   529  		return value
   530  	}
   531  	return def
   532  }
   533  
   534  // NOTE: This is not intended to reflect the actual Go version being used.
   535  // It was changed at the time of Go 1.1 release because the former User-Agent
   536  // had ended up blocked by some intrusion detection systems.
   537  // See https://codereview.appspot.com/7532043.
   538  const defaultUserAgent = "Go-http-client/1.1"
   539  
   540  // Write writes an HTTP/1.1 request, which is the header and body, in wire format.
   541  // This method consults the following fields of the request:
   542  //
   543  //	Host
   544  //	URL
   545  //	Method (defaults to "GET")
   546  //	Header
   547  //	ContentLength
   548  //	TransferEncoding
   549  //	Body
   550  //
   551  // If Body is present, Content-Length is <= 0 and [Request.TransferEncoding]
   552  // hasn't been set to "identity", Write adds "Transfer-Encoding:
   553  // chunked" to the header. Body is closed after it is sent.
   554  func (r *Request) Write(w io.Writer) error {
   555  	return r.write(w, false, nil, nil)
   556  }
   557  
   558  // WriteProxy is like [Request.Write] but writes the request in the form
   559  // expected by an HTTP proxy. In particular, [Request.WriteProxy] writes the
   560  // initial Request-URI line of the request with an absolute URI, per
   561  // section 5.3 of RFC 7230, including the scheme and host.
   562  // In either case, WriteProxy also writes a Host header, using
   563  // either r.Host or r.URL.Host.
   564  func (r *Request) WriteProxy(w io.Writer) error {
   565  	return r.write(w, true, nil, nil)
   566  }
   567  
   568  // errMissingHost is returned by Write when there is no Host or URL present in
   569  // the Request.
   570  var errMissingHost = errors.New("http: Request.Write on Request with no Host or URL set")
   571  
   572  // extraHeaders may be nil
   573  // waitForContinue may be nil
   574  // always closes body
   575  func (r *Request) write(w io.Writer, usingProxy bool, extraHeaders Header, waitForContinue func() bool) (err error) {
   576  	trace := httptrace.ContextClientTrace(r.Context())
   577  	if trace != nil && trace.WroteRequest != nil {
   578  		defer func() {
   579  			trace.WroteRequest(httptrace.WroteRequestInfo{
   580  				Err: err,
   581  			})
   582  		}()
   583  	}
   584  	closed := false
   585  	defer func() {
   586  		if closed {
   587  			return
   588  		}
   589  		if closeErr := r.closeBody(); closeErr != nil && err == nil {
   590  			err = closeErr
   591  		}
   592  	}()
   593  
   594  	// Find the target host. Prefer the Host: header, but if that
   595  	// is not given, use the host from the request URL.
   596  	//
   597  	// Clean the host, in case it arrives with unexpected stuff in it.
   598  	host := r.Host
   599  	if host == "" {
   600  		if r.URL == nil {
   601  			return errMissingHost
   602  		}
   603  		host = r.URL.Host
   604  	}
   605  	host, err = httpguts.PunycodeHostPort(host)
   606  	if err != nil {
   607  		return err
   608  	}
   609  	// Validate that the Host header is a valid header in general,
   610  	// but don't validate the host itself. This is sufficient to avoid
   611  	// header or request smuggling via the Host field.
   612  	// The server can (and will, if it's a net/http server) reject
   613  	// the request if it doesn't consider the host valid.
   614  	if !httpguts.ValidHostHeader(host) {
   615  		// Historically, we would truncate the Host header after '/' or ' '.
   616  		// Some users have relied on this truncation to convert a network
   617  		// address such as Unix domain socket path into a valid, ignored
   618  		// Host header (see https://go.dev/issue/61431).
   619  		//
   620  		// We don't preserve the truncation, because sending an altered
   621  		// header field opens a smuggling vector. Instead, zero out the
   622  		// Host header entirely if it isn't valid. (An empty Host is valid;
   623  		// see RFC 9112 Section 3.2.)
   624  		//
   625  		// Return an error if we're sending to a proxy, since the proxy
   626  		// probably can't do anything useful with an empty Host header.
   627  		if !usingProxy {
   628  			host = ""
   629  		} else {
   630  			return errors.New("http: invalid Host header")
   631  		}
   632  	}
   633  
   634  	// According to RFC 6874, an HTTP client, proxy, or other
   635  	// intermediary must remove any IPv6 zone identifier attached
   636  	// to an outgoing URI.
   637  	host = removeZone(host)
   638  
   639  	ruri := r.URL.RequestURI()
   640  	if usingProxy && r.URL.Scheme != "" && r.URL.Opaque == "" {
   641  		ruri = r.URL.Scheme + "://" + host + ruri
   642  	} else if r.Method == "CONNECT" && r.URL.Path == "" {
   643  		// CONNECT requests normally give just the host and port, not a full URL.
   644  		ruri = host
   645  		if r.URL.Opaque != "" {
   646  			ruri = r.URL.Opaque
   647  		}
   648  	}
   649  	if stringContainsCTLByte(ruri) {
   650  		return errors.New("net/http: can't write control character in Request.URL")
   651  	}
   652  	// TODO: validate r.Method too? At least it's less likely to
   653  	// come from an attacker (more likely to be a constant in
   654  	// code).
   655  
   656  	// Wrap the writer in a bufio Writer if it's not already buffered.
   657  	// Don't always call NewWriter, as that forces a bytes.Buffer
   658  	// and other small bufio Writers to have a minimum 4k buffer
   659  	// size.
   660  	var bw *bufio.Writer
   661  	if _, ok := w.(io.ByteWriter); !ok {
   662  		bw = bufio.NewWriter(w)
   663  		w = bw
   664  	}
   665  
   666  	_, err = fmt.Fprintf(w, "%s %s HTTP/1.1\r\n", valueOrDefault(r.Method, "GET"), ruri)
   667  	if err != nil {
   668  		return err
   669  	}
   670  
   671  	// Header lines
   672  	_, err = fmt.Fprintf(w, "Host: %s\r\n", host)
   673  	if err != nil {
   674  		return err
   675  	}
   676  	if trace != nil && trace.WroteHeaderField != nil {
   677  		trace.WroteHeaderField("Host", []string{host})
   678  	}
   679  
   680  	// Use the defaultUserAgent unless the Header contains one, which
   681  	// may be blank to not send the header.
   682  	userAgent := defaultUserAgent
   683  	if r.Header.has("User-Agent") {
   684  		userAgent = r.Header.Get("User-Agent")
   685  	}
   686  	if userAgent != "" {
   687  		userAgent = headerNewlineToSpace.Replace(userAgent)
   688  		userAgent = textproto.TrimString(userAgent)
   689  		_, err = fmt.Fprintf(w, "User-Agent: %s\r\n", userAgent)
   690  		if err != nil {
   691  			return err
   692  		}
   693  		if trace != nil && trace.WroteHeaderField != nil {
   694  			trace.WroteHeaderField("User-Agent", []string{userAgent})
   695  		}
   696  	}
   697  
   698  	// Process Body,ContentLength,Close,Trailer
   699  	tw, err := newTransferWriter(r)
   700  	if err != nil {
   701  		return err
   702  	}
   703  	err = tw.writeHeader(w, trace)
   704  	if err != nil {
   705  		return err
   706  	}
   707  
   708  	err = r.Header.writeSubset(w, reqWriteExcludeHeader, trace)
   709  	if err != nil {
   710  		return err
   711  	}
   712  
   713  	if extraHeaders != nil {
   714  		err = extraHeaders.write(w, trace)
   715  		if err != nil {
   716  			return err
   717  		}
   718  	}
   719  
   720  	_, err = io.WriteString(w, "\r\n")
   721  	if err != nil {
   722  		return err
   723  	}
   724  
   725  	if trace != nil && trace.WroteHeaders != nil {
   726  		trace.WroteHeaders()
   727  	}
   728  
   729  	// Flush and wait for 100-continue if expected.
   730  	if waitForContinue != nil {
   731  		if bw, ok := w.(*bufio.Writer); ok {
   732  			err = bw.Flush()
   733  			if err != nil {
   734  				return err
   735  			}
   736  		}
   737  		if trace != nil && trace.Wait100Continue != nil {
   738  			trace.Wait100Continue()
   739  		}
   740  		if !waitForContinue() {
   741  			closed = true
   742  			r.closeBody()
   743  			return nil
   744  		}
   745  	}
   746  
   747  	if bw, ok := w.(*bufio.Writer); ok && tw.FlushHeaders {
   748  		if err := bw.Flush(); err != nil {
   749  			return err
   750  		}
   751  	}
   752  
   753  	// Write body and trailer
   754  	closed = true
   755  	err = tw.writeBody(w)
   756  	if err != nil {
   757  		if tw.bodyReadError == err {
   758  			err = requestBodyReadError{err}
   759  		}
   760  		return err
   761  	}
   762  
   763  	if bw != nil {
   764  		return bw.Flush()
   765  	}
   766  	return nil
   767  }
   768  
   769  // requestBodyReadError wraps an error from (*Request).write to indicate
   770  // that the error came from a Read call on the Request.Body.
   771  // This error type should not escape the net/http package to users.
   772  type requestBodyReadError struct{ error }
   773  
   774  func idnaASCII(v string) (string, error) {
   775  	// TODO: Consider removing this check after verifying performance is okay.
   776  	// Right now punycode verification, length checks, context checks, and the
   777  	// permissible character tests are all omitted. It also prevents the ToASCII
   778  	// call from salvaging an invalid IDN, when possible. As a result it may be
   779  	// possible to have two IDNs that appear identical to the user where the
   780  	// ASCII-only version causes an error downstream whereas the non-ASCII
   781  	// version does not.
   782  	// Note that for correct ASCII IDNs ToASCII will only do considerably more
   783  	// work, but it will not cause an allocation.
   784  	if ascii.Is(v) {
   785  		return v, nil
   786  	}
   787  	return idna.Lookup.ToASCII(v)
   788  }
   789  
   790  // removeZone removes IPv6 zone identifier from host.
   791  // E.g., "[fe80::1%en0]:8080" to "[fe80::1]:8080"
   792  func removeZone(host string) string {
   793  	if !strings.HasPrefix(host, "[") {
   794  		return host
   795  	}
   796  	i := strings.LastIndex(host, "]")
   797  	if i < 0 {
   798  		return host
   799  	}
   800  	j := strings.LastIndex(host[:i], "%")
   801  	if j < 0 {
   802  		return host
   803  	}
   804  	return host[:j] + host[i:]
   805  }
   806  
   807  // ParseHTTPVersion parses an HTTP version string according to RFC 7230, section 2.6.
   808  // "HTTP/1.0" returns (1, 0, true). Note that strings without
   809  // a minor version, such as "HTTP/2", are not valid.
   810  func ParseHTTPVersion(vers string) (major, minor int, ok bool) {
   811  	switch vers {
   812  	case "HTTP/1.1":
   813  		return 1, 1, true
   814  	case "HTTP/1.0":
   815  		return 1, 0, true
   816  	}
   817  	if !strings.HasPrefix(vers, "HTTP/") {
   818  		return 0, 0, false
   819  	}
   820  	if len(vers) != len("HTTP/X.Y") {
   821  		return 0, 0, false
   822  	}
   823  	if vers[6] != '.' {
   824  		return 0, 0, false
   825  	}
   826  	maj, err := strconv.ParseUint(vers[5:6], 10, 0)
   827  	if err != nil {
   828  		return 0, 0, false
   829  	}
   830  	min, err := strconv.ParseUint(vers[7:8], 10, 0)
   831  	if err != nil {
   832  		return 0, 0, false
   833  	}
   834  	return int(maj), int(min), true
   835  }
   836  
   837  func validMethod(method string) bool {
   838  	/*
   839  	     Method         = "OPTIONS"                ; Section 9.2
   840  	                    | "GET"                    ; Section 9.3
   841  	                    | "HEAD"                   ; Section 9.4
   842  	                    | "POST"                   ; Section 9.5
   843  	                    | "PUT"                    ; Section 9.6
   844  	                    | "DELETE"                 ; Section 9.7
   845  	                    | "TRACE"                  ; Section 9.8
   846  	                    | "CONNECT"                ; Section 9.9
   847  	                    | extension-method
   848  	   extension-method = token
   849  	     token          = 1*<any CHAR except CTLs or separators>
   850  	*/
   851  	return len(method) > 0 && strings.IndexFunc(method, isNotToken) == -1
   852  }
   853  
   854  // NewRequest wraps [NewRequestWithContext] using [context.Background].
   855  func NewRequest(method, url string, body io.Reader) (*Request, error) {
   856  	return NewRequestWithContext(context.Background(), method, url, body)
   857  }
   858  
   859  // NewRequestWithContext returns a new [Request] given a method, URL, and
   860  // optional body.
   861  //
   862  // If the provided body is also an [io.Closer], the returned
   863  // [Request.Body] is set to body and will be closed (possibly
   864  // asynchronously) by the Client methods Do, Post, and PostForm,
   865  // and [Transport.RoundTrip].
   866  //
   867  // NewRequestWithContext returns a Request suitable for use with
   868  // [Client.Do] or [Transport.RoundTrip]. To create a request for use with
   869  // testing a Server Handler, either use the [NewRequest] function in the
   870  // net/http/httptest package, use [ReadRequest], or manually update the
   871  // Request fields. For an outgoing client request, the context
   872  // controls the entire lifetime of a request and its response:
   873  // obtaining a connection, sending the request, and reading the
   874  // response headers and body. See the Request type's documentation for
   875  // the difference between inbound and outbound request fields.
   876  //
   877  // If body is of type [*bytes.Buffer], [*bytes.Reader], or
   878  // [*strings.Reader], the returned request's ContentLength is set to its
   879  // exact value (instead of -1), GetBody is populated (so 307 and 308
   880  // redirects can replay the body), and Body is set to [NoBody] if the
   881  // ContentLength is 0.
   882  func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error) {
   883  	if method == "" {
   884  		// We document that "" means "GET" for Request.Method, and people have
   885  		// relied on that from NewRequest, so keep that working.
   886  		// We still enforce validMethod for non-empty methods.
   887  		method = "GET"
   888  	}
   889  	if !validMethod(method) {
   890  		return nil, fmt.Errorf("net/http: invalid method %q", method)
   891  	}
   892  	if ctx == nil {
   893  		return nil, errors.New("net/http: nil Context")
   894  	}
   895  	u, err := urlpkg.Parse(url)
   896  	if err != nil {
   897  		return nil, err
   898  	}
   899  	rc, ok := body.(io.ReadCloser)
   900  	if !ok && body != nil {
   901  		rc = io.NopCloser(body)
   902  	}
   903  	// The host's colon:port should be normalized. See Issue 14836.
   904  	u.Host = removeEmptyPort(u.Host)
   905  	req := &Request{
   906  		ctx:        ctx,
   907  		Method:     method,
   908  		URL:        u,
   909  		Proto:      "HTTP/1.1",
   910  		ProtoMajor: 1,
   911  		ProtoMinor: 1,
   912  		Header:     make(Header),
   913  		Body:       rc,
   914  		Host:       u.Host,
   915  	}
   916  	if body != nil {
   917  		switch v := body.(type) {
   918  		case *bytes.Buffer:
   919  			req.ContentLength = int64(v.Len())
   920  			buf := v.Bytes()
   921  			req.GetBody = func() (io.ReadCloser, error) {
   922  				r := bytes.NewReader(buf)
   923  				return io.NopCloser(r), nil
   924  			}
   925  		case *bytes.Reader:
   926  			req.ContentLength = int64(v.Len())
   927  			snapshot := *v
   928  			req.GetBody = func() (io.ReadCloser, error) {
   929  				r := snapshot
   930  				return io.NopCloser(&r), nil
   931  			}
   932  		case *strings.Reader:
   933  			req.ContentLength = int64(v.Len())
   934  			snapshot := *v
   935  			req.GetBody = func() (io.ReadCloser, error) {
   936  				r := snapshot
   937  				return io.NopCloser(&r), nil
   938  			}
   939  		default:
   940  			// This is where we'd set it to -1 (at least
   941  			// if body != NoBody) to mean unknown, but
   942  			// that broke people during the Go 1.8 testing
   943  			// period. People depend on it being 0 I
   944  			// guess. Maybe retry later. See Issue 18117.
   945  		}
   946  		// For client requests, Request.ContentLength of 0
   947  		// means either actually 0, or unknown. The only way
   948  		// to explicitly say that the ContentLength is zero is
   949  		// to set the Body to nil. But turns out too much code
   950  		// depends on NewRequest returning a non-nil Body,
   951  		// so we use a well-known ReadCloser variable instead
   952  		// and have the http package also treat that sentinel
   953  		// variable to mean explicitly zero.
   954  		if req.GetBody != nil && req.ContentLength == 0 {
   955  			req.Body = NoBody
   956  			req.GetBody = func() (io.ReadCloser, error) { return NoBody, nil }
   957  		}
   958  	}
   959  
   960  	return req, nil
   961  }
   962  
   963  // BasicAuth returns the username and password provided in the request's
   964  // Authorization header, if the request uses HTTP Basic Authentication.
   965  // See RFC 2617, Section 2.
   966  func (r *Request) BasicAuth() (username, password string, ok bool) {
   967  	auth := r.Header.Get("Authorization")
   968  	if auth == "" {
   969  		return "", "", false
   970  	}
   971  	return parseBasicAuth(auth)
   972  }
   973  
   974  // parseBasicAuth parses an HTTP Basic Authentication string.
   975  // "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" returns ("Aladdin", "open sesame", true).
   976  func parseBasicAuth(auth string) (username, password string, ok bool) {
   977  	const prefix = "Basic "
   978  	// Case insensitive prefix match. See Issue 22736.
   979  	if len(auth) < len(prefix) || !ascii.EqualFold(auth[:len(prefix)], prefix) {
   980  		return "", "", false
   981  	}
   982  	c, err := base64.StdEncoding.DecodeString(auth[len(prefix):])
   983  	if err != nil {
   984  		return "", "", false
   985  	}
   986  	cs := string(c)
   987  	username, password, ok = strings.Cut(cs, ":")
   988  	if !ok {
   989  		return "", "", false
   990  	}
   991  	return username, password, true
   992  }
   993  
   994  // SetBasicAuth sets the request's Authorization header to use HTTP
   995  // Basic Authentication with the provided username and password.
   996  //
   997  // With HTTP Basic Authentication the provided username and password
   998  // are not encrypted. It should generally only be used in an HTTPS
   999  // request.
  1000  //
  1001  // The username may not contain a colon. Some protocols may impose
  1002  // additional requirements on pre-escaping the username and
  1003  // password. For instance, when used with OAuth2, both arguments must
  1004  // be URL encoded first with [url.QueryEscape].
  1005  func (r *Request) SetBasicAuth(username, password string) {
  1006  	r.Header.Set("Authorization", "Basic "+basicAuth(username, password))
  1007  }
  1008  
  1009  // parseRequestLine parses "GET /foo HTTP/1.1" into its three parts.
  1010  func parseRequestLine(line string) (method, requestURI, proto string, ok bool) {
  1011  	method, rest, ok1 := strings.Cut(line, " ")
  1012  	requestURI, proto, ok2 := strings.Cut(rest, " ")
  1013  	if !ok1 || !ok2 {
  1014  		return "", "", "", false
  1015  	}
  1016  	return method, requestURI, proto, true
  1017  }
  1018  
  1019  var textprotoReaderPool sync.Pool
  1020  
  1021  func newTextprotoReader(br *bufio.Reader) *textproto.Reader {
  1022  	if v := textprotoReaderPool.Get(); v != nil {
  1023  		tr := v.(*textproto.Reader)
  1024  		tr.R = br
  1025  		return tr
  1026  	}
  1027  	return textproto.NewReader(br)
  1028  }
  1029  
  1030  func putTextprotoReader(r *textproto.Reader) {
  1031  	r.R = nil
  1032  	textprotoReaderPool.Put(r)
  1033  }
  1034  
  1035  // ReadRequest reads and parses an incoming request from b.
  1036  //
  1037  // ReadRequest is a low-level function and should only be used for
  1038  // specialized applications; most code should use the [Server] to read
  1039  // requests and handle them via the [Handler] interface. ReadRequest
  1040  // only supports HTTP/1.x requests. For HTTP/2, use golang.org/x/net/http2.
  1041  func ReadRequest(b *bufio.Reader) (*Request, error) {
  1042  	req, err := readRequest(b)
  1043  	if err != nil {
  1044  		return nil, err
  1045  	}
  1046  
  1047  	delete(req.Header, "Host")
  1048  	return req, err
  1049  }
  1050  
  1051  func readRequest(b *bufio.Reader) (req *Request, err error) {
  1052  	tp := newTextprotoReader(b)
  1053  	defer putTextprotoReader(tp)
  1054  
  1055  	req = new(Request)
  1056  
  1057  	// First line: GET /index.html HTTP/1.0
  1058  	var s string
  1059  	if s, err = tp.ReadLine(); err != nil {
  1060  		return nil, err
  1061  	}
  1062  	defer func() {
  1063  		if err == io.EOF {
  1064  			err = io.ErrUnexpectedEOF
  1065  		}
  1066  	}()
  1067  
  1068  	var ok bool
  1069  	req.Method, req.RequestURI, req.Proto, ok = parseRequestLine(s)
  1070  	if !ok {
  1071  		return nil, badStringError("malformed HTTP request", s)
  1072  	}
  1073  	if !validMethod(req.Method) {
  1074  		return nil, badStringError("invalid method", req.Method)
  1075  	}
  1076  	rawurl := req.RequestURI
  1077  	if req.ProtoMajor, req.ProtoMinor, ok = ParseHTTPVersion(req.Proto); !ok {
  1078  		return nil, badStringError("malformed HTTP version", req.Proto)
  1079  	}
  1080  
  1081  	// CONNECT requests are used two different ways, and neither uses a full URL:
  1082  	// The standard use is to tunnel HTTPS through an HTTP proxy.
  1083  	// It looks like "CONNECT www.google.com:443 HTTP/1.1", and the parameter is
  1084  	// just the authority section of a URL. This information should go in req.URL.Host.
  1085  	//
  1086  	// The net/rpc package also uses CONNECT, but there the parameter is a path
  1087  	// that starts with a slash. It can be parsed with the regular URL parser,
  1088  	// and the path will end up in req.URL.Path, where it needs to be in order for
  1089  	// RPC to work.
  1090  	justAuthority := req.Method == "CONNECT" && !strings.HasPrefix(rawurl, "/")
  1091  	if justAuthority {
  1092  		rawurl = "http://" + rawurl
  1093  	}
  1094  
  1095  	if req.URL, err = url.ParseRequestURI(rawurl); err != nil {
  1096  		return nil, err
  1097  	}
  1098  
  1099  	if justAuthority {
  1100  		// Strip the bogus "http://" back off.
  1101  		req.URL.Scheme = ""
  1102  	}
  1103  
  1104  	// Subsequent lines: Key: value.
  1105  	mimeHeader, err := tp.ReadMIMEHeader()
  1106  	if err != nil {
  1107  		return nil, err
  1108  	}
  1109  	req.Header = Header(mimeHeader)
  1110  	if len(req.Header["Host"]) > 1 {
  1111  		return nil, fmt.Errorf("too many Host headers")
  1112  	}
  1113  
  1114  	// RFC 7230, section 5.3: Must treat
  1115  	//	GET /index.html HTTP/1.1
  1116  	//	Host: www.google.com
  1117  	// and
  1118  	//	GET http://www.google.com/index.html HTTP/1.1
  1119  	//	Host: doesntmatter
  1120  	// the same. In the second case, any Host line is ignored.
  1121  	req.Host = req.URL.Host
  1122  	if req.Host == "" {
  1123  		req.Host = req.Header.get("Host")
  1124  	}
  1125  
  1126  	fixPragmaCacheControl(req.Header)
  1127  
  1128  	req.Close = shouldClose(req.ProtoMajor, req.ProtoMinor, req.Header, false)
  1129  
  1130  	err = readTransfer(req, b)
  1131  	if err != nil {
  1132  		return nil, err
  1133  	}
  1134  
  1135  	if req.isH2Upgrade() {
  1136  		// Because it's neither chunked, nor declared:
  1137  		req.ContentLength = -1
  1138  
  1139  		// We want to give handlers a chance to hijack the
  1140  		// connection, but we need to prevent the Server from
  1141  		// dealing with the connection further if it's not
  1142  		// hijacked. Set Close to ensure that:
  1143  		req.Close = true
  1144  	}
  1145  	return req, nil
  1146  }
  1147  
  1148  // MaxBytesReader is similar to [io.LimitReader] but is intended for
  1149  // limiting the size of incoming request bodies. In contrast to
  1150  // io.LimitReader, MaxBytesReader's result is a ReadCloser, returns a
  1151  // non-nil error of type [*MaxBytesError] for a Read beyond the limit,
  1152  // and closes the underlying reader when its Close method is called.
  1153  //
  1154  // MaxBytesReader prevents clients from accidentally or maliciously
  1155  // sending a large request and wasting server resources. If possible,
  1156  // it tells the [ResponseWriter] to close the connection after the limit
  1157  // has been reached.
  1158  func MaxBytesReader(w ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser {
  1159  	if n < 0 { // Treat negative limits as equivalent to 0.
  1160  		n = 0
  1161  	}
  1162  	return &maxBytesReader{w: w, r: r, i: n, n: n}
  1163  }
  1164  
  1165  // MaxBytesError is returned by [MaxBytesReader] when its read limit is exceeded.
  1166  type MaxBytesError struct {
  1167  	Limit int64
  1168  }
  1169  
  1170  func (e *MaxBytesError) Error() string {
  1171  	// Due to Hyrum's law, this text cannot be changed.
  1172  	return "http: request body too large"
  1173  }
  1174  
  1175  type maxBytesReader struct {
  1176  	w   ResponseWriter
  1177  	r   io.ReadCloser // underlying reader
  1178  	i   int64         // max bytes initially, for MaxBytesError
  1179  	n   int64         // max bytes remaining
  1180  	err error         // sticky error
  1181  }
  1182  
  1183  func (l *maxBytesReader) Read(p []byte) (n int, err error) {
  1184  	if l.err != nil {
  1185  		return 0, l.err
  1186  	}
  1187  	if len(p) == 0 {
  1188  		return 0, nil
  1189  	}
  1190  	// If they asked for a 32KB byte read but only 5 bytes are
  1191  	// remaining, no need to read 32KB. 6 bytes will answer the
  1192  	// question of the whether we hit the limit or go past it.
  1193  	// 0 < len(p) < 2^63
  1194  	if int64(len(p))-1 > l.n {
  1195  		p = p[:l.n+1]
  1196  	}
  1197  	n, err = l.r.Read(p)
  1198  
  1199  	if int64(n) <= l.n {
  1200  		l.n -= int64(n)
  1201  		l.err = err
  1202  		return n, err
  1203  	}
  1204  
  1205  	n = int(l.n)
  1206  	l.n = 0
  1207  
  1208  	// The server code and client code both use
  1209  	// maxBytesReader. This "requestTooLarge" check is
  1210  	// only used by the server code. To prevent binaries
  1211  	// which only using the HTTP Client code (such as
  1212  	// cmd/go) from also linking in the HTTP server, don't
  1213  	// use a static type assertion to the server
  1214  	// "*response" type. Check this interface instead:
  1215  	type requestTooLarger interface {
  1216  		requestTooLarge()
  1217  	}
  1218  	if res, ok := l.w.(requestTooLarger); ok {
  1219  		res.requestTooLarge()
  1220  	}
  1221  	l.err = &MaxBytesError{l.i}
  1222  	return n, l.err
  1223  }
  1224  
  1225  func (l *maxBytesReader) Close() error {
  1226  	return l.r.Close()
  1227  }
  1228  
  1229  func copyValues(dst, src url.Values) {
  1230  	for k, vs := range src {
  1231  		dst[k] = append(dst[k], vs...)
  1232  	}
  1233  }
  1234  
  1235  func parsePostForm(r *Request) (vs url.Values, err error) {
  1236  	if r.Body == nil {
  1237  		err = errors.New("missing form body")
  1238  		return
  1239  	}
  1240  	ct := r.Header.Get("Content-Type")
  1241  	// RFC 7231, section 3.1.1.5 - empty type
  1242  	//   MAY be treated as application/octet-stream
  1243  	if ct == "" {
  1244  		ct = "application/octet-stream"
  1245  	}
  1246  	ct, _, err = mime.ParseMediaType(ct)
  1247  	switch {
  1248  	case ct == "application/x-www-form-urlencoded":
  1249  		var reader io.Reader = r.Body
  1250  		maxFormSize := int64(1<<63 - 1)
  1251  		if _, ok := r.Body.(*maxBytesReader); !ok {
  1252  			maxFormSize = int64(10 << 20) // 10 MB is a lot of text.
  1253  			reader = io.LimitReader(r.Body, maxFormSize+1)
  1254  		}
  1255  		b, e := io.ReadAll(reader)
  1256  		if e != nil {
  1257  			if err == nil {
  1258  				err = e
  1259  			}
  1260  			break
  1261  		}
  1262  		if int64(len(b)) > maxFormSize {
  1263  			err = errors.New("http: POST too large")
  1264  			return
  1265  		}
  1266  		vs, e = url.ParseQuery(string(b))
  1267  		if err == nil {
  1268  			err = e
  1269  		}
  1270  	case ct == "multipart/form-data":
  1271  		// handled by ParseMultipartForm (which is calling us, or should be)
  1272  		// TODO(bradfitz): there are too many possible
  1273  		// orders to call too many functions here.
  1274  		// Clean this up and write more tests.
  1275  		// request_test.go contains the start of this,
  1276  		// in TestParseMultipartFormOrder and others.
  1277  	}
  1278  	return
  1279  }
  1280  
  1281  // ParseForm populates r.Form and r.PostForm.
  1282  //
  1283  // For all requests, ParseForm parses the raw query from the URL and updates
  1284  // r.Form.
  1285  //
  1286  // For POST, PUT, and PATCH requests, it also reads the request body, parses it
  1287  // as a form and puts the results into both r.PostForm and r.Form. Request body
  1288  // parameters take precedence over URL query string values in r.Form.
  1289  //
  1290  // If the request Body's size has not already been limited by [MaxBytesReader],
  1291  // the size is capped at 10MB.
  1292  //
  1293  // For other HTTP methods, or when the Content-Type is not
  1294  // application/x-www-form-urlencoded, the request Body is not read, and
  1295  // r.PostForm is initialized to a non-nil, empty value.
  1296  //
  1297  // [Request.ParseMultipartForm] calls ParseForm automatically.
  1298  // ParseForm is idempotent.
  1299  func (r *Request) ParseForm() error {
  1300  	var err error
  1301  	if r.PostForm == nil {
  1302  		if r.Method == "POST" || r.Method == "PUT" || r.Method == "PATCH" {
  1303  			r.PostForm, err = parsePostForm(r)
  1304  		}
  1305  		if r.PostForm == nil {
  1306  			r.PostForm = make(url.Values)
  1307  		}
  1308  	}
  1309  	if r.Form == nil {
  1310  		if len(r.PostForm) > 0 {
  1311  			r.Form = make(url.Values)
  1312  			copyValues(r.Form, r.PostForm)
  1313  		}
  1314  		var newValues url.Values
  1315  		if r.URL != nil {
  1316  			var e error
  1317  			newValues, e = url.ParseQuery(r.URL.RawQuery)
  1318  			if err == nil {
  1319  				err = e
  1320  			}
  1321  		}
  1322  		if newValues == nil {
  1323  			newValues = make(url.Values)
  1324  		}
  1325  		if r.Form == nil {
  1326  			r.Form = newValues
  1327  		} else {
  1328  			copyValues(r.Form, newValues)
  1329  		}
  1330  	}
  1331  	return err
  1332  }
  1333  
  1334  // ParseMultipartForm parses a request body as multipart/form-data.
  1335  // The whole request body is parsed and up to a total of maxMemory bytes of
  1336  // its file parts are stored in memory, with the remainder stored on
  1337  // disk in temporary files.
  1338  // ParseMultipartForm calls [Request.ParseForm] if necessary.
  1339  // If ParseForm returns an error, ParseMultipartForm returns it but also
  1340  // continues parsing the request body.
  1341  // After one call to ParseMultipartForm, subsequent calls have no effect.
  1342  func (r *Request) ParseMultipartForm(maxMemory int64) error {
  1343  	if r.MultipartForm == multipartByReader {
  1344  		return errors.New("http: multipart handled by MultipartReader")
  1345  	}
  1346  	var parseFormErr error
  1347  	if r.Form == nil {
  1348  		// Let errors in ParseForm fall through, and just
  1349  		// return it at the end.
  1350  		parseFormErr = r.ParseForm()
  1351  	}
  1352  	if r.MultipartForm != nil {
  1353  		return nil
  1354  	}
  1355  
  1356  	mr, err := r.multipartReader(false)
  1357  	if err != nil {
  1358  		return err
  1359  	}
  1360  
  1361  	f, err := mr.ReadForm(maxMemory)
  1362  	if err != nil {
  1363  		return err
  1364  	}
  1365  
  1366  	if r.PostForm == nil {
  1367  		r.PostForm = make(url.Values)
  1368  	}
  1369  	for k, v := range f.Value {
  1370  		r.Form[k] = append(r.Form[k], v...)
  1371  		// r.PostForm should also be populated. See Issue 9305.
  1372  		r.PostForm[k] = append(r.PostForm[k], v...)
  1373  	}
  1374  
  1375  	r.MultipartForm = f
  1376  
  1377  	return parseFormErr
  1378  }
  1379  
  1380  // FormValue returns the first value for the named component of the query.
  1381  // The precedence order:
  1382  //  1. application/x-www-form-urlencoded form body (POST, PUT, PATCH only)
  1383  //  2. query parameters (always)
  1384  //  3. multipart/form-data form body (always)
  1385  //
  1386  // FormValue calls [Request.ParseMultipartForm] and [Request.ParseForm]
  1387  // if necessary and ignores any errors returned by these functions.
  1388  // If key is not present, FormValue returns the empty string.
  1389  // To access multiple values of the same key, call ParseForm and
  1390  // then inspect [Request.Form] directly.
  1391  func (r *Request) FormValue(key string) string {
  1392  	if r.Form == nil {
  1393  		r.ParseMultipartForm(defaultMaxMemory)
  1394  	}
  1395  	if vs := r.Form[key]; len(vs) > 0 {
  1396  		return vs[0]
  1397  	}
  1398  	return ""
  1399  }
  1400  
  1401  // PostFormValue returns the first value for the named component of the POST,
  1402  // PUT, or PATCH request body. URL query parameters are ignored.
  1403  // PostFormValue calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary and ignores
  1404  // any errors returned by these functions.
  1405  // If key is not present, PostFormValue returns the empty string.
  1406  func (r *Request) PostFormValue(key string) string {
  1407  	if r.PostForm == nil {
  1408  		r.ParseMultipartForm(defaultMaxMemory)
  1409  	}
  1410  	if vs := r.PostForm[key]; len(vs) > 0 {
  1411  		return vs[0]
  1412  	}
  1413  	return ""
  1414  }
  1415  
  1416  // FormFile returns the first file for the provided form key.
  1417  // FormFile calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary.
  1418  func (r *Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error) {
  1419  	if r.MultipartForm == multipartByReader {
  1420  		return nil, nil, errors.New("http: multipart handled by MultipartReader")
  1421  	}
  1422  	if r.MultipartForm == nil {
  1423  		err := r.ParseMultipartForm(defaultMaxMemory)
  1424  		if err != nil {
  1425  			return nil, nil, err
  1426  		}
  1427  	}
  1428  	if r.MultipartForm != nil && r.MultipartForm.File != nil {
  1429  		if fhs := r.MultipartForm.File[key]; len(fhs) > 0 {
  1430  			f, err := fhs[0].Open()
  1431  			return f, fhs[0], err
  1432  		}
  1433  	}
  1434  	return nil, nil, ErrMissingFile
  1435  }
  1436  
  1437  // PathValue returns the value for the named path wildcard in the [ServeMux] pattern
  1438  // that matched the request.
  1439  // It returns the empty string if the request was not matched against a pattern
  1440  // or there is no such wildcard in the pattern.
  1441  func (r *Request) PathValue(name string) string {
  1442  	if i := r.patIndex(name); i >= 0 {
  1443  		return r.matches[i]
  1444  	}
  1445  	return r.otherValues[name]
  1446  }
  1447  
  1448  // SetPathValue sets name to value, so that subsequent calls to r.PathValue(name)
  1449  // return value.
  1450  func (r *Request) SetPathValue(name, value string) {
  1451  	if i := r.patIndex(name); i >= 0 {
  1452  		r.matches[i] = value
  1453  	} else {
  1454  		if r.otherValues == nil {
  1455  			r.otherValues = map[string]string{}
  1456  		}
  1457  		r.otherValues[name] = value
  1458  	}
  1459  }
  1460  
  1461  // patIndex returns the index of name in the list of named wildcards of the
  1462  // request's pattern, or -1 if there is no such name.
  1463  func (r *Request) patIndex(name string) int {
  1464  	// The linear search seems expensive compared to a map, but just creating the map
  1465  	// takes a lot of time, and most patterns will just have a couple of wildcards.
  1466  	if r.pat == nil {
  1467  		return -1
  1468  	}
  1469  	i := 0
  1470  	for _, seg := range r.pat.segments {
  1471  		if seg.wild && seg.s != "" {
  1472  			if name == seg.s {
  1473  				return i
  1474  			}
  1475  			i++
  1476  		}
  1477  	}
  1478  	return -1
  1479  }
  1480  
  1481  func (r *Request) expectsContinue() bool {
  1482  	return hasToken(r.Header.get("Expect"), "100-continue")
  1483  }
  1484  
  1485  func (r *Request) wantsHttp10KeepAlive() bool {
  1486  	if r.ProtoMajor != 1 || r.ProtoMinor != 0 {
  1487  		return false
  1488  	}
  1489  	return hasToken(r.Header.get("Connection"), "keep-alive")
  1490  }
  1491  
  1492  func (r *Request) wantsClose() bool {
  1493  	if r.Close {
  1494  		return true
  1495  	}
  1496  	return hasToken(r.Header.get("Connection"), "close")
  1497  }
  1498  
  1499  func (r *Request) closeBody() error {
  1500  	if r.Body == nil {
  1501  		return nil
  1502  	}
  1503  	return r.Body.Close()
  1504  }
  1505  
  1506  func (r *Request) isReplayable() bool {
  1507  	if r.Body == nil || r.Body == NoBody || r.GetBody != nil {
  1508  		switch valueOrDefault(r.Method, "GET") {
  1509  		case "GET", "HEAD", "OPTIONS", "TRACE":
  1510  			return true
  1511  		}
  1512  		// The Idempotency-Key, while non-standard, is widely used to
  1513  		// mean a POST or other request is idempotent. See
  1514  		// https://golang.org/issue/19943#issuecomment-421092421
  1515  		if r.Header.has("Idempotency-Key") || r.Header.has("X-Idempotency-Key") {
  1516  			return true
  1517  		}
  1518  	}
  1519  	return false
  1520  }
  1521  
  1522  // outgoingLength reports the Content-Length of this outgoing (Client) request.
  1523  // It maps 0 into -1 (unknown) when the Body is non-nil.
  1524  func (r *Request) outgoingLength() int64 {
  1525  	if r.Body == nil || r.Body == NoBody {
  1526  		return 0
  1527  	}
  1528  	if r.ContentLength != 0 {
  1529  		return r.ContentLength
  1530  	}
  1531  	return -1
  1532  }
  1533  
  1534  // requestMethodUsuallyLacksBody reports whether the given request
  1535  // method is one that typically does not involve a request body.
  1536  // This is used by the Transport (via
  1537  // transferWriter.shouldSendChunkedRequestBody) to determine whether
  1538  // we try to test-read a byte from a non-nil Request.Body when
  1539  // Request.outgoingLength() returns -1. See the comments in
  1540  // shouldSendChunkedRequestBody.
  1541  func requestMethodUsuallyLacksBody(method string) bool {
  1542  	switch method {
  1543  	case "GET", "HEAD", "DELETE", "OPTIONS", "PROPFIND", "SEARCH":
  1544  		return true
  1545  	}
  1546  	return false
  1547  }
  1548  
  1549  // requiresHTTP1 reports whether this request requires being sent on
  1550  // an HTTP/1 connection.
  1551  func (r *Request) requiresHTTP1() bool {
  1552  	return hasToken(r.Header.Get("Connection"), "upgrade") &&
  1553  		ascii.EqualFold(r.Header.Get("Upgrade"), "websocket")
  1554  }
  1555  

View as plain text