libgo/go/net/http/doc.go

   1 // Copyright 2011 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 /*
   6 Package http provides HTTP client and server implementations.
   7
   8 Get, Head, Post, and PostForm make HTTP (or HTTPS) requests:
   9
  10         resp, err := http.Get("http://example.com/")
  11         ...
  12         resp, err := http.Post("http://example.com/upload", "image/jpeg", &buf)
  13         ...
  14         resp, err := http.PostForm("http://example.com/form",
  15                 url.Values{"key": {"Value"}, "id": {"123"}})
  16
  17 The client must close the response body when finished with it:
  18
  19         resp, err := http.Get("http://example.com/")
  20         if err != nil {
  21                 // handle error
  22         }
  23         defer resp.Body.Close()
  24         body, err := ioutil.ReadAll(resp.Body)
  25         // ...
  26
  27 For control over HTTP client headers, redirect policy, and other
  28 settings, create a Client:
  29
  30         client := &http.Client{
  31                 CheckRedirect: redirectPolicyFunc,
  32         }
  33
  34         resp, err := client.Get("http://example.com")
  35         // ...
  36
  37         req, err := http.NewRequest("GET", "http://example.com", nil)
  38         // ...
  39         req.Header.Add("If-None-Match", `W/"wyzzy"`)
  40         resp, err := client.Do(req)
  41         // ...
  42
  43 For control over proxies, TLS configuration, keep-alives,
  44 compression, and other settings, create a Transport:
  45
  46         tr := &http.Transport{
  47                 MaxIdleConns:       10,
  48                 IdleConnTimeout:    30 * time.Second,
  49                 DisableCompression: true,
  50         }
  51         client := &http.Client{Transport: tr}
  52         resp, err := client.Get("https://example.com")
  53
  54 Clients and Transports are safe for concurrent use by multiple
  55 goroutines and for efficiency should only be created once and re-used.
  56
  57 ListenAndServe starts an HTTP server with a given address and handler.
  58 The handler is usually nil, which means to use DefaultServeMux.
  59 Handle and HandleFunc add handlers to DefaultServeMux:
  60
  61         http.Handle("/foo", fooHandler)
  62
  63         http.HandleFunc("/bar", func(w http.ResponseWriter, r *http.Request) {
  64                 fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
  65         })
  66
  67         log.Fatal(http.ListenAndServe(":8080", nil))
  68
  69 More control over the server's behavior is available by creating a
  70 custom Server:
  71
  72         s := &http.Server{
  73                 Addr:           ":8080",
  74                 Handler:        myHandler,
  75                 ReadTimeout:    10 * time.Second,
  76                 WriteTimeout:   10 * time.Second,
  77                 MaxHeaderBytes: 1 << 20,
  78         }
  79         log.Fatal(s.ListenAndServe())
  80
  81 Starting with Go 1.6, the http package has transparent support for the
  82 HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2
  83 can do so by setting Transport.TLSNextProto (for clients) or
  84 Server.TLSNextProto (for servers) to a non-nil, empty
  85 map. Alternatively, the following GODEBUG environment variables are
  86 currently supported:
  87
  88         GODEBUG=http2client=0  # disable HTTP/2 client support
  89         GODEBUG=http2server=0  # disable HTTP/2 server support
  90         GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
  91         GODEBUG=http2debug=2   # ... even more verbose, with frame dumps
  92
  93 The GODEBUG variables are not covered by Go's API compatibility
  94 promise. Please report any issues before disabling HTTP/2
  95 support: https://golang.org/s/http2bug
  96
  97 The http package's Transport and Server both automatically enable
  98 HTTP/2 support for simple configurations. To enable HTTP/2 for more
  99 complex configurations, to use lower-level HTTP/2 features, or to use
 100 a newer version of Go's http2 package, import "golang.org/x/net/http2"
 101 directly and use its ConfigureTransport and/or ConfigureServer
 102 functions. Manually configuring HTTP/2 via the golang.org/x/net/http2
 103 package takes precedence over the net/http package's built-in HTTP/2
 104 support.
 105
 106 */
 107 package http