Realtime
SupabaseRealtime (Bean 名は supabaseRealtime) は、Supabase Realtime が送る三つのものをストリームとして渡します。データベースの行の変更 (Postgres Changes)、クライアント間のメッセージ (Broadcast)、誰がオンラインか (Presence) です。通常は、アプリケーションが @RealtimeChannel のインターフェースを宣言し、ジェネレーターがその Bean を書きます。
使う理由
Realtime は、一つの WebSocket の上で Phoenix Channels プロトコルを話します。参加するトピック、対応付ける応答、ハートビート、再接続のたびの再参加、そして変わるたびに送り直すユーザーのトークンがあります。そのうえ、チャンネルの設定は参加のときにしか受け取られません。スターターはそのすべてを行います。チャンネルは何かがそれを購読している間だけ参加し、アプリケーションが見るのはストリームと Future だけです。
例
@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 です。スターター自身のものより先に尋ねられます。
行の変更
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 データストアが、自分の行の変更をここから報告します。Realtime が絞れる条件 (eq、neq、lt、lte、gt、gte の条件が一つ) はサーバーで絞られ、それ以外はこちら側で絞られます。
@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 のときだけ)。データ と 行の変更 を参照してください。
コードでのブロードキャストとプレゼンス
アプリケーションのビルド時に名前や使い方が分からないチャンネルは、SupabaseRealtime に尋ねます。
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.websocket.client.config.supabase-realtime.*で調整します (reconnect.*、connect-timeout、max-text-message-size、phoenix.*)。そのurlは読まれません。
トークン
- すべてのチャンネルは、
SupabaseCredentialsのアクセストークンで参加します。トークンは参加のたびに尋ねられます。 - アプリケーションに
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()。自動で呼ばれる |