Merge pull request #61 from ArunPrakashG/feature/execute-middleware

[FEATURE] Execution Middleware Override

lib/src/bootstrap_builder.dart

@@ -26,7 +26,7 @@ class BootstrapBuilder {
     _middlewares = config.middlewares;
   }
 
-  Duration _defaultRequestTimeout = kDefaultRequestTimeout; // 60 seconds
+  Duration _defaultRequestTimeout = DEFAULT_REQUEST_TIMEOUT; // 60 seconds
   bool Function(dynamic)? _responsePreprocessorDelegate;
   IAuthorization? _defaultAuthorization;
   String? _defaultUserAgent;

lib/src/client_configuration.dart

@@ -8,7 +8,7 @@ import 'constants.dart';
 @immutable
 final class BootstrapConfiguration {
   const BootstrapConfiguration({
-    this.requestTimeout = kDefaultRequestTimeout,
+    this.requestTimeout = DEFAULT_REQUEST_TIMEOUT,
     this.responsePreprocessorDelegate,
     this.defaultAuthorization,
     this.defaultUserAgent,

lib/src/constants.dart

@@ -1 +1,2 @@
-const Duration kDefaultRequestTimeout = Duration(seconds: 30);
+const Duration DEFAULT_REQUEST_TIMEOUT = Duration(seconds: 30);
+const String MIDDLEWARE_HEADER_KEY = 'X-Local-Middleware';

lib/src/enums.dart

@@ -28,6 +28,7 @@ enum RequestErrorType {
   requestCancelled,
   invalidStatusCode,
   middlewareAborted,
+  middlewareExecutionFailed,
 }
 
 enum SearchType {

lib/src/internal_requester.dart

@@ -1,5 +1,9 @@
 part of 'wordpress_client_base.dart';
 
+typedef MiddlwareResponseTransformer = WordpressRawResponse Function(
+  MiddlewareRawResponse data,
+);
+
 final class InternalRequester extends IRequestExecutor {
   InternalRequester.configure(
     this._baseUrl, [
@@ -94,7 +98,7 @@ final class InternalRequester extends IRequestExecutor {
 
   @override
   Future<WordpressRawResponse> execute(WordpressRequest request) async {
-    final headers = request.headers ?? <String, dynamic>{};
+    final requestHeaders = request.headers ?? <String, dynamic>{};
 
     if (request.requireAuth) {
       final authorizer = () {
@@ -127,7 +131,7 @@ final class InternalRequester extends IRequestExecutor {
         );
       }
 
-      headers[authResult.key] = authResult.value;
+      requestHeaders[authResult.key] = authResult.value;
     }
 
     final requestUrl = () {
@@ -140,6 +144,44 @@ final class InternalRequester extends IRequestExecutor {
 
     _triggerStatistics(requestUrl);
 
+    final result = await executeGuarded(
+      function: () async {
+        return _executeMiddlewareEvent(
+          request: request,
+          transformer: (data) {
+            final headers = <String, dynamic>{
+              MIDDLEWARE_HEADER_KEY: true,
+            };
+
+            headers.addAllIfNotNull(data.headers);
+
+            return WordpressRawResponse(
+              data: data,
+              code: data.statusCode,
+              headers: headers,
+              requestHeaders: requestHeaders,
+              extra: data.extra ?? <String, dynamic>{},
+              message:
+                  data.message ?? 'Middleware event executed successfully.',
+            );
+          },
+        );
+      },
+      onError: (error, stackTrace) async {
+        return WordpressRawResponse(
+          data: null,
+          requestHeaders: requestHeaders,
+          code: -RequestErrorType.middlewareExecutionFailed.index,
+          message: 'Middleware execution failed.',
+        );
+      },
+    );
+
+    if (result != null &&
+        result.code != -RequestErrorType.middlewareExecutionFailed.index) {
+      return result;
+    }
+
     final watch = Stopwatch();
 
     Future<Response<dynamic>> run() async {
@@ -159,7 +201,7 @@ final class InternalRequester extends IRequestExecutor {
             method: request.method.name,
             sendTimeout: request.sendTimeout,
             receiveTimeout: request.receiveTimeout,
-            headers: headers,
+            headers: requestHeaders,
           ),
         );
       } finally {
@@ -184,6 +226,21 @@ final class InternalRequester extends IRequestExecutor {
     );
   }
 
+  Future<WordpressRawResponse?> _executeMiddlewareEvent({
+    required WordpressRequest request,
+    required MiddlwareResponseTransformer transformer,
+  }) async {
+    for (final middleware in _middlewares) {
+      final result = await middleware.onExecute(request);
+
+      if (result.hasData) {
+        return transformer(result);
+      }
+    }
+
+    return null;
+  }
+
   Dio _createDioClient() {
     final client = Dio(
       BaseOptions(

lib/src/middleware/delegated_middleware.dart

@@ -12,19 +12,24 @@ typedef OnResponseDelegate = Future<WordpressRawResponse> Function(
 
 typedef InitializeDelegate = Future<void> Function();
 typedef OnRemovedDelegate = Future<void> Function();
+typedef OnExecuteDelegate = Future<MiddlewareRawResponse> Function(
+  WordpressRequest request,
+);
 
 final class DelegatedMiddleware extends IWordpressMiddleware {
   const DelegatedMiddleware({
     required this.onRequestDelegate,
     required this.onResponseDelegate,
     this.initializeDelegate,
+    this.onExecuteDelegate,
     this.onRemovedDelegate,
   });
 
   final InitializeDelegate? initializeDelegate;
   final OnRequestDelegate onRequestDelegate;
   final OnResponseDelegate onResponseDelegate;
   final OnRemovedDelegate? onRemovedDelegate;
+  final OnExecuteDelegate? onExecuteDelegate;
 
   @override
   Future<void> onLoad() async {
@@ -39,6 +44,12 @@ final class DelegatedMiddleware extends IWordpressMiddleware {
     return onRequestDelegate(request);
   }
 
+  @override
+  Future<MiddlewareRawResponse> onExecute(WordpressRequest request) async {
+    return await onExecuteDelegate?.call(request) ??
+        MiddlewareRawResponse.defaultInstance();
+  }
+
   @override
   Future<WordpressRawResponse> onResponse(WordpressRawResponse response) async {
     return onResponseDelegate(response);

lib/src/middleware/middleware_exports.dart

@@ -1,2 +1,3 @@
 export 'delegated_middleware.dart';
+export 'models/middleware_raw_response.dart';
 export 'wordpress_middleware_base.dart';

lib/src/middleware/models/middleware_raw_response.dart

@@ -0,0 +1,26 @@
+final class MiddlewareRawResponse {
+  const MiddlewareRawResponse({
+    required this.statusCode,
+    required this.body,
+    this.message,
+    this.headers,
+    this.extra,
+  });
+
+  factory MiddlewareRawResponse.defaultInstance() {
+    return const MiddlewareRawResponse(statusCode: -99, body: null);
+  }
+
+  final int statusCode;
+  final Map<String, dynamic>? headers;
+  final Map<String, dynamic>? extra;
+  final dynamic body;
+  final String? message;
+
+  bool get hasData => body != null && statusCode >= 200 && statusCode < 300;
+
+  @override
+  String toString() {
+    return 'MiddlewareRawResponse(statusCode: $statusCode, headers: $headers, body: $body, message: $message, extra: $extra)';
+  }
+}

lib/src/middleware/wordpress_middleware_base.dart

@@ -2,13 +2,31 @@ import 'dart:async';
 
 import '../library_exports.dart';
 
-abstract base class IWordpressMiddleware {
+/// The base interface for WordPress middleware.
+abstract class IWordpressMiddleware {
   const IWordpressMiddleware();
 
+  /// The name of the middleware.
   String get name;
 
+  /// Called when the middleware is loaded.
   Future<void> onLoad();
+
+  /// Called before sending a request to the WordPress server.
   Future<WordpressRequest> onRequest(WordpressRequest request);
+
+  /// Called before executing a request to the WordPress server.
+  ///
+  /// By default, it returns a [MiddlewareRawResponse] with default values.
+  ///
+  /// This can used for returning a custom response (cached response), or to cancel the request (By throwing an exception).
+  Future<MiddlewareRawResponse> onExecute(WordpressRequest request) async {
+    return MiddlewareRawResponse.defaultInstance();
+  }
+
+  /// Called after receiving a response from the WordPress server.
   Future<WordpressRawResponse> onResponse(WordpressRawResponse response);
+
+  /// Called when the middleware is unloaded.
   Future<void> onUnload();
 }

lib/src/requests/wordpress_request.dart

@@ -16,8 +16,8 @@ final class WordpressRequest {
     this.requireAuth = false,
     this.authorization,
     this.validator,
-    this.sendTimeout = kDefaultRequestTimeout,
-    this.receiveTimeout = kDefaultRequestTimeout,
+    this.sendTimeout = DEFAULT_REQUEST_TIMEOUT,
+    this.receiveTimeout = DEFAULT_REQUEST_TIMEOUT,
   });
 
   /// The request url.

lib/src/responses/wordpress_raw_response.dart

@@ -2,6 +2,7 @@ import 'package:collection/collection.dart';
 import 'package:meta/meta.dart';
 
 import '../../wordpress_client.dart';
+import '../constants.dart';
 import '../utilities/helpers.dart';
 import 'wordpress_error.dart';
 
@@ -71,6 +72,8 @@ final class WordpressRawResponse {
   /// Returns true if the given [code] is not in between 200 to 399 range. A convenience method for `!isSuccessful`.
   bool get isFailure => !isSuccessful;
 
+  bool get isMiddlewareResponse => headers.containsKey(MIDDLEWARE_HEADER_KEY);
+
   dynamic operator [](dynamic key) {
     if (data == null) {
       throw NullReferenceException('Response is null.');

lib/src/wordpress_client_base.dart

@@ -6,6 +6,7 @@ import 'package:dio/dio.dart';
 import 'package:path/path.dart';
 
 import 'bootstrap_builder.dart';
+import 'constants.dart';
 import 'interface/application_passwords.dart';
 import 'interface/category.dart';
 import 'interface/comments.dart';