GitHub トラッカーフィード
GitHub トラッカーフィード
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
GitHub フィードは、チームのトラッカーレコードをチームの ClickHouse データベース内に維持します。Loom の serving プロセスは、そのレコードを既存の読み取り専用トラッカーソースを通じて読み取ります。フィードは、issue 本文、コメント、プルリクエストを Loom のデプロイメントテーブルには置きません。
所有権と認証情報
オペレーターは、フィードを有限のCLIジョブとして実行します。ジョブはチームのジョブランナーがスケジュールします。登録済みエンドポイントを読み取る前、またはレコードを開く前に、CLI は実際のデプロイメントが選択した権威あるデータストア(ClickHouse または Postgres のバックエンド)であるかどうか、およびそのセルがフィード組織を保持しているかどうかを確認します。外部接続でもこのデプロイメントのゲートを繰り返し確認します。レコードのメタデータをデプロイメントの権限として扱うことはありません。ジョブは終了時に、両方のクライアントとデプロイメントの Postgres プールを閉じます。 初期化では、空の専用データベースにフィードテーブルとコントラクトビューを作成します。既存のオブジェクトがある場合は拒否します。その後、オペレーターはそのデータベースを、別個の読み取り専用認証情報を持つトラッカーソースとして登録します。設定と同期には、その登録済みエンドポイントとリポジトリの許可リストが必要です。別途用意された書き込み用認証情報は、チームのフィードデータベースにのみ書き込めます。読み取り用認証情報が昇格されたり、書き込みに再利用されたりすることはありません。
ソースの認証情報は、設定済みのリポジトリに限定された、読み取り専用のファイングレイン GitHub トークン、または App インストールトークンです。権限は Metadata、Issues、Pull requests で、すべて読み取り専用です。トークンの権限はオペレーターが保証する設定です。GET の成功、トークンのプレフィックス、エンドポイント権限ヘッダーでは、書き込み権限が付与されていないことを証明できません。識別できないホストトークンは、読み取り専用のライブプローブの対象になりません。トークンは、チームのフィード設定テーブルに既存の secret-root の仕組みで封印されます。トークンが引数、出力、コントラクトビューに現れることはありません。
CLI は、データベースの書き込み用パスワードを名前付き環境変数から受け取ります。このパスワードを永続化することはありません。GitHub へのリクエストは、固定の https://api.github.com オリジンに対する GET を使い、リダイレクトを拒否し、検証済みのリポジトリ名と数値の項目 id からパスを構築します。レスポンス内の URL をたどることはありません。
チームは、コピーされたレコード、そのバックアップの保持、および消去を所有します。コピーされたコンテンツを消去するには、チームはスケジュールされた書き込みを停止し、対象のフィード行、コメント、チェックポイントを削除してから、除外設定を加えて再開するか、ソースリポジトリを削除します。Loom の名前空間を削除すると、Loom の派生データと権限付与は破棄されますが、チームのレコードは削除されません。これは、登録済みのどのトラッカーデータベースとも同じ境界です。レコード書き込み用の認証情報は Loom 自身のデータベースにアクセスできず、コピーされたコンテンツがそこに書き込まれることはありません。ローカルなのは、既存のデプロイメントストアのリースだけです。
レコードと進捗
生の項目とコメントは、チームのデータベースにバージョン付きで保存され、識別タプル、プロセスアクター、インポートされたソースクラスが付随します。コントラクトビューは、最新の項目バージョン、コントラクト UUID、有効な可視性を公開します。issue とプルリクエストのコメントは別々に保持され、対応する項目の検索可能な本文に含まれます。未対応のトリアージフィールドにはコントラクトの型付きデフォルト値を使い、エッジは根拠が得られるまで空です。
コントラクトの updated_at は、項目とそのコメントにわたる、永続化された最新の公開タイムスタンプです。そのため、遅れて取り込まれたデータやコメントの編集によって、増分のトラッカー読み取りが進みます。公開バージョンはトラッカーのカーソルに合わせてミリ秒単位の整数を使います。レコードの書き込みリースのもとで、各コンテンツバッチは、レコードのクロックと、その組織について永続化されたすべてのリポジトリのコンテンツバージョンより 1 ミリ秒後の値のうち、遅い方を受け取ります。この順序付けは、1 つのカーソルで複数のリポジトリを読み取る名前空間にも適用されます。
リポジトリの制御書き込みも同様に、受信側のクロックが逆戻りしても、その組織とリポジトリに対して永続化されたバージョンより先に進みます。そのため、可視性の取り消し、認証情報のローテーション、カーソルのチェックポイントは、タイムスタンプで負けることなく、以前の制御行を置き換えます。
上流の生のタイムスタンプは別に保持され、API カーソルを駆動します。モデルや埋め込みの呼び出しは不要です。リポジトリの識別子は、API が異なる大文字小文字を返した場合でも、登録済みの許可リストの綴りを保持します。
オーナー、リポジトリリビジョン、公開ウォーターマークの読み取りは select_sequential_consistency = 1 を要求します。書き込みリースだけでは、レプリカが最新になるとは限りません。フィードの書き込みには、SharedMergeTree ストレージ、またはシングルのセルフホストサーバーが必要です。これはread-your-writes の保証に従います(read-your-writes:確認応答された書き込みは、呼び出し元のその後の読み取りで可視になります)。この設定だけでは、セルフホストのレプリケートテーブルにおける確認応答済みの書き込みはカバーされません。
書き込み側の検証では、接続先のレコードデータベース内にある 5 つのフィードテーブルについて、ReplacingMergeTree と SharedReplacingMergeTree のみを受け付けます。レプリケート、分散、および認識できないテーブルエンジンは、ジョブが公開する前に拒否されます。
各リポジトリは、項目、issue コメント、レビューコメントのそれぞれに独立したカーソルを持ちます。issues エンドポイントは issue とプルリクエストをまとめて列挙し、プルリクエストは数値エンドポイントを通じて詳細を取得します。issue コメントのエンドポイントとレビューコメントのエンドポイントは、それぞれ別個の更新時刻によるスキャンを持ちます。いずれも updated_at の昇順を使い、ページ数、レスポンスのバイト数、リクエスト時間に上限があります。カーソルの前進は、確認応答された書き込みのみに従い、完全なタイムスタンプ境界を通じて行われます。since は排他的なので、リクエストでは保存済みのタイムスタンプを 1 秒戻します。ページ予算を使い切った場合は、最後のページの最も早いタイムスタンプを保存し、次のターンでその境界を再生します。予算は 2〜100 ページです。それ以前のページで進捗が許され、最後のページには不完全なタイムスタンプ境界が残ります。
1 つのタイムスタンプが、設定されたページ予算全体を埋めてしまう場合、ジョブは容量エラーを報告し、行をスキップしたり進捗を主張したりせずにチェックポイントを保持します。オペレーターは、そのリポジトリの上限付きページ予算を引き上げられます。再生された行は同じ識別子を置き換えます。API は変化するコレクションであり、スナップショットではありません。スキャンを重ねることでページネーションの競合は減りますが、上流の読み取りがトランザクション的であるとは主張しません。
各ターンは、コンテンツをコピーする前に、リポジトリの識別子と可視性を検証します。利用できない、移動された、または一致しないリポジトリは、まずそのリポジトリのコントラクト行を非表示にし、そのうえでターンを拒否します。コントラクトビューは、直近に成功した可視性の観測も必要とし、スケジューラーが停止した場合は、一定の間隔の後に失効します。各項目とコメントの公開では、その観測のプライバシー分類を、コンテンツと同じ行に保存します。ビューは、リポジトリ、項目、保存済みコメントのうち最も制限の厳しい分類を、is_private とコントラクト UUID の両方に使用します。そのため、リポジトリのメタデータより先に新しいコンテンツを知ったレプリカが、非公開の公開物を公開と表示することはありません。標準のトラッカーの既存の述語は、これらの行を除外します。制限付きの名前空間は、ライブの直接付与のチェックを維持します。可視性はポーリングによる観測であり、即時の権限ミラーではありません。
検証済みの識別子の不一致や非公開の観測は、別のターンがリビジョンを変更した場合でも、現在のレコードを非表示にできます。これにより、現在の認証情報とカーソルが保たれます。古い認証情報による一般的な失敗では、リビジョンチェックが維持されます。古い公開の観測がアクセスを広げることはありません。
リポジトリが公開になると、設定または同期は、公開メタデータを公開する前に既存のストリームカーソルをリセットします。上限付きのスキャンが項目とコメントを再生し、それぞれに公開の観測を付与します。項目は、自身の行と保存済みコメントが再生されるまで制限付きのままです。スケジュールされたターンを繰り返すことで、同じページとタイムスタンプ境界の制限のもとで、バックログが処理されます。上流で削除された行は再生できません。非公開の分類を解除するには、チームが保持されているそれらのコピーを消去する必要があります。
増分の API リストは、削除された issue やコメントを報告しません。チームがこれらの消去を明示的に処理します。フィードは削除の検出を主張しません。設定、封印された認証情報、カーソルはチームのレコードとともに保持されるため、CLI の再起動はローカルファイルに依存しません。初期化は、レコードを 1 つの Loom デプロイメントのデータベース UUID に結び付けます。設定と同期は、他のデプロイメントを拒否します。そのデプロイメント内の同時実行ジョブは、レコードのデータベース UUID をキーとする 1 つの公開リースを使用し、ソースのエイリアスやリポジトリ名の変更には依存しません。プロバイダーからの取得はそのリースの外で行われます。初期化、設定、公開はリースを共有するため、初回の識別子の同時観測が直列化を回避することはありません。不確定なデータベース書き込みは、上限のあるサーバー送信ウィンドウの間、その要求権を保持します。レコードの消去には、チームが先にすべての書き込みを停止する必要があります。
検証とロールアウト
フェイクにより、ページネーションの同順位、部分的なレスポンス、レート制限、リトライ、可視性の変更、リダイレクト、認証情報のマスキングを検証します。プライベートな ClickHouse で、コントラクト、現在のビュー、再生、中断されたカーソル公開を検証します。読み取り専用トークンが利用できる場合は、上限付きの公開リポジトリの一部を確認します。書き込み可能な CLI トークンが代用されることはありません。 フィードは、Loom のワイヤーオペレーションや自動ワーカーを追加しません。オペレーターがフィードを初期化してスケジュールするまで、既存のデプロイメントと登録済みトラッカーは変わりません。
ソースのエントリポイント
- CLI:
register_tracker_feedと_runが、所有するレコードと別個の書き込み用認証情報を選択します。_validate_writerは権限付与とサポートされるテーブルエンジンを確認します。 - フィードアプリケーション:
initialize、configure、sync、_publishが、所有権を強制し、公開時のプライバシーを付与し、書き込みをフェンスします。 - レコードストア:
statementsがコントラクトビューを定義します。repository、put_repository、put_itemsは公開状態を一貫して読み取ります。 - API クライアント:
pagesが上流のスキャンを制限します。ドメインルールは識別子を検証し、next_cursorを通じて再生の境界を選びます。
不変条件
- コピーされたコンテンツは、チームが消去を所有する登録済みレコード内にとどまります。
- リポジトリの識別子、可視性、リビジョンのチェックは、コンテンツの公開より前に行われます。制御の読み取りには、サポートされるストレージトポロジーにおいて、確認応答されたレコードの書き込みが含まれます。
- コンテンツとそのプライバシー分類は、1 つの生の行バージョンを共有します。コントラクトのプライバシーと UUID は、テーブルが個別に遅れる場合でも、保存されたすべての構成要素の分類を含みます。
- 非公開から公開への移行は、公開の前にカーソルをリセットします。そのため、リトライでは、非公開の分類を早まって落とすことなく、保持されたコンテンツが再生されます。
- レコード全体の書き込みリースは、公開とチェックポイントの書き込みをカバーします。不確定な送信は、確定するまで要求権を保持し、カーソルは確認応答された書き込みの後にのみ前進します。
- ミリ秒単位の整数のコンテンツバージョンは、レコード内のすべてのリポジトリにわたって増加するため、結合された項目とコメントの本文は、既存のトラッカーカーソルから見え続けます。