supabase · spydon · Aug 10, 2026 · coderabbitai · Aug 11, 2026
@@ -326,3 +326,69 @@ unaffected. For `functions.invoke`, two things changed:
   (3 to 5). This one is not a compile error, so replace any persisted `index` with `name`.
 
 The enum also exposes `value`, the uppercase wire form, in place of `method.name.toUpperCase()`.
+
+### Core types declare their subtyping intent with class modifiers
+
+The core public types now carry Dart 3 class modifiers that state whether they are meant to be
+extended, implemented, or neither. Nothing about their behaviour changed, but subtyping them in a
+way the modifier disallows is now a compile error.
+
+The clients and the request builders are `interface class`, so they can still be implemented (this
+is what `mockito` and `mocktail` need) but no longer extended:
+
+| Type | Modifier |
+| --- | --- |
+| `SupabaseClient` | `interface class` |
+| `GoTrueClient` | `interface class` |
+| `PostgrestClient` | `interface class` |
+| `PostgrestBuilder` | `interface class` |
+| `RealtimeClient` | `interface class` |
+| `FunctionsClient` | `interface class` |
+| `SupabaseStorageClient` | `interface class` |
+| `StorageFileApi` | `interface class` |
+
+If you were extending one of these to change its behaviour, wrap it instead:
+
+```dart
+// Before
+class LoggingSupabaseClient extends SupabaseClient {
+  LoggingSupabaseClient(super.url, super.key);
+}
+
+// After
+class LoggingSupabaseClient {
+  LoggingSupabaseClient(this._inner);
+
+  final SupabaseClient _inner;
+
+  SupabaseQueryBuilder from(String table) {
+    print('from($table)');
+    return _inner.from(table);
+  }
+}
+```
+
+Mocks are unaffected, because `implements` is still allowed:
+
+```dart
+// Still compiles
+class MockSupabaseClient extends Mock implements SupabaseClient {}
+```
+
+The two storage abstractions you are meant to plug your own implementation into are
+`abstract interface class`, so they must be implemented rather than extended. Both declare only
+abstract members, so this is a one-word change at the use site:
+
+```dart
+// Before
+class MyLocalStorage extends LocalStorage { /* ... */ }
+class MyPkceStorage extends GotrueAsyncStorage { /* ... */ }
+
+// After
+class MyLocalStorage implements LocalStorage { /* ... */ }
+class MyPkceStorage implements GotrueAsyncStorage { /* ... */ }
+```
+
+Finally, `AuthState` is a `final class`. It is a plain value carrying an `AuthChangeEvent` and a
+`Session`, and `AuthChangeEvent` is already an enum, so switching over auth state changes is
+unchanged.
@@ -10,7 +10,7 @@ import 'package:logging/logging.dart';
 import 'package:supabase_common/supabase_common.dart';
 import 'package:yet_another_json_isolate/yet_another_json_isolate.dart';
 
