feat(functions): add request cancellation to invoke via abortSignal (#1593)

## Summary

Adds request cancellation to `FunctionsClient.invoke`, closing the gap
versus the canonical compliance matrix. `invoke` now accepts an optional
`abortSignal` Future; completing it cancels the in-flight HTTP request
and throws `RequestAbortedException`, mirroring how the database client
exposes cancellation through `PostgrestBuilder.abortSignal`.

This is done idiomatically with the `http` package's
`AbortableRequest`/`AbortableMultipartRequest` (wiring `abortTrigger`),
so it works for both regular and multipart invocations.
`RequestAbortedException` is re-exported from the package so callers can
catch it.

A per-invocation timeout is now expressible as `invoke(..., abortSignal:
Future.delayed(duration))`, so the previously `not_applicable`
`functions.invocation.timeout` note is updated accordingly.

## Outcome

**implemented**

## Reference

Mirrors the existing Dart
`database.using_modifiers.request_cancellation` idiom
(`PostgrestBuilder.abortSignal`).

## Compliance matrix

- `functions.invocation.request_cancellation` → **implemented** (symbol
`FunctionsClient.invoke` registered)

## Tests

- Aborting an in-flight request throws `RequestAbortedException`
- Aborting a multipart request throws `RequestAbortedException`
- A never-firing signal lets the request complete normally

SDK-1310

Author: spydon

packages/functions_client/lib/functions_client.dart

@@ -1,7 +1,8 @@
 /// A dart client library for Supabase Edge Functions.
 library;
 
-export 'package:http/http.dart' show ByteStream, MultipartFile;
+export 'package:http/http.dart'
+    show ByteStream, MultipartFile, RequestAbortedException;
 
 export 'src/functions_client.dart';
 export 'src/types.dart';

packages/functions_client/lib/src/functions_client.dart

@@ -66,6 +66,32 @@ class FunctionsClient {
   /// [region] optionally specify the region to invoke the function in.
   /// When specified, adds both `x-region` header and `forceFunctionRegion` query parameter.
   ///
+  /// [abortSignal] cancels the in-flight request when the provided [Future]
+  /// completes. It must not complete with an error. On abort, a
+  /// [RequestAbortedException] is thrown. This is useful for cancelling a
+  /// request in response to an event or for setting a request timeout:
+  ///
+  /// ```dart
+  /// // Event based
+  /// final abortSignal = Completer<void>();
+  /// abortSignal.complete(); // Call in some event handler to abort the request
+  ///
+  /// try {
+  ///   final response = await supabase.functions.invoke(
+  ///     'hello-world',
+  ///     abortSignal: abortSignal.future,
+  ///   );
+  /// } on RequestAbortedException catch (error) {
+  ///   print('Request was aborted: $error');
+  /// }
+  ///
+  /// // Timer based
+  /// final response = await supabase.functions.invoke(
+  ///   'hello-world',
+  ///   abortSignal: Future.delayed(Duration(seconds: 5)),
+  /// );
+  /// ```
+  ///
   /// ```dart
   /// // Call a standard function
   /// final response = await supabase.functions.invoke('hello-world');
@@ -98,6 +124,7 @@ class FunctionsClient {
     Map<String, dynamic>? queryParameters,
     HttpMethod method = HttpMethod.post,
     String? region,
+    Future<void>? abortSignal,
   }) async {
     final effectiveRegion = region ?? _region;
 
@@ -137,11 +164,20 @@ class FunctionsClient {
       );
       final fields = (body as Map?)?.cast<String, String>();
 
-      request = http.MultipartRequest(method.name.toUpperCase(), uri)
-        ..fields.addAll(fields ?? {})
-        ..files.addAll(files);
+      request =
+          http.AbortableMultipartRequest(
+              method.name.toUpperCase(),
+              uri,
+              abortTrigger: abortSignal,
+            )
+            ..fields.addAll(fields ?? {})
+            ..files.addAll(files);
     } else {
-      final bodyRequest = http.Request(method.name.toUpperCase(), uri);
+      final bodyRequest = http.AbortableRequest(
+        method.name.toUpperCase(),
+        uri,
+        abortTrigger: abortSignal,
+      );
 
       if (body == null) {
         // No body to set
@@ -165,6 +201,8 @@ class FunctionsClient {
     final http.StreamedResponse response;
     try {
       response = await (_httpClient?.send(request) ?? request.send());
+    } on http.RequestAbortedException {
+      rethrow;
     } catch (error) {
       throw FunctionsFetchException(details: error);
     }

packages/functions_client/test/custom_http_client.dart

@@ -14,7 +14,22 @@ class CustomHttpClient extends BaseClient {
     receivedRequests.add(request);
     request.finalize();
 
-    if (request.url.path.endsWith('network-error')) {
+    if (request.url.path.endsWith('slow')) {
+      // Hangs until the request is aborted, mirroring how a real client
+      // surfaces abortion. Without an abort trigger it responds immediately so
+      // non-abort tests don't stall.
+      final abortTrigger = request is Abortable ? request.abortTrigger : null;
+      if (abortTrigger != null) {
+        await abortTrigger;
+        throw RequestAbortedException(request.url);
+      }
+      return StreamedResponse(
+        Stream.value(utf8.encode(jsonEncode({"key": "Hello World"}))),
+        200,
+        request: request,
+        headers: {"Content-Type": "application/json"},
+      );
+    } else if (request.url.path.endsWith('network-error')) {
       // Simulate a transport failure before any response is received.
       throw ClientException('Connection failed', request.url);
     } else if (request.url.path.endsWith('relay-error')) {

packages/functions_client/test/functions_dart_test.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';
 import 'dart:typed_data';
 
@@ -530,6 +531,47 @@ void main() {
       });
     });
 
+    group('Request cancellation', () {
+      test('aborts an in-flight request via abortSignal', () async {
+        final abortSignal = Completer<void>();
+        Timer(const Duration(milliseconds: 50), abortSignal.complete);
+
+        await expectLater(
+          functionsCustomHttpClient.invoke(
+            'slow',
+            abortSignal: abortSignal.future,
+          ),
+          throwsA(isA<RequestAbortedException>()),
+        );
+      });
+
+      test('aborts a multipart request via abortSignal', () async {
+        final abortSignal = Completer<void>();
+        Timer(const Duration(milliseconds: 50), abortSignal.complete);
+
+        await expectLater(
+          functionsCustomHttpClient.invoke(
+            'slow',
+            files: [MultipartFile.fromString('file', 'content')],
+            abortSignal: abortSignal.future,
+          ),
+          throwsA(isA<RequestAbortedException>()),
+        );
+      });
+
+      test('completes normally when the signal never fires', () async {
+        final abortSignal = Completer<void>();
+
+        final response = await functionsCustomHttpClient.invoke(
+          'function',
+          abortSignal: abortSignal.future,
+        );
+
+        expect(response.status, 200);
+        expect(response.data, {'key': 'Hello World'});
+      });
+    });
+
     group('Response content types', () {
       test('handles application/octet-stream response', () async {
         final response = await functionsCustomHttpClient.invoke('binary');

sdk-compliance.yaml

@@ -695,8 +695,11 @@ features:
   functions.invocation.region_selection: implemented
   functions.invocation.timeout:
     status: not_applicable
-    note: "A per-invocation timeout would only wrap the returned Future and cannot abort the in-flight request, so a caller could still see the function succeed after a timeout fires. That is identical to the caller applying Future.timeout themselves, so exposing it as an option adds no capability and would be misleading."
-  functions.invocation.request_cancellation: not_implemented
+    note: "A genuine timeout that aborts the in-flight request is already expressible as `invoke(..., abortSignal: Future.delayed(duration))` via functions.invocation.request_cancellation, so a dedicated timeout option would add no capability over that."
+  functions.invocation.request_cancellation:
+    status: implemented
+    symbols:
+      - FunctionsClient.invoke
 
   # client
   client.authentication_integration.third_party_auth: implemented