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(...) テーブルの行の変更。

行の変更

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。

行は 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 はそうします。

接続

トークン

対応していないもの

プロパティ

キー 型 デフォルト 意味
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()。自動で呼ばれる

関連項目