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/*
6Package 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
17The 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
29For control over HTTP client headers, redirect policy, and other
30settings, 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
45For control over proxies, TLS configuration, keep-alives,
46compression, 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
56Clients and Transports are safe for concurrent use by multiple
57goroutines and for efficiency should only be created once and re-used.
58
59# Servers
60
61ListenAndServe starts an HTTP server with a given address and handler.
62The 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
73More control over the server's behavior is available by creating a
74custom 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
87Starting with Go 1.6, the http package has transparent support for the
88HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2
89can do so by setting [Transport.TLSNextProto] (for clients) or
90[Server.TLSNextProto] (for servers) to a non-nil, empty
91map. Alternatively, the following GODEBUG settings are
92currently 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
99Please report any issues before disabling HTTP/2 support: https://golang.org/s/http2bug
100
101The http package's [Transport] and [Server] both automatically enable
102HTTP/2 support for simple configurations. To enable HTTP/2 for more
103complex configurations, to use lower-level HTTP/2 features, or to use
104a newer version of Go's http2 package, import "golang.org/x/net/http2"
105directly and use its ConfigureTransport and/or ConfigureServer
106functions. Manually configuring HTTP/2 via the golang.org/x/net/http2
107package takes precedence over the net/http package's built-in HTTP/2
108support.
109*/
110package http
111