feat: package/chopper_requester

packages/chopper_requester/.gitignore

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

packages/chopper_requester/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0
+
+- Initial version.

packages/chopper_requester/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Klemen Tusar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/chopper_requester/README.md

@@ -0,0 +1,117 @@
+# Chopper Requester for Algolia Search Client
+
+## 💡 Installation
+
+Add Algolia Client Core 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
+});
+```
+
+### 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)),
+ ),
+ );
+ ```
+
+## License
+
+Chopper Requester for Algolia Search Client is an open-sourced software licensed under the [MIT license](LICENSE).

packages/chopper_requester/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:lints/recommended.yaml

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';

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()));
+}

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,
+ },
+ ),
+ );
+}

packages/chopper_requester/lib/src/chopper_requester.dart

@@ -0,0 +1,109 @@
+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,
+ }) : _client = ChopperClient(
+ client: client,
+ 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,
+ Uri(
+ scheme: request.host.scheme,
+ host: request.host.url,
+ port: request.host.port,
+ path: request.path,
+ ),
+ _client.baseUrl,
+ body: request.body,
+ parameters: request.queryParameters,
+ 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!),
+ };
+ }
+
+ @override
+ void close() => _client.dispose();
+}

packages/chopper_requester/lib/src/platform/platform.dart

@@ -0,0 +1,17 @@
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:chopper/chopper.dart';
+
+import 'platform_stub.dart'
+ if (dart.library.html) 'platform_web.dart'
+ if (dart.library.io) 'platform_io.dart';
+
+final class Platform {
+ /// Get [AgentSegment]s for the current platform.
+ static Iterable<AgentSegment> agentSegments() => platformAgentSegments();
+
+ /// Set Algolia Agent as User-Agent or as query param depending on the platform.
+ static Request algoliaAgent<T>(Chain<T> chain, String agent) =>
+ platformAlgoliaAgent(chain, agent);
+
+ Platform._();
+}

packages/chopper_requester/lib/src/platform/platform_io.dart

@@ -0,0 +1,20 @@
+import 'dart:io' as io;
+
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:chopper/chopper.dart';
+
+/// [AgentSegment]s for native platforms.
+Iterable<AgentSegment> platformAgentSegments() => [
+ AgentSegment(
+ value: 'Dart',
+ version: io.Platform.version,
+ ),
+ AgentSegment(
+ value: io.Platform.operatingSystem,
+ version: io.Platform.operatingSystemVersion,
+ ),
+ ];
+
+/// [AlgoliaAgent] for native platforms as user-agent.
+Request platformAlgoliaAgent<T>(Chain<T> chain, String agent) =>
+ applyHeader(chain.request, "user-agent", agent);

packages/chopper_requester/lib/src/platform/platform_stub.dart

@@ -0,0 +1,11 @@
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:chopper/chopper.dart';
+
+/// [AgentSegment]s for unsupported platforms.
+Iterable<AgentSegment> platformAgentSegments() => const [];
+
+/// [AlgoliaAgent] for unsupported platforms.
+Request platformAlgoliaAgent<T>(Chain<T> chain, String agent) {
+ // NO-OP.
+ return chain.request;
+}

packages/chopper_requester/lib/src/platform/platform_web.dart

@@ -0,0 +1,20 @@
+import 'dart:html' as web;
+
+import 'package:algolia_client_core/algolia_client_core.dart';
+import 'package:chopper/chopper.dart';
+
+/// [AgentSegment]s for web platforms.
+Iterable<AgentSegment> platformAgentSegments() => [
+ AgentSegment(
+ value: 'Platform',
+ version: 'Web ${web.window.navigator.platform}',
+ ),
+ ];
+
+Request platformAlgoliaAgent<T>(Chain<T> chain, String agent) =>
+ chain.request.copyWith(
+ parameters: {
+ ...chain.request.parameters,
+ 'X-Algolia-Agent': agent,
+ },
+ );

packages/chopper_requester/lib/src/version.dart

@@ -0,0 +1,2 @@
+/// Current package version
+const packageVersion = '1.0.0';