feat(postgrest): configurable auto-retry and request timeout

packages/gotrue/lib/src/gotrue_oauth_api.dart

@@ -56,7 +56,7 @@ class OAuthGrant {
   factory OAuthGrant.fromJson(Map<String, dynamic> json) {
     return OAuthGrant(
       client: OAuthAuthorizedClient.fromJson(json['client']),
-      scopes: (json['scopes'] as List?)?.cast<String>() ?? const <String>[],
+      scopes: (json['scopes'] as List?)?.cast() ?? const [],
       grantedAt: DateTime.parse(json['granted_at'] as String),
     );
   }

packages/postgrest/lib/src/postgrest.dart

@@ -7,13 +7,19 @@ import 'package:yet_another_json_isolate/yet_another_json_isolate.dart';
 
 /// A PostgREST api client written in Dartlang. The goal of this library is to make an "ORM-like" restful interface.
 class PostgrestClient {
+  /// HTTP status codes that trigger an automatic retry by default.
+  static const Set<int> defaultRetryableStatusCodes = {503, 520};
+
   final String url;
   final Map<String, String> headers;
   final String? _schema;
   final Client? httpClient;
   final YAJsonIsolate _isolate;
   final bool _hasCustomIsolate;
   final bool retryEnabled;
+  final int retryCount;
+  final Set<int> retryableStatusCodes;
+  final Duration? requestTimeout;
   final Duration Function(int attempt)? _retryDelay;
   final _log = Logger('supabase.postgrest');
 
@@ -30,21 +36,46 @@ class PostgrestClient {
   /// [isolate] is optional and can be used to provide a custom isolate, which is used for heavy json computation
   ///
   /// [retryEnabled] controls whether automatic retries are performed for GET and
-  /// HEAD requests that fail with HTTP 503, HTTP 520, or a network error. Defaults to `true`.
-  /// Use [PostgrestBuilder.retry] to override this per request.
+  /// HEAD requests that fail with a retryable status code or a network error.
+  /// Defaults to `true`. Use [PostgrestBuilder.retry] to override this per request.
+  ///
+  /// [retryCount] is the number of retry attempts made for a retryable request
+  /// before giving up. Defaults to `3`.
+  ///
+  /// [retryableStatusCodes] are the HTTP status codes that trigger a retry.
+  /// Defaults to `{503, 520}`.
+  ///
+  /// [requestTimeout] optionally bounds how long a single request attempt may
+  /// take. It is implemented on top of the abort mechanism, so it actually
+  /// cancels a stalled attempt instead of leaving it running. A timed-out
+  /// attempt is retried like any other failure, and a [TimeoutException] is
+  /// thrown once the retries are exhausted. When `null` (the default) no
+  /// timeout is applied. Use [PostgrestBuilder.abortSignal] to cancel a request
+  /// outright, which stops retrying immediately.
   PostgrestClient(
     this.url, {
     Map<String, String>? headers,
     String? schema,
     this.httpClient,
     YAJsonIsolate? isolate,
     this.retryEnabled = true,
+    this.retryCount = 3,
+    Set<int> retryableStatusCodes = defaultRetryableStatusCodes,
+    this.requestTimeout,
     @visibleForTesting Duration Function(int attempt)? retryDelay,
-  }) : _schema = schema,
+  }) : retryableStatusCodes = Set.unmodifiable(retryableStatusCodes),
+       _schema = schema,
        headers = {...defaultHeaders, ...?headers},
        _isolate = isolate ?? (YAJsonIsolate()..initialize()),
        _hasCustomIsolate = isolate != null,
        _retryDelay = retryDelay {
+    if (retryCount < 0) {
+      throw ArgumentError.value(
+        retryCount,
+        'retryCount',
+        'must not be negative',
+      );
+    }
     _log.config('Initialize PostgrestClient with url: $url, schema: $_schema');
     _log.finest('Initialize with headers: $headers');
   }
@@ -76,6 +107,9 @@ class PostgrestClient {
       httpClient: httpClient,
       isolate: _isolate,
       retryEnabled: retryEnabled,
+      retryCount: retryCount,
+      retryableStatusCodes: retryableStatusCodes,
+      requestTimeout: requestTimeout,
       retryDelay: _retryDelay,
     );
   }
@@ -91,6 +125,9 @@ class PostgrestClient {
       httpClient: httpClient,
       isolate: _isolate,
       retryEnabled: retryEnabled,
+      retryCount: retryCount,
+      retryableStatusCodes: retryableStatusCodes,
+      requestTimeout: requestTimeout,
       retryDelay: _retryDelay,
     );
   }
@@ -123,6 +160,9 @@ class PostgrestClient {
       httpClient: httpClient,
       isolate: _isolate,
       retryEnabled: retryEnabled,
+      retryCount: retryCount,
+      retryableStatusCodes: retryableStatusCodes,
+      requestTimeout: requestTimeout,
       retryDelay: _retryDelay,
     ).rpc(params, get);
   }