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