
# Realtime

`SupabaseRealtime` (Bean 名は `supabaseRealtime`) は、Supabase Realtime が送る三つのものをストリームとして渡します。データベースの行の変更 (Postgres Changes)、クライアント間のメッセージ (Broadcast)、誰がオンラインか (Presence) です。通常は、アプリケーションが `@RealtimeChannel` のインターフェースを宣言し、ジェネレーターがその Bean を書きます。

## 使う理由

Realtime は、一つの WebSocket の上で Phoenix Channels プロトコルを話します。参加するトピック、対応付ける応答、ハートビート、再接続のたびの再参加、そして変わるたびに送り直すユーザーのトークンがあります。そのうえ、チャンネルの設定は参加のときにしか受け取られません。スターターはそのすべてを行います。チャンネルは何かがそれを購読している間だけ参加し、アプリケーションが見るのはストリームと Future だけです。

## 例

```dart
@Introspected()
class Cursor {
  Cursor({required this.x, required this.y});

  final int x;
  final int y;
}

@Introspected()
class Member {
  Member({required this.name, this.typing = false});

  final String name;
  final bool typing;
}

@RealtimeChannel('room:{id}', presenceKey: '#{authentication.name}')
abstract interface class Room {
  @Broadcast('cursor')
  Stream<Cursor> cursors(String id);

  @Broadcast('cursor')
  Future<void> moveCursor(String id, Cursor cursor);

  @Presence()
  Stream<List<Member>> members(String id);

  @Presence()
  Future<void> join(String id, Member me);

  @PostgresChanges(table: 'messages', filter: 'room_id=eq.{id}')
  Stream<RealtimeRowChange> messages(String id);
}

@Service()
class Board {
  Board(this.room);              // the generated bean

  final Room room;

  void open(String id) {
    room.cursors(id).listen(drawCursor);     // listening joins room:<id>
    room.members(id).listen(showMembers);
    room.join(id, Member(name: 'Ann'));
  }
}
```

## 宣言したチャンネル

`@RealtimeChannel(name, private:, self:, ack:, presenceKey:)` は、チャンネル `name` (トピックは `realtime:<name>`) のインターフェースに付けます。

| オプション | 意味 |
|---|---|
| `private` | メンバーが `realtime.messages` の行レベルセキュリティのポリシーで認可されるチャンネル。 |
| `self` | このクライアントが自分のブロードキャストも受け取る。 |
| `ack` | 送信する `@Broadcast` メソッドが、サーバーがメッセージを受け取るまで待つ。 |
| `presenceKey` | このクライアントがプレゼンスに使うキー。`#{authentication.name}` にすると、一人のユーザーの複数のデバイスが一人のメンバーになる。なければ、サーバーが接続ごとにキーを作る。 |

| メソッド | すること |
|---|---|
| `@Broadcast('event') Stream<T> name(...)` | 他のクライアントのブロードキャスト。各ペイロードは `ObjectMapper` で `T` として読まれる (`Map<String, Object?>` はそのまま)。読めないペイロードはエラーイベント (`MessageConversionException`) になり、ストリームは続く。 |
| `@Broadcast('event') Future<void> name(..., payload)` | ブロードキャストを一つ送る。ペイロードは、チャンネル名が使っていないパラメーター (または `@RequestBody()` の付いたもの) で、JSON として書かれる。なければ `{}` が送られる。 |
| `@Presence() Stream<List<T>> name(...)` | 現在いる全員。今の一覧と、変更のたびの一覧。各自が追跡した状態が `T` として読まれる (`RealtimePresence` ならキーと参照も得られる)。 |
| `@Presence() Future<void> name(..., state)` | このクライアントを、その状態 (JSON オブジェクトとして書かれる) でプレゼンスに加える。 |
| `@Presence() Future<void> name(...)` | 状態のパラメーターがない場合: このクライアントのプレゼンスを終える。 |
| `@PostgresChanges(table:, schema:, filter:, kind:) Stream<RealtimeRowChange> name(...)` | テーブルの行の変更。 |

- **名前。** チャンネルの名前、`presenceKey`、フィルターには、設定からの `${property}`、同じ名前のメソッドのパラメーターからの `{name}`、`#{...}` の SpEL を書けます (パラメーターは `#name`、`authentication` と `principal` は `@PreAuthorize` と同じ、Bean は `@name`)。そのため、一つのインターフェースがすべての部屋に使えます。
- **一つの名前に一つのチャンネル。** 出てきた名前ごとに一つのチャンネルです。そのメソッドのどれかが最初に使われたときに参加し、最後のストリームがキャンセルされ、何も追跡されていなくなったときに離脱します。
- **起動時に検査。** 誤って宣言されたメソッドは起動を止め、メッセージはそのインターフェースのすべての問題を示します。
- **AOP。** この Bean には、他の Bean と同じく AOP が効きます (`@PreAuthorize`)。
- **独自の種類のメソッド**は、`RealtimeChannelOperation` を実装する Bean です。スターター自身のものより先に尋ねられます。

