CIP-16: Replication

0. Abstract

本ドキュメントでは、Concrnt サーバーが保持するコミットログ (CIP-3 §3.4) を、検索インデクサやアーカイバ等の他のソフトウェアが時系列に追従して取得するための Replication エンドポイントを定義する。

1. Status of This Memo

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

本 CIP はオプショナルな拡張であり、CIP-0、CIP-2、CIP-3 および CIP-5 を前提とする。読み取り認可には CIP-12 を必要とする。

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

2. 表記規則

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

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

3. Replication エンドポイント

サーバーは、自身のコミットログをページングして返す Replication エンドポイントを提供してもよい (MAY)。提供する場合、CIP-0 のサービスディスカバリにおいて net.concrnt.core.replication エンドポイント名で広告しなければならない (MUST)。

{
  "endpoints": {
    "net.concrnt.core.replication": "/replication{?owner,since,until,limit,order}"
  }
}

このエンドポイントは HTTP GET リクエストを受け付ける。

列挙対象は、サーバーが CIP-3 §3.4 のコミットログとして記録した Signed Document (CIP-1) の全体であり、 kind を問わない (entity, record, association, delete, ack, unack, acked, unacked)。コミットログは適用された Document のみを含むため (CIP-3 §3.4)、本エンドポイントの出力を順に再適用することで、サーバーが保持する状態を再構成できる。

CIP-4 §5 により GC の候補となったコミットも、実際に破棄されるまでは列挙に含めなければならない (MUST)。

3.1 リクエスト形式

Replication エンドポイントは、以下のクエリパラメータを受け付ける。

owner — コミットの所有者 (CIP-3 §3.1 で導出されるコミット対象の名前空間の owner) を CCID で指定する文字列。指定した場合、その所有者のコミットのみを返す。(任意)
since — ソートキー (§3.2) が since 以上のコミットのみを返すための RFC3339 形式の日時文字列。境界を含む。(任意)
until — ソートキー (§3.2) が until 以下のコミットのみを返すための RFC3339 形式の日時文字列。境界を含む。(任意)
limit — 返されるコミットの最大数を指定する整数。切り詰め・切り上げの規則は CIP-5 §3.1 と同じである。参考実装の既定値は 10、上限は 100 である。(任意)
order — ソート順序を指定する文字列。asc (昇順) または desc (降順)。デフォルトは asc である (CIP-5 の Query エンドポイントと異なる。追従する消費者はログを古い側から順に読むため)。それ以外の値が指定された場合、サーバーは HTTP 400 Bad Request を返さなければならない (MUST)。(任意)

3.2 レスポンス形式

サーバーは、CIP-5 §3.2 と同じ形式の JSON オブジェクト (items, prev, next) を返さなければならない (MUST)。

{
  "items": [
    {
      "document": "{...}",
      "proof": { "type": "concrnt-ecrecover-direct", "signature": "..." },
      "ccfs": "ccfs://<CCID>/concrnt/<cdid>"
    }
  ],
  "prev": "2026-09-15T12:00:00.123456Z",
  "next": "2026-09-15T12:00:02.000001Z"
}

items — Signed Document の JSON 配列。所有者が記録されているコミットの要素は ccfs URI を持たなければならない (MUST)。ccfs の owner 部はコミットの所有者、CDID 部は当該 Document の CDID である。所有者を持たないコミット (旧仕様から移行され、所有者が補完されていないもの) では ccfs を省略する。各要素に cckv を含めてはならない (MUST NOT)。上書き済みのコミットのキーは現時点で別の Document を指しうるため、コミットログの項目としては誤解を招く。
prev / next — RFC3339 形式の日時文字列によるページングカーソル、または null。両キーは常に存在しなければならない (MUST)。

