Files
pages/docs/design/ja/geduldh.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts.

Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation.

Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
2026-11-01 15:23:31 +09:00

97 lines
7.1 KiB
Markdown

# Geduldh の文書保存契約
2026-11-01、ローカルDocument Storeと一時展開の初期分離を実装。
GeduldhはSHA-256で識別する不変の文書バイト列を保存・取得・検証する。
従来の `internal/documentstore` の実装を移し、保存形式、DBスキーマ、公開URLは変えない。
名称の位置付けは [コンポーネント命名と責務](component-names.md)、
外部ストレージと運用の計画は [保存基盤の多様化](../storage-portability-and-operations.md) を参照。
## 実装と責務
| 層 | 所有するもの | 所有しないもの |
| --- | --- | --- |
| `internal/geduldh` | Store契約、ローカルpayload、保存キー、サイズ・hash検証、容量制限付き一時展開 | SQL、認証・認可、Page/Revision、GCの削除判断 |
| `internal/documentstore` | 旧公開型のalias、旧コンストラクター・Keyの委譲 | 独自の保存実装・検証ロジック |
| `internal/store` | Revisionと参照のtransaction、DB-only互換、バックフィルのidentity・checkpoint、read-only運用 | 別実装のローカルpayload writer |
| server / DR / CLI | 認可後の配信、外部ツール、保全・復元の手順 | hashを知っていることによる認可の省略 |
アプリケーションと旧入口からGeduldhへの一方向依存とする。Geduldhからstore、DB、
server、旧documentstoreへ戻る参照は作らない。HTTPレスポンスや権限判定も持たせない。
`Component = "geduldh"` は内部の固定識別名であり、保存ディレクトリやサービス名ではない。
## 保存と取得の契約
`geduldh.Store` は既存の `documentstore.Store` と同じ型として扱える。
| 操作 | 契約 |
| --- | --- |
| `Stat(ctx, hash)` | 正規化したhashとバイト数を返す。内容全体の検証ではない |
| `Open(ctx, hash)` | `Read`、`ReadAt`、`Seek`、`Close` に対応するReaderを返す。全体を先読みしない |
| `PutIfAbsent(ctx, hash, size, reader)` | サイズとSHA-256を検証し、完全なpayloadだけを上書きせず公開する |
| `Verify(ctx, hash)` | ストリーム全体を読み、SHA-256の一致を検証する |
通常の `Open` / `Stat` は全体をhash検証しない。Range配信やZIPの部分読み取りで
ファイル全体の走査を強制しないためである。検証が必要な経路は `Verify` または検証付き
Materializerを選ぶ。既存のRevision本文取得時のhash検査はstore側に残る。
保存キーは `sha256/<hashの先頭2文字>/<64桁hash>`、ルートは既存の `documents`。
hashの前後空白の除去・小文字化、既存エラーの同一性を維持する。Path、ファイル名、
Domain、言語、Revision UUIDは保存キーに混ぜない。配置の変更で公開URLやETagを変えない。
ローカル保存はルート内アクセス、64 KiB単位の検証コピー、一時ファイル、ファイルfsync、
hardlinkによるno-replace公開、ディレクトリfsyncを維持する。
既存payloadは再検証し、破損していても入力で上書き修復しない。
`NewLocal` は保存先を作成しない。ルートの準備とバックフィルは起動・運用側の責務とする。
書込みではpayloadの永続化を先に完了し、その参照を持つRevisionのDB transactionを
後で確定する。DB側の競合・rollbackで未参照payloadが残ることは許容する。
Geduldhは参照数を判断せず、`Store` にDeleteを設けない。GCは保持・参照・backup pinを
判断する別の経路とし、今回の分離では変更しない。
## 外部ツール用の一時コピー
`Materializer.Acquire` は同じhashの取得を共有し、検証済みのノードローカルコピーを
`Lease` で返す。ここでのleaseは一時ファイルの利用権であり、分散ジョブの期限付きリースではない。
最後の利用者がCloseするとコピーを削除する。正本のhardlinkを外部ツールへ渡さない。
一人の待機中断で他の利用者を巻き込まず、全員が中断した場合は取得を取り消す。
既存アプリケーションの上限を維持する:同時取得2件、待機・利用中を含め64件、
予約容量合計2 GiB、共有取得期限2分。呼出し側のファイル単位上限とcontextも適用する。
一時ディレクトリは0700、コピーは0400。削除失敗時には予約容量を解放済みと扱わない。
これらはアクセス元アプリケーションの設定であり、外部ストレージ対応の宣言ではない。
## 互換性と今回の変更範囲
- 旧documentstoreの型・エラーはalias、関数はGeduldhへの委譲とし、実装を二重に持たない。
- storeの保存、読み取り、サイズ・部分取得、一時展開はGeduldhへ接続する。
- `.document-store-id`、バックフィルのUUID cursor、DB-only互換、起動時移行は変更しない。
- DR manifest、スナップショットの構造、復元手順、保存済みデータは変更しない。
- UI、URI、設定キー、イメージ名、イベント型、consumer checkpointは変更しない。
これは既存の保存実装の分離であり、新たなファイル移行・DB migrationを必要としない。
任意のmount先での永続性、外部backend、マルチノードHAを追加するものではない。
## 残件
- [ ] S3 / SFTPなどのbackendを、条件付き作成・部分取得・破損・切断の共通契約試験を経て追加する。
- [ ] NFS / SMB / SSHFSはno-replace公開・fsync・mount喪失の実環境試験を行う。ローカルパスであるだけで対応済みとしない。
- [ ] 旧Revision保存・本文取得を含む全経路へcontextを伝播する。
- [ ] payload、可変正本、秘密情報、scratchの配置設定を分離する。
- [ ] 一時展開の上限を設定化し、削除失敗・クラッシュ残骸の安全な回収とメトリクスを追加する。
- [ ] Documentのサイズをメタデータ化し、外部backend導入時の一覧のStat/HEAD多発を防ぐ。
- [ ] GCの参照snapshot・保持・backup pinと、外部ストレージの削除契約を整備する。
## 検証
合成payloadと一時DB・ディレクトリで、次を検証する。
- 移動前レイアウトの読み取り、新旧入口の型・エラー・キー互換、既存inodeの保持。
- 並行書込み、不完全入力・既存破損の拒否、キャンセル、ルート外へのsymlink逸脱防止。
- Range / ReaderAtと逐次読み取りの独立性、ZIP配信、認可を伴う不変オブジェクト配信。
- 一時コピーの共有、容量・件数・時間制限、最終Closeでの削除、正本からの分離。
- 永続化失敗時のRevision非確定、metadata競合時の正本保全、バックフィルの再開。
- Geduldhで保存 → 既存DR snapshot → verify → restore → Geduldhで検証・読取り。
実行結果は [コンポーネントの検証記録](component-names.md#検証記録) に記載する。
本番データの操作、commit・push・本番展開はこの初期分離には含めない。