refactor: initial v3.0.0 implementation

Author: CodingAleCR

.gitignore

@@ -6,7 +6,6 @@
 
 build/
 
-
 .atom/
 .idea
 .vscode
@@ -21,4 +20,7 @@ coverage/
 *.log
 flutter_export_environment.sh
 !packages/**/example/ios/
-!packages/**/example/android/
+!packages/**/example/android/
+
+# FVM Version Cache
+.fvm/

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 3.0.0
+
+- **Breaking**: Rebuild from scratch. Not backwards compatible with 2.x.
+- **Added**: `HttpInterceptor` interface (replaces `InterceptorContract`). Same four methods with `FutureOr` support.
+- **Added**: `InterceptedClient.build(...)` and `InterceptedHttp.build(...)` with `interceptors`, `client`, `retryPolicy`, `requestTimeout`, `onRequestTimeout`.
+- **Added**: Optional `params` and `paramsAll` on `get`, `post`, `put`, `patch`, `delete`, `head`; merged into URL query.
+- **Added**: `String.toUri()` extension. `Uri.addQueryParams(params: ..., paramsAll: ...)` extension.
+- **Added**: Conditional export `http_interceptor_io.dart` for `IOClient` (VM/mobile/desktop; do not use on web).
+- **Removed**: `RequestData`/`ResponseData`. Use `BaseRequest`/`BaseResponse` only; no `copyWith` in core.
+- **Removed**: Dependencies `qs_dart` and `validators` (not used in v3).
+
 ## 2.0.0
 
 * feat: Simplify configuration of delay between retries by @jonasschaude in <https://github.com/CodingAleCR/http_interceptor/pull/122>

README.md

@@ -18,7 +18,7 @@ This is a plugin that lets you intercept the different requests and responses fr
 
 ## Quick Reference
 
