> Source: https://clickhouse.github.io/loom/ja/architecture/source-push/ (Markdown: https://clickhouse.github.io/loom/ja/architecture/source-push.md)

<!-- i18n: source=docs/architecture/source-push.md blob=3114dcae551415671efdfa6f880845f601eb7342 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://clickhouse.github.io/loom/architecture/source-push/)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/architecture/source-push/), which is authoritative.

<a id="document-source-push-notifications"></a>

# ドキュメントソースのプッシュ通知

プロバイダーの通知からドキュメントソースの同期を要求するには、`LOOM_KNOWLEDGE_SOURCE_PUSH_ENABLED=true` が必要です。通知がドキュメントの内容を書き込んだり、ソースのアクセスポリシーを変更したりすることはありません。通常の 15 分ごとのポーリングは有効のままで、配信が失われた場合の復旧経路になります。プッシュを無効にすると、セットアップ、配信、更新は一時停止しますが、シークレットの再暗号化とセットアップの廃止は妨げられません。

<a id="source-entry-points"></a>

## ソースのエントリポイント

- `server/knowledge/api/ops_source_push.py`（`OPERATIONS`）は、管理者向けのセットアップ、確認、ステータスの各オペレーションを宣言します。
- `server/knowledge/app/source_push_routes.py`（`notification`）は、コールバックの本文サイズを制限し、プロバイダーからの配信を振り分けます。
- `server/knowledge/app/source_push.py`（`receive`、`_fresh`、`_put`、`renew_drive`、`reseal_registry`）は、通知ヒントを認証し、レジストリのライフサイクル書き込みを調整します。
- `server/knowledge/domain/source_push.py`（`fingerprint`、`verify_drive`、`verify_notion`、`verify_linear`）は、セットアップを束縛し、プロバイダーの証明を検証します。`server/knowledge/store/source_push.py`（`get`、`put`）は、レジストリのバージョンを永続化します。
- `server/knowledge/app/sources.py`（`sources_lease`、`deactivate_namespace_sources`）は、ソースのライフサイクル変更を調整します。`server/erasure/store/steps_ledgers.py`（`delete_source_push_by_namespace`）は、レジストリの消去を確定します。

<a id="invariants"></a>

## 不変条件

- 認証済みの配信は、既存のソース経路を通じて同期を要求します。プロバイダーのペイロードが内容を書き込んだり、ソースのアクセス範囲を広げたりすることはできません。
- 配信は、現在のソース ID、セットアップ世代と認証情報、アイテムと設定のフィンガープリントに一致する必要があります。ソースのリースと逐次読み取りにより、ソースの置き換え、廃止、遅れて届くプロバイダーの応答を防ぎます。
- プッシュのシークレットには、用途に束縛された暗号化を使用します。保留中のチャレンジを表示できるのは管理者だけです。通常の読み取り、監査の対象、冪等性リプレイには含まれません。
- レジストリの書き込みと名前空間の消去は、フェンス付きのライターリースを共有します。消去はすべての保存済みバージョンを削除し、セットアップの公開にはその消去ステップへのフリート全体の対応が検証されていることが必要です。

<a id="registration-and-authentication"></a>

## 登録と認証

プッシュレジストリは、ソースレジストリや同期カーソルとは別に管理されます。1 行が、組織、名前空間、ソース ID、プロバイダー、ランダムなセットアップ世代を、ソースの認証情報とアイテムのフィンガープリントに束縛します。設定は管理者の操作です。明示的に設定された HTTPS の公開ベース URL が必要です。

コールバック URL は、パスに名前空間、ソース ID、セットアップ世代を含み、必須の `org` クエリパラメーターに正確な組織を含みます。クエリのエンコードにより、スラッシュや URL の予約文字を含む組織名も保持されます。コールバックは、同期要求を記録する前に、名前空間のソースリースの下でレジストリと現在のソースを再読み込みします。ソースの削除や置き換え、認証情報の変更、アイテム集合の変更、非アクティブな名前空間、廃止された世代がある場合、配信は拒否されます。コールバックのペイロードとヘッダーは保存もログ出力もされません。

- Drive のチャネルは、それぞれ独立したランダムなチャネル ID と暗号化されたチャネルトークンを使います。配信は、有効期限前にアクティブなチャネル ID、トークン、リソース ID と一致する必要があります。これはチャネルトークンによる検証です。Drive はこれらの配信に署名しません。早い段階の `sync` 通知は、作業を要求せずに受理応答だけを返します。watch の応答は、セットアップ世代を再確認した後にだけ有効化されます。
- Notion のセットアップでは、新しい世代ごとに、サイズが制限された暗号化済みの検証チャレンジを 1 つ取得します。保留中の間、これを表示できるのは管理者だけです。管理者はプロバイダーの UI でサブスクリプションを確認した後、その正確な世代とチャレンジのフィンガープリントを確定します。署名のないチャレンジでは、サブスクリプションを有効化することも同期を要求することもできません。有効な配信には、生の本文に対する HMAC と、設定されたワークスペース ID が必要です。
- Linear のセットアップでは、まず保留中の通知アドレスを提示します。管理者はそこに webhook を作成し、その署名シークレットとともに同じ世代を確定します。配信には、生の本文に対する HMAC、署名された本文のミリ秒タイムスタンプが 1 分以内であること、設定された組織 ID が必要です。

