mirror of
https://github.com/moby/moby.git
synced 2026-01-11 18:51:37 +00:00
client: remove serverResponse and use http.Response directly
Looking in history to learn why this struct existed, shows that this type was mostly the result of tech-debt accumulating over time; - originally ([moby@1aa7f13]) most of the request handling was internal; the [`call()` function][1] would make a request, read the `response.Body`, and return it as a `[]byte` (or an error if one happened). - some features needed the statuscode, so [moby@a4bcf7e] added an extra output variable to return the `response.StatusCode`. - some new features required streaming, so [moby@fdd8d4b] changed the function to return the `response.Body` as a `io.ReadCloser`, instead of a `[]byte`. - some features needed access to the content-type header, so a new `clientRequest` method was introduced in [moby@6b2eeaf] to read the `Content-Type` header from `response.Headers` and return it as a string. - of course, `Content-Type` may not be the only header needed, so [moby@0cdc3b7] changed the signature to return `response.Headers` as a whole as a `http.Header` - things became a bit unwieldy now, with the function having four (4) output variables, so [moby@126529c] chose to refactor this code, introducing a `serverResponse` struct to wrap them all, not realizing that all these values were effectively deconstructed from the `url.Response`, so now re-assembling them into our own "URL response", only preserving a subset of the information available. - now that we had a custom struct, it was possible to add more information to it without changing the signature. When there was a need to know the URL of the request that initiated the response, [moby@27ef09a] introduced a `reqURL` field to hold the `request.URL` which notably also is available in `response.Request.URL`. In short; - The original implementation tried to (pre-maturely) abstract the underlying response to provide a simplified interface. - While initially not needed, abstracting caused relevant information from the response (and request) to be unavailable to callers. - As a result, we ended up in a situation where we are deconstructing the original `url.Response`, only to re-assemble it into our own, custom struct (`serverResponsee`) with only a subset of the information preserved. This patch removes the `serverResponse` struct, instead returning the `url.Response` as-is, so that all information is preserved, allowing callers to use the information they need. There is one follow-up change to consider; commit [moby@589df17] introduced a `ensureReaderClosed` utility. Before that commit, the response body would be closed in a more idiomatic way through a [`defer serverResp.body.Close()`][2]. A later change in [docker/engine-api@5dd6452] added an optimization to that utility, draining the response to allow connections to be reused. While skipping that utility (and not draining the response) would not be a critical issue, it may be easy to overlook that utility, and to close the response body in the "idiomatic" way, resulting in a possible performance regression. We need to check if that optimization is still relevant or if later changes in Go itself already take care of this; we should also look if context cancellation is handled correctly for these. If it's still relevant, we could - Wrap the the `url.Response` in a custom struct ("drainCloser") to provide a `Close()` function handling the draining and closing; this would re- introduce a custom type to be returned, so perhaps not what we want. - Wrap the `url.Response.Body` in the response returned (so, calling) `response.Body.Close()` would call the wrapped closer. - Change the signature of `Client.sendRequest()` (and related) to return a `close()` func to handle this; doing so would more strongly encourage callers to close the response body. [1]:1aa7f1392d/commands.go (L1008-L1027)[2]:589df17a1a/api/client/ps.go (L84-L89)[moby@1aa7f13]:1aa7f1392d[moby@a4bcf7e]:a4bcf7e1ac[moby@fdd8d4b]:fdd8d4b7d9[moby@6b2eeaf]:6b2eeaf896[moby@0cdc3b7]:0cdc3b7539[moby@126529c]:126529c6d0[moby@27ef09a]:27ef09a46f[moby@589df17]:589df17a1a[docker/engine-api@5dd6452]:5dd6452d4dSigned-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
@@ -19,47 +19,39 @@ import (
|
||||
"github.com/pkg/errors"
|
||||
)
|
||||
|
||||
// serverResponse is a wrapper for http API responses.
|
||||
type serverResponse struct {
|
||||
body io.ReadCloser
|
||||
header http.Header
|
||||
statusCode int
|
||||
reqURL *url.URL
|
||||
}
|
||||
|
||||
// head sends an http request to the docker API using the method HEAD.
|
||||
func (cli *Client) head(ctx context.Context, path string, query url.Values, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) head(ctx context.Context, path string, query url.Values, headers http.Header) (*http.Response, error) {
|
||||
return cli.sendRequest(ctx, http.MethodHead, path, query, nil, headers)
|
||||
}
|
||||
|
||||
// get sends an http request to the docker API using the method GET with a specific Go context.
|
||||
func (cli *Client) get(ctx context.Context, path string, query url.Values, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) get(ctx context.Context, path string, query url.Values, headers http.Header) (*http.Response, error) {
|
||||
return cli.sendRequest(ctx, http.MethodGet, path, query, nil, headers)
|
||||
}
|
||||
|
||||
// post sends an http request to the docker API using the method POST with a specific Go context.
|
||||
func (cli *Client) post(ctx context.Context, path string, query url.Values, obj interface{}, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) post(ctx context.Context, path string, query url.Values, obj interface{}, headers http.Header) (*http.Response, error) {
|
||||
body, headers, err := encodeBody(obj, headers)
|
||||
if err != nil {
|
||||
return serverResponse{}, err
|
||||
return nil, err
|
||||
}
|
||||
return cli.sendRequest(ctx, http.MethodPost, path, query, body, headers)
|
||||
}
|
||||
|
||||
func (cli *Client) postRaw(ctx context.Context, path string, query url.Values, body io.Reader, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) postRaw(ctx context.Context, path string, query url.Values, body io.Reader, headers http.Header) (*http.Response, error) {
|
||||
return cli.sendRequest(ctx, http.MethodPost, path, query, body, headers)
|
||||
}
|
||||
|
||||
func (cli *Client) put(ctx context.Context, path string, query url.Values, obj interface{}, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) put(ctx context.Context, path string, query url.Values, obj interface{}, headers http.Header) (*http.Response, error) {
|
||||
body, headers, err := encodeBody(obj, headers)
|
||||
if err != nil {
|
||||
return serverResponse{}, err
|
||||
return nil, err
|
||||
}
|
||||
return cli.putRaw(ctx, path, query, body, headers)
|
||||
}
|
||||
|
||||
// putRaw sends an http request to the docker API using the method PUT.
|
||||
func (cli *Client) putRaw(ctx context.Context, path string, query url.Values, body io.Reader, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) putRaw(ctx context.Context, path string, query url.Values, body io.Reader, headers http.Header) (*http.Response, error) {
|
||||
// PUT requests are expected to always have a body (apparently)
|
||||
// so explicitly pass an empty body to sendRequest to signal that
|
||||
// it should set the Content-Type header if not already present.
|
||||
@@ -70,7 +62,7 @@ func (cli *Client) putRaw(ctx context.Context, path string, query url.Values, bo
|
||||
}
|
||||
|
||||
// delete sends an http request to the docker API using the method DELETE.
|
||||
func (cli *Client) delete(ctx context.Context, path string, query url.Values, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) delete(ctx context.Context, path string, query url.Values, headers http.Header) (*http.Response, error) {
|
||||
return cli.sendRequest(ctx, http.MethodDelete, path, query, nil, headers)
|
||||
}
|
||||
|
||||
@@ -116,42 +108,40 @@ func (cli *Client) buildRequest(ctx context.Context, method, path string, body i
|
||||
return req, nil
|
||||
}
|
||||
|
||||
func (cli *Client) sendRequest(ctx context.Context, method, path string, query url.Values, body io.Reader, headers http.Header) (serverResponse, error) {
|
||||
func (cli *Client) sendRequest(ctx context.Context, method, path string, query url.Values, body io.Reader, headers http.Header) (*http.Response, error) {
|
||||
req, err := cli.buildRequest(ctx, method, cli.getAPIPath(ctx, path, query), body, headers)
|
||||
if err != nil {
|
||||
return serverResponse{}, err
|
||||
return nil, err
|
||||
}
|
||||
|
||||
resp, err := cli.doRequest(req)
|
||||
switch {
|
||||
case errors.Is(err, context.Canceled):
|
||||
return serverResponse{}, errdefs.Cancelled(err)
|
||||
return nil, errdefs.Cancelled(err)
|
||||
case errors.Is(err, context.DeadlineExceeded):
|
||||
return serverResponse{}, errdefs.Deadline(err)
|
||||
return nil, errdefs.Deadline(err)
|
||||
case err == nil:
|
||||
err = cli.checkResponseErr(resp)
|
||||
return resp, cli.checkResponseErr(resp)
|
||||
default:
|
||||
return resp, err
|
||||
}
|
||||
return resp, errdefs.FromStatusCode(err, resp.statusCode)
|
||||
}
|
||||
|
||||
// FIXME(thaJeztah): Should this actually return a serverResp when a connection error occurred?
|
||||
func (cli *Client) doRequest(req *http.Request) (serverResponse, error) {
|
||||
serverResp := serverResponse{statusCode: -1, reqURL: req.URL}
|
||||
|
||||
func (cli *Client) doRequest(req *http.Request) (*http.Response, error) {
|
||||
resp, err := cli.client.Do(req)
|
||||
if err != nil {
|
||||
if cli.scheme != "https" && strings.Contains(err.Error(), "malformed HTTP response") {
|
||||
return serverResp, errConnectionFailed{fmt.Errorf("%v.\n* Are you trying to connect to a TLS-enabled daemon without TLS?", err)}
|
||||
return nil, errConnectionFailed{fmt.Errorf("%v.\n* Are you trying to connect to a TLS-enabled daemon without TLS?", err)}
|
||||
}
|
||||
|
||||
if cli.scheme == "https" && strings.Contains(err.Error(), "bad certificate") {
|
||||
return serverResp, errConnectionFailed{errors.Wrap(err, "the server probably has client authentication (--tlsverify) enabled; check your TLS client certification settings")}
|
||||
return nil, errConnectionFailed{errors.Wrap(err, "the server probably has client authentication (--tlsverify) enabled; check your TLS client certification settings")}
|
||||
}
|
||||
|
||||
// Don't decorate context sentinel errors; users may be comparing to
|
||||
// them directly.
|
||||
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
|
||||
return serverResp, err
|
||||
return nil, err
|
||||
}
|
||||
|
||||
var uErr *url.Error
|
||||
@@ -159,7 +149,7 @@ func (cli *Client) doRequest(req *http.Request) (serverResponse, error) {
|
||||
var nErr *net.OpError
|
||||
if errors.As(uErr.Err, &nErr) {
|
||||
if os.IsPermission(nErr.Err) {
|
||||
return serverResp, errConnectionFailed{errors.Wrapf(err, "permission denied while trying to connect to the Docker daemon socket at %v", cli.host)}
|
||||
return nil, errConnectionFailed{errors.Wrapf(err, "permission denied while trying to connect to the Docker daemon socket at %v", cli.host)}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -168,10 +158,10 @@ func (cli *Client) doRequest(req *http.Request) (serverResponse, error) {
|
||||
if errors.As(err, &nErr) {
|
||||
// FIXME(thaJeztah): any net.Error should be considered a connection error (but we should include the original error)?
|
||||
if nErr.Timeout() {
|
||||
return serverResp, connectionFailed(cli.host)
|
||||
return nil, connectionFailed(cli.host)
|
||||
}
|
||||
if strings.Contains(nErr.Error(), "connection refused") || strings.Contains(nErr.Error(), "dial unix") {
|
||||
return serverResp, connectionFailed(cli.host)
|
||||
return nil, connectionFailed(cli.host)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -195,28 +185,37 @@ func (cli *Client) doRequest(req *http.Request) (serverResponse, error) {
|
||||
}
|
||||
}
|
||||
|
||||
return serverResp, errConnectionFailed{errors.Wrap(err, "error during connect")}
|
||||
return nil, errConnectionFailed{errors.Wrap(err, "error during connect")}
|
||||
}
|
||||
|
||||
if resp != nil {
|
||||
serverResp.statusCode = resp.StatusCode
|
||||
serverResp.body = resp.Body
|
||||
serverResp.header = resp.Header
|
||||
}
|
||||
return serverResp, nil
|
||||
return resp, nil
|
||||
}
|
||||
|
||||
func (cli *Client) checkResponseErr(serverResp serverResponse) error {
|
||||
if serverResp.statusCode >= 200 && serverResp.statusCode < 400 {
|
||||
func (cli *Client) checkResponseErr(serverResp *http.Response) (retErr error) {
|
||||
if serverResp == nil {
|
||||
return nil
|
||||
}
|
||||
if serverResp.StatusCode >= 200 && serverResp.StatusCode < 400 {
|
||||
return nil
|
||||
}
|
||||
defer func() {
|
||||
retErr = errdefs.FromStatusCode(retErr, serverResp.StatusCode)
|
||||
}()
|
||||
|
||||
var body []byte
|
||||
var err error
|
||||
if serverResp.body != nil {
|
||||
var reqURL string
|
||||
if serverResp.Request != nil {
|
||||
reqURL = serverResp.Request.URL.String()
|
||||
}
|
||||
statusMsg := serverResp.Status
|
||||
if statusMsg == "" {
|
||||
statusMsg = http.StatusText(serverResp.StatusCode)
|
||||
}
|
||||
if serverResp.Body != nil {
|
||||
bodyMax := 1 * 1024 * 1024 // 1 MiB
|
||||
bodyR := &io.LimitedReader{
|
||||
R: serverResp.body,
|
||||
R: serverResp.Body,
|
||||
N: int64(bodyMax),
|
||||
}
|
||||
body, err = io.ReadAll(bodyR)
|
||||
@@ -224,15 +223,21 @@ func (cli *Client) checkResponseErr(serverResp serverResponse) error {
|
||||
return err
|
||||
}
|
||||
if bodyR.N == 0 {
|
||||
return fmt.Errorf("request returned %s with a message (> %d bytes) for API route and version %s, check if the server supports the requested API version", http.StatusText(serverResp.statusCode), bodyMax, serverResp.reqURL)
|
||||
if reqURL != "" {
|
||||
return fmt.Errorf("request returned %s with a message (> %d bytes) for API route and version %s, check if the server supports the requested API version", statusMsg, bodyMax, reqURL)
|
||||
}
|
||||
return fmt.Errorf("request returned %s with a message (> %d bytes); check if the server supports the requested API version", statusMsg, bodyMax)
|
||||
}
|
||||
}
|
||||
if len(body) == 0 {
|
||||
return fmt.Errorf("request returned %s for API route and version %s, check if the server supports the requested API version", http.StatusText(serverResp.statusCode), serverResp.reqURL)
|
||||
if reqURL != "" {
|
||||
return fmt.Errorf("request returned %s for API route and version %s, check if the server supports the requested API version", statusMsg, reqURL)
|
||||
}
|
||||
return fmt.Errorf("request returned %s; check if the server supports the requested API version", statusMsg)
|
||||
}
|
||||
|
||||
var daemonErr error
|
||||
if serverResp.header.Get("Content-Type") == "application/json" && (cli.version == "" || versions.GreaterThan(cli.version, "1.23")) {
|
||||
if serverResp.Header.Get("Content-Type") == "application/json" && (cli.version == "" || versions.GreaterThan(cli.version, "1.23")) {
|
||||
var errorResponse types.ErrorResponse
|
||||
if err := json.Unmarshal(body, &errorResponse); err != nil {
|
||||
return errors.Wrap(err, "Error reading JSON")
|
||||
@@ -255,8 +260,8 @@ func (cli *Client) checkResponseErr(serverResp serverResponse) error {
|
||||
//
|
||||
// TODO(thaJeztah): consider adding a log.Debug to allow clients to debug the actual response when enabling debug logging.
|
||||
daemonErr = fmt.Errorf(`API returned a %d (%s) but provided no error-message`,
|
||||
serverResp.statusCode,
|
||||
http.StatusText(serverResp.statusCode),
|
||||
serverResp.StatusCode,
|
||||
http.StatusText(serverResp.StatusCode),
|
||||
)
|
||||
} else {
|
||||
daemonErr = errors.New(strings.TrimSpace(errorResponse.Message))
|
||||
@@ -305,10 +310,16 @@ func encodeData(data interface{}) (*bytes.Buffer, error) {
|
||||
return params, nil
|
||||
}
|
||||
|
||||
func ensureReaderClosed(response serverResponse) {
|
||||
if response.body != nil {
|
||||
func ensureReaderClosed(response *http.Response) {
|
||||
if response != nil && response.Body != nil {
|
||||
// Drain up to 512 bytes and close the body to let the Transport reuse the connection
|
||||
_, _ = io.CopyN(io.Discard, response.body, 512)
|
||||
_ = response.body.Close()
|
||||
// see https://github.com/google/go-github/pull/317/files#r57536827
|
||||
//
|
||||
// TODO(thaJeztah): see if this optimization is still needed, or already implemented in stdlib,
|
||||
// and check if context-cancellation should handle this as well. If still needed, consider
|
||||
// wrapping response.Body, or returning a "closer()" from [Client.sendRequest] and related
|
||||
// methods.
|
||||
_, _ = io.CopyN(io.Discard, response.Body, 512)
|
||||
_ = response.Body.Close()
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user