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