From 8cca427d17d56cfa7bdf63386bc78cf946ecb5bf Mon Sep 17 00:00:00 2001 From: Damien Neil Date: Mon, 14 Nov 2022 16:28:57 -0800 Subject: [PATCH] doc/go1.20: add release notes for net/http and net/http/httputil For #41773 For #41773 For #50465 For #51914 For #53002 For #53896 For #53960 For #54136 For #54299 Change-Id: I729d5eafc1940d5706f980882a08ece1f69bb42c Reviewed-on: https://go-review.googlesource.com/c/go/+/450515 Auto-Submit: Damien Neil TryBot-Result: Gopher Robot Run-TryBot: Damien Neil Reviewed-by: Ian Lance Taylor --- doc/go1.20.html | 143 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 119 insertions(+), 24 deletions(-) diff --git a/doc/go1.20.html b/doc/go1.20.html index 25ece4de0b..509cab9253 100644 --- a/doc/go1.20.html +++ b/doc/go1.20.html @@ -187,6 +187,87 @@ Do not send CLs removing the interior tags from such phrases. returns an error wrapping a list of errors.

+

HTTP ResponseController

+ +

+ The new + "net/http".ResponseController + type provides access to extended per-request functionality not handled by the + "net/http".ResponseWriter interface. +

+ +

+ Previously, we have added new per-request functionality by defining optional + interfaces which a ResponseWriter can implement, such as + Flusher. These interfaces + are not discoverable and clumsy to use. +

+ +

+ The ResponseController type provides a clearer, more discoverable way + to add per-handler controls. Two such controls also added in Go 1.20 are + SetReadDeadline and SetWriteDeadline, which allow setting + per-request read and write deadlines. For example: +

+ +
+func RequestHandler(w ResponseWriter, r *Request) {
+  rc := http.NewResponseController(w)
+  rc.SetWriteDeadline(0) // disable Server.WriteTimeout when sending a large response
+  io.Copy(w, bigData)
+}
+
+ +

New ReverseProxy Rewrite hook

+ +

+ The httputil.ReverseProxy + forwarding proxy includes a new Rewrite hook function, superseding the + previous Director hook. +

+ +

+ The Rewrite hook accepts a + ProxyRequest parameter, + which includes both the inbound request received by the proxy and the outbound + request that it will send. + Unlike Director hooks, which only operate on the outbound request, + this permits Rewrite hooks to avoid certain scenarios where + a malicious inbound request may cause headers added by the hook + to be removed before forwarding. + See issue #50580. +

+ +

+ The ProxyRequest.SetURL + method routes the outbound request to a provided destination + and supersedes the NewSingleHostReverseProxy function. + Unlike NewSingleHostReverseProxy, SetURL + also sets the Host header of the outbound request. +

+ +

+ The + ProxyRequest.SetXForwarded + method sets the X-Forwarded-For, X-Forwarded-Host, + and X-Forwarded-Proto headers of the outbound request. + When using a Rewrite, these headers are not added by default. +

+ +

+ An example of a Rewrite hook using these features is: +

+ +
+proxyHandler := &httputil.ReverseProxy{
+  Rewrite: func(r *httputil.ProxyRequest) {
+    r.SetURL(outboundURL) // Forward request to outboundURL.
+    r.SetXForwarded()     // Set X-Forwarded-* headers.
+    r.Out.Header.Set("X-Additional-Header", "header set by the proxy")
+  },
+}
+
+

Minor changes to the library

@@ -476,56 +557,70 @@ Do not send CLs removing the interior tags from such phrases.

net/http
-

- TODO: https://go.dev/issue/41773: add Server.OptionsHandler to allow custom handling of OPTIONS * -

+

+ The new ResponseController type provides access to extended per-request + functionality not handled by the ResponseWriter interface. +

-

- TODO: https://go.dev/cl/356410: net/http: add Server.DisableOptionsHandler for custom handling of OPTIONS *; modified api/next/41773.txt +

+ The new ResponseController.SetReadDeadline and + ResponseController.SetWriteDeadline methods permit setting + per-request read and write deadlines.

- TODO: https://go.dev/issue/51914: support for the 103 status code + The ResponseWriter.WriteHeader function now supports sending + 1xx status codes.

-

- TODO: https://go.dev/issue/53896: easier access to HTTP/2 error codes +

+ The new Server.DisableGeneralOptionsHandler configuration setting + allows disabling the default OPTIONS * handler.

- TODO: https://go.dev/issue/54299: add Transport.OnProxyConnectResponse + The new Transport.OnProxyConnectResponse hook is called + when a Transport receives an HTTP response from a proxy + for a CONNECT request.

-

- TODO: https://go.dev/cl/418614: net/http: accept HEAD requests with a body; accept HEAD requests with a body +

+ The HTTP server now accepts HEAD requests containing a body, + rather than rejecting them as invalid.

-

- TODO: https://go.dev/cl/436890: net/http: add ResponseController and per-handler timeouts; modified api/next/54136.txt +

+ HTTP/2 stream errors returned by net/http functions may be converted + to a "golang.org/x/net/http2".StreamError using errors.As.

-

- TODO: https://go.dev/cl/447216: net/http: add Transport.OnProxyConnectResponse; modified api/next/54299.txt +

+ Leading and trailing spaces are trimmed from cookie names, + rather than being rejected as invalid. + For example, a cookie setting of "name =value" + is now accepted as setting the cookie "name".

net/http/httputil
-

- TODO: https://go.dev/issue/50465: add X-Forwarded-Proto and X-Forwarded-Host by default -

-

- TODO: https://go.dev/issue/53002: replace Director with Rewrite + The new ReverseProxy hook supersedes the existing Rewrite hook.

-

- TODO: https://go.dev/cl/407214: net/http/httputil: add ReverseProxy.Rewrite; modified api/next/53002.txt +

+ ReverseProxy now adds + X-Forwarded-Proto and X-Forwarded-Host headers + to forwarded requests. + These headers are added to all requests forwarded by a Director hook, + and to requests forwarded by a Rewrite hook which calls the + ProxyRequest.SetXForwarded function.

-

- TODO: https://go.dev/cl/407414: net/http/httputil: add X-Forwarded-{Host,Proto} headers in ReverseProxy +

+ ReverseProxy no longer adds a User-Agent header + to forwarded requests when the incoming request does not have one.

-- 2.52.0