Merge pull request #10 from go-resty/docs-part9

Docs part9

assets/_custom.scss

@@ -95,6 +95,12 @@ a .r-icon {
     background-color: #282a36;
 }
 
+.resty-go-min {
+    margin-top: .3rem;
+    text-align: center;
+    font-size: 0.8em;
+}
+
 .global-msg {
     margin: 0 0 2rem;
     padding: .5rem 1rem .5rem .75rem;

content/_index.md

@@ -31,6 +31,7 @@ type: docs
 <code>require resty.dev/v3 {{% param Resty.V3.Version %}}</code>
 </pre>
 </div>
+<div class="resty-go-min">Minimum required Go version is {{% param Resty.V3.GoMinVersion %}}</div>
 
 {{% columns %}}
 ```go
@@ -49,8 +50,8 @@ fmt.Println(res.Request.TraceInfo())
 // Server-Sent Events Client
 es := NewEventSource().
     SetURL("https://sse.dev/test").
-    OnMessage(func(a any) {
-        fmt.Println(a.(*resty.Event))
+    OnMessage(func(e any) {
+        fmt.Println(e.(*resty.Event))
     }, nil)
 
 err := es.Get()
@@ -88,7 +89,7 @@ This website represents Resty v3 and above. For previous v2 documentation, refer
 * Download to file
 * Redirect Policies
 * Circuit Breaker Policy
-* Debug mode with human-readable log
+* Debug mode with human-readable, JSON log
 * Load Balancer and Service Discovery
 * Response body limit & Unlimited reads
 * Bazel support
@@ -112,5 +113,6 @@ Resty provides various ways to enhance its functionality by implementing its int
 * Request Functions
 * Redirect Policy
 * Transport RoundTripper
+* Debug Log Formatter
 * Logger
 

content/credits.md

@@ -5,9 +5,9 @@ bookHidden: true
 
 # Credits
 
-* [Caddy Web Server](https://caddyserver.com)
-* [Hugo Static Generator](https://gohugo.io)
-* Customized version of [hugo-book theme](https://github.com/alex-shpak/hugo-book)
+* [Caddy Server](https://caddyserver.com)
+* [Hugo](https://gohugo.io) Static Website Generator
+* Customized version of [hugo-book](https://github.com/alex-shpak/hugo-book) theme
 * Icons obtained from [UXWing](https://uxwing.com)
     * github-icon
     * contrast-icon

content/docs/debug-log.md

@@ -0,0 +1,81 @@
+
+# Debug Log
+
+The debug log provides insights into Resty's request and response details for troubleshooting. The v3 introduces the debug log formatter feature, allowing the debug log content customization for the user's use case. Out of the box, the following formatters are available:
+
+* [DebugLogFormatter]({{% godoc v3 %}}DebugLogFormatter) (default)
+* [DebugLogJSONFormatter]({{% godoc v3 %}}DebugLogJSONFormatter)
+
+## Default Behaviour
+
+* Automatically sanitize HTTP headers in both Request and Response if the header key contains `authorization`, `auth`, or `token`.
+* Applies a human-readable debug log formatter.
+
+## Examples
+
+### Get Started
+
+```go
+// enabling debug for all requests
+c := resty.New().
+    SetDebug(true)
+
+// enabling debug for a particular request
+req := c.R().SetDebug(true)
+
+// few syntactic sugar methods available; see Methods section
+```
+
+### Editing Log Details
+
+Register to debug log callback for any log modification; see [DebugLog]({{% godoc v3 %}}DebugLog).
+
+```go
+c := resty.New().
+    OnDebugLog(func(dl *DebugLog) {
+        // logic goes here
+    })
+```
+
+### JSON Formatter
+
+```go
+c := resty.New().
+    SetDebugLogFormatter(resty.DebugLogJSONFormatter)
+```
+
+### Custom Formatter
+
+See [DebugLog]({{% godoc v3 %}}DebugLog).
+
+```go
+// implement custom debug log formatter
+func DebugLogCustomFormatter(dl *DebugLog) string {
+    logContent := ""
+
+    // perform log manipulation logic here
+
+	return logContent
+}
+
+// set the custom debug log formatter
+c := resty.New().
+    SetDebugLogFormatter(DebugLogCustomFormatter)
+```
+
+## Methods
+
+### Client
+
+* [Client.SetDebug]({{% godoc v3 %}}Client.SetDebug)
+* [Client.EnableDebug]({{% godoc v3 %}}Client.EnableDebug)
+* [Client.DisableDebug]({{% godoc v3 %}}Client.DisableDebug)
+* [Client.SetDebugBodyLimit]({{% godoc v3 %}}Client.SetDebugBodyLimit)
+* [Client.OnDebugLog]({{% godoc v3 %}}Client.OnDebugLog)
+* [Client.SetDebugLogFormatter]({{% godoc v3 %}}Client.SetDebugLogFormatter)
+
+### Request
+
+* [Request.SetDebug]({{% godoc v3 %}}Request.SetDebug)
+* [Request.EnableDebug]({{% godoc v3 %}}Request.EnableDebug)
+* [Request.DisableDebug]({{% godoc v3 %}}Request.DisableDebug)

content/docs/example/how-to-do-dry-run.md

@@ -0,0 +1,30 @@
+---
+title: How to do Dry-Run?
+---
+
+# How to do Dry-Run?
+
+The appropriate way to do Dry-Run implementation with Resty is to implement custom transport using the `http.RoundTripper` interface.
+
+With custom transport, the user could perform any use case handling for Dry-Run.
+
+```go
+type DryRunTransport struct {
+    http.RoundTripper
+}
+
+func (dr *DryRunTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+    // implement Dry-Run logic here ...
+
+    return resp, err
+}
+
+c := resty.New().
+    SetTransport(&DryRunTransport{
+        // initialize dry-run fields
+    })
+
+defer c.Close()
+
+// start using the Resty client with dry-run ...
+```

content/docs/example/tls-client-config-on-custom-roundtriper.md

@@ -9,28 +9,28 @@ Resty v3 provides the [TLSClientConfiger]({{% godoc v3 %}}TLSClientConfiger) int
 ## Implement `TLSClientConfiger` interface
 
 ```go
- type CustomTransport struct {
-    http.RoundTripper
-    resty.TLSClientConfiger
- }
+type CustomTransport struct {
+   http.RoundTripper
+   resty.TLSClientConfiger
+}
 
- func (t *CustomTransport) RoundTrip(r *http.Request) (*http.Response, error) {
-    // custom round trip implementation here ...
+func (t *CustomTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+   // custom round trip implementation here ...
 
- 	return resp, err
- }
+   return resp, err
+}
 
- func (t *CustomTransport) TLSClientConfig() *tls.Config {
-    // return TLS config instance
+func (t *CustomTransport) TLSClientConfig() *tls.Config {
+   // return TLS config instance
 
- 	return t.tlsConfig
- }
+   return t.tlsConfig
+}
 
- func (t *CustomTransport) SetTLSClientConfig(tlsConfig *tls.Config) error {
- 	// handle TLS client config here
+func (t *CustomTransport) SetTLSClientConfig(tlsConfig *tls.Config) error {
+   // handle TLS client config here
 
- 	return nil
- }
+   return nil
+}
 ```
 
 ## Assign it to the Resty client

content/docs/new-features-and-enhancements.md

@@ -28,6 +28,8 @@ bookHidden: true
     * Updates hash functions for `SHA-512-256` and `SHA-512-256-sess`.
 * Adds Request level [timeout]({{% relref "timeout" %}}) support.
 * Adds the ability to determine the filename automatically from the response for [saving the response]({{% relref "save-response" %}}).
+* [Debug Log]({{% relref "debug-log" %}})
+    * Introduced Debug Log formatter, out of the box human-readable and JSON formatter added.
 
 
 ## New ways to create Client
@@ -74,7 +76,8 @@ bookHidden: true
 * [Client.SetCertificateFromFile]({{% godoc v3 %}}Client.SetCertificateFromFile)
 * [Client.SetCertificateFromString]({{% godoc v3 %}}Client.SetCertificateFromString)
 * [Client.SetUnescapeQueryParams]({{% godoc v3 %}}Client.SetUnescapeQueryParams)
-
+* [Client.OnDebugLog]({{% godoc v3 %}}Client.OnDebugLog)
+* [Client.SetDebugLogFormatter]({{% godoc v3 %}}Client.SetDebugLogFormatter)
 
 ## Request
 
@@ -111,6 +114,7 @@ bookHidden: true
 * [Request.SetUnescapeQueryParams]({{% godoc v3 %}}Request.SetUnescapeQueryParams)
 * [Request.Funcs]({{% godoc v3 %}}Request.Funcs)
 * [Request.SetTimeout]({{% godoc v3 %}}Request.SetTimeout)
+* [Request.SetHeaderAuthorizationKey]({{% godoc v3 %}}Request.SetHeaderAuthorizationKey)
 
 ## Response
 
@@ -122,4 +126,5 @@ bookHidden: true
 
 ## TraceInfo
 
-* [TraceInfo.String]({{% godoc v3 %}}TraceInfo.String)
+* [TraceInfo.String]({{% godoc v3 %}}TraceInfo.String)
+* [TraceInfo.JSON]({{% godoc v3 %}}TraceInfo.JSON)

content/docs/server-sent-events.md

@@ -1,7 +1,7 @@
 
 # Server-Sent Events
 
-Resty v3 adds Server-Sent Events feature. It provides APIs similar to the specification and is easy to use.
+Resty v3 adds Server-Sent Events feature. It provides APIs similar to the [specification](https://html.spec.whatwg.org/multipage/server-sent-events.html) and is easy to use.
 
 ## Examples
 

content/docs/upgrading-to-v3.md

@@ -6,6 +6,10 @@ bookHidden: true
 
 Resty v3 release brings many new features, enhancements, and breaking changes. This page outlines upgrading Resty to v3.
 
+{{% hint info %}}
+Minimum required go version is `{{% param Resty.V3.GoMinVersion %}}`
+{{% /hint %}}
+
 ## Update go.mod
 
 Resty v3 provides a Go vanity URL.
@@ -69,8 +73,6 @@ I made necessary breaking changes to improve Resty and open up future growth pos
 * `Client.AddRetryCondition` => [Client.AddRetryConditions]({{% godoc v3 %}}Client.AddRetryConditions)
 * `Client.AddRetryHook` => [Client.AddRetryHooks]({{% godoc v3 %}}Client.AddRetryHooks)
 * `Client.SetRetryAfter` => [Client.SetRetryStrategy]({{% godoc v3 %}}Client.SetRetryStrategy)
-* `Client.OnRequestLog` => [Client.OnRequestDebugLog]({{% godoc v3 %}}Client.OnRequestDebugLog)
-* `Client.OnResponseLog` => [Client.OnResponseDebugLog]({{% godoc v3 %}}Client.OnResponseDebugLog)
 * `Client.Transport` => [Client.HTTPTransport]({{% godoc v3 %}}Client.HTTPTransport) new method returns `http.Transport`
     * [Client.Transport]({{% godoc v3 %}}Client.Transport) method does exist in v3, which returns `http.RoundTripper`
 * `Client.OnBeforeRequest` => [Client.AddRequestMiddleware]({{% godoc v3 %}}Client.AddRequestMiddleware)
@@ -89,18 +91,23 @@ I made necessary breaking changes to improve Resty and open up future growth pos
 * `Request.GenerateCurlCommand` => [Request.CurlCmd]({{% godoc v3 %}}Request.CurlCmd)
 * `Request.AddRetryCondition` => [Request.AddRetryConditions]({{% godoc v3 %}}Request.AddRetryConditions)
 
+#### Response
+
+* `Response.Time` => [Response.Duration]({{% godoc v3 %}}Response.Duration)
+
 #### Multipart
 
 * `MultipartField.Param` => [MultipartField.Name]({{% godoc v3 %}}MultipartField)
 
+#### TraceInfo
+
+* `TraceInfo.RemoteAddr` => `net.Addr` to `string`
+
 #### Package Level
 
 * Retry
     * `OnRetryFunc` => [RetryHookFunc]({{% godoc v3 %}}RetryHookFunc)
     * `RetryStrategyFunc` => [RetryStrategyFunc]({{% godoc v3 %}}RetryStrategyFunc)
-* Debug Log
-    * `RequestLogCallback` and `ResponseLogCallback` => [DebugLogCallback]({{% godoc v3 %}}DebugLogCallback)
-
 
 ### Removed
 
@@ -112,9 +119,12 @@ I made necessary breaking changes to improve Resty and open up future growth pos
 * `Client.UserInfo`
 * `Client.SetRetryResetReaders` - it happens automatically.
 * `Client.SetRetryAfter` - use [Client.SetRetryStrategy]({{% godoc v3 %}}Client.SetRetryStrategy) or [Request.SetRetryStrategy]({{% godoc v3 %}}Request.SetRetryStrategy) instead.
-* `Client.RateLimiter` and `Client.SetRateLimiter` - Retry respects header `Retry-After` if present
+* `Client.RateLimiter` and `Client.SetRateLimiter` - Retry respects header `Retry-After` if present.
 * `Client.AddRetryAfterErrorCondition` - use [Client.AddRetryConditions]({{% godoc v3 %}}Client.AddRetryConditions) instead.
 * `Client.SetPreRequestHook` - use [Client.SetRequestMiddlewares]({{% godoc v3 %}}Client.SetRequestMiddlewares) instead. Refer to [docs]({{% relref "request-middleware" %}}).
+* `Client.OnRequestLog` => use [Client.OnDebugLog]({{% godoc v3 %}}Client.OnDebugLog) instead.
+* `Client.OnResponseLog` => use [Client.OnDebugLog]({{% godoc v3 %}}Client.OnDebugLog) instead.
+
 
 #### Request
 
@@ -138,6 +148,7 @@ I made necessary breaking changes to improve Resty and open up future growth pos
 * `SRVRecord` - in favor of new [Load Balancer feature]({{% relref "load-balancer-and-service-discovery" %}}) that supports SRV record lookup.
 * `File` - in favor of enhanced [MultipartField]({{% godoc v3 %}}MultipartField) feature.
 * `RequestLog`, `ResponseLog` => use [DebugLog]({{% godoc v3 %}}DebugLog) instead.
+* `RequestLogCallback` and `ResponseLogCallback` => use [DebugLogCallbackFunc]({{% godoc v3 %}}DebugLogCallbackFunc) instead
 
 ##### Methods
 

content/timeline.md

@@ -11,7 +11,7 @@ bookHidden: true
 | [v1.0.0]({{% restyrelease v1.0.0 %}}) | Sep 25, 2017 | First major release |
 | [v1.12.0]({{% restyrelease v1.12.0 %}}) | Feb 27, 2019 | Final release of v1 series |
 | [v2.0.0]({{% restyrelease v2.0.0 %}}) | Jul 16, 2019 | Second major release |
-| [v2.16.2]({{% restyrelease v2.16.2 %}}) | Nov 21, 2024 | Final (guessing) release of v2 series |
+| [v2.16.5]({{% restyrelease v2.16.2 %}}) | Jan 22, 2025 | Final (guessing) release of v2 series |
 | v3.0.0 | TBD | Third major release |
 
 Currently v3 is in [{{% param Resty.V3.Version %}}](https://github.com/go-resty/resty/releases/tag/{{% param Resty.V3.Version %}})

hugo.yaml

@@ -49,7 +49,8 @@ params:
     GitHubRepo: https://github.com/go-resty/resty
     GitHubSlug: go-resty/resty
     V3:
-      Version: v3.0.0-alpha.9
+      Version: v3.0.0-beta.1
+      GoMinVersion: go1.21
       Vanity: resty.dev/v3
       GoDocLinkPrefix: https://pkg.go.dev/resty.dev/v3#
 

layouts/partials/docs/inject/content-before.html

@@ -1,3 +1,3 @@
 <div class="global-msg global-msg-warning" align="center">
-    <p><strong>NOTE: Currently, Resty v3 is in alpha release, and documentation is in-progress ...</strong></p>
+    <p><strong>NOTE: Currently, Resty v3 is in beta release</strong></p>
 </div>