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 this.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,117 @@
+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.
+  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,
+  }) : _client = ChopperClient(
+          client: client,
+          converter: converter ?? JsonConverter(),
+          interceptors: [
+            AuthInterceptor(
+              appId: appId,
+              apiKey: apiKey,
+            ),
+            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();
+}