## 行の変更

```dart
realtime
    .postgresChanges(table: 'todos', filter: 'list_id=eq.7')
    .listen((change) {
      if (change.kind == RealtimeChangeKind.delete) {
        remove(change.oldRecord['id']);
      } else {
        put(change.record);
      }
    });
```

`RealtimeRowChange` は一つの変更で、コミットされた後に送られます。

| メンバー | 意味 |
|---|---|
| `kind` | `RealtimeChangeKind.insert`、`update`、`delete` のいずれか。 |
| `schema`、`table` | どこで起きたか。 |
| `record` | 変更後の行。列名から JSON の値へのマップ。削除のときは空。 |
| `oldRecord` | 更新または削除の前の行。テーブルが `replica identity full` でない限り、主キーだけ。挿入のときは空。 |
| `commitTime` | 変更がコミットされた時刻 (サーバーが伝えた場合)。 |
| `columns` | 列の PostgreSQL の型 (列名ごと)。 |
| `errors` | この変更についてサーバーができなかったこと。例えば `Error 413: Payload Too Large`。 |

- テーブルは、パブリケーション `supabase_realtime` に含まれていなければなりません。
- ユーザーは、その行を読む権限を持っていなければなりません。行レベルセキュリティが適用され、ユーザーが読めないものは送られません。
- `filter` は、サーバーで行を絞ります。`column=operator.value` の形で、演算子は `eq`、`neq`、`lt`、`lte`、`gt`、`gte`、`in` (`id=in.(1,2,3)`) です。`kind` は、挿入、更新、削除のどれかだけにします。
- 宣言したフィルターでは、パラメーターや式が返すものは一つの値で、フィルターの一部になることはありません。`,`、`(`、`)`、`"`、`\` を含む値は二重引用符で囲まれ、リストは `in.({ids})` のために、カンマで区切った値になります。
- サーバーが作れない購読 (誤ったフィルター、パブリッシュされていないテーブル) は、エラーイベントの `RealtimeException` になります。ストリームは開いたままです。

行は JSON で、エンティティではありません。エンティティが欲しい場合は、リポジトリに `watch…By` (`Stream<List<T>>`、最新に保たれる行) と `changes…By` (`Stream<RowChange<T>>`) のメソッドを宣言します。[REST データストア](data.md)が、自分の行の変更をここから報告します。Realtime が絞れる条件 (`eq`、`neq`、`lt`、`lte`、`gt`、`gte` の条件が一つ) はサーバーで絞られ、それ以外はこちら側で絞られます。

```dart
@UseStore('supabase')
abstract interface class Todos implements ListCrudRepository<Todo, int> {
  Stream<List<Todo>> watchByListId(String listId);

