Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/codingalecr/http_interceptor
A lightweight, simple plugin that allows you to intercept request and response objects and modify them if desired.
https://github.com/codingalecr/http_interceptor
dart dart-library flutter http http-interceptor http-requests intercept-calls interceptors open-source plugin retrying-requests
Last synced: 1 day ago
JSON representation
A lightweight, simple plugin that allows you to intercept request and response objects and modify them if desired.
- Host: GitHub
- URL: https://github.com/codingalecr/http_interceptor
- Owner: CodingAleCR
- License: mit
- Created: 2019-04-09T21:36:03.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-17T17:58:48.000Z (17 days ago)
- Last Synced: 2025-01-02T01:08:37.271Z (1 day ago)
- Topics: dart, dart-library, flutter, http, http-interceptor, http-requests, intercept-calls, interceptors, open-source, plugin, retrying-requests
- Language: Dart
- Homepage:
- Size: 357 KB
- Stars: 132
- Watchers: 6
- Forks: 68
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# http_interceptor
[](https://pub.dev/packages/http_interceptor)
[](https://github.com/tenhobi/effective_dart)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/gh/CodingAleCR/http_interceptor)
[](https://github.com/codingalecr/http_interceptor)
[](#contributors-)
This is a plugin that lets you intercept the different requests and responses from Dart's http package. You can use to add headers, modify query params, or print a log of the response.
## 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.**
- [http_interceptor](#http_interceptor)
- [Quick Reference](#quick-reference)
- [Installation](#installation)
- [Features](#features)
- [Usage](#usage)
- [Building your own interceptor](#building-your-own-interceptor)
- [Using your interceptor](#using-your-interceptor)
- [Using interceptors with Client](#using-interceptors-with-client)
- [Using interceptors without Client](#using-interceptors-without-client)
- [Retrying requests](#retrying-requests)
- [Using self signed certificates](#using-self-signed-certificates)
- [InterceptedClient](#interceptedclient)
- [InterceptedHttp](#interceptedhttp)
- [Roadmap](#roadmap)
- [Troubleshooting](#troubleshooting)
- [Contributions](#contributions)
- [Contributors](#contributors)
## Installation
Include the package with the latest version available in your `pubspec.yaml`.
```dart
http_interceptor:
```
## Features
- 🚦 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.
- 🙌🏼 Array parameters on requests.
- 🖋 Supports self-signed certificates (except on Flutter Web).
- 🍦 Compatible with vanilla Dart projects or Flutter projects.
- 🎉 Null-safety.
- ⏲ Timeout configuration with duration and timeout functions.
- ⏳ Configure the delay for each retry attempt.
## Usage
```dart
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 two methods: `interceptRequest`, which triggers before the http request is called; and `interceptResponse`, which triggers after the request is called, it has a response attached to it which the corresponding to said request. You could use this 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.
`interceptRequest` and `interceptResponse` use `FutureOr` syntax, which makes it easier to support both synchronous and asynchronous behaviors.
- Logging with interceptor:
```dart
class LoggerInterceptor extends InterceptorContract {
@override
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}');
if (response is Response) {
log((response).body);
}
return response;
}
}
```
- Changing headers with interceptor:
```dart
class WeatherApiInterceptor implements InterceptorContract {
@override
FutureOr 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;
}
```
- You can also react to and modify specific types of requests and responses, such as `StreamedRequest`,`StreamedResponse`, or `MultipartRequest` :
```dart
class MultipartRequestInterceptor implements InterceptorContract {
@override
FutureOr interceptRequest({required BaseRequest request}) async {
if(request is MultipartRequest){
request.fields['app_version'] = await PackageInfo.fromPlatform().version;
}
return request;
}
@override
FutureOr interceptResponse({required BaseResponse response}) async {
if(response is StreamedResponse){
response.stream.asBroadcastStream().listen((data){
print(data);
});
}
return response;
}
}
```
### Using your interceptor
Now that you actually have your interceptor implemented, now you need to use it. There are two general ways in which you can use them: by using the `InterceptedHttp` to do separate connections for different requests or using a `InterceptedClient` for keeping a connection alive while making the different `http` calls. The ideal place to use them is in the service/provider class or the repository class (if you are not using services or providers); if you don't know about the repository pattern you can just google it and you'll know what I'm talking about. 😉
#### Using interceptors with Client
Normally, this approach is taken because of its ability to be tested and mocked.
Here is an example with a repository using the `InterceptedClient` class.
```dart
class WeatherRepository {
Client client = InterceptedClient.build(interceptors: [
WeatherApiInterceptor(),
]);
Future> fetchCityWeather(int id) async {
var parsedWeather;
try {
final response =
await client.get("$baseUrl/weather".toUri(), params: {'id': "$id"});
if (response.statusCode == 200) {
parsedWeather = json.decode(response.body);
} else {
throw Exception("Error while fetching. \n ${response.body}");
}
} catch (e) {
print(e);
}
return parsedWeather;
}
}
```
#### Using interceptors without Client
This is mostly the straight forward approach for a one-and-only call that you might need intercepted.
Here is an example with a repository using the `InterceptedHttp` class.
```dart
class WeatherRepository {
Future> fetchCityWeather(int id) async {
var parsedWeather;
try {
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 {
return Future.error(
"Error while fetching.",
StackTrace.fromString("${response.body}"),
);
}
} on SocketException {
return Future.error('No Internet connection 😑');
} on FormatException {
return Future.error('Bad response format 👎');
} on Exception {
return Future.error('Unexpected error 😢');
}
return parsedWeather;
}
}
```
### Retrying requests
Sometimes you need to retry a request due to different circumstances, an expired token is a really good example. Here's how you could potentially implement an expired token retry policy with `http_interceptor`.
```dart
class ExpiredTokenRetryPolicy extends RetryPolicy {
@override
Future shouldAttemptRetryOnResponse(BaseResponse response) async {
if (response.statusCode == 401) {
// Perform your token refresh here.
return true;
}
return false;
}
}
```
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.
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
Duration delayRetryAttemptOnResponse({required int retryAttempt}) {
return const Duration(milliseconds: 250) * math.pow(2.0, retryAttempt);
}
}
```
### Using self signed certificates
You can achieve support for self-signed certificates by providing `InterceptedHttp` or `InterceptedClient` with the `client` parameter when using the `build` method on either of those, it should look something like this:
### InterceptedClient
```dart
Client client = InterceptedClient.build(
interceptors: [
WeatherApiInterceptor(),
],
client: IOClient(
HttpClient()
..badCertificateCallback = badCertificateCallback
..findProxy = findProxy,
);
);
```
### InterceptedHttp
```dart
final http = InterceptedHttp.build(
interceptors: [
WeatherApiInterceptor(),
],
client: IOClient(
HttpClient()
..badCertificateCallback = badCertificateCallback
..findProxy = findProxy,
);
);
```
_**Note:** It is important to know that since both HttpClient and IOClient are part of `dart:io` package, this will not be a feature that you can perform on Flutter Web (due to `BrowserClient` and browser limitations)._
## Roadmap
Check out our roadmap [here](https://doc.clickup.com/p/h/82gtq-119/f552a826792c049).
_We migrated our roadmap to better suit the needs for development since we use ClickUp as our task management tool._
## Troubleshooting
Open an issue and tell me, I will be happy to help you out as soon as I can.
## Contributions
Contributions are always welcomed and encouraged, we will always give you credit for your work on this section. If you are interested in maintaining the project on a regular basis drop me a line at [[email protected]](mailto:[email protected]).
### Contributors
Thanks to all the wonderful people contributing to improve this package. Check the [Emoji Key](https://github.com/kentcdodds/all-contributors#emoji-key) for reference on what means what!
Alejandro Ulate Fallas
💻 📖 ⚠️ 🤔 🚧
Konstantin Serov
🤔
Virus1908
🤔 💻 ⚠️
Wes Ehrlichman
🤔 💻 ⚠️
Jan Lübeck
🤔 💻 ⚠️
Lucas Alves
🤔 💻 ⚠️
István Juhos
🤔 💻 ⚠️
Scott Hyndman
🤔
Islam Akhrarov
🤔 ⚠️ 💻
Meysam
📖
Martijn
⚠️ 💻
MaciejZuk
🐛
Lukas Kurz
⚠️ 🤔 💻
Glenn Ruysschaert
💻 ⚠️
Erick
💻 ⚠️
javiermrz
💻
nihar
🤔
Ayush Yadav
🤔
Alex
💻