CIP-11: Realtime API

0. Abstract

本仕様は、Concrnt サーバーのエンドポイントを拡張し、サーバーで発生したリソースの変更イベントをリアルタイムにクライアントへ通知する手段を提供する。

1. Status of This Memo

このドキュメントは Realtime API の仕様を定義する。 Concrnt プロジェクトにより公開されるバージョン付き仕様であり、実装者およびプロトコル設計者を対象とする。

本 CIP はオプショナルな拡張であり、CIP-0, CIP-1 を前提とする。イベントの redaction には CIP-12 を必要とする。

本仕様はドラフトであり、後方互換性のない変更が行われる可能性がある。

2. 表記規則

このドキュメントにおける以下の語は、必ず大文字で記述される場合、 BCP 14 [RFC2119] [RFC8174] にしたがって解釈される。

MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, OPTIONAL

3. Realtime エンドポイント

本 CIP を実装するサーバーは、WebSocket [RFC6455] へアップグレード可能な HTTP GET エンドポイントを提供し、CIP-0 のサービスディスカバリにおいて net.concrnt.core.realtime エンドポイント名で広告しなければならない (MUST)。

{
  "version": "2.0",
  "csid": "ccs1<bech32-encoded-address>",
  "endpoints": {
    "net.concrnt.core.resolve": "/resource/{uri}",
    "net.concrnt.core.realtime": "/realtime"
  }
}

3.1 購読の開始

クライアントは、Realtime エンドポイントに対して WebSocket ハンドシェイクを行い、接続確立後に以下の JSON メッセージを送信して、リソースの変更イベントの購読を開始する。

{
    "type": "subscribe",
    "prefixes": [
        "<CCURI>",
        "<CCURI>"
    ]
}

type メッセージ種別。購読の開始は "subscribe" を指定する。サーバーは "listen" を "subscribe" の別名として受理してもよい (MAY。旧仕様との互換のため)。このほか、"h" はハートビートを表すメッセージ種別であり、サーバーは何も行わず受理する。
prefixes 購読するリソースの CCURI の配列。

