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