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 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  The http package has transparent support for the HTTP/2 protocol.
    88  
    89  [Server] and [DefaultTransport] automatically enable HTTP/2 support
    90  when using HTTPS. [Transport] does not enable HTTP/2 by default.
    91  
    92  To enable or disable support for HTTP/1, HTTP/2, and/or unencrypted HTTP/2,
    93  see the [Server.Protocols] and [Transport.Protocols] configuration fields.
    94  
    95  To configure advanced HTTP/2 features, see the [Server.HTTP2] and
    96  [Transport.HTTP2] configuration fields.
    97  
    98  Alternatively, the following GODEBUG settings are currently supported:
    99  
   100  	GODEBUG=http2client=0  # disable HTTP/2 client support
   101  	GODEBUG=http2server=0  # disable HTTP/2 server support
   102  	GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
   103  	GODEBUG=http2debug=2   # ... even more verbose, with frame dumps
   104  
   105  The "omithttp2" build tag may be used to disable the HTTP/2 implementation
   106  contained in the http package.
   107  */
   108  
   109  package http
   110
View as plain text