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

170 行
13 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 の外部 URL は
通常のリンクとして残すため、そのリンク先の閲覧は外部サイトの存続に依存する。
各 HTML に静的保存版の表示、UTC のデータ基準時点、`noindex, nofollow`、
本家への絶対リンクを焼き込む。内部リンク・CSS・JS は相対参照。
`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 / ジョブは置き換える。
期限後も最後のファイルがディスクに残り得るが、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 になる。再開や再実行はしない。
失敗コードは `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 情報は投影しない。
`CountsExporter.with_read_snapshot` の既存 repeatable-read 境界を再利用し、Post、Tag、
全言語 TagName、PostTag、publication revision を同じ読み取り view から取得する。
これには既存 HistoryAccess の SQL が動作する MySQL 環境が必要。未対応の adapter や
未整備の DB では生成失敗とし、認可を迂回した出力へフォールバックしない。
`data_at` はこの現在状態読み取りの開始時刻であり、履歴の指定日時復元を表さない。
`generated_at` はファイル生成後の別の時刻。
生成の最後と状態・ZIP 取得時に既存 artifact policy / discard revision を再検証する。
生成中の除票は失敗にし、生成後の除票では古い ZIP の再取得を404にする。
ZIP は再認可後のバイト列として返し、遅延 sendfile に古いパスを渡さない。
HTTP 応答は既存境界の `private, no-store`。ダウンロード済み ZIP の回収や、
最終認可と送出の間に発生する公開制御変更の完全な排他は保証できない。
新しい公開制御を導入する場合は共通 policy と artifact revision の連動が必要。
本文・名前・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、基準時点、公開権限、後続除票、言語名・別名、容量・件数上限。
- `backend/spec/requests/static_mirrors_spec.rb`: 一般受付、非同期境界、所有権、
公開制御変更、失敗・期限・競合・全体 rate limit、開発環境制限、CSRF と BAN。
- `frontend/src/pages/StaticMirrorPage.test.tsx`: 開始、進捗、取得、失敗、
受付エラー、認可喪失、日本語 fallback の言語属性。
- `frontend/src/lib/staticMirrorAssets.test.ts`: 静的検索の相対参照・escape と
サブディレクトリ配備、本家設定の欠落・不正・変更。
実施したのは既存コードの調査と差分の目視確認のみ。テスト、lint、build、型検査、
migration、実ブラウザーでの表示、ZIP 展開・HTTP 配置は実行していない。
管理者指定の suite による結果確認と、サブディレクトリ配置・JS 無効・原サーバー停止・
設定 JS 欠落・静的検索の実画面確認が残る。
本番公開には durable な worker / queue、復旧・取消・削除と運用監視、適切な利用者別
rate limit、容量・時間・負荷の実測、公開制御の監査と変更検知、長時間配信の再認可方針、
asset の権利・保管方針、追加 resource の安全な投影、UI 文言・翻訳の確定が必要。
本 PoC の開発環境制限を単に外して公開することは想定しない。
## 変更ファイルの責務
| ファイル | 責務 |
| --- | --- |
| `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` | 手順・制約・調査・未検証事項 |