  Stream<RowChange<Todo>> changesByListId(String listId);
}
// changesByListId('l1') joins with {event: *, schema: public, table: todos, filter: list_id=eq.l1}
```

`watch…By` は、購読されたときにクエリを実行し、変更のたびにもう一度実行します。`changes…By` は、挿入、更新、削除のそれぞれを `RowChange` として渡します (`previous` は `replica identity full` のときだけ)。[データ](data.md) と [行の変更](../spring-boot-starter-data/changes.md) を参照してください。

## コードでのブロードキャストとプレゼンス

アプリケーションのビルド時に名前や使い方が分からないチャンネルは、`SupabaseRealtime` に尋ねます。

```dart
final room = realtime.channel('room:42', presenceKey: userId);
room.broadcast('cursor').listen(moveCursor);
room.presence().listen(showMembers);
await room.track({'name': 'Ann'});
await room.send('cursor', {'x': 3, 'y': 4});
```

`realtime.channel(name, private:, self:, ack:, presenceKey:)` は `RealtimeChannelSession` を返します。同じ名前での呼び出しは、すべて同じチャンネルを返します。使われている間はオプションが同じでなければならず、違うと、その使用は `StateError` で失敗します。

| メンバー | すること |
|---|---|
| `broadcast(event)` | `event` という名前のブロードキャストのペイロード (JSON オブジェクト)。オブジェクトでないものはエラーイベントになる。 |
| `events(event)` | 同じだが、JSON が何であってもよい (オブジェクト、リスト、テキスト)。 |
| `send(event, [payload])` | ブロードキャストする。必要なら先にチャンネルに参加する。`ack` があるとサーバーを待ち、サーバーが拒否すると `PhoenixPushException` で失敗する。 |
| `presence()` | 現在いる人。今の一覧と、変更のたびの一覧。 |
| `track(state)`、`untrack()` | このクライアントを状態付きでプレゼンスに加える (もう一度追跡すると置き換える)。そのプレゼンスを終える。 |
| `postgresChanges(table:, schema:, filter:, kind:)` | このチャンネルでの行の変更。 |
| `leave()` | 今すぐチャンネルを離れる。そのストリームは完了する。もう一度使うと、再び参加する。 |

`RealtimePresence` は、クライアントが参加に使った `key`、その一つのプレゼンスについてのサーバーの `ref`、追跡した `state` を持ちます。同じキーが複数回現れることがあります。二つのデバイスを使うユーザーです。

サーバーは、チャンネルの設定を参加のときにしか受け取りません。そのため、チャンネルが参加している間に、データベースの変更のストリームが追加またはキャンセルされたり、プレゼンスが初めて使われたりすると、チャンネルは参加し直します。他のストリームは続きますが、その瞬間に送られたブロードキャストは取りこぼします。チャンネルに必要なものは一度に購読するか、データベースの変更には専用のチャンネルを与えてください。`realtime.postgresChanges` はそうします。

## 接続

- すべてのチャンネルに**接続は一つ**です。最初に使われるチャンネルとともに開き、最後のチャンネルが離脱したとき、そしてアプリケーションが停止したときに閉じます。
- **再接続。** 接続が失われた後、すべてのチャンネルは新しいアクセストークンで自動的に参加し直します。追跡していたものは再び追跡され、ストリームは続きます。サーバーが拒否した参加はエラーイベント (`PhoenixJoinException`) になり、再試行されます。
- **サーバーがチャンネルを終わらせたとき** (制限を超えた、トークンを拒否した)、そのストリームは `RealtimeException` を受け取り、完了します。
- 接続は WebSocket クライアント `supabase-realtime` で、WebSocket スターターの [Phoenix ソケット](../spring-boot-starter-websocket/phoenix.md) です。`spring.websocket.client.config.supabase-realtime.*` で調整します (`reconnect.*`、`connect-timeout`、`max-text-message-size`、`phoenix.*`)。その `url` は読まれません。

## トークン

- すべてのチャンネルは、[`SupabaseCredentials`](credentials.md) のアクセストークンで参加します。トークンは参加のたびに尋ねられます。
- アプリケーションに `LoginSession` (サインインしたユーザー) があると、ログインが変わるたびに、参加し直すことなく、新しいトークンが参加中のチャンネルに送られます。ログアウトの後は anon キーです。
- 更新されたトークンは、次のハートビートで送られます。`realtime.refreshAuth()` は、現在のトークンを今すぐ送ります。
- **チャンネルはアプリケーション自身として動作します。** そのログイン、または anon キーです。チャンネルはサーバーのリクエストより長く生きるので、それを要求したリクエストのトークンを使うことはありません。
- `asServiceRole` の中で要求されたチャンネルは、いつ使われても、サービスロールとして参加します。

## 対応していないもの

- ワイヤーフォーマット `2.0.0`。Realtime はこの形式で、ブロードキャストをバイナリフレームとして送ります。接続は `1.0.0` を使い、すべてのメッセージは JSON のテキストです。
- ブロードキャストの REST へのフォールバック。`send` はチャンネルに参加します。
- `connect()`、`subscribe()`、`removeChannel()`。チャンネルは、使われている間だけ参加します。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.supabase.realtime.heartbeat-interval` | `Duration` | `25s` | 接続が生きていることを伝える間隔。`spring.websocket.client.config.supabase-realtime.phoenix.heartbeat-interval` が優先される。 |
| `spring.supabase.realtime.timeout` | `Duration` | `10s` | 参加やメッセージが応答を待つ時間。`…supabase-realtime.phoenix.push-timeout` が優先される。 |
| `spring.supabase.realtime.max-message-size` | `DataSize` | `4MB` | 読む最大のメッセージ。これより大きいと接続を閉じる。`…supabase-realtime.max-text-message-size` が優先される。 |
| `spring.supabase.connect-timeout` | `Duration` | `10s` | 接続を開くのにかけてよい時間。`…supabase-realtime.connect-timeout` (または `default` のもの) が優先される。 |

## Supabase (JavaScript) との対応

| `realtime-js` | ここでは |
|---|---|
| `supabase.channel(name, {config})` | `realtime.channel(name, …)`、または `@RealtimeChannel` のインターフェース |
| `channel.on('postgres_changes', {event, schema, table, filter}, fn)` | `postgresChanges(table:, schema:, filter:, kind:)`、`@PostgresChanges` |
| `channel.on('broadcast', {event}, fn)`、`channel.send({type: 'broadcast', event, payload})` | `broadcast(event)`、`send(event, payload)`、`@Broadcast` |
| `channel.on('presence', {event: 'sync'}, fn)`、`channel.track(state)`、`channel.untrack()` | `presence()`、`track(state)`、`untrack()`、`@Presence` |
| `channel.subscribe()` | 不要 |
| `supabase.removeChannel(channel)` | `leave()` |
| `realtime.setAuth()` | `refreshAuth()`。自動で呼ばれる |

## 関連項目

- [Phoenix Channels クライアント](../spring-boot-starter-websocket/phoenix.md)
- [データスターターの行の変更](../spring-boot-starter-data/changes.md)
- [誰として呼び出すか](credentials.md)
- [データ](data.md)
