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.
22 "net/http/internal/ascii"
30 "golang.org/x/net/idna"
34 defaultMaxMemory
= 32 << 20 // 32 MB
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")
41 // ProtocolError represents an HTTP protocol error.
43 // Deprecated: Not all errors in the http package related to protocol errors
44 // are of type ProtocolError.
45 type ProtocolError
struct {
49 func (pe
*ProtocolError
) Error() string { return pe
.ErrorString
}
52 // ErrNotSupported is returned by the Push method of Pusher
53 // implementations to indicate that HTTP/2 Push support is not
55 ErrNotSupported
= &ProtocolError
{"feature not supported"}
57 // Deprecated: ErrUnexpectedTrailer is no longer returned by
58 // anything in the net/http package. Callers should not
59 // compare errors against this variable.
60 ErrUnexpectedTrailer
= &ProtocolError
{"trailer header without chunked transfer encoding"}
62 // ErrMissingBoundary is returned by Request.MultipartReader when the
63 // request's Content-Type does not include a "boundary" parameter.
64 ErrMissingBoundary
= &ProtocolError
{"no multipart boundary param in Content-Type"}
66 // ErrNotMultipart is returned by Request.MultipartReader when the
67 // request's Content-Type is not multipart/form-data.
68 ErrNotMultipart
= &ProtocolError
{"request Content-Type isn't multipart/form-data"}
70 // Deprecated: ErrHeaderTooLong is no longer returned by
71 // anything in the net/http package. Callers should not
72 // compare errors against this variable.
73 ErrHeaderTooLong
= &ProtocolError
{"header too long"}
75 // Deprecated: ErrShortBody is no longer returned by
76 // anything in the net/http package. Callers should not
77 // compare errors against this variable.
78 ErrShortBody
= &ProtocolError
{"entity body too short"}
80 // Deprecated: ErrMissingContentLength is no longer returned by
81 // anything in the net/http package. Callers should not
82 // compare errors against this variable.
83 ErrMissingContentLength
= &ProtocolError
{"missing ContentLength in HEAD response"}
86 func badStringError(what
, val
string) error
{ return fmt
.Errorf("%s %q", what
, val
) }
88 // Headers that Request.Write handles itself and should be skipped.
89 var reqWriteExcludeHeader
= map[string]bool{
90 "Host": true, // not in Header map anyway
92 "Content-Length": true,
93 "Transfer-Encoding": true,
97 // A Request represents an HTTP request received by a server
98 // or to be sent by a client.
100 // The field semantics differ slightly between client and server
101 // usage. In addition to the notes on the fields below, see the
102 // documentation for Request.Write and RoundTripper.
103 type Request
struct {
104 // Method specifies the HTTP method (GET, POST, PUT, etc.).
105 // For client requests, an empty string means GET.
107 // Go's HTTP client does not support sending a request with
108 // the CONNECT method. See the documentation on Transport for
112 // URL specifies either the URI being requested (for server
113 // requests) or the URL to access (for client requests).
115 // For server requests, the URL is parsed from the URI
116 // supplied on the Request-Line as stored in RequestURI. For
117 // most requests, fields other than Path and RawQuery will be
118 // empty. (See RFC 7230, Section 5.3)
120 // For client requests, the URL's Host specifies the server to
121 // connect to, while the Request's Host field optionally
122 // specifies the Host header value to send in the HTTP
126 // The protocol version for incoming server requests.
128 // For client requests, these fields are ignored. The HTTP
129 // client code always uses either HTTP/1.1 or HTTP/2.
130 // See the docs on Transport for details.
131 Proto
string // "HTTP/1.0"
135 // Header contains the request header fields either received
136 // by the server or to be sent by the client.
138 // If a server received a request with header lines,
141 // accept-encoding: gzip, deflate
142 // Accept-Language: en-us
148 // Header = map[string][]string{
149 // "Accept-Encoding": {"gzip, deflate"},
150 // "Accept-Language": {"en-us"},
151 // "Foo": {"Bar", "two"},
154 // For incoming requests, the Host header is promoted to the
155 // Request.Host field and removed from the Header map.
157 // HTTP defines that header names are case-insensitive. The
158 // request parser implements this by using CanonicalHeaderKey,
159 // making the first character and any characters following a
160 // hyphen uppercase and the rest lowercase.
162 // For client requests, certain headers such as Content-Length
163 // and Connection are automatically written when needed and
164 // values in Header may be ignored. See the documentation
165 // for the Request.Write method.
168 // Body is the request's body.
170 // For client requests, a nil body means the request has no
171 // body, such as a GET request. The HTTP Client's Transport
172 // is responsible for calling the Close method.
174 // For server requests, the Request Body is always non-nil
175 // but will return EOF immediately when no body is present.
176 // The Server will close the request body. The ServeHTTP
177 // Handler does not need to.
179 // Body must allow Read to be called concurrently with Close.
180 // In particular, calling Close should unblock a Read waiting
184 // GetBody defines an optional func to return a new copy of
185 // Body. It is used for client requests when a redirect requires
186 // reading the body more than once. Use of GetBody still
187 // requires setting Body.
189 // For server requests, it is unused.
190 GetBody
func() (io
.ReadCloser
, error
)
192 // ContentLength records the length of the associated content.
193 // The value -1 indicates that the length is unknown.
194 // Values >= 0 indicate that the given number of bytes may
195 // be read from Body.
197 // For client requests, a value of 0 with a non-nil Body is
198 // also treated as unknown.
201 // TransferEncoding lists the transfer encodings from outermost to
202 // innermost. An empty list denotes the "identity" encoding.
203 // TransferEncoding can usually be ignored; chunked encoding is
204 // automatically added and removed as necessary when sending and
205 // receiving requests.
206 TransferEncoding
[]string
208 // Close indicates whether to close the connection after
209 // replying to this request (for servers) or after sending this
210 // request and reading its response (for clients).
212 // For server requests, the HTTP server handles this automatically
213 // and this field is not needed by Handlers.
215 // For client requests, setting this field prevents re-use of
216 // TCP connections between requests to the same hosts, as if
217 // Transport.DisableKeepAlives were set.
220 // For server requests, Host specifies the host on which the
221 // URL is sought. For HTTP/1 (per RFC 7230, section 5.4), this
222 // is either the value of the "Host" header or the host name
223 // given in the URL itself. For HTTP/2, it is the value of the
224 // ":authority" pseudo-header field.
225 // It may be of the form "host:port". For international domain
226 // names, Host may be in Punycode or Unicode form. Use
227 // golang.org/x/net/idna to convert it to either format if
229 // To prevent DNS rebinding attacks, server Handlers should
230 // validate that the Host header has a value for which the
231 // Handler considers itself authoritative. The included
232 // ServeMux supports patterns registered to particular host
233 // names and thus protects its registered Handlers.
235 // For client requests, Host optionally overrides the Host
236 // header to send. If empty, the Request.Write method uses
237 // the value of URL.Host. Host may contain an international
241 // Form contains the parsed form data, including both the URL
242 // field's query parameters and the PATCH, POST, or PUT form data.
243 // This field is only available after ParseForm is called.
244 // The HTTP client ignores Form and uses Body instead.
247 // PostForm contains the parsed form data from PATCH, POST
248 // or PUT body parameters.
250 // This field is only available after ParseForm is called.
251 // The HTTP client ignores PostForm and uses Body instead.
254 // MultipartForm is the parsed multipart form, including file uploads.
255 // This field is only available after ParseMultipartForm is called.
256 // The HTTP client ignores MultipartForm and uses Body instead.
257 MultipartForm
*multipart
.Form
259 // Trailer specifies additional headers that are sent after the request
262 // For server requests, the Trailer map initially contains only the
263 // trailer keys, with nil values. (The client declares which trailers it
264 // will later send.) While the handler is reading from Body, it must
265 // not reference Trailer. After reading from Body returns EOF, Trailer
266 // can be read again and will contain non-nil values, if they were sent
269 // For client requests, Trailer must be initialized to a map containing
270 // the trailer keys to later send. The values may be nil or their final
271 // values. The ContentLength must be 0 or -1, to send a chunked request.
272 // After the HTTP request is sent the map values can be updated while
273 // the request body is read. Once the body returns EOF, the caller must
274 // not mutate Trailer.
276 // Few HTTP clients, servers, or proxies support HTTP trailers.
279 // RemoteAddr allows HTTP servers and other software to record
280 // the network address that sent the request, usually for
281 // logging. This field is not filled in by ReadRequest and
282 // has no defined format. The HTTP server in this package
283 // sets RemoteAddr to an "IP:port" address before invoking a
285 // This field is ignored by the HTTP client.
288 // RequestURI is the unmodified request-target of the
289 // Request-Line (RFC 7230, Section 3.1.1) as sent by the client
290 // to a server. Usually the URL field should be used instead.
291 // It is an error to set this field in an HTTP client request.
294 // TLS allows HTTP servers and other software to record
295 // information about the TLS connection on which the request
296 // was received. This field is not filled in by ReadRequest.
297 // The HTTP server in this package sets the field for
298 // TLS-enabled connections before invoking a handler;
299 // otherwise it leaves the field nil.
300 // This field is ignored by the HTTP client.
301 TLS
*tls
.ConnectionState
303 // Cancel is an optional channel whose closure indicates that the client
304 // request should be regarded as canceled. Not all implementations of
305 // RoundTripper may support Cancel.
307 // For server requests, this field is not applicable.
309 // Deprecated: Set the Request's context with NewRequestWithContext
310 // instead. If a Request's Cancel field and context are both
311 // set, it is undefined whether Cancel is respected.
312 Cancel
<-chan struct{}
314 // Response is the redirect response which caused this request
315 // to be created. This field is only populated during client
319 // ctx is either the client or server context. It should only
320 // be modified via copying the whole Request using WithContext.
321 // It is unexported to prevent people from using Context wrong
322 // and mutating the contexts held by callers of the same request.
326 // Context returns the request's context. To change the context, use
329 // The returned context is always non-nil; it defaults to the
330 // background context.
332 // For outgoing client requests, the context controls cancellation.
334 // For incoming server requests, the context is canceled when the
335 // client's connection closes, the request is canceled (with HTTP/2),
336 // or when the ServeHTTP method returns.
337 func (r
*Request
) Context() context
.Context
{
341 return context
.Background()
344 // WithContext returns a shallow copy of r with its context changed
345 // to ctx. The provided ctx must be non-nil.
347 // For outgoing client request, the context controls the entire
348 // lifetime of a request and its response: obtaining a connection,
349 // sending the request, and reading the response headers and body.
351 // To create a new request with a context, use NewRequestWithContext.
352 // To change the context of a request, such as an incoming request you
353 // want to modify before sending back out, use Request.Clone. Between
354 // those two uses, it's rare to need WithContext.
355 func (r
*Request
) WithContext(ctx context
.Context
) *Request
{
362 r2
.URL
= cloneURL(r
.URL
) // legacy behavior; TODO: try to remove. Issue 23544
366 // Clone returns a deep copy of r with its context changed to ctx.
367 // The provided ctx must be non-nil.
369 // For an outgoing client request, the context controls the entire
370 // lifetime of a request and its response: obtaining a connection,
371 // sending the request, and reading the response headers and body.
372 func (r
*Request
) Clone(ctx context
.Context
) *Request
{
379 r2
.URL
= cloneURL(r
.URL
)
381 r2
.Header
= r
.Header
.Clone()
383 if r
.Trailer
!= nil {
384 r2
.Trailer
= r
.Trailer
.Clone()
386 if s
:= r
.TransferEncoding
; s
!= nil {
387 s2
:= make([]string, len(s
))
389 r2
.TransferEncoding
= s2
391 r2
.Form
= cloneURLValues(r
.Form
)
392 r2
.PostForm
= cloneURLValues(r
.PostForm
)
393 r2
.MultipartForm
= cloneMultipartForm(r
.MultipartForm
)
397 // ProtoAtLeast reports whether the HTTP protocol used
398 // in the request is at least major.minor.
399 func (r
*Request
) ProtoAtLeast(major
, minor
int) bool {
400 return r
.ProtoMajor
> major ||
401 r
.ProtoMajor
== major
&& r
.ProtoMinor
>= minor
404 // UserAgent returns the client's User-Agent, if sent in the request.
405 func (r
*Request
) UserAgent() string {
406 return r
.Header
.Get("User-Agent")
409 // Cookies parses and returns the HTTP cookies sent with the request.
410 func (r
*Request
) Cookies() []*Cookie
{
411 return readCookies(r
.Header
, "")
414 // ErrNoCookie is returned by Request's Cookie method when a cookie is not found.
415 var ErrNoCookie
= errors
.New("http: named cookie not present")
417 // Cookie returns the named cookie provided in the request or
418 // ErrNoCookie if not found.
419 // If multiple cookies match the given name, only one cookie will
421 func (r
*Request
) Cookie(name
string) (*Cookie
, error
) {
422 for _
, c
:= range readCookies(r
.Header
, name
) {
425 return nil, ErrNoCookie
428 // AddCookie adds a cookie to the request. Per RFC 6265 section 5.4,
429 // AddCookie does not attach more than one Cookie header field. That
430 // means all cookies, if any, are written into the same line,
431 // separated by semicolon.
432 // AddCookie only sanitizes c's name and value, and does not sanitize
433 // a Cookie header already present in the request.
434 func (r
*Request
) AddCookie(c
*Cookie
) {
435 s
:= fmt
.Sprintf("%s=%s", sanitizeCookieName(c
.Name
), sanitizeCookieValue(c
.Value
))
436 if c
:= r
.Header
.Get("Cookie"); c
!= "" {
437 r
.Header
.Set("Cookie", c
+"; "+s
)
439 r
.Header
.Set("Cookie", s
)
443 // Referer returns the referring URL, if sent in the request.
445 // Referer is misspelled as in the request itself, a mistake from the
446 // earliest days of HTTP. This value can also be fetched from the
447 // Header map as Header["Referer"]; the benefit of making it available
448 // as a method is that the compiler can diagnose programs that use the
449 // alternate (correct English) spelling req.Referrer() but cannot
450 // diagnose programs that use Header["Referrer"].
451 func (r
*Request
) Referer() string {
452 return r
.Header
.Get("Referer")
455 // multipartByReader is a sentinel value.
456 // Its presence in Request.MultipartForm indicates that parsing of the request
457 // body has been handed off to a MultipartReader instead of ParseMultipartForm.
458 var multipartByReader
= &multipart
.Form
{
459 Value
: make(map[string][]string),
460 File
: make(map[string][]*multipart
.FileHeader
),
463 // MultipartReader returns a MIME multipart reader if this is a
464 // multipart/form-data or a multipart/mixed POST request, else returns nil and an error.
465 // Use this function instead of ParseMultipartForm to
466 // process the request body as a stream.
467 func (r
*Request
) MultipartReader() (*multipart
.Reader
, error
) {
468 if r
.MultipartForm
== multipartByReader
{
469 return nil, errors
.New("http: MultipartReader called twice")
471 if r
.MultipartForm
!= nil {
472 return nil, errors
.New("http: multipart handled by ParseMultipartForm")
474 r
.MultipartForm
= multipartByReader
475 return r
.multipartReader(true)
478 func (r
*Request
) multipartReader(allowMixed
bool) (*multipart
.Reader
, error
) {
479 v
:= r
.Header
.Get("Content-Type")
481 return nil, ErrNotMultipart
483 d
, params
, err
:= mime
.ParseMediaType(v
)
484 if err
!= nil ||
!(d
== "multipart/form-data" || allowMixed
&& d
== "multipart/mixed") {
485 return nil, ErrNotMultipart
487 boundary
, ok
:= params
["boundary"]
489 return nil, ErrMissingBoundary
491 return multipart
.NewReader(r
.Body
, boundary
), nil
494 // isH2Upgrade reports whether r represents the http2 "client preface"
496 func (r
*Request
) isH2Upgrade() bool {
497 return r
.Method
== "PRI" && len(r
.Header
) == 0 && r
.URL
.Path
== "*" && r
.Proto
== "HTTP/2.0"
500 // Return value if nonempty, def otherwise.
501 func valueOrDefault(value
, def
string) string {
508 // NOTE: This is not intended to reflect the actual Go version being used.
509 // It was changed at the time of Go 1.1 release because the former User-Agent
510 // had ended up blocked by some intrusion detection systems.
511 // See https://codereview.appspot.com/7532043.
512 const defaultUserAgent
= "Go-http-client/1.1"
514 // Write writes an HTTP/1.1 request, which is the header and body, in wire format.
515 // This method consults the following fields of the request:
518 // Method (defaults to "GET")
524 // If Body is present, Content-Length is <= 0 and TransferEncoding
525 // hasn't been set to "identity", Write adds "Transfer-Encoding:
526 // chunked" to the header. Body is closed after it is sent.
527 func (r
*Request
) Write(w io
.Writer
) error
{
528 return r
.write(w
, false, nil, nil)
531 // WriteProxy is like Write but writes the request in the form
532 // expected by an HTTP proxy. In particular, WriteProxy writes the
533 // initial Request-URI line of the request with an absolute URI, per
534 // section 5.3 of RFC 7230, including the scheme and host.
535 // In either case, WriteProxy also writes a Host header, using
536 // either r.Host or r.URL.Host.
537 func (r
*Request
) WriteProxy(w io
.Writer
) error
{
538 return r
.write(w
, true, nil, nil)
541 // errMissingHost is returned by Write when there is no Host or URL present in
543 var errMissingHost
= errors
.New("http: Request.Write on Request with no Host or URL set")
545 // extraHeaders may be nil
546 // waitForContinue may be nil
547 // always closes body
548 func (r
*Request
) write(w io
.Writer
, usingProxy
bool, extraHeaders Header
, waitForContinue
func() bool) (err error
) {
549 trace
:= httptrace
.ContextClientTrace(r
.Context())
550 if trace
!= nil && trace
.WroteRequest
!= nil {
552 trace
.WroteRequest(httptrace
.WroteRequestInfo
{
562 if closeErr
:= r
.closeBody(); closeErr
!= nil && err
== nil {
567 // Find the target host. Prefer the Host: header, but if that
568 // is not given, use the host from the request URL.
570 // Clean the host, in case it arrives with unexpected stuff in it.
571 host
:= cleanHost(r
.Host
)
574 return errMissingHost
576 host
= cleanHost(r
.URL
.Host
)
579 // According to RFC 6874, an HTTP client, proxy, or other
580 // intermediary must remove any IPv6 zone identifier attached
581 // to an outgoing URI.
582 host
= removeZone(host
)
584 ruri
:= r
.URL
.RequestURI()
585 if usingProxy
&& r
.URL
.Scheme
!= "" && r
.URL
.Opaque
== "" {
586 ruri
= r
.URL
.Scheme
+ "://" + host
+ ruri
587 } else if r
.Method
== "CONNECT" && r
.URL
.Path
== "" {
588 // CONNECT requests normally give just the host and port, not a full URL.
590 if r
.URL
.Opaque
!= "" {
594 if stringContainsCTLByte(ruri
) {
595 return errors
.New("net/http: can't write control character in Request.URL")
597 // TODO: validate r.Method too? At least it's less likely to
598 // come from an attacker (more likely to be a constant in
601 // Wrap the writer in a bufio Writer if it's not already buffered.
602 // Don't always call NewWriter, as that forces a bytes.Buffer
603 // and other small bufio Writers to have a minimum 4k buffer
606 if _
, ok
:= w
.(io
.ByteWriter
); !ok
{
607 bw
= bufio
.NewWriter(w
)
611 _
, err
= fmt
.Fprintf(w
, "%s %s HTTP/1.1\r\n", valueOrDefault(r
.Method
, "GET"), ruri
)
617 _
, err
= fmt
.Fprintf(w
, "Host: %s\r\n", host
)
621 if trace
!= nil && trace
.WroteHeaderField
!= nil {
622 trace
.WroteHeaderField("Host", []string{host
})
625 // Use the defaultUserAgent unless the Header contains one, which
626 // may be blank to not send the header.
627 userAgent
:= defaultUserAgent
628 if r
.Header
.has("User-Agent") {
629 userAgent
= r
.Header
.Get("User-Agent")
632 _
, err
= fmt
.Fprintf(w
, "User-Agent: %s\r\n", userAgent
)
636 if trace
!= nil && trace
.WroteHeaderField
!= nil {
637 trace
.WroteHeaderField("User-Agent", []string{userAgent
})
641 // Process Body,ContentLength,Close,Trailer
642 tw
, err
:= newTransferWriter(r
)
646 err
= tw
.writeHeader(w
, trace
)
651 err
= r
.Header
.writeSubset(w
, reqWriteExcludeHeader
, trace
)
656 if extraHeaders
!= nil {
657 err
= extraHeaders
.write(w
, trace
)
663 _
, err
= io
.WriteString(w
, "\r\n")
668 if trace
!= nil && trace
.WroteHeaders
!= nil {
672 // Flush and wait for 100-continue if expected.
673 if waitForContinue
!= nil {
674 if bw
, ok
:= w
.(*bufio
.Writer
); ok
{
680 if trace
!= nil && trace
.Wait100Continue
!= nil {
681 trace
.Wait100Continue()
683 if !waitForContinue() {
690 if bw
, ok
:= w
.(*bufio
.Writer
); ok
&& tw
.FlushHeaders
{
691 if err
:= bw
.Flush(); err
!= nil {
696 // Write body and trailer
698 err
= tw
.writeBody(w
)
700 if tw
.bodyReadError
== err
{
701 err
= requestBodyReadError
{err
}
712 // requestBodyReadError wraps an error from (*Request).write to indicate
713 // that the error came from a Read call on the Request.Body.
714 // This error type should not escape the net/http package to users.
715 type requestBodyReadError
struct{ error
}
717 func idnaASCII(v
string) (string, error
) {
718 // TODO: Consider removing this check after verifying performance is okay.
719 // Right now punycode verification, length checks, context checks, and the
720 // permissible character tests are all omitted. It also prevents the ToASCII
721 // call from salvaging an invalid IDN, when possible. As a result it may be
722 // possible to have two IDNs that appear identical to the user where the
723 // ASCII-only version causes an error downstream whereas the non-ASCII
725 // Note that for correct ASCII IDNs ToASCII will only do considerably more
726 // work, but it will not cause an allocation.
730 return idna
.Lookup
.ToASCII(v
)
733 // cleanHost cleans up the host sent in request's Host header.
735 // It both strips anything after '/' or ' ', and puts the value
736 // into Punycode form, if necessary.
738 // Ideally we'd clean the Host header according to the spec:
739 // https://tools.ietf.org/html/rfc7230#section-5.4 (Host = uri-host [ ":" port ]")
740 // https://tools.ietf.org/html/rfc7230#section-2.7 (uri-host -> rfc3986's host)
741 // https://tools.ietf.org/html/rfc3986#section-3.2.2 (definition of host)
742 // But practically, what we are trying to avoid is the situation in
743 // issue 11206, where a malformed Host header used in the proxy context
744 // would create a bad request. So it is enough to just truncate at the
745 // first offending character.
746 func cleanHost(in
string) string {
747 if i
:= strings
.IndexAny(in
, " /"); i
!= -1 {
750 host
, port
, err
:= net
.SplitHostPort(in
)
751 if err
!= nil { // input was just a host
752 a
, err
:= idnaASCII(in
)
754 return in
// garbage in, garbage out
758 a
, err
:= idnaASCII(host
)
760 return in
// garbage in, garbage out
762 return net
.JoinHostPort(a
, port
)
765 // removeZone removes IPv6 zone identifier from host.
766 // E.g., "[fe80::1%en0]:8080" to "[fe80::1]:8080"
767 func removeZone(host
string) string {
768 if !strings
.HasPrefix(host
, "[") {
771 i
:= strings
.LastIndex(host
, "]")
775 j
:= strings
.LastIndex(host
[:i
], "%")
779 return host
[:j
] + host
[i
:]
782 // ParseHTTPVersion parses an HTTP version string according to RFC 7230, section 2.6.
783 // "HTTP/1.0" returns (1, 0, true). Note that strings without
784 // a minor version, such as "HTTP/2", are not valid.
785 func ParseHTTPVersion(vers
string) (major
, minor
int, ok
bool) {
792 if !strings
.HasPrefix(vers
, "HTTP/") {
795 if len(vers
) != len("HTTP/X.Y") {
801 maj
, err
:= strconv
.ParseUint(vers
[5:6], 10, 0)
805 min
, err
:= strconv
.ParseUint(vers
[7:8], 10, 0)
809 return int(maj
), int(min
), true
812 func validMethod(method
string) bool {
814 Method = "OPTIONS" ; Section 9.2
815 | "GET" ; Section 9.3
816 | "HEAD" ; Section 9.4
817 | "POST" ; Section 9.5
818 | "PUT" ; Section 9.6
819 | "DELETE" ; Section 9.7
820 | "TRACE" ; Section 9.8
821 | "CONNECT" ; Section 9.9
823 extension-method = token
824 token = 1*<any CHAR except CTLs or separators>
826 return len(method
) > 0 && strings
.IndexFunc(method
, isNotToken
) == -1
829 // NewRequest wraps NewRequestWithContext using context.Background.
830 func NewRequest(method
, url
string, body io
.Reader
) (*Request
, error
) {
831 return NewRequestWithContext(context
.Background(), method
, url
, body
)
834 // NewRequestWithContext returns a new Request given a method, URL, and
837 // If the provided body is also an io.Closer, the returned
838 // Request.Body is set to body and will be closed by the Client
839 // methods Do, Post, and PostForm, and Transport.RoundTrip.
841 // NewRequestWithContext returns a Request suitable for use with
842 // Client.Do or Transport.RoundTrip. To create a request for use with
843 // testing a Server Handler, either use the NewRequest function in the
844 // net/http/httptest package, use ReadRequest, or manually update the
845 // Request fields. For an outgoing client request, the context
846 // controls the entire lifetime of a request and its response:
847 // obtaining a connection, sending the request, and reading the
848 // response headers and body. See the Request type's documentation for
849 // the difference between inbound and outbound request fields.
851 // If body is of type *bytes.Buffer, *bytes.Reader, or
852 // *strings.Reader, the returned request's ContentLength is set to its
853 // exact value (instead of -1), GetBody is populated (so 307 and 308
854 // redirects can replay the body), and Body is set to NoBody if the
855 // ContentLength is 0.
856 func NewRequestWithContext(ctx context
.Context
, method
, url
string, body io
.Reader
) (*Request
, error
) {
858 // We document that "" means "GET" for Request.Method, and people have
859 // relied on that from NewRequest, so keep that working.
860 // We still enforce validMethod for non-empty methods.
863 if !validMethod(method
) {
864 return nil, fmt
.Errorf("net/http: invalid method %q", method
)
867 return nil, errors
.New("net/http: nil Context")
869 u
, err
:= urlpkg
.Parse(url
)
873 rc
, ok
:= body
.(io
.ReadCloser
)
874 if !ok
&& body
!= nil {
875 rc
= io
.NopCloser(body
)
877 // The host's colon:port should be normalized. See Issue 14836.
878 u
.Host
= removeEmptyPort(u
.Host
)
886 Header
: make(Header
),
891 switch v
:= body
.(type) {
893 req
.ContentLength
= int64(v
.Len())
895 req
.GetBody
= func() (io
.ReadCloser
, error
) {
896 r
:= bytes
.NewReader(buf
)
897 return io
.NopCloser(r
), nil
900 req
.ContentLength
= int64(v
.Len())
902 req
.GetBody
= func() (io
.ReadCloser
, error
) {
904 return io
.NopCloser(&r
), nil
906 case *strings
.Reader
:
907 req
.ContentLength
= int64(v
.Len())
909 req
.GetBody
= func() (io
.ReadCloser
, error
) {
911 return io
.NopCloser(&r
), nil
914 // This is where we'd set it to -1 (at least
915 // if body != NoBody) to mean unknown, but
916 // that broke people during the Go 1.8 testing
917 // period. People depend on it being 0 I
918 // guess. Maybe retry later. See Issue 18117.
920 // For client requests, Request.ContentLength of 0
921 // means either actually 0, or unknown. The only way
922 // to explicitly say that the ContentLength is zero is
923 // to set the Body to nil. But turns out too much code
924 // depends on NewRequest returning a non-nil Body,
925 // so we use a well-known ReadCloser variable instead
926 // and have the http package also treat that sentinel
927 // variable to mean explicitly zero.
928 if req
.GetBody
!= nil && req
.ContentLength
== 0 {
930 req
.GetBody
= func() (io
.ReadCloser
, error
) { return NoBody
, nil }
937 // BasicAuth returns the username and password provided in the request's
938 // Authorization header, if the request uses HTTP Basic Authentication.
939 // See RFC 2617, Section 2.
940 func (r
*Request
) BasicAuth() (username
, password
string, ok
bool) {
941 auth
:= r
.Header
.Get("Authorization")
945 return parseBasicAuth(auth
)
948 // parseBasicAuth parses an HTTP Basic Authentication string.
949 // "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" returns ("Aladdin", "open sesame", true).
950 func parseBasicAuth(auth
string) (username
, password
string, ok
bool) {
951 const prefix
= "Basic "
952 // Case insensitive prefix match. See Issue 22736.
953 if len(auth
) < len(prefix
) ||
!ascii
.EqualFold(auth
[:len(prefix
)], prefix
) {
956 c
, err
:= base64
.StdEncoding
.DecodeString(auth
[len(prefix
):])
961 username
, password
, ok
= strings
.Cut(cs
, ":")
965 return username
, password
, true
968 // SetBasicAuth sets the request's Authorization header to use HTTP
969 // Basic Authentication with the provided username and password.
971 // With HTTP Basic Authentication the provided username and password
972 // are not encrypted.
974 // Some protocols may impose additional requirements on pre-escaping the
975 // username and password. For instance, when used with OAuth2, both arguments
976 // must be URL encoded first with url.QueryEscape.
977 func (r
*Request
) SetBasicAuth(username
, password
string) {
978 r
.Header
.Set("Authorization", "Basic "+basicAuth(username
, password
))
981 // parseRequestLine parses "GET /foo HTTP/1.1" into its three parts.
982 func parseRequestLine(line
string) (method
, requestURI
, proto
string, ok
bool) {
983 method
, rest
, ok1
:= strings
.Cut(line
, " ")
984 requestURI
, proto
, ok2
:= strings
.Cut(rest
, " ")
986 return "", "", "", false
988 return method
, requestURI
, proto
, true
991 var textprotoReaderPool sync
.Pool
993 func newTextprotoReader(br
*bufio
.Reader
) *textproto
.Reader
{
994 if v
:= textprotoReaderPool
.Get(); v
!= nil {
995 tr
:= v
.(*textproto
.Reader
)
999 return textproto
.NewReader(br
)
1002 func putTextprotoReader(r
*textproto
.Reader
) {
1004 textprotoReaderPool
.Put(r
)
1007 // ReadRequest reads and parses an incoming request from b.
1009 // ReadRequest is a low-level function and should only be used for
1010 // specialized applications; most code should use the Server to read
1011 // requests and handle them via the Handler interface. ReadRequest
1012 // only supports HTTP/1.x requests. For HTTP/2, use golang.org/x/net/http2.
1013 func ReadRequest(b
*bufio
.Reader
) (*Request
, error
) {
1014 req
, err
:= readRequest(b
)
1019 delete(req
.Header
, "Host")
1023 func readRequest(b
*bufio
.Reader
) (req
*Request
, err error
) {
1024 tp
:= newTextprotoReader(b
)
1027 // First line: GET /index.html HTTP/1.0
1029 if s
, err
= tp
.ReadLine(); err
!= nil {
1033 putTextprotoReader(tp
)
1035 err
= io
.ErrUnexpectedEOF
1040 req
.Method
, req
.RequestURI
, req
.Proto
, ok
= parseRequestLine(s
)
1042 return nil, badStringError("malformed HTTP request", s
)
1044 if !validMethod(req
.Method
) {
1045 return nil, badStringError("invalid method", req
.Method
)
1047 rawurl
:= req
.RequestURI
1048 if req
.ProtoMajor
, req
.ProtoMinor
, ok
= ParseHTTPVersion(req
.Proto
); !ok
{
1049 return nil, badStringError("malformed HTTP version", req
.Proto
)
1052 // CONNECT requests are used two different ways, and neither uses a full URL:
1053 // The standard use is to tunnel HTTPS through an HTTP proxy.
1054 // It looks like "CONNECT www.google.com:443 HTTP/1.1", and the parameter is
1055 // just the authority section of a URL. This information should go in req.URL.Host.
1057 // The net/rpc package also uses CONNECT, but there the parameter is a path
1058 // that starts with a slash. It can be parsed with the regular URL parser,
1059 // and the path will end up in req.URL.Path, where it needs to be in order for
1061 justAuthority
:= req
.Method
== "CONNECT" && !strings
.HasPrefix(rawurl
, "/")
1063 rawurl
= "http://" + rawurl
1066 if req
.URL
, err
= url
.ParseRequestURI(rawurl
); err
!= nil {
1071 // Strip the bogus "http://" back off.
1075 // Subsequent lines: Key: value.
1076 mimeHeader
, err
:= tp
.ReadMIMEHeader()
1080 req
.Header
= Header(mimeHeader
)
1081 if len(req
.Header
["Host"]) > 1 {
1082 return nil, fmt
.Errorf("too many Host headers")
1085 // RFC 7230, section 5.3: Must treat
1086 // GET /index.html HTTP/1.1
1087 // Host: www.google.com
1089 // GET http://www.google.com/index.html HTTP/1.1
1090 // Host: doesntmatter
1091 // the same. In the second case, any Host line is ignored.
1092 req
.Host
= req
.URL
.Host
1094 req
.Host
= req
.Header
.get("Host")
1097 fixPragmaCacheControl(req
.Header
)
1099 req
.Close
= shouldClose(req
.ProtoMajor
, req
.ProtoMinor
, req
.Header
, false)
1101 err
= readTransfer(req
, b
)
1106 if req
.isH2Upgrade() {
1107 // Because it's neither chunked, nor declared:
1108 req
.ContentLength
= -1
1110 // We want to give handlers a chance to hijack the
1111 // connection, but we need to prevent the Server from
1112 // dealing with the connection further if it's not
1113 // hijacked. Set Close to ensure that:
1119 // MaxBytesReader is similar to io.LimitReader but is intended for
1120 // limiting the size of incoming request bodies. In contrast to
1121 // io.LimitReader, MaxBytesReader's result is a ReadCloser, returns a
1122 // non-EOF error for a Read beyond the limit, and closes the
1123 // underlying reader when its Close method is called.
1125 // MaxBytesReader prevents clients from accidentally or maliciously
1126 // sending a large request and wasting server resources.
1127 func MaxBytesReader(w ResponseWriter
, r io
.ReadCloser
, n
int64) io
.ReadCloser
{
1128 if n
< 0 { // Treat negative limits as equivalent to 0.
1131 return &maxBytesReader
{w
: w
, r
: r
, n
: n
}
1134 type maxBytesReader
struct {
1136 r io
.ReadCloser
// underlying reader
1137 n
int64 // max bytes remaining
1138 err error
// sticky error
1141 func (l
*maxBytesReader
) Read(p
[]byte) (n
int, err error
) {
1148 // If they asked for a 32KB byte read but only 5 bytes are
1149 // remaining, no need to read 32KB. 6 bytes will answer the
1150 // question of the whether we hit the limit or go past it.
1151 if int64(len(p
)) > l
.n
+1 {
1154 n
, err
= l
.r
.Read(p
)
1156 if int64(n
) <= l
.n
{
1165 // The server code and client code both use
1166 // maxBytesReader. This "requestTooLarge" check is
1167 // only used by the server code. To prevent binaries
1168 // which only using the HTTP Client code (such as
1169 // cmd/go) from also linking in the HTTP server, don't
1170 // use a static type assertion to the server
1171 // "*response" type. Check this interface instead:
1172 type requestTooLarger
interface {
1175 if res
, ok
:= l
.w
.(requestTooLarger
); ok
{
1176 res
.requestTooLarge()
1178 l
.err
= errors
.New("http: request body too large")
1182 func (l
*maxBytesReader
) Close() error
{
1186 func copyValues(dst
, src url
.Values
) {
1187 for k
, vs
:= range src
{
1188 dst
[k
] = append(dst
[k
], vs
...)
1192 func parsePostForm(r
*Request
) (vs url
.Values
, err error
) {
1194 err
= errors
.New("missing form body")
1197 ct
:= r
.Header
.Get("Content-Type")
1198 // RFC 7231, section 3.1.1.5 - empty type
1199 // MAY be treated as application/octet-stream
1201 ct
= "application/octet-stream"
1203 ct
, _
, err
= mime
.ParseMediaType(ct
)
1205 case ct
== "application/x-www-form-urlencoded":
1206 var reader io
.Reader
= r
.Body
1207 maxFormSize
:= int64(1<<63 - 1)
1208 if _
, ok
:= r
.Body
.(*maxBytesReader
); !ok
{
1209 maxFormSize
= int64(10 << 20) // 10 MB is a lot of text.
1210 reader
= io
.LimitReader(r
.Body
, maxFormSize
+1)
1212 b
, e
:= io
.ReadAll(reader
)
1219 if int64(len(b
)) > maxFormSize
{
1220 err
= errors
.New("http: POST too large")
1223 vs
, e
= url
.ParseQuery(string(b
))
1227 case ct
== "multipart/form-data":
1228 // handled by ParseMultipartForm (which is calling us, or should be)
1229 // TODO(bradfitz): there are too many possible
1230 // orders to call too many functions here.
1231 // Clean this up and write more tests.
1232 // request_test.go contains the start of this,
1233 // in TestParseMultipartFormOrder and others.
1238 // ParseForm populates r.Form and r.PostForm.
1240 // For all requests, ParseForm parses the raw query from the URL and updates
1243 // For POST, PUT, and PATCH requests, it also reads the request body, parses it
1244 // as a form and puts the results into both r.PostForm and r.Form. Request body
1245 // parameters take precedence over URL query string values in r.Form.
1247 // If the request Body's size has not already been limited by MaxBytesReader,
1248 // the size is capped at 10MB.
1250 // For other HTTP methods, or when the Content-Type is not
1251 // application/x-www-form-urlencoded, the request Body is not read, and
1252 // r.PostForm is initialized to a non-nil, empty value.
1254 // ParseMultipartForm calls ParseForm automatically.
1255 // ParseForm is idempotent.
1256 func (r
*Request
) ParseForm() error
{
1258 if r
.PostForm
== nil {
1259 if r
.Method
== "POST" || r
.Method
== "PUT" || r
.Method
== "PATCH" {
1260 r
.PostForm
, err
= parsePostForm(r
)
1262 if r
.PostForm
== nil {
1263 r
.PostForm
= make(url
.Values
)
1267 if len(r
.PostForm
) > 0 {
1268 r
.Form
= make(url
.Values
)
1269 copyValues(r
.Form
, r
.PostForm
)
1271 var newValues url
.Values
1274 newValues
, e
= url
.ParseQuery(r
.URL
.RawQuery
)
1279 if newValues
== nil {
1280 newValues
= make(url
.Values
)
1285 copyValues(r
.Form
, newValues
)
1291 // ParseMultipartForm parses a request body as multipart/form-data.
1292 // The whole request body is parsed and up to a total of maxMemory bytes of
1293 // its file parts are stored in memory, with the remainder stored on
1294 // disk in temporary files.
1295 // ParseMultipartForm calls ParseForm if necessary.
1296 // If ParseForm returns an error, ParseMultipartForm returns it but also
1297 // continues parsing the request body.
1298 // After one call to ParseMultipartForm, subsequent calls have no effect.
1299 func (r
*Request
) ParseMultipartForm(maxMemory
int64) error
{
1300 if r
.MultipartForm
== multipartByReader
{
1301 return errors
.New("http: multipart handled by MultipartReader")
1303 var parseFormErr error
1305 // Let errors in ParseForm fall through, and just
1306 // return it at the end.
1307 parseFormErr
= r
.ParseForm()
1309 if r
.MultipartForm
!= nil {
1313 mr
, err
:= r
.multipartReader(false)
1318 f
, err
:= mr
.ReadForm(maxMemory
)
1323 if r
.PostForm
== nil {
1324 r
.PostForm
= make(url
.Values
)
1326 for k
, v
:= range f
.Value
{
1327 r
.Form
[k
] = append(r
.Form
[k
], v
...)
1328 // r.PostForm should also be populated. See Issue 9305.
1329 r
.PostForm
[k
] = append(r
.PostForm
[k
], v
...)
1337 // FormValue returns the first value for the named component of the query.
1338 // POST and PUT body parameters take precedence over URL query string values.
1339 // FormValue calls ParseMultipartForm and ParseForm if necessary and ignores
1340 // any errors returned by these functions.
1341 // If key is not present, FormValue returns the empty string.
1342 // To access multiple values of the same key, call ParseForm and
1343 // then inspect Request.Form directly.
1344 func (r
*Request
) FormValue(key
string) string {
1346 r
.ParseMultipartForm(defaultMaxMemory
)
1348 if vs
:= r
.Form
[key
]; len(vs
) > 0 {
1354 // PostFormValue returns the first value for the named component of the POST,
1355 // PATCH, or PUT request body. URL query parameters are ignored.
1356 // PostFormValue calls ParseMultipartForm and ParseForm if necessary and ignores
1357 // any errors returned by these functions.
1358 // If key is not present, PostFormValue returns the empty string.
1359 func (r
*Request
) PostFormValue(key
string) string {
1360 if r
.PostForm
== nil {
1361 r
.ParseMultipartForm(defaultMaxMemory
)
1363 if vs
:= r
.PostForm
[key
]; len(vs
) > 0 {
1369 // FormFile returns the first file for the provided form key.
1370 // FormFile calls ParseMultipartForm and ParseForm if necessary.
1371 func (r
*Request
) FormFile(key
string) (multipart
.File
, *multipart
.FileHeader
, error
) {
1372 if r
.MultipartForm
== multipartByReader
{
1373 return nil, nil, errors
.New("http: multipart handled by MultipartReader")
1375 if r
.MultipartForm
== nil {
1376 err
:= r
.ParseMultipartForm(defaultMaxMemory
)
1378 return nil, nil, err
1381 if r
.MultipartForm
!= nil && r
.MultipartForm
.File
!= nil {
1382 if fhs
:= r
.MultipartForm
.File
[key
]; len(fhs
) > 0 {
1383 f
, err
:= fhs
[0].Open()
1384 return f
, fhs
[0], err
1387 return nil, nil, ErrMissingFile
1390 func (r
*Request
) expectsContinue() bool {
1391 return hasToken(r
.Header
.get("Expect"), "100-continue")
1394 func (r
*Request
) wantsHttp10KeepAlive() bool {
1395 if r
.ProtoMajor
!= 1 || r
.ProtoMinor
!= 0 {
1398 return hasToken(r
.Header
.get("Connection"), "keep-alive")
1401 func (r
*Request
) wantsClose() bool {
1405 return hasToken(r
.Header
.get("Connection"), "close")
1408 func (r
*Request
) closeBody() error
{
1412 return r
.Body
.Close()
1415 func (r
*Request
) isReplayable() bool {
1416 if r
.Body
== nil || r
.Body
== NoBody || r
.GetBody
!= nil {
1417 switch valueOrDefault(r
.Method
, "GET") {
1418 case "GET", "HEAD", "OPTIONS", "TRACE":
1421 // The Idempotency-Key, while non-standard, is widely used to
1422 // mean a POST or other request is idempotent. See
1423 // https://golang.org/issue/19943#issuecomment-421092421
1424 if r
.Header
.has("Idempotency-Key") || r
.Header
.has("X-Idempotency-Key") {
1431 // outgoingLength reports the Content-Length of this outgoing (Client) request.
1432 // It maps 0 into -1 (unknown) when the Body is non-nil.
1433 func (r
*Request
) outgoingLength() int64 {
1434 if r
.Body
== nil || r
.Body
== NoBody
{
1437 if r
.ContentLength
!= 0 {
1438 return r
.ContentLength
1443 // requestMethodUsuallyLacksBody reports whether the given request
1444 // method is one that typically does not involve a request body.
1445 // This is used by the Transport (via
1446 // transferWriter.shouldSendChunkedRequestBody) to determine whether
1447 // we try to test-read a byte from a non-nil Request.Body when
1448 // Request.outgoingLength() returns -1. See the comments in
1449 // shouldSendChunkedRequestBody.
1450 func requestMethodUsuallyLacksBody(method
string) bool {
1452 case "GET", "HEAD", "DELETE", "OPTIONS", "PROPFIND", "SEARCH":
1458 // requiresHTTP1 reports whether this request requires being sent on
1459 // an HTTP/1 connection.
1460 func (r
*Request
) requiresHTTP1() bool {
1461 return hasToken(r
.Header
.Get("Connection"), "upgrade") &&
1462 ascii
.EqualFold(r
.Header
.Get("Upgrade"), "websocket")