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. |
- Parameters, results and errors are Feign's:
@RequestBody,@RequestParam,@RequestHeader,@PathVariable; the results are listed below;FeignExceptionand its subclasses. See Methods and Errors and retries. - A function's name takes
${property}from the configuration. A part that changes per call is a{name}filled by a@PathVariable()parameter. It takes no SpEL: a function's name is fixed where it is deployed. - A method without
@EdgeFunctionstops the start, with every such method in one message.
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 timeout of a call is the client's
call-timeout; without itspring.supabase.functions.timeout; without thatspring.supabase.timeout(30 s). - It never follows a redirect, whatever
follow-redirectssays: a redirect could carry the key and the token to another host. apikeyis among the headers the client's logs hide.- The region:
spring.supabase.functions.regionis sent as thex-regionheader. - An observation per call, named
supabase.functions, with the function's name.
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.