Document Timeout property behavior for RestClientOptions and RestRequest

docs/docs/advanced/configuration.md

@@ -172,7 +172,7 @@ RestSharp allows configuring `RestClient` using client options, as mentioned at
 | `RemoteCertificateValidationCallback`        | Custom function to validate the server certificate. Normally, it's used when the server uses a certificate that isn't trusted by default.                                                                                                                                                         |
 | `BaseHost`                                   | Value for the `Host` header sent with each request.                                                                                                                                                                                                                                               |
 | `CookieContainer`                            | Custom cookie container that will be shared among all calls made by the client. Normally not required as RestSharp handles cookies without using a client-level cookie container.                                                                                                                 |
-| `MaxTimeout`                                 | Client-level timeout in milliseconds. If the request timeout is also set, this value isn't used.                                                                                                                                                                                                  |
+| `Timeout`                                    | Client-level timeout as `TimeSpan`. Default is 100 seconds. See [Configuring Timeouts](#configuring-timeouts) for details on timeout behavior.                                                                                                                                                   |
 | `Encoding`                                   | Default request encoding. Override it only if you don't use UTF-8.                                                                                                                                                                                                                                |
 | `ThrowOnDeserializationError`                | Forces the client to throw if it fails to deserialize the response. Remember that not all deserialization issues forces the serializer to throw. Default is `false`, so the client will return a `RestResponse` with deserialization exception details. Only relevant for `Execute...` functions. |
 | `FailOnDeserializationError`                 | When set to `true`, if the client fails to deserialize the response, the response object will have status `Failed`, although the HTTP calls might have been successful. Default is `true`.                                                                                                        |
@@ -213,7 +213,7 @@ Client options apply to all requests made by the client. Sometimes, you want to
 | `Authenticator`              | Overrides the client-level authenticator.                                                                                                                                                                                                                                                                         |
 | `Files`                      | Collection of file parameters, read-only. Use `AddFile` for adding files to the request.                                                                                                                                                                                                                          |
 | `Method`                     | Request HTTP method, default is `GET`. Only needed when using `Execute` or `ExecuteAsync` as other functions like `ExecutePostAsync` will override the request method.                                                                                                                                            |
-| `TImeout`                    | Overrides the client-level timeout.                                                                                                                                                                                                                                                                               |
+| `Timeout`                    | Request-level timeout override. See [Configuring Timeouts](#configuring-timeouts) for details on timeout behavior.                                                                                                                                                                                |
 | `Resource`                   | Resource part of the remote endpoint URL. For example, when using the client-level base URL `https://localhost:5000/api` and `Resource` set to `weather`, the request will be sent to `https://localhost:5000/api/weather`. It can container resource placeholders to be used in combination with `AddUrlSegment` |
 | `RequestFormat`              | Identifies the request as JSON, XML, binary, or none. Rarely used because the client will set the request format based on the body type if functions like `AddJsonBody` or `AddXmlBody` are used.                                                                                                                 |
 | `RootElement`                | Used by the default deserializers to determine where to start deserializing from. Only supported for XML responses. Does not apply to requests.                                                                                                                                                                   |
@@ -228,3 +228,50 @@ Client options apply to all requests made by the client. Sometimes, you want to
 | `Interceptors`               | Allows adding interceptors to the request. Both client-level and request-level interceptors will be called.                                                                                                                                                                                                       |
 
 The table below contains all configuration properties of `RestRequest`. To learn more about adding request parameters, check the [usage page](../usage/request.md) page about creating requests with parameters.
+
+## Configuring Timeouts
+
+RestSharp provides flexible timeout configuration at both the client and request levels. The timeout determines how long RestSharp will wait for a response before canceling the request.
+
+:::note Migration from MaxTimeout
+In older versions of RestSharp, the `MaxTimeout` property (measured in milliseconds) was used. This has been replaced by the `Timeout` property, which uses `TimeSpan` for more intuitive and type-safe timeout configuration.
+:::
+
+### Timeout Resolution
+
+When making a request, RestSharp uses the following priority order to determine the timeout:
+1. `RestRequest.Timeout` (if set)
+2. `RestClientOptions.Timeout` (if set)
+3. Default timeout of 100 seconds
+
+### Timeout Values
+
+The `Timeout` property accepts a `TimeSpan?` value and supports the following behaviors:
+
+| Value | Behavior |
+|-------|----------|
+| `null` (not set) | Uses the next level timeout (client timeout, then default 100 seconds) |
+| Positive `TimeSpan` | Request times out after the specified duration (e.g., `TimeSpan.FromSeconds(30)`) |
+| `Timeout.InfiniteTimeSpan` or `TimeSpan.FromMilliseconds(-1)` | No timeout - request will wait indefinitely for a response |
+| `TimeSpan.Zero` | Request is canceled immediately (effectively no time allowed for the request) |
+| Other negative values | Throws `ArgumentOutOfRangeException` when the request is executed |
+
+### Examples
+
+```csharp
+// Client-level timeout of 30 seconds
+var options = new RestClientOptions("https://api.example.com") {
+    Timeout = TimeSpan.FromSeconds(30)
+};
+var client = new RestClient(options);
+
+// Request-level timeout override
+var request = new RestRequest("resource") {
+    Timeout = TimeSpan.FromSeconds(60) // This request gets 60 seconds
+};
+
+// Infinite timeout (no timeout)
+var longRunningRequest = new RestRequest("long-operation") {
+    Timeout = Timeout.InfiniteTimeSpan
+};
+```

src/RestSharp/Options/RestClientOptions.cs

@@ -183,8 +183,16 @@ public RestClientOptions(string baseUrl) : this(new Uri(Ensure.NotEmptyString(ba
     public CookieContainer? CookieContainer { get; set; }
 
     /// <summary>
-    /// Request duration. Used when the request timeout is not specified using <seealso cref="RestRequest.Timeout"/>,
-    /// </summary>
+    /// Request timeout duration. Used when the request timeout is not specified using <seealso cref="RestRequest.Timeout"/>.
+    /// If not set, the default timeout is 100 seconds.
+    /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    /// <item><description>Set to <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> (or <c>TimeSpan.FromMilliseconds(-1)</c>) for no timeout</description></item>
+    /// <item><description>Set to <see cref="TimeSpan.Zero"/> to cancel the request immediately</description></item>
+    /// <item><description>Negative values (other than -1 millisecond) will throw <see cref="ArgumentOutOfRangeException"/></description></item>
+    /// </list>
+    /// </remarks>
     public TimeSpan? Timeout { get; set; }
 
     /// <summary>

src/RestSharp/Request/RestRequest.cs

@@ -131,8 +131,16 @@ public RestRequest(Uri resource, Method method = Method.Get)
     public Method Method { get; set; }
 
     /// <summary>
-    /// Custom request timeout
+    /// Custom request timeout. Overrides <see cref="RestClientOptions.Timeout"/> if set.
+    /// If not set, uses the client-level timeout or the default of 100 seconds.
     /// </summary>
+    /// <remarks>
+    /// <list type="bullet">
+    /// <item><description>Set to <see cref="System.Threading.Timeout.InfiniteTimeSpan"/> (or <c>TimeSpan.FromMilliseconds(-1)</c>) for no timeout</description></item>
+    /// <item><description>Set to <see cref="TimeSpan.Zero"/> to cancel the request immediately</description></item>
+    /// <item><description>Negative values (other than -1 millisecond) will throw <see cref="ArgumentOutOfRangeException"/></description></item>
+    /// </list>
+    /// </remarks>
     public TimeSpan? Timeout { get; set; }
 
     /// <summary>