feat: support aborting HTTP requests

[JaffaKetchup]

Resolves #424
Closes #978, closes #521, closes #602, closes #819

As discussed in #424, this adds an Abortable interface for BaseRequests that provides an abortTrigger which Clients may use to abort requests.

We can do it this time :D

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[brianquinlan]

The outline looks good so far! Let me know if you need me to press the button to run the workflows.

[github-actions]

Package publishing

Package	Version	Status	Publish tag (post-merge)
package:cronet_http	1.4.0-wip	WIP (no publish necessary)
package:cupertino_http	2.2.0	already published at pub.dev
package:http	1.5.0-wip	WIP (no publish necessary)
package:http2	3.0.0	ready to publish	http2-v3.0.0
package:http_multi_server	3.2.2	already published at pub.dev
package:http_parser	4.1.2	already published at pub.dev
package:http_profile	0.1.1-wip	WIP (no publish necessary)
package:ok_http	0.1.1-wip	WIP (no publish necessary)
package:web_socket	1.0.1	already published at pub.dev
package:web_socket_channel	3.0.3	already published at pub.dev

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

[github-actions]

PR Health

Breaking changes ⚠️

Package	Change	Current Version	New Version	Needed Version	Looking good?
cronet_http	Breaking	1.3.4	1.4.0-wip	2.0.0 Got "1.4.0-wip" expected >= "2.0.0" (breaking changes)	⚠️
cupertino_http	Breaking	2.2.0	2.2.0	3.0.0 Got "2.2.0" expected >= "3.0.0" (breaking changes)	⚠️
http	Breaking	1.4.0	1.5.0-wip	2.0.0 Got "1.5.0-wip" expected >= "2.0.0" (breaking changes)	⚠️
ok_http	Breaking	0.1.0	0.1.1-wip	0.2.0 Got "0.1.1-wip" expected >= "0.2.0" (breaking changes)	⚠️

This check can be disabled by tagging the PR with skip-breaking-check.

Changelog Entry ❗

Package	Changed Files
package:cronet_http	pkgs/cronet_http/example/pubspec.yaml
package:cupertino_http	pkgs/cupertino_http/example/pubspec.yaml
package:ok_http	pkgs/ok_http/example/pubspec.yaml

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Coverage ⚠️

File	Coverage
pkgs/http/lib/http.dart	💚 100 %
pkgs/http/lib/retry.dart	💚 93 % ⬆️ 2 %
pkgs/http/lib/src/abortable.dart	💚 100 %
pkgs/http/lib/src/base_request.dart	💚 88 %
pkgs/http/lib/src/browser_client.dart	💔 Not covered
pkgs/http/lib/src/io_client.dart	💚 88 % ⬆️ 2 %
pkgs/http/lib/src/mock_client.dart	💚 100 %
pkgs/http/lib/src/multipart_request.dart	💔 93 % ⬇️ 4 %
pkgs/http/lib/src/request.dart	💚 98 % ⬆️ 0 %
pkgs/http/lib/src/streamed_request.dart	💚 100 %

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

