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.
20 KiB
DR詳細設計:実施計画・受入試験・導入判定
設計版:DR-D1、2026-09-27。詳細設計完了、実装作業は未着手。 ここでいう実装作業はDR-D1の再参加・役割分離protocol。既存のoffline DR CLIは別の初版。 今回の成果物は文書のみであり、DB・migration・本番配置を変更する作業指示ではない。
1. 設計成果物と完了条件
| 成果物 | 本版で定義した範囲 |
|---|---|
| 役割・再参加 | CG/DG/Instance、writer連動境界、identity、状態機械、設定・UI・権限 |
| protocol・同期 | 認証probe、API、authority契約、checkpoint、manifest v3案、切替・失敗時動作 |
| 本書 | 実施順、予定変更箇所、DB別件への接続条件、試験、導入/撤退手順 |
| 初版記録 | 既存機能と制約を保持し、DR-D1と区別 |
- primaryを管理/データに分け、物理保存境界による連動条件を記述。
- 起動・probe・Learning・同期・昇格・preempt・失敗からの再参加を定義。
- 身元、世代、許可、同期内容、承認、未知損失の扱いを定義。
- API入出力、サイズ上限、再試行、冪等性、切替phase、認可主体を定義。
- DBを変更せずに準備できる範囲と、保存担当との合意待ち範囲を分離。
- 実装タスク、依存、合格条件、障害注入試験、導入/撤退条件を定義。
- 実装・実機でのfencing認定・復旧訓練・本番反映。
「詳細設計完了」は実装方針と判断規則を定義した状態であり、未知の本番設備の能力を保証した 意味ではない。RPO/RTO値、ノード数/FQDN、fence機器、容量、鍵保管先は導入時の必須入力として残す。 これらを未設定のまま自動運転へ移行することはできない。
2. DB別件との作業境界
本タスクでは以下を行わない。
- アプリDBへのSELECTを含むアクセス、DBのコピー・バックアップ・復元、schema inspectの実行。
- SQL/DDL/migration/repositoryの編集、コード生成、サーバ起動、CLIによるデータ操作。
- compose、認証鍵、federation token、node設定、稼働コンテナ、外部カレンダーへのアクセス。
- 文書を本番Wikiへアップロードする操作(アップロードもDBへの書き込みになるため)。
読み取る対象は設計書と必要最小限のソースコードだけ。ドキュメントの静的整合性確認を実施する。 別件の変更を前提にDBの物理分割方法やテーブル名を確定させない。
保存担当へ渡すinterface要求は次の通り。応答はSQLの実装ではなく、能力の宣言とテスト結果で受け取る。
| 契約 | 保存担当に確認する事項 | 未提供時の挙動 |
|---|---|---|
| Resource map | metadata/可変正本/署名発行状態が共有するwriter境界 | shared-instance連動のみ |
| Schema inspection | 非破壊・read-onlyでの互換性/世代取得 | 復旧世代をservableにしない |
| Consistent cut | DBとcalendar等を同じ論理時点で固定できる範囲 | 全writer停止snapshotのみ |
| Durable pin | snapshot/GC/転送/再起動を跨ぐ参照保持 | online同期不可 |
| Restore activation | 新generationの検証、root切替、途中停止からの復旧 | 自動復元不可、既存手動手順のみ |
| Manifest apply | 管理内容と受理位置のatomic commit | manifest v3配信不可 |
| Write fencing | 旧許可を実際の書込み先で拒否できるか | 外部fence必須 |
| Durability receipt | client成功応答済み更新がreplica上で永続化された境界 | 自動無損失failover不可 |
| Identity/secret inventory | logical service keyとphysical node keyの区別 | nodeを自動参加させない |
合意前に作業できるのは仕様型、pure state machine、mock provider、観測専用probe、 静的UI/認可契約の設計まで。runtimeへのwrite gate接続も、別件の保存経路を網羅できることを 確認してから行う。この順序は「DBが共有のままでもroleのflagだけ先に動かす」ことを禁止する。
3. 実装タスクと依存順
以下は将来の予定。行が存在しても対象ソースを今回変更しない。
| ID | 実施内容 | 主な変更予定箇所 | 依存 | 完了判定 |
|---|---|---|---|---|
| DR01 | version付き型、ID/epoch/構成検証、resource coupling planner | internal/drの新model/config/planner |
設計D1 | 不正構成・独立不可・未知版を拒否。DB依存なし |
| DR02 | pure state machineとoperation phase reducer、fake clock | internal/drのstate/operation |
DR01 | 不変条件N1〜N10の遷移試験。失敗時はwriterを開かない |
| DR03 | 専用node identity、mTLS/署名/nonce、観測専用probe | internal/drのtransport、server管理route |
DR01 | 未認証/別group/replayを拒否。probeでroleが変わらない |
| DR04 | runtime startup gateの接続、非DR互換、旧CLI禁止 | cmd/pageswiki/main.go、server middleware、store/CLI全writer入口 |
DR02/03+保存経路合意 | 再起動で必ずrecovering。起動修復/workerも許可前にwriteしない |
| DR05 | AuthorityStore interface、manual provider、etcd providerと限定service | internal/drのauthority、専用運用cmd |
DR01/02 | CAS競合/timeout/再起動でgrantが二重にならない |
| DR06 | checkpoint adapter、世代/pin台帳、schema/read-only検証 | 既存internal/dr/snapshot.goと保存担当adapter |
DR01+保存契約合意 | offline fixtureから再開可能。online未対応を明示拒否 |
| DR07 | 認証済みmanifest/Range転送、recipient ACK、負荷制御 | DR transport、documentstore adapter、scheduler表示 | DR03/06 | 中断再開/破損/別groupアクセス/容量不足を検出 |
| DR08 | v1/v2 anchor移行、管理manifest v3発行/受理/ACK | federation manifest、enroll/reconcile、受理repository | DR03/05/06+受理永続化合意 | 同内容再送・旧epoch・欠落履歴・rollbackを正しく処理 |
| DR09 | fence provider契約、impact planner、証跡照合 | DR fence/operation、運用connector | DR05 | 隔離未確認/誤node/別boot/別group影響で昇格拒否 |
| DR10 | 手動switchover/failover/reseedをoperationへ統合 | DR CLI/API、root activation、routing adapter | DR04〜09 | 完全fixtureでroleごとの切替と共有DB連動が成立 |
| DR11 | preempt planner、自動coordinated gate、cooldown | DR policy executor | DR10+設備認定 | flapping抑制、0損失の計画復帰、不可条件時の提案のみ |
| DR12 | DR管理UI、i18n、health、Inbox、監査集約 | config panels、status APIs、metrics | DR03/10+operator認可 | group別表示、権限境界、秘密非表示、plan/applyが一致 |
| DR13 | v0移行/本番runbook、復旧訓練、負荷/障害試験 | docs/operations、隔離検証環境 | DR10/12 | 受入matrix全通過、RPO/RTO実測、明示承認後のみ有効化 |
DR04以降のコード接続は、DB別件の差分が落ち着き接続点が合意された後。 DR08のschema実装は保存担当の変更計画に載せ、DRタスクが独自migrationを追加しない。 DR09の機器connectorは任意shell入力ではなく、許可された設備・resource IDへのtyped操作とする。
段階リリース
| 段階 | 提供するもの | 明示的に提供しないもの |
|---|---|---|
| L0:現行初版 | offline snapshot、検証、手動復元・昇格 | 再参加判定、オンライン同期、自動fencing |
| L1:観測 | DR01〜03、状態の参照UI | 自動昇格、既存writerのruntime変更 |
| L2:再参加gate | DR04/05、operator承認下の起動、shared bundle判定 | 未接続の保存経路があるprofileの有効化 |
| L3:同期・手動切替 | DR06〜10、認証転送、group別の計画操作 | 未認定providerの自動切替 |
| L4:自動主系復帰 | 認定済みDR11/12、coordinated preempt | snapshotのみを根拠にした無人・無損失failover |
| L5:自動障害復旧 | replica durability receipt等が揃うprofileのみ | 未複製更新や未知損失の黙認 |
各段階で有効化フラグは既定off。capabilityの揃わない段階へUI操作で飛び越せない。 L1の観測機能が動作しても「Learningから自動で昇格できる」と表示しない。
4. CLI・API・UIの実施内容
将来CLI案(すべて未実装、DB直接更新用コマンドではない):
pageswiki dr config validate --file <operator-config>
pageswiki dr groups status --group <id>
pageswiki dr rejoin plan --group <id> --node <id>
pageswiki dr switchover plan --group <id> --to <id>
pageswiki dr failover plan --group <id> --to <id>
pageswiki dr operations apply --plan <id> --plan-sha256 <hash>
pageswiki dr operations show --id <id>
pageswiki dr operations cancel --id <id>
pageswiki dr reseed plan --group <id> --node <id> --checkpoint <id>
現行の dr promote はL0専用とする。D1管理されたdatasetでは旧epochの手動書換えに
ならないよう拒否し、operationへ案内する。旧binary/旧CLIもwriterとして動けない配置制約を
設ける。新設定ファイルの存在を古いbinaryが無視する可能性は、file markerだけでは解決しない。
online CLI、Web、policy executorは同じplan/operation serviceを使う。 dry-run/planはfence・permission・同期実体を変更しない。operatorがCLIから秘密付きbackupを 扱えることと、campus_adminがWebから全DBをダウンロードできることを同一にしない。
UIは最初に観測だけを実装し、operationが完成した段階で切替ボタンを追加する。 コンパクトなgroup一覧、control/dataの別ラベル、preempt状態、同期点、ブロック理由を優先する。 確認dialogには「どのCampus/Domain/同居groupが止まるか」「失う可能性のある期間」 「隔離手段」「未達条件」を列挙する。UNIX時刻入力や、色だけの安全判定は使わない。
5. 受入試験マトリクス
テストはfake clock/fake authority/fake fence/一時保存領域から開始し、 実カレンダー・個人文書・本番ノードには接続しない。各テストは最終状態だけでなく、 途中のwriter許可集合を記録し、同一resourceで2 holderになっていないことを検査する。
| ID | 入力・障害注入 | 期待結果 |
|---|---|---|
| T01 | primary記録を持つnodeが再起動、peer応答なし | recovering→blocked、migration/worker含めwrite 0 |
| T02 | 非DR instance起動 | 従来の起動を維持。DR期待環境で設定欠落なら起動拒否 |
| T03 | 別group、未知鍵、同FQDNで別fingerprint、失効nodeからprobe | 認証/認可拒否、WARNING。membership変化なし |
| T04 | 古いboot/nonce、応答遅延、重複JSON key、未知protocol、大きすぎるbody | 状態遷移なし。入力種別に応じたerror |
| T05 | peerが大きいepoch/primaryを自己申告、authorityは異なる | 再確認・conflict、安全側停止。自己申告で昇格なし |
| T06 | 発見peerの半数以上が同じ内容、登録authorityに到達不能 | 観測の多数決でgrantを出さない |
| T07 | 同一DBのCG/DGが別holderを要求、alias resourceも混在 | WRITER_BOUNDARY_COUPLED、連動planを提示 |
| T08 | 独立storeのCG停止、DGは有効grantと設定を保持 | CGだけ停止。DGは権限鮮度条件の範囲で継続 |
| T09 | CGのpreempt on、DGのpreempt off | 独立profileならCGのみ戻る。sharedなら連動影響を承認前に提示 |
| T10 | primaryの停止・再開、時計逆行、VM pause、permit応答喪失 | stale permitでwrite再開なし。新grantにはfenceを要求 |
| T11 | 2 executor/2 candidateが同時に同group操作、response消失、manual agent二重起動 | 一つのoperation/grantだけ確定。同じIDで結果照合、manual agent排他 |
| T12 | fence要求送信済みだが確認不明、別node/古いbootの証跡 | FENCE_UNCONFIRMED、grantなし |
| T13 | ホストfenceが別DG primaryにも影響 | 自動preempt禁止、impactに全groupを列挙 |
| T14 | capture中にDB更新・calendar世代更新・GC・schema変更 | barrier/capabilityに従い排他。保証不能ならcapture中止 |
| T15 | 転送中断/Range再開、chunk改変、symlink/path traversal、未登録file ID | 検証失敗、他データを読ませずactive root不変 |
| T16 | blobの一部欠落、calendar参照世代欠落、schema不適合、secret欠落 | verified/applicable ACKなし、standby公開なし |
| T17 | pin後にsource再起動、transfer期限切れ、GC/保持処理 | 必要世代を消さない。残存pinを照合して回収 |
| T18 | 同期中に新しいwrite、表示上lag=0だが最終cut未確定 | switchover不可。final checkpointの一致を必須とする |
| T19 | metadataのみ最新、ACL/session失効は古い | read/write readinessとも不成立 |
| T20 | 旧primaryに現系列にない更新 | 隔離保全、conflict。自動マージ/削除なし |
| T21 | manifest旧epoch、同sequence異hash、欠落親、receiptなし | 適用拒否。v3導入後のv1/v2 downgradeも拒否 |
| T22 | 内容適用と受理checkpointの間で失敗、publication receipt応答喪失 | 一体rollback/同内容照合。別payloadで再発行しない |
| T23 | controller復元点が管理ノード受理位置より古い | blocked、epochを増やして古い権限を再配信しない |
| T24 | 各operation phaseの前後でprocess kill | 文書化したphaseから再開。REVOKING以降は旧epoch復活なし |
| T25 | GRANTED後root切替失敗、RO filesystem、disk full、fsync失敗 | 新primaryを公開せず、次の復旧operationへ |
| T26 | routing更新失敗、DNS cacheに旧宛先、既存keep-alive | 新primaryは一つ。旧宛先はwrite拒否、routing修復 |
| T27 | 同期済みpreferred nodeが繰り返しflap、時間帯/DST境界 | 安定時間リセット、cooldown遵守、不要な再切替なし |
| T28 | snapshotの鮮度はRPO内だがclient成功応答の反映が不明 | 自動障害昇格不可。損失確認をoperatorへ要求 |
| T29 | grant lease失効/authority quorum喪失/watch欠落 | 新grantなし。local gate期限で停止、外部fence前は他holder不可 |
| T30 | AuthorityStoreを古いbackupへ復元、manual台帳の破損/消失 | 全writerを隔離、新trust世代の手動復旧。epochの黙認・自動初期化なし |
| T31 | high IO/CPU/foreground要求増、巨大snapshot | stream/帯域/hash上限を維持。制御通信が転送に埋もれない |
| T32 | campus_admin/domain_adminが他scope切替/backup秘密を要求 | 拒否。read UIも他Campus・secretを漏らさない |
| T33 | restart後workerが過去jobを拾う、外部通知結果が曖昧 | 許可と再送条件を確認。曖昧な副作用は自動で成功/再送しない |
| T34 | operatorがcancel/disable/旧binaryへのrollbackを要求 | 安全点だけ取消。active grantを消して旧系を復活させない |
T24はPLANNED〜COMPLETEDの全境界で行う。ネットワークを切るタイミングも 「要求送信前」「相手がcommit後、応答前」「応答後、ローカル永続化前」に分ける。 fixtureの全writer経路を一度ずつ実行し、HTTP guardだけで満たしたと判定しない。
6. 性能・運用の合格条件
固定のRTO保証値を現時点で作らず、次の測定結果を導入記録に残す。
- 通常foreground p50/p95/p99と、同時同期時の差。目安の許容悪化率は10%以内、超過なら転送予算を縮小。
- DB/可変正本のbarrier時間、checkpoint作成時間、初回/増分転送時間、検証時間、必要空き容量。
- suspect検知、fence確認、grant、起動、routing完了の各所要時間と合計RTO。
- 障害時点と最後のDR側検証cutの差、client成功応答境界の確認可否、未複製損失の有無。
- スナップショット10万/100万file相当のmanifest paging、RSS/heap、descriptor数の上限。 初版v1の10万file上限を、v2の性能試験なしに解除しない。
- 一日継続のprobe/転送/再起動試験で、timer・goroutine・scratch・pin・operationが無制限に増えない。
10%は候補性能予算であり、実機測定前に達成と表明しない。別件の保存層の性能評価と同じ fixture条件を使用する。外部サービス/実データにアクセスする実機試験は別途承認を得る。
7. 導入時に入力・承認する事項
設計として未決のアルゴリズムではなく、設備・運用に依存する導入パラメータを列挙する。
| 入力 | 決定する主体 | 未入力時 |
|---|---|---|
| node FQDN/管理origin、node identity、対象Campus/DG、resource対応 | 運用者+保存担当 | 登録・同期を開始しない |
| RPO/RTO、retention、容量/帯域予算 | 運用者 | 本番enable不可 |
| authority配置、CA、専用service key保管/更新、quorum障害領域 | 運用者 | manualのみ |
| fence機器/credential参照、再起動抑止、影響group | 運用者 | coordinated enable不可 |
| backup/secret暗号化と復号担当、別障害領域の保全先 | 運用者 | 秘密付き転送不可 |
| CG/DGごとのpreferred、preemptと許可時間帯 | 運用者+管理者 | preempt off |
| 保存profile能力と対応app/image/schema | 保存担当 | offline/shared-instanceのみ |
8. 本番導入手順
- 運用者が対象と入力を確定し、保存担当がresource map・能力契約を承認する。
- 本番とは通信しない隔離fixtureで対応段階のT01〜T34と負荷試験を実施する。
- 既存環境の保全・image digest・schema互換性・復旧手順をレビューする。実データ保全は別途承認。
- L1観測のみを配置し、比較表示を確認する。旧roleに基づくサービス挙動はこの段階では変えない。
- 全writerと旧CLIを停止する保守枠を取り、L2への移行planを確認する。
- 旧cluster/node/roleを新group/resourceに対応させ、fresh authorityをbootstrapする。 旧primaryの確認記録を付け、元のepochを新authorityの根拠にしない。
- 新startup gate下で起動し、他nodeはlearnerとして参加。sourceと同期内容を検証する。
- L3の手動switchoverと復帰を1往復実施し、RPO/RTO・監査・権限失効・queueを検証する。
- 保存分離済みprofileならCG/DGの独立切替、共有profileなら連動拒否/連動切替を確認する。
- 能力が揃ったgroupに限り、明示承認を得てL4を有効化する。L5は別の認定を要求する。
ローリング移行中、旧ノードをwriter候補に残さない。mixed protocolで書込み可能nodeを 増やす移行はしない。旧nodeからのprobeは対応版を表示し、新grant候補から除外する。 管理manifest v3は全対象が移行anchorをACKした後に切替える。
9. 撤退・失敗時
DRの「無効化」は設定ファイル削除ではない。新operation受付を止め、active operationを照合し、 一つのwriterを運用者が確定・隔離確認してから非DR運用への移行planを実行する。 authorityを停止しただけで旧nodeに書き込みを許可しない。
L1だけなら観測プロセスを停止して戻せる。L2以降はrole/許可/DB互換性の記録を保持する。 新epochでwriteが発生した後は、旧snapshotを起動することでrollbackしない。 旧binaryに戻す場合は、最新データとschema互換性を検証し、DRのtrust/gateを無視するbinaryが 同時に動かないことを外部で保証する。保証できなければ停止を継続する。
実施結果には、適用していない段階、満たしていない能力、最後に検証した世代、 次に必要な承認を必ず残す。設計完了・実装完了・復旧訓練完了・本番稼働を同じチェックにしない。