...
Run Format

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		"io/ioutil"
    19		"mime"
    20		"mime/multipart"
    21		"net/http/httptrace"
    22		"net/textproto"
    23		"net/url"
    24		"strconv"
    25		"strings"
    26		"sync"
    27	)
    28	
    29	const (
    30		defaultMaxMemory = 32 << 20 // 32 MB
    31	)
    32	
    33	// ErrMissingFile is returned by FormFile when the provided file field name
    34	// is either not present in the request or not a file field.
    35	var ErrMissingFile = errors.New("http: no such file")
    36	
    37	// HTTP request parsing errors.
    38	type ProtocolError struct {
    39		ErrorString string
    40	}
    41	
    42	func (err *ProtocolError) Error() string { return err.ErrorString }
    43	
    44	var (
    45		ErrHeaderTooLong        = &ProtocolError{"header too long"}
    46		ErrShortBody            = &ProtocolError{"entity body too short"}
    47		ErrNotSupported         = &ProtocolError{"feature not supported"}
    48		ErrUnexpectedTrailer    = &ProtocolError{"trailer header without chunked transfer encoding"}
    49		ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
    50		ErrNotMultipart         = &ProtocolError{"request Content-Type isn't multipart/form-data"}
    51		ErrMissingBoundary      = &ProtocolError{"no multipart boundary param in Content-Type"}
    52	)
    53	
    54	type badStringError struct {
    55		what string
    56		str  string
    57	}
    58	
    59	func (e *badStringError) Error() string { return fmt.Sprintf("%s %q", e.what, e.str) }
    60	
    61	// Headers that Request.Write handles itself and should be skipped.
    62	var reqWriteExcludeHeader = map[string]bool{
    63		"Host":              true, // not in Header map anyway
    64		"User-Agent":        true,
    65		"Content-Length":    true,
    66		"Transfer-Encoding": true,
    67		"Trailer":           true,
    68	}
    69	
    70	// A Request represents an HTTP request received by a server
    71	// or to be sent by a client.
    72	//
    73	// The field semantics differ slightly between client and server
    74	// usage. In addition to the notes on the fields below, see the
    75	// documentation for Request.Write and RoundTripper.
    76	type Request struct {
    77		// Method specifies the HTTP method (GET, POST, PUT, etc.).
    78		// For client requests an empty string means GET.
    79		Method string
    80	
    81		// URL specifies either the URI being requested (for server
    82		// requests) or the URL to access (for client requests).
    83		//
    84		// For server requests the URL is parsed from the URI
    85		// supplied on the Request-Line as stored in RequestURI.  For
    86		// most requests, fields other than Path and RawQuery will be
    87		// empty. (See RFC 2616, Section 5.1.2)
    88		//
    89		// For client requests, the URL's Host specifies the server to
    90		// connect to, while the Request's Host field optionally
    91		// specifies the Host header value to send in the HTTP
    92		// request.
    93		URL *url.URL
    94	
    95		// The protocol version for incoming server requests.
    96		//
    97		// For client requests these fields are ignored. The HTTP
    98		// client code always uses either HTTP/1.1 or HTTP/2.
    99		// See the docs on Transport for details.
   100		Proto      string // "HTTP/1.0"
   101		ProtoMajor int    // 1
   102		ProtoMinor int    // 0
   103	
   104		// Header contains the request header fields either received
   105		// by the server or to be sent by the client.
   106		//
   107		// If a server received a request with header lines,
   108		//
   109		//	Host: example.com
   110		//	accept-encoding: gzip, deflate
   111		//	Accept-Language: en-us
   112		//	fOO: Bar
   113		//	foo: two
   114		//
   115		// then
   116		//
   117		//	Header = map[string][]string{
   118		//		"Accept-Encoding": {"gzip, deflate"},
   119		//		"Accept-Language": {"en-us"},
   120		//		"Foo": {"Bar", "two"},
   121		//	}
   122		//
   123		// For incoming requests, the Host header is promoted to the
   124		// Request.Host field and removed from the Header map.
   125		//
   126		// HTTP defines that header names are case-insensitive. The
   127		// request parser implements this by using CanonicalHeaderKey,
   128		// making the first character and any characters following a
   129		// hyphen uppercase and the rest lowercase.
   130		//
   131		// For client requests, certain headers such as Content-Length
   132		// and Connection are automatically written when needed and
   133		// values in Header may be ignored. See the documentation
   134		// for the Request.Write method.
   135		Header Header
   136	
   137		// Body is the request's body.
   138		//
   139		// For client requests a nil body means the request has no
   140		// body, such as a GET request. The HTTP Client's Transport
   141		// is responsible for calling the Close method.
   142		//
   143		// For server requests the Request Body is always non-nil
   144		// but will return EOF immediately when no body is present.
   145		// The Server will close the request body. The ServeHTTP
   146		// Handler does not need to.
   147		Body io.ReadCloser
   148	
   149		// ContentLength records the length of the associated content.
   150		// The value -1 indicates that the length is unknown.
   151		// Values >= 0 indicate that the given number of bytes may
   152		// be read from Body.
   153		// For client requests, a value of 0 means unknown if Body is not nil.
   154		ContentLength int64
   155	
   156		// TransferEncoding lists the transfer encodings from outermost to
   157		// innermost. An empty list denotes the "identity" encoding.
   158		// TransferEncoding can usually be ignored; chunked encoding is
   159		// automatically added and removed as necessary when sending and
   160		// receiving requests.
   161		TransferEncoding []string
   162	
   163		// Close indicates whether to close the connection after
   164		// replying to this request (for servers) or after sending this
   165		// request and reading its response (for clients).
   166		//
   167		// For server requests, the HTTP server handles this automatically
   168		// and this field is not needed by Handlers.
   169		//
   170		// For client requests, setting this field prevents re-use of
   171		// TCP connections between requests to the same hosts, as if
   172		// Transport.DisableKeepAlives were set.
   173		Close bool
   174	
   175		// For server requests Host specifies the host on which the
   176		// URL is sought. Per RFC 2616, this is either the value of
   177		// the "Host" header or the host name given in the URL itself.
   178		// It may be of the form "host:port".
   179		//
   180		// For client requests Host optionally overrides the Host
   181		// header to send. If empty, the Request.Write method uses
   182		// the value of URL.Host.
   183		Host string
   184	
   185		// Form contains the parsed form data, including both the URL
   186		// field's query parameters and the POST or PUT form data.
   187		// This field is only available after ParseForm is called.
   188		// The HTTP client ignores Form and uses Body instead.
   189		Form url.Values
   190	
   191		// PostForm contains the parsed form data from POST, PATCH,
   192		// or PUT body parameters.
   193		//
   194		// This field is only available after ParseForm is called.
   195		// The HTTP client ignores PostForm and uses Body instead.
   196		PostForm url.Values
   197	
   198		// MultipartForm is the parsed multipart form, including file uploads.
   199		// This field is only available after ParseMultipartForm is called.
   200		// The HTTP client ignores MultipartForm and uses Body instead.
   201		MultipartForm *multipart.Form
   202	
   203		// Trailer specifies additional headers that are sent after the request
   204		// body.
   205		//
   206		// For server requests the Trailer map initially contains only the
   207		// trailer keys, with nil values. (The client declares which trailers it
   208		// will later send.)  While the handler is reading from Body, it must
   209		// not reference Trailer. After reading from Body returns EOF, Trailer
   210		// can be read again and will contain non-nil values, if they were sent
   211		// by the client.
   212		//
   213		// For client requests Trailer must be initialized to a map containing
   214		// the trailer keys to later send. The values may be nil or their final
   215		// values. The ContentLength must be 0 or -1, to send a chunked request.
   216		// After the HTTP request is sent the map values can be updated while
   217		// the request body is read. Once the body returns EOF, the caller must
   218		// not mutate Trailer.
   219		//
   220		// Few HTTP clients, servers, or proxies support HTTP trailers.
   221		Trailer Header
   222	
   223		// RemoteAddr allows HTTP servers and other software to record
   224		// the network address that sent the request, usually for
   225		// logging. This field is not filled in by ReadRequest and
   226		// has no defined format. The HTTP server in this package
   227		// sets RemoteAddr to an "IP:port" address before invoking a
   228		// handler.
   229		// This field is ignored by the HTTP client.
   230		RemoteAddr string
   231	
   232		// RequestURI is the unmodified Request-URI of the
   233		// Request-Line (RFC 2616, Section 5.1) as sent by the client
   234		// to a server. Usually the URL field should be used instead.
   235		// It is an error to set this field in an HTTP client request.
   236		RequestURI string
   237	
   238		// TLS allows HTTP servers and other software to record
   239		// information about the TLS connection on which the request
   240		// was received. This field is not filled in by ReadRequest.
   241		// The HTTP server in this package sets the field for
   242		// TLS-enabled connections before invoking a handler;
   243		// otherwise it leaves the field nil.
   244		// This field is ignored by the HTTP client.
   245		TLS *tls.ConnectionState
   246	
   247		// Cancel is an optional channel whose closure indicates that the client
   248		// request should be regarded as canceled. Not all implementations of
   249		// RoundTripper may support Cancel.
   250		//
   251		// For server requests, this field is not applicable.
   252		//
   253		// Deprecated: Use the Context and WithContext methods
   254		// instead. If a Request's Cancel field and context are both
   255		// set, it is undefined whether Cancel is respected.
   256		Cancel <-chan struct{}
   257	
   258		// Response is the redirect response which caused this request
   259		// to be created. This field is only populated during client
   260		// redirects.
   261		Response *Response
   262	
   263		// ctx is either the client or server context. It should only
   264		// be modified via copying the whole Request using WithContext.
   265		// It is unexported to prevent people from using Context wrong
   266		// and mutating the contexts held by callers of the same request.
   267		ctx context.Context
   268	}
   269	
   270	// Context returns the request's context. To change the context, use
   271	// WithContext.
   272	//
   273	// The returned context is always non-nil; it defaults to the
   274	// background context.
   275	//
   276	// For outgoing client requests, the context controls cancelation.
   277	//
   278	// For incoming server requests, the context is canceled when the
   279	// ServeHTTP method returns. For its associated values, see
   280	// ServerContextKey and LocalAddrContextKey.
   281	func (r *Request) Context() context.Context {
   282		if r.ctx != nil {
   283			return r.ctx
   284		}
   285		return context.Background()
   286	}
   287	
   288	// WithContext returns a shallow copy of r with its context changed
   289	// to ctx. The provided ctx must be non-nil.
   290	func (r *Request) WithContext(ctx context.Context) *Request {
   291		if ctx == nil {
   292			panic("nil context")
   293		}
   294		r2 := new(Request)
   295		*r2 = *r
   296		r2.ctx = ctx
   297		return r2
   298	}
   299	
   300	// ProtoAtLeast reports whether the HTTP protocol used
   301	// in the request is at least major.minor.
   302	func (r *Request) ProtoAtLeast(major, minor int) bool {
   303		return r.ProtoMajor > major ||
   304			r.ProtoMajor == major && r.ProtoMinor >= minor
   305	}
   306	
   307	// UserAgent returns the client's User-Agent, if sent in the request.
   308	func (r *Request) UserAgent() string {
   309		return r.Header.Get("User-Agent")
   310	}
   311	
   312	// Cookies parses and returns the HTTP cookies sent with the request.
   313	func (r *Request) Cookies() []*Cookie {
   314		return readCookies(r.Header, "")
   315	}
   316	
   317	// ErrNoCookie is returned by Request's Cookie method when a cookie is not found.
   318	var ErrNoCookie = errors.New("http: named cookie not present")
   319	
   320	// Cookie returns the named cookie provided in the request or
   321	// ErrNoCookie if not found.
   322	func (r *Request) Cookie(name string) (*Cookie, error) {
   323		for _, c := range readCookies(r.Header, name) {
   324			return c, nil
   325		}
   326		return nil, ErrNoCookie
   327	}
   328	
   329	// AddCookie adds a cookie to the request. Per RFC 6265 section 5.4,
   330	// AddCookie does not attach more than one Cookie header field. That
   331	// means all cookies, if any, are written into the same line,
   332	// separated by semicolon.
   333	func (r *Request) AddCookie(c *Cookie) {
   334		s := fmt.Sprintf("%s=%s", sanitizeCookieName(c.Name), sanitizeCookieValue(c.Value))
   335		if c := r.Header.Get("Cookie"); c != "" {
   336			r.Header.Set("Cookie", c+"; "+s)
   337		} else {
   338			r.Header.Set("Cookie", s)
   339		}
   340	}
   341	
   342	// Referer returns the referring URL, if sent in the request.
   343	//
   344	// Referer is misspelled as in the request itself, a mistake from the
   345	// earliest days of HTTP.  This value can also be fetched from the
   346	// Header map as Header["Referer"]; the benefit of making it available
   347	// as a method is that the compiler can diagnose programs that use the
   348	// alternate (correct English) spelling req.Referrer() but cannot
   349	// diagnose programs that use Header["Referrer"].
   350	func (r *Request) Referer() string {
   351		return r.Header.Get("Referer")
   352	}
   353	
   354	// multipartByReader is a sentinel value.
   355	// Its presence in Request.MultipartForm indicates that parsing of the request
   356	// body has been handed off to a MultipartReader instead of ParseMultipartFrom.
   357	var multipartByReader = &multipart.Form{
   358		Value: make(map[string][]string),
   359		File:  make(map[string][]*multipart.FileHeader),
   360	}
   361	
   362	// MultipartReader returns a MIME multipart reader if this is a
   363	// multipart/form-data POST request, else returns nil and an error.
   364	// Use this function instead of ParseMultipartForm to
   365	// process the request body as a stream.
   366	func (r *Request) MultipartReader() (*multipart.Reader, error) {
   367		if r.MultipartForm == multipartByReader {
   368			return nil, errors.New("http: MultipartReader called twice")
   369		}
   370		if r.MultipartForm != nil {
   371			return nil, errors.New("http: multipart handled by ParseMultipartForm")
   372		}
   373		r.MultipartForm = multipartByReader
   374		return r.multipartReader()
   375	}
   376	
   377	func (r *Request) multipartReader() (*multipart.Reader, error) {
   378		v := r.Header.Get("Content-Type")
   379		if v == "" {
   380			return nil, ErrNotMultipart
   381		}
   382		d, params, err := mime.ParseMediaType(v)
   383		if err != nil || d != "multipart/form-data" {
   384			return nil, ErrNotMultipart
   385		}
   386		boundary, ok := params["boundary"]
   387		if !ok {
   388			return nil, ErrMissingBoundary
   389		}
   390		return multipart.NewReader(r.Body, boundary), nil
   391	}
   392	
   393	// isH2Upgrade reports whether r represents the http2 "client preface"
   394	// magic string.
   395	func (r *Request) isH2Upgrade() bool {
   396		return r.Method == "PRI" && len(r.Header) == 0 && r.URL.Path == "*" && r.Proto == "HTTP/2.0"
   397	}
   398	
   399	// Return value if nonempty, def otherwise.
   400	func valueOrDefault(value, def string) string {
   401		if value != "" {
   402			return value
   403		}
   404		return def
   405	}
   406	
   407	// NOTE: This is not intended to reflect the actual Go version being used.
   408	// It was changed at the time of Go 1.1 release because the former User-Agent
   409	// had ended up on a blacklist for some intrusion detection systems.
   410	// See https://codereview.appspot.com/7532043.
   411	const defaultUserAgent = "Go-http-client/1.1"
   412	
   413	// Write writes an HTTP/1.1 request, which is the header and body, in wire format.
   414	// This method consults the following fields of the request:
   415	//	Host
   416	//	URL
   417	//	Method (defaults to "GET")
   418	//	Header
   419	//	ContentLength
   420	//	TransferEncoding
   421	//	Body
   422	//
   423	// If Body is present, Content-Length is <= 0 and TransferEncoding
   424	// hasn't been set to "identity", Write adds "Transfer-Encoding:
   425	// chunked" to the header. Body is closed after it is sent.
   426	func (r *Request) Write(w io.Writer) error {
   427		return r.write(w, false, nil, nil)
   428	}
   429	
   430	// WriteProxy is like Write but writes the request in the form
   431	// expected by an HTTP proxy. In particular, WriteProxy writes the
   432	// initial Request-URI line of the request with an absolute URI, per
   433	// section 5.1.2 of RFC 2616, including the scheme and host.
   434	// In either case, WriteProxy also writes a Host header, using
   435	// either r.Host or r.URL.Host.
   436	func (r *Request) WriteProxy(w io.Writer) error {
   437		return r.write(w, true, nil, nil)
   438	}
   439	
   440	// errMissingHost is returned by Write when there is no Host or URL present in
   441	// the Request.
   442	var errMissingHost = errors.New("http: Request.Write on Request with no Host or URL set")
   443	
   444	// extraHeaders may be nil
   445	// waitForContinue may be nil
   446	func (req *Request) write(w io.Writer, usingProxy bool, extraHeaders Header, waitForContinue func() bool) (err error) {
   447		trace := httptrace.ContextClientTrace(req.Context())
   448		if trace != nil && trace.WroteRequest != nil {
   449			defer func() {
   450				trace.WroteRequest(httptrace.WroteRequestInfo{
   451					Err: err,
   452				})
   453			}()
   454		}
   455	
   456		// Find the target host. Prefer the Host: header, but if that
   457		// is not given, use the host from the request URL.
   458		//
   459		// Clean the host, in case it arrives with unexpected stuff in it.
   460		host := cleanHost(req.Host)
   461		if host == "" {
   462			if req.URL == nil {
   463				return errMissingHost
   464			}
   465			host = cleanHost(req.URL.Host)
   466		}
   467	
   468		// According to RFC 6874, an HTTP client, proxy, or other
   469		// intermediary must remove any IPv6 zone identifier attached
   470		// to an outgoing URI.
   471		host = removeZone(host)
   472	
   473		ruri := req.URL.RequestURI()
   474		if usingProxy && req.URL.Scheme != "" && req.URL.Opaque == "" {
   475			ruri = req.URL.Scheme + "://" + host + ruri
   476		} else if req.Method == "CONNECT" && req.URL.Path == "" {
   477			// CONNECT requests normally give just the host and port, not a full URL.
   478			ruri = host
   479		}
   480		// TODO(bradfitz): escape at least newlines in ruri?
   481	
   482		// Wrap the writer in a bufio Writer if it's not already buffered.
   483		// Don't always call NewWriter, as that forces a bytes.Buffer
   484		// and other small bufio Writers to have a minimum 4k buffer
   485		// size.
   486		var bw *bufio.Writer
   487		if _, ok := w.(io.ByteWriter); !ok {
   488			bw = bufio.NewWriter(w)
   489			w = bw
   490		}
   491	
   492		_, err = fmt.Fprintf(w, "%s %s HTTP/1.1\r\n", valueOrDefault(req.Method, "GET"), ruri)
   493		if err != nil {
   494			return err
   495		}
   496	
   497		// Header lines
   498		_, err = fmt.Fprintf(w, "Host: %s\r\n", host)
   499		if err != nil {
   500			return err
   501		}
   502	
   503		// Use the defaultUserAgent unless the Header contains one, which
   504		// may be blank to not send the header.
   505		userAgent := defaultUserAgent
   506		if _, ok := req.Header["User-Agent"]; ok {
   507			userAgent = req.Header.Get("User-Agent")
   508		}
   509		if userAgent != "" {
   510			_, err = fmt.Fprintf(w, "User-Agent: %s\r\n", userAgent)
   511			if err != nil {
   512				return err
   513			}
   514		}
   515	
   516		// Process Body,ContentLength,Close,Trailer
   517		tw, err := newTransferWriter(req)
   518		if err != nil {
   519			return err
   520		}
   521		err = tw.WriteHeader(w)
   522		if err != nil {
   523			return err
   524		}
   525	
   526		err = req.Header.WriteSubset(w, reqWriteExcludeHeader)
   527		if err != nil {
   528			return err
   529		}
   530	
   531		if extraHeaders != nil {
   532			err = extraHeaders.Write(w)
   533			if err != nil {
   534				return err
   535			}
   536		}
   537	
   538		_, err = io.WriteString(w, "\r\n")
   539		if err != nil {
   540			return err
   541		}
   542	
   543		if trace != nil && trace.WroteHeaders != nil {
   544			trace.WroteHeaders()
   545		}
   546	
   547		// Flush and wait for 100-continue if expected.
   548		if waitForContinue != nil {
   549			if bw, ok := w.(*bufio.Writer); ok {
   550				err = bw.Flush()
   551				if err != nil {
   552					return err
   553				}
   554			}
   555			if trace != nil && trace.Wait100Continue != nil {
   556				trace.Wait100Continue()
   557			}
   558			if !waitForContinue() {
   559				req.closeBody()
   560				return nil
   561			}
   562		}
   563	
   564		// Write body and trailer
   565		err = tw.WriteBody(w)
   566		if err != nil {
   567			return err
   568		}
   569	
   570		if bw != nil {
   571			return bw.Flush()
   572		}
   573		return nil
   574	}
   575	
   576	// cleanHost strips anything after '/' or ' '.
   577	// Ideally we'd clean the Host header according to the spec:
   578	//   https://tools.ietf.org/html/rfc7230#section-5.4 (Host = uri-host [ ":" port ]")
   579	//   https://tools.ietf.org/html/rfc7230#section-2.7 (uri-host -> rfc3986's host)
   580	//   https://tools.ietf.org/html/rfc3986#section-3.2.2 (definition of host)
   581	// But practically, what we are trying to avoid is the situation in
   582	// issue 11206, where a malformed Host header used in the proxy context
   583	// would create a bad request. So it is enough to just truncate at the
   584	// first offending character.
   585	func cleanHost(in string) string {
   586		if i := strings.IndexAny(in, " /"); i != -1 {
   587			return in[:i]
   588		}
   589		return in
   590	}
   591	
   592	// removeZone removes IPv6 zone identifier from host.
   593	// E.g., "[fe80::1%en0]:8080" to "[fe80::1]:8080"
   594	func removeZone(host string) string {
   595		if !strings.HasPrefix(host, "[") {
   596			return host
   597		}
   598		i := strings.LastIndex(host, "]")
   599		if i < 0 {
   600			return host
   601		}
   602		j := strings.LastIndex(host[:i], "%")
   603		if j < 0 {
   604			return host
   605		}
   606		return host[:j] + host[i:]
   607	}
   608	
   609	// ParseHTTPVersion parses a HTTP version string.
   610	// "HTTP/1.0" returns (1, 0, true).
   611	func ParseHTTPVersion(vers string) (major, minor int, ok bool) {
   612		const Big = 1000000 // arbitrary upper bound
   613		switch vers {
   614		case "HTTP/1.1":
   615			return 1, 1, true
   616		case "HTTP/1.0":
   617			return 1, 0, true
   618		}
   619		if !strings.HasPrefix(vers, "HTTP/") {
   620			return 0, 0, false
   621		}
   622		dot := strings.Index(vers, ".")
   623		if dot < 0 {
   624			return 0, 0, false
   625		}
   626		major, err := strconv.Atoi(vers[5:dot])
   627		if err != nil || major < 0 || major > Big {
   628			return 0, 0, false
   629		}
   630		minor, err = strconv.Atoi(vers[dot+1:])
   631		if err != nil || minor < 0 || minor > Big {
   632			return 0, 0, false
   633		}
   634		return major, minor, true
   635	}
   636	
   637	func validMethod(method string) bool {
   638		/*
   639		     Method         = "OPTIONS"                ; Section 9.2
   640		                    | "GET"                    ; Section 9.3
   641		                    | "HEAD"                   ; Section 9.4
   642		                    | "POST"                   ; Section 9.5
   643		                    | "PUT"                    ; Section 9.6
   644		                    | "DELETE"                 ; Section 9.7
   645		                    | "TRACE"                  ; Section 9.8
   646		                    | "CONNECT"                ; Section 9.9
   647		                    | extension-method
   648		   extension-method = token
   649		     token          = 1*<any CHAR except CTLs or separators>
   650		*/
   651		return len(method) > 0 && strings.IndexFunc(method, isNotToken) == -1
   652	}
   653	
   654	// NewRequest returns a new Request given a method, URL, and optional body.
   655	//
   656	// If the provided body is also an io.Closer, the returned
   657	// Request.Body is set to body and will be closed by the Client
   658	// methods Do, Post, and PostForm, and Transport.RoundTrip.
   659	//
   660	// NewRequest returns a Request suitable for use with Client.Do or
   661	// Transport.RoundTrip.
   662	// To create a request for use with testing a Server Handler use either
   663	// ReadRequest or manually update the Request fields. See the Request
   664	// type's documentation for the difference between inbound and outbound
   665	// request fields.
   666	func NewRequest(method, urlStr string, body io.Reader) (*Request, error) {
   667		if method == "" {
   668			// We document that "" means "GET" for Request.Method, and people have
   669			// relied on that from NewRequest, so keep that working.
   670			// We still enforce validMethod for non-empty methods.
   671			method = "GET"
   672		}
   673		if !validMethod(method) {
   674			return nil, fmt.Errorf("net/http: invalid method %q", method)
   675		}
   676		u, err := url.Parse(urlStr)
   677		if err != nil {
   678			return nil, err
   679		}
   680		rc, ok := body.(io.ReadCloser)
   681		if !ok && body != nil {
   682			rc = ioutil.NopCloser(body)
   683		}
   684		// The host's colon:port should be normalized. See Issue 14836.
   685		u.Host = removeEmptyPort(u.Host)
   686		req := &Request{
   687			Method:     method,
   688			URL:        u,
   689			Proto:      "HTTP/1.1",
   690			ProtoMajor: 1,
   691			ProtoMinor: 1,
   692			Header:     make(Header),
   693			Body:       rc,
   694			Host:       u.Host,
   695		}
   696		if body != nil {
   697			switch v := body.(type) {
   698			case *bytes.Buffer:
   699				req.ContentLength = int64(v.Len())
   700			case *bytes.Reader:
   701				req.ContentLength = int64(v.Len())
   702			case *strings.Reader:
   703				req.ContentLength = int64(v.Len())
   704			}
   705		}
   706	
   707		return req, nil
   708	}
   709	
   710	// BasicAuth returns the username and password provided in the request's
   711	// Authorization header, if the request uses HTTP Basic Authentication.
   712	// See RFC 2617, Section 2.
   713	func (r *Request) BasicAuth() (username, password string, ok bool) {
   714		auth := r.Header.Get("Authorization")
   715		if auth == "" {
   716			return
   717		}
   718		return parseBasicAuth(auth)
   719	}
   720	
   721	// parseBasicAuth parses an HTTP Basic Authentication string.
   722	// "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" returns ("Aladdin", "open sesame", true).
   723	func parseBasicAuth(auth string) (username, password string, ok bool) {
   724		const prefix = "Basic "
   725		if !strings.HasPrefix(auth, prefix) {
   726			return
   727		}
   728		c, err := base64.StdEncoding.DecodeString(auth[len(prefix):])
   729		if err != nil {
   730			return
   731		}
   732		cs := string(c)
   733		s := strings.IndexByte(cs, ':')
   734		if s < 0 {
   735			return
   736		}
   737		return cs[:s], cs[s+1:], true
   738	}
   739	
   740	// SetBasicAuth sets the request's Authorization header to use HTTP
   741	// Basic Authentication with the provided username and password.
   742	//
   743	// With HTTP Basic Authentication the provided username and password
   744	// are not encrypted.
   745	func (r *Request) SetBasicAuth(username, password string) {
   746		r.Header.Set("Authorization", "Basic "+basicAuth(username, password))
   747	}
   748	
   749	// parseRequestLine parses "GET /foo HTTP/1.1" into its three parts.
   750	func parseRequestLine(line string) (method, requestURI, proto string, ok bool) {
   751		s1 := strings.Index(line, " ")
   752		s2 := strings.Index(line[s1+1:], " ")
   753		if s1 < 0 || s2 < 0 {
   754			return
   755		}
   756		s2 += s1 + 1
   757		return line[:s1], line[s1+1 : s2], line[s2+1:], true
   758	}
   759	
   760	var textprotoReaderPool sync.Pool
   761	
   762	func newTextprotoReader(br *bufio.Reader) *textproto.Reader {
   763		if v := textprotoReaderPool.Get(); v != nil {
   764			tr := v.(*textproto.Reader)
   765			tr.R = br
   766			return tr
   767		}
   768		return textproto.NewReader(br)
   769	}
   770	
   771	func putTextprotoReader(r *textproto.Reader) {
   772		r.R = nil
   773		textprotoReaderPool.Put(r)
   774	}
   775	
   776	// ReadRequest reads and parses an incoming request from b.
   777	func ReadRequest(b *bufio.Reader) (*Request, error) {
   778		return readRequest(b, deleteHostHeader)
   779	}
   780	
   781	// Constants for readRequest's deleteHostHeader parameter.
   782	const (
   783		deleteHostHeader = true
   784		keepHostHeader   = false
   785	)
   786	
   787	func readRequest(b *bufio.Reader, deleteHostHeader bool) (req *Request, err error) {
   788		tp := newTextprotoReader(b)
   789		req = new(Request)
   790	
   791		// First line: GET /index.html HTTP/1.0
   792		var s string
   793		if s, err = tp.ReadLine(); err != nil {
   794			return nil, err
   795		}
   796		defer func() {
   797			putTextprotoReader(tp)
   798			if err == io.EOF {
   799				err = io.ErrUnexpectedEOF
   800			}
   801		}()
   802	
   803		var ok bool
   804		req.Method, req.RequestURI, req.Proto, ok = parseRequestLine(s)
   805		if !ok {
   806			return nil, &badStringError{"malformed HTTP request", s}
   807		}
   808		rawurl := req.RequestURI
   809		if req.ProtoMajor, req.ProtoMinor, ok = ParseHTTPVersion(req.Proto); !ok {
   810			return nil, &badStringError{"malformed HTTP version", req.Proto}
   811		}
   812	
   813		// CONNECT requests are used two different ways, and neither uses a full URL:
   814		// The standard use is to tunnel HTTPS through an HTTP proxy.
   815		// It looks like "CONNECT www.google.com:443 HTTP/1.1", and the parameter is
   816		// just the authority section of a URL. This information should go in req.URL.Host.
   817		//
   818		// The net/rpc package also uses CONNECT, but there the parameter is a path
   819		// that starts with a slash. It can be parsed with the regular URL parser,
   820		// and the path will end up in req.URL.Path, where it needs to be in order for
   821		// RPC to work.
   822		justAuthority := req.Method == "CONNECT" && !strings.HasPrefix(rawurl, "/")
   823		if justAuthority {
   824			rawurl = "http://" + rawurl
   825		}
   826	
   827		if req.URL, err = url.ParseRequestURI(rawurl); err != nil {
   828			return nil, err
   829		}
   830	
   831		if justAuthority {
   832			// Strip the bogus "http://" back off.
   833			req.URL.Scheme = ""
   834		}
   835	
   836		// Subsequent lines: Key: value.
   837		mimeHeader, err := tp.ReadMIMEHeader()
   838		if err != nil {
   839			return nil, err
   840		}
   841		req.Header = Header(mimeHeader)
   842	
   843		// RFC 2616: Must treat
   844		//	GET /index.html HTTP/1.1
   845		//	Host: www.google.com
   846		// and
   847		//	GET http://www.google.com/index.html HTTP/1.1
   848		//	Host: doesntmatter
   849		// the same. In the second case, any Host line is ignored.
   850		req.Host = req.URL.Host
   851		if req.Host == "" {
   852			req.Host = req.Header.get("Host")
   853		}
   854		if deleteHostHeader {
   855			delete(req.Header, "Host")
   856		}
   857	
   858		fixPragmaCacheControl(req.Header)
   859	
   860		req.Close = shouldClose(req.ProtoMajor, req.ProtoMinor, req.Header, false)
   861	
   862		err = readTransfer(req, b)
   863		if err != nil {
   864			return nil, err
   865		}
   866	
   867		if req.isH2Upgrade() {
   868			// Because it's neither chunked, nor declared:
   869			req.ContentLength = -1
   870	
   871			// We want to give handlers a chance to hijack the
   872			// connection, but we need to prevent the Server from
   873			// dealing with the connection further if it's not
   874			// hijacked. Set Close to ensure that:
   875			req.Close = true
   876		}
   877		return req, nil
   878	}
   879	
   880	// MaxBytesReader is similar to io.LimitReader but is intended for
   881	// limiting the size of incoming request bodies. In contrast to
   882	// io.LimitReader, MaxBytesReader's result is a ReadCloser, returns a
   883	// non-EOF error for a Read beyond the limit, and closes the
   884	// underlying reader when its Close method is called.
   885	//
   886	// MaxBytesReader prevents clients from accidentally or maliciously
   887	// sending a large request and wasting server resources.
   888	func MaxBytesReader(w ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser {
   889		return &maxBytesReader{w: w, r: r, n: n}
   890	}
   891	
   892	type maxBytesReader struct {
   893		w   ResponseWriter
   894		r   io.ReadCloser // underlying reader
   895		n   int64         // max bytes remaining
   896		err error         // sticky error
   897	}
   898	
   899	func (l *maxBytesReader) tooLarge() (n int, err error) {
   900		l.err = errors.New("http: request body too large")
   901		return 0, l.err
   902	}
   903	
   904	func (l *maxBytesReader) Read(p []byte) (n int, err error) {
   905		if l.err != nil {
   906			return 0, l.err
   907		}
   908		if len(p) == 0 {
   909			return 0, nil
   910		}
   911		// If they asked for a 32KB byte read but only 5 bytes are
   912		// remaining, no need to read 32KB. 6 bytes will answer the
   913		// question of the whether we hit the limit or go past it.
   914		if int64(len(p)) > l.n+1 {
   915			p = p[:l.n+1]
   916		}
   917		n, err = l.r.Read(p)
   918	
   919		if int64(n) <= l.n {
   920			l.n -= int64(n)
   921			l.err = err
   922			return n, err
   923		}
   924	
   925		n = int(l.n)
   926		l.n = 0
   927	
   928		// The server code and client code both use
   929		// maxBytesReader. This "requestTooLarge" check is
   930		// only used by the server code. To prevent binaries
   931		// which only using the HTTP Client code (such as
   932		// cmd/go) from also linking in the HTTP server, don't
   933		// use a static type assertion to the server
   934		// "*response" type. Check this interface instead:
   935		type requestTooLarger interface {
   936			requestTooLarge()
   937		}
   938		if res, ok := l.w.(requestTooLarger); ok {
   939			res.requestTooLarge()
   940		}
   941		l.err = errors.New("http: request body too large")
   942		return n, l.err
   943	}
   944	
   945	func (l *maxBytesReader) Close() error {
   946		return l.r.Close()
   947	}
   948	
   949	func copyValues(dst, src url.Values) {
   950		for k, vs := range src {
   951			for _, value := range vs {
   952				dst.Add(k, value)
   953			}
   954		}
   955	}
   956	
   957	func parsePostForm(r *Request) (vs url.Values, err error) {
   958		if r.Body == nil {
   959			err = errors.New("missing form body")
   960			return
   961		}
   962		ct := r.Header.Get("Content-Type")
   963		// RFC 2616, section 7.2.1 - empty type
   964		//   SHOULD be treated as application/octet-stream
   965		if ct == "" {
   966			ct = "application/octet-stream"
   967		}
   968		ct, _, err = mime.ParseMediaType(ct)
   969		switch {
   970		case ct == "application/x-www-form-urlencoded":
   971			var reader io.Reader = r.Body
   972			maxFormSize := int64(1<<63 - 1)
   973			if _, ok := r.Body.(*maxBytesReader); !ok {
   974				maxFormSize = int64(10 << 20) // 10 MB is a lot of text.
   975				reader = io.LimitReader(r.Body, maxFormSize+1)
   976			}
   977			b, e := ioutil.ReadAll(reader)
   978			if e != nil {
   979				if err == nil {
   980					err = e
   981				}
   982				break
   983			}
   984			if int64(len(b)) > maxFormSize {
   985				err = errors.New("http: POST too large")
   986				return
   987			}
   988			vs, e = url.ParseQuery(string(b))
   989			if err == nil {
   990				err = e
   991			}
   992		case ct == "multipart/form-data":
   993			// handled by ParseMultipartForm (which is calling us, or should be)
   994			// TODO(bradfitz): there are too many possible
   995			// orders to call too many functions here.
   996			// Clean this up and write more tests.
   997			// request_test.go contains the start of this,
   998			// in TestParseMultipartFormOrder and others.
   999		}
  1000		return
  1001	}
  1002	
  1003	// ParseForm parses the raw query from the URL and updates r.Form.
  1004	//
  1005	// For POST or PUT requests, it also parses the request body as a form and
  1006	// put the results into both r.PostForm and r.Form.
  1007	// POST and PUT body parameters take precedence over URL query string values
  1008	// in r.Form.
  1009	//
  1010	// If the request Body's size has not already been limited by MaxBytesReader,
  1011	// the size is capped at 10MB.
  1012	//
  1013	// ParseMultipartForm calls ParseForm automatically.
  1014	// It is idempotent.
  1015	func (r *Request) ParseForm() error {
  1016		var err error
  1017		if r.PostForm == nil {
  1018			if r.Method == "POST" || r.Method == "PUT" || r.Method == "PATCH" {
  1019				r.PostForm, err = parsePostForm(r)
  1020			}
  1021			if r.PostForm == nil {
  1022				r.PostForm = make(url.Values)
  1023			}
  1024		}
  1025		if r.Form == nil {
  1026			if len(r.PostForm) > 0 {
  1027				r.Form = make(url.Values)
  1028				copyValues(r.Form, r.PostForm)
  1029			}
  1030			var newValues url.Values
  1031			if r.URL != nil {
  1032				var e error
  1033				newValues, e = url.ParseQuery(r.URL.RawQuery)
  1034				if err == nil {
  1035					err = e
  1036				}
  1037			}
  1038			if newValues == nil {
  1039				newValues = make(url.Values)
  1040			}
  1041			if r.Form == nil {
  1042				r.Form = newValues
  1043			} else {
  1044				copyValues(r.Form, newValues)
  1045			}
  1046		}
  1047		return err
  1048	}
  1049	
  1050	// ParseMultipartForm parses a request body as multipart/form-data.
  1051	// The whole request body is parsed and up to a total of maxMemory bytes of
  1052	// its file parts are stored in memory, with the remainder stored on
  1053	// disk in temporary files.
  1054	// ParseMultipartForm calls ParseForm if necessary.
  1055	// After one call to ParseMultipartForm, subsequent calls have no effect.
  1056	func (r *Request) ParseMultipartForm(maxMemory int64) error {
  1057		if r.MultipartForm == multipartByReader {
  1058			return errors.New("http: multipart handled by MultipartReader")
  1059		}
  1060		if r.Form == nil {
  1061			err := r.ParseForm()
  1062			if err != nil {
  1063				return err
  1064			}
  1065		}
  1066		if r.MultipartForm != nil {
  1067			return nil
  1068		}
  1069	
  1070		mr, err := r.multipartReader()
  1071		if err != nil {
  1072			return err
  1073		}
  1074	
  1075		f, err := mr.ReadForm(maxMemory)
  1076		if err != nil {
  1077			return err
  1078		}
  1079	
  1080		if r.PostForm == nil {
  1081			r.PostForm = make(url.Values)
  1082		}
  1083		for k, v := range f.Value {
  1084			r.Form[k] = append(r.Form[k], v...)
  1085			// r.PostForm should also be populated. See Issue 9305.
  1086			r.PostForm[k] = append(r.PostForm[k], v...)
  1087		}
  1088	
  1089		r.MultipartForm = f
  1090	
  1091		return nil
  1092	}
  1093	
  1094	// FormValue returns the first value for the named component of the query.
  1095	// POST and PUT body parameters take precedence over URL query string values.
  1096	// FormValue calls ParseMultipartForm and ParseForm if necessary and ignores
  1097	// any errors returned by these functions.
  1098	// If key is not present, FormValue returns the empty string.
  1099	// To access multiple values of the same key, call ParseForm and
  1100	// then inspect Request.Form directly.
  1101	func (r *Request) FormValue(key string) string {
  1102		if r.Form == nil {
  1103			r.ParseMultipartForm(defaultMaxMemory)
  1104		}
  1105		if vs := r.Form[key]; len(vs) > 0 {
  1106			return vs[0]
  1107		}
  1108		return ""
  1109	}
  1110	
  1111	// PostFormValue returns the first value for the named component of the POST
  1112	// or PUT request body. URL query parameters are ignored.
  1113	// PostFormValue calls ParseMultipartForm and ParseForm if necessary and ignores
  1114	// any errors returned by these functions.
  1115	// If key is not present, PostFormValue returns the empty string.
  1116	func (r *Request) PostFormValue(key string) string {
  1117		if r.PostForm == nil {
  1118			r.ParseMultipartForm(defaultMaxMemory)
  1119		}
  1120		if vs := r.PostForm[key]; len(vs) > 0 {
  1121			return vs[0]
  1122		}
  1123		return ""
  1124	}
  1125	
  1126	// FormFile returns the first file for the provided form key.
  1127	// FormFile calls ParseMultipartForm and ParseForm if necessary.
  1128	func (r *Request) FormFile(key string) (multipart.File, *multipart.FileHeader, error) {
  1129		if r.MultipartForm == multipartByReader {
  1130			return nil, nil, errors.New("http: multipart handled by MultipartReader")
  1131		}
  1132		if r.MultipartForm == nil {
  1133			err := r.ParseMultipartForm(defaultMaxMemory)
  1134			if err != nil {
  1135				return nil, nil, err
  1136			}
  1137		}
  1138		if r.MultipartForm != nil && r.MultipartForm.File != nil {
  1139			if fhs := r.MultipartForm.File[key]; len(fhs) > 0 {
  1140				f, err := fhs[0].Open()
  1141				return f, fhs[0], err
  1142			}
  1143		}
  1144		return nil, nil, ErrMissingFile
  1145	}
  1146	
  1147	func (r *Request) expectsContinue() bool {
  1148		return hasToken(r.Header.get("Expect"), "100-continue")
  1149	}
  1150	
  1151	func (r *Request) wantsHttp10KeepAlive() bool {
  1152		if r.ProtoMajor != 1 || r.ProtoMinor != 0 {
  1153			return false
  1154		}
  1155		return hasToken(r.Header.get("Connection"), "keep-alive")
  1156	}
  1157	
  1158	func (r *Request) wantsClose() bool {
  1159		return hasToken(r.Header.get("Connection"), "close")
  1160	}
  1161	
  1162	func (r *Request) closeBody() {
  1163		if r.Body != nil {
  1164			r.Body.Close()
  1165		}
  1166	}
  1167	
  1168	func (r *Request) isReplayable() bool {
  1169		if r.Body == nil {
  1170			switch valueOrDefault(r.Method, "GET") {
  1171			case "GET", "HEAD", "OPTIONS", "TRACE":
  1172				return true
  1173			}
  1174		}
  1175		return false
  1176	}
  1177	

View as plain text