API leaks ⚠️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbols
cupertino_http	ncb.NSURLCache NSURLRequest NSURLRequestAttribution NSCachedURLResponse ncb.NSURLSessionDelegate ncb.NSURLSessionConfiguration SSLProtocol tls_protocol_version_t NSHTTPCookieStorage NSURLCredentialStorage __CFRunLoopObserver __CFRunLoopTimer __SecTrust __CFError __darwin_mcontext64 _opaque_pthread_attr_t __darwin_sigaltstack __darwin_ucontext __siginfo sigval rusage_info_v6 _malloc_zone_t _opaque_pthread_cond_t _opaque_pthread_condattr_t _opaque_pthread_mutex_t _opaque_pthread_mutexattr_t _opaque_pthread_once_t _opaque_pthread_rwlock_t _opaque_pthread_rwlockattr_t _opaque_pthread_t UnsignedWide ProcessSerialNumber Point Rect wide TimeBaseRecord NumVersionVariant NumVersion VersRec Float80 Float96 __CFString __CFNull __CFAllocator __CFArray __SecCertificate __SecIdentity __SecKey __SecPolicy __SecAccessControl __SecKeychain __SecKeychainItem __SecKeychainSearch SecKeychainAttribute __SecTrustedApplication __SecAccess __SecACL __SecPassword __sFILE __CFBag __CFBinaryHeap __CFBitVector __CFDictionary __CFNotificationCenter __CFLocale __CFDate __CFTimeZone __CFData __CFCharacterSet __CFCalendar __CFDateFormatter __CFBoolean __CFNumber __CFNumberFormatter __CFURL mach_port_status mach_port_limits mach_port_info_ext mach_port_guard_info mach_port_qos mach_service_port_info mach_port_options UnnamedUnion1 __CFRunLoop __CFRunLoopSource __CFSocket fsignatures fsupplement fchecklv fgetsigsinfo fstore fpunchhole ftrimactivefile fspecread fattributiontag _filesec OS_os_workgroup os_workgroup_attr_opaque_s os_workgroup_join_token_opaque_s os_workgroup_max_parallel_threads_attr_s os_workgroup_interval_data_opaque_s time_value mach_timespec mach_msg_mac_trailer_t security_token_t audit_token_t msg_labels_t mach_msg_security_trailer_t dispatch_source_type_s __CFReadStream __CFWriteStream __CFSet __CFTree __CFUUID __CFBundle __CFMessagePort __CFPlugInInstance __CFMachPort __CFAttributedString __CFURLEnumerator kauth_ace guid_t kauth_acl kauth_filesec _acl _acl_entry _acl_permset _acl_flagset __CFFileSecurity __CFStringTokenizer __CFFileDescriptor __CFUserNotification __CFXMLNode __CFXMLParser cssm_data SecAsn1Template_struct cssm_guid cssm_version cssm_subservice_uid cssm_net_address cssm_crypto_data cssm_list_element UnnamedUnion2 cssm_list CSSM_TUPLE cssm_tuplegroup cssm_sample cssm_samplegroup cssm_memory_funcs cssm_encoded_cert cssm_parsed_cert cssm_cert_pair cssm_certgroup UnnamedUnion3 cssm_base_certs cssm_access_credentials cssm_authorizationgroup cssm_acl_validity_period cssm_acl_entry_prototype cssm_acl_owner_prototype cssm_acl_entry_input cssm_resource_control_context cssm_acl_entry_info cssm_acl_edit cssm_func_name_addr cssm_date cssm_range cssm_query_size_data cssm_key_size cssm_keyheader cssm_key cssm_dl_db_handle cssm_context_attribute cssm_context_attribute_value cssm_kr_profile cssm_context cssm_pkcs1_oaep_params cssm_csp_operational_statistics cssm_pkcs5_pbkdf1_params cssm_pkcs5_pbkdf2_params cssm_kea_derive_params cssm_tp_authority_id cssm_field cssm_tp_policyinfo cssm_dl_db_list cssm_tp_callerauth_context cssm_encoded_crl cssm_parsed_crl cssm_crl_pair cssm_crlgroup UnnamedUnion4 cssm_fieldgroup cssm_evidence cssm_tp_verify_context cssm_tp_verify_context_result cssm_tp_request_set cssm_tp_result_set cssm_tp_confirm_response cssm_tp_certissue_input cssm_tp_certissue_output cssm_tp_certchange_input cssm_tp_certchange_output cssm_tp_certverify_input cssm_tp_certverify_output cssm_tp_certnotarize_input cssm_tp_certnotarize_output cssm_tp_certreclaim_input cssm_tp_certreclaim_output cssm_tp_crlissue_input cssm_tp_crlissue_output cssm_cert_bundle_header cssm_cert_bundle cssm_db_attribute_info cssm_db_attribute_label cssm_db_attribute_data cssm_db_record_attribute_info cssm_db_record_attribute_data cssm_db_parsing_module_info cssm_db_index_info cssm_db_unique_record cssm_db_record_index_info cssm_dbinfo cssm_selection_predicate cssm_query_limits cssm_query cssm_dl_pkcs11_attributes cssm_name_list cssm_db_schema_attribute_info cssm_db_schema_index_info SecAsn1AlgId cssm_x509_type_value_pair cssm_x509_rdn cssm_x509_name SecAsn1PubKeyInfo cssm_x509_time x509_validity cssm_x509ext_basicConstraints cssm_x509_extensionTagAndValue cssm_x509ext_pair cssm_x509_extension cssm_x509ext_value extension_data_format cssm_x509_extensions cssm_x509_tbs_certificate cssm_x509_signature cssm_x509_signed_certificate cssm_x509ext_policyQualifierInfo cssm_x509ext_policyQualifiers cssm_x509ext_policyInfo cssm_x509_revoked_cert_entry cssm_x509_revoked_cert_list cssm_x509_tbs_certlist cssm_x509_signed_crl __CE_OtherName __CE_GeneralName __CE_GeneralNameType __CE_GeneralNames __CE_AuthorityKeyID __CE_ExtendedKeyUsage __CE_BasicConstraints __CE_PolicyQualifierInfo __CE_PolicyInformation __CE_CertPolicies __CE_DistributionPointName UnnamedUnion5 __CE_CrlDistributionPointNameType __CE_CRLDistributionPoint __CE_CRLDistPointsSyntax __CE_AccessDescription __CE_AuthorityInfoAccess __CE_SemanticsInformation __CE_QC_Statement __CE_QC_Statements __CE_IssuingDistributionPoint __CE_GeneralSubtree __CE_GeneralSubtrees __CE_NameConstraints __CE_PolicyMapping __CE_PolicyMappings __CE_PolicyConstraints __CE_DataAndType CE_Data __CE_DataType cssm_acl_process_subject_selector cssm_acl_keychain_prompt_selector cssm_appledl_open_parameters cssm_applecspdl_db_settings_parameters cssm_applecspdl_db_is_locked_parameters cssm_applecspdl_db_change_password_parameters SSLContext
ok_http	$Certificate$NullableType $Certificate$Type PublicKey $PublicKey$NullableType $PublicKey$Type $PublicKey $X509Certificate$NullableType $X509Certificate$Type $PrivateKey$NullableType $PrivateKey$Type $PrivateKey

