feat: support aborting HTTP requests (#1773)

Author: JaffaKetchup

pkgs/cronet_http/example/pubspec.yaml

@@ -29,3 +29,9 @@ dev_dependencies:
 
 flutter:
   uses-material-design: true
+
+# TODO(brianquinlan): Remove this when a release version of `package:http`
+# supports abortable requests.
+dependency_overrides:
+  http:
+    path: ../../http/

pkgs/cupertino_http/example/pubspec.yaml

@@ -38,3 +38,9 @@ dev_dependencies:
 
 flutter:
   uses-material-design: true
+
+# TODO(brianquinlan): Remove this when a release version of `package:http`
+# supports abortable requests.
+dependency_overrides:
+  http:
+    path: ../../http/

pkgs/http/CHANGELOG.md

@@ -1,5 +1,6 @@
-## 1.4.1
+## 1.5.0-wip
 
+* Added support for aborting requests before they complete.
 * Clarify that some header names may not be sent/received.
 
 ## 1.4.0

pkgs/http/README.md

@@ -113,6 +113,92 @@ the [`RetryClient()`][new RetryClient] constructor.
 
 [new RetryClient]: https://pub.dev/documentation/http/latest/retry/RetryClient/RetryClient.html
 
+## Aborting requests
+
+Some clients, such as [`BrowserClient`][browserclient], [`IOClient`][ioclient], and
+[`RetryClient`][retryclient], support aborting requests before they complete.
+
+Aborting in this way can only be performed when using [`Client.send`][clientsend] or
+[`BaseRequest.send`][baserequestsend] with an [`Abortable`][abortable] request (such
+as [`AbortableRequest`][abortablerequest]).
+
+To abort a request, complete the [`Abortable.abortTrigger`][aborttrigger] `Future`.
+
+If the request is aborted before the response `Future` completes, then the response
+`Future` will complete with [`RequestAbortedException`][requestabortedexception]. If
+the response is a `StreamedResponse` and the the request is cancelled while the
+response stream is being consumed, then the response stream will contain a
+[`RequestAbortedException`][requestabortedexception].
+
+```dart
+import 'dart:async';
+
+import 'package:http/http.dart' as http;
+
+Future<void> main() async {
+  final abortTrigger = Completer<void>();
+  final client = Client();
+  final request = AbortableRequest(
+    'GET',
+    Uri.https('example.com'),
+    abortTrigger: abortTrigger.future,
+  );
+
+  // Whenever abortion is required:
+  // > abortTrigger.complete();
+
+  // Send request
+  final StreamedResponse response;
+  try {
+    response = await client.send(request);
+  } on RequestAbortedException {
+    // request aborted before it was fully sent
+    rethrow;
+  }
+
+  // Using full response bytes listener
+  response.stream.listen(
+    (data) {
+      // consume response bytes
+    },
+    onError: (Object err) {
+      if (err is RequestAbortedException) {
+        // request aborted whilst response bytes are being streamed;
+        // the stream will always be finished early
+      }
+    },
+    onDone: () {
+      // response bytes consumed, or partially consumed if finished
+      // early due to abortion
+    },
+  );
+
+  // Alternatively, using `asFuture`
+  try {
+    await response.stream.listen(
+      (data) {
+        // consume response bytes
+      },
+    ).asFuture<void>();
+  } on RequestAbortedException {
+    // request aborted whilst response bytes are being streamed
+    rethrow;
+  }
+    // response bytes fully consumed
+}
+```
+
+[browserclient]: https://pub.dev/documentation/http/latest/browser_client/BrowserClient-class.html
+[ioclient]: https://pub.dev/documentation/http/latest/io_client/IOClient-class.html
+[retryclient]: https://pub.dev/documentation/http/latest/retry/RetryClient-class.html
+[clientsend]: https://pub.dev/documentation/http/latest/http/Client/send.html
+[baserequestsend]: https://pub.dev/documentation/http/latest/http/BaseRequest/send.html
+[abortable]: https://pub.dev/documentation/http/latest/http/Abortable-class.html
+[abortablerequest]: https://pub.dev/documentation/http/latest/http/AbortableRequest-class.html
+[aborttrigger]: https://pub.dev/documentation/http/latest/http/Abortable/abortTrigger.html
+[requestabortedexception]: https://pub.dev/documentation/http/latest/http/RequestAbortedException-class.html
+
+
 ## Choosing an implementation
 
 There are multiple implementations of the `package:http` [`Client`][client] interface. By default, `package:http` uses [`BrowserClient`][browserclient] on the web and [`IOClient`][ioclient] on all other platforms. You can choose a different [`Client`][client] implementation based on the needs of your application.

pkgs/http/lib/http.dart

@@ -14,6 +14,7 @@ import 'src/request.dart';
 import 'src/response.dart';
 import 'src/streamed_request.dart';
 
+export 'src/abortable.dart';
 export 'src/base_client.dart';
 export 'src/base_request.dart';
 export 'src/base_response.dart'

pkgs/http/lib/retry.dart

@@ -52,6 +52,11 @@ final class RetryClient extends BaseClient {
   /// the client has a chance to perform side effects like logging. The
   /// `response` parameter will be null if the request was retried due to an
   /// error for which [whenError] returned `true`.
+  ///
+  /// If the inner client supports aborting requests, then this client will
+  /// forward any [RequestAbortedException]s thrown. A request will not be
+  /// retried if it is aborted (even if the inner client does not support
+  /// aborting requests).
   RetryClient(
     this._inner, {
     int retries = 3,
@@ -108,11 +113,22 @@ final class RetryClient extends BaseClient {
   Future<StreamedResponse> send(BaseRequest request) async {
     final splitter = StreamSplitter(request.finalize());
 
+    var aborted = false;
+    if (request case Abortable(:final abortTrigger?)) {
+      unawaited(abortTrigger.whenComplete(() => aborted = true));
+    }
+
     var i = 0;
     for (;;) {
       StreamedResponse? response;
       try {
+        // If the inner client doesn't support abortable, we still try to avoid
+        // re-requests when aborted
+        if (aborted) throw RequestAbortedException(request.url);
+
         response = await _inner.send(_copyRequest(request, splitter.split()));
+      } on RequestAbortedException {
+        rethrow;
       } catch (error, stackTrace) {
         if (i == _retries || !await _whenError(error, stackTrace)) rethrow;
       }
@@ -122,7 +138,7 @@ final class RetryClient extends BaseClient {
 
         // Make sure the response stream is listened to so that we don't leave
         // dangling connections.
-        _unawaited(response.stream.listen((_) {}).cancel().catchError((_) {}));
+        unawaited(response.stream.listen((_) {}).cancel().catchError((_) {}));
       }
 
       await Future<void>.delayed(_delay(i));
@@ -133,7 +149,18 @@ final class RetryClient extends BaseClient {
 
   /// Returns a copy of [original] with the given [body].
   StreamedRequest _copyRequest(BaseRequest original, Stream<List<int>> body) {
-    final request = StreamedRequest(original.method, original.url)
+    final StreamedRequest request;
+    if (original case Abortable(:final abortTrigger?)) {
+      request = AbortableStreamedRequest(
+        original.method,
+        original.url,
+        abortTrigger: abortTrigger,
+      );
+    } else {
+      request = StreamedRequest(original.method, original.url);
+    }
+
+    request
       ..contentLength = original.contentLength
       ..followRedirects = original.followRedirects
       ..headers.addAll(original.headers)
@@ -158,5 +185,3 @@ bool _defaultWhenError(Object error, StackTrace stackTrace) => false;
 
 Duration _defaultDelay(int retryCount) =>
     const Duration(milliseconds: 500) * math.pow(1.5, retryCount);
-
-void _unawaited(Future<void>? f) {}

pkgs/http/lib/src/abortable.dart

@@ -0,0 +1,43 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+
+import 'base_request.dart';
+import 'client.dart';
+import 'exception.dart';
+import 'streamed_response.dart';
+
+/// An HTTP request that can be aborted before it completes.
+abstract mixin class Abortable implements BaseRequest {
+  /// Completion of this future aborts this request (if the client supports
+  /// abortion).
+  ///
+  /// Requests/responses may be aborted at any time during their lifecycle.
+  ///
+  ///  * If completed before the request has been finalized and sent,
+  ///    [Client.send] completes with [RequestAbortedException].
+  ///  * If completed after the response headers are available, or whilst
+  ///    streaming the response, clients inject [RequestAbortedException] into
+  ///    the [StreamedResponse.stream] then close the stream.
+  ///  * If completed after the response is fully complete, there is no effect.
+  ///
+  /// A common pattern is aborting a request when another event occurs (such as
+  /// a user action): use a [Completer] to implement this. To implement a
+  /// timeout (to abort the request after a set time has elapsed), use
+  /// [Future.delayed].
+  ///
+  /// This future must not complete with an error.
+  ///
+  /// Some clients may not support abortion, or may not support this trigger.
+  abstract final Future<void>? abortTrigger;
+}
+
+/// Thrown when an HTTP request is aborted.
+///
+/// This exception is triggered when [Abortable.abortTrigger] completes.
+class RequestAbortedException extends ClientException {
+  RequestAbortedException([Uri? uri])
+      : super('Request aborted by `abortTrigger`', uri);
+}

pkgs/http/lib/src/base_request.dart

@@ -7,6 +7,7 @@ import 'dart:collection';
 import 'package:meta/meta.dart';
 
 import '../http.dart' show ClientException, get;
+import 'abortable.dart';
 import 'base_client.dart';
 import 'base_response.dart';
 import 'byte_stream.dart';
@@ -20,6 +21,10 @@ import 'utils.dart';
 /// [BaseClient.send], which allows the user to provide fine-grained control
 /// over the request properties. However, usually it's easier to use convenience
 /// methods like [get] or [BaseClient.get].
+///
+/// Subclasses/implementers should mixin/implement [Abortable] to support
+/// request cancellation. A future breaking version of 'package:http' will
+/// merge [Abortable] into [BaseRequest], making it a requirement.
 abstract class BaseRequest {
   /// The HTTP method of the request.
   ///

pkgs/http/lib/src/browser_client.dart

@@ -8,12 +8,14 @@ import 'dart:js_interop';
 import 'package:web/web.dart'
     show
         AbortController,
+        DOMException,
         HeadersInit,
         ReadableStreamDefaultReader,
         RequestInfo,
         RequestInit,
         Response;
 
+import 'abortable.dart';
 import 'base_client.dart';
 import 'base_request.dart';
 import 'exception.dart';
@@ -49,15 +51,14 @@ external JSPromise<Response> _fetch(
 /// Responses are streamed but requests are not. A request will only be sent
 /// once all the data is available.
 class BrowserClient extends BaseClient {
-  final _abortController = AbortController();
-
   /// Whether to send credentials such as cookies or authorization headers for
   /// cross-site requests.
   ///
   /// Defaults to `false`.
   bool withCredentials = false;
 
   bool _isClosed = false;
+  final _openRequestAbortControllers = <AbortController>[];
 
   /// Sends an HTTP request and asynchronously returns the response.
   @override
@@ -67,8 +68,17 @@ class BrowserClient extends BaseClient {
           'HTTP request failed. Client is already closed.', request.url);
     }
 
+    final abortController = AbortController();
+    _openRequestAbortControllers.add(abortController);
+
     final bodyBytes = await request.finalize().toBytes();
     try {
+      if (request case Abortable(:final abortTrigger?)) {
+        // Tear-offs of external extension type interop members are disallowed
+        // ignore: unnecessary_lambdas
+        unawaited(abortTrigger.whenComplete(() => abortController.abort()));
+      }
+
       final response = await _fetch(
         '${request.url}'.toJS,
         RequestInit(
@@ -81,7 +91,7 @@ class BrowserClient extends BaseClient {
             for (var header in request.headers.entries)
               header.key: header.value,
           }.jsify()! as HeadersInit,
-          signal: _abortController.signal,
+          signal: abortController.signal,
           redirect: request.followRedirects ? 'follow' : 'error',
         ),
       ).toDart;
@@ -116,20 +126,28 @@ class BrowserClient extends BaseClient {
       );
     } catch (e, st) {
       _rethrowAsClientException(e, st, request);
+    } finally {
+      _openRequestAbortControllers.remove(abortController);
     }
   }
 
   /// Closes the client.
   ///
-  /// This terminates all active requests.
+  /// This terminates all active requests, which may cause them to throw
+  /// [RequestAbortedException] or [ClientException].
   @override
   void close() {
+    for (final abortController in _openRequestAbortControllers) {
+      abortController.abort();
+    }
     _isClosed = true;
-    _abortController.abort();
   }
 }
 
 Never _rethrowAsClientException(Object e, StackTrace st, BaseRequest request) {
+  if (e case DOMException(:final name) when name == 'AbortError') {
+    Error.throwWithStackTrace(RequestAbortedException(request.url), st);
+  }
   if (e is! ClientException) {
     var message = e.toString();
     if (message.startsWith('TypeError: ')) {