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.
97 lines
7.1 KiB
Markdown
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・本番展開はこの初期分離には含めない。
|