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.
7.1 KiB
Geduldh の文書保存契約
2026-11-01、ローカルDocument Storeと一時展開の初期分離を実装。
GeduldhはSHA-256で識別する不変の文書バイト列を保存・取得・検証する。
従来の internal/documentstore の実装を移し、保存形式、DBスキーマ、公開URLは変えない。
名称の位置付けは コンポーネント命名と責務、
外部ストレージと運用の計画は 保存基盤の多様化 を参照。
実装と責務
| 層 | 所有するもの | 所有しないもの |
|---|---|---|
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で検証・読取り。
実行結果は コンポーネントの検証記録 に記載する。 本番データの操作、commit・push・本番展開はこの初期分離には含めない。