購読のマッチングは、イベントの source (§3.2) の CCURI 文字列に対する単純な前方一致とする (MUST)。指定した CCURI そのものに加え、それを接頭辞とするリソースで発生したイベントも通知される (CIP-5 §3.1 の prefix と同じ規則であり、item の購読には兄弟キー item2 もマッチする点に注意)。 prefix 中の * ? [ 等の文字をワイルドカードとして解釈してはならない (MUST NOT)。

各 prefix は owner 部を持つ有効な CCURI でなければならない (MUST)。owner 部を持たない prefix (空文字列や cckv:// 等) は、サーバー全体のイベントの購読を許すため、無視しなければならない (MUST)。サーバーは、1 接続あたりの prefix 数に上限を設けるべきである (SHOULD)。

複数回 subscribe メッセージが送信された場合、サーバーは最新の購読リストのみを保持する (購読リストの全置換)。明示的な unsubscribe メッセージは存在せず、購読の解除は縮小した購読リストによる subscribe の再送によって行う。

サーバーは、未知の type を持つメッセージを受信した場合、接続を切断せず無視するべきである (SHOULD)。サーバーは接続の生存確認に WebSocket の Ping フレーム (RFC6455) を用いるべきであり (SHOULD)、アプリケーションレベルの "h" メッセージの受信を接続維持の条件としてはならない (MUST NOT)。

3.1.1 外部リソースの購読 (中継)

prefixes に指定するリソースは、そのサーバーが管理しているものでなくてもよい。外部リソースが要求された場合、サーバーはそのリソースの権威サーバーの Realtime エンドポイントへ代理で購読を行い、イベントを中継してもよい (MAY)。中継を行わないサーバーは、管理外の prefix に対するイベントを配信しない (購読メッセージ自体はエラーとしない)。クライアントは、確実に受信するためには対象リソースの権威サーバーへ直接接続することができる。

中継を行う場合、以下に従う。

上流接続の宛先が、プライベート・ループバック・リンクローカルアドレスへ解決される場合、接続してはならない (MUST NOT)。
1 接続あたり、およびサーバー全体で確立する上流接続数に上限を設けなければならない (MUST)。
中継されたイベントを、それを受信した上流接続へ再送してはならない (MUST NOT)。中継のホップ数に上限を設けるべきである (SHOULD)。

サーバー間中継の詳細プロトコル (上流の多重化、購読の張り替え、再接続方式等) は本仕様では規定せず、将来の CIP に委ねる。

3.2 イベントの受信

サーバーは、購読されたリソースに変更が発生した場合、以下の JSON メッセージをクライアントに送信する。

{
    "type": "created",
    "source": "<CCURI>",
    "uri": "<CCURI>",
    "association": "<CCURI>",
    "documents": {
        "<CCURI>": { ... }
    },
    "timestamp": "2025-11-23T12:34:56Z"
}

type (required) 変更イベントの種類を示す文字列。とりうる値は以下の通り。
- "created": 新しい Document が作成されたことを示す。既存キーの上書き (CIP-3 §3.4) の場合も "created" を発行する (Document の作成を示すのであり、キーの新規性を示すものではない)。
- "deleted": Document が削除されたことを示す。
- "associated": Document に Association (CIP-9) が作成されたことを示す。
- "unassociated": Document から Association が削除されたことを示す。
クライアントは、未知の type を持つメッセージを、接続を切断せず無視しなければならない (MUST)。
source (required) イベントが発行されたチャンネル (変更が発生したリソース側) の CCURI を設定しなければならない (MUST)。購読プレフィックスの値そのものを設定してはならない (MUST NOT)。クライアントは、自身の購読プレフィックスと source の前方一致により、由来する購読を判別する。
uri (required) 変更対象となったリソースの CCURI。 "created" / "deleted" では作成・削除された Document の URI、 "associated" / "unassociated" では関連付けの対象となった Document の URI が入る。
association (OPTIONAL) "associated" / "unassociated" イベントにおいて、作成・削除された Association Document の ccfs URI を設定するべきである (SHOULD)。
documents (OPTIONAL) イベントに関連する Concrnt Signed Document (CIP-1) を、そのリソースの CCURI をキーとしたマップで格納する。
- "created": 作成された Document (キーは uri と同じ) を含む。
- "associated": 作成された Association Document (キーは association と同じ) を含む。
- "deleted" / "unassociated": 通常このフィールドは省略される。
保護された Document の編集 (redaction): サーバーは、イベントの送出時に、対象 Document の読み取りアクション (record:read / association:read, CIP-12) をゲスト (匿名) リクエスタで評価し、匿名での読み取りが許可されない Document については documents フィールドからその内容を省略しなければならない (MUST)。この場合もイベント自体 (type / source / uri / timestamp 等) は配送される。同梱される Signed Document がネストされた references (CIP-1) を持つ場合 (例: 配布 Reference Document に内包された元 Document)、その各エントリにも同じ匿名 read 評価を適用し、許可されないエントリは省略しなければならない (MUST)。さらに深い階層のネストは一律に省略してよい (MAY)。参考実装は省略する。クライアントは、内容が省略されたイベントを受信した場合、必要に応じて自身の認証情報を用いた通常の Resolve / Query (CIP-0, CIP-5) で Document を取得する。
timestamp (required) イベントの発生時刻。"created" イベントでは Document の createdAt の値が入る。それ以外のイベントでは、サーバーがイベントを発行した時刻が入る。

4. Security Considerations

Realtime API の配信内容は匿名で閲覧可能な情報に限定される。購読自体には認証を要求しない代わりに、匿名リクエスタで読み取りが許可されない Document の内容は §3.2 の redaction 規則によりイベントから省略されなければならない (MUST)。これにより、購読者ごとの認可評価やサーバー間中継時のアイデンティティの伝搬を必要とせず、保護された Document の内容が未認可の購読者 (および中継先) へ漏えいすることを防ぐ。
イベントのメタデータ (uri 等のキー情報・イベントの発生事実) は保護の対象外である。購読は前方一致 (§3.1) であるため、キー名そのものが機微である場合は保護されない。リソースの存在自体を秘匿する必要がある用途では、Realtime API によるイベント配信を行うべきではない (SHOULD NOT)。
イベントは配信元サーバーが構成する助言的な通知であり、それ自体は暗号学的な証明を伴わない。クライアントは、イベントのみを根拠にリソースの状態を確定せず、必要に応じて対象を resolve で確認すること。特に deleted / unassociated イベントは、伝搬削除の受信処理 (CIP-4 §6.1) の性質上、実際には削除されていない対象について発行されうる。
中継 (§3.1.1) は匿名クライアントの指定に基づく外向き接続であり、SSRF・増幅・ループの温床となる。中継を行うサーバーは §3.1.1 の防御を省略してはならない。

5. References

RFC 2119 – Key words for use in RFCs to Indicate Requirement Levels
RFC 8174 – Clarifications to RFC 2119
RFC 6455 – The WebSocket Protocol
CIP-12 – Policy (record:read / association:read)

この文書は concrnt/CIPs-translated の ja/11-realtime.md から生成されています。原文(英語)は concrnt/CIPs を参照してください。