ファイル
btrc-hub/docs/static-mirror.md
T

226 行
18 KiB
Markdown

# Static Mirror PoC (#483)
現在の公開状態の一部を、Rails で HTML にして ZIP 出力する開発環境専用の PoC。
Post は ID・タイトル・URL・出力済み Tag との関連、Tag は ID・カテゴリ・全言語の
名前と別名・出力済み Post との関連を出力する。それ以外の Post / Tag 属性は対象外。
DB backup / restore とは別機能で、日時指定の復元機能はない。
本番環境では全 API が 404 になる。依存パッケージ・DB schema の変更はない。
## 操作
既存のローカル開発用 MySQL 設定と locale 登録を用意した環境で、
`backend/` の `bin/rails server -p 3002` と、`frontend/` の `npm run dev` を使う。
Vite の既存 `/api` proxy は3002番ポートを参照する。これらの起動コマンドは
今回実行していない。DB の準備・migration・依存導入も実行していない。
1. `http://localhost:5173/ja/static-mirror` を開く。開発時の「その他」にもリンクがある。
有効な locale では `/:locale/static-mirror` から利用できる。
2. 「スナップショット生成」を押す。ログインは不要。通常の CSRF、IP BAN、user BAN
の境界を通り、セッションに紐づくジョブを登録する。
3. 状態・処理件数・データ基準時点を確認し、完了後「ZIP ダウンロード」を押す。
4. ZIP を展開し、`archive/` を通常の静的 HTTP サーバーへ配置する。
`/保存版/archive/index.html` のようなサブディレクトリ配置に対応する。
DB、Node.js、原サーバー、外部 API は閲覧先では不要。
一覧・詳細・相互リンクは JavaScript 無効でも利用できる。検索は HTTP 配信した
`search-index.json` を JavaScript が読む。`file://` からの検索は保証しない。
Post はタイトルに加えて、出力対象の関連 Tag の全言語名・別名から検索できる。
非公開・廃止・件数上限外の Tag や、関連しない Tag の名前は Post の検索項目に含めない。
外部動画・画像・サムネール・素材ファイルは取得も同梱もしない。Post の外部 URL は
通常のリンクとして残すため、そのリンク先の閲覧は外部サイトの存続に依存する。
各 HTML に静的保存版の表示、UTC のデータ基準時点、`noindex, nofollow`、
本家への絶対リンクを焼き込む。内部リンク・CSS・JS は相対参照。
本家リンクの初期オリジンは `https://hub.nizika.monster`。request の Host、
forwarded header、API のオリジンは採用しない。
`archive-config.js` の `window.archiveConfig.origin` を HTTP(S) の本家基点 URL
(例: `https://example.org`)に変更すれば本家リンクをまとめて変更できる。
設定 JS が削除・欠落・不正な場合や JS 無効時にも HTML の初期リンクが残る。
設定は配置先ミラーの URL ではなく、本家の基点を指す。
## API と処理上限
| API | 役割 |
| --- | --- |
| `GET /static_mirror` | 件数・容量・実行制限と対象外機能 |
| `POST /static_mirror/jobs` | 現在状態のジョブ登録。入力は `locale` のみ |
| `GET /static_mirror/jobs/:id` | 所有セッションの状態・処理進捗・基準時点・失敗コード |
| `GET /static_mirror/files/:id` | 所有セッションの完成 ZIP を再認可して取得 |
通常どおりフロントエンドの API transport と Query key を使用する。
URL に JSON を格納しない。`at` 等の任意時点入力・未知の生成オプションは400で拒否する。
- Post / Tag は各100件。公開認可後に ID 昇順で選ぶ。非公開件数や全母集団件数は返さない。
- 対象 Tag の全言語名・別名は最大2,000行。超過時は失敗させ、黙って切り捨てない。
言語・文字体系は保持し、表示対象言語に登録がない場合は ID を使う。
- Post と Tag の関連は両者が出力集合にあるものだけ。出力外への内部リンクは生成しない。
- 展開後のファイル合計及び ZIP は各8 MiB 以下。超過時は配布しない。
- 同時実行1件、全セッションを通じて新規登録は60秒に1件、登録から処理期限60秒。
競合・受付制限は429と `Retry-After`。状態取得・取得時の短いロック競合は503。
- ZIP とジョブの認可期限は10分。次のジョブ登録で前の ZIP / ジョブは置き換える。
queued / running の予約は cooldown が過ぎても置き換えない。75秒を超えた予約は
状態取得又は次の受付で failed にし、実行ロックが空いている場合だけ次を受け付ける。
期限後も最後のファイルがディスクに残り得るが、API では取得できない。
容量は単一 ZIP と作業ファイルに限定され、無制限に蓄積しない。
Rails の既存 Active Job と `:async` adapter を使い、生成は HTTP request の外で行う。
既存 `CountsExportJobs` は Counts の入力・投影・配信確認に結合しているため変更せず、
本機能の状態・単一成果物の管理だけを feature 固有の Job に置く。
受付・状態・ZIP は `backend/tmp/static_mirror/` の単一 spool を使う。
プロセス間の filesystem lock で実行枠と更新を制御する。各ファイルは0600、directory は
0700で作成する。Web プロセス再起動で非永続キューが失われる点が PoC の限界。
進まない queued / running は75秒経過後の状態取得又は次の受付で failed になる。
worker は受付中の短い実行ロック競合を待ち、競合だけを理由に queued を放棄しない。
再開や再実行はしない。実行ロック待ちも登録からの60秒の処理期限に含まれる。
失敗コードは `too_large`、`generation_timeout`、`publication_changed`、
`generation_failed`、`worker_stopped`。内部の例外本文・パス・資源属性は応答に含めない。
画面では失敗コード又は既存の通信・認可エラー文言を表示する。
## 公開制御と整合性
生成者の role によらず `HistoryAccess.set(user: nil)` の公開権限を使う。
既存の `HistoryAccess.current` と確定済みの同一 `version_no` の存在確認を組み合わせる。
独自の role 判定や簡易な除票判定は作らない。対応する immutable revision がない
legacy record は安全側で対象外とする。公開不可の参照を含む確定版も既存認可で除外する。
廃止 Tag は対象外。HTML / 検索 JSON / manifest の件数には認可済みの出力集合だけが入る。
user、actor、履歴版番号、監査、認証、blob 情報は投影しない。
公開条件の調査範囲は V1 の Post / Tag / TagName / Locale の model、schema、
閲覧 controller・representation、HistoryAccess と Material の抑止経路。
Post / Tag / TagName には別の private / visibility カラムや、汎用の公開抑止 scope は
見つからなかった。Tag の `deprecated_at` は除票とは別の廃止状態で、通常の Post
表示からも除外されるため、ミラーから引き続き除外する。Locale の廃止後も配布しない。
`MaterialImportBlock`、`MaterialSyncSuppression` は著作権・個人情報等を理由にした
素材取込・同期の抑止であり、Post / Tag の汎用認可として流用しない。Material と
関連ファイル・監査用の理由・同期元情報は全て出力対象外のままにする。
既存の通常 Post / Tag 閲覧経路が共通認可を一律適用しているとは仮定せず、
ミラー自身は必ず HistoryAccess を経由する。新たな抑止条件を導入する場合には
適用範囲を確認して共通認可と静的配布契約を更新する必要がある。
`CountsExporter.with_read_snapshot` の既存 repeatable-read 境界を再利用し、Post、Tag、
全言語 TagName、PostTag、publication revision を同じ読み取り view から取得する。
これには既存 HistoryAccess の SQL が動作する MySQL 環境が必要。未対応の adapter や
未整備の DB では生成失敗とし、認可を迂回した出力へフォールバックしない。
`data_at` は DB 読み取り transaction を要求する直前の、取得処理開始時の
サーバー時計(UTC)。manifest の `data_at_basis: capture_started_at` に意味を記録する。
MySQL の read view は後の最初の consistent read で成立するため、その厳密な成立時刻や
`data_at` 以前のコミットだけを含むことは保証しない。履歴の指定日時復元も表さない。
独立した worker では repeatable-read を開始するが、呼出元の transaction がある場合は
既存 helper の契約どおり、その transaction の view と分離レベルを引き継ぐ。
`generated_at` はファイル生成後の別の時刻。
静的配布契約は `StaticMirror::PUBLICATION_POLICY` の
`static-mirror-public-projection-1`。Counts 用 `HistoryAccess::ARTIFACT_POLICY`、
`authority`、`authorised_artifact?` は使わない。共通 HistoryAccess の現在版認可と
全後続除票の revision 検知は再利用し、集計件数の例外や admin の配布モードは設けない。
旧 Counts 契約の metadata しかない ZIP は再生成を必要とする。
生成の最後と状態・ZIP 取得時に、別の読み取り transaction で共通 discard revision と
出力対象 ID の公開投影を再取得する。SQL query cache を使わず、対象の存在、確定版、
Tag / Locale の廃止、タイトル・URL・category、全言語名・別名・文字体系、関連の変更を
検知する。除票を伴わない訂正・削除も投影 digest の不一致として配布を止める。
対象 ID と digest はサーバー側ジョブ metadata にだけ置き、manifest や API 状態応答へ
出さない。対象は各100件・名前2,000行以内の一括取得で、行ごとの追加 query は行わない。
生成中の除票は失敗にし、生成後の除票では古い ZIP の再取得を404にする。
ZIP は再認可後のバイト列として返し、遅延 sendfile に古いパスを渡さない。
HTTP 応答は既存境界の `private, no-store`。ダウンロード済み ZIP の回収や、
最終認可と送出の間に発生する公開制御変更の完全な排他は保証できない。
新しい公開制御を導入する場合は共通 policy と静的配布契約の連動が必要。
本文・名前・URL は escape する。外部リンクは HTTP(S)・host・userinfo 不在を検証し、
不正な URL はリンクとして出さない。外部 URL の取得は行わないため SSRF 用 DNS 検査を
流用しない。HTML の CSP は外部スクリプト・画像・通信を許可しない。
`manifest.json` に形式版、生成日時、基準時点、locale、出力件数、対象外項目、上限、
各ファイルの相対パスと SHA-256 を記録する。自己ハッシュは成立しないため manifest
自身だけは一覧の対象外とし、`checksum_scope` にその範囲を記録する。
## 過去時点復元の調査
- `post_versions` / `tag_versions` は親 ID と正の `version_no` に一意制約があり、
readonly の `VersionRecord` を使う。`created_at <= 時点` の中で最大の確定版を
選ぶことは可能。同一時刻の順序は時刻だけで決めず版番号を併用する必要がある。
- Tag は `names` に言語別の名前・script・別名を保存する。古い行の移行では
日本語として backfill し、旧 aliases 文字列を分割している。失われた区切りや
当時未記録の他言語名を現在の TagName で補完して正確と称することはできない。
- Post は `tags_json`、区間、Tag 版参照、`parent_post_ids` を、Tag は
`parent_tag_ids` を記録する。ただし legacy `tags_json` は名前・時刻からの補完を
含む。全時代・全書き込み経路の関係変更の完全性を検証する必要がある。
外部 Tag 名の現行参照など、immutable history だけでは揃わない値もある。
- Tag Description は `(tag_id, language_code, version_no)` の版に本文と翻訳元を記録する。
Material にはファイル情報等の版があるが、blob 本体の永久保存や除票・公開抑止との
整合は別途必要。Help はフロントエンドの文書配信に依存し、DB の任意時点だけでは
当時の公開版を復元できない。
- 当時の publication policy そのものや将来追加される公開抑止の完全な履歴は、
これらの内容版だけでは保証できない。指定時点の再現と現在の公開許可を別々に評価し、
現在の全後続除票境界を版番号と複合キーで適用する必要がある。恢復しても過去の
秘匿履歴を再公開しない。Counts の件数例外はこの機能へ拡張しない。
- 正確な時点復元には、全 resource の履歴の起点・欠落・backfill の識別、関係・名前・
policy・locale・asset の時点整合性、immutable な Help の版、削除済み asset の保存方針、
一つの DB read view と現在の認可の再検証、同時刻更新の順序・境界の設計が必要。
このため日時入力は実装していない。履歴評価はソース調査であり、実 DB の網羅監査ではない。
## 検証と残課題
追加した回帰テスト:
- `backend/spec/services/static_mirror_spec.rb`: ZIP の CRC / 構造、全ファイルの hash、
内部参照、escape、基準時点、公開権限、後続除票、言語名・別名、容量・件数上限。
今回は Counts 契約との独立性、除票なしの訂正・廃止・関連変更、取得開始時刻の意味、
Post 検索への関連名の投影を追加。
- `backend/spec/requests/static_mirrors_spec.rb`: 一般受付、非同期境界、所有権、
公開制御変更、失敗・期限・競合・全体 rate limit、開発環境制限、CSRF と BAN。
今回は Host に依存しない本家リンク、訂正後の取得拒否、queued 予約の保持・期限切れ、
実 filesystem lock を使う受付競合待ちを追加。
- `frontend/src/pages/StaticMirrorPage.test.tsx`: 開始、進捗、取得、失敗、
受付エラー、認可喪失、日本語 fallback の言語属性。
- `frontend/src/lib/staticMirrorAssets.test.ts`: 静的検索の相対参照・escape と
サブディレクトリ配備、本家設定の欠落・不正・変更。
今回は Tag 名・別名から関連 Post が見つかるケースを追加。検索 JS の変更は不要。
実施したのは既存コードの調査、差分の目視確認と `git diff --check`(成功)。
テスト、lint、build、型検査、
migration、実ブラウザーでの表示、ZIP 展開・HTTP 配置は実行していない。
管理者指定の suite による結果確認と、サブディレクトリ配置・JS 無効・原サーバー停止・
設定 JS 欠落・静的検索の実画面確認が残る。
本番公開には durable な worker / queue、復旧・取消・削除と運用監視、適切な利用者別
rate limit、容量・時間・負荷の実測、公開制御の監査と変更検知、長時間配信の再認可方針、
asset の権利・保管方針、追加 resource の安全な投影、UI 文言・翻訳の確定が必要。
本 PoC の開発環境制限を単に外して公開することは想定しない。
## 今回のレビュー対応の変更ファイル
| ファイル | 修正と理由 |
| --- | --- |
| `backend/app/controllers/static_mirrors_controller.rb` | request オリジンを生成処理へ渡さず、本家リンクへの Host 混入を防止 |
| `backend/app/jobs/static_mirror_job.rb` | 静的配布専用の再認可、queued 予約と期限切れの共通処理、worker のロック待ちでジョブ消失を防止 |
| `backend/app/services/static_mirror.rb` | Counts と独立した公開投影の再検証、関連 Tag 名を含む Post 検索、正規の本家リンク初期値、`data_at_basis` |
| `backend/spec/services/static_mirror_spec.rb` | 専用契約・訂正・廃止・関連変更・検索投影・時刻意味の回帰テスト |
| `backend/spec/requests/static_mirrors_spec.rb` | 本家オリジン・ZIP 再認可・queued 予約・実行ロック競合の回帰テスト |
| `frontend/src/lib/staticMirrorAssets.test.ts` | 名前・別名を使う Post 検索の回帰テスト |
| `docs/static-mirror.md` | 公開条件の調査結果、配布契約、ロックと時刻の保証範囲・未解決事項を更新 |
V2、DB schema / migration、既存の Counts 契約・共通認可、UI 文言は変更していない。
## 変更ファイルの責務
| ファイル | 責務 |
| --- | --- |
| `backend/config/routes.rb` | metadata・job・ZIP の4経路 |
| `backend/app/controllers/static_mirrors_controller.rb` | 通常認証境界、開発制限、入力・HTTP 応答 |
| `backend/app/jobs/static_mirror_job.rb` | 単一生成枠、受付制限、状態・成果物・期限・取得認可 |
| `backend/app/services/static_mirror.rb` | 公開データの一貫した投影、ページ・検索・manifest・ZIP |
| `backend/app/views/static_mirror/page.html.erb` | escape 済み HTML、ナビ、基準時点・本家リンク・CSP |
| `backend/app/views/static_mirror/archive.css` | 静的サイトの読み取り表示 |
| `backend/app/views/static_mirror/archive.js` | ローカル検索と本家リンクの設定変更 |
| `frontend/src/App.tsx` | locale 付き操作画面経路 |
| `frontend/src/lib/queryKeys.ts` | 既存 Query key entrypoint への追加 |
| `frontend/src/pages/StaticMirrorPage.tsx` | 開始・制限・進捗・失敗・ZIP 操作 |
| `frontend/src/pages/MorePage.tsx` | 開発時の画面への導線 |
| `frontend/src/locales/{ja,ain-Kana}/archive.json` | Issue 指定の文言と未翻訳 fallback |
| 上記4テストファイル | 回帰テスト |
| `docs/static-mirror.md` | 手順・制約・調査・未検証事項 |