From 8e6cfc298b2122f49a971d5a66ea073890052b6f Mon Sep 17 00:00:00 2001 From: "Jeevanandam M." Date: Fri, 13 Sep 2024 22:10:04 -0700 Subject: [PATCH] docs: godoc improvements (#851) --- client.go | 274 +++++++++++++++++++------------------ redirect.go | 28 ++-- request.go | 274 +++++++++++++++++++++---------------- response.go | 42 +++--- resty.go | 2 +- retry.go | 12 +- shellescape/shellescape.go | 4 +- trace.go | 22 +-- 8 files changed, 356 insertions(+), 302 deletions(-) diff --git a/client.go b/client.go index 3bdf0db..a40bbe4 100644 --- a/client.go +++ b/client.go @@ -92,10 +92,10 @@ type ( SuccessHook func(*Client, *Response) ) -// Client struct is used to create Resty client with client level settings, -// these settings are applicable to all the request raised from the client. +// Client struct is used to create a Resty client with client-level settings, +// these settings apply to all the requests raised from the client. // -// Resty also provides an options to override most of the client settings +// Resty also provides an option to override most of the client settings // at [Request] level. type Client struct { BaseURL string @@ -166,8 +166,8 @@ type User struct { // Client methods //___________________________________ -// SetHostURL method is to set Host URL in the client instance. It will be used with request -// raised from this client with relative URL +// SetHostURL method sets the Host URL in the client instance. It will be used with a request +// raised from this client with a relative URL // // // Setting HTTP address // client.SetHostURL("http://myjeeva.com") @@ -175,14 +175,14 @@ type User struct { // // Setting HTTPS address // client.SetHostURL("https://myjeeva.com") // -// Deprecated: use [Client.SetBaseURL] instead. To be removed in v3.0.0 release. +// Deprecated: use [Client.SetBaseURL] instead. To be removed in the v3.0.0 release. func (c *Client) SetHostURL(url string) *Client { c.SetBaseURL(url) return c } -// SetBaseURL method is to set Base URL in the client instance. It will be used with request -// raised from this client with relative URL +// SetBaseURL method sets the Base URL in the client instance. It will be used with a request +// raised from this client with a relative URL // // // Setting HTTP address // client.SetBaseURL("http://myjeeva.com") @@ -196,8 +196,8 @@ func (c *Client) SetBaseURL(url string) *Client { } // SetHeader method sets a single header field and its value in the client instance. -// These headers will be applied to all requests raised from this client instance. -// Also it can be overridden at request level header options. +// These headers will be applied to all requests from this client instance. +// Also, it can be overridden by request-level header options. // // See [Request.SetHeader] or [Request.SetHeaders]. // @@ -211,8 +211,8 @@ func (c *Client) SetHeader(header, value string) *Client { return c } -// SetHeaders method sets multiple headers field and its values at one go in the client instance. -// These headers will be applied to all requests raised from this client instance. Also it can be +// SetHeaders method sets multiple header fields and their values at one go in the client instance. +// These headers will be applied to all requests from this client instance. Also, it can be // overridden at request level headers options. // // See [Request.SetHeaders] or [Request.SetHeader]. @@ -230,23 +230,21 @@ func (c *Client) SetHeaders(headers map[string]string) *Client { return c } -// SetHeaderVerbatim method is to set a single header field and its value verbatim in the current request. +// SetHeaderVerbatim method sets a single header field and its value verbatim in the current request. // // For Example: To set `all_lowercase` and `UPPERCASE` as `available`. // -// client.R(). +// client. // SetHeaderVerbatim("all_lowercase", "available"). // SetHeaderVerbatim("UPPERCASE", "available") -// -// Also you can override header value, which was set at client instance level. func (c *Client) SetHeaderVerbatim(header, value string) *Client { c.Header[header] = []string{value} return c } -// SetCookieJar method sets custom [http.CookieJar] in the resty client. Its way to override default. +// SetCookieJar method sets custom [http.CookieJar] in the resty client. It's a way to override the default. // -// For Example: sometimes we don't want to save cookies in API mode, we can remove the default +// For Example, sometimes we don't want to save cookies in API mode so that we can remove the default // CookieJar in resty client. // // client.SetCookieJar(nil) @@ -255,8 +253,8 @@ func (c *Client) SetCookieJar(jar http.CookieJar) *Client { return c } -// SetCookie method appends a single cookie in the client instance. -// These cookies will be added to all the request raised from this client instance. +// SetCookie method appends a single cookie to the client instance. +// These cookies will be added to all the requests from this client instance. // // client.SetCookie(&http.Cookie{ // Name:"go-resty", @@ -268,7 +266,7 @@ func (c *Client) SetCookie(hc *http.Cookie) *Client { } // SetCookies method sets an array of cookies in the client instance. -// These cookies will be added to all the request raised from this client instance. +// These cookies will be added to all the requests from this client instance. // // cookies := []*http.Cookie{ // &http.Cookie{ @@ -288,13 +286,13 @@ func (c *Client) SetCookies(cs []*http.Cookie) *Client { return c } -// SetQueryParam method sets single parameter and its value in the client instance. -// It will be formed as query string for the request. +// SetQueryParam method sets a single parameter and its value in the client instance. +// It will be formed as a query string for the request. // // For Example: `search=kitchen%20papers&size=large` // -// In the URL after `?` mark. These query params will be added to all the request raised from -// this client instance. Also it can be overridden at request level Query Param options. +// In the URL after the `?` mark. These query params will be added to all the requests raised from +// this client instance. Also, it can be overridden at the request level. // // See [Request.SetQueryParam] or [Request.SetQueryParams]. // @@ -307,12 +305,12 @@ func (c *Client) SetQueryParam(param, value string) *Client { } // SetQueryParams method sets multiple parameters and their values at one go in the client instance. -// It will be formed as query string for the request. +// It will be formed as a query string for the request. // // For Example: `search=kitchen%20papers&size=large` // -// In the URL after `?` mark. These query params will be added to all the request raised from this -// client instance. Also it can be overridden at request level Query Param options. +// In the URL after the `?` mark. These query params will be added to all the requests raised from this +// client instance. Also, it can be overridden at the request level. // // See [Request.SetQueryParams] or [Request.SetQueryParam]. // @@ -328,9 +326,9 @@ func (c *Client) SetQueryParams(params map[string]string) *Client { } // SetFormData method sets Form parameters and their values in the client instance. -// It's applicable only HTTP method `POST` and `PUT` and request content type would be set as -// `application/x-www-form-urlencoded`. These form data will be added to all the request raised from -// this client instance. Also it can be overridden at request level form data. +// It applies only to HTTP methods `POST` and `PUT`, and the request content type would be set as +// `application/x-www-form-urlencoded`. These form data will be added to all the requests raised from +// this client instance. Also, it can be overridden at the request level. // // See [Request.SetFormData]. // @@ -353,8 +351,8 @@ func (c *Client) SetFormData(data map[string]string) *Client { // // client.SetBasicAuth("go-resty", "welcome") // -// This basic auth information gets added to all the request raised from this client instance. -// Also it can be overridden or set one at the request level is supported. +// This basic auth information is added to all requests from this client instance. +// It can also be overridden at the request level. // // See [Request.SetBasicAuth]. func (c *Client) SetBasicAuth(username, password string) *Client { @@ -363,7 +361,7 @@ func (c *Client) SetBasicAuth(username, password string) *Client { } // SetAuthToken method sets the auth token of the `Authorization` header for all HTTP requests. -// The default auth scheme is `Bearer`, it can be customized with the method [Client.SetAuthScheme]. For Example: +// The default auth scheme is `Bearer`; it can be customized with the method [Client.SetAuthScheme]. For Example: // // Authorization: // @@ -372,7 +370,7 @@ func (c *Client) SetBasicAuth(username, password string) *Client { // client.SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F") // // This auth token gets added to all the requests raised from this client instance. -// Also it can be overridden or set one at the request level is supported. +// Also, it can be overridden at the request level. // // See [Request.SetAuthToken]. func (c *Client) SetAuthToken(token string) *Client { @@ -389,7 +387,7 @@ func (c *Client) SetAuthToken(token string) *Client { // client.SetAuthScheme("OAuth") // // This auth scheme gets added to all the requests raised from this client instance. -// Also it can be overridden or set one at the request level is supported. +// Also, it can be overridden at the request level. // // Information about auth schemes can be found in [RFC 7235], IANA [HTTP Auth schemes]. // @@ -430,7 +428,7 @@ func (c *Client) SetDigestAuth(username, password string) *Client { return c } -// R method creates a new request instance, its used for Get, Post, Put, Delete, Patch, Head, Options, etc. +// R method creates a new request instance; it's used for Get, Post, Put, Delete, Patch, Head, Options, etc. func (c *Client) R() *Request { r := &Request{ QueryParam: url.Values{}, @@ -452,21 +450,20 @@ func (c *Client) R() *Request { return r } -// NewRequest is an alias for method `R()`. Creates a new request instance, its used for -// Get, Post, Put, Delete, Patch, Head, Options, etc. +// NewRequest method is an alias for method `R()`. func (c *Client) NewRequest() *Request { return c.R() } -// OnBeforeRequest method appends a request middleware into the before request chain. -// The user defined middlewares get applied before the default Resty request middlewares. +// OnBeforeRequest method appends a request middleware to the before request chain. +// The user-defined middlewares are applied before the default Resty request middlewares. // After all middlewares have been applied, the request is sent from Resty to the host server. // // client.OnBeforeRequest(func(c *resty.Client, r *resty.Request) error { -// // Now you have access to Client and Request instance +// // Now you have access to the Client and Request instance // // manipulate it as per your need // -// return nil // if its success otherwise return error +// return nil // if its successful otherwise return error // }) func (c *Client) OnBeforeRequest(m RequestMiddleware) *Client { c.udBeforeRequestLock.Lock() @@ -477,15 +474,15 @@ func (c *Client) OnBeforeRequest(m RequestMiddleware) *Client { return c } -// OnAfterResponse method appends response middleware into the after response chain. -// Once we receive response from host server, default Resty response middleware -// gets applied and then user assigned response middlewares applied. +// OnAfterResponse method appends response middleware to the after-response chain. +// Once we receive a response from the host server, the default Resty response middleware +// gets applied, and then the user-assigned response middleware is applied. // // client.OnAfterResponse(func(c *resty.Client, r *resty.Response) error { -// // Now you have access to Client and Response instance +// // Now you have access to the Client and Response instance // // manipulate it as per your need // -// return nil // if its success otherwise return error +// return nil // if its successful otherwise return error // }) func (c *Client) OnAfterResponse(m ResponseMiddleware) *Client { c.afterResponseLock.Lock() @@ -542,13 +539,13 @@ func (c *Client) OnInvalid(h ErrorHook) *Client { // callbacks, exactly one set will be invoked for each call to [Request.Execute] that completes. // // If an [Client.OnSuccess], [Client.OnError], or [Client.OnInvalid] callback panics, -// then the exactly one rule can be violated. +// then exactly one rule can be violated. func (c *Client) OnPanic(h ErrorHook) *Client { c.panicHooks = append(c.panicHooks, h) return c } -// SetPreRequestHook method sets the given pre-request function into resty client. +// SetPreRequestHook method sets the given pre-request function into a resty client. // It is called right before the request is fired. // // NOTE: Only one pre-request hook can be registered. Use [Client.OnBeforeRequest] for multiple. @@ -560,19 +557,23 @@ func (c *Client) SetPreRequestHook(h PreRequestHook) *Client { return c } -// SetDebug method enables the debug mode on Resty client. Client logs details of every request and response. -// For [Request] it logs information such as HTTP verb, Relative URL path, Host, Headers, Body if it has one. -// For [Response] it logs information such as Status, Response Time, Headers, Body if it has one. +// SetDebug method enables the debug mode on the Resty client. The client logs details +// of every request and response. // // client.SetDebug(true) // -// Also it can be enabled at request level for particular request, see [Request.SetDebug]. +// Also, it can be enabled at the request level for a particular request; see [Request.SetDebug]. +// - For [Request], it logs information such as HTTP verb, Relative URL path, +// Host, Headers, and Body if it has one. +// - For [Response], it logs information such as Status, Response Time, Headers, +// and Body if it has one. func (c *Client) SetDebug(d bool) *Client { c.Debug = d return c } -// SetDebugBodyLimit sets the maximum size for which the response and request body will be logged in debug mode. +// SetDebugBodyLimit sets the maximum size in bytes for which the response and +// request body will be logged in debug mode. // // client.SetDebugBodyLimit(1000000) func (c *Client) SetDebugBodyLimit(sl int64) *Client { @@ -580,8 +581,8 @@ func (c *Client) SetDebugBodyLimit(sl int64) *Client { return c } -// OnRequestLog method used to set request log callback into Resty. Registered callback gets -// called before the resty actually logs the information. +// OnRequestLog method sets the request log callback to Resty. Registered callback gets +// called before the resty logs the information. func (c *Client) OnRequestLog(rl RequestLogCallback) *Client { if c.requestLog != nil { c.log.Warnf("Overwriting an existing on-request-log callback from=%s to=%s", @@ -591,8 +592,8 @@ func (c *Client) OnRequestLog(rl RequestLogCallback) *Client { return c } -// OnResponseLog method used to set response log callback into Resty. Registered callback gets -// called before the resty actually logs the information. +// OnResponseLog method sets the response log callback to Resty. Registered callback gets +// called before the resty logs the information. func (c *Client) OnResponseLog(rl ResponseLogCallback) *Client { if c.responseLog != nil { c.log.Warnf("Overwriting an existing on-response-log callback from=%s to=%s", @@ -602,9 +603,9 @@ func (c *Client) OnResponseLog(rl ResponseLogCallback) *Client { return c } -// SetDisableWarn method disables the warning message on Resty client. +// SetDisableWarn method disables the warning log message on the Resty client. // -// For Example: Resty warns the user when BasicAuth used on non-TLS mode. +// For example, Resty warns users when BasicAuth is used in non-TLS mode. // // client.SetDisableWarn(true) func (c *Client) SetDisableWarn(d bool) *Client { @@ -612,9 +613,9 @@ func (c *Client) SetDisableWarn(d bool) *Client { return c } -// SetAllowGetMethodPayload method allows the GET method with payload on Resty client. +// SetAllowGetMethodPayload method allows the GET method with payload on the Resty client. // -// For Example: Resty allows the user sends request with a payload on HTTP GET method. +// For example, Resty allows the user to send a request with a payload using the HTTP GET method. // // client.SetAllowGetMethodPayload(true) func (c *Client) SetAllowGetMethodPayload(a bool) *Client { @@ -631,17 +632,17 @@ func (c *Client) SetLogger(l Logger) *Client { } // SetContentLength method enables the HTTP header `Content-Length` value for every request. -// By default Resty won't set `Content-Length`. +// By default, Resty won't set `Content-Length`. // // client.SetContentLength(true) // -// Also you have an option to enable for particular request. See [Request.SetContentLength] +// Also, you have the option to enable a particular request. See [Request.SetContentLength] func (c *Client) SetContentLength(l bool) *Client { c.setContentLength = l return c } -// SetTimeout method sets timeout for request raised from client. +// SetTimeout method sets the timeout for a request raised by the client. // // client.SetTimeout(time.Duration(1 * time.Minute)) func (c *Client) SetTimeout(timeout time.Duration) *Client { @@ -649,9 +650,9 @@ func (c *Client) SetTimeout(timeout time.Duration) *Client { return c } -// SetError method is to register the global or client common `Error` object into Resty. -// It is used for automatic unmarshalling if response status code is greater than 399 and -// content type either JSON or XML. Can be pointer or non-pointer. +// SetError method registers the global or client common `Error` object into Resty. +// It is used for automatic unmarshalling if the response status code is greater than 399 and +// content type is JSON or XML. It can be a pointer or a non-pointer. // // client.SetError(&Error{}) // // OR @@ -661,8 +662,8 @@ func (c *Client) SetError(err interface{}) *Client { return c } -// SetRedirectPolicy method sets the client redirect policy. Resty provides ready to use -// redirect policies. Wanna create one for yourself refer to `redirect.go`. +// SetRedirectPolicy method sets the redirect policy for the client. Resty provides ready-to-use +// redirect policies. Wanna create one for yourself, refer to `redirect.go`. // // client.SetRedirectPolicy(FlexibleRedirectPolicy(20)) // @@ -695,7 +696,7 @@ func (c *Client) SetRetryCount(count int) *Client { return c } -// SetRetryWaitTime method sets default wait time to sleep before retrying +// SetRetryWaitTime method sets the default wait time for sleep before retrying // request. // // Default is 100 milliseconds. @@ -704,7 +705,7 @@ func (c *Client) SetRetryWaitTime(waitTime time.Duration) *Client { return c } -// SetRetryMaxWaitTime method sets max wait time to sleep before retrying +// SetRetryMaxWaitTime method sets the max wait time for sleep before retrying // request. // // Default is 2 seconds. @@ -713,7 +714,7 @@ func (c *Client) SetRetryMaxWaitTime(maxWaitTime time.Duration) *Client { return c } -// SetRetryAfter sets callback to calculate wait time between retries. +// SetRetryAfter sets a callback to calculate the wait time between retries. // Default (nil) implies exponential backoff with jitter func (c *Client) SetRetryAfter(callback RetryAfterFunc) *Client { c.RetryAfter = callback @@ -748,19 +749,19 @@ func (c *Client) SetXMLUnmarshaler(unmarshaler func(data []byte, v interface{}) return c } -// AddRetryCondition method adds a retry condition function to array of functions +// AddRetryCondition method adds a retry condition function to an array of functions // that are checked to determine if the request is retried. The request will -// retry if any of the functions return true and error is nil. +// retry if any functions return true and the error is nil. // -// NOTE: These retry conditions are applied on all Request made using this Client. -// For [Request] specific retry conditions check [Request.AddRetryCondition] +// NOTE: These retry conditions are applied on all requests made using this Client. +// For [Request] specific retry conditions, check [Request.AddRetryCondition] func (c *Client) AddRetryCondition(condition RetryConditionFunc) *Client { c.RetryConditions = append(c.RetryConditions, condition) return c } // AddRetryAfterErrorCondition adds the basic condition of retrying after encountering -// an error from the http response +// an error from the HTTP response func (c *Client) AddRetryAfterErrorCondition() *Client { c.AddRetryCondition(func(response *Response, err error) bool { return response.IsError() @@ -776,17 +777,17 @@ func (c *Client) AddRetryHook(hook OnRetryFunc) *Client { } // SetRetryResetReaders method enables the Resty client to seek the start of all -// file readers given as multipart files, if the given object implements [io.ReadSeeker]. +// file readers are given as multipart files if the object implements [io.ReadSeeker]. func (c *Client) SetRetryResetReaders(b bool) *Client { c.RetryResetReaders = b return c } -// SetTLSClientConfig method sets TLSClientConfig for underling client Transport. +// SetTLSClientConfig method sets TLSClientConfig for underlying client Transport. // // For Example: // -// // One can set custom root-certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dial +// // One can set a custom root certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dial // client.SetTLSClientConfig(&tls.Config{ RootCAs: roots }) // // // or One can disable security check (https) @@ -803,7 +804,7 @@ func (c *Client) SetTLSClientConfig(config *tls.Config) *Client { return c } -// SetProxy method sets the Proxy URL and Port for Resty client. +// SetProxy method sets the Proxy URL and Port for the Resty client. // // client.SetProxy("http://proxyserver:8888") // @@ -826,7 +827,7 @@ func (c *Client) SetProxy(proxyURL string) *Client { return c } -// RemoveProxy method removes the proxy configuration from Resty client +// RemoveProxy method removes the proxy configuration from the Resty client // // client.RemoveProxy() func (c *Client) RemoveProxy() *Client { @@ -840,7 +841,7 @@ func (c *Client) RemoveProxy() *Client { return c } -// SetCertificates method helps to set client certificates into Resty conveniently. +// SetCertificates method helps to conveniently set client certificates into Resty. func (c *Client) SetCertificates(certs ...tls.Certificate) *Client { config, err := c.tlsConfig() if err != nil { @@ -851,7 +852,7 @@ func (c *Client) SetCertificates(certs ...tls.Certificate) *Client { return c } -// SetRootCertificate method helps to add one or more root certificates into Resty client +// SetRootCertificate method helps to add one or more root certificates into the Resty client // // client.SetRootCertificate("/path/to/root/pemFile.pem") func (c *Client) SetRootCertificate(pemFilePath string) *Client { @@ -864,7 +865,8 @@ func (c *Client) SetRootCertificate(pemFilePath string) *Client { return c } -// SetRootCertificateFromString method helps to add one or more root certificates into Resty client +// SetRootCertificateFromString method helps to add one or more root certificates +// into the Resty client // // client.SetRootCertificateFromString("pem certs content") func (c *Client) SetRootCertificateFromString(pemCerts string) *Client { @@ -872,7 +874,8 @@ func (c *Client) SetRootCertificateFromString(pemCerts string) *Client { return c } -// SetClientRootCertificate method helps to add one or more client's root certificates into Resty client +// SetClientRootCertificate method helps to add one or more client's root +// certificates into the Resty client // // client.SetClientRootCertificate("/path/to/root/pemFile.pem") func (c *Client) SetClientRootCertificate(pemFilePath string) *Client { @@ -885,7 +888,8 @@ func (c *Client) SetClientRootCertificate(pemFilePath string) *Client { return c } -// SetClientRootCertificateFromString method helps to add one or more client's root certificates into Resty client +// SetClientRootCertificateFromString method helps to add one or more clients +// root certificates into the Resty client // // client.SetClientRootCertificateFromString("pem certs content") func (c *Client) SetClientRootCertificateFromString(pemCerts string) *Client { @@ -914,9 +918,9 @@ func (c *Client) handleCAs(scope string, permCerts []byte) { } } -// SetOutputDirectory method sets output directory for saving HTTP response into file. -// If the output directory not exists then resty creates one. This setting is optional one, -// if you're planning using absolute path in [Request.SetOutput] and can used together. +// SetOutputDirectory method sets the output directory for saving HTTP responses in a file. +// Resty creates one if the output directory does not exist. This setting is optional, +// if you plan to use the absolute path in [Request.SetOutput] and can used together. // // client.SetOutputDirectory("/save/http/response/here") func (c *Client) SetOutputDirectory(dirPath string) *Client { @@ -924,15 +928,15 @@ func (c *Client) SetOutputDirectory(dirPath string) *Client { return c } -// SetRateLimiter sets an optional [RateLimiter]. If set the rate limiter will control -// all requests made with this client. +// SetRateLimiter sets an optional [RateLimiter]. If set, the rate limiter will control +// all requests were made by this client. func (c *Client) SetRateLimiter(rl RateLimiter) *Client { c.rateLimiter = rl return c } // SetTransport method sets custom [http.Transport] or any [http.RoundTripper] -// compatible interface implementation in the resty client. +// compatible interface implementation in the Resty client. // // transport := &http.Transport{ // // something like Proxying to httptest.Server, etc... @@ -943,9 +947,9 @@ func (c *Client) SetRateLimiter(rl RateLimiter) *Client { // client.SetTransport(transport) // // NOTE: -// - If transport is not type of `*http.Transport` then you may not be able to +// - If transport is not the type of `*http.Transport`, then you may not be able to // take advantage of some of the Resty client settings. -// - It overwrites the Resty client transport instance and it's configurations. +// - It overwrites the Resty client transport instance and its configurations. func (c *Client) SetTransport(transport http.RoundTripper) *Client { if transport != nil { c.httpClient.Transport = transport @@ -953,7 +957,7 @@ func (c *Client) SetTransport(transport http.RoundTripper) *Client { return c } -// SetScheme method sets custom scheme in the Resty client. It's way to override default. +// SetScheme method sets a custom scheme for the Resty client. It's a way to override the default. // // client.SetScheme("http") func (c *Client) SetScheme(scheme string) *Client { @@ -963,25 +967,26 @@ func (c *Client) SetScheme(scheme string) *Client { return c } -// SetCloseConnection method sets variable `Close` in http request struct with the given +// SetCloseConnection method sets variable `Close` in HTTP request struct with the given // value. More info: https://golang.org/src/net/http/request.go func (c *Client) SetCloseConnection(close bool) *Client { c.closeConnection = close return c } -// SetDoNotParseResponse method instructs `Resty` not to parse the response body automatically. -// Resty exposes the raw response body as [io.ReadCloser]. Also do not forget to close the body, -// otherwise you might get into connection leaks, no connection reuse. +// SetDoNotParseResponse method instructs Resty not to parse the response body automatically. +// Resty exposes the raw response body as [io.ReadCloser]. If you use it, do not +// forget to close the body, otherwise, you might get into connection leaks, and connection +// reuse may not happen. // -// NOTE: [Response] middlewares are not applicable, if you use this option. Basically you have -// taken over the control of response parsing from `Resty`. +// NOTE: [Response] middlewares are not executed using this option. You have +// taken over the control of response parsing from Resty. func (c *Client) SetDoNotParseResponse(notParse bool) *Client { c.notParseResponse = notParse return c } -// SetPathParam method sets single URL path key-value pair in the +// SetPathParam method sets a single URL path key-value pair in the // Resty client instance. // // client.SetPathParam("userId", "sample@sample.com") @@ -993,7 +998,7 @@ func (c *Client) SetDoNotParseResponse(notParse bool) *Client { // It replaces the value of the key while composing the request URL. // The value will be escaped using [url.PathEscape] function. // -// Also it can be overridden at request level Path Params options, +// It can be overridden at the request level, // see [Request.SetPathParam] or [Request.SetPathParams] func (c *Client) SetPathParam(param, value string) *Client { c.PathParams[param] = value @@ -1016,7 +1021,7 @@ func (c *Client) SetPathParam(param, value string) *Client { // It replaces the value of the key while composing the request URL. // The values will be escaped using [url.PathEscape] function. // -// Also it can be overridden at request level Path Params options, +// It can be overridden at the request level, // see [Request.SetPathParam] or [Request.SetPathParams] func (c *Client) SetPathParams(params map[string]string) *Client { for p, v := range params { @@ -1025,7 +1030,7 @@ func (c *Client) SetPathParams(params map[string]string) *Client { return c } -// SetRawPathParam method sets single URL path key-value pair in the +// SetRawPathParam method sets a single URL path key-value pair in the // Resty client instance. // // client.SetPathParam("userId", "sample@sample.com") @@ -1043,7 +1048,7 @@ func (c *Client) SetPathParams(params map[string]string) *Client { // It replaces the value of the key while composing the request URL. // The value will be used as it is and will not be escaped. // -// Also it can be overridden at request level Path Params options, +// It can be overridden at the request level, // see [Request.SetRawPathParam] or [Request.SetRawPathParams] func (c *Client) SetRawPathParam(param, value string) *Client { c.RawPathParams[param] = value @@ -1066,7 +1071,7 @@ func (c *Client) SetRawPathParam(param, value string) *Client { // It replaces the value of the key while composing the request URL. // The values will be used as they are and will not be escaped. // -// Also it can be overridden at request level Path Params options, +// It can be overridden at the request level, // see [Request.SetRawPathParam] or [Request.SetRawPathParams] func (c *Client) SetRawPathParams(params map[string]string) *Client { for p, v := range params { @@ -1075,23 +1080,28 @@ func (c *Client) SetRawPathParams(params map[string]string) *Client { return c } -// SetJSONEscapeHTML method is to enable/disable the HTML escape on JSON marshal. +// SetJSONEscapeHTML method enables or disables the HTML escape on JSON marshal. +// By default, escape HTML is false. +// +// NOTE: This option only applies to the standard JSON Marshaller used by Resty. // -// NOTE: This option only applicable to standard JSON Marshaller. +// It can be overridden at the request level, see [Client.SetJSONEscapeHTML] func (c *Client) SetJSONEscapeHTML(b bool) *Client { c.jsonEscapeHTML = b return c } -// SetResponseBodyLimit set a max body size limit on response, avoid reading too many data to memory. +// SetResponseBodyLimit method sets a maximum body size limit in bytes on response, +// avoid reading too much data to memory. // -// Client will return [resty.ErrResponseBodyTooLarge] if uncompressed response body size if larger than limit. -// Body size limit will not be enforced in following case: +// Client will return [resty.ErrResponseBodyTooLarge] if the body size of the body +// in the uncompressed response is larger than the limit. +// Body size limit will not be enforced in the following cases: // - ResponseBodyLimit <= 0, which is the default behavior. -// - [Request.SetOutput] is called to save a response data to file. +// - [Request.SetOutput] is called to save response data to the file. // - "DoNotParseResponse" is set for client or request. // -// this can be overridden at client level with [Request.SetResponseBodyLimit] +// It can be overridden at the request level; see [Request.SetResponseBodyLimit] func (c *Client) SetResponseBodyLimit(v int) *Client { c.ResponseBodyLimit = v return c @@ -1106,7 +1116,7 @@ func (c *Client) SetResponseBodyLimit(v int) *Client { // fmt.Println("Error:", err) // fmt.Println("Trace Info:", resp.Request.TraceInfo()) // -// Also [Request.EnableTrace] available too to get trace info for single request. +// The method [Request.EnableTrace] is also available to get trace info for a single request. func (c *Client) EnableTrace() *Client { c.trace = true return c @@ -1122,7 +1132,7 @@ func (c *Client) DisableTrace() *Client { // It works in conjunction with debug mode. // // NOTE: Use with care. -// - Potential to leak sensitive data in the debug log from [Request] and [Response]. +// - Potential to leak sensitive data from [Request] and [Response] in the debug log. // - Beware of memory usage since the request body is reread. func (c *Client) EnableGenerateCurlOnDebug() *Client { c.generateCurlOnDebug = true @@ -1135,13 +1145,13 @@ func (c *Client) DisableGenerateCurlOnDebug() *Client { return c } -// IsProxySet method returns the true is proxy is set from resty client otherwise -// false. By default proxy is set from environment, refer to [http.ProxyFromEnvironment]. +// IsProxySet method returns the true is proxy is set from the Resty client; otherwise +// false. By default, the proxy is set from the environment variable; refer to [http.ProxyFromEnvironment]. func (c *Client) IsProxySet() bool { return c.proxyURL != nil } -// GetClient method returns the current [http.Client] used by the resty client. +// GetClient method returns the underlying [http.Client] used by the Resty. func (c *Client) GetClient() *http.Client { return c.httpClient } @@ -1151,8 +1161,8 @@ func (c *Client) GetClient() *http.Client { // NOTE: Use with care: // - Interface values are not deeply cloned. Thus, both the original and the // clone will use the same value. -// - This function is not safe for concurrent use. You should only use this -// when you are sure that the client is not being used by any other goroutine. +// - This function is not safe for concurrent use. You should only use this method +// when you are sure that any other goroutine is not using the client. func (c *Client) Clone() *Client { // dereference the pointer and copy the value cc := *c @@ -1217,8 +1227,8 @@ func (c *Client) executeBefore(req *Request) error { return nil } -// Executes method executes the given `Request` object and returns response -// error. +// Executes method executes the given `Request` object and returns +// response or error. func (c *Client) execute(req *Request) (*Response, error) { if err := c.executeBefore(req); err != nil { return nil, err @@ -1330,9 +1340,9 @@ func (c *Client) tlsConfig() (*tls.Config, error) { } // Transport method returns [http.Transport] currently in use or error -// in case currently used `transport` is not a [http.Transport]. +// in case the currently used `transport` is not a [http.Transport]. // -// Since v2.8.0 become exported method. +// Since v2.8.0 has become exported method. func (c *Client) Transport() (*http.Transport, error) { if transport, ok := c.httpClient.Transport.(*http.Transport); ok { return transport, nil @@ -1346,7 +1356,7 @@ func (c *Client) outputLogTo(w io.Writer) *Client { return c } -// ResponseError is a wrapper for including the server response with an error. +// ResponseError is a wrapper that includes the server response with an error. // Neither the err nor the response should be nil. type ResponseError struct { Response *Response @@ -1397,14 +1407,14 @@ func (c *Client) onInvalidHooks(req *Request, err error) { // File struct and its methods //_______________________________________________________________________ -// File struct represent file information for multipart request +// File struct represents file information for multipart request type File struct { Name string ParamName string io.Reader } -// String returns string value of current file details +// String method returns the string value of current file details func (f *File) String() string { return fmt.Sprintf("ParamName: %v; FileName: %v", f.ParamName, f.Name) } @@ -1413,7 +1423,7 @@ func (f *File) String() string { // MultipartField struct //_______________________________________________________________________ -// MultipartField struct represent custom data part for multipart request +// MultipartField struct represents the custom data part for a multipart request type MultipartField struct { Param string FileName string diff --git a/redirect.go b/redirect.go index fececc4..bb016e2 100644 --- a/redirect.go +++ b/redirect.go @@ -17,17 +17,18 @@ var ( ) type ( - // RedirectPolicy to regulate the redirects in the resty client. + // RedirectPolicy to regulate the redirects in the Resty client. // Objects implementing the [RedirectPolicy] interface can be registered as // - // Apply function should return nil to continue the redirect journey, otherwise + // Apply function should return nil to continue the redirect journey; otherwise // return error to stop the redirect. RedirectPolicy interface { Apply(req *http.Request, via []*http.Request) error } - // The [RedirectPolicyFunc] type is an adapter to allow the use of ordinary functions as [RedirectPolicy]. - // If f is a function with the appropriate signature, RedirectPolicyFunc(f) is a RedirectPolicy object that calls f. + // The [RedirectPolicyFunc] type is an adapter to allow the use of ordinary + // functions as [RedirectPolicy]. If `f` is a function with the appropriate + // signature, RedirectPolicyFunc(f) is a RedirectPolicy object that calls `f`. RedirectPolicyFunc func(*http.Request, []*http.Request) error ) @@ -36,7 +37,7 @@ func (f RedirectPolicyFunc) Apply(req *http.Request, via []*http.Request) error return f(req, via) } -// NoRedirectPolicy is used to disable redirects in the HTTP client +// NoRedirectPolicy is used to disable redirects in the Resty client // // resty.SetRedirectPolicy(NoRedirectPolicy()) func NoRedirectPolicy() RedirectPolicy { @@ -45,7 +46,7 @@ func NoRedirectPolicy() RedirectPolicy { }) } -// FlexibleRedirectPolicy is convenient method to create No of redirect policy for HTTP client. +// FlexibleRedirectPolicy method is convenient for creating several redirect policies for Resty clients. // // resty.SetRedirectPolicy(FlexibleRedirectPolicy(20)) func FlexibleRedirectPolicy(noOfRedirect int) RedirectPolicy { @@ -58,8 +59,8 @@ func FlexibleRedirectPolicy(noOfRedirect int) RedirectPolicy { }) } -// DomainCheckRedirectPolicy is convenient method to define domain name redirect rule in resty client. -// Redirect is allowed for only mentioned host in the policy. +// DomainCheckRedirectPolicy method is convenient for defining domain name redirect rules in Resty clients. +// Redirect is allowed only for the host mentioned in the policy. // // resty.SetRedirectPolicy(DomainCheckRedirectPolicy("host1.com", "host2.org", "host3.net")) func DomainCheckRedirectPolicy(hostnames ...string) RedirectPolicy { @@ -79,10 +80,6 @@ func DomainCheckRedirectPolicy(hostnames ...string) RedirectPolicy { return fn } -//‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ -// Package Unexported methods -//_______________________________________________________________________ - func getHostname(host string) (hostname string) { if strings.Index(host, ":") > 0 { host, _, _ = net.SplitHostPort(host) @@ -91,10 +88,11 @@ func getHostname(host string) (hostname string) { return } -// By default Golang will not redirect request headers -// after go throwing various discussion comments from thread +// By default, Golang will not redirect request headers. +// After reading through the various discussion comments from the thread - // https://github.com/golang/go/issues/4800 -// Resty will add all the headers during a redirect for the same host +// Resty will add all the headers during a redirect for the same host and +// adds library user-agent if the Host is different. func checkHostAndAddHeaders(cur *http.Request, pre *http.Request) { curHostname := getHostname(cur.URL.Host) preHostname := getHostname(pre.URL.Host) diff --git a/request.go b/request.go index 241e461..1834071 100644 --- a/request.go +++ b/request.go @@ -23,9 +23,9 @@ import ( // Request struct and methods //_______________________________________________________________________ -// Request struct is used to compose and fire individual request from -// resty client. Request provides an options to override client level -// settings and also an options for the request composition. +// Request struct is used to compose and fire individual requests from +// Resty client. The [Request] provides an option to override client-level +// settings and also an option for the request composition. type Request struct { URL string Method string @@ -75,7 +75,7 @@ type Request struct { generateCurlOnDebug bool } -// Generate curl command for the request. +// GenerateCurlCommand method generates the CURL command for the request. func (r *Request) GenerateCurlCommand() string { if !(r.Debug && r.generateCurlOnDebug) { return "" @@ -95,8 +95,8 @@ func (r *Request) GenerateCurlCommand() string { return *r.resultCurlCmd } -// Context method returns the Context if its already set in request -// otherwise it creates new one using [context.Background]. +// Context method returns the Context if it is already set in the [Request] +// otherwise, it creates a new one using [context.Background]. func (r *Request) Context() context.Context { if r.ctx == nil { return context.Background() @@ -105,15 +105,15 @@ func (r *Request) Context() context.Context { } // SetContext method sets the [context.Context] for current [Request]. It allows -// to interrupt the request execution if ctx.Done() channel is closed. -// See https://blog.golang.org/context article and the "context" package +// to interrupt the request execution if `ctx.Done()` channel is closed. +// See https://blog.golang.org/context article and the package [context] // documentation. func (r *Request) SetContext(ctx context.Context) *Request { r.ctx = ctx return r } -// SetHeader method is to set a single header field and its value in the current request. +// SetHeader method sets a single header field and its value in the current request. // // For Example: To set `Content-Type` and `Accept` as `application/json`. // @@ -121,13 +121,13 @@ func (r *Request) SetContext(ctx context.Context) *Request { // SetHeader("Content-Type", "application/json"). // SetHeader("Accept", "application/json") // -// Also you can override header value, which was set at client instance level. +// It overrides the header value set at the client instance level. func (r *Request) SetHeader(header, value string) *Request { r.Header.Set(header, value) return r } -// SetHeaders method sets multiple headers field and its values at one go in the current request. +// SetHeaders method sets multiple header fields and their values at one go in the current request. // // For Example: To set `Content-Type` and `Accept` as `application/json` // @@ -137,7 +137,7 @@ func (r *Request) SetHeader(header, value string) *Request { // "Accept": "application/json", // }) // -// Also you can override header value, which was set at client instance level. +// It overrides the header value set at the client instance level. func (r *Request) SetHeaders(headers map[string]string) *Request { for h, v := range headers { r.SetHeader(h, v) @@ -145,7 +145,7 @@ func (r *Request) SetHeaders(headers map[string]string) *Request { return r } -// SetHeaderMultiValues sets multiple headers fields and its values is list of strings at one go in the current request. +// SetHeaderMultiValues sets multiple header fields and their values as a list of strings in the current request. // // For Example: To set `Accept` as `text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8` // @@ -154,7 +154,7 @@ func (r *Request) SetHeaders(headers map[string]string) *Request { // "Accept": []string{"text/html", "application/xhtml+xml", "application/xml;q=0.9", "image/webp", "*/*;q=0.8"}, // }) // -// Also you can override header value, which was set at client instance level. +// It overrides the header value set at the client instance level. func (r *Request) SetHeaderMultiValues(headers map[string][]string) *Request { for key, values := range headers { r.SetHeader(key, strings.Join(values, ", ")) @@ -162,7 +162,7 @@ func (r *Request) SetHeaderMultiValues(headers map[string][]string) *Request { return r } -// SetHeaderVerbatim method is to set a single header field and its value verbatim in the current request. +// SetHeaderVerbatim method sets a single header field and its value verbatim in the current request. // // For Example: To set `all_lowercase` and `UPPERCASE` as `available`. // @@ -170,31 +170,31 @@ func (r *Request) SetHeaderMultiValues(headers map[string][]string) *Request { // SetHeaderVerbatim("all_lowercase", "available"). // SetHeaderVerbatim("UPPERCASE", "available") // -// Also you can override header value, which was set at client instance level. +// It overrides the header value set at the client instance level. func (r *Request) SetHeaderVerbatim(header, value string) *Request { r.Header[header] = []string{value} return r } -// SetQueryParam method sets single parameter and its value in the current request. -// It will be formed as query string for the request. +// SetQueryParam method sets a single parameter and its value in the current request. +// It will be formed as a query string for the request. // -// For Example: `search=kitchen%20papers&size=large` in the URL after `?` mark. +// For Example: `search=kitchen%20papers&size=large` in the URL after the `?` mark. // // client.R(). // SetQueryParam("search", "kitchen papers"). // SetQueryParam("size", "large") // -// Also you can override query params value, which was set at client instance level. +// It overrides the query parameter value set at the client instance level. func (r *Request) SetQueryParam(param, value string) *Request { r.QueryParam.Set(param, value) return r } -// SetQueryParams method sets multiple parameters and its values at one go in the current request. -// It will be formed as query string for the request. +// SetQueryParams method sets multiple parameters and their values at one go in the current request. +// It will be formed as a query string for the request. // -// For Example: `search=kitchen%20papers&size=large` in the URL after `?` mark. +// For Example: `search=kitchen%20papers&size=large` in the URL after the `?` mark. // // client.R(). // SetQueryParams(map[string]string{ @@ -202,7 +202,7 @@ func (r *Request) SetQueryParam(param, value string) *Request { // "size": "large", // }) // -// Also you can override query params value, which was set at client instance level. +// It overrides the query parameter value set at the client instance level. func (r *Request) SetQueryParams(params map[string]string) *Request { for p, v := range params { r.SetQueryParam(p, v) @@ -214,14 +214,14 @@ func (r *Request) SetQueryParams(params map[string]string) *Request { // ([url.Values]) at one go in the current request. It will be formed as // query string for the request. // -// For Example: `status=pending&status=approved&status=open` in the URL after `?` mark. +// For Example: `status=pending&status=approved&status=open` in the URL after the `?` mark. // // client.R(). // SetQueryParamsFromValues(url.Values{ // "status": []string{"pending", "approved", "open"}, // }) // -// Also you can override query params value, which was set at client instance level. +// It overrides the query parameter value set at the client instance level. func (r *Request) SetQueryParamsFromValues(params url.Values) *Request { for p, v := range params { for _, pv := range v { @@ -231,12 +231,12 @@ func (r *Request) SetQueryParamsFromValues(params url.Values) *Request { return r } -// SetQueryString method provides ability to use string as an input to set URL query string for the request. -// -// Using String as an input +// SetQueryString method provides the ability to use string as an input to set URL query string for the request. // // client.R(). // SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more") +// +// It overrides the query parameter value set at the client instance level. func (r *Request) SetQueryString(query string) *Request { params, err := url.ParseQuery(strings.TrimSpace(query)) if err == nil { @@ -251,9 +251,9 @@ func (r *Request) SetQueryString(query string) *Request { return r } -// SetFormData method sets Form parameters and their values in the current request. -// It's applicable only HTTP method `POST` and `PUT` and requests content type would be set as -// `application/x-www-form-urlencoded`. +// SetFormData method sets Form parameters and their values for the current request. +// It applies only to HTTP methods `POST` and `PUT`, and by default requests +// content type would be set as `application/x-www-form-urlencoded`. // // client.R(). // SetFormData(map[string]string{ @@ -261,7 +261,7 @@ func (r *Request) SetQueryString(query string) *Request { // "user_id": "3455454545", // }) // -// Also you can override form data value, which was set at client instance level. +// It overrides the form data value set at the client instance level. func (r *Request) SetFormData(data map[string]string) *Request { for k, v := range data { r.FormData.Set(k, v) @@ -277,7 +277,7 @@ func (r *Request) SetFormData(data map[string]string) *Request { // "search_criteria": []string{"book", "glass", "pencil"}, // }) // -// Also you can override form data value, which was set at client instance level. +// It overrides the form data value set at the client instance level. func (r *Request) SetFormDataFromValues(data url.Values) *Request { for k, v := range data { for _, kv := range v { @@ -287,14 +287,17 @@ func (r *Request) SetFormDataFromValues(data url.Values) *Request { return r } -// SetBody method sets the request body for the request. It supports various realtime needs as easy. -// We can say its quite handy or powerful. Supported request body data types is `string`, -// `[]byte`, `struct`, `map`, `slice` and [io.Reader]. Body value can be pointer or non-pointer. -// Automatic marshalling for JSON and XML content type, if it is `struct`, `map`, or `slice`. +// SetBody method sets the request body for the request. It supports various practical needs as easy. +// It's quite handy and powerful. Supported request body data types are `string`, +// `[]byte`, `struct`, `map`, `slice` and [io.Reader]. +// +// Body value can be pointer or non-pointer. Automatic marshalling for JSON and XML content type, if it is `struct`, `map`, or `slice`. // -// NOTE: [io.Reader] is processed as bufferless mode while sending request. +// NOTE: [io.Reader] is processed in bufferless mode while sending a request. // -// For Example: Struct as a body input, based on content type, it will be marshalled. +// For Example: +// +// `struct` gets marshaled based on the request header `Content-Type`. // // client.R(). // SetBody(User{ @@ -302,7 +305,7 @@ func (r *Request) SetFormDataFromValues(data url.Values) *Request { // Password: "welcome2resty", // }) // -// Map as a body input, based on content type, it will be marshalled. +// 'map` gets marshaled based on the request header `Content-Type`. // // client.R(). // SetBody(map[string]interface{}{ @@ -317,7 +320,7 @@ func (r *Request) SetFormDataFromValues(data url.Values) *Request { // }, // }) // -// String as a body input. Suitable for any need as a string input. +// `string` as a body input. Suitable for any need as a string input. // // client.R(). // SetBody(`{ @@ -325,27 +328,41 @@ func (r *Request) SetFormDataFromValues(data url.Values) *Request { // "password": "admin" // }`) // -// []byte as a body input. Suitable for raw request such as file upload, serialize & deserialize, etc. +// `[]byte` as a body input. Suitable for raw requests such as file upload, serialize & deserialize, etc. // // client.R(). // SetBody([]byte("This is my raw request, sent as-is")) +// +// and so on. func (r *Request) SetBody(body interface{}) *Request { r.Body = body return r } -// SetResult method is to register the response `Result` object for automatic unmarshalling for the request, -// if response status code is between 200 and 299 and content type either JSON or XML. +// SetResult method is to register the response `Result` object for automatic +// unmarshalling of the HTTP response if the response status code is +// between 200 and 299, and the content type is JSON or XML. // -// NOTE: Result object can be pointer or non-pointer. +// Note: [Request.SetResult] input can be a pointer or non-pointer. +// +// The pointer with handle +// +// authToken := &AuthToken{} +// client.R().SetResult(authToken) +// +// // Can be accessed via - +// fmt.Println(authToken) OR fmt.Println(response.Result().(*AuthToken)) +// +// OR - +// +// The pointer without handle or non-pointer // // client.R().SetResult(&AuthToken{}) // // OR // client.R().SetResult(AuthToken{}) // -// Accessing a result value from response instance. -// -// response.Result().(*AuthToken) +// // Can be accessed via - +// fmt.Println(response.Result().(*AuthToken)) func (r *Request) SetResult(res interface{}) *Request { if res != nil { r.Result = getPointer(res) @@ -354,23 +371,25 @@ func (r *Request) SetResult(res interface{}) *Request { } // SetError method is to register the request `Error` object for automatic unmarshalling for the request, -// if response status code is greater than 399 and content type either JSON or XML. +// if the response status code is greater than 399 and the content type is either JSON or XML. // -// NOTE: Error object can be pointer or non-pointer. +// NOTE: [Request.SetError] input can be a pointer or non-pointer. // // client.R().SetError(&AuthError{}) // // OR // client.R().SetError(AuthError{}) // -// Accessing a error value from response instance. +// Accessing an error value from response instance. // // response.Error().(*AuthError) +// +// If this request Error object is nil, Resty will use the client-level error object Type if it is set. func (r *Request) SetError(err interface{}) *Request { r.Error = getPointer(err) return r } -// SetFile method is to set single file field name and its path for multipart upload. +// SetFile method sets a single file field name and its path for multipart upload. // // client.R(). // SetFile("my_file", "/Users/jeeva/Gas Bill - Sep.pdf") @@ -380,7 +399,7 @@ func (r *Request) SetFile(param, filePath string) *Request { return r } -// SetFiles method is to set multiple file field name and its path for multipart upload. +// SetFiles method sets multiple file field names and their paths for multipart uploads. // // client.R(). // SetFiles(map[string]string{ @@ -396,7 +415,7 @@ func (r *Request) SetFiles(files map[string]string) *Request { return r } -// SetFileReader method is to set single file using io.Reader for multipart upload. +// SetFileReader method is to set a file using [io.Reader] for multipart upload. // // client.R(). // SetFileReader("profile_img", "my-profile-img.png", bytes.NewReader(profileImgBytes)). @@ -411,7 +430,8 @@ func (r *Request) SetFileReader(param, fileName string, reader io.Reader) *Reque return r } -// SetMultipartFormData method allows simple form data to be attached to the request as `multipart:form-data` +// SetMultipartFormData method allows simple form data to be attached to the request +// as `multipart:form-data` func (r *Request) SetMultipartFormData(data map[string]string) *Request { for k, v := range data { r = r.SetMultipartField(k, "", "", strings.NewReader(v)) @@ -420,7 +440,7 @@ func (r *Request) SetMultipartFormData(data map[string]string) *Request { return r } -// SetMultipartField method is to set custom data using io.Reader for multipart upload. +// SetMultipartField method sets custom data with Content-Type using [io.Reader] for multipart upload. func (r *Request) SetMultipartField(param, fileName, contentType string, reader io.Reader) *Request { r.isMultiPart = true r.multipartFields = append(r.multipartFields, &MultipartField{ @@ -432,7 +452,7 @@ func (r *Request) SetMultipartField(param, fileName, contentType string, reader return r } -// SetMultipartFields method is to set multiple data fields using [io.Reader] for multipart upload. +// SetMultipartFields method sets multiple data fields using [io.Reader] for multipart upload. // // For Example: // @@ -450,7 +470,7 @@ func (r *Request) SetMultipartField(param, fileName, contentType string, reader // Reader: strings.NewReader(`{"input": {"name": "Uploaded document 2", "_filename" : ["file2.txt"]}}`), // }) // -// If you have slice already, then simply call- +// If you have a `slice` of fields already, then call- // // client.R().SetMultipartFields(fields...) func (r *Request) SetMultipartFields(fields ...*MultipartField) *Request { @@ -460,19 +480,20 @@ func (r *Request) SetMultipartFields(fields ...*MultipartField) *Request { } // SetMultipartBoundary method sets the custom multipart boundary for the multipart request. -// Typically, the `mime/multipart` package generates a random multipart boundary, if not provided. +// Typically, the `mime/multipart` package generates a random multipart boundary if not provided. func (r *Request) SetMultipartBoundary(boundary string) *Request { r.multipartBoundary = boundary return r } -// SetContentLength method sets the HTTP header `Content-Length` value for current request. -// By default Resty won't set `Content-Length`. Also you have an option to enable for every -// request. +// SetContentLength method sets the current request's HTTP header `Content-Length` value. +// By default, Resty won't set `Content-Length`. // // See [Client.SetContentLength] // // client.R().SetContentLength(true) +// +// It overrides the value set at the client instance level. func (r *Request) SetContentLength(l bool) *Request { r.setContentLength = l return r @@ -488,7 +509,7 @@ func (r *Request) SetContentLength(l bool) *Request { // // client.R().SetBasicAuth("go-resty", "welcome") // -// This method overrides the credentials set by method [Client.SetBasicAuth]. +// It overrides the credentials set by method [Client.SetBasicAuth]. func (r *Request) SetBasicAuth(username, password string) *Request { r.UserInfo = &User{Username: username, Password: password} return r @@ -502,13 +523,15 @@ func (r *Request) SetBasicAuth(username, password string) *Request { // // client.R().SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F") // -// This method overrides the Auth token set by method [Client.SetAuthToken]. +// It overrides the Auth token set by method [Client.SetAuthToken]. func (r *Request) SetAuthToken(token string) *Request { r.Token = token return r } -// SetAuthScheme method sets the auth token scheme type in the HTTP request. For Example: +// SetAuthScheme method sets the auth token scheme type in the HTTP request. +// +// Example Header value structure: // // Authorization: // @@ -516,12 +539,12 @@ func (r *Request) SetAuthToken(token string) *Request { // // client.R().SetAuthScheme("OAuth") // -// This auth header scheme gets added to all the request raised from this client instance. -// Also it can be overridden or set one at the request level is supported. +// // The outcome will be - +// Authorization: OAuth // // Information about Auth schemes can be found in [RFC 7235], IANA [HTTP Auth schemes] // -// This method overrides the Authorization scheme set by method [Client.SetAuthScheme]. +// It overrides the `Authorization` scheme set by method [Client.SetAuthScheme]. // // [RFC 7235]: https://tools.ietf.org/html/rfc7235 // [HTTP Auth schemes]: https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml#authschemes @@ -540,7 +563,7 @@ func (r *Request) SetAuthScheme(scheme string) *Request { // // Information about Digest Access Authentication can be found in [RFC 7616] // -// This method overrides the username and password set by method [Client.SetDigestAuth]. +// It overrides the digest username and password set by method [Client.SetDigestAuth]. // // [RFC 7616]: https://datatracker.ietf.org/doc/html/rfc7616 func (r *Request) SetDigestAuth(username, password string) *Request { @@ -560,9 +583,12 @@ func (r *Request) SetDigestAuth(username, password string) *Request { return r } -// SetOutput method sets the output file for current HTTP request. Current HTTP response will be -// saved into given file. It is similar to `curl -o` flag. Absolute path or relative path can be used. -// If is it relative path then output file goes under the output directory, as mentioned +// SetOutput method sets the output file for the current HTTP request. The current +// HTTP response will be saved in the given file. It is similar to the `curl -o` flag. +// +// Absolute path or relative path can be used. +// +// If it is a relative path, then the output file goes under the output directory, as mentioned // in the [Client.SetOutputDirectory]. // // client.R(). @@ -587,32 +613,35 @@ func (r *Request) SetSRV(srv *SRVRecord) *Request { return r } -// SetDoNotParseResponse method instructs `Resty` not to parse the response body automatically. -// Resty exposes the raw response body as [io.ReadCloser]. Also do not forget to close the body, -// otherwise you might get into connection leaks, no connection reuse. +// SetDoNotParseResponse method instructs Resty not to parse the response body automatically. +// Resty exposes the raw response body as [io.ReadCloser]. If you use it, do not +// forget to close the body, otherwise, you might get into connection leaks, and connection +// reuse may not happen. // -// NOTE: [Response] middlewares are not applicable, if you use this option. Basically you have -// taken over the control of response parsing from `Resty`. +// NOTE: [Response] middlewares are not executed using this option. You have +// taken over the control of response parsing from Resty. func (r *Request) SetDoNotParseResponse(parse bool) *Request { r.notParseResponse = parse return r } -// SetResponseBodyLimit set a max body size limit on response, avoid reading too many data to memory. +// SetResponseBodyLimit method sets a maximum body size limit in bytes on response, +// avoid reading too much data to memory. // -// Request will return [resty.ErrResponseBodyTooLarge] if uncompressed response body size if larger than limit. -// Body size limit will not be enforced in following case: +// Client will return [resty.ErrResponseBodyTooLarge] if the body size of the body +// in the uncompressed response is larger than the limit. +// Body size limit will not be enforced in the following cases: // - ResponseBodyLimit <= 0, which is the default behavior. -// - [Request.SetOutput] is called to save a response data to file. +// - [Request.SetOutput] is called to save response data to the file. // - "DoNotParseResponse" is set for client or request. // -// This will override Client config. +// It overrides the value set at the client instance level. see [Client.SetResponseBodyLimit] func (r *Request) SetResponseBodyLimit(v int) *Request { r.responseBodyLimit = v return r } -// SetPathParam method sets single URL path key-value pair in the +// SetPathParam method sets a single URL path key-value pair in the // Resty current request instance. // // client.R().SetPathParam("userId", "sample@sample.com") @@ -628,10 +657,9 @@ func (r *Request) SetResponseBodyLimit(v int) *Request { // Composed URL - /v1/users/groups%2Fdevelopers/details // // It replaces the value of the key while composing the request URL. -// The values will be escaped using `url.PathEscape` function. +// The values will be escaped using function [url.PathEscape]. // -// Also you can override Path Params value, which was set at client instance -// level. +// It overrides the path parameter set at the client instance level. func (r *Request) SetPathParam(param, value string) *Request { r.PathParams[param] = value return r @@ -650,11 +678,10 @@ func (r *Request) SetPathParam(param, value string) *Request { // URL - /v1/users/{userId}/{subAccountId}/{path}/details // Composed URL - /v1/users/sample@sample.com/100002/groups%2Fdevelopers/details // -// It replaces the value of the key while composing request URL. -// The value will be used as it is and will not be escaped. +// It replaces the value of the key while composing the request URL. +// The values will be escaped using function [url.PathEscape]. // -// Also you can override Path Params value, which was set at client instance -// level. +// It overrides the path parameter set at the client instance level. func (r *Request) SetPathParams(params map[string]string) *Request { for p, v := range params { r.SetPathParam(p, v) @@ -662,7 +689,7 @@ func (r *Request) SetPathParams(params map[string]string) *Request { return r } -// SetRawPathParam method sets single URL path key-value pair in the +// SetRawPathParam method sets a single URL path key-value pair in the // Resty current request instance. // // client.R().SetPathParam("userId", "sample@sample.com") @@ -678,10 +705,9 @@ func (r *Request) SetPathParams(params map[string]string) *Request { // Composed URL - /v1/users/groups/developers/details // // It replaces the value of the key while composing the request URL. -// The value will be used as it is and will not be escaped. +// The value will be used as-is and has not been escaped. // -// Also you can override Path Params value, which was set at client instance -// level. +// It overrides the raw path parameter set at the client instance level. func (r *Request) SetRawPathParam(param, value string) *Request { r.RawPathParams[param] = value return r @@ -700,11 +726,10 @@ func (r *Request) SetRawPathParam(param, value string) *Request { // URL - /v1/users/{userId}/{subAccountId}/{path}/details // Composed URL - /v1/users/sample@sample.com/100002/groups/developers/details // -// It replaces the value of the key while composing request URL. -// The values will be used as they are and will not be escaped. +// It replaces the value of the key while composing the request URL. +// The value will be used as-is and has not been escaped. // -// Also you can override Path Params value, which was set at client instance -// level. +// It overrides the raw path parameter set at the client instance level. func (r *Request) SetRawPathParams(params map[string]string) *Request { for p, v := range params { r.SetRawPathParam(p, v) @@ -713,23 +738,29 @@ func (r *Request) SetRawPathParams(params map[string]string) *Request { } // ExpectContentType method allows to provide fallback `Content-Type` for automatic unmarshalling -// when `Content-Type` response header is unavailable. +// when the `Content-Type` response header is unavailable. func (r *Request) ExpectContentType(contentType string) *Request { r.fallbackContentType = contentType return r } -// ForceContentType method provides a strong sense of response `Content-Type` for automatic unmarshalling. -// Resty gives this a higher priority than the `Content-Type` response header. This means that if both -// [Request.ForceContentType] is set and the response `Content-Type` is available, `ForceContentType` will win. +// ForceContentType method provides a strong sense of response `Content-Type` for +// automatic unmarshalling. Resty gives this a higher priority than the `Content-Type` +// response header. +// +// This means that if both [Request.ForceContentType] is set and +// the response `Content-Type` is available, `ForceContentType` will win. func (r *Request) ForceContentType(contentType string) *Request { r.forceContentType = contentType return r } -// SetJSONEscapeHTML method is to enable/disable the HTML escape on JSON marshal. +// SetJSONEscapeHTML method enables or disables the HTML escape on JSON marshal. +// By default, escape HTML is false. // -// NOTE: This option only applicable to standard JSON Marshaller. +// NOTE: This option only applies to the standard JSON Marshaller used by Resty. +// +// It overrides the value set at the client instance level, see [Client.SetJSONEscapeHTML] func (r *Request) SetJSONEscapeHTML(b bool) *Request { r.jsonEscapeHTML = b return r @@ -742,7 +773,7 @@ func (r *Request) SetJSONEscapeHTML(b bool) *Request { // Value:"This is cookie value", // }) // -// NOTE: Method appends the Cookie value into existing Cookie if already existing. +// NOTE: Method appends the Cookie value into existing Cookie even if its already existing. func (r *Request) SetCookie(hc *http.Cookie) *Request { r.Cookies = append(r.Cookies, hc) return r @@ -764,7 +795,7 @@ func (r *Request) SetCookie(hc *http.Cookie) *Request { // // Setting a cookies into resty's current request // client.R().SetCookies(cookies) // -// NOTE: Method appends the Cookie value into existing Cookie if already existing. +// NOTE: Method appends the Cookie value into existing Cookie even if its already existing. func (r *Request) SetCookies(rs []*http.Cookie) *Request { r.Cookies = append(r.Cookies, rs...) return r @@ -774,27 +805,34 @@ func (r *Request) SetCookies(rs []*http.Cookie) *Request { // By default, requests and responses inherit their logger from the client. // // Compliant to interface [resty.Logger]. +// +// It overrides the logger value set at the client instance level. func (r *Request) SetLogger(l Logger) *Request { r.log = l return r } -// SetDebug method enables the debug mode on current request Resty request, It logs +// SetDebug method enables the debug mode on the current request. It logs // the details current request and response. -// For [Request] it logs information such as HTTP verb, Relative URL path, Host, Headers, Body if it has one. -// For [Response] it logs information such as Status, Response Time, Headers, Body if it has one. // -// client.R().SetDebug(true) +// client.SetDebug(true) +// +// Also, it can be enabled at the request level for a particular request; see [Request.SetDebug]. +// - For [Request], it logs information such as HTTP verb, Relative URL path, +// Host, Headers, and Body if it has one. +// - For [Response], it logs information such as Status, Response Time, Headers, +// and Body if it has one. func (r *Request) SetDebug(d bool) *Request { r.Debug = d return r } // AddRetryCondition method adds a retry condition function to the request's -// array of functions that are checked to determine if the request is retried. -// The request will retry if any of the functions return true and error is nil. +// array of functions is checked to determine if the request can be retried. +// The request will retry if any functions return true and the error is nil. // -// NOTE: These retry conditions are checked before all retry conditions of the client. +// NOTE: The request level retry conditions are checked before all retry +// conditions from the client instance. func (r *Request) AddRetryCondition(condition RetryConditionFunc) *Request { r.retryConditions = append(r.retryConditions, condition) return r @@ -813,7 +851,7 @@ func (r *Request) AddRetryCondition(condition RetryConditionFunc) *Request { // fmt.Println("Error:", err) // fmt.Println("Trace Info:", resp.Request.TraceInfo()) // -// See [Client.EnableTrace] available too to get trace info for all requests. +// See [Client.EnableTrace] is also available to get trace info for all requests. func (r *Request) EnableTrace() *Request { r.trace = true return r @@ -823,7 +861,7 @@ func (r *Request) EnableTrace() *Request { // It works in conjunction with debug mode. It overrides the options set by the [Client]. // // NOTE: Use with care. -// - Potential to leak sensitive data in the debug log from [Request] and [Response]. +// - Potential to leak sensitive data from [Request] and [Response] in the debug log. // - Beware of memory usage since the request body is reread. func (r *Request) EnableGenerateCurlOnDebug() *Request { r.generateCurlOnDebug = true @@ -839,7 +877,7 @@ func (r *Request) DisableGenerateCurlOnDebug() *Request { // TraceInfo method returns the trace info for the request. // If either the [Client.EnableTrace] or [Request.EnableTrace] function has not been called -// prior to the request being made, an empty [resty.TraceInfo] object will be returned. +// before the request is made, an empty [resty.TraceInfo] object is returned. func (r *Request) TraceInfo() TraceInfo { ct := r.clientTrace @@ -938,7 +976,7 @@ func (r *Request) Send() (*Response, error) { return r.Execute(r.Method, r.URL) } -// Execute method performs the HTTP request with given HTTP method and URL +// Execute method performs the HTTP request with the given HTTP method and URL // for current [Request]. // // resp, err := client.R().Execute(resty.MethodGet, "http://httpbin.org/get") diff --git a/response.go b/response.go index 5a85aac..c3e4611 100644 --- a/response.go +++ b/response.go @@ -17,7 +17,7 @@ import ( // Response struct and methods //_______________________________________________________________________ -// Response struct holds response values of executed request. +// Response struct holds response values of executed requests. type Response struct { Request *Request RawResponse *http.Response @@ -27,9 +27,10 @@ type Response struct { receivedAt time.Time } -// Body method returns HTTP response as []byte array for the executed request. +// Body method returns the HTTP response as `[]byte` slice for the executed request. // -// NOTE: [Response.Body] might be nil, if [Request.SetOutput] is used. +// NOTE: [Response.Body] might be nil if [Request.SetOutput] is used. +// Also see [Request.SetDoNotParseResponse], [Client.SetDoNotParseResponse] func (r *Response) Body() []byte { if r.RawResponse == nil { return []byte{} @@ -37,8 +38,8 @@ func (r *Response) Body() []byte { return r.body } -// SetBody method is to set [Response] body in byte slice. Typically, -// its helpful for test cases. +// SetBody method sets [Response] body in byte slice. Typically, +// It is helpful for test cases. // // resp.SetBody([]byte("This is test body content")) // resp.SetBody(nil) @@ -76,11 +77,15 @@ func (r *Response) Proto() string { } // Result method returns the response value as an object if it has one +// +// See [Request.SetResult] func (r *Response) Result() interface{} { return r.Request.Result } // Error method returns the error object if it has one +// +// See [Request.SetError], [Client.SetError] func (r *Response) Error() interface{} { return r.Request.Error } @@ -93,7 +98,7 @@ func (r *Response) Header() http.Header { return r.RawResponse.Header } -// Cookies method to access all the response cookies +// Cookies method to returns all the response cookies func (r *Response) Cookies() []*http.Cookie { if r.RawResponse == nil { return make([]*http.Cookie, 0) @@ -101,7 +106,8 @@ func (r *Response) Cookies() []*http.Cookie { return r.RawResponse.Cookies() } -// String method returns the body of the server response as String. +// String method returns the body of the HTTP response as a `string`. +// It returns an empty string if it is nil or the body is zero length. func (r *Response) String() string { if len(r.body) == 0 { return "" @@ -109,10 +115,11 @@ func (r *Response) String() string { return strings.TrimSpace(string(r.body)) } -// Time method returns the time of HTTP response time that from request we sent and received a request. +// Time method returns the duration of HTTP response time from the request we sent +// and received a request. // -// See [Response.ReceivedAt] to know when client received response and see `Response.Request.Time` to know -// when client sent a request. +// See [Response.ReceivedAt] to know when the client received a response and see +// `Response.Request.Time` to know when the client sent a request. func (r *Response) Time() time.Duration { if r.Request.clientTrace != nil { return r.Request.TraceInfo().TotalTime @@ -120,24 +127,25 @@ func (r *Response) Time() time.Duration { return r.receivedAt.Sub(r.Request.Time) } -// ReceivedAt method returns when response got received from server for the request. +// ReceivedAt method returns the time we received a response from the server for the request. func (r *Response) ReceivedAt() time.Time { return r.receivedAt } -// Size method returns the HTTP response size in bytes. Ya, you can relay on HTTP `Content-Length` header, -// however it won't be good for chucked transfer/compressed response. Since Resty calculates response size -// at the client end. You will get actual size of the http response. +// Size method returns the HTTP response size in bytes. Yeah, you can rely on HTTP `Content-Length` +// header, however it won't be available for chucked transfer/compressed response. +// Since Resty captures response size details when processing the response body +// when possible. So that users get the actual size of response bytes. func (r *Response) Size() int64 { return r.size } -// RawBody method exposes the HTTP raw response body. Use this method in-conjunction with +// RawBody method exposes the HTTP raw response body. Use this method in conjunction with // [Client.SetDoNotParseResponse] or [Request.SetDoNotParseResponse] -// option otherwise you get an error as `read err: http: read on closed response body`. +// option; otherwise, you get an error as `read err: http: read on closed response body.` // // Do not forget to close the body, otherwise you might get into connection leaks, no connection reuse. -// Basically you have taken over the control of response parsing from `Resty`. +// You have taken over the control of response parsing from Resty. func (r *Response) RawBody() io.ReadCloser { if r.RawResponse == nil { return nil diff --git a/resty.go b/resty.go index 8545174..e5eb292 100644 --- a/resty.go +++ b/resty.go @@ -29,7 +29,7 @@ func NewWithClient(hc *http.Client) *Client { return createClient(hc) } -// NewWithLocalAddr method creates a new Resty client with given Local Address +// NewWithLocalAddr method creates a new Resty client with the given Local Address. // to dial from. func NewWithLocalAddr(localAddr net.Addr) *Client { cookieJar, _ := cookiejar.New(&cookiejar.Options{PublicSuffixList: publicsuffix.List}) diff --git a/retry.go b/retry.go index 16f5416..416107e 100644 --- a/retry.go +++ b/retry.go @@ -23,7 +23,7 @@ type ( // Option is to create convenient retry options like wait time, max retries, etc. Option func(*Options) - // RetryConditionFunc type is for retry condition function + // RetryConditionFunc type is for the retry condition function // input: non-nil Response OR request execution error RetryConditionFunc func(*Response, error) bool @@ -33,8 +33,8 @@ type ( // RetryAfterFunc returns time to wait before retry // For example, it can parse HTTP Retry-After header // https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html - // Non-nil error is returned if it is found that request is not retryable - // (0, nil) is a special result means 'use default algorithm' + // Non-nil error is returned if it is found that the request is not retryable + // (0, nil) is a special result that means 'use default algorithm' RetryAfterFunc func(*Client, *Response) (time.Duration, error) // Options struct is used to hold retry settings. @@ -69,7 +69,7 @@ func MaxWaitTime(value time.Duration) Option { } } -// RetryConditions sets the conditions that will be checked for retry. +// RetryConditions sets the conditions that will be checked for retry func RetryConditions(conditions []RetryConditionFunc) Option { return func(o *Options) { o.retryConditions = conditions @@ -84,7 +84,7 @@ func RetryHooks(hooks []OnRetryFunc) Option { } // ResetMultipartReaders sets a boolean value which will lead the start being seeked out -// on all multipart file readers, if they implement [io.ReadSeeker] +// on all multipart file readers if they implement [io.ReadSeeker] func ResetMultipartReaders(value bool) Option { return func(o *Options) { o.resetReaders = value @@ -202,7 +202,7 @@ func sleepDuration(resp *Response, min, max time.Duration, attempt int) (time.Du } // Return capped exponential backoff with jitter -// http://www.awsarchitectureblog.com/2015/03/backoff.html +// https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ func jitterBackoff(min, max time.Duration, attempt int) time.Duration { base := float64(min) capLevel := float64(max) diff --git a/shellescape/shellescape.go b/shellescape/shellescape.go index c46b5e7..1e835cb 100644 --- a/shellescape/shellescape.go +++ b/shellescape/shellescape.go @@ -25,8 +25,8 @@ func init() { pattern = regexp.MustCompile(`[^\w@%+=:,./-]`) } -// Quote returns a shell-escaped version of the string s. The returned value -// is a string that can safely be used as one token in a shell command line. +// Quote method returns a shell-escaped version of the string. The returned value +// can safely be used as one token in a shell command line. func Quote(s string) string { if len(s) == 0 { return "''" diff --git a/trace.go b/trace.go index 2fb2ceb..226bfbf 100644 --- a/trace.go +++ b/trace.go @@ -16,30 +16,30 @@ import ( // TraceInfo struct //_______________________________________________________________________ -// TraceInfo struct is used provide request trace info such as DNS lookup +// TraceInfo struct is used to provide request trace info such as DNS lookup // duration, Connection obtain duration, Server processing duration, etc. type TraceInfo struct { - // DNSLookup is a duration that transport took to perform + // DNSLookup is the duration that transport took to perform // DNS lookup. DNSLookup time.Duration - // ConnTime is a duration that took to obtain a successful connection. + // ConnTime is the duration it took to obtain a successful connection. ConnTime time.Duration - // TCPConnTime is a duration that took to obtain the TCP connection. + // TCPConnTime is the duration it took to obtain the TCP connection. TCPConnTime time.Duration - // TLSHandshake is a duration that TLS handshake took place. + // TLSHandshake is the duration of the TLS handshake. TLSHandshake time.Duration - // ServerTime is a duration that server took to respond first byte. + // ServerTime is the server's duration for responding to the first byte. ServerTime time.Duration - // ResponseTime is a duration since first response byte from server to + // ResponseTime is the duration since the first response byte from the server to // request completion. ResponseTime time.Duration - // TotalTime is a duration that total request took end-to-end. + // TotalTime is the duration of the total time request taken end-to-end. TotalTime time.Duration // IsConnReused is whether this connection has been previously @@ -50,7 +50,7 @@ type TraceInfo struct { // idle pool. IsConnWasIdle bool - // ConnIdleTime is a duration how long the connection was previously + // ConnIdleTime is the duration how long the connection that was previously // idle, if IsConnWasIdle is true. ConnIdleTime time.Duration @@ -66,8 +66,8 @@ type TraceInfo struct { // ClientTrace struct and its methods //_______________________________________________________________________ -// tracer struct maps the [httptrace.ClientTrace] hooks into Fields -// with same naming for easy understanding. Plus additional insights +// clientTrace struct maps the [httptrace.ClientTrace] hooks into Fields +// with the same naming for easy understanding. Plus additional insights // [Request]. type clientTrace struct { getConn time.Time