[Breaking Change Request] Support abort() in HttpClientRequest in Dart:IO

[zichangg]

Summary

With current APIs in Dart:IO, there is no way to abort the HttpClientRequest. Once HttpClientRequest has been sent, the request cannot be canceled until HttpClientResponse comes back. See the example below:

HttpClient client = new HttpClient();
client.getUrl(Uri.parse("http://www.example.com/"))
   .then((HttpClientRequest request) {
     // Optionally set up headers...
     request.write();
     // Optionally write to the request object...
     // Then call close.
     ...
     return request.close();
   })
   .then((HttpClientResponse response) {
     // Process the response.
     ...
   });

Abort() will allow users to stop waiting for HttpClientResponse, so users can abort the request if it takes too long.

Function signature

  abort([Object? exception, StackTrace? stackTrace]);

The intended behavior

• The future returned by close() will complete with exception and stackTrace if abort() is called prior to HttpClientResponse being available. The default value for exception and stackTrace will be HttpException and StackTrace.empty.
• Data cannot be sent through IOSink's API after abort().
• In case of HttpClientResponse returning before abort, abort() will not make any effect.

Expected use case

HttpClient client = new HttpClient();
client.getUrl(Uri.parse("http://www.example.com/"))
   .then((HttpClientRequest request) {
     // Optionally set up headers...
     request.write();
     // Optionally write to the request object...
     // Then call close.
     Timer(Duration(seconds: 1), () {
       request.abort(Exception("Customized value"));
     }); 
     return request.close();
   })
   .then((HttpClientResponse response) {
     // Process the response.
     ...
   }, onError: (e) {
      // e will be `Exception("Customized value")`
   });

Expected impact

All classes extends or implements HttpClientRequest in Dart:IO will need to update accordingly.

Proposed Implementation

https://dart-review.googlesource.com/c/sdk/+/147339

Relative discussions

#22265

[zichangg]

@lrhn @mit-mit @sortie

[mit-mit]

lgtm, @franklinyow can you enquire with partner teams?

[franklinyow]

cc @Hixie @matanlurey @vsmenon for review and approval.

[Hixie]

An abort method on the request object seems like an elegant solution.

[zichangg]

Based on some discussion in draft cl, abort() now will accept two optional parameters. Users are allowed to provide customized exception and stackTrace, which will trigger onError() callback.
@Hixie @matanlurey @vsmenon

[Hixie]

SGTM.

[zichangg]

A friendly ping. @matanlurey @vsmenon
If it looks good, I can starting preparing fixing patch on packages and flutter. ^_^

[vsmenon]

lgtm

[matanlurey]

lgtm

[franklinyow]

Mark Approved
@zichangg Please go ahead