-**Already using `http_interceptor`? Check out the [1.0.0 migration guide](./guides/migration_guide_1.0.0.md) for quick reference on the changes made and how to migrate your code.**
+**Upgrading from 2.x? See the [3.0.0 migration guide](./guides/migration_guide_3.0.0.md).**
 
 - [http\_interceptor](#http_interceptor)
   - [Quick Reference](#quick-reference)
@@ -51,7 +51,7 @@ http_interceptor: <latest>
 - 🚦 Intercept & change unstreamed requests and responses.
 - ✨ Retrying requests when an error occurs or when the response does not match the desired (useful for handling custom error responses).
 - 👓 `GET` requests with separated parameters.
-- ⚡️ Standard `bodyBytes` on `ResponseData` to encode or decode in the desired format.
+- ⚡️ Standard `Response.bodyBytes` for encoding or decoding as needed.
 - 🙌🏼 Array parameters on requests.
 - 🖋 Supports self-signed certificates (except on Flutter Web).
 - 🍦 Compatible with vanilla Dart projects or Flutter projects.
@@ -67,114 +67,57 @@ import 'package:http_interceptor/http_interceptor.dart';
 
 ### Building your own interceptor
 
-In order to implement `http_interceptor` you need to implement the `InterceptorContract` and create your own interceptor. This abstract class has four methods:
+Implement `HttpInterceptor` to add logging, headers, error handling, and more. The interface has four methods:
 
- - `interceptRequest`, which triggers before the http request is called 
- - `interceptResponse`, which triggers after the request is called, it has a response attached to it which the corresponding to said request;
- 
-- `shouldInterceptRequest` and `shouldInterceptResponse`, which are used to determine if the request or response should be intercepted or not. These two methods are optional as they return `true` by default, but they can be useful if you want to conditionally intercept requests or responses based on certain criteria. 
+- **interceptRequest** – runs before the request is sent. Return the (possibly modified) request.
+- **interceptResponse** – runs after the response is received. Return the (possibly modified) response.
+- **shouldInterceptRequest** / **shouldInterceptResponse** – return `false` to skip interception for that request/response (default `true`).
 
-You could use this package to do logging, adding headers, error handling, or many other cool stuff. It is important to note that after you proccess the request/response objects you need to return them so that `http` can continue the execute.
+All methods support `FutureOr` so you can use sync or async. Modify the request/response in place and return it, or return a new instance.
 
-All four methods use `FutureOr` syntax, which makes it easier to support both synchronous and asynchronous behaviors.
-
-- Logging with interceptor:
+- Logging interceptor:
 
 ```dart
-class LoggerInterceptor extends InterceptorContract {
+class LoggerInterceptor implements HttpInterceptor {
   @override
-  BaseRequest interceptRequest({
-    required BaseRequest request,
-  }) {
+  BaseRequest interceptRequest({required BaseRequest request}) {
     print('----- Request -----');
     print(request.toString());
-    print(request.headers.toString());
     return request;
   }
 
   @override
-  BaseResponse interceptResponse({
-    required BaseResponse response,
-  }) {
-    log('----- Response -----');
-    log('Code: ${response.statusCode}');
+  BaseResponse interceptResponse({required BaseResponse response}) {
+    print('----- Response -----');
+    print('Code: ${response.statusCode}');
     if (response is Response) {
-      log((response).body);
+      print(response.body);
     }
     return response;
   }
 }
 ```
 
-- Changing headers with interceptor:
-
-```dart
-class WeatherApiInterceptor implements InterceptorContract {
-  @override
-  FutureOr<BaseRequest> interceptRequest({required BaseRequest request}) async {
-    try {
-      request.url.queryParameters['appid'] = OPEN_WEATHER_API_KEY;
-      request.url.queryParameters['units'] = 'metric';
-      request.headers[HttpHeaders.contentTypeHeader] = "application/json";
-    } catch (e) {
-      print(e);
-    }
-    return request;
-  }
-
-  @override
-  BaseResponse interceptResponse({
-  required BaseResponse response,
-  }) =>
-      response;
-  
-  @override
-  FutureOr<bool> shouldInterceptRequest({required BaseRequest request}) async {
-    // You can conditionally intercept requests here
-    return true; // Intercept all requests
-  }
-
-  @override
-  FutureOr<bool> shouldInterceptResponse({required BaseResponse response}) async {
-    // You can conditionally intercept responses here
-    return true; // Intercept all responses
-  }
-}
-```
-
-- You can also react to and modify specific types of requests and responses, such as `StreamedRequest`,`StreamedResponse`, or `MultipartRequest` :
+- Adding headers / query params (in-place mutation):
 
 ```dart
-class MultipartRequestInterceptor implements InterceptorContract {
-  @override
-  FutureOr<BaseRequest> interceptRequest({required BaseRequest request}) async {
-    if(request is MultipartRequest){
-      request.fields['app_version'] = await PackageInfo.fromPlatform().version;
-    }
-    return request;
-  }
-
-  @override
-  FutureOr<BaseResponse> interceptResponse({required BaseResponse response}) async {
-    if(response is StreamedResponse){
-      response.stream.asBroadcastStream().listen((data){
-        print(data);
-      });
-    }
-    return response;
-  }
-
+class WeatherApiInterceptor implements HttpInterceptor {
   @override
-  FutureOr<bool> shouldInterceptRequest({required BaseRequest request}) async {
-    // You can conditionally intercept requests here
-    return true; // Intercept all requests
+  BaseRequest interceptRequest({required BaseRequest request}) {
+    final url = request.url.replace(
+      queryParameters: {
+        ...request.url.queryParameters,
+        'appid': apiKey,
+        'units': 'metric',
+      },
+    );
+    return Request(request.method, url)
+      ..headers.addAll(request.headers)
+      ..headers[HttpHeaders.contentTypeHeader] = 'application/json';
   }
 
   @override
-  FutureOr<bool> shouldInterceptResponse({required BaseResponse response}) async {
-    // You can conditionally intercept responses here
-    return true; // Intercept all responses
-  }
+  BaseResponse interceptResponse({required BaseResponse response}) => response;
 }
 ```
 
@@ -190,15 +133,17 @@ Here is an example with a repository using the `InterceptedClient` class.
 
 ```dart
 class WeatherRepository {
-  Client client = InterceptedClient.build(interceptors: [
-      WeatherApiInterceptor(),
-  ]);
+  final client = InterceptedClient.build(
+    interceptors: [WeatherApiInterceptor()],
+  );
 
   Future<Map<String, dynamic>> fetchCityWeather(int id) async {
     var parsedWeather;
     try {
-      final response =
-          await client.get("$baseUrl/weather".toUri(), params: {'id': "$id"});
+      final response = await client.get(
+        '$baseUrl/weather'.toUri(),
+        params: {'id': '$id'},
+      );
       if (response.statusCode == 200) {
         parsedWeather = json.decode(response.body);
       } else {
@@ -225,11 +170,13 @@ class WeatherRepository {
     Future<Map<String, dynamic>> fetchCityWeather(int id) async {
     var parsedWeather;
     try {
-      final http = InterceptedHttp.build(interceptors: [
-          WeatherApiInterceptor(),
-      ]);
-      final response =
-          await http.get("$baseUrl/weather".toUri(), params: {'id': "$id"});
+      final http = InterceptedHttp.build(
+        interceptors: [WeatherApiInterceptor()],
+      );
+      final response = await http.get(
+        '$baseUrl/weather'.toUri(),
+        params: {'id': '$id'},
+      );
       if (response.statusCode == 200) {
         parsedWeather = json.decode(response.body);
       } else {

docs/decisions/000-template.md

@@ -0,0 +1,18 @@
+# Title
+
+Date: YYYY-MM-DD
+
+Status: proposed | rejected | accepted | deprecated | … | superseded by
+[0005](0005-example.md)
+
+## Context
+
+<!-- Explain the overall context of the decision, the problem it attempts to solve, examples of why it might need solving. You can even add possible solutions -->
+
+## Decision
+
+<!-- Explain the decision that was taken. Why it was taken -->
+
+## Consequences
+
+<!-- Describe the consequences of this decision, deprecations, new features, removed code, etc. -->

docs/decisions/001-v3-rebuild.md

@@ -0,0 +1,34 @@
+# V3 from-scratch rebuild
+
+Date: 2025-03-15
+
+Status: accepted
+
+## Context
+
+The library was initally a rewrite of [http_middleware](https://pub.dev/packages/http_middleware). It has reached 2.0.0 with a full feature set (interceptors, retry, timeout, copyWith on requests/responses, query params, etc.). However, the existing implementation had accumulated complexity and made a clean evolution difficult. A from-scratch rebuild was chosen to:
+
+- Apply the principles, design patterns, and best practices.
+- Avoid inheriting code smells and anti-patterns from the previous implementation.
+- Prioritize a small API surface and clear behavior over backwards compatibility with 2.x.
+
+The 2.0.0 API was used as a feature and API reference only; no backwards compatibility with 2.x is required.
+
+## Decision
+
+Rebuild the library as version 3 with the following decisions:
+
+- **Decorator pattern**: The intercepted client wraps a `Client`, implements `Client`, and delegates to the inner client while adding interception. New behavior is added by composition (interceptors, retry, timeout), not by one large class.
+- **Strategy pattern**: Interceptors define how to transform request/response; `RetryPolicy` defines when to retry and with what delay. Both are injectable strategies.
+- **No copyWith in core**: Interceptors receive and return `BaseRequest`/`BaseResponse` from `package:http`. The supported pattern is in-place mutation or returning the same instance. Cloning (copyWith) was not added to the core API to keep the library simple; it can be a code smell (many clone surfaces). Importantly, `StreamedRequest` and `StreamedResponse` carry streams, which can be consumed only once—you cannot meaningfully “copy” a stream. A copyWith for those types would therefore be either limited (e.g. only URL and headers) or error-prone (e.g. reusing or re-wrapping the same stream). That constraint makes a uniform copyWith story across all request/response types fragile and reinforces the decision to avoid it in core.
+- **Small composable units**: Interceptor chain runner, retry executor, and timeout wrapper are separate, testable units. The client’s `send()` orchestrates them in a clear order: request interceptors → (optional) timeout → send → response interceptors; retry re-runs from request interceptors when the policy allows.
+- **InterceptedClient and InterceptedHttp**: `InterceptedClient` extends `BaseClient` and overrides `send()`; `InterceptedHttp` is a facade that holds an `InterceptedClient` and exposes `get`, `post`, etc., plus optional `close()`.
+- **Single interceptor and retry abstractions**: One `HttpInterceptor` interface and one `RetryPolicy` interface; avoid overlapping or redundant abstractions (YAGNI).
+
+## Consequences
+
+- **Removed**: Backwards compatibility with 2.x; `RequestData`/`ResponseData`; copyWith in the core API; any structure or naming copied from the deleted implementation.
+- **Added**: Clean implementation under `lib/src/` with interceptors, chain, retry, timeout, and client/facade; alignment with Decorator/Strategy and SOLID; guard clauses and linear control flow where possible.
+- **Preserved (conceptually)**: Interceptor contract (intercept request/response, shouldIntercept flags), retry policy (on exception and on response, configurable delay), request timeout and callback, query params (`params`/`paramsAll`) on convenience methods, Uri and String extensions where they fit the minimal API.
+- **Documentation**: Migration guide (e.g. [migration_guide_3.0.0.md](../../guides/migration_guide_3.0.0.md)) explains the break from 2.x and how to migrate (e.g. work with `BaseRequest`/`BaseResponse`, no copyWith).
+

example/devtools_options.yaml

@@ -0,0 +1,3 @@
+description: This file stores settings for Dart & Flutter DevTools.
+documentation: https://docs.flutter.dev/tools/devtools/extensions#configure-extension-enablement-states
+extensions:

example/ios/Flutter/AppFrameworkInfo.plist

@@ -20,7 +20,5 @@
   <string>????</string>
   <key>CFBundleVersion</key>
   <string>1.0</string>
-  <key>MinimumOSVersion</key>
-  <string>12.0</string>
 </dict>
 </plist>

example/ios/Podfile

@@ -1,5 +1,5 @@
 # Uncomment this line to define a global platform for your project
-# platform :ios, '12.0'
+# platform :ios, '13.0'
 
 # CocoaPods analytics sends network stats synchronously affecting flutter build latency.
 ENV['COCOAPODS_DISABLE_STATS'] = 'true'

example/ios/Podfile.lock

@@ -20,10 +20,10 @@ EXTERNAL SOURCES:
     :path: ".symlinks/plugins/shared_preferences_foundation/darwin"
 
 SPEC CHECKSUMS:
-  Flutter: e0871f40cf51350855a761d2e70bf5af5b9b5de7
-  image_picker_ios: 4a8aadfbb6dc30ad5141a2ce3832af9214a705b5
-  shared_preferences_foundation: fcdcbc04712aee1108ac7fda236f363274528f78
+  Flutter: cabc95a1d2626b1b06e7179b784ebcf0c0cde467
+  image_picker_ios: 4f2f91b01abdb52842a8e277617df877e40f905b
+  shared_preferences_foundation: 5086985c1d43c5ba4d5e69a4e8083a389e2909e6
 
-PODFILE CHECKSUM: c4c93c5f6502fe2754f48404d3594bf779584011
+PODFILE CHECKSUM: 0dbd5a87e0ace00c9610d2037ac22083a01f861d
 
 COCOAPODS: 1.15.2

example/ios/Runner.xcodeproj/project.pbxproj

@@ -343,7 +343,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;
@@ -421,7 +421,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
@@ -470,7 +470,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 12.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = iphoneos;
 				SUPPORTED_PLATFORMS = iphoneos;