fix(dio): guard dispatch-stage handler completion, add request context to duplicate-completion errors

dio/CHANGELOG.md

@@ -5,7 +5,7 @@ See the [Migration Guide][] for the complete breaking changes list.**
 
 ## Unreleased
 
-*None.*
+- Fix duplicate interceptor handler completions: the dispatch stage no longer double-completes a handler racing a cancellation, and the resulting `StateError` (if any) now identifies the offending request.
 
 ## 5.11.1
 

dio/lib/src/dio_mixin.dart

@@ -437,7 +437,7 @@ abstract class DioMixin implements Dio {
           return listenCancelForAsyncTask(
             requestOptions.cancelToken,
             Future(() async {
-              final handler = RequestInterceptorHandler();
+              final handler = RequestInterceptorHandler(requestOptions);
               final result = cb(state.data as RequestOptions, handler);
               _observeInterceptorCallback(
                 result,
@@ -467,7 +467,7 @@ abstract class DioMixin implements Dio {
           return listenCancelForAsyncTask(
             requestOptions.cancelToken,
             Future(() async {
-              final handler = ResponseInterceptorHandler();
+              final handler = ResponseInterceptorHandler(requestOptions);
               final result = cb(state.data as Response, handler);
               _observeInterceptorCallback(
                 result,
@@ -495,7 +495,7 @@ abstract class DioMixin implements Dio {
             ? error
             : InterceptorState(assureDioException(error, requestOptions));
         Future<InterceptorState> handleError() async {
-          final handler = ErrorInterceptorHandler();
+          final handler = ErrorInterceptorHandler(requestOptions);
           final result = cb(state.data, handler);
           _observeInterceptorCallback(
             result,
@@ -552,9 +552,14 @@ abstract class DioMixin implements Dio {
         requestOptions = reqOpt;
         try {
           final value = await _dispatchRequest<T>(reqOpt);
-          handler.resolve(value, true);
+          // A racing cancellation may have already completed this handler.
+          if (!handler.isCompleted) {
+            handler.resolve(value, true);
+          }
         } on DioException catch (e) {
-          handler.reject(e, true);
+          if (!handler.isCompleted) {
+            handler.reject(e, true);
+          }
         }
         return null;
       }),

dio/lib/src/interceptor.dart

@@ -21,19 +21,29 @@ class InterceptorState<T> {
 }
 
 abstract class _BaseHandler {
+  _BaseHandler([this._requestOptions]);
+
   final _completer = Completer<InterceptorState>();
   void Function()? _processNextInQueue;
 
+  // Identifies which request a duplicate-completion error belongs to.
+  final RequestOptions? _requestOptions;
+
   @protected
   Future<InterceptorState> get future => _completer.future;
 
   bool get isCompleted => _completer.isCompleted;
 
   void _throwIfCompleted() {
     if (_completer.isCompleted) {
+      final requestOptions = _requestOptions;
+      final requestDescription = requestOptions == null
+          ? ''
+          : ' (${requestOptions.method} ${requestOptions.uri})';
       throw StateError(
         'The `handler` has already been called, '
-        'make sure each handler gets called only once.',
+        'make sure each handler gets called only once.'
+        '$requestDescription',
       );
     }
   }
@@ -92,6 +102,8 @@ Object? _invokeCallbackDynamically<T, V extends _BaseHandler>(
 
 /// The handler for interceptors to handle before the request has been sent.
 class RequestInterceptorHandler extends _BaseHandler {
+  RequestInterceptorHandler([super.requestOptions]);
+
   /// Deliver the [requestOptions] to the next interceptor.
   ///
   /// Typically, the method should be called once interceptors done
@@ -152,6 +164,8 @@ class RequestInterceptorHandler extends _BaseHandler {
 
 /// The handler for interceptors to handle after respond.
 class ResponseInterceptorHandler extends _BaseHandler {
+  ResponseInterceptorHandler([super.requestOptions]);
+
   /// Deliver the [response] to the next interceptor.
   ///
   /// Typically, the method should be called once interceptors done
@@ -203,6 +217,8 @@ class ResponseInterceptorHandler extends _BaseHandler {
 
 /// The handler for interceptors to handle error occurred during the request.
 class ErrorInterceptorHandler extends _BaseHandler {
+  ErrorInterceptorHandler([super.requestOptions]);
+
   /// Deliver the [error] to the next interceptor.
   ///
   /// Typically, the method should be called once interceptors done

dio/test/interceptor_test.dart

@@ -61,7 +61,8 @@ void main() {
         allOf([
           isA<DioException>(),
           (DioException e) => e.error is StateError,
-          (DioException e) => (e.error as StateError).message == message,
+          (DioException e) =>
+              (e.error as StateError).message.startsWith(message),
         ]),
       ),
     );
@@ -71,7 +72,8 @@ void main() {
         allOf([
           isA<DioException>(),
           (DioException e) => e.error is StateError,
-          (DioException e) => (e.error as StateError).message == message,
+          (DioException e) =>
+              (e.error as StateError).message.startsWith(message),
         ]),
       ),
     );
@@ -81,12 +83,42 @@ void main() {
         allOf([
           isA<DioException>(),
           (DioException e) => e.error is StateError,
-          (DioException e) => (e.error as StateError).message == message,
+          (DioException e) =>
+              (e.error as StateError).message.startsWith(message),
         ]),
       ),
     );
   });
 
+  test(
+    'Duplicate handler call StateError identifies the offending request',
+    () async {
+      final dio = Dio()
+        ..options.baseUrl = MockAdapter.mockBase
+        ..httpClientAdapter = MockAdapter()
+        ..interceptors.add(
+          InterceptorsWrapper(
+            onRequest: (options, handler) {
+              handler.next(options);
+              handler.next(options);
+            },
+          ),
+        );
+      await expectLater(
+        dio.get('/test'),
+        throwsA(
+          allOf([
+            isA<DioException>(),
+            (DioException e) => e.error is StateError,
+            (DioException e) =>
+                (e.error as StateError).message.contains('GET') &&
+                (e.error as StateError).message.contains('/test'),
+          ]),
+        ),
+      );
+    },
+  );
+
   group('InterceptorState', () {
     test('toString()', () {
       final data = DioException(requestOptions: RequestOptions());