
# 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](../spring-boot-starter-feign/index.md) already does all but the two headers, so an `@EdgeFunctions` interface is a Feign client with them added.

## Example

```dart
@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();
}
```

```dart
final result = await functions.sendInvite(Invite(email: 'ada@example.com'));
// 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; `FeignException` and its subclasses. See [Methods](../spring-boot-starter-feign/methods.md) and [Errors and retries](../spring-boot-starter-feign/errors-and-retries.md).
- **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 `@EdgeFunction`** stops 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](storage.md). See [Methods](../spring-boot-starter-feign/methods.md) for what each type does with errors and empty bodies.

## The key and the token

Every call gets `apikey` and `Authorization: Bearer` from [`SupabaseCredentials`](credentials.md), 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:

```properties
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 it `spring.supabase.functions.timeout`; without that `spring.supabase.timeout` (30 s).
- **It never follows a redirect**, whatever `follow-redirects` says: a redirect could carry the key and the token to another host.
- **`apikey`** is among the headers the client's logs hide.
- **The region:** `spring.supabase.functions.region` is sent as the `x-region` header.
- **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.

## See also

- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [Feign configuration](../spring-boot-starter-feign/configuration.md)
- [Who a call is made as](credentials.md)
