fix: improve retry policies, url parsing and documentation

Author: CodingAleCR

README.md

@@ -227,11 +227,25 @@ Sometimes you need to retry a request due to different circumstances, an expired
 
 ```dart
 class ExpiredTokenRetryPolicy extends RetryPolicy {
+  @override
+  int get maxRetryAttempts => 2;
+
+  @override
+  bool shouldAttemptRetryOnException(Exception reason, BaseRequest request) {
+    // Log the exception for debugging
+    print('Request failed: ${reason.toString()}');
+    print('Request URL: ${request.url}');
+    
+    // Retry on network exceptions, but not on client errors
+    return reason is SocketException || reason is TimeoutException;
+  }
+
   @override
   Future<bool> shouldAttemptRetryOnResponse(BaseResponse response) async {
     if (response.statusCode == 401) {
       // Perform your token refresh here.
-
+      print('Token expired, refreshing...');
+      
       return true;
     }
 
@@ -242,13 +256,56 @@ class ExpiredTokenRetryPolicy extends RetryPolicy {
 
 You can also set the maximum amount of retry attempts with `maxRetryAttempts` property or override the `shouldAttemptRetryOnException` if you want to retry the request after it failed with an exception.
 
+### RetryPolicy Interface
+
+The `RetryPolicy` abstract class provides the following methods that you can override:
+
+- **`shouldAttemptRetryOnException(Exception reason, BaseRequest request)`**: Called when an exception occurs during the request. Return `true` to retry, `false` to fail immediately.
+- **`shouldAttemptRetryOnResponse(BaseResponse response)`**: Called after receiving a response. Return `true` to retry, `false` to accept the response.
+- **`maxRetryAttempts`**: The maximum number of retry attempts (default: 1).
+- **`delayRetryAttemptOnException({required int retryAttempt})`**: Delay before retrying after an exception (default: no delay).
+- **`delayRetryAttemptOnResponse({required int retryAttempt})`**: Delay before retrying after a response (default: no delay).
+
+### Using Retry Policies
+
+To use a retry policy, pass it to the `InterceptedClient` or `InterceptedHttp`:
+
+```dart
+final client = InterceptedClient.build(
+  interceptors: [WeatherApiInterceptor()],
+  retryPolicy: ExpiredTokenRetryPolicy(),
+);
+```
+
 Sometimes it is helpful to have a cool-down phase between multiple requests. This delay could for example also differ between the first and the second retry attempt as shown in the following example.
 
 ```dart
 class ExpiredTokenRetryPolicy extends RetryPolicy {
+  @override
+  int get maxRetryAttempts => 3;
+
+  @override
+  bool shouldAttemptRetryOnException(Exception reason, BaseRequest request) {
+    // Only retry on network-related exceptions
+    return reason is SocketException || reason is TimeoutException;
+  }
+
+  @override
+  Future<bool> shouldAttemptRetryOnResponse(BaseResponse response) async {
+    // Retry on server errors (5xx) and authentication errors (401)
+    return response.statusCode >= 500 || response.statusCode == 401;
+  }
+
+  @override
+  Duration delayRetryAttemptOnException({required int retryAttempt}) {
+    // Exponential backoff for exceptions
+    return Duration(milliseconds: (250 * math.pow(2.0, retryAttempt - 1)).round());
+  }
+
   @override
   Duration delayRetryAttemptOnResponse({required int retryAttempt}) {
-    return const Duration(milliseconds: 250) * math.pow(2.0, retryAttempt);
+    // Exponential backoff for response-based retries
+    return Duration(milliseconds: (250 * math.pow(2.0, retryAttempt - 1)).round());
   }
 }
 ```

lib/models/retry_policy.dart

@@ -12,8 +12,9 @@ import 'package:http/http.dart';
 ///   int get maxRetryAttempts => 2;
 ///
 ///   @override
-///   bool shouldAttemptRetryOnException(Exception reason) {
+///   bool shouldAttemptRetryOnException(Exception reason, BaseRequest request) {
 ///     log(reason.toString());
+///     log("Request URL: ${request.url}");
 ///
 ///     return false;
 ///   }
@@ -36,20 +37,45 @@ import 'package:http/http.dart';
 abstract class RetryPolicy {
   /// Defines whether the request should be retried when an Exception occurs
   /// while making said request to the server.
+  ///
+  /// [reason] - The exception that occurred during the request
+  /// [request] - The original request that failed
+  /// 
+  /// Returns `true` if the request should be retried, `false` otherwise.
   FutureOr<bool> shouldAttemptRetryOnException(
           Exception reason, BaseRequest request) =>
       false;
 
   /// Defines whether the request should be retried after the request has
   /// received `response` from the server.
+  ///
+  /// [response] - The response received from the server
+  /// 
+  /// Returns `true` if the request should be retried, `false` otherwise.
+  /// Common use cases include retrying on 401 (Unauthorized) or 500 (Server Error).
   FutureOr<bool> shouldAttemptRetryOnResponse(BaseResponse response) => false;
 
   /// Number of maximum request attempts that can be retried.
+  /// 
+  /// Default is 1, meaning the original request plus 1 retry attempt.
+  /// Set to 0 to disable retries, or higher values for more retry attempts.
   int get maxRetryAttempts => 1;
 
+  /// Delay before retrying when an exception occurs.
+  ///
+  /// [retryAttempt] - The current retry attempt number (1-based)
+  /// 
+  /// Returns the delay duration. Default is no delay (Duration.zero).
+  /// Consider implementing exponential backoff for production use.
   Duration delayRetryAttemptOnException({required int retryAttempt}) =>
       Duration.zero;
 
+  /// Delay before retrying when a response indicates retry is needed.
+  ///
+  /// [retryAttempt] - The current retry attempt number (1-based)
+  /// 
+  /// Returns the delay duration. Default is no delay (Duration.zero).
+  /// Consider implementing exponential backoff for production use.
   Duration delayRetryAttemptOnResponse({required int retryAttempt}) =>
       Duration.zero;
 }

lib/utils/query_parameters.dart

@@ -9,9 +9,21 @@ String buildUrlString(String url, Map<String, dynamic>? parameters) {
   // Check if there are parameters to add.
   if (parameters.isNotEmpty) {
     // Validate URL structure to prevent injection
+    // First check if it looks like a valid HTTP/HTTPS URL
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+      throw ArgumentError('Invalid URL structure: $url - must be a valid HTTP/HTTPS URL');
+    }
+    
     try {
-      Uri.parse(url);
+      final uri = Uri.parse(url);
+      // Additional validation: ensure it has a host
+      if (uri.host.isEmpty) {
+        throw ArgumentError('Invalid URL structure: $url - must have a valid host');
+      }
     } catch (e) {
+      if (e is ArgumentError) {
+        rethrow;
+      }
       throw ArgumentError('Invalid URL structure: $url');
     }
 

test/utils/utils_test.dart

@@ -1,5 +1,5 @@
-import 'package:test/test.dart';
 import 'package:http_interceptor/utils/utils.dart';
+import 'package:test/test.dart';
 
 main() {
   group("buildUrlString", () {
@@ -73,5 +73,15 @@ main() {
       expect(() => buildUrlString(invalidUrl, parameters), 
              throwsA(isA<ArgumentError>()));
     });
+    
+    test("Validates URL structure and throws error for URLs without scheme", () {
+      // Arrange
+      String invalidUrl = "example.com/path"; // No scheme
+      Map<String, dynamic> parameters = {"key": "value"};
+
+      // Act & Assert
+      expect(() => buildUrlString(invalidUrl, parameters), 
+             throwsA(isA<ArgumentError>()));
+    });
   });
 }