
# Edge Functions

`@EdgeFunctions` のインターフェースは、プロジェクトの Edge Functions を、関数ごとに一つのメソッドで記述します。ジェネレーターが Bean を書き、メソッドを呼び出すと、プロジェクトのキーと現在のユーザーのトークンを付けたリクエストが送られます。

## 使う理由

Edge Function は、`/functions/v1` の下にある HTTP エンドポイントです。手で呼び出すには、アドレス、`apikey` ヘッダー、ユーザーのトークン、双方向の JSON、ステータスの確認が必要です。[Feign スターター](../spring-boot-starter-feign/index.md)は、二つのヘッダー以外をすでに行っています。そこで、`@EdgeFunctions` のインターフェースは、その二つを加えた Feign クライアントになっています。

## 例

```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>
```

## アノテーション

| アノテーション | 意味 |
|---|---|
| `@EdgeFunctions(name:, qualifiers:, primary:)` | インターフェースに付ける。`name` は Feign クライアントの名前で、デフォルトは `supabase-functions`。その設定とログに使われる。 |
| `@EdgeFunction(name, method:, headers:, produces:, consumes:)` | 関数 `name` を呼び出す。`method` が指定しない限り `POST`。 |

- **パラメーター、結果、エラーは Feign のものです。** `@RequestBody`、`@RequestParam`、`@RequestHeader`、`@PathVariable`。結果は下の一覧のとおりです。`FeignException` とそのサブクラス。[メソッド](../spring-boot-starter-feign/methods.md) と [エラーとリトライ](../spring-boot-starter-feign/errors-and-retries.md) を参照してください。
- **関数の名前**には、設定からの `${property}` を書けます。呼び出しごとに変わる部分は、`@PathVariable()` のパラメーターが埋める `{name}` です。SpEL は書けません。関数の名前は、デプロイされた場所で決まっているためです。
- **`@EdgeFunction` のないメソッド**は起動を止めます。そのようなメソッドがすべて一つのメッセージに示されます。

## 関数が返せるもの

| メソッドの戻り値 | 答えは |
|---|---|
| `Future<T>` (クラス、`Map`、`List`)、`Future<String>` | JSON、またはテキスト。 |
| `Future<Uint8List>` | ファイル。全体を読んでから呼び出しが戻る。 |
| `EventStream<T>`、`Stream<T>` | 届いた順のサーバー送信イベント。 |
| `Stream<List<int>>` | コンテンツタイプにかかわらず、届いた順のボディ: 大きなファイル、またはイベントではないチャンク。 |
| `Future<ResponseEntity<T>>` | ステータス、ヘッダー、ボディ。 |

上の `progress` はイベントを送る関数、`export` はファイルを返す関数です。`export` と `exportStream` は同じ関数を呼びます。前者はファイル全体が届いてから戻り、後者は届いたチャンクをそのまま渡し、リスナーごとに一つのリクエストを送ります。

リクエストのボディは、送る前に全体が読まれます。関数にストリームを渡すことはできず、大きなアップロードは [Storage](storage.md) の役目です。型ごとのエラーと空のボディの扱いは [メソッド](../spring-boot-starter-feign/methods.md) を参照してください。

## キーとトークン

すべての呼び出しは、`apikey` と `Authorization: Bearer` を [`SupabaseCredentials`](credentials.md) から受け取ります。これらは最後に設定されるので、他の何もそれを決められません。アプリケーションの `RequestInterceptor` も、デフォルトのヘッダーもです。そのため、関数はリポジトリや Storage と同じユーザーを見ます。`asServiceRole` の中では、サービスロールとして呼び出されます。

アプリケーション自身の `RequestInterceptor` の Bean は、他の Feign クライアントと同じく、その前に実行されます。スターターのインターセプターはその一つではありません。アプリケーションの他の Feign クライアントでは実行されません。

## 設定

クライアントは、その名前の Feign クライアントの設定を受け取ります。

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

- **呼び出しのタイムアウト**は、クライアントの `call-timeout` です。なければ `spring.supabase.functions.timeout`、それもなければ `spring.supabase.timeout` (30 秒) です。
- `follow-redirects` が何であっても、**リダイレクトには従いません。** リダイレクトは、キーとトークンを別のホストに運ぶおそれがあるためです。
- **`apikey`** は、クライアントのログが隠すヘッダーに含まれます。
- **リージョン:** `spring.supabase.functions.region` は、`x-region` ヘッダーとして送られます。
- **呼び出しごとにオブザベーション**が記録されます。名前は `supabase.functions` で、関数の名前が付きます。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.supabase.functions.region` | `String` | なし | 関数を実行するリージョン (`x-region` ヘッダー)。設定しなければ最も近いリージョン。 |
| `spring.supabase.functions.timeout` | `Duration` | `spring.supabase.timeout` | 関数にかけてよい時間。 |

## Spring (Java) との対応

Spring Cloud OpenFeign の `@FeignClient` と、トークンのための `RequestInterceptor` です。`@EdgeFunctions` は、その組み合わせを一つのアノテーションにしたものです。

## 関連項目

- [spring_boot_starter_feign](../spring-boot-starter-feign/index.md)
- [Feign の設定](../spring-boot-starter-feign/configuration.md)
- [誰として呼び出すか](credentials.md)