This check can be disabled by tagging the PR with skip-leaking-check.

License Headers ✔️

// 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.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/http/example/main.dart

[JaffaKetchup]

Sorry @brianquinlan :D Hopefully the workflows should be good to go now (except the tests which I've commented above).

[brianquinlan]

Amazing work. I have a few nits and I'd like to patch this in and try it out myself before we merge it.

[brianquinlan]

I fixed all of the cronet_http fails and most of cupertino_http failures. I think that the ok_http failures are unrelated (and the cupertino_http failures are probably unrelated too). I'll take a closer look at the cupertino_http failures tomorrow.

[brianquinlan]

I think that the package:cupertino_http tests will be fixed in #1786 and the package:cronet_http test failures are unrelated.

[JaffaKetchup]

@brianquinlan Not sure where/how to test the retry client effectively. Would just plugging it into the existing client conformance tests for io & html be acceptable? I'm not really sure why it is tested alone in the first place.

  testAbort(clientFactory(),
      supportsAbort: supportsAbort,
      canStreamRequestBody: canStreamRequestBody,
      canStreamResponseBody: canStreamResponseBody);
+ testAbort(RetryClient(clientFactory()),
+     supportsAbort: supportsAbort,
+     canStreamRequestBody: canStreamRequestBody,
+     canStreamResponseBody: canStreamResponseBody);

I think that it makes sense use the conformance tests on RetryClient but that test should be in pkg/http. May have test/http_retry_conformance_test.dart?

But that test would not check that the behavior if the request is aborted after the first request fails. Maybe you needs some tests in http_retry_test.dart like:

  test('', () async {
    var count = 0;
    final client = RetryClient(
        MockClient(expectAsync1((request) async {
          count++;
          if (count < 2) return Response('', 503);
          throw RequestAbortedException(...);
        }, count: 2)),
        delay: (_) => Duration.zero);

    expect(client.get(Uri.http('example.org', ''), throwsA<RequestAbortedException>(...));
    
  });

You should probably also add a test for the case where the Client does not support being aborted. Do you want to not retry is the request has been imported even if the Client does not throw RequestAborted? Like:

  test('', () async {
    var count = 0;
    final client = RetryClient(
        MockClient(expectAsync1((request) async {
          count++;
          if (count == 2) {
             abortCompleter.complete();
          }
          return Response('', 503);
        }, count: 2)),
        delay: (_) => Duration.zero);

    final response = await client.get(Uri.http('example.org', ''));
    expect(client.send(<abortable request with abortCompleter>), throwsA<RequestAbortedException>(...));
  });

[JaffaKetchup]

@brianquinlan That should be all sorted, ready for re-review.

[brianquinlan]

Thanks for fixing the lints!

[devoncarew]

Not for this PR, but we could also address this by moving this repo to a workspace.

[devoncarew]

🎉

[JaffaKetchup]

🎉indeed 😂

[devoncarew]

This might want a type on the left ('DO type annotate fields and top-level variables if the type isn't obvious'). 'Obvious' isn't precisely defined, but adding one would also match w/ the other fields.

Suggested change

	final _openRequestAbortControllers = <AbortController>[];
	final List<AbortController> _openRequestAbortControllers = [];

[kevmoo]

I really don't like this style. Prefer as-is!

Devon: No offence to your bad ideas. 😛

[brianquinlan]

I agree with @kevmoo here - since the type is clearly indicated on the RHS, adding it explicitly is redundant

[devoncarew]

👍 - good docs on the various possible states

[brianquinlan]

I'm going to merge this. My intent is to release a 1.5.0-beta version and update the associated issues asking for testing.

[JaffaKetchup]

Sounds good to me. Thanks for all the help!

[brianquinlan]

Sounds good to me. Thanks for all the help!

@JaffaKetchup No, thank you for all the great work!

[JaffaKetchup]

(Just to note, this is now used by default in the latest version of flutter_map, so hopefully it all goes well :D)

[brianquinlan]

(Just to note, this is now used by default in the latest version of flutter_map, so hopefully it all goes well :D)

Awesome! I was wondering if we would get adequate testing for the beta release but I don't need to worry anymore ;-)