feat(dart): add algolia_chopper_requester package

clients/algoliasearch-client-dart/packages/chopper_requester/.gitignore

@@ -0,0 +1,3 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/

clients/algoliasearch-client-dart/packages/chopper_requester/README.md

@@ -0,0 +1,143 @@
+<!-- centered logo -->
+<p align="center">
+ <a href="https://www.algolia.com">
+ <img alt="Algolia for Dart" src="https://raw.githubusercontent.com/algolia/algoliasearch-client-common/master/banners/dart.png" >
+ </a>
+</p>
+
+<!-- centered badges -->
+<p align="center">
+ <a href="https://pub.dartlang.org/packages/algolia_chopper_client"><img src="https://img.shields.io/pub/v/algolia_chopper_client.svg" alt="Latest version"></a>
+ <a href="https://pub.dev/packages/algolia_chopper_client/publisher"><img src="https://img.shields.io/pub/publisher/algolia_chopper_client.svg" alt="Publisher"></a>
+</p>
+
+<h3 align="center">
+ <strong>Algolia API Chopper Requester</strong>
+</h3>
+
+<p align="center">
+ Use the Chopper Requester to send requests to the Algolia API with the Algolia Search Client for Dart. This package provides a custom Requester for the Algolia Search Client, allowing users to send requests to the Algolia API using the Chopper HTTP client.
+</p>
+
+## 💡 Installation
+
+Add Chopper Requester as a dependency in your project directly from pub.dev:
+
+#### For Dart projects:
+
+```shell
+dart pub add algolia_chopper_requester
+```
+
+#### For Flutter projects:
+
+```shell
+flutter pub add algolia_chopper_requester
+```
+
+### Basic Usage
+
+```dart
+final String appId = 'latency';
+final String apiKey = '6be0576ff61c053d5f9a3225e2a90f76';
+
+final SearchClient _client = SearchClient(
+ appId: appId,
+ apiKey: apiKey,
+ options: ClientOptions(
+ requester: ChopperRequester(
+ appId: appId,
+ apiKey: apiKey,
+ )
+ ),
+);
+
+Future<SearchResponse> search(String query) => _client.searchIndex(
+ request: SearchForHits(
+ indexName: 'flutter',
+ query: query,
+ hitsPerPage: 5,
+ ),
+ );
+```
+
+You can configure the `ChopperRequester` with the following parameters:
+
+### Configuration
+
+```dart
+final requester = ChopperRequester({
+ /// Your Algolia Application ID
+ required String appId,
+ /// Your Algolia Search-Only API Key
+ required String apiKey,
+ /// Additional headers to send with the request
+ Map<String, dynamic>? headers,
+ /// The segments to include in the `User-Agent` header
+ Iterable<AgentSegment>? clientSegments,
+ /// The logger to use for debugging
+ Logger? logger,
+ /// The Chopper Interceptors to use for modifying the request
+ Iterable<Interceptor>? interceptors,
+ /// The HTTP client to use for sending requests
+ Client? client,
+ /// A custom JSON converter to use for serializing and deserializing JSON
+ JsonConverter? converter,
+});
+```
+
+### Advanced Usage
+
+To set the connect timeout one has to do that directly on the `Client`, i.e.
+
+```dart
+final requester = ChopperRequester(
+ appId: appId,
+ apiKey: apiKey,
+ client: http.IOClient(
+ HttpClient()..connectionTimeout = const Duration(seconds: 60),
+ ),
+);
+```
+
+#### Custom Interceptors
+
+For interceptors please see the [Chopper documentation](https://hadrien-lejard.gitbook.io/chopper/interceptors).
+
+#### Custom Clients
+
+Via the `client` option users can use platform specific HTTP clients such:
+- [cronet_http](https://pub.dev/packages/cronet_http) on Android
+ ```dart
+ final requester = ChopperRequester(
+ appId: appId,
+ apiKey: apiKey,
+ client: CronetClient.fromCronetEngine(
+ CronetEngine.build(
+ cacheMode: CacheMode.memory,
+ cacheMaxSize: 50 * 1024 * 1024,
+ ),
+ closeEngine: true,
+ ),
+ );
+ ```
+- [cupertino_http](https://pub.dev/packages/cupertino_http) on iOS/macOS
+ ```dart
+ final requester = ChopperRequester(
+ appId: appId,
+ apiKey: apiKey,
+ client: CupertinoClient.fromSessionConfiguration(
+ (URLSessionConfiguration.defaultSessionConfiguration()
+ ..timeoutIntervalForRequest = const Duration(seconds: 30)),
+ ),
+ );
+ ```
+
+#### Parsing JSON in the background using Isolates
+
+Parsing JSON in the background is a good idea if you don't want to block the main thread.
+Please see the [Chopper documentation](https://hadrien-lejard.gitbook.io/chopper/faq#decoding-json-using-isolates) on Decoding JSON using Isolate worker pools.
+
+## License
+
+Chopper Requester for Algolia Search Client is an open-sourced software licensed under the [MIT license](LICENSE).

clients/algoliasearch-client-dart/packages/chopper_requester/example/example.dart

@@ -0,0 +1,55 @@
+import 'dart:io' show HttpClient;
+
+import 'package:algolia_chopper_requester/algolia_chopper_requester.dart';
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:http/http.dart' as http show Client;
+import 'package:http/io_client.dart' show IOClient;
+
+void main() async {
+ const String appId = 'latency';
+ const String apiKey = '6be0576ff61c053d5f9a3225e2a90f76';
+
+ // Create a custom http [Client] with a connection timeout of 30 seconds
+ final http.Client client = IOClient(
+ HttpClient()..connectionTimeout = const Duration(seconds: 30),
+ );
+
+ // Creating an instance of the RetryStrategy with necessary parameters.
+ // This will retry the failed requests with a backoff strategy.
+ final RetryStrategy requester = RetryStrategy.create(
+ segment: AgentSegment(value: 'CustomClient'),
+ appId: appId,
+ apiKey: apiKey,
+ defaultHosts: () => [
+ Host(url: 'latency-dsn.algolia.net'),
+ Host(url: 'latency-1.algolianet.com'),
+ ],
+ options: ClientOptions(
+ requester: ChopperRequester(
+ appId: appId,
+ apiKey: apiKey,
+ // Optionally, pass a custom http [Client] to the ChopperRequester.
+ // NOTE: The [Client] must be manually disposed of after use.
+ client: client,
+ ),
+ ),
+ );
+
+ // Executing a GET request on the '/1/indexes/instant_search' endpoint.
+ final Map<String, dynamic> response = await requester.execute(
+ request: ApiRequest(
+ method: RequestMethod.get,
+ path: '/1/indexes/instant_search',
+ queryParams: {'query': 'a', 'hitsPerPage': '5'},
+ ),
+ );
+
+ // Printing json response.
+ print(response);
+
+ // Dispose of the requester to clean up its resources.
+ requester.dispose();
+
+ // Disposing a custom [Client] has to be done manually.
+ client.close();
+}

clients/algoliasearch-client-dart/packages/chopper_requester/lib/algolia_chopper_requester.dart

@@ -0,0 +1,4 @@
+library algolia_chopper_requester;
+
+export 'package:chopper/chopper.dart' show Interceptor;
+export 'src/chopper_requester.dart';

clients/algoliasearch-client-dart/packages/chopper_requester/lib/src/agent_interceptor.dart

@@ -0,0 +1,21 @@
+import 'dart:async' show FutureOr;
+
+import 'package:algolia_client_core/algolia_client_core.dart' show AlgoliaAgent;
+import 'package:chopper/chopper.dart';
+import 'package:algolia_chopper_requester/src/platform/platform.dart';
+
+/// Interceptor that attaches the Algolia agent to outgoing requests.
+///
+/// This interceptor modifies the query parameters of each request to include the
+/// formatted representation of the Algolia agent.
+class AgentInterceptor implements Interceptor {
+ /// The Algolia agent to be attached to outgoing requests.
+ final AlgoliaAgent agent;
+
+ /// Constructs an [AgentInterceptor] with the provided Algolia agent.
+ const AgentInterceptor({required this.agent});
+
+ @override
+ FutureOr<Response<BodyType>> intercept<BodyType>(Chain<BodyType> chain) =>
+ chain.proceed(Platform.algoliaAgent<BodyType>(chain, agent.formatted()));
+}

clients/algoliasearch-client-dart/packages/chopper_requester/lib/src/auth_interceptor.dart

@@ -0,0 +1,33 @@
+import 'dart:async' show FutureOr;
+
+import 'package:chopper/chopper.dart';
+
+/// Interceptor that attaches the application id and API key to outgoing requests.
+///
+/// This interceptor modifies the headers of each request to include the
+/// application id and API key for Algolia authentication.
+class AuthInterceptor implements Interceptor {
+ /// The application id used for Algolia authentication.
+ final String appId;
+
+ /// The API key used for Algolia authentication.
+ final String _apiKey;
+
+ /// Constructs an [AuthInterceptor] with the provided application id and API key.
+ const AuthInterceptor({
+ required this.appId,
+ required String apiKey,
+ }) : _apiKey = apiKey;
+
+ @override
+ FutureOr<Response<BodyType>> intercept<BodyType>(Chain<BodyType> chain) =>
+ chain.proceed(
+ applyHeaders(
+ chain.request,
+ {
+ 'x-algolia-application-id': appId,
+ 'x-algolia-api-key': _apiKey,
+ },
+ ),
+ );
+}

clients/algoliasearch-client-dart/packages/chopper_requester/lib/src/chopper_requester.dart

@@ -0,0 +1,128 @@
+import 'dart:async' show TimeoutException;
+
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:chopper/chopper.dart';
+import 'package:algolia_chopper_requester/src/agent_interceptor.dart';
+import 'package:algolia_chopper_requester/src/auth_interceptor.dart';
+import 'package:algolia_chopper_requester/src/platform/platform.dart';
+import 'package:algolia_chopper_requester/src/version.dart';
+import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart' show Logger;
+
+/// A [Requester] implementation using the Chopper library.
+///
+/// This class sends HTTP requests using the Chopper library and handles
+/// response conversion and error handling.
+class ChopperRequester implements Requester {
+ /// The underlying Chopper client.
+ AuthInterceptor _authInterceptor;
+ late final ChopperClient _client;
+
+ /// Constructs a [ChopperClient] with the given [appId] and [apiKey].
+ ChopperRequester({
+ required String appId,
+ required String apiKey,
+ Map<String, dynamic>? headers,
+ Iterable<AgentSegment>? clientSegments,
+ Logger? logger,
+ Iterable<Interceptor>? interceptors,
+ http.Client? client,
+ JsonConverter? converter,
+ }) : _authInterceptor = AuthInterceptor(
+ appId: appId,
+ apiKey: apiKey,
+ ) {
+ _client = ChopperClient(
+ client: client,
+ converter: converter ?? JsonConverter(),
+ interceptors: [
+ _authInterceptor,
+ AgentInterceptor(
+ agent: AlgoliaAgent(packageVersion)
+ ..addAll([
+ ...?clientSegments,
+ ...Platform.agentSegments(),
+ ]),
+ ),
+ if (logger != null)
+ HttpLoggingInterceptor(
+ level: Level.body,
+ onlyErrors: false,
+ logger: logger,
+ ),
+ ...?interceptors,
+ ],
+ );
+ }
+
+ @override
+ Future<HttpResponse> perform(HttpRequest request) async {
+ try {
+ final Response<Map<String, dynamic>> response = await execute(request);
+
+ if (response.isSuccessful) {
+ return HttpResponse(
+ response.statusCode,
+ response.body,
+ );
+ } else {
+ throw AlgoliaApiException(
+ response.statusCode,
+ response.error ?? response.body,
+ );
+ }
+ } on TimeoutException catch (e) {
+ throw AlgoliaTimeoutException(e);
+ } on http.ClientException catch (e) {
+ throw AlgoliaIOException(e);
+ }
+ }
+
+ /// Executes the [request] and returns the response as an [HttpResponse].
+ Future<Response<Map<String, dynamic>>> execute(HttpRequest request) async {
+ final Request chopperRequest = Request(
+ request.method,
+ requestUri(request),
+ Uri(),
+ body: request.body,
+ headers: {
+ for (final MapEntry<String, dynamic> entry
+ in request.headers?.entries ?? const {})
+ entry.key: entry.value.toString(),
+ if (request.body != null) 'content-type': 'application/json',
+ },
+ );
+
+ return switch (options.timeout) {
+ null => await _client
+ .send<Map<String, dynamic>, Map<String, dynamic>>(chopperRequest),
+ _ => await _client
+ .send<Map<String, dynamic>, Map<String, dynamic>>(chopperRequest)
+ .timeout(options.timeout!),
+ };
+ }
+
+ /// Constructs the request URI from the [request] details.
+ Uri requestUri(HttpRequest request) => Uri(
+ scheme: request.host.scheme,
+ host: request.host.url,
+ port: request.host.port,
+ path: request.path,
+ query: request.queryParameters.isNotEmpty
+ ? request.queryParameters.entries
+ .map((e) => "${e.key}=${e.value}")
+ .join("&")
+ : null,
+ );
+
+ @override
+ void close() => _client.dispose();
+
+ @override
+ void setClientApiKey(String apiKey) {
+ _authInterceptor = AuthInterceptor(
+ appId: _authInterceptor.appId,
+ apiKey: apiKey,
+ );
+ }
+}