-class FunctionsClient {
+interface class FunctionsClient {
   final String _url;
   final Map<String, String> _headers;
   final http.Client? _httpClient;

@@ -11,7 +11,7 @@ import 'package:meta/meta.dart';
 import 'package:supabase_common/supabase_common.dart';
 
 @internal
-class GotrueFetch {
+final class GotrueFetch {
   final Client? httpClient;
 
   const GotrueFetch([this.httpClient]);

@@ -49,7 +49,7 @@ class _SessionState {
 ///
 /// Set [flowType] to [AuthFlowType.implicit] to perform old implicit auth flow.
 /// {@endtemplate}
-class GoTrueClient {
+interface class GoTrueClient {
   /// Namespace for the GoTrue API methods. These can be used for example to get
   /// a user from a JWT in a server environment or reset a user's password.
   late final GoTrueAdminApi admin;

@@ -2,7 +2,7 @@ import 'package:gotrue/src/constants.dart';
 import 'package:gotrue/src/types/session.dart';
 import 'package:gotrue/src/types/sign_out_reason.dart';
 
-class AuthState {
+final class AuthState {
   final AuthChangeEvent event;
   final Session? session;
 

@@ -1,5 +1,5 @@
 /// Interface to provide async storage to store pkce tokens.
-abstract class GotrueAsyncStorage {
+abstract interface class GotrueAsyncStorage {
   const GotrueAsyncStorage();
 
   /// Retrieves an item asynchronously from the storage with the key.

@@ -81,7 +81,7 @@ const sessionDataUserId = '4d2583da-8de4-49d3-9cd1-37a9a74f55bd';
   return (accessToken: accessToken, sessionString: sessionString);
 }
 
-class TestAsyncStorage extends GotrueAsyncStorage {
+class TestAsyncStorage implements GotrueAsyncStorage {
   final Map<String, String> _map = {};
   @override
   Future<String?> getItem({required String key}) async {

@@ -7,7 +7,7 @@ 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 {
+interface class PostgrestClient {
   /// HTTP status codes that trigger an automatic retry by default.
   static const Set<int> defaultRetryableStatusCodes = {503, 520};
 

@@ -134,7 +134,7 @@ String? _emptyPreferAsNull(String? prefer) =>
 /// When using [_converter], [R] is the input and [S] is the output
 /// Otherwise [S] and [R] are the same
 @immutable
-class PostgrestBuilder<T, S, R> implements Future<T> {
+interface class PostgrestBuilder<T, S, R> implements Future<T> {
   final _RequestConfig _config;
   final PostgrestConverter<S, R>? _converter;
   final _log = Logger('supabase.postgrest');

@@ -97,7 +97,7 @@ enum RealtimeHeartbeatStatus {
 /// **Platform notes:**
 /// - Works on all Dart platforms (Flutter mobile/desktop, web, server).
 /// - On web, the underlying [WebSocketChannel] uses the browser WebSocket API.
-class RealtimeClient {
+interface class RealtimeClient {
   String? accessToken;
   List<RealtimeChannel> channels = [];
   final String endPoint;

@@ -3,12 +3,15 @@ import 'dart:convert';
 import 'dart:io';
 import 'dart:typed_data';
 
+import 'package:mocktail/mocktail.dart';
 import 'package:realtime_client/realtime_client.dart';
 import 'package:realtime_client/src/constants.dart';
 import 'package:realtime_client/src/push.dart';
 import 'package:realtime_client/src/types.dart';
 import 'package:test/test.dart';
 
+const _expiredToken = 'expired-token';
+
 void main() {
   late RealtimeClient socket;
   late RealtimeChannel channel;
@@ -132,15 +135,13 @@ void main() {
     // https://github.com/supabase/supabase-flutter/issues/1363.
     test("swallows FormatException with 'InvalidJWTToken' from setAuth and "
         "still emits 'subscribed' status", () async {
-      final throwingSocket = _SetAuthThrowingSocket(
-        '/socket',
-        thrown: const FormatException(
+      final throwingSocket = _setAuthThrowingSocket(
+        const FormatException(
           'InvalidJWTToken: Invalid value for JWT claim "exp" with value 0',
         ),
       );
-      throwingSocket.accessToken = 'expired-token';
 
-      final localChannel = throwingSocket.channel('topic');
+      final localChannel = RealtimeChannel('topic', throwingSocket);
 
       RealtimeSubscribeStatus? status;
       localChannel.subscribe((s, _) => status = s);
@@ -150,7 +151,7 @@ void main() {
       await Future<void>.value();
       await Future<void>.value();
 
-      expect(throwingSocket.setAuthCalls, 1);
+      verify(() => throwingSocket.setAuth(_expiredToken)).called(1);
       expect(
         status,
         RealtimeSubscribeStatus.subscribed,
@@ -162,13 +163,11 @@ void main() {
 
     test("non-InvalidJWTToken FormatExceptions from setAuth still abort the "
         "rejoin handler", () async {
-      final throwingSocket = _SetAuthThrowingSocket(
-        '/socket',
-        thrown: const FormatException('some other parsing failure'),
+      final throwingSocket = _setAuthThrowingSocket(
+        const FormatException('some other parsing failure'),
       );
-      throwingSocket.accessToken = 'some-token';
 
-      final localChannel = throwingSocket.channel('topic');
+      final localChannel = RealtimeChannel('topic', throwingSocket);
 
       RealtimeSubscribeStatus? status;
       // Use runZonedGuarded so the rethrown async error does not pollute
@@ -185,7 +184,7 @@ void main() {
         },
       );
 
-      expect(throwingSocket.setAuthCalls, 1);
+      verify(() => throwingSocket.setAuth(_expiredToken)).called(1);
       expect(
         status,
         isNull,
@@ -1365,23 +1364,21 @@ void main() {
   });
 }
 
-class _SetAuthThrowingSocket extends RealtimeClient {
-  _SetAuthThrowingSocket(super.endPoint, {required this.thrown});
-
-  final FormatException thrown;
-  int setAuthCalls = 0;
-
-  @override
-  Future<void> connect() async {
-    // No-op: avoid opening a real WebSocket so async transport failures
-    // don't leak into the test runner zone.
-  }
-
-  @override
-  Future<void> setAuth(String? token) async {
-    setAuthCalls++;
-    throw thrown;
-  }
+class _MockSocket extends Mock implements RealtimeClient {}
+
+/// A socket whose [RealtimeClient.setAuth] throws [thrown]. It reports itself
+/// as already connected so no real WebSocket is opened and async transport
+/// failures don't leak into the test runner zone.
+_MockSocket _setAuthThrowingSocket(FormatException thrown) {
+  final socket = _MockSocket();
+  when(() => socket.endPoint).thenReturn('/socket');
+  when(() => socket.timeout).thenReturn(Constants.defaultTimeout);
+  when(() => socket.reconnectAfterMs).thenReturn((_) => 0);
+  when(() => socket.isConnected).thenReturn(true);
+  when(() => socket.accessToken).thenReturn(_expiredToken);
+  when(() => socket.makeRef()).thenReturn('1');
+  when(() => socket.setAuth(any())).thenThrow(thrown);
+  return socket;
 }
 
 class _OptsCapturingChannel extends RealtimeChannel {

@@ -595,23 +595,14 @@ void main() {
       final mockedChannel2 = MockChannel();
       when(() => mockedChannel2.joinRef).thenReturn('2');
 
-      const tTopic1 = 'topic-1';
-      const tTopic2 = 'topic-2';
+      final mockedSocket = RealtimeClient(socketEndpoint);
+      mockedSocket.channels.addAll([mockedChannel1, mockedChannel2]);
 
-      final mockedSocket = SocketWithMockedChannel(socketEndpoint);
-      mockedSocket.mockedChannelLooker.addAll({
-        tTopic1: mockedChannel1,
-        tTopic2: mockedChannel2,
-      });
-
-      final channel1 = mockedSocket.channel(tTopic1);
-      final channel2 = mockedSocket.channel(tTopic2);
-
-      mockedSocket.remove(channel1);
+      mockedSocket.remove(mockedChannel1);
       expect(mockedSocket.channels, hasLength(1));
 
       final foundChannel = mockedSocket.channels[0];
-      expect(foundChannel, channel2);
+      expect(foundChannel, mockedChannel2);
     });
 
     test('keeps the other channels when none of them have joined', () {
@@ -1090,29 +1081,24 @@ void main() {
           () => mockedChannel2.push(ChannelEvent.accessToken, pushPayload),
         ).thenReturn(MockPush());
 
-        const tTopic1 = 'topic-1';
-        const tTopic2 = 'topic-2';
-
-        final mockedSocket = SocketWithMockedChannel(socketEndpoint);
-        mockedSocket.mockedChannelLooker.addAll({
-          tTopic1: mockedChannel1,
-          tTopic2: mockedChannel2,
-        });
-
-        final channel1 = mockedSocket.channel(tTopic1);
-        final channel2 = mockedSocket.channel(tTopic2);
+        final mockedSocket = RealtimeClient(socketEndpoint);
+        mockedSocket.channels.addAll([mockedChannel1, mockedChannel2]);
 
         await mockedSocket.setAuth(token);
 
         expect(mockedSocket.accessToken, token);
 
-        verify(() => channel1.updateJoinPayload(updateJoinPayload)).called(1);
-        verify(() => channel2.updateJoinPayload(updateJoinPayload)).called(1);
         verify(
-          () => channel1.push(ChannelEvent.accessToken, pushPayload),
+          () => mockedChannel1.updateJoinPayload(updateJoinPayload),
         ).called(1);
         verify(
-          () => channel2.push(ChannelEvent.accessToken, pushPayload),
+          () => mockedChannel2.updateJoinPayload(updateJoinPayload),
+        ).called(1);
+        verify(
+          () => mockedChannel1.push(ChannelEvent.accessToken, pushPayload),
+        ).called(1);
+        verify(
+          () => mockedChannel2.push(ChannelEvent.accessToken, pushPayload),
         ).called(1);
       },
     );
@@ -1143,20 +1129,12 @@ void main() {
           () => mockedChannel3.push(ChannelEvent.accessToken, any()),
         ).thenReturn(MockPush());
 
-        const tTopic1 = 'test-topic1';
-        const tTopic2 = 'test-topic2';
-        const tTopic3 = 'test-topic3';
-
-        final mockedSocket = SocketWithMockedChannel(socketEndpoint);
-        mockedSocket.mockedChannelLooker.addAll({
-          tTopic1: mockedChannel1,
-          tTopic2: mockedChannel2,
-          tTopic3: mockedChannel3,
-        });
-
-        final channel1 = mockedSocket.channel(tTopic1);
-        final channel2 = mockedSocket.channel(tTopic2);
-        final channel3 = mockedSocket.channel(tTopic3);
+        final mockedSocket = RealtimeClient(socketEndpoint);
+        mockedSocket.channels.addAll([
+          mockedChannel1,
+          mockedChannel2,
+          mockedChannel3,
+        ]);
 
         const authToken = 'sb-key';
         final expectedPushPayload = {'access_token': authToken};
@@ -1170,23 +1148,32 @@ void main() {
         expect(mockedSocket.accessToken, authToken);
 
         verify(
-          () => channel1.updateJoinPayload(expectedUpdateJoinPayload),
+          () => mockedChannel1.updateJoinPayload(expectedUpdateJoinPayload),
         ).called(1);
         verify(
-          () => channel2.updateJoinPayload(expectedUpdateJoinPayload),
+          () => mockedChannel2.updateJoinPayload(expectedUpdateJoinPayload),
         ).called(1);
         verify(
-          () => channel3.updateJoinPayload(expectedUpdateJoinPayload),
+          () => mockedChannel3.updateJoinPayload(expectedUpdateJoinPayload),
         ).called(1);
 
         verify(
-          () => channel1.push(ChannelEvent.accessToken, expectedPushPayload),
+          () => mockedChannel1.push(
+            ChannelEvent.accessToken,
+            expectedPushPayload,
+          ),
         ).called(1);
         verifyNever(
-          () => channel2.push(ChannelEvent.accessToken, expectedPushPayload),
+          () => mockedChannel2.push(
+            ChannelEvent.accessToken,
+            expectedPushPayload,
+          ),
         );
         verify(
-          () => channel3.push(ChannelEvent.accessToken, expectedPushPayload),
+          () => mockedChannel3.push(
+            ChannelEvent.accessToken,
+            expectedPushPayload,
+          ),
         ).called(1);
       },
     );