diff --git a/client.go b/client.go index 1c890999..419f3c07 100644 --- a/client.go +++ b/client.go @@ -602,8 +602,8 @@ func (c *Client) SetAuthScheme(scheme string) *Client { // // NOTE: // - On the QOP `auth-int` scenario, the request body is read into memory to -// compute the body hash that consumes additional memory usage. -// - It is recommended to create a dedicated client instance for digest auth, +// compute the body hash that increases memory usage. +// - Create a dedicated client instance to use digest auth, // as it does digest auth for all the requests raised by the client. // // [RFC 7616]: https://datatracker.ietf.org/doc/html/rfc7616 @@ -676,16 +676,12 @@ func (c *Client) NewRequest() *Request { // SetRequestMiddlewares method allows Resty users to override the default request // middlewares sequence // -// client := New() -// defer client.Close() -// // client.SetRequestMiddlewares( -// CustomRequest1Middleware, -// CustomRequest2Middleware, -// resty.PrepareRequestMiddleware, // after this, Request.RawRequest is available -// resty.GenerateCurlRequestMiddleware, -// CustomRequest3Middleware, -// CustomRequest4Middleware, +// Custom1RequestMiddleware, +// Custom2RequestMiddleware, +// resty.PrepareRequestMiddleware, // after this, `Request.RawRequest` instance is available +// Custom3RequestMiddleware, +// Custom4RequestMiddleware, // ) // // See, [Client.AddRequestMiddleware] @@ -703,23 +699,20 @@ func (c *Client) SetRequestMiddlewares(middlewares ...RequestMiddleware) *Client // SetResponseMiddlewares method allows Resty users to override the default response // middlewares sequence // -// client := New() -// defer client.Close() -// // client.SetResponseMiddlewares( -// CustomResponse1Middleware, -// CustomResponse2Middleware, -// resty.AutoParseResponseMiddleware, // before this, body is not read except on debug flow -// CustomResponse3Middleware, -// resty.SaveToFileResponseMiddleware, // See, Request.SetOutputFile -// CustomResponse4Middleware, -// CustomResponse5Middleware, +// Custom1ResponseMiddleware, +// Custom2ResponseMiddleware, +// resty.AutoParseResponseMiddleware, // before this, the body is not read except on the debug flow +// Custom3ResponseMiddleware, +// resty.SaveToFileResponseMiddleware, // See, Request.SetOutputFileName, Request.SetSaveResponse +// Custom4ResponseMiddleware, +// Custom5ResponseMiddleware, // ) // // See, [Client.AddResponseMiddleware] // // NOTE: -// - It overwrites the existing request middleware list. +// - It overwrites the existing response middleware list. // - Be sure to include Resty response middlewares in the response chain at the appropriate spot. func (c *Client) SetResponseMiddlewares(middlewares ...ResponseMiddleware) *Client { c.lock.Lock() @@ -1167,7 +1160,7 @@ func (c *Client) Timeout() time.Duration { // // It can be overridden at the request level. See [Request.SetTimeout] // -// NOTE: Resty uses [context.WithTimeout] on the request, it does not use [http.Client.Timeout] +// NOTE: Resty uses [context.WithTimeout] on the request, it does not use [http.Client].Timeout func (c *Client) SetTimeout(timeout time.Duration) *Client { c.lock.Lock() defer c.lock.Unlock() @@ -1242,7 +1235,7 @@ func (c *Client) RetryCount() int { // See [Request.SetRetryStrategy] // // NOTE: -// - By default, Resty only does retry on idempotent HTTP methods, [RFC 9110 Section 9.2.2], [RFC 9110 Section 18.2] +// - By default, Resty only does retry on idempotent HTTP verb, [RFC 9110 Section 9.2.2], [RFC 9110 Section 18.2] // // [RFC 9110 Section 9.2.2]: https://datatracker.ietf.org/doc/html/rfc9110.html#name-idempotent-methods // [RFC 9110 Section 18.2]: https://datatracker.ietf.org/doc/html/rfc9110.html#name-method-registration @@ -1380,8 +1373,9 @@ func (c *Client) RetryConditions() []RetryConditionFunc { // The request will retry if any functions return `true`, otherwise return `false`. // // NOTE: +// - The default retry conditions are applied first. // - The client-level retry conditions are applied to all requests. -// - The request-level retry conditions are executed first before client-level +// - The request-level retry conditions are executed first before the client-level // retry conditions. See [Request.AddRetryConditions], [Request.SetRetryConditions] func (c *Client) AddRetryConditions(conditions ...RetryConditionFunc) *Client { c.lock.Lock() @@ -1422,13 +1416,12 @@ func (c *Client) TLSClientConfig() *tls.Config { // SetTLSClientConfig method sets TLSClientConfig for underlying client Transport. // -// For Example: -// -// // One can set a custom root certificate. Refer: http://golang.org/pkg/crypto/tls/#example_Dial -// client.SetTLSClientConfig(&tls.Config{ RootCAs: roots }) +// Values supported by https://pkg.go.dev/crypto/tls#Config can be configured. // -// // or One can disable security check (https) -// client.SetTLSClientConfig(&tls.Config{ InsecureSkipVerify: true }) +// // Disable SSL cert verification for local development +// client.SetTLSClientConfig(&tls.Config{ +// InsecureSkipVerify: true +// }) // // NOTE: This method overwrites existing [http.Transport.TLSClientConfig] func (c *Client) SetTLSClientConfig(tlsConfig *tls.Config) *Client { @@ -1507,7 +1500,7 @@ func (c *Client) RemoveProxy() *Client { return c } -// SetCertificateFromString method helps to set client certificates into Resty +// SetCertificateFromFile method helps to set client certificates into Resty // from cert and key files to perform SSL client authentication // // client.SetCertificateFromFile("certs/client.pem", "certs/client.key") @@ -1543,8 +1536,8 @@ func (c *Client) SetCertificateFromString(certStr, certKeyStr string) *Client { return c } -// SetCertificates method helps to conveniently set client certificates into Resty -// to perform SSL client authentication +// SetCertificates method helps to conveniently set a slice of client certificates +// into Resty to perform SSL client authentication // // cert, err := tls.LoadX509KeyPair("certs/client.pem", "certs/client.key") // if err != nil { @@ -1566,7 +1559,8 @@ func (c *Client) SetCertificates(certs ...tls.Certificate) *Client { return c } -// SetRootCertificates method helps to add one or more root certificates into the Resty client +// SetRootCertificates method helps to add one or more root certificate files +// into the Resty client // // // one pem file path // client.SetRootCertificates("/path/to/root/pemFile.pem") @@ -1592,14 +1586,14 @@ func (c *Client) SetRootCertificates(pemFilePaths ...string) *Client { return c } -// SetRootCertificatesWatcher method enables dynamic reloading of one or more root certificates. +// SetRootCertificatesWatcher method enables dynamic reloading of one or more root certificate files. // It is designed for scenarios involving long-running Resty clients where certificates may be renewed. // // client.SetRootCertificatesWatcher( // &resty.CertWatcherOptions{ // PoolInterval: 24 * time.Hour, // }, -// "root-ca.crt", +// "root-ca.pem", // ) func (c *Client) SetRootCertificatesWatcher(options *CertWatcherOptions, pemFilePaths ...string) *Client { c.SetRootCertificates(pemFilePaths...) @@ -1609,7 +1603,7 @@ func (c *Client) SetRootCertificatesWatcher(options *CertWatcherOptions, pemFile return c } -// SetRootCertificateFromString method helps to add one or more root certificates +// SetRootCertificateFromString method helps to add root certificate from the string // into the Resty client // // myRootCertStr := `-----BEGIN CERTIFICATE----- @@ -1622,21 +1616,21 @@ func (c *Client) SetRootCertificateFromString(pemCerts string) *Client { return c } -// SetClientRootCertificates method helps to add one or more client's root -// certificates into the Resty client +// SetClientRootCertificates method helps to add one or more client root +// certificate files into the Resty client // // // one pem file path -// client.SetClientCertificates("/path/to/client/pemFile.pem") +// client.SetClientRootCertificates("/path/to/client-root/pemFile.pem") // // // one or more pem file path(s) -// client.SetClientCertificates( -// "/path/to/client/pemFile1.pem", -// "/path/to/client/pemFile2.pem" -// "/path/to/client/pemFile3.pem" +// client.SetClientRootCertificates( +// "/path/to/client-root/pemFile1.pem", +// "/path/to/client-root/pemFile2.pem" +// "/path/to/client-root/pemFile3.pem" // ) // // // if you happen to have string slices -// client.SetClientCertificates(certs...) +// client.SetClientRootCertificates(certs...) func (c *Client) SetClientRootCertificates(pemFilePaths ...string) *Client { for _, fp := range pemFilePaths { pemData, err := os.ReadFile(fp) @@ -1649,14 +1643,14 @@ func (c *Client) SetClientRootCertificates(pemFilePaths ...string) *Client { return c } -// SetClientRootCertificatesWatcher method enables dynamic reloading of one or more client root certificates. +// SetClientRootCertificatesWatcher method enables dynamic reloading of one or more client root certificate files. // It is designed for scenarios involving long-running Resty clients where certificates may be renewed. // // client.SetClientRootCertificatesWatcher( // &resty.CertWatcherOptions{ // PoolInterval: 24 * time.Hour, // }, -// "root-ca.crt", +// "client-root-ca.pem", // ) func (c *Client) SetClientRootCertificatesWatcher(options *CertWatcherOptions, pemFilePaths ...string) *Client { c.SetClientRootCertificates(pemFilePaths...) @@ -1666,8 +1660,8 @@ func (c *Client) SetClientRootCertificatesWatcher(options *CertWatcherOptions, p return c } -// SetClientRootCertificateFromString method helps to add one or more clients -// root certificates into the Resty client +// SetClientRootCertificateFromString method helps to add a client root certificate +// from the string into the Resty client // // myClientRootCertStr := `-----BEGIN CERTIFICATE----- // ... cert content ... @@ -1878,12 +1872,13 @@ func (c *Client) SetCloseConnection(close bool) *Client { } // 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 executed using this option. You have -// taken over the control of response parsing from Resty. +// NOTE: The default [Response] middlewares are not executed when using this option. User +// takes over the control of handling response body from Resty. func (c *Client) SetDoNotParseResponse(notParse bool) *Client { c.lock.Lock() defer c.lock.Unlock() @@ -2074,7 +2069,8 @@ func (c *Client) SetTrace(t bool) *Client { // client instance level. // // By default, Resty does not log the curl command in the debug log since it has the potential -// to leak sensitive data unless explicitly enabled via [Client.SetDebugLogCurlCmd]. +// to leak sensitive data unless explicitly enabled via [Client.SetDebugLogCurlCmd] or +// [Request.SetDebugLogCurlCmd]. // // NOTE: Use with care. // - Potential to leak sensitive data from [Request] and [Response] in the debug log @@ -2097,7 +2093,8 @@ func (c *Client) DisableGenerateCurlCmd() *Client { // client instance level. // // By default, Resty does not log the curl command in the debug log since it has the potential -// to leak sensitive data unless explicitly enabled via [Client.SetDebugLogCurlCmd]. +// to leak sensitive data unless explicitly enabled via [Client.SetDebugLogCurlCmd] or +// [Request.SetDebugLogCurlCmd]. // // NOTE: Use with care. // - Potential to leak sensitive data from [Request] and [Response] in the debug log @@ -2143,7 +2140,7 @@ func (c *Client) ResponseBodyUnlimitedReads() bool { return c.resBodyUnlimitedReads } -// SetResponseBodyUnlimitedReads method is to turn on/off the response body copy +// SetResponseBodyUnlimitedReads method is to turn on/off the response body in memory // that provides an ability to do unlimited reads. // // It can be overridden at the request level; see [Request.SetResponseBodyUnlimitedReads] @@ -2152,7 +2149,7 @@ func (c *Client) ResponseBodyUnlimitedReads() bool { // - When debug mode is enabled // // NOTE: Use with care -// - Turning on this feature uses additional memory to store a copy of the response body buffer. +// - Turning on this feature keeps the response body in memory, which might cause additional memory usage. func (c *Client) SetResponseBodyUnlimitedReads(b bool) *Client { c.lock.Lock() defer c.lock.Unlock() @@ -2179,7 +2176,8 @@ func (c *Client) Client() *http.Client { // - Interface values are not deeply cloned. Thus, both the original and the // clone will use the same value. // - It is not safe for concurrent use. You should only use this method -// when you are sure that any other concurrent process is not using the client. +// when you are sure that any other concurrent process is not using the client +// or client instance is protected by a mutex. func (c *Client) Clone(ctx context.Context) *Client { cc := new(Client) // dereference the pointer and copy the value diff --git a/multipart.go b/multipart.go index 17cd6dff..0cba259a 100644 --- a/multipart.go +++ b/multipart.go @@ -49,8 +49,8 @@ type MultipartField struct { // ProgressCallback function is used to provide live progress details // during a multipart upload (Optional) // - // NOTE: It is recommended to set the FileSize value when using - // ProgressCallback feature so that Resty sends the FileSize + // NOTE: It is recommended to set the FileSize value when using `MultipartField.Reader` + // with `ProgressCallback` feature so that Resty sends the FileSize // value via [MultipartFieldProgress] ProgressCallback MultipartFieldCallbackFunc diff --git a/request.go b/request.go index 97fc599e..0f1b10bb 100644 --- a/request.go +++ b/request.go @@ -668,7 +668,7 @@ func (r *Request) SetAuthScheme(scheme string) *Request { // // NOTE: In this scenario // - [Response.BodyBytes] might be nil. -// - [Response].Body might be already read. +// - [Response].Body might have been already read. func (r *Request) SetOutputFileName(file string) *Request { r.OutputFileName = file r.SetSaveResponse(true) @@ -701,12 +701,13 @@ func (r *Request) SetCloseConnection(close bool) *Request { } // 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 executed using this option. You have -// taken over the control of response parsing from Resty. +// NOTE: The default [Response] middlewares are not executed when using this option. User +// takes over the control of handling response body from Resty. func (r *Request) SetDoNotParseResponse(notParse bool) *Request { r.DoNotParseResponse = notParse return r @@ -728,7 +729,7 @@ func (r *Request) SetResponseBodyLimit(v int64) *Request { return r } -// SetResponseBodyUnlimitedReads method is to turn on/off the response body copy +// SetResponseBodyUnlimitedReads method is to turn on/off the response body in memory // that provides an ability to do unlimited reads. // // It overrides the value set at the client level; see [Client.SetResponseBodyUnlimitedReads] @@ -737,7 +738,7 @@ func (r *Request) SetResponseBodyLimit(v int64) *Request { // - When debug mode is enabled // // NOTE: Use with care -// - Turning on this feature uses additional memory to store a copy of the response body buffer. +// - Turning on this feature keeps the response body in memory, which might cause additional memory usage. func (r *Request) SetResponseBodyUnlimitedReads(b bool) *Request { r.ResponseBodyUnlimitedReads = b return r @@ -960,8 +961,9 @@ func (r *Request) SetDebug(d bool) *Request { // The request will retry if any functions return `true`, otherwise return `false`. // // NOTE: +// - The default retry conditions are applied first. // - The client-level retry conditions are applied to all requests. -// - The request-level retry conditions are executed first before client-level +// - The request-level retry conditions are executed first before the client-level // retry conditions. See [Request.SetRetryConditions] func (r *Request) AddRetryConditions(conditions ...RetryConditionFunc) *Request { r.retryConditions = append(r.retryConditions, conditions...) @@ -980,7 +982,7 @@ func (r *Request) SetRetryConditions(conditions ...RetryConditionFunc) *Request // // NOTE: // - All the retry hooks are executed on each request retry. -// - The request-level retry hooks are executed first before client-level hooks. +// - The request-level retry hooks are executed first before the client-level hooks. func (r *Request) AddRetryHooks(hooks ...RetryHookFunc) *Request { r.retryHooks = append(r.retryHooks, hooks...) return r @@ -1003,7 +1005,7 @@ func (r *Request) SetRetryHooks(hooks ...RetryHookFunc) *Request { // See [Request.SetRetryStrategy] // // NOTE: -// - By default, Resty only does retry on idempotent HTTP methods, [RFC 9110 Section 9.2.2], [RFC 9110 Section 18.2] +// - By default, Resty only does retry on idempotent HTTP verb, [RFC 9110 Section 9.2.2], [RFC 9110 Section 18.2] // // [RFC 9110 Section 9.2.2]: https://datatracker.ietf.org/doc/html/rfc9110.html#name-idempotent-methods // [RFC 9110 Section 18.2]: https://datatracker.ietf.org/doc/html/rfc9110.html#name-method-registration @@ -1109,10 +1111,12 @@ func (r *Request) SetTrace(t bool) *Request { } // EnableGenerateCurlCmd method enables the generation of curl commands for the current request. -// It overrides the options set in the [Client]. // // By default, Resty does not log the curl command in the debug log since it has the potential -// to leak sensitive data unless explicitly enabled via [Request.SetDebugLogCurlCmd]. +// to leak sensitive data unless explicitly enabled via [Request.SetDebugLogCurlCmd] or +// [Client.SetDebugLogCurlCmd]. +// +// It overrides the options set in the [Client]. // // NOTE: Use with care. // - Potential to leak sensitive data from [Request] and [Response] in the debug log @@ -1136,15 +1140,16 @@ func (r *Request) DisableGenerateCurlCmd() *Request { // SetGenerateCurlCmd method is used to turn on/off the generate curl command for the current request. // // By default, Resty does not log the curl command in the debug log since it has the potential -// to leak sensitive data unless explicitly enabled via [Request.SetDebugLogCurlCmd]. +// to leak sensitive data unless explicitly enabled via [Request.SetDebugLogCurlCmd] or +// [Client.SetDebugLogCurlCmd]. +// +// It overrides the options set by the [Client.SetGenerateCurlCmd] // // NOTE: Use with care. // - Potential to leak sensitive data from [Request] and [Response] in the debug log // when the debug log option is enabled. // - Additional memory usage since the request body was reread. // - curl body is not generated for [io.Reader] and multipart request flow. -// -// It overrides the options set by the [Client.SetGenerateCurlCmd] func (r *Request) SetGenerateCurlCmd(b bool) *Request { r.generateCurlCmd = b return r @@ -1271,42 +1276,58 @@ func (r *Request) TraceInfo() TraceInfo { // HTTP verb method starts here //_______________________________________________________________________ -// Get method does GET HTTP request. It's defined in section 4.3.1 of RFC7231. +// Get method does GET HTTP request. It's defined in section 9.3.1 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.1 func (r *Request) Get(url string) (*Response, error) { return r.Execute(MethodGet, url) } -// Head method does HEAD HTTP request. It's defined in section 4.3.2 of RFC7231. +// Head method does HEAD HTTP request. It's defined in section 9.3.2 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.2 func (r *Request) Head(url string) (*Response, error) { return r.Execute(MethodHead, url) } -// Post method does POST HTTP request. It's defined in section 4.3.3 of RFC7231. +// Post method does POST HTTP request. It's defined in section 9.3.3 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.3 func (r *Request) Post(url string) (*Response, error) { return r.Execute(MethodPost, url) } -// Put method does PUT HTTP request. It's defined in section 4.3.4 of RFC7231. +// Put method does PUT HTTP request. It's defined in section 9.3.4 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.4 func (r *Request) Put(url string) (*Response, error) { return r.Execute(MethodPut, url) } -// Patch method does PATCH HTTP request. It's defined in section 2 of RFC5789. +// Patch method does PATCH HTTP request. It's defined in section 2 of [RFC 5789]. +// +// [RFC 5789]: https://datatracker.ietf.org/doc/html/rfc5789.html#section-2 func (r *Request) Patch(url string) (*Response, error) { return r.Execute(MethodPatch, url) } -// Delete method does DELETE HTTP request. It's defined in section 4.3.5 of RFC7231. +// Delete method does DELETE HTTP request. It's defined in section 9.3.5 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.5 func (r *Request) Delete(url string) (*Response, error) { return r.Execute(MethodDelete, url) } -// Options method does OPTIONS HTTP request. It's defined in section 4.3.7 of RFC7231. +// Options method does OPTIONS HTTP request. It's defined in section 9.3.7 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.7 func (r *Request) Options(url string) (*Response, error) { return r.Execute(MethodOptions, url) } -// Trace method does TRACE HTTP request. It's defined in section 4.3.8 of RFC7231. +// Trace method does TRACE HTTP request. It's defined in section 9.3.8 of [RFC 9110]. +// +// [RFC 9110]: https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.8 func (r *Request) Trace(url string) (*Response, error) { return r.Execute(MethodTrace, url) } diff --git a/response.go b/response.go index 3299f797..4148147c 100644 --- a/response.go +++ b/response.go @@ -99,7 +99,7 @@ func (r *Response) Cookies() []*http.Cookie { // NOTE: // - Returns an empty string on auto-unmarshal scenarios, unless // [Client.SetResponseBodyUnlimitedReads] or [Request.SetResponseBodyUnlimitedReads] set. -// - Returns an empty string when [Client.SetDoNotParseResponse] or [Request.SetDoNotParseResponse] set +// - Returns an empty string when [Client.SetDoNotParseResponse] or [Request.SetDoNotParseResponse] set. func (r *Response) String() string { r.readIfRequired() return strings.TrimSpace(string(r.bodyBytes)) @@ -111,7 +111,7 @@ func (r *Response) String() string { // NOTE: // - Returns an empty byte slice on auto-unmarshal scenarios, unless // [Client.SetResponseBodyUnlimitedReads] or [Request.SetResponseBodyUnlimitedReads] set. -// - Returns an empty string when [Client.SetDoNotParseResponse] or [Request.SetDoNotParseResponse] set +// - Returns an empty byte slice when [Client.SetDoNotParseResponse] or [Request.SetDoNotParseResponse] set. func (r *Response) Bytes() []byte { r.readIfRequired() return r.bodyBytes diff --git a/sse.go b/sse.go index e44ca7a8..440cabea 100644 --- a/sse.go +++ b/sse.go @@ -172,7 +172,7 @@ func (es *EventSource) SetRetryCount(count int) *EventSource { // // Default is 100 milliseconds. // -// NOTE: The server-sent retry value takes precedence if available. +// NOTE: The server-sent retry value takes precedence if present. // // es.SetRetryWaitTime(1 * time.Second) func (es *EventSource) SetRetryWaitTime(waitTime time.Duration) *EventSource { @@ -187,7 +187,7 @@ func (es *EventSource) SetRetryWaitTime(waitTime time.Duration) *EventSource { // // Default is 2 seconds. // -// NOTE: The server-sent retry value takes precedence if available. +// NOTE: The server-sent retry value takes precedence if present. // // es.SetRetryMaxWaitTime(3 * time.Second) func (es *EventSource) SetRetryMaxWaitTime(maxWaitTime time.Duration) *EventSource {