Source file src/net/http/response.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 Response reading and parsing. 6 7 package http 8 9 import ( 10 "bufio" 11 "bytes" 12 "crypto/tls" 13 "errors" 14 "fmt" 15 "io" 16 "net/textproto" 17 "net/url" 18 "strconv" 19 "strings" 20 21 "golang.org/x/net/http/httpguts" 22 ) 23 24 var respExcludeHeader = map[string]bool{ 25 "Content-Length": true, 26 "Transfer-Encoding": true, 27 "Trailer": true, 28 } 29 30 // Response represents the response from an HTTP request. 31 // 32 // The Client and Transport return Responses from servers once 33 // the response headers have been received. The response body 34 // is streamed on demand as the Body field is read. 35 type Response struct { 36 Status string // e.g. "200 OK" 37 StatusCode int // e.g. 200 38 Proto string // e.g. "HTTP/1.0" 39 ProtoMajor int // e.g. 1 40 ProtoMinor int // e.g. 0 41 42 // Header maps header keys to values. If the response had multiple 43 // headers with the same key, they may be concatenated, with comma 44 // delimiters. (RFC 7230, section 3.2.2 requires that multiple headers 45 // be semantically equivalent to a comma-delimited sequence.) When 46 // Header values are duplicated by other fields in this struct (e.g., 47 // ContentLength, TransferEncoding, Trailer), the field values are 48 // authoritative. 49 // 50 // Keys in the map are canonicalized (see CanonicalHeaderKey). 51 Header Header 52 53 // Body represents the response body. 54 // 55 // The response body is streamed on demand as the Body field 56 // is read. If the network connection fails or the server 57 // terminates the response, Body.Read calls return an error. 58 // 59 // The http Client and Transport guarantee that Body is always 60 // non-nil, even on responses without a body or responses with 61 // a zero-length body. It is the caller's responsibility to 62 // close Body. The default HTTP client's Transport may not 63 // reuse HTTP/1.x "keep-alive" TCP connections if the Body is 64 // not read to completion and closed. 65 // 66 // The Body is automatically dechunked if the server replied 67 // with a "chunked" Transfer-Encoding. 68 // 69 // As of Go 1.12, the Body will also implement io.Writer 70 // on a successful "101 Switching Protocols" response, 71 // as used by WebSockets and HTTP/2's "h2c" mode. 72 Body io.ReadCloser 73 74 // ContentLength records the length of the associated content. The 75 // value -1 indicates that the length is unknown. Unless Request.Method 76 // is "HEAD", values >= 0 indicate that the given number of bytes may 77 // be read from Body. 78 ContentLength int64 79 80 // Contains transfer encodings from outer-most to inner-most. Value is 81 // nil, means that "identity" encoding is used. 82 TransferEncoding []string 83 84 // Close records whether the header directed that the connection be 85 // closed after reading Body. The value is advice for clients: neither 86 // ReadResponse nor Response.Write ever closes a connection. 87 Close bool 88 89 // Uncompressed reports whether the response was sent compressed but 90 // was decompressed by the http package. When true, reading from 91 // Body yields the uncompressed content instead of the compressed 92 // content actually set from the server, ContentLength is set to -1, 93 // and the "Content-Length" and "Content-Encoding" fields are deleted 94 // from the responseHeader. To get the original response from 95 // the server, set Transport.DisableCompression to true. 96 Uncompressed bool 97 98 // Trailer maps trailer keys to values in the same 99 // format as Header. 100 // 101 // The Trailer initially contains only nil values, one for 102 // each key specified in the server's "Trailer" header 103 // value. Those values are not added to Header. 104 // 105 // Trailer must not be accessed concurrently with Read calls 106 // on the Body. 107 // 108 // After Body.Read has returned io.EOF, Trailer will contain 109 // any trailer values sent by the server. 110 Trailer Header 111 112 // Request is the request that was sent to obtain this Response. 113 // Request's Body is nil (having already been consumed). 114 // This is only populated for Client requests. 115 Request *Request 116 117 // TLS contains information about the TLS connection on which the 118 // response was received. It is nil for unencrypted responses. 119 // The pointer is shared between responses and should not be 120 // modified. 121 TLS *tls.ConnectionState 122 } 123 124 // Cookies parses and returns the cookies set in the Set-Cookie headers. 125 func (r *Response) Cookies() []*Cookie { 126 return readSetCookies(r.Header) 127 } 128 129 // ErrNoLocation is returned by Response's Location method 130 // when no Location header is present. 131 var ErrNoLocation = errors.New("http: no Location header in response") 132 133 // Location returns the URL of the response's "Location" header, 134 // if present. Relative redirects are resolved relative to 135 // the Response's Request. ErrNoLocation is returned if no 136 // Location header is present. 137 func (r *Response) Location() (*url.URL, error) { 138 lv := r.Header.Get("Location") 139 if lv == "" { 140 return nil, ErrNoLocation 141 } 142 if r.Request != nil && r.Request.URL != nil { 143 return r.Request.URL.Parse(lv) 144 } 145 return url.Parse(lv) 146 } 147 148 // ReadResponse reads and returns an HTTP response from r. 149 // The req parameter optionally specifies the Request that corresponds 150 // to this Response. If nil, a GET request is assumed. 151 // Clients must call resp.Body.Close when finished reading resp.Body. 152 // After that call, clients can inspect resp.Trailer to find key/value 153 // pairs included in the response trailer. 154 func ReadResponse(r *bufio.Reader, req *Request) (*Response, error) { 155 tp := textproto.NewReader(r) 156 resp := &Response{ 157 Request: req, 158 } 159 160 // Parse the first line of the response. 161 line, err := tp.ReadLine() 162 if err != nil { 163 if err == io.EOF { 164 err = io.ErrUnexpectedEOF 165 } 166 return nil, err 167 } 168 proto, status, ok := strings.Cut(line, " ") 169 if !ok { 170 return nil, badStringError("malformed HTTP response", line) 171 } 172 resp.Proto = proto 173 resp.Status = strings.TrimLeft(status, " ") 174 175 statusCode, _, _ := strings.Cut(resp.Status, " ") 176 if len(statusCode) != 3 { 177 return nil, badStringError("malformed HTTP status code", statusCode) 178 } 179 resp.StatusCode, err = strconv.Atoi(statusCode) 180 if err != nil || resp.StatusCode < 0 { 181 return nil, badStringError("malformed HTTP status code", statusCode) 182 } 183 if resp.ProtoMajor, resp.ProtoMinor, ok = ParseHTTPVersion(resp.Proto); !ok { 184 return nil, badStringError("malformed HTTP version", resp.Proto) 185 } 186 187 // Parse the response headers. 188 mimeHeader, err := tp.ReadMIMEHeader() 189 if err != nil { 190 if err == io.EOF { 191 err = io.ErrUnexpectedEOF 192 } 193 return nil, err 194 } 195 resp.Header = Header(mimeHeader) 196 197 fixPragmaCacheControl(resp.Header) 198 199 err = readTransfer(resp, r) 200 if err != nil { 201 return nil, err 202 } 203 204 return resp, nil 205 } 206 207 // RFC 7234, section 5.4: Should treat 208 // Pragma: no-cache 209 // like 210 // Cache-Control: no-cache 211 func fixPragmaCacheControl(header Header) { 212 if hp, ok := header["Pragma"]; ok && len(hp) > 0 && hp[0] == "no-cache" { 213 if _, presentcc := header["Cache-Control"]; !presentcc { 214 header["Cache-Control"] = []string{"no-cache"} 215 } 216 } 217 } 218 219 // ProtoAtLeast reports whether the HTTP protocol used 220 // in the response is at least major.minor. 221 func (r *Response) ProtoAtLeast(major, minor int) bool { 222 return r.ProtoMajor > major || 223 r.ProtoMajor == major && r.ProtoMinor >= minor 224 } 225 226 // Write writes r to w in the HTTP/1.x server response format, 227 // including the status line, headers, body, and optional trailer. 228 // 229 // This method consults the following fields of the response r: 230 // 231 // StatusCode 232 // ProtoMajor 233 // ProtoMinor 234 // Request.Method 235 // TransferEncoding 236 // Trailer 237 // Body 238 // ContentLength 239 // Header, values for non-canonical keys will have unpredictable behavior 240 // 241 // The Response Body is closed after it is sent. 242 func (r *Response) Write(w io.Writer) error { 243 // Status line 244 text := r.Status 245 if text == "" { 246 var ok bool 247 text, ok = statusText[r.StatusCode] 248 if !ok { 249 text = "status code " + strconv.Itoa(r.StatusCode) 250 } 251 } else { 252 // Just to reduce stutter, if user set r.Status to "200 OK" and StatusCode to 200. 253 // Not important. 254 text = strings.TrimPrefix(text, strconv.Itoa(r.StatusCode)+" ") 255 } 256 257 if _, err := fmt.Fprintf(w, "HTTP/%d.%d %03d %s\r\n", r.ProtoMajor, r.ProtoMinor, r.StatusCode, text); err != nil { 258 return err 259 } 260 261 // Clone it, so we can modify r1 as needed. 262 r1 := new(Response) 263 *r1 = *r 264 if r1.ContentLength == 0 && r1.Body != nil { 265 // Is it actually 0 length? Or just unknown? 266 var buf [1]byte 267 n, err := r1.Body.Read(buf[:]) 268 if err != nil && err != io.EOF { 269 return err 270 } 271 if n == 0 { 272 // Reset it to a known zero reader, in case underlying one 273 // is unhappy being read repeatedly. 274 r1.Body = NoBody 275 } else { 276 r1.ContentLength = -1 277 r1.Body = struct { 278 io.Reader 279 io.Closer 280 }{ 281 io.MultiReader(bytes.NewReader(buf[:1]), r.Body), 282 r.Body, 283 } 284 } 285 } 286 // If we're sending a non-chunked HTTP/1.1 response without a 287 // content-length, the only way to do that is the old HTTP/1.0 288 // way, by noting the EOF with a connection close, so we need 289 // to set Close. 290 if r1.ContentLength == -1 && !r1.Close && r1.ProtoAtLeast(1, 1) && !chunked(r1.TransferEncoding) && !r1.Uncompressed { 291 r1.Close = true 292 } 293 294 // Process Body,ContentLength,Close,Trailer 295 tw, err := newTransferWriter(r1) 296 if err != nil { 297 return err 298 } 299 err = tw.writeHeader(w, nil) 300 if err != nil { 301 return err 302 } 303 304 // Rest of header 305 err = r.Header.WriteSubset(w, respExcludeHeader) 306 if err != nil { 307 return err 308 } 309 310 // contentLengthAlreadySent may have been already sent for 311 // POST/PUT requests, even if zero length. See Issue 8180. 312 contentLengthAlreadySent := tw.shouldSendContentLength() 313 if r1.ContentLength == 0 && !chunked(r1.TransferEncoding) && !contentLengthAlreadySent && bodyAllowedForStatus(r.StatusCode) { 314 if _, err := io.WriteString(w, "Content-Length: 0\r\n"); err != nil { 315 return err 316 } 317 } 318 319 // End-of-header 320 if _, err := io.WriteString(w, "\r\n"); err != nil { 321 return err 322 } 323 324 // Write body and trailer 325 err = tw.writeBody(w) 326 if err != nil { 327 return err 328 } 329 330 // Success 331 return nil 332 } 333 334 func (r *Response) closeBody() { 335 if r.Body != nil { 336 r.Body.Close() 337 } 338 } 339 340 // bodyIsWritable reports whether the Body supports writing. The 341 // Transport returns Writable bodies for 101 Switching Protocols 342 // responses. 343 // The Transport uses this method to determine whether a persistent 344 // connection is done being managed from its perspective. Once we 345 // return a writable response body to a user, the net/http package is 346 // done managing that connection. 347 func (r *Response) bodyIsWritable() bool { 348 _, ok := r.Body.(io.Writer) 349 return ok 350 } 351 352 // isProtocolSwitch reports whether the response code and header 353 // indicate a successful protocol upgrade response. 354 func (r *Response) isProtocolSwitch() bool { 355 return isProtocolSwitchResponse(r.StatusCode, r.Header) 356 } 357 358 // isProtocolSwitchResponse reports whether the response code and 359 // response header indicate a successful protocol upgrade response. 360 func isProtocolSwitchResponse(code int, h Header) bool { 361 return code == StatusSwitchingProtocols && isProtocolSwitchHeader(h) 362 } 363 364 // isProtocolSwitchHeader reports whether the request or response header 365 // is for a protocol switch. 366 func isProtocolSwitchHeader(h Header) bool { 367 return h.Get("Upgrade") != "" && 368 httpguts.HeaderValuesContainsToken(h["Connection"], "Upgrade") 369 } 370