code review 4607052: os.Error API: don't export os.ErrorString, use os.NewEr...

src/pkg/http/request.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // HTTP Request reading and parsing.
 
 // Package http implements parsing of HTTP requests, replies, and URLs and
 // provides an extensible HTTP server and a basic HTTP client.
 package http
 
@@ skipping 21 matching lines @@
         chunkSize        = 4 << 10  // 4 KB chunks
         defaultMaxMemory = 32 << 20 // 32 MB
 )
 
 // ErrMissingFile is returned by FormFile when the provided file field name
 // is either not present in the request or not a file field.
 var ErrMissingFile = os.NewError("http: no such file")
 
 // HTTP request parsing errors.
 type ProtocolError struct {
-        os.Error
-}
+        ErrorString string
+}
+
+func (err *ProtocolError) String() string { return err.ErrorString }
 
 var (
-        ErrLineTooLong          = &ProtocolError{os.NewError("header line too long")}
-        ErrHeaderTooLong        = &ProtocolError{os.NewError("header too long")}
-        ErrShortBody            = &ProtocolError{os.NewError("entity body too short")}
-        ErrNotSupported         = &ProtocolError{os.NewError("feature not supported")}
-        ErrUnexpectedTrailer    = &ProtocolError{os.NewError("trailer header without chunked transfer encoding")}
-        ErrMissingContentLength = &ProtocolError{os.NewError("missing ContentLength in HEAD response")}
-        ErrNotMultipart         = &ProtocolError{os.NewError("request Content-Type isn't multipart/form-data")}
-        ErrMissingBoundary      = &ProtocolError{os.NewError("no multipart boundary param Content-Type")}
+        ErrLineTooLong          = &ProtocolError{"header line too long"}
+        ErrHeaderTooLong        = &ProtocolError{"header too long"}
+        ErrShortBody            = &ProtocolError{"entity body too short"}
+        ErrNotSupported         = &ProtocolError{"feature not supported"}
+        ErrUnexpectedTrailer    = &ProtocolError{"trailer header without chunked transfer encoding"}
+        ErrMissingContentLength = &ProtocolError{"missing ContentLength in HEAD response"}
+        ErrNotMultipart         = &ProtocolError{"request Content-Type isn't multipart/form-data"}
+        ErrMissingBoundary      = &ProtocolError{"no multipart boundary param Content-Type"}
 )
 
 type badStringError struct {
         what string
         str  string
 }
 
 func (e *badStringError) String() string { return fmt.Sprintf("%s %q", e.what, e.str) }
 
