Edge Functions

An @EdgeFunctions interface describes the Edge Functions of the project, one method per function. The generator writes the bean, and calling a method sends the request with the project's key and the current user's token.

Why

An Edge Function is an HTTP endpoint under /functions/v1. Calling it by hand means the address, the apikey header, the user's token, JSON both ways and a status to check. The Feign starter already does all but the two headers, so an @EdgeFunctions interface is a Feign client with them added.

Example

@Introspected()
class Invite {
  Invite({required this.email});

  final String email;
}

@Introspected()
class InviteResult {
  InviteResult({required this.id});

  final String id;
}

@EdgeFunctions()
abstract interface class Functions {
  @EdgeFunction('send-invite')
  Future<InviteResult> sendInvite(@RequestBody() Invite invite);

  @EdgeFunction('stats', method: HttpMethod.get)
  Future<Map<String, Object?>> stats(@RequestParam('from') String from);

  @EdgeFunction('reports/{year}', method: HttpMethod.get)
  Future<String> report(@PathVariable() int year);

  @EdgeFunction('progress', method: HttpMethod.get)
  EventStream<Map<String, Object?>> progress();

  @EdgeFunction('export', method: HttpMethod.get)
  Future<Uint8List> export();

  @EdgeFunction('export', method: HttpMethod.get)
  Stream<List<int>> exportStream();
}
final result = await functions.sendInvite(Invite(email: '[email protected]'));
// POST https://abcd.supabase.co/functions/v1/send-invite
// apikey: <anon key>        Authorization: Bearer <the user's token>

The annotations

Annotation Meaning
@EdgeFunctions(name:, qualifiers:, primary:) Marks the interface. name is the Feign client's name, supabase-functions by default: its settings and its logs.
@EdgeFunction(name, method:, headers:, produces:, consumes:) Calls the function name, with POST unless method says otherwise.

What a function may answer

The method returns The answer is
Future<T> (a class, a Map, a List), Future<String> JSON, or text.
Future<Uint8List> A file, read whole before the call returns.
EventStream<T>, Stream<T> Server-sent events, as they arrive.
Stream<List<int>> The body as it arrives, whatever its content type: a large file, or chunks that are not events.
Future<ResponseEntity<T>> The status, the headers and the body.

progress above is a function that sends events, export a file. export and exportStream call the same function: the first returns when the whole file is here, the second gives each chunk as it comes, and makes one request for each listener.

A request body is read whole before it is sent: a function cannot be given a stream, and a large upload belongs in Storage. See Methods for what each type does with errors and empty bodies.

The key and the token

Every call gets apikey and Authorization: Bearer from SupabaseCredentials, set last: nothing else decides them, not a RequestInterceptor of the application and not a default header. So a function sees the same user as the repositories and Storage, and inside asServiceRole it is called as the service role.

The application's own RequestInterceptor beans run before, as for any Feign client. The starter's interceptor is not one of them: it does not run for the application's other Feign clients.

Settings

The client takes the settings of the Feign client of its name:

spring.feign.client.config.supabase-functions.read-timeout=20s
spring.feign.client.config.supabase-functions.logger-level=basic

The properties

Key Type Default Meaning
spring.supabase.functions.region String none The region the functions run in (the x-region header); the nearest one when not set.
spring.supabase.functions.timeout Duration spring.supabase.timeout How long a function may take.

In Spring (Java)

Spring Cloud OpenFeign's @FeignClient with a RequestInterceptor for the token. @EdgeFunctions is that pair as one annotation.

See also