code review 4239044: http: expose Client's Transport

src/pkg/http/client.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.
 
 // Primitive HTTP client. See RFC 2616.
 
 package http
 
 import (
         "bytes"
         "encoding/base64"
         "fmt"
         "io"
         "os"
         "strconv"
         "strings"
 )
 
-// A Client is an HTTP client.
-// It is not yet possible to create custom Clients; use DefaultClient.
+// A Client is an HTTP client. Its zero value (DefaultClient) is a usable client
+// that uses DefaultTransport.
+// Client is not yet very configurable.
 type Client struct {
         Transport ClientTransport // if nil, DefaultTransport is used
-
-        unused int // prevent instantiation; there will likely be internal state in the future
 }
 
 // DefaultClient is the default Client and is used by Get, Head, and Post.
 var DefaultClient = &Client{}
-
-// NewClient returns a new Client which you can then initialize as needed.
-func NewClient() *Client {
-        return &Client{}
-}
 
 // ClientTransport is an interface representing the ability to execute a
 // single HTTP transaction, obtaining the Response for a given Request.
 type ClientTransport interface {
         // Do executes a single HTTP transaction, returning the Response for the
         // request req.  Do should not attempt to interpret the response.
         // In particular, Do must return err == nil if it obtained a response,
         // regardless of the response's HTTP status code.  A non-nil err should
         // be reserved for failure to obtain a response.  Similarly, Do should
         // not attempt to handle higher-level protocol details such as redirects,
@@ skipping 43 matching lines @@
                 if addr == p || (p[0] == '.' && (strings.HasSuffix(addr, p) || addr == p[1:])) {
                         return true
                 }
         }
         return false
 }
 
 // Do sends an HTTP request and returns an HTTP response, following
 // policy (e.g. redirects, cookies, auth) as configured on the client.
 //
-// Callers should close resp.Body when done reading it.
+// Callers should close resp.Body when done reading from it.
 //
 // Generally Get, Post, or PostForm will be used instead of Do.
 func (c *Client) Do(req *Request) (resp *Response, err os.Error) {
         return send(req, c.Transport)
 }
 
 
-// send issues an HTTP request.  Caller should close resp.Body when done reading it.
+// send issues an HTTP request.  Caller should close resp.Body when done reading from it.
 //
 // TODO: support persistent connections (multiple requests on a single connection).
 // send() method is nonpublic because, when we refactor the code for persistent
 // connections, it may no longer make sense to have a method with this signature.
 func send(req *Request, t ClientTransport) (resp *Response, err os.Error) {
         if t == nil {
                 t = DefaultTransport
                 if t == nil {
                         err = os.NewError("no http.Client.Transport or http.DefaultTransport")
                         return
@@ skipping 26 matching lines @@
 // redirect codes, it follows the redirect, up to a maximum of 10 redirects:
 //
 //    301 (Moved Permanently)
 //    302 (Found)
 //    303 (See Other)
 //    307 (Temporary Redirect)
 //
 // finalURL is the URL from which the response was fetched -- identical to the
 // input URL unless redirects were followed.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 //
 // Get is a convenience wrapper around DefaultClient.Get.
 func Get(url string) (r *Response, finalURL string, err os.Error) {
         return DefaultClient.Get(url)
 }
 
 // Get issues a GET to the specified URL.  If the response is one of the following
 // redirect codes, it follows the redirect, up to a maximum of 10 redirects:
 //
 //    301 (Moved Permanently)
 //    302 (Found)
 //    303 (See Other)
 //    307 (Temporary Redirect)
 //
 // finalURL is the URL from which the response was fetched -- identical to the
 // input URL unless redirects were followed.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 func (c *Client) Get(url string) (r *Response, finalURL string, err os.Error) {
         // TODO: if/when we add cookie support, the redirected request shouldn't
         // necessarily supply the same cookies as the original.
         // TODO: set referrer header on redirects.
         var base *URL
         // TODO: remove this hard-coded 10 and use the Client's policy
         // (ClientConfig) instead.
         for redirect := 0; ; redirect++ {
                 if redirect >= 10 {
                         err = os.ErrorString("stopped after 10 redirects")
@@ skipping 28 matching lines @@
                 finalURL = url
                 return
         }
 
         err = &URLError{"Get", url, err}
         return
 }
 
 // Post issues a POST to the specified URL.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 //
 // Post is a wrapper around DefaultClient.Post
 func Post(url string, bodyType string, body io.Reader) (r *Response, err os.Error) {
         return DefaultClient.Post(url, bodyType, body)
 }
 
 // Post issues a POST to the specified URL.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 func (c *Client) Post(url string, bodyType string, body io.Reader) (r *Response, err os.Error) {
         var req Request
         req.Method = "POST"
         req.ProtoMajor = 1
         req.ProtoMinor = 1
         req.Close = true
         req.Body = nopCloser{body}
         req.Header = Header{
                 "Content-Type": {bodyType},
         }
         req.TransferEncoding = []string{"chunked"}
 
         req.URL, err = ParseURL(url)
         if err != nil {
                 return nil, err
         }
 
         return send(&req, c.Transport)
 }
 
 // PostForm issues a POST to the specified URL,·
 // with data's keys and values urlencoded as the request body.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 //
 // PostForm is a wrapper around DefaultClient.PostForm
 func PostForm(url string, data map[string]string) (r *Response, err os.Error) {
         return DefaultClient.PostForm(url, data)
 }
 
 // PostForm issues a POST to the specified URL,·
 // with data's keys and values urlencoded as the request body.
 //
-// Caller should close r.Body when done reading it.
+// Caller should close r.Body when done reading from it.
 func (c *Client) PostForm(url string, data map[string]string) (r *Response, err os.Error) {
         var req Request
         req.Method = "POST"
         req.ProtoMajor = 1
         req.ProtoMinor = 1
         req.Close = true
         body := urlencode(data)
         req.Body = nopCloser{body}
         req.Header = Header{
                 "Content-Type":   {"application/x-www-form-urlencoded"},
@@ skipping 33 matching lines @@
                 return
         }
         return send(&req, c.Transport)
 }
 
 type nopCloser struct {
         io.Reader
 }
 
 func (nopCloser) Close() os.Error { return nil }