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.
5 // HTTP Request reading and parsing.
29 "golang_org/x/net/idna"
33 defaultMaxMemory
= 32 << 20 // 32 MB
36 // ErrMissingFile is returned by FormFile when the provided file field name
37 // is either not present in the request or not a file field.
38 var ErrMissingFile
= errors
.New("http: no such file")
40 // ProtocolError represents an HTTP protocol error.
42 // Deprecated: Not all errors in the http package related to protocol errors
43 // are of type ProtocolError.
44 type ProtocolError
struct {
48 func (pe
*ProtocolError
) Error() string { return pe
.ErrorString
}
51 // ErrNotSupported is returned by the Push method of Pusher
52 // implementations to indicate that HTTP/2 Push support is not
54 ErrNotSupported
= &ProtocolError
{"feature not supported"}
56 // ErrUnexpectedTrailer is returned by the Transport when a server
57 // replies with a Trailer header, but without a chunked reply.
58 ErrUnexpectedTrailer
= &ProtocolError
{"trailer header without chunked transfer encoding"}
60 // ErrMissingBoundary is returned by Request.MultipartReader when the
61 // request's Content-Type does not include a "boundary" parameter.
62 ErrMissingBoundary
= &ProtocolError
{"no multipart boundary param in Content-Type"}
64 // ErrNotMultipart is returned by Request.MultipartReader when the
65 // request's Content-Type is not multipart/form-data.
66 ErrNotMultipart
= &ProtocolError
{"request Content-Type isn't multipart/form-data"}
68 // Deprecated: ErrHeaderTooLong is no longer returned by
69 // anything in the net/http package. Callers should not
70 // compare errors against this variable.
71 ErrHeaderTooLong
= &ProtocolError
{"header too long"}
73 // Deprecated: ErrShortBody is no longer returned by
74 // anything in the net/http package. Callers should not
75 // compare errors against this variable.
76 ErrShortBody
= &ProtocolError
{"entity body too short"}
78 // Deprecated: ErrMissingContentLength is no longer returned by
79 // anything in the net/http package. Callers should not
80 // compare errors against this variable.
81 ErrMissingContentLength
= &ProtocolError
{"missing ContentLength in HEAD response"}
84 type badStringError
struct {
89 func (e
*badStringError
) Error() string { return fmt
.Sprintf("%s %q", e
.what
, e
.str
) }
91 // Headers that Request.Write handles itself and should be skipped.
92 var reqWriteExcludeHeader
= map[string]bool{
93 "Host": true, // not in Header map anyway
95 "Content-Length": true,
96 "Transfer-Encoding": true,
100 // A Request represents an HTTP request received by a server
101 // or to be sent by a client.
103 // The field semantics differ slightly between client and server
104 // usage. In addition to the notes on the fields below, see the
105 // documentation for Request.Write and RoundTripper.
106 type Request
struct {
107 // Method specifies the HTTP method (GET, POST, PUT, etc.).
108 // For client requests an empty string means GET.
110 // Go's HTTP client does not support sending a request with
111 // the CONNECT method. See the documentation on Transport for
115 // URL specifies either the URI being requested (for server
116 // requests) or the URL to access (for client requests).
118 // For server requests the URL is parsed from the URI
119 // supplied on the Request-Line as stored in RequestURI. For
120 // most requests, fields other than Path and RawQuery will be
121 // empty. (See RFC 7230, Section 5.3)
123 // For client requests, the URL's Host specifies the server to
124 // connect to, while the Request's Host field optionally
125 // specifies the Host header value to send in the HTTP
129 // The protocol version for incoming server requests.
131 // For client requests these fields are ignored. The HTTP
132 // client code always uses either HTTP/1.1 or HTTP/2.
133 // See the docs on Transport for details.
134 Proto
string // "HTTP/1.0"
138 // Header contains the request header fields either received
139 // by the server or to be sent by the client.
141 // If a server received a request with header lines,
144 // accept-encoding: gzip, deflate
145 // Accept-Language: en-us
151 // Header = map[string][]string{
152 // "Accept-Encoding": {"gzip, deflate"},
153 // "Accept-Language": {"en-us"},
154 // "Foo": {"Bar", "two"},
157 // For incoming requests, the Host header is promoted to the
158 // Request.Host field and removed from the Header map.
160 // HTTP defines that header names are case-insensitive. The
161 // request parser implements this by using CanonicalHeaderKey,
162 // making the first character and any characters following a
163 // hyphen uppercase and the rest lowercase.
165 // For client requests, certain headers such as Content-Length
166 // and Connection are automatically written when needed and
167 // values in Header may be ignored. See the documentation
168 // for the Request.Write method.
171 // Body is the request's body.
173 // For client requests a nil body means the request has no
174 // body, such as a GET request. The HTTP Client's Transport
175 // is responsible for calling the Close method.
177 // For server requests the Request Body is always non-nil
178 // but will return EOF immediately when no body is present.
179 // The Server will close the request body. The ServeHTTP
180 // Handler does not need to.
183 // GetBody defines an optional func to return a new copy of
184 // Body. It is used for client requests when a redirect requires
185 // reading the body more than once. Use of GetBody still
186 // requires setting Body.
188 // For server requests it is unused.
189 GetBody
func() (io
.ReadCloser
, error
)
191 // ContentLength records the length of the associated content.
192 // The value -1 indicates that the length is unknown.
193 // Values >= 0 indicate that the given number of bytes may
194 // be read from Body.
195 // For client requests, a value of 0 with a non-nil Body is
196 // also treated as unknown.
199 // TransferEncoding lists the transfer encodings from outermost to
200 // innermost. An empty list denotes the "identity" encoding.
201 // TransferEncoding can usually be ignored; chunked encoding is
202 // automatically added and removed as necessary when sending and
203 // receiving requests.
204 TransferEncoding
[]string
206 // Close indicates whether to close the connection after
207 // replying to this request (for servers) or after sending this
208 // request and reading its response (for clients).
210 // For server requests, the HTTP server handles this automatically
211 // and this field is not needed by Handlers.
213 // For client requests, setting this field prevents re-use of
214 // TCP connections between requests to the same hosts, as if
215 // Transport.DisableKeepAlives were set.
218 // For server requests Host specifies the host on which the URL
219 // is sought. Per RFC 7230, section 5.4, this is either the value
220 // of the "Host" header or the host name given in the URL itself.
221 // It may be of the form "host:port". For international domain
222 // names, Host may be in Punycode or Unicode form. Use
223 // golang.org/x/net/idna to convert it to either format if
225 // To prevent DNS rebinding attacks, server Handlers should
226 // validate that the Host header has a value for which the
227 // Handler considers itself authoritative. The included
228 // ServeMux supports patterns registered to particular host
229 // names and thus protects its registered Handlers.
231 // For client requests Host optionally overrides the Host
232 // header to send. If empty, the Request.Write method uses
233 // the value of URL.Host. Host may contain an international
237 // Form contains the parsed form data, including both the URL
238 // field's query parameters and the POST or PUT form data.
239 // This field is only available after ParseForm is called.
240 // The HTTP client ignores Form and uses Body instead.
243 // PostForm contains the parsed form data from POST, PATCH,
244 // or PUT body parameters.
246 // This field is only available after ParseForm is called.
247 // The HTTP client ignores PostForm and uses Body instead.
250 // MultipartForm is the parsed multipart form, including file uploads.
251 // This field is only available after ParseMultipartForm is called.
252 // The HTTP client ignores MultipartForm and uses Body instead.
253 MultipartForm
*multipart
.Form
255 // Trailer specifies additional headers that are sent after the request
258 // For server requests the Trailer map initially contains only the
259 // trailer keys, with nil values. (The client declares which trailers it
260 // will later send.) While the handler is reading from Body, it must
261 // not reference Trailer. After reading from Body returns EOF, Trailer
262 // can be read again and will contain non-nil values, if they were sent
265 // For client requests Trailer must be initialized to a map containing
266 // the trailer keys to later send. The values may be nil or their final
267 // values. The ContentLength must be 0 or -1, to send a chunked request.
268 // After the HTTP request is sent the map values can be updated while
269 // the request body is read. Once the body returns EOF, the caller must
270 // not mutate Trailer.
272 // Few HTTP clients, servers, or proxies support HTTP trailers.
275 // RemoteAddr allows HTTP servers and other software to record
276 // the network address that sent the request, usually for
277 // logging. This field is not filled in by ReadRequest and
278 // has no defined format. The HTTP server in this package
279 // sets RemoteAddr to an "IP:port" address before invoking a
281 // This field is ignored by the HTTP client.
284 // RequestURI is the unmodified request-target of the
285 // Request-Line (RFC 7230, Section 3.1.1) as sent by the client
286 // to a server. Usually the URL field should be used instead.
287 // It is an error to set this field in an HTTP client request.
290 // TLS allows HTTP servers and other software to record
291 // information about the TLS connection on which the request
292 // was received. This field is not filled in by ReadRequest.
293 // The HTTP server in this package sets the field for
294 // TLS-enabled connections before invoking a handler;
295 // otherwise it leaves the field nil.
296 // This field is ignored by the HTTP client.
297 TLS
*tls
.ConnectionState
299 // Cancel is an optional channel whose closure indicates that the client
300 // request should be regarded as canceled. Not all implementations of
301 // RoundTripper may support Cancel.
303 // For server requests, this field is not applicable.
305 // Deprecated: Use the Context and WithContext methods
306 // instead. If a Request's Cancel field and context are both
307 // set, it is undefined whether Cancel is respected.
308 Cancel
<-chan struct{}
310 // Response is the redirect response which caused this request
311 // to be created. This field is only populated during client
315 // ctx is either the client or server context. It should only
316 // be modified via copying the whole Request using WithContext.
317 // It is unexported to prevent people from using Context wrong
318 // and mutating the contexts held by callers of the same request.
322 // Context returns the request's context. To change the context, use
325 // The returned context is always non-nil; it defaults to the
326 // background context.
328 // For outgoing client requests, the context controls cancelation.
330 // For incoming server requests, the context is canceled when the
331 // client's connection closes, the request is canceled (with HTTP/2),
332 // or when the ServeHTTP method returns.
333 func (r
*Request
) Context() context
.Context
{
337 return context
.Background()
340 // WithContext returns a shallow copy of r with its context changed
341 // to ctx. The provided ctx must be non-nil.
343 // For outgoing client request, the context controls the entire
344 // lifetime of a request and its response: obtaining a connection,
345 // sending the request, and reading the response headers and body.
346 func (r
*Request
) WithContext(ctx context
.Context
) *Request
{
354 // Deep copy the URL because it isn't
355 // a map and the URL is mutable by users
358 r2URL
:= new(url
.URL
)
366 // ProtoAtLeast reports whether the HTTP protocol used
367 // in the request is at least major.minor.
368 func (r
*Request
) ProtoAtLeast(major
, minor
int) bool {
369 return r
.ProtoMajor
> major ||
370 r
.ProtoMajor
== major
&& r
.ProtoMinor
>= minor
373 // UserAgent returns the client's User-Agent, if sent in the request.
374 func (r
*Request
) UserAgent() string {
375 return r
.Header
.Get("User-Agent")
378 // Cookies parses and returns the HTTP cookies sent with the request.
379 func (r
*Request
) Cookies() []*Cookie
{
380 return readCookies(r
.Header
, "")
383 // ErrNoCookie is returned by Request's Cookie method when a cookie is not found.
384 var ErrNoCookie
= errors
.New("http: named cookie not present")
386 // Cookie returns the named cookie provided in the request or
387 // ErrNoCookie if not found.
388 // If multiple cookies match the given name, only one cookie will
390 func (r
*Request
) Cookie(name
string) (*Cookie
, error
) {
391 for _
, c
:= range readCookies(r
.Header
, name
) {
394 return nil, ErrNoCookie
397 // AddCookie adds a cookie to the request. Per RFC 6265 section 5.4,
398 // AddCookie does not attach more than one Cookie header field. That
399 // means all cookies, if any, are written into the same line,
400 // separated by semicolon.
401 func (r
*Request
) AddCookie(c
*Cookie
) {
402 s
:= fmt
.Sprintf("%s=%s", sanitizeCookieName(c
.Name
), sanitizeCookieValue(c
.Value
))
403 if c
:= r
.Header
.Get("Cookie"); c
!= "" {
404 r
.Header
.Set("Cookie", c
+"; "+s
)
406 r
.Header
.Set("Cookie", s
)
410 // Referer returns the referring URL, if sent in the request.
412 // Referer is misspelled as in the request itself, a mistake from the
413 // earliest days of HTTP. This value can also be fetched from the
414 // Header map as Header["Referer"]; the benefit of making it available
415 // as a method is that the compiler can diagnose programs that use the
416 // alternate (correct English) spelling req.Referrer() but cannot
417 // diagnose programs that use Header["Referrer"].
418 func (r
*Request
) Referer() string {
419 return r
.Header
.Get("Referer")
422 // multipartByReader is a sentinel value.
423 // Its presence in Request.MultipartForm indicates that parsing of the request
424 // body has been handed off to a MultipartReader instead of ParseMultipartFrom.
425 var multipartByReader
= &multipart
.Form
{
426 Value
: make(map[string][]string),
427 File
: make(map[string][]*multipart
.FileHeader
),
430 // MultipartReader returns a MIME multipart reader if this is a
431 // multipart/form-data or a multipart/mixed POST request, else returns nil and an error.
432 // Use this function instead of ParseMultipartForm to
433 // process the request body as a stream.
434 func (r
*Request
) MultipartReader() (*multipart
.Reader
, error
) {
435 if r
.MultipartForm
== multipartByReader
{
436 return nil, errors
.New("http: MultipartReader called twice")
438 if r
.MultipartForm
!= nil {
439 return nil, errors
.New("http: multipart handled by ParseMultipartForm")
441 r
.MultipartForm
= multipartByReader
442 return r
.multipartReader(true)
445 func (r
*Request
) multipartReader(allowMixed
bool) (*multipart
.Reader
, error
) {
446 v
:= r
.Header
.Get("Content-Type")
448 return nil, ErrNotMultipart
450 d
, params
, err
:= mime
.ParseMediaType(v
)
451 if err
!= nil ||
!(d
== "multipart/form-data" || allowMixed
&& d
== "multipart/mixed") {
452 return nil, ErrNotMultipart
454 boundary
, ok
:= params
["boundary"]
456 return nil, ErrMissingBoundary
458 return multipart
.NewReader(r
.Body
, boundary
), nil
461 // isH2Upgrade reports whether r represents the http2 "client preface"
463 func (r
*Request
) isH2Upgrade() bool {
464 return r
.Method
== "PRI" && len(r
.Header
) == 0 && r
.URL
.Path
== "*" && r
.Proto
== "HTTP/2.0"
467 // Return value if nonempty, def otherwise.
468 func valueOrDefault(value
, def
string) string {
475 // NOTE: This is not intended to reflect the actual Go version being used.
476 // It was changed at the time of Go 1.1 release because the former User-Agent
477 // had ended up on a blacklist for some intrusion detection systems.
478 // See https://codereview.appspot.com/7532043.
479 const defaultUserAgent
= "Go-http-client/1.1"
481 // Write writes an HTTP/1.1 request, which is the header and body, in wire format.
482 // This method consults the following fields of the request:
485 // Method (defaults to "GET")
491 // If Body is present, Content-Length is <= 0 and TransferEncoding
492 // hasn't been set to "identity", Write adds "Transfer-Encoding:
493 // chunked" to the header. Body is closed after it is sent.
494 func (r
*Request
) Write(w io
.Writer
) error
{
495 return r
.write(w
, false, nil, nil)
498 // WriteProxy is like Write but writes the request in the form
499 // expected by an HTTP proxy. In particular, WriteProxy writes the
500 // initial Request-URI line of the request with an absolute URI, per
501 // section 5.3 of RFC 7230, including the scheme and host.
502 // In either case, WriteProxy also writes a Host header, using
503 // either r.Host or r.URL.Host.
504 func (r
*Request
) WriteProxy(w io
.Writer
) error
{
505 return r
.write(w
, true, nil, nil)
508 // errMissingHost is returned by Write when there is no Host or URL present in
510 var errMissingHost
= errors
.New("http: Request.Write on Request with no Host or URL set")
512 // extraHeaders may be nil
513 // waitForContinue may be nil
514 func (r
*Request
) write(w io
.Writer
, usingProxy
bool, extraHeaders Header
, waitForContinue
func() bool) (err error
) {
515 trace
:= httptrace
.ContextClientTrace(r
.Context())
516 if trace
!= nil && trace
.WroteRequest
!= nil {
518 trace
.WroteRequest(httptrace
.WroteRequestInfo
{
524 // Find the target host. Prefer the Host: header, but if that
525 // is not given, use the host from the request URL.
527 // Clean the host, in case it arrives with unexpected stuff in it.
528 host
:= cleanHost(r
.Host
)
531 return errMissingHost
533 host
= cleanHost(r
.URL
.Host
)
536 // According to RFC 6874, an HTTP client, proxy, or other
537 // intermediary must remove any IPv6 zone identifier attached
538 // to an outgoing URI.
539 host
= removeZone(host
)
541 ruri
:= r
.URL
.RequestURI()
542 if usingProxy
&& r
.URL
.Scheme
!= "" && r
.URL
.Opaque
== "" {
543 ruri
= r
.URL
.Scheme
+ "://" + host
+ ruri
544 } else if r
.Method
== "CONNECT" && r
.URL
.Path
== "" {
545 // CONNECT requests normally give just the host and port, not a full URL.
548 // TODO(bradfitz): escape at least newlines in ruri?
550 // Wrap the writer in a bufio Writer if it's not already buffered.
551 // Don't always call NewWriter, as that forces a bytes.Buffer
552 // and other small bufio Writers to have a minimum 4k buffer
555 if _
, ok
:= w
.(io
.ByteWriter
); !ok
{
556 bw
= bufio
.NewWriter(w
)
560 _
, err
= fmt
.Fprintf(w
, "%s %s HTTP/1.1\r\n", valueOrDefault(r
.Method
, "GET"), ruri
)
566 _
, err
= fmt
.Fprintf(w
, "Host: %s\r\n", host
)
570 if trace
!= nil && trace
.WroteHeaderField
!= nil {
571 trace
.WroteHeaderField("Host", []string{host
})
574 // Use the defaultUserAgent unless the Header contains one, which
575 // may be blank to not send the header.
576 userAgent
:= defaultUserAgent
577 if _
, ok
:= r
.Header
["User-Agent"]; ok
{
578 userAgent
= r
.Header
.Get("User-Agent")
581 _
, err
= fmt
.Fprintf(w
, "User-Agent: %s\r\n", userAgent
)
585 if trace
!= nil && trace
.WroteHeaderField
!= nil {
586 trace
.WroteHeaderField("User-Agent", []string{userAgent
})
590 // Process Body,ContentLength,Close,Trailer
591 tw
, err
:= newTransferWriter(r
)
595 err
= tw
.writeHeader(w
, trace
)
600 err
= r
.Header
.writeSubset(w
, reqWriteExcludeHeader
, trace
)
605 if extraHeaders
!= nil {
606 err
= extraHeaders
.write(w
, trace
)
612 _
, err
= io
.WriteString(w
, "\r\n")
617 if trace
!= nil && trace
.WroteHeaders
!= nil {
621 // Flush and wait for 100-continue if expected.
622 if waitForContinue
!= nil {
623 if bw
, ok
:= w
.(*bufio
.Writer
); ok
{
629 if trace
!= nil && trace
.Wait100Continue
!= nil {
630 trace
.Wait100Continue()
632 if !waitForContinue() {
638 if bw
, ok
:= w
.(*bufio
.Writer
); ok
&& tw
.FlushHeaders
{
639 if err
:= bw
.Flush(); err
!= nil {
644 // Write body and trailer
645 err
= tw
.writeBody(w
)
647 if tw
.bodyReadError
== err
{
648 err
= requestBodyReadError
{err
}
659 // requestBodyReadError wraps an error from (*Request).write to indicate
660 // that the error came from a Read call on the Request.Body.
661 // This error type should not escape the net/http package to users.
662 type requestBodyReadError
struct{ error
}
664 func idnaASCII(v
string) (string, error
) {
665 // TODO: Consider removing this check after verifying performance is okay.
666 // Right now punycode verification, length checks, context checks, and the
667 // permissible character tests are all omitted. It also prevents the ToASCII
668 // call from salvaging an invalid IDN, when possible. As a result it may be
669 // possible to have two IDNs that appear identical to the user where the
670 // ASCII-only version causes an error downstream whereas the non-ASCII
672 // Note that for correct ASCII IDNs ToASCII will only do considerably more
673 // work, but it will not cause an allocation.
677 return idna
.Lookup
.ToASCII(v
)
680 // cleanHost cleans up the host sent in request's Host header.
682 // It both strips anything after '/' or ' ', and puts the value
683 // into Punycode form, if necessary.
685 // Ideally we'd clean the Host header according to the spec:
686 // https://tools.ietf.org/html/rfc7230#section-5.4 (Host = uri-host [ ":" port ]")
687 // https://tools.ietf.org/html/rfc7230#section-2.7 (uri-host -> rfc3986's host)
688 // https://tools.ietf.org/html/rfc3986#section-3.2.2 (definition of host)
689 // But practically, what we are trying to avoid is the situation in
690 // issue 11206, where a malformed Host header used in the proxy context
691 // would create a bad request. So it is enough to just truncate at the
692 // first offending character.
693 func cleanHost(in
string) string {
694 if i
:= strings
.IndexAny(in
, " /"); i
!= -1 {
697 host
, port
, err
:= net
.SplitHostPort(in
)
698 if err
!= nil { // input was just a host
699 a
, err
:= idnaASCII(in
)
701 return in
// garbage in, garbage out
705 a
, err
:= idnaASCII(host
)
707 return in
// garbage in, garbage out
709 return net
.JoinHostPort(a
, port
)
712 // removeZone removes IPv6 zone identifier from host.
713 // E.g., "[fe80::1%en0]:8080" to "[fe80::1]:8080"
714 func removeZone(host
string) string {
715 if !strings
.HasPrefix(host
, "[") {
718 i
:= strings
.LastIndex(host
, "]")
722 j
:= strings
.LastIndex(host
[:i
], "%")
726 return host
[:j
] + host
[i
:]
729 // ParseHTTPVersion parses a HTTP version string.
730 // "HTTP/1.0" returns (1, 0, true).
731 func ParseHTTPVersion(vers
string) (major
, minor
int, ok
bool) {
732 const Big
= 1000000 // arbitrary upper bound
739 if !strings
.HasPrefix(vers
, "HTTP/") {
742 dot
:= strings
.Index(vers
, ".")
746 major
, err
:= strconv
.Atoi(vers
[5:dot
])
747 if err
!= nil || major
< 0 || major
> Big
{
750 minor
, err
= strconv
.Atoi(vers
[dot
+1:])
751 if err
!= nil || minor
< 0 || minor
> Big
{
754 return major
, minor
, true
757 func validMethod(method
string) bool {
759 Method = "OPTIONS" ; Section 9.2
760 | "GET" ; Section 9.3
761 | "HEAD" ; Section 9.4
762 | "POST" ; Section 9.5
763 | "PUT" ; Section 9.6
764 | "DELETE" ; Section 9.7
765 | "TRACE" ; Section 9.8
766 | "CONNECT" ; Section 9.9
768 extension-method = token
769 token = 1*<any CHAR except CTLs or separators>
771 return len(method
) > 0 && strings
.IndexFunc(method
, isNotToken
) == -1
774 // NewRequest returns a new Request given a method, URL, and optional body.
776 // If the provided body is also an io.Closer, the returned
777 // Request.Body is set to body and will be closed by the Client
778 // methods Do, Post, and PostForm, and Transport.RoundTrip.
780 // NewRequest returns a Request suitable for use with Client.Do or
781 // Transport.RoundTrip. To create a request for use with testing a
782 // Server Handler, either use the NewRequest function in the
783 // net/http/httptest package, use ReadRequest, or manually update the
784 // Request fields. See the Request type's documentation for the
785 // difference between inbound and outbound request fields.
787 // If body is of type *bytes.Buffer, *bytes.Reader, or
788 // *strings.Reader, the returned request's ContentLength is set to its
789 // exact value (instead of -1), GetBody is populated (so 307 and 308
790 // redirects can replay the body), and Body is set to NoBody if the
791 // ContentLength is 0.
792 func NewRequest(method
, url
string, body io
.Reader
) (*Request
, error
) {
794 // We document that "" means "GET" for Request.Method, and people have
795 // relied on that from NewRequest, so keep that working.
796 // We still enforce validMethod for non-empty methods.
799 if !validMethod(method
) {
800 return nil, fmt
.Errorf("net/http: invalid method %q", method
)
802 u
, err
:= parseURL(url
) // Just url.Parse (url is shadowed for godoc).
806 rc
, ok
:= body
.(io
.ReadCloser
)
807 if !ok
&& body
!= nil {
808 rc
= ioutil
.NopCloser(body
)
810 // The host's colon:port should be normalized. See Issue 14836.
811 u
.Host
= removeEmptyPort(u
.Host
)
818 Header
: make(Header
),
823 switch v
:= body
.(type) {
825 req
.ContentLength
= int64(v
.Len())
827 req
.GetBody
= func() (io
.ReadCloser
, error
) {
828 r
:= bytes
.NewReader(buf
)
829 return ioutil
.NopCloser(r
), nil
832 req
.ContentLength
= int64(v
.Len())
834 req
.GetBody
= func() (io
.ReadCloser
, error
) {
836 return ioutil
.NopCloser(&r
), nil
838 case *strings
.Reader
:
839 req
.ContentLength
= int64(v
.Len())
841 req
.GetBody
= func() (io
.ReadCloser
, error
) {
843 return ioutil
.NopCloser(&r
), nil
846 // This is where we'd set it to -1 (at least
847 // if body != NoBody) to mean unknown, but
848 // that broke people during the Go 1.8 testing
849 // period. People depend on it being 0 I
850 // guess. Maybe retry later. See Issue 18117.
852 // For client requests, Request.ContentLength of 0
853 // means either actually 0, or unknown. The only way
854 // to explicitly say that the ContentLength is zero is
855 // to set the Body to nil. But turns out too much code
856 // depends on NewRequest returning a non-nil Body,
857 // so we use a well-known ReadCloser variable instead
858 // and have the http package also treat that sentinel
859 // variable to mean explicitly zero.
860 if req
.GetBody
!= nil && req
.ContentLength
== 0 {
862 req
.GetBody
= func() (io
.ReadCloser
, error
) { return NoBody
, nil }
869 // BasicAuth returns the username and password provided in the request's
870 // Authorization header, if the request uses HTTP Basic Authentication.
871 // See RFC 2617, Section 2.
872 func (r
*Request
) BasicAuth() (username
, password
string, ok
bool) {
873 auth
:= r
.Header
.Get("Authorization")
877 return parseBasicAuth(auth
)
880 // parseBasicAuth parses an HTTP Basic Authentication string.
881 // "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" returns ("Aladdin", "open sesame", true).
882 func parseBasicAuth(auth
string) (username
, password
string, ok
bool) {
883 const prefix
= "Basic "
884 // Case insensitive prefix match. See Issue 22736.
885 if len(auth
) < len(prefix
) ||
!strings
.EqualFold(auth
[:len(prefix
)], prefix
) {
888 c
, err
:= base64
.StdEncoding
.DecodeString(auth
[len(prefix
):])
893 s
:= strings
.IndexByte(cs
, ':')
897 return cs
[:s
], cs
[s
+1:], true
900 // SetBasicAuth sets the request's Authorization header to use HTTP
901 // Basic Authentication with the provided username and password.
903 // With HTTP Basic Authentication the provided username and password
904 // are not encrypted.
905 func (r
*Request
) SetBasicAuth(username
, password
string) {
906 r
.Header
.Set("Authorization", "Basic "+basicAuth(username
, password
))
909 // parseRequestLine parses "GET /foo HTTP/1.1" into its three parts.
910 func parseRequestLine(line
string) (method
, requestURI
, proto
string, ok
bool) {
911 s1
:= strings
.Index(line
, " ")
912 s2
:= strings
.Index(line
[s1
+1:], " ")
913 if s1
< 0 || s2
< 0 {
917 return line
[:s1
], line
[s1
+1 : s2
], line
[s2
+1:], true
920 var textprotoReaderPool sync
.Pool
922 func newTextprotoReader(br
*bufio
.Reader
) *textproto
.Reader
{
923 if v
:= textprotoReaderPool
.Get(); v
!= nil {
924 tr
:= v
.(*textproto
.Reader
)
928 return textproto
.NewReader(br
)
931 func putTextprotoReader(r
*textproto
.Reader
) {
933 textprotoReaderPool
.Put(r
)
936 // ReadRequest reads and parses an incoming request from b.
938 // ReadRequest is a low-level function and should only be used for
939 // specialized applications; most code should use the Server to read
940 // requests and handle them via the Handler interface. ReadRequest
941 // only supports HTTP/1.x requests. For HTTP/2, use golang.org/x/net/http2.
942 func ReadRequest(b
*bufio
.Reader
) (*Request
, error
) {
943 return readRequest(b
, deleteHostHeader
)
946 // Constants for readRequest's deleteHostHeader parameter.
948 deleteHostHeader
= true
949 keepHostHeader
= false
952 func readRequest(b
*bufio
.Reader
, deleteHostHeader
bool) (req
*Request
, err error
) {
953 tp
:= newTextprotoReader(b
)
956 // First line: GET /index.html HTTP/1.0
958 if s
, err
= tp
.ReadLine(); err
!= nil {
962 putTextprotoReader(tp
)
964 err
= io
.ErrUnexpectedEOF
969 req
.Method
, req
.RequestURI
, req
.Proto
, ok
= parseRequestLine(s
)
971 return nil, &badStringError
{"malformed HTTP request", s
}
973 if !validMethod(req
.Method
) {
974 return nil, &badStringError
{"invalid method", req
.Method
}
976 rawurl
:= req
.RequestURI
977 if req
.ProtoMajor
, req
.ProtoMinor
, ok
= ParseHTTPVersion(req
.Proto
); !ok
{
978 return nil, &badStringError
{"malformed HTTP version", req
.Proto
}
981 // CONNECT requests are used two different ways, and neither uses a full URL:
982 // The standard use is to tunnel HTTPS through an HTTP proxy.
983 // It looks like "CONNECT www.google.com:443 HTTP/1.1", and the parameter is
984 // just the authority section of a URL. This information should go in req.URL.Host.
986 // The net/rpc package also uses CONNECT, but there the parameter is a path
987 // that starts with a slash. It can be parsed with the regular URL parser,
988 // and the path will end up in req.URL.Path, where it needs to be in order for
990 justAuthority
:= req
.Method
== "CONNECT" && !strings
.HasPrefix(rawurl
, "/")
992 rawurl
= "http://" + rawurl
995 if req
.URL
, err
= url
.ParseRequestURI(rawurl
); err
!= nil {
1000 // Strip the bogus "http://" back off.
1004 // Subsequent lines: Key: value.
1005 mimeHeader
, err
:= tp
.ReadMIMEHeader()
1009 req
.Header
= Header(mimeHeader
)
1011 // RFC 7230, section 5.3: Must treat
1012 // GET /index.html HTTP/1.1
1013 // Host: www.google.com
1015 // GET http://www.google.com/index.html HTTP/1.1
1016 // Host: doesntmatter
1017 // the same. In the second case, any Host line is ignored.
1018 req
.Host
= req
.URL
.Host
1020 req
.Host
= req
.Header
.get("Host")
1022 if deleteHostHeader
{
1023 delete(req
.Header
, "Host")
1026 fixPragmaCacheControl(req
.Header
)
1028 req
.Close
= shouldClose(req
.ProtoMajor
, req
.ProtoMinor
, req
.Header
, false)
1030 err
= readTransfer(req
, b
)
1035 if req
.isH2Upgrade() {
1036 // Because it's neither chunked, nor declared:
1037 req
.ContentLength
= -1
1039 // We want to give handlers a chance to hijack the
1040 // connection, but we need to prevent the Server from
1041 // dealing with the connection further if it's not
1042 // hijacked. Set Close to ensure that:
1048 // MaxBytesReader is similar to io.LimitReader but is intended for
1049 // limiting the size of incoming request bodies. In contrast to
1050 // io.LimitReader, MaxBytesReader's result is a ReadCloser, returns a
1051 // non-EOF error for a Read beyond the limit, and closes the
1052 // underlying reader when its Close method is called.
1054 // MaxBytesReader prevents clients from accidentally or maliciously
1055 // sending a large request and wasting server resources.
1056 func MaxBytesReader(w ResponseWriter
, r io
.ReadCloser
, n
int64) io
.ReadCloser
{
1057 return &maxBytesReader
{w
: w
, r
: r
, n
: n
}
1060 type maxBytesReader
struct {
1062 r io
.ReadCloser
// underlying reader
1063 n
int64 // max bytes remaining
1064 err error
// sticky error
1067 func (l
*maxBytesReader
) Read(p
[]byte) (n
int, err error
) {
1074 // If they asked for a 32KB byte read but only 5 bytes are
1075 // remaining, no need to read 32KB. 6 bytes will answer the
1076 // question of the whether we hit the limit or go past it.
1077 if int64(len(p
)) > l
.n
+1 {
1080 n
, err
= l
.r
.Read(p
)
1082 if int64(n
) <= l
.n
{
1091 // The server code and client code both use
1092 // maxBytesReader. This "requestTooLarge" check is
1093 // only used by the server code. To prevent binaries
1094 // which only using the HTTP Client code (such as
1095 // cmd/go) from also linking in the HTTP server, don't
1096 // use a static type assertion to the server
1097 // "*response" type. Check this interface instead:
1098 type requestTooLarger
interface {
1101 if res
, ok
:= l
.w
.(requestTooLarger
); ok
{
1102 res
.requestTooLarge()
1104 l
.err
= errors
.New("http: request body too large")
1108 func (l
*maxBytesReader
) Close() error
{
1112 func copyValues(dst
, src url
.Values
) {
1113 for k
, vs
:= range src
{
1114 for _
, value
:= range vs
{
1120 func parsePostForm(r
*Request
) (vs url
.Values
, err error
) {
1122 err
= errors
.New("missing form body")
1125 ct
:= r
.Header
.Get("Content-Type")
1126 // RFC 7231, section 3.1.1.5 - empty type
1127 // MAY be treated as application/octet-stream
1129 ct
= "application/octet-stream"
1131 ct
, _
, err
= mime
.ParseMediaType(ct
)
1133 case ct
== "application/x-www-form-urlencoded":
1134 var reader io
.Reader
= r
.Body
1135 maxFormSize
:= int64(1<<63 - 1)
1136 if _
, ok
:= r
.Body
.(*maxBytesReader
); !ok
{
1137 maxFormSize
= int64(10 << 20) // 10 MB is a lot of text.
1138 reader
= io
.LimitReader(r
.Body
, maxFormSize
+1)
1140 b
, e
:= ioutil
.ReadAll(reader
)
1147 if int64(len(b
)) > maxFormSize
{
1148 err
= errors
.New("http: POST too large")
1151 vs
, e
= url
.ParseQuery(string(b
))
1155 case ct
== "multipart/form-data":
1156 // handled by ParseMultipartForm (which is calling us, or should be)
1157 // TODO(bradfitz): there are too many possible
1158 // orders to call too many functions here.
1159 // Clean this up and write more tests.
1160 // request_test.go contains the start of this,
1161 // in TestParseMultipartFormOrder and others.
1166 // ParseForm populates r.Form and r.PostForm.
1168 // For all requests, ParseForm parses the raw query from the URL and updates
1171 // For POST, PUT, and PATCH requests, it also parses the request body as a form
1172 // and puts the results into both r.PostForm and r.Form. Request body parameters
1173 // take precedence over URL query string values in r.Form.
1175 // For other HTTP methods, or when the Content-Type is not
1176 // application/x-www-form-urlencoded, the request Body is not read, and
1177 // r.PostForm is initialized to a non-nil, empty value.
1179 // If the request Body's size has not already been limited by MaxBytesReader,
1180 // the size is capped at 10MB.
1182 // ParseMultipartForm calls ParseForm automatically.
1183 // ParseForm is idempotent.
1184 func (r
*Request
) ParseForm() error
{
1186 if r
.PostForm
== nil {
1187 if r
.Method
== "POST" || r
.Method
== "PUT" || r
.Method
== "PATCH" {
1188 r
.PostForm
, err
= parsePostForm(r
)
1190 if r
.PostForm
== nil {
1191 r
.PostForm
= make(url
.Values
)
1195 if len(r
.PostForm
) > 0 {
1196 r
.Form
= make(url
.Values
)
1197 copyValues(r
.Form
, r
.PostForm
)
1199 var newValues url
.Values
1202 newValues
, e
= url
.ParseQuery(r
.URL
.RawQuery
)
1207 if newValues
== nil {
1208 newValues
= make(url
.Values
)
1213 copyValues(r
.Form
, newValues
)
1219 // ParseMultipartForm parses a request body as multipart/form-data.
1220 // The whole request body is parsed and up to a total of maxMemory bytes of
1221 // its file parts are stored in memory, with the remainder stored on
1222 // disk in temporary files.
1223 // ParseMultipartForm calls ParseForm if necessary.
1224 // After one call to ParseMultipartForm, subsequent calls have no effect.
1225 func (r
*Request
) ParseMultipartForm(maxMemory
int64) error
{
1226 if r
.MultipartForm
== multipartByReader
{
1227 return errors
.New("http: multipart handled by MultipartReader")
1230 err
:= r
.ParseForm()
1235 if r
.MultipartForm
!= nil {
1239 mr
, err
:= r
.multipartReader(false)
1244 f
, err
:= mr
.ReadForm(maxMemory
)
1249 if r
.PostForm
== nil {
1250 r
.PostForm
= make(url
.Values
)
1252 for k
, v
:= range f
.Value
{
1253 r
.Form
[k
] = append(r
.Form
[k
], v
...)
1254 // r.PostForm should also be populated. See Issue 9305.
1255 r
.PostForm
[k
] = append(r
.PostForm
[k
], v
...)
1263 // FormValue returns the first value for the named component of the query.
1264 // POST and PUT body parameters take precedence over URL query string values.
1265 // FormValue calls ParseMultipartForm and ParseForm if necessary and ignores
1266 // any errors returned by these functions.
1267 // If key is not present, FormValue returns the empty string.
1268 // To access multiple values of the same key, call ParseForm and
1269 // then inspect Request.Form directly.
1270 func (r
*Request
) FormValue(key
string) string {
1272 r
.ParseMultipartForm(defaultMaxMemory
)
1274 if vs
:= r
.Form
[key
]; len(vs
) > 0 {
1280 // PostFormValue returns the first value for the named component of the POST,
1281 // PATCH, or PUT request body. URL query parameters are ignored.
1282 // PostFormValue calls ParseMultipartForm and ParseForm if necessary and ignores
1283 // any errors returned by these functions.
1284 // If key is not present, PostFormValue returns the empty string.
1285 func (r
*Request
) PostFormValue(key
string) string {
1286 if r
.PostForm
== nil {
1287 r
.ParseMultipartForm(defaultMaxMemory
)
1289 if vs
:= r
.PostForm
[key
]; len(vs
) > 0 {
1295 // FormFile returns the first file for the provided form key.
1296 // FormFile calls ParseMultipartForm and ParseForm if necessary.
1297 func (r
*Request
) FormFile(key
string) (multipart
.File
, *multipart
.FileHeader
, error
) {
1298 if r
.MultipartForm
== multipartByReader
{
1299 return nil, nil, errors
.New("http: multipart handled by MultipartReader")
1301 if r
.MultipartForm
== nil {
1302 err
:= r
.ParseMultipartForm(defaultMaxMemory
)
1304 return nil, nil, err
1307 if r
.MultipartForm
!= nil && r
.MultipartForm
.File
!= nil {
1308 if fhs
:= r
.MultipartForm
.File
[key
]; len(fhs
) > 0 {
1309 f
, err
:= fhs
[0].Open()
1310 return f
, fhs
[0], err
1313 return nil, nil, ErrMissingFile
1316 func (r
*Request
) expectsContinue() bool {
1317 return hasToken(r
.Header
.get("Expect"), "100-continue")
1320 func (r
*Request
) wantsHttp10KeepAlive() bool {
1321 if r
.ProtoMajor
!= 1 || r
.ProtoMinor
!= 0 {
1324 return hasToken(r
.Header
.get("Connection"), "keep-alive")
1327 func (r
*Request
) wantsClose() bool {
1328 return hasToken(r
.Header
.get("Connection"), "close")
1331 func (r
*Request
) closeBody() {
1337 func (r
*Request
) isReplayable() bool {
1338 if r
.Body
== nil || r
.Body
== NoBody || r
.GetBody
!= nil {
1339 switch valueOrDefault(r
.Method
, "GET") {
1340 case "GET", "HEAD", "OPTIONS", "TRACE":
1347 // outgoingLength reports the Content-Length of this outgoing (Client) request.
1348 // It maps 0 into -1 (unknown) when the Body is non-nil.
1349 func (r
*Request
) outgoingLength() int64 {
1350 if r
.Body
== nil || r
.Body
== NoBody
{
1353 if r
.ContentLength
!= 0 {
1354 return r
.ContentLength
1359 // requestMethodUsuallyLacksBody reports whether the given request
1360 // method is one that typically does not involve a request body.
1361 // This is used by the Transport (via
1362 // transferWriter.shouldSendChunkedRequestBody) to determine whether
1363 // we try to test-read a byte from a non-nil Request.Body when
1364 // Request.outgoingLength() returns -1. See the comments in
1365 // shouldSendChunkedRequestBody.
1366 func requestMethodUsuallyLacksBody(method
string) bool {
1368 case "GET", "HEAD", "DELETE", "OPTIONS", "PROPFIND", "SEARCH":