返却するコミットは、order パラメータで指定された順序でソートされなければならない (MUST)。 ソートキーは、サーバーがそのコミットを受理してコミットログに記録した時刻であり、Document の createdAt ではない。これにより、backdate window (CIP-3 §3.4) の範囲内で過去の createdAt を持つ Document や、再インポートされた Document も、追従する消費者には必ず受理順に現れる。ソートキーが同一のコミット間の順序は、CDID の辞書順を決定的なタイブレークとして用いなければならない (MUST)。タイブレークの方向は order に追従する (desc の場合は CDID も降順)。

3.3 ページングカーソル

カーソルの意味、limit + 1 件取得による next の決定、prev の決定、境界を含むことによる重複、および next が進まない場合の停止条件は、CIP-5 §3.3 を準用する。ソートキーは §3.2 の受理時刻である。 prev / next は、読み取り認可 (§3.4) による除外を適用する前の結果から計算しなければならない (MUST)。

全件を列挙するクライアントは、ccfs URI (ccfs を持たない要素については Document から計算した CDID) をキーとして結果を重複排除すべきである (SHOULD)。コミットログではこれらはコミットごとに一意である。

追加の既知の限界として、受理時刻はコミット処理中にサーバーが採取する時刻であり、トランザクションの完了順とは必ずしも一致しない。並行して処理されたコミットにより、より小さいソートキーを持つコミットが後から可視になることがある。next を保存して継続的に追従するクライアントは、最後に取得したカーソルから一定の余裕 (参考実装の想定では数秒程度) を差し引いた since で再走査し、上記の重複排除を行うべきである (SHOULD)。

3.4 読み取り認可

サーバーは、リクエスタ (CIP-2 の認証によって識別される。未認証の場合はゲスト) が読み取り権限を持たないコミットを結果から除外しなければならない (MUST)。評価対象は kind によって次のように定める。

kind: "record" — Document の key を評価対象 URI とし、record:read (CIP-12) を評価する。
kind: "association" — Document の associate を評価対象 URI とし、association:read (CIP-12、CIP-9) を評価する。
それ以外の kind (entity, delete, ack, unack, acked, unacked) — 認可評価を行わず、そのまま返す。これらはエンティティの公開情報、公開の関係、または削除の事実のみを含む。

除外が発生したことをエラーとして通知する必要はなく、単に結果から省略してよい (MAY)。この場合、返却件数が limit に満たないことがある。

サービスアカウント種別 "system" (CIP-2 §6) のリクエストに対しては、サーバーは認可評価を省略して全コミットを返してもよい (MAY)。サーバーの全状態を複製するソフトウェアは、この経路を用いることが想定される。

4. Security Considerations

読み取り認可 (§3.4) は、評価時点のキー階層ポリシー (CIP-12) に基づく。上書き済みまたは削除済みの Document のコミットは、現時点でそのキー (存在しない場合はその祖先) に適用されるポリシーで評価される。削除された Document の秘匿を、そのキー単体のポリシーだけに依存して達成することはできない。
kind: "delete" のコミットは認可評価を行わないため、削除対象の URI が公開される。非公開 Document の存在自体を秘匿したい場合、削除対象の名前空間全体を非公開とすることが必要である。
未認証のリクエストはゲストとして認可される。全件の複製が必要なソフトウェアはサービスアカウントトークンを用いるが、このトークンは CIP-2 §6 の通り運用者の管理経路以外に発行してはならない (MUST NOT)。
本エンドポイントはコミットログ全体に対する範囲走査であり、負荷が高くなりうる。サーバーはレート制限や limit 上限の引き下げを行ってもよい (MAY)。
出力には proof (署名) が含まれるため、消費者は各 Document を CIP-1 の手順で独立に検証できる。ただし proof.type が none のコミット (CIP-1 §7.5) は発行元サーバーへの信頼に依存する。

5. References

RFC 2119 – Key words for use in RFCs to Indicate Requirement Levels
RFC 8174 – Clarifications to RFC 2119
RFC 3339 – Date and Time on the Internet: Timestamps
CIP-2 – Auth (サービスアカウント)
CIP-3 – Commit (コミットログ)
CIP-5 – Query (ページングカーソル)
CIP-12 – Policy (読み取り認可)

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