Refactor of the with*HttpPubApiClient method(s).

app/lib/fake/backend/fake_auth_provider.dart

@@ -416,15 +416,20 @@ Future<String> _acquireCsrfToken({
 
 /// Creates a pub.dev API client and executes [fn], making sure that the HTTP
 /// resources are freed after the callback finishes.
+/// The callback [fn] is retried on the transient network errors.
 ///
 /// The [email] is used to create an HTTP session and the related CSRF token is
 /// extracted from the session, both are sent alongside the requests.
-Future<R> withFakeAuthHttpPubApiClient<R>(
+Future<R> withFakeAuthRetryPubApiClient<R>(
   Future<R> Function(PubApiClient client) fn, {
   required String email,
   List<String>? scopes,
+
+  /// The base URL of the pub server.
   String? pubHostedUrl,
-  Set<String>? experimental,
+
+  /// The enabled experiments that will be part of the experimental cookie.
+  Set<String>? experiments,
 }) async {
   final sessionId = await _acquireFakeSessionId(
     email: email,
@@ -436,11 +441,11 @@ Future<R> withFakeAuthHttpPubApiClient<R>(
     pubHostedUrl: pubHostedUrl,
   );
 
-  return await withHttpPubApiClient(
+  return await withRetryPubApiClient(
     sessionId: sessionId,
     csrfToken: csrfToken,
     pubHostedUrl: pubHostedUrl,
-    experimental: experimental,
+    experiments: experiments,
     fn,
   );
 }

app/lib/tool/test_profile/importer.dart

@@ -45,7 +45,7 @@ Future<void> importProfile({
   // create publishers
   for (final p in profile.publishers) {
     final firstMemberEmail = p.members.first.email;
-    await withFakeAuthHttpPubApiClient(
+    await withFakeAuthRetryPubApiClient(
       email: firstMemberEmail,
       scopes: [webmasterScope],
       pubHostedUrl: pubHostedUrl,
@@ -94,8 +94,8 @@ Future<void> importProfile({
           await source.getArchiveBytes(rv.package, rv.version);
       bytes = await _mayCleanupTarModeBits(bytes);
       try {
-        await withHttpPubApiClient(
-          bearerToken: createFakeAuthTokenForEmail(uploaderEmail,
+        await withRetryPubApiClient(
+          authToken: createFakeAuthTokenForEmail(uploaderEmail,
               audience: activeConfiguration.pubClientAudience),
           pubHostedUrl: pubHostedUrl,
           (client) => client.uploadPackageBytes(bytes),
@@ -120,7 +120,7 @@ Future<void> importProfile({
     final packageName = testPackage.name;
     final activeEmail = lastActiveUploaderEmails[packageName];
 
-    await withFakeAuthHttpPubApiClient(
+    await withFakeAuthRetryPubApiClient(
       email: activeEmail!,
       pubHostedUrl: pubHostedUrl,
       (client) async {
@@ -151,8 +151,8 @@ Future<void> importProfile({
     );
 
     if (testPackage.isFlutterFavorite ?? false) {
-      await withHttpPubApiClient(
-        bearerToken:
+      await withRetryPubApiClient(
+        authToken:
             createFakeServiceAccountToken(email: adminUserEmail ?? activeEmail),
         pubHostedUrl: pubHostedUrl,
         (client) async {
@@ -170,7 +170,7 @@ Future<void> importProfile({
   final createLikeCounts = <String, int>{};
   // create users
   for (final u in profile.users) {
-    await withFakeAuthHttpPubApiClient(
+    await withFakeAuthRetryPubApiClient(
       email: u.email,
       pubHostedUrl: pubHostedUrl,
       (client) async {
@@ -194,7 +194,7 @@ Future<void> importProfile({
 
       for (var i = 0; i < likesMissing; i++) {
         final userEmail = '[email protected]';
-        await withFakeAuthHttpPubApiClient(
+        await withFakeAuthRetryPubApiClient(
           email: userEmail,
           pubHostedUrl: pubHostedUrl,
           (client) async {

app/lib/tool/utils/pub_api_client.dart

@@ -96,22 +96,32 @@ class _FakeTimeClient implements http.Client {
 /// resources are freed after the callback finishes.
 /// The callback [fn] is retried on the transient network errors.
 ///
-/// If [bearerToken], [sessionId] or [csrfToken] is specified, the corresponding
+/// If [authToken], [sessionId] or [csrfToken] is specified, the corresponding
 /// HTTP header will be sent alongside the request.
-Future<R> withHttpPubApiClient<R>(
+Future<R> withRetryPubApiClient<R>(
+  /// The callback function that may be retried on transient errors.
   Future<R> Function(PubApiClient client) fn, {
-  String? bearerToken,
+  /// The token to use as the `Authorization` header in the format of `Bearer <token>`.
+  String? authToken,
+
+  /// The session id that will be part of the session cookie.
   String? sessionId,
+
+  /// The CSRF token that will be the value of the CSRF header (`x-pub-csrf-token`).
   String? csrfToken,
+
+  /// The base URL of the pub server.
   String? pubHostedUrl,
-  Set<String>? experimental,
+
+  /// The enabled experiments that will be part of the experimental cookie.
+  Set<String>? experiments,
 }) async {
   final httpClient = httpClientWithAuthorization(
-    tokenProvider: () async => bearerToken,
+    tokenProvider: () async => authToken,
     sessionIdProvider: () async => sessionId,
     csrfTokenProvider: () async => csrfToken,
     cookieProvider: () async => {
-      if (experimental != null) experimentalCookieName: experimental.join(':'),
+      if (experiments != null) experimentalCookieName: experiments.join(':'),
     },
     client: http.Client(),
   );

app/test/account/consent_backend_test.dart

@@ -25,7 +25,7 @@ void main() {
   group('Uploader invite', () {
     Future<String?> inviteUploader(
         {String adminEmail = '[email protected]'}) async {
-      await withFakeAuthHttpPubApiClient(
+      await withFakeAuthRetryPubApiClient(
         email: adminEmail,
         pubHostedUrl: activeConfiguration.primarySiteUri.toString(),
         (client) async {
@@ -309,7 +309,7 @@ void main() {
 
   group('Sanity check', () {
     testWithProfile('consent parameter length', fn: () async {
-      await withFakeAuthHttpPubApiClient(email: adminAtPubDevEmail, (c) async {
+      await withFakeAuthRetryPubApiClient(email: adminAtPubDevEmail, (c) async {
         await expectApiException(
           c.consentInfo('abcd' * 500),
           status: 400,

app/test/admin/exported_api_sync_test.dart

@@ -19,8 +19,8 @@ void main() {
       List<String>? packages,
       bool forceWrite = false,
     }) async {
-      await withHttpPubApiClient(
-        bearerToken: siteAdminToken,
+      await withRetryPubApiClient(
+        authToken: siteAdminToken,
         (api) async {
           await api.adminInvokeAction(
             'exported-api-sync',

app/test/admin/moderate_package_test.dart

@@ -33,7 +33,7 @@ import '../shared/test_services.dart';
 void main() {
   group('Moderate package', () {
     Future<ModerationCase> _report(String package) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(ReportForm(
             email: '[email protected]',

app/test/admin/moderate_package_version_test.dart

@@ -33,7 +33,7 @@ import '../shared/test_services.dart';
 void main() {
   group('Moderate package version', () {
     Future<ModerationCase> _report(String package, String version) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(ReportForm(
             email: '[email protected]',

app/test/admin/moderate_publisher_test.dart

@@ -24,7 +24,7 @@ import '../shared/test_services.dart';
 void main() {
   group('Moderate Publisher', () {
     Future<ModerationCase> _report(String publisherId) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(ReportForm(
             email: '[email protected]',

app/test/admin/moderate_user_test.dart

@@ -28,7 +28,7 @@ import '../shared/test_services.dart';
 void main() {
   group('Moderate User', () {
     Future<ModerationCase> _report(String package) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(account_api.ReportForm(
             email: '[email protected]',

app/test/admin/moderation_case_resolve_test.dart

@@ -18,7 +18,7 @@ void main() {
       String? appealCaseId,
       required bool? apply,
     }) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(ReportForm(
             email: '[email protected]',

app/test/admin/moderation_transparency_metrics_test.dart

@@ -21,7 +21,7 @@ void main() {
       String? email,
       String? caseId,
     }) async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await client.postReport(account_api.ReportForm(
             email: email ?? '[email protected]',

app/test/frontend/handlers/report_test.dart

@@ -78,7 +78,7 @@ void main() {
 
   group('Report API test', () {
     testWithProfile('unauthenticated email missing', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -97,7 +97,7 @@ void main() {
       await withFakeAuthRequestContext('[email protected]', () async {
         final sessionId = requestContext.sessionData?.sessionId;
         final csrfToken = requestContext.csrfToken;
-        await withHttpPubApiClient(
+        await withRetryPubApiClient(
           sessionId: sessionId,
           csrfToken: csrfToken,
           (client) async {
@@ -117,7 +117,7 @@ void main() {
     });
 
     testWithProfile('subject missing', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -134,7 +134,7 @@ void main() {
     });
 
     testWithProfile('subject is invalid', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -152,7 +152,7 @@ void main() {
     });
 
     testWithProfile('package missing', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -170,7 +170,7 @@ void main() {
     });
 
     testWithProfile('version missing', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -188,7 +188,7 @@ void main() {
     });
 
     testWithProfile('publisher missing', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -209,7 +209,7 @@ void main() {
       await withFakeAuthRequestContext('[email protected]', () async {
         final sessionId = requestContext.sessionData?.sessionId;
         final csrfToken = requestContext.csrfToken;
-        await withHttpPubApiClient(
+        await withRetryPubApiClient(
           sessionId: sessionId,
           csrfToken: csrfToken,
           (client) async {
@@ -229,7 +229,7 @@ void main() {
     });
 
     testWithProfile('unauthenticated report success', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           final msg = await client.postReport(ReportForm(
             email: '[email protected]',
@@ -256,7 +256,7 @@ void main() {
       await withFakeAuthRequestContext('[email protected]', () async {
         final sessionId = requestContext.sessionData?.sessionId;
         final csrfToken = requestContext.csrfToken;
-        await withHttpPubApiClient(
+        await withRetryPubApiClient(
           sessionId: sessionId,
           csrfToken: csrfToken,
           (client) async {
@@ -307,7 +307,7 @@ void main() {
     }
 
     testWithProfile('failure: case does not exists', fn: () async {
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -326,7 +326,7 @@ void main() {
 
     testWithProfile('failure: case is not closed', fn: () async {
       await _prepareApplied(status: ModerationStatus.pending);
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -345,7 +345,7 @@ void main() {
 
     testWithProfile('failure: subject is not on the case', fn: () async {
       await _prepareApplied();
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           await expectApiException(
             client.postReport(ReportForm(
@@ -370,7 +370,7 @@ void main() {
       );
 
       // first report: success
-      await withHttpPubApiClient(
+      await withRetryPubApiClient(
         (client) async {
           final msg = await client.postReport(ReportForm(
             email: '[email protected]',
@@ -400,7 +400,7 @@ void main() {
       );
 
       // second report: rejected
-      await withHttpPubApiClient((client) async {
+      await withRetryPubApiClient((client) async {
         await expectApiException(
           client.postReport(ReportForm(
             email: '[email protected]',
@@ -421,7 +421,7 @@ void main() {
         logSubject: 'package-version:oxygen/1.2.0',
       );
 
-      await withFakeAuthHttpPubApiClient(
+      await withFakeAuthRetryPubApiClient(
         email: '[email protected]',
         (client) async {
           final msg = await client.postReport(ReportForm(