Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
105 lines
7.0 KiB
Markdown
105 lines
7.0 KiB
Markdown
# Zombie GC: 原子性・Domain 境界・instance maintenance
|
|
|
|
更新: 2026-09-14
|
|
|
|
## 修正した問題
|
|
|
|
旧実装は全インスタンスの候補を transaction 外で取得し、その UUID の
|
|
Revision/Object を無条件に削除していた。WAL reader の候補取得後に別 connection
|
|
が Path/Asset/本文 Revision を追加すると、その変更を無視して削除できた。
|
|
また Domain 管理者の HTTP/config 操作が同じ global purge を呼び出していた。
|
|
|
|
## 候補の定義
|
|
|
|
Object の作成時刻が指定した猶予期間より古く、次の全条件を満たすものに限定する。
|
|
|
|
- **すべての Domain** において Path と Asset 所有者の参照がない。
|
|
- Revision がない、または **全 Revision** の本文 bytes と Document hash が空である。
|
|
空 Document の SHA-256 は空として扱うが、非空の inline body を上書きしない。
|
|
NUL を含む本文も BLOB byte length で保護する。HEAD だけの判定は禁止する。
|
|
- `revision_document_refs`、City の明示ページ参照・Street inbox・ページ配置 override、
|
|
exact Object capability grant、未期限切れの連携エディタ ticket/session がない。
|
|
|
|
後半の参照は保守的に保護する。Path だけ消しても、意味的に保持している空ページや
|
|
編集中のページを自動削除しない。期限切れ editor session の bookkeeping は削除時に清掃する。
|
|
|
|
## 権限境界
|
|
|
|
| 呼び出し元 | 範囲 |
|
|
| --- | --- |
|
|
| `GET /_/api/v1/gc/zombies/list` | current Domain の作成 provenance がある候補のみ |
|
|
| `POST /_/api/v1/gc/zombies/purge` | current Domain の作成 provenance がある候補のみ |
|
|
| 設定画面の一覧・`section=zombie-purge` | 同じ Domain 制約 |
|
|
| ローカルの trusted CLI/store maintenance | インスタンス全体 |
|
|
| ビルトイン 6 時間周期 GC worker | インスタンス全体 |
|
|
|
|
HTTP 呼び出しは `object_origins(object_uuid, domain_uuid)` が current Domain に一致する
|
|
ことを必須とする。クエリ・フォームの `domain_uuid` で切り替えない。Campus 管理者でも
|
|
HTTP から global maintenance に昇格しない。legacy/作成元不明 Object は一覧にも出さず、
|
|
HTTP から削除しない。参照がないこと自体を所有権の証拠にはしない。
|
|
|
|
`CreateObjectInDomain` が記録した provenance を利用する。作成元を記録していない
|
|
既存データや旧作成経路を、現在の default Domain に推測で backfill してはならない。
|
|
こうしたデータの整理は trusted instance maintenance の範囲とする。
|
|
|
|
現在 `runEvent` に global GC の event type は登録しない。HTTP から任意の event type
|
|
を保存・手動起動しても、`gc.purge` 等は worker で unknown type として失敗し、削除しない。
|
|
将来 GC を scheduler に統合する場合、サーバー内部だけが設定できる trusted origin と、
|
|
Domain provenance を持つ手動 payload の区別を先に設計する必要がある。
|
|
|
|
## 書き込み原子性と上限
|
|
|
|
`BeginTx(ctx)` の直後、`zombie_gc_maintenance` の一行を UPDATE し、SQLite の writer lock
|
|
を取得してから候補を選ぶ。同じ write transaction 内で UUID ごとに全条件と provenance を
|
|
再検証し、関連 bookkeeping/Revision/Object を削除する。候補抽出から commit まで他 connection
|
|
の書き込みが入らない。失敗・キャンセル時にはバッチ全体を rollback し、成功件数を返さない。
|
|
|
|
Domain 一覧は indexed `object_origins(domain_uuid, object_uuid)` から検索を開始する。
|
|
他 Domain の全 Object を走査しない。候補上限は SQL `LIMIT` に置き、Go の後処理 slice
|
|
で制限してはならない。各参照検索には Object/Page UUID の lookup index を用意する。
|
|
|
|
- HTTP/config の既定バッチ: 100 件。
|
|
- 最大: 1,000 件。HTTP の `limit=0`・負数・最大値超過は 400。
|
|
- trusted store の旧 `limit=0` は無制限にせず既定 100 件とする。
|
|
- trusted 一覧も最大 1,000 件。継続する purge はローカルから明示的に繰り返す。
|
|
- 検索・削除の context は最長 5 秒。HTTP は request context のキャンセルを継承する。
|
|
- SQLite writer の待機も既存 busy timeout の 5 秒内。重い history の走査が期限に
|
|
達したときは、不完全な候補判定で削除せず失敗する。
|
|
|
|
Foreign key enforcement が無効な legacy connection でも整合性を保つよう、
|
|
`object_origins` 等は明示的に清掃する。Revision の検索 index は既存の transaction 内
|
|
trigger で追従する。CAS 本体のファイル削除はこの GC では行わない。
|
|
|
|
`BindPathInDomain` と Revision の INSERT も、同じ書き込み SQL に
|
|
`WHERE EXISTS(SELECT ... FROM objects)` と `RowsAffected` の検証を置く。
|
|
GC が先に commit した場合は `ErrPageNotFound` または安全な書き込み競合失敗となり、
|
|
orphan Path/Revision を作らない。失敗した bind は既存 Path を置換しない。
|
|
`PutAsset` は新規 Object と Asset を同じ transaction で作成しており、別途変更は不要。
|
|
|
|
## global worker の猶予期間
|
|
|
|
既定の **24 時間** と **6 時間ごとの実行** は維持する。今回の変更によって従来より
|
|
短い猶予へ移行させない。
|
|
|
|
起動時に、従来の default Domain の `zombie_grace_hours`、24 時間、永続保持済み値、
|
|
operator 環境変数 `PAGESWIKI_ZOMBIE_GC_GRACE_HOURS` の最大値を採用し、
|
|
`zombie_gc_maintenance.grace_seconds` に high-water mark として保存する。
|
|
Domain の UI 設定がその後短縮されても、再起動しても、この値は小さくならない。
|
|
Domain の設定は Domain 内の手動 purge に適用され、稼働中の global worker は変更しない。
|
|
|
|
より長い operator 環境設定は再起動時に継承できる。短縮のための HTTP/API は提供しない。
|
|
従来設定の読み込み失敗・不正な operator 環境設定では global worker を停止しログに残す。
|
|
時間から秒への整数 overflow で削除が早まることも防止する。
|
|
|
|
## 回帰テスト
|
|
|
|
- WAL の別 connection が Path・Asset・非空 Revision を未 commit のまま追加し、
|
|
GC を開始した後で commit しても Object が保持される。
|
|
- 作成元が foreign/unknown の Object は管理画面/API から見えず、削除できない。
|
|
- 他 Domain の Path/Asset、過去 Revision、NUL bytes、CAS hash、明示参照を保持する。
|
|
- 既定/最大/不正 limit、キャンセル、途中 SQL failure の完全 rollback。
|
|
- GC の commit 後の bind・Revision 保存は孤立データを作らない。Revision は
|
|
テスト専用 SQLite view/scalar による制御で、存在確認直後の削除を時刻依存なく再現する。
|
|
- 手動 event の偽装 type から global GC を実行できない。
|
|
- 長い従来設定、Domain 設定変更、再起動、operator 設定、整数 overflow、設定 read failure。
|