-var reqExcludeHeader = map[string]bool{
+// Headers that Request.Write handles itself and should be skipped.
+var reqWriteExcludeHeader = map[string]bool{
         "Host":              true,
         "User-Agent":        true,
-        "Referer":           true,
         "Content-Length":    true,
         "Transfer-Encoding": true,
         "Trailer":           true,
 }
 
 // A Request represents a parsed HTTP request header.
 type Request struct {
         Method string // GET, POST, PUT, etc.
         RawURL string // The raw URL given in the request.
         URL    *URL   // Parsed URL.
@@ skipping 18 matching lines @@
         //              "Accept-Language": {"en-us"},
         //              "Connection": {"keep-alive"},
         //      }
         //
         // HTTP defines that header names are case-insensitive.
         // The request parser implements this by canonicalizing the
         // name, making the first character and any characters
         // following a hyphen uppercase and the rest lowercase.
         Header Header
 
-        // Cookie records the HTTP cookies sent with the request.
-        Cookie []*Cookie
-
         // The message body.
         Body io.ReadCloser
 
         // ContentLength records the length of the associated content.
         // The value -1 indicates that the length is unknown.
         // Values >= 0 indicate that the given number of bytes may be read from Body.
         ContentLength int64
 
         // TransferEncoding lists the transfer encodings from outermost to innermost.
         // An empty list denotes the "identity" encoding.
         TransferEncoding []string
 
         // Whether to close the connection after replying to this request.
         Close bool
 
         // The host on which the URL is sought.
         // Per RFC 2616, this is either the value of the Host: header
         // or the host name given in the URL itself.
         Host string
-
-        // The referring URL, if sent in the request.
-        //
-        // Referer is misspelled as in the request itself,
-        // a mistake from the earliest days of HTTP.
-        // This value can also be fetched from the Header map
-        // as Header["Referer"]; the benefit of making it
-        // available as a structure field is that the compiler
-        // can diagnose programs that use the alternate
-        // (correct English) spelling req.Referrer but cannot
-        // diagnose programs that use Header["Referrer"].
-        Referer string
-
-        // The User-Agent: header string, if sent in the request.
-        UserAgent string
 
         // The parsed form. Only available after ParseForm is called.
         Form Values
 
         // The parsed multipart form, including file uploads.
         // Only available after ParseMultipartForm is called.
         MultipartForm *multipart.Form
 
         // Trailer maps trailer keys to values.  Like for Header, if the
         // response has multiple trailer lines with the same key, they will be
@@ skipping 17 matching lines @@
         TLS *tls.ConnectionState
 }
 
 // ProtoAtLeast returns whether the HTTP protocol used
 // in the request is at least major.minor.
 func (r *Request) ProtoAtLeast(major, minor int) bool {
         return r.ProtoMajor > major ||
                 r.ProtoMajor == major && r.ProtoMinor >= minor
 }
 
+// UserAgent returns the client's User-Agent, if sent in the request.
+func (r *Request) UserAgent() string {
+        return r.Header.Get("User-Agent")
+}
+
+// Cookies parses and returns the HTTP cookies sent with the request.
+func (r *Request) Cookies() []*Cookie {
+        return readCookies(r.Header, "")
+}
+
+var ErrNoCookie = os.NewError("http: named cookied not present")
+
+// Cookie returns the named cookie provided in the request or
+// ErrNoCookie if not found.
+func (r *Request) Cookie(name string) (*Cookie, os.Error) {
+        for _, c := range readCookies(r.Header, name) {
+                return c, nil
+        }
+        return nil, ErrNoCookie
+}
+
+// AddCookie adds a cookie to the request.  Per RFC 6265 section 5.4,
+// AddCookie does not attach more than one Cookie header field.  That
+// means all cookies, if any, are written into the same line,
+// separated by semicolon.
+func (r *Request) AddCookie(c *Cookie) {
+        s := fmt.Sprintf("%s=%s", sanitizeName(c.Name), sanitizeValue(c.Value))
+        if c := r.Header.Get("Cookie"); c != "" {
+                r.Header.Set("Cookie", c+"; "+s)
+        } else {
+                r.Header.Set("Cookie", s)
+        }
+}
+
+// Referer returns the referring URL, if sent in the request.
+//
+// Referer is misspelled as in the request itself, a mistake from the
+// earliest days of HTTP.  This value can also be fetched from the
+// Header map as Header["Referer"]; the benefit of making it available
+// as a method is that the compiler can diagnose programs that use the
+// alternate (correct English) spelling req.Referrer() but cannot
+// diagnose programs that use Header["Referrer"].
+func (r *Request) Referer() string {
+        return r.Header.Get("Referer")
+}
+
 // multipartByReader is a sentinel value.
 // Its presence in Request.MultipartForm indicates that parsing of the request
 // body has been handed off to a MultipartReader instead of ParseMultipartFrom.
 var multipartByReader = &multipart.Form{
         Value: make(map[string][]string),
         File:  make(map[string][]*multipart.FileHeader),
 }
 
 // MultipartReader returns a MIME multipart reader if this is a
 // multipart/form-data POST request, else returns nil and an error.
 // Use this function instead of ParseMultipartForm to
 // process the request body as a stream.
-func (r *Request) MultipartReader() (multipart.Reader, os.Error) {
+func (r *Request) MultipartReader() (*multipart.Reader, os.Error) {
         if r.MultipartForm == multipartByReader {
                 return nil, os.NewError("http: MultipartReader called twice")
         }
         if r.MultipartForm != nil {
                 return nil, os.NewError("http: multipart handled by ParseMultipartForm")
         }
         r.MultipartForm = multipartByReader
         return r.multipartReader()
 }
 
-func (r *Request) multipartReader() (multipart.Reader, os.Error) {
+func (r *Request) multipartReader() (*multipart.Reader, os.Error) {
         v := r.Header.Get("Content-Type")
         if v == "" {
                 return nil, ErrNotMultipart
         }
         d, params := mime.ParseMediaType(v)
         if d != "multipart/form-data" {
                 return nil, ErrNotMultipart
         }
         boundary, ok := params["boundary"]
         if !ok {
@@ skipping 10 matching lines @@
         return def
 }
 
 const defaultUserAgent = "Go http package"
 
 // Write writes an HTTP/1.1 request -- header and body -- in wire format.
 // This method consults the following fields of req:
 //      Host
 //      RawURL, if non-empty, or else URL
 //      Method (defaults to "GET")
-//      UserAgent (defaults to defaultUserAgent)
-//      Referer
-//      Header (only keys not already in this list)
-//      Cookie
+//      Header
 //      ContentLength
 //      TransferEncoding
 //      Body
 //
 // If Body is present, Content-Length is <= 0 and TransferEncoding
 // hasn't been set to "identity", Write adds "Transfer-Encoding:
 // chunked" to the header. Body is closed after it is sent.
 func (req *Request) Write(w io.Writer) os.Error {
         return req.write(w, false)
 }
@@ skipping 27 matching lines @@
                                 uri = "/" + uri
                         }
                         uri = req.URL.Scheme + "://" + host + uri
                 }
         }
 
         fmt.Fprintf(w, "%s %s HTTP/1.1\r\n", valueOrDefault(req.Method, "GET"), uri)
 
         // Header lines
         fmt.Fprintf(w, "Host: %s\r\n", host)
-        fmt.Fprintf(w, "User-Agent: %s\r\n", valueOrDefault(req.UserAgent, defaultUserAgent))
-        if req.Referer != "" {
-                fmt.Fprintf(w, "Referer: %s\r\n", req.Referer)
+
+        // Use the defaultUserAgent unless the Header contains one, which
+        // may be blank to not send the header.
+        userAgent := defaultUserAgent
+        if req.Header != nil {
+                if ua := req.Header["User-Agent"]; len(ua) > 0 {
+                        userAgent = ua[0]
+                }
+        }
+        if userAgent != "" {
+                fmt.Fprintf(w, "User-Agent: %s\r\n", userAgent)
         }
 
         // Process Body,ContentLength,Close,Trailer
         tw, err := newTransferWriter(req)
         if err != nil {
                 return err
         }
         err = tw.WriteHeader(w)
         if err != nil {
                 return err
         }
 
         // TODO: split long values?  (If so, should share code with Conn.Write)
-        // TODO: if Header includes values for Host, User-Agent, or Referer, this
-        // may conflict with the User-Agent or Referer headers we add manually.
-        // One solution would be to remove the Host, UserAgent, and Referer fields
-        // from Request, and introduce Request methods along the lines of
-        // Response.{GetHeader,AddHeader} and string constants for "Host",
-        // "User-Agent" and "Referer".
-        err = req.Header.WriteSubset(w, reqExcludeHeader)
+        err = req.Header.WriteSubset(w, reqWriteExcludeHeader)
         if err != nil {
-                return err
-        }
-
-        if err = writeCookies(w, req.Cookie); err != nil {
                 return err
         }
 
         io.WriteString(w, "\r\n")
 
         // Write body and trailer
         err = tw.WriteBody(w)
         if err != nil {
                 return err
         }
@@ skipping 229 matching lines @@
         //      GET http://www.google.com/index.html HTTP/1.1
         //      Host: doesntmatter
         // the same.  In the second case, any Host line is ignored.
         req.Host = req.URL.Host
         if req.Host == "" {
                 req.Host = req.Header.Get("Host")
         }
         req.Header.Del("Host")
 
         fixPragmaCacheControl(req.Header)
-
-        // Pull out useful fields as a convenience to clients.
-        req.Referer = req.Header.Get("Referer")
-        req.Header.Del("Referer")
-
-        req.UserAgent = req.Header.Get("User-Agent")
-        req.Header.Del("User-Agent")
 
         // TODO: Parse specific header values:
         //      Accept
         //      Accept-Encoding
         //      Accept-Language
         //      Authorization
         //      Cache-Control
         //      Connection
         //      Date
         //      Expect
@@ skipping 12 matching lines @@
         //      Upgrade
         //      User-Agent
         //      Via
         //      Warning
 
         err = readTransfer(req, b)
         if err != nil {
                 return nil, err
         }
 
-        req.Cookie = readCookies(req.Header)
-
         return req, nil
 }
 
 // Values maps a string key to a list of values.
 // It is typically used for query parameters and form values.
 // Unlike in the Header map, the keys in a Values map
 // are case-sensitive.
 type Values map[string][]string
 
 // Get gets the first value associated with the given key.
@@ skipping 182 matching lines @@
 func (r *Request) expectsContinue() bool {
         return strings.ToLower(r.Header.Get("Expect")) == "100-continue"
 }
 
 func (r *Request) wantsHttp10KeepAlive() bool {
         if r.ProtoMajor != 1 || r.ProtoMinor != 0 {
                 return false
         }
         return strings.Contains(strings.ToLower(r.Header.Get("Connection")), "keep-alive")
 }