Added section to README

Improved documentation

Author: JaffaKetchup

pkgs/http/README.md

@@ -113,6 +113,87 @@ 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 abortion of requests in-flight.
+
+Abortion 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].
+
+Depending on when the abortion is triggered, an [`AbortedRequest`][abortedrequest] may be thrown in different places.
+
+```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.parse('http://example.org'),
+    abortTrigger: abortTrigger.future,
+  );
+
+  // Whenever abortion is required:
+  // > abortTrigger.complete();
+
+  // Send request
+  final StreamedResponse response;
+  try {
+    response = await client.send(request);
+  } on AbortedRequest {
+    // 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 AbortedRequest) {
+        // 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 AbortedRequest {
+    // 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
+[abortedrequest]: https://pub.dev/documentation/http/latest/http/AbortedRequest-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/src/abortable.dart

@@ -6,32 +6,37 @@ import 'dart:async';
 
 import 'base_request.dart';
 import 'client.dart';
-import 'exception.dart';
+import 'streamed_response.dart';
 
 /// Enables a request to be recognised by a [Client] as abortable
 abstract mixin class Abortable implements BaseRequest {
-  /// This request will be aborted if this completes
+  /// Completion of this future aborts this request (if the client supports
+  /// abortion)
   ///
-  /// A common pattern is aborting a request when another event occurs (such as
-  /// a user action). A [Completer] may be used to implement this.
+  /// Requests/responses may be aborted at any time during their lifecycle.
   ///
-  /// Another pattern is a timeout. Use [Future.delayed] to achieve this.
+  ///  * If completed before the request has been finalized and sent,
+  ///    [Client.send] completes with an [AbortedRequest] exception
+  ///  * If completed after the response headers are available, or whilst
+  ///    streaming response bytes, clients inject [AbortedRequest] into the
+  ///    [StreamedResponse.stream] then finish it early
+  ///  * If completed after the response is fully complete, there is no effect
   ///
-  /// This future must not complete to an error.
+  /// 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 may complete at any time - a [AbortedRequest] will be thrown
-  /// by [send]/[Client.send] if it is completed before the request is complete.
+  /// This future must not complete to an error.
   ///
-  /// Non-'package:http' [Client]s may unexpectedly not support this trigger.
+  /// Some clients may not support abortion, or may not support this trigger.
   abstract final Future<void>? abortTrigger;
 }
 
-/// Thrown when a HTTP request is aborted
+/// Thrown when an HTTP request is aborted
 ///
-/// Usually, this is due to [Abortable.abortTrigger] completing before the
-/// request is already complete. However, some clients' [Client.close]
-/// implementation may cause open requests to throw this (or a standard
-/// [ClientException]).
+/// Usually, this is due to [Abortable.abortTrigger]. See documentation on that
+/// property for more info.
 class AbortedRequest implements Exception {
   /// Indicator that the request has been aborted
   const AbortedRequest();