プロバイダー ID は、セットアップ時にソースの既存の認証情報を使って読み取られます。通知の本文には固定のサイズ上限があります。有効な通知が重複した場合は、既存の保留中の同期要求にまとめられ、待機中のフル同期は保持されます。コールバックが成功すると、4 秒のハンドラー予算内に HTTP 200 を返します。

<a id="drive-coverage-and-renewal"></a>

## Drive の対象範囲と更新

Drive のユーザー変更チャネルは、共有ドライブのすべての変更をカバーするわけではありません。そのためセットアップでは、ユーザーのコーパスと、アカウントが所属するすべての共有ドライブ（最大 19 ドライブ）に対してチャネルを作成します。完全で上限のあるメンバーシップ一覧を使うことで、直接共有されたファイルのドライブ ID をメンバーシップと取り違えることを避けます。非メンバーに直接共有されたアイテムには、ユーザーのログが使われます。コーパスの集合が不完全な場合や上限を超える場合、セットアップは完全なプッシュ対象範囲を主張せずに拒否します。ファイルを新しいコーパスへ移動した場合は、再度セットアップが必要になることがあります。ポーリングでは引き続き変更が検出されます。

デフォルトで無効の、上限付きワーカーが、有効期限の前にチャネルを更新します。ワーカーは新しい一意のチャネルを作成し、応答とソース世代を検証してから、ソースリースの下で入れ替えます。古いチャネルの停止はベストエフォートで行います。更新に失敗してもポーリングは利用可能なままで、期限切れのチャネルはセットアップのステータスに表示されます。

設定カタログでは、プロバイダー処理、チャネルごとの停止、クリーンアップ全体、ワーカーのパスの各期限を制御します。デフォルトはそれぞれ 40、2、5、120 秒です。パスは、プロバイダーの試行 1 回とクリーンアップ枠 2 回分の時間が残っている間だけ、新しい更新を開始します。プロバイダー処理とクリーンアップの合計が 120 秒の更新リースの中の 48 秒の作業枠を超えうる場合、または更新を開始する時間が残らないパス予算の場合、設定は拒否されます。チャネル停止の期限は、クリーンアップ全体の期限を超えられません。

<a id="lifecycle-and-storage"></a>

## ライフサイクルとストレージ

レジストリは組織、名前空間、ソース ID の順に並べられているため、名前空間の読み取りは物理キー範囲を絞り込めます。メンテナンスのスキャンも同じ順序で進みます。レジストリには、完全な ID タプル、サーバーが付与したアクター、導出されたプロビナンスが保存されます。シークレットには用途に束縛された暗号化を使用し、再暗号化の対象になります。通常のソース読み取りや監査の対象には、トークンやチャレンジは含まれません。管理者のセットアップ読み取りは冪等性リプレイの保存を経由しないため、表示された保留中のチャレンジが、有効化後に通常のキャッシュから再生されることはありません。

ソースの削除、認証情報のローテーション、アイテムの更新、名前空間の廃止は、同じソースリースの下でプッシュのセットアップを廃止します。遅れて届く外部の watch 応答が、廃止されたセットアップを復活させることはできません。名前空間の消去は、既存の確定型消去の仕組みを通じて、レジストリのすべてのバージョンを削除します。設定の書き込みには、レジストリの消去ステップを理解するフリートが必要で、読み取れないフリートの場合は拒否されます。このレジストリを持たないビルドへロールバックする前に、プッシュを無効にし、現在のビルドでレジストリの行を消去し、名前空間の消去が完了したことを確認してください。停止できないプロバイダーのチャネルは期限切れになり、廃止されたコールバックはそれらを拒否します。

<a id="alternatives"></a>

## 代替案

プッシュの状態をソースの行に置くと、すべての配信が認証情報の書き込みと競合し、古い認証情報を引き継ぐ危険があります。同期の詳細に置くと、暗号化されたセットアップのシークレットが通常の確認用出力と混ざります。別のレジストリを使うことで、どちらも避けられます。通知はヒントにすぎないため、永続的なイベントキュー、プロバイダーのペイロードのアーカイブ、2 つ目の取り込み経路は不要です。

<a id="provider-contracts"></a>

## プロバイダーの仕様

- [Drive のプッシュ通知](https://developers.google.com/workspace/drive/api/guides/push)
- [Drive のユーザーログと共有ドライブのログ](https://developers.google.com/workspace/drive/api/guides/about-changes)
- [Notion の webhook 検証](https://developers.notion.com/reference/webhooks)
- [Notion のイベント配信](https://developers.notion.com/reference/webhooks-events-delivery)
- [Linear の webhook 検証](https://linear.app/developers/webhooks)
