libgo/go/net/http/client.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 client. See RFC 2616.
   6 //
   7 // This is the high-level Client interface.
   8 // The low-level implementation is in transport.go.
   9
  10 package http
  11
  12 import (
  13         "encoding/base64"
  14         "errors"
  15         "fmt"
  16         "io"
  17         "net/url"
  18         "strings"
  19 )
  20
  21 // A Client is an HTTP client. Its zero value (DefaultClient) is a usable client
  22 // that uses DefaultTransport.
  23 //
  24 // The Client's Transport typically has internal state (cached
  25 // TCP connections), so Clients should be reused instead of created as
  26 // needed. Clients are safe for concurrent use by multiple goroutines.
  27 type Client struct {
  28         // Transport specifies the mechanism by which individual
  29         // HTTP requests are made.
  30         // If nil, DefaultTransport is used.
  31         Transport RoundTripper
  32
  33         // CheckRedirect specifies the policy for handling redirects.
  34         // If CheckRedirect is not nil, the client calls it before
  35         // following an HTTP redirect. The arguments req and via
  36         // are the upcoming request and the requests made already,
  37         // oldest first. If CheckRedirect returns an error, the client
  38         // returns that error instead of issue the Request req.
  39         //
  40         // If CheckRedirect is nil, the Client uses its default policy,
  41         // which is to stop after 10 consecutive requests.
  42         CheckRedirect func(req *Request, via []*Request) error
  43
  44         // Jar specifies the cookie jar.
  45         // If Jar is nil, cookies are not sent in requests and ignored
  46         // in responses.
  47         Jar CookieJar
  48 }
  49
  50 // DefaultClient is the default Client and is used by Get, Head, and Post.
  51 var DefaultClient = &Client{}
  52
  53 // RoundTripper is an interface representing the ability to execute a
  54 // single HTTP transaction, obtaining the Response for a given Request.
  55 //
  56 // A RoundTripper must be safe for concurrent use by multiple
  57 // goroutines.
  58 type RoundTripper interface {
  59         // RoundTrip executes a single HTTP transaction, returning
  60         // the Response for the request req.  RoundTrip should not
  61         // attempt to interpret the response.  In particular,
  62         // RoundTrip must return err == nil if it obtained a response,
  63         // regardless of the response's HTTP status code.  A non-nil
  64         // err should be reserved for failure to obtain a response.
  65         // Similarly, RoundTrip should not attempt to handle
  66         // higher-level protocol details such as redirects,
  67         // authentication, or cookies.
  68         //
  69         // RoundTrip should not modify the request, except for
  70         // consuming the Body.  The request's URL and Header fields
  71         // are guaranteed to be initialized.
  72         RoundTrip(*Request) (*Response, error)
  73 }
  74
  75 // Given a string of the form "host", "host:port", or "[ipv6::address]:port",
  76 // return true if the string includes a port.
  77 func hasPort(s string) bool { return strings.LastIndex(s, ":") > strings.LastIndex(s, "]") }
  78
  79 // Used in Send to implement io.ReadCloser by bundling together the
  80 // bufio.Reader through which we read the response, and the underlying
  81 // network connection.
  82 type readClose struct {
  83         io.Reader
  84         io.Closer
  85 }
  86
  87 // Do sends an HTTP request and returns an HTTP response, following
  88 // policy (e.g. redirects, cookies, auth) as configured on the client.
  89 //
  90 // A non-nil response always contains a non-nil resp.Body.
  91 //
  92 // Callers should close resp.Body when done reading from it. If
  93 // resp.Body is not closed, the Client's underlying RoundTripper
  94 // (typically Transport) may not be able to re-use a persistent TCP
  95 // connection to the server for a subsequent "keep-alive" request.
  96 //
  97 // Generally Get, Post, or PostForm will be used instead of Do.
  98 func (c *Client) Do(req *Request) (resp *Response, err error) {
  99         if req.Method == "GET" || req.Method == "HEAD" {
 100                 return c.doFollowingRedirects(req)
 101         }
 102         return send(req, c.Transport)
 103 }
 104
 105 // send issues an HTTP request.  Caller should close resp.Body when done reading from it.
 106 func send(req *Request, t RoundTripper) (resp *Response, err error) {
 107         if t == nil {
 108                 t = DefaultTransport
 109                 if t == nil {
 110                         err = errors.New("http: no Client.Transport or DefaultTransport")
 111                         return
 112                 }
 113         }
 114
 115         if req.URL == nil {
 116                 return nil, errors.New("http: nil Request.URL")
 117         }
 118
 119         if req.RequestURI != "" {
 120                 return nil, errors.New("http: Request.RequestURI can't be set in client requests.")
 121         }
 122
 123         // Most the callers of send (Get, Post, et al) don't need
 124         // Headers, leaving it uninitialized.  We guarantee to the
 125         // Transport that this has been initialized, though.
 126         if req.Header == nil {
 127                 req.Header = make(Header)
 128         }
 129
 130         if u := req.URL.User; u != nil {
 131                 req.Header.Set("Authorization", "Basic "+base64.URLEncoding.EncodeToString([]byte(u.String())))
 132         }
 133         return t.RoundTrip(req)
 134 }
 135
 136 // True if the specified HTTP status code is one for which the Get utility should
 137 // automatically redirect.
 138 func shouldRedirect(statusCode int) bool {
 139         switch statusCode {
 140         case StatusMovedPermanently, StatusFound, StatusSeeOther, StatusTemporaryRedirect:
 141                 return true
 142         }
 143         return false
 144 }
 145
 146 // Get issues a GET to the specified URL.  If the response is one of the following
 147 // redirect codes, Get follows the redirect, up to a maximum of 10 redirects:
 148 //
 149 //    301 (Moved Permanently)
 150 //    302 (Found)
 151 //    303 (See Other)
 152 //    307 (Temporary Redirect)
 153 //
 154 // Caller should close r.Body when done reading from it.
 155 //
 156 // Get is a wrapper around DefaultClient.Get.
 157 func Get(url string) (r *Response, err error) {
 158         return DefaultClient.Get(url)
 159 }
 160
 161 // Get issues a GET to the specified URL.  If the response is one of the
 162 // following redirect codes, Get follows the redirect after calling the
 163 // Client's CheckRedirect function.
 164 //
 165 //    301 (Moved Permanently)
 166 //    302 (Found)
 167 //    303 (See Other)
 168 //    307 (Temporary Redirect)
 169 //
 170 // Caller should close r.Body when done reading from it.
 171 func (c *Client) Get(url string) (r *Response, err error) {
 172         req, err := NewRequest("GET", url, nil)
 173         if err != nil {
 174                 return nil, err
 175         }
 176         return c.doFollowingRedirects(req)
 177 }
 178
 179 func (c *Client) doFollowingRedirects(ireq *Request) (r *Response, err error) {
 180         // TODO: if/when we add cookie support, the redirected request shouldn't
 181         // necessarily supply the same cookies as the original.
 182         var base *url.URL
 183         redirectChecker := c.CheckRedirect
 184         if redirectChecker == nil {
 185                 redirectChecker = defaultCheckRedirect
 186         }
 187         var via []*Request
 188
 189         if ireq.URL == nil {
 190                 return nil, errors.New("http: nil Request.URL")
 191         }
 192
 193         jar := c.Jar
 194         if jar == nil {
 195                 jar = blackHoleJar{}
 196         }
 197
 198         req := ireq
 199         urlStr := "" // next relative or absolute URL to fetch (after first request)
 200         for redirect := 0; ; redirect++ {
 201                 if redirect != 0 {
 202                         req = new(Request)
 203                         req.Method = ireq.Method
 204                         req.Header = make(Header)
 205                         req.URL, err = base.Parse(urlStr)
 206                         if err != nil {
 207                                 break
 208                         }
 209                         if len(via) > 0 {
 210                                 // Add the Referer header.
 211                                 lastReq := via[len(via)-1]
 212                                 if lastReq.URL.Scheme != "https" {
 213                                         req.Header.Set("Referer", lastReq.URL.String())
 214                                 }
 215
 216                                 err = redirectChecker(req, via)
 217                                 if err != nil {
 218                                         break
 219                                 }
 220                         }
 221                 }
 222
 223                 for _, cookie := range jar.Cookies(req.URL) {
 224                         req.AddCookie(cookie)
 225                 }
 226                 urlStr = req.URL.String()
 227                 if r, err = send(req, c.Transport); err != nil {
 228                         break
 229                 }
 230                 if c := r.Cookies(); len(c) > 0 {
 231                         jar.SetCookies(req.URL, c)
 232                 }
 233
 234                 if shouldRedirect(r.StatusCode) {
 235                         r.Body.Close()
 236                         if urlStr = r.Header.Get("Location"); urlStr == "" {
 237                                 err = errors.New(fmt.Sprintf("%d response missing Location header", r.StatusCode))
 238                                 break
 239                         }
 240                         base = req.URL
 241                         via = append(via, req)
 242                         continue
 243                 }
 244                 return
 245         }
 246
 247         method := ireq.Method
 248         err = &url.Error{
 249                 Op:  method[0:1] + strings.ToLower(method[1:]),
 250                 URL: urlStr,
 251                 Err: err,
 252         }
 253         return
 254 }
 255
 256 func defaultCheckRedirect(req *Request, via []*Request) error {
 257         if len(via) >= 10 {
 258                 return errors.New("stopped after 10 redirects")
 259         }
 260         return nil
 261 }
 262
 263 // Post issues a POST to the specified URL.
 264 //
 265 // Caller should close r.Body when done reading from it.
 266 //
 267 // Post is a wrapper around DefaultClient.Post
 268 func Post(url string, bodyType string, body io.Reader) (r *Response, err error) {
 269         return DefaultClient.Post(url, bodyType, body)
 270 }
 271
 272 // Post issues a POST to the specified URL.
 273 //
 274 // Caller should close r.Body when done reading from it.
 275 func (c *Client) Post(url string, bodyType string, body io.Reader) (r *Response, err error) {
 276         req, err := NewRequest("POST", url, body)
 277         if err != nil {
 278                 return nil, err
 279         }
 280         req.Header.Set("Content-Type", bodyType)
 281         if c.Jar != nil {
 282                 for _, cookie := range c.Jar.Cookies(req.URL) {
 283                         req.AddCookie(cookie)
 284                 }
 285         }
 286         r, err = send(req, c.Transport)
 287         if err == nil && c.Jar != nil {
 288                 c.Jar.SetCookies(req.URL, r.Cookies())
 289         }
 290         return r, err
 291 }
 292
 293 // PostForm issues a POST to the specified URL,
 294 // with data's keys and values urlencoded as the request body.
 295 //
 296 // Caller should close r.Body when done reading from it.
 297 //
 298 // PostForm is a wrapper around DefaultClient.PostForm
 299 func PostForm(url string, data url.Values) (r *Response, err error) {
 300         return DefaultClient.PostForm(url, data)
 301 }
 302
 303 // PostForm issues a POST to the specified URL,
 304 // with data's keys and values urlencoded as the request body.
 305 //
 306 // Caller should close r.Body when done reading from it.
 307 func (c *Client) PostForm(url string, data url.Values) (r *Response, err error) {
 308         return c.Post(url, "application/x-www-form-urlencoded", strings.NewReader(data.Encode()))
 309 }
 310
 311 // Head issues a HEAD to the specified URL.  If the response is one of the
 312 // following redirect codes, Head follows the redirect after calling the
 313 // Client's CheckRedirect function.
 314 //
 315 //    301 (Moved Permanently)
 316 //    302 (Found)
 317 //    303 (See Other)
 318 //    307 (Temporary Redirect)
 319 //
 320 // Head is a wrapper around DefaultClient.Head
 321 func Head(url string) (r *Response, err error) {
 322         return DefaultClient.Head(url)
 323 }
 324
 325 // Head issues a HEAD to the specified URL.  If the response is one of the
 326 // following redirect codes, Head follows the redirect after calling the
 327 // Client's CheckRedirect function.
 328 //
 329 //    301 (Moved Permanently)
 330 //    302 (Found)
 331 //    303 (See Other)
 332 //    307 (Temporary Redirect)
 333 func (c *Client) Head(url string) (r *Response, err error) {
 334         req, err := NewRequest("HEAD", url, nil)
 335         if err != nil {
 336                 return nil, err
 337         }
 338         return c.doFollowingRedirects(req)
 339 }