github.com/ooni/oohttp@v0.7.2/doc.go (about)

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