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 the [Response.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  // [Response.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  //
   209  //	Pragma: no-cache
   210  //
   211  // like
   212  //
   213  //	Cache-Control: no-cache
   214  func fixPragmaCacheControl(header Header) {
   215  	if hp, ok := header["Pragma"]; ok && len(hp) > 0 && hp[0] == "no-cache" {
   216  		if _, presentcc := header["Cache-Control"]; !presentcc {
   217  			header["Cache-Control"] = []string{"no-cache"}
   218  		}
   219  	}
   220  }
   221  
   222  // ProtoAtLeast reports whether the HTTP protocol used
   223  // in the response is at least major.minor.
   224  func (r *Response) ProtoAtLeast(major, minor int) bool {
   225  	return r.ProtoMajor > major ||
   226  		r.ProtoMajor == major && r.ProtoMinor >= minor
   227  }
   228  
   229  // Write writes r to w in the HTTP/1.x server response format,
   230  // including the status line, headers, body, and optional trailer.
   231  //
   232  // This method consults the following fields of the response r:
   233  //
   234  //	StatusCode
   235  //	ProtoMajor
   236  //	ProtoMinor
   237  //	Request.Method
   238  //	TransferEncoding
   239  //	Trailer
   240  //	Body
   241  //	ContentLength
   242  //	Header, values for non-canonical keys will have unpredictable behavior
   243  //
   244  // The Response Body is closed after it is sent.
   245  func (r *Response) Write(w io.Writer) error {
   246  	// Status line
   247  	text := r.Status
   248  	if text == "" {
   249  		text = StatusText(r.StatusCode)
   250  		if text == "" {
   251  			text = "status code " + strconv.Itoa(r.StatusCode)
   252  		}
   253  	} else {
   254  		// Just to reduce stutter, if user set r.Status to "200 OK" and StatusCode to 200.
   255  		// Not important.
   256  		text = strings.TrimPrefix(text, strconv.Itoa(r.StatusCode)+" ")
   257  	}
   258  
   259  	if _, err := fmt.Fprintf(w, "HTTP/%d.%d %03d %s\r\n", r.ProtoMajor, r.ProtoMinor, r.StatusCode, text); err != nil {
   260  		return err
   261  	}
   262  
   263  	// Clone it, so we can modify r1 as needed.
   264  	r1 := new(Response)
   265  	*r1 = *r
   266  	if r1.ContentLength == 0 && r1.Body != nil {
   267  		// Is it actually 0 length? Or just unknown?
   268  		var buf [1]byte
   269  		n, err := r1.Body.Read(buf[:])
   270  		if err != nil && err != io.EOF {
   271  			return err
   272  		}
   273  		if n == 0 {
   274  			// Reset it to a known zero reader, in case underlying one
   275  			// is unhappy being read repeatedly.
   276  			r1.Body = NoBody
   277  		} else {
   278  			r1.ContentLength = -1
   279  			r1.Body = struct {
   280  				io.Reader
   281  				io.Closer
   282  			}{
   283  				io.MultiReader(bytes.NewReader(buf[:1]), r.Body),
   284  				r.Body,
   285  			}
   286  		}
   287  	}
   288  	// If we're sending a non-chunked HTTP/1.1 response without a
   289  	// content-length, the only way to do that is the old HTTP/1.0
   290  	// way, by noting the EOF with a connection close, so we need
   291  	// to set Close.
   292  	if r1.ContentLength == -1 && !r1.Close && r1.ProtoAtLeast(1, 1) && !chunked(r1.TransferEncoding) && !r1.Uncompressed {
   293  		r1.Close = true
   294  	}
   295  
   296  	// Process Body,ContentLength,Close,Trailer
   297  	tw, err := newTransferWriter(r1)
   298  	if err != nil {
   299  		return err
   300  	}
   301  	err = tw.writeHeader(w, nil)
   302  	if err != nil {
   303  		return err
   304  	}
   305  
   306  	// Rest of header
   307  	err = r.Header.WriteSubset(w, respExcludeHeader)
   308  	if err != nil {
   309  		return err
   310  	}
   311  
   312  	// contentLengthAlreadySent may have been already sent for
   313  	// POST/PUT requests, even if zero length. See Issue 8180.
   314  	contentLengthAlreadySent := tw.shouldSendContentLength()
   315  	if r1.ContentLength == 0 && !chunked(r1.TransferEncoding) && !contentLengthAlreadySent && bodyAllowedForStatus(r.StatusCode) {
   316  		if _, err := io.WriteString(w, "Content-Length: 0\r\n"); err != nil {
   317  			return err
   318  		}
   319  	}
   320  
   321  	// End-of-header
   322  	if _, err := io.WriteString(w, "\r\n"); err != nil {
   323  		return err
   324  	}
   325  
   326  	// Write body and trailer
   327  	err = tw.writeBody(w)
   328  	if err != nil {
   329  		return err
   330  	}
   331  
   332  	// Success
   333  	return nil
   334  }
   335  
   336  func (r *Response) closeBody() {
   337  	if r.Body != nil {
   338  		r.Body.Close()
   339  	}
   340  }
   341  
   342  // bodyIsWritable reports whether the Body supports writing. The
   343  // Transport returns Writable bodies for 101 Switching Protocols
   344  // responses.
   345  // The Transport uses this method to determine whether a persistent
   346  // connection is done being managed from its perspective. Once we
   347  // return a writable response body to a user, the net/http package is
   348  // done managing that connection.
   349  func (r *Response) bodyIsWritable() bool {
   350  	_, ok := r.Body.(io.Writer)
   351  	return ok
   352  }
   353  
   354  // isProtocolSwitch reports whether the response code and header
   355  // indicate a successful protocol upgrade response.
   356  func (r *Response) isProtocolSwitch() bool {
   357  	return isProtocolSwitchResponse(r.StatusCode, r.Header)
   358  }
   359  
   360  // isProtocolSwitchResponse reports whether the response code and
   361  // response header indicate a successful protocol upgrade response.
   362  func isProtocolSwitchResponse(code int, h Header) bool {
   363  	return code == StatusSwitchingProtocols && isProtocolSwitchHeader(h)
   364  }
   365  
   366  // isProtocolSwitchHeader reports whether the request or response header
   367  // is for a protocol switch.
   368  func isProtocolSwitchHeader(h Header) bool {
   369  	return h.Get("Upgrade") != "" &&
   370  		httpguts.HeaderValuesContainsToken(h["Connection"], "Upgrade")
   371  }
   372  

View as plain text