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.
This commit is contained in:
1 parent
9dd425f765
commit
d5d21b7841
302 files changed
+20037
-3492
No files matched your search
@@ -0,0 +1,397 @@
|
||||
# DR詳細設計:通信・同期・主導権移譲契約
|
||||
|
||||
設計版:DR-D1、2026-09-27。**すべて次段階の設計。新endpoint・設定・永続化は未実装。**
|
||||
責務と用語は [管理主系・データ主系](dr-authority-and-rejoin.md)、実装の順序は
|
||||
[実施計画](dr-delivery-plan.md) を正とする。DB変更は本作業に含めない。
|
||||
|
||||
## 1. 構成と永続化の契約
|
||||
|
||||
### 1.1 Authority Service
|
||||
|
||||
manual providerは単一のoperator管理agentと専用のdurable操作台帳を使用する。
|
||||
台帳は業務DB/snapshot外のローカル保護領域に置き、プロセス排他、revision比較、
|
||||
operationの追記・fsync後の応答を必須にする。grant発行・holder変更にはoperator承認が必要。
|
||||
同じ許可の短期renewは自動でもよいが、別boot/holderへの変更にはならない。
|
||||
台帳破損/消失/別agent起動で自動再初期化せずblockedにする。manual provider自体のHAは
|
||||
提供せず、復旧時は旧agentと全writerを隔離してtrust再承認する。これは独自分散合意ではない。
|
||||
この運用台帳をアプリmetadataや管理manifest受理checkpointの代わりには使わない。
|
||||
|
||||
独立した運用サービスとしてgroup membership、grant、operation、fence証跡の参照を扱う。
|
||||
coordinated providerはetcd v3の線形化readと比較更新transaction。業務nodeにはetcdの
|
||||
任意Put権を与えず、認証されたAuthority Serviceの限定操作を通す。APIプロセスは複数起動できるが、
|
||||
決定の正本は一つのetcd keyspaceであり、プロセスのメモリや通常event queueではない。
|
||||
|
||||
論理keyは `groups/{kind}/{uuid}/membership`、`.../active`、`resources/{uuid}/active`、
|
||||
`operations/{operation_uuid}`、`trust/generation`。これはetcdの論理配置案で、アプリDBのDDLではない。
|
||||
group/resource activeとoperation phaseの変更は同じCAS transactionで確定する。
|
||||
共有bundleは関連全group/resourceを同じtransactionに含める。provider上限を超えるbundleは
|
||||
登録時に拒否し、一部だけ切替えない。初期上限は1 bundleあたりgroup+resource合計32。
|
||||
|
||||
`active` は `{membership_revision, trust_generation, epoch, holder_node_id, holder_boot_id,
|
||||
state, operation_id, resource_epochs, checkpoint_id, revision}` を持つ。
|
||||
`state` は ACTIVE / REVOKING / FENCED / PREPARED / NONE。epochは10進文字列uint64、
|
||||
上限でエラー。membership revisionとprovider revisionもJSON数値精度に依存しない文字列にする。
|
||||
epochと操作intentはleaseに付けず保存し続ける。短期permitだけが期限付き。
|
||||
|
||||
### 1.2 契約インターフェース
|
||||
|
||||
| 契約 | 入力→結果 | 必須の性質 |
|
||||
| --- | --- | --- |
|
||||
| `ObserveAuthority` | group/bundle→membership、active、revision | 線形化read。watch/probeのcacheで代替不可 |
|
||||
| `PlanTransition` | expected revision、target、reason→immutable plan/hash | 不足能力・影響・損失・必要承認を全列挙。副作用なし |
|
||||
| `BeginTransition` | plan hash、承認、idempotency key→operation | CASで一つだけ開始、競合は409 |
|
||||
| `RecordFence` | operation、provider evidence→FENCED | exact node/boot/resource/operationへの新鮮な証跡を検証 |
|
||||
| `CommitGrant` | 検証ACK、fence、expected各revision→PREPARED | group/resourceを原子的に新holderへ。旧grantは復活不可 |
|
||||
| `RenewPermit` | active grant、boot、nonce→短期permit | ACTIVE holder、またはPREPARED holderの限定初期化scopeだけ。期限更新は権限移譲ではない |
|
||||
| `CompleteActivation` | writer gate/root検証ACK→ACTIVE | checkpoint/root、schema、grantの一致。未完なら配信不可 |
|
||||
| `DescribeResources` | role→resource集合・能力 | aliasを含む共通正本を検出。未申告は独立と見なさない |
|
||||
| `FreezeWriters` | bundle、operation、deadline→cut候補 | 新規受付停止、実行中writerをdrain。未知writerがいれば失敗 |
|
||||
| `CaptureCheckpoint` | freeze token→checkpoint、pins | metadata/可変正本の同一cut、checksum、復旧に必要な参照集合 |
|
||||
| `Stage/VerifyGeneration` | checkpoint、payload→verified ACK | 非稼働rootのみ。権限/互換性も検証し、writerを開かない |
|
||||
| `ActivateGeneration` | verified ACK、grant→root ACK | root pointerをdurableに切替。曖昧な状態はrecovering |
|
||||
| `ApplyControlManifest` | envelope、expected受理checkpoint→ACK | 内容・受理checkpointを同じ永続化境界でcommit |
|
||||
|
||||
PREPAREDではmigration/正本修復に必要な限定writerを新holderだけに許可できる。
|
||||
通常リクエストとworkerはACTIVEになるまで閉じる。移行が長引けばpermitを更新する必要がある。
|
||||
初段は同じschema/imageで復元し、DR切替にschema migrationを混ぜない。
|
||||
|
||||
`FreezeWriters` の成立はアプリDBの外から書くCLI等も止められる場合に限る。
|
||||
未知writerが存在する保存profileは、サーバ/CLI全停止と外部保守lockによるoffline modeだけを許可する。
|
||||
保存層で実現できない契約を、別ファイルへの二重書きで「同じtransaction」と称しない。
|
||||
|
||||
## 2. 信頼・ネットワーク
|
||||
|
||||
接続はHTTPS、TLS 1.2以上、mTLSによる専用node identityとgroup許可を必須にする。
|
||||
検証無効化、HTTPフォールバック、通常Campus参加tokenの転用はしない。
|
||||
既存の開発用 `--add-external-campus-http` はこのprotocolを許可しない。
|
||||
初回信頼はoperatorがCA/鍵fingerprintとnode UUIDを別経路で承認する。probeによるTOFUはしない。
|
||||
|
||||
TLS終端proxyを用いる場合、外部からのidentity headerを除去し、信頼済みproxy接続だけで
|
||||
検証済みidentityを伝える。加えて下記のnode署名で要求を束縛する。任意の
|
||||
`X-Client-Cert` やFQDNだけで認証しない。FQDNの再利用・鍵変更はWARNING+quarantine。
|
||||
|
||||
peer endpointはoperatorが登録したHTTPS originと固定prefixのみ。ユーザーのURL入力や
|
||||
probe応答の未知URLへ自動接続しない。redirectは禁止。私設networkの許可はgroupごとの
|
||||
allowlistで定義し、DNS解決後の宛先IPも検証する。TLSのserver nameと登録originは維持する。
|
||||
|
||||
### 署名envelope
|
||||
|
||||
共通JSON envelopeは `protocol_version="dr/1"`, `key_id`, `payload_b64`, `payload_sha256`,
|
||||
`signature_b64`。payloadはUTF-8 JSONの**送信した正確なbyte列**を署名し、再serializeしない。
|
||||
署名対象は用途別固定prefix(例 `pageswiki.dr.probe.request.v1\n`)+payload bytes。
|
||||
Ed25519を用い、種類の異なるenvelope間で署名を使い回さない。JSON重複key、未知version、
|
||||
不正UTF-8、深さ過大、型違い、未知の必須capabilityを拒否する。canonical JSONの独自実装は不要。
|
||||
|
||||
通信payloadは `request_id`, `sender_node_id`, `sender_boot_id`, `group_id`, `group_kind`,
|
||||
`membership_revision`, `trust_generation`, `nonce`, `issued_at`, `expires_at` を共通に持つ。
|
||||
nonceは32 random bytesのbase64url、request_idはUUID。応答は要求ID/nonce/宛先node/bootと
|
||||
要求payload hashをechoし、観測したauthority revisionを含める。nonce未要求・別boot・期限切れ
|
||||
応答は状態遷移に使わない。UTC時刻の許容ずれは5秒、response有効時間は10秒以内を初期値とする。
|
||||
時刻だけに依存せず、boot/nonce/authority revisionも検証する。
|
||||
|
||||
node用秘密鍵はnode-local。Campus manifest署名鍵とは別。信頼世代・鍵ローテーションは
|
||||
旧新keyの承認期間と撤回revisionを記録し、同一nodeを二つのbootが同時に有効化しない。
|
||||
|
||||
要求payloadには `http_method`, `request_target`, `audience_id` も含め、実際のmethod/管理URI/
|
||||
受信nodeまたはserviceに一致させる。署名検証前に別URIへrewriteしない。未知query、dot-segment、
|
||||
encoded slashなどの曖昧なpathを拒否する。path groupとpayload groupの不一致も拒否する。
|
||||
管理manifestの署名鍵をbackupから持ち出せても、Authority Serviceが確定したpublication receipt
|
||||
なしに新manifestを受理させない。署名鍵を保持することと、現在の発行権限を持つことを分離する。
|
||||
|
||||
POSTの通信envelopeはJSON body、GETは8KiB以内の `PagesWiki-DR-Request` headerへ格納し、
|
||||
GET bodyを要求しない。Range要求はその値も署名payloadへ含める。通常JSONの復号payload上限は
|
||||
256KiB/深さ16、manifest pageだけは1MiBまで。binary転送の応答検証は署名済みmanifestの
|
||||
chunk/全体hashで行い、全ファイルをbase64 JSONに包まない。
|
||||
保管するcheckpoint/manifest署名は通信envelopeと用途prefixを分け、request nonceや10秒の
|
||||
応答期限を付けない。不変artifactの由来/完全性検証と、今このnodeがアクセス・書込みできるかの
|
||||
短期許可検証を分離する。古いartifact署名が有効でも現行のwrite grantにはならない。
|
||||
|
||||
## 3. probeと再参加
|
||||
|
||||
`POST /_/api/v1/instance/dr/probes` を認証済みgroup member/learnerだけに提供する。
|
||||
無認証でpeer一覧、group一覧、snapshot一覧を返さない。
|
||||
|
||||
要求の追加項目:
|
||||
|
||||
```json
|
||||
{
|
||||
"group_kind": "data",
|
||||
"group_id": "<group-uuid>",
|
||||
"sender_node_id": "<node-uuid>",
|
||||
"sender_boot_id": "<new-boot-uuid>",
|
||||
"known_authority_revision": "123",
|
||||
"known_epoch": "7",
|
||||
"applied_checkpoint_id": "<checkpoint-uuid-or-null>",
|
||||
"supported_protocols": ["dr/1"],
|
||||
"capabilities": ["probe-v1", "offline-checkpoint-v1"],
|
||||
"nonce": "<random-base64url>"
|
||||
}
|
||||
```
|
||||
|
||||
例は共通項目の一部を省略した型説明で、稼働設定として投入しない。
|
||||
応答はprimary観測値、membership revision、state、checkpoint id/hash/親、
|
||||
内容cut時刻、verified/applicableの区別、schema互換性、roleに応じたcontrol受理位置を返す。
|
||||
資格情報・文書本文・ユーザー一覧・内部path・任意SQLは返さない。
|
||||
|
||||
probe結果は `observed`、AuthorityStore read結果は `authoritative` と区別する。
|
||||
処理順:node identity→group所属→nonce等→protocol→authority照合→履歴照合→同期plan。
|
||||
新しいepochを発見したら必ずauthorityへ再確認し、peerだけを根拠に旧許可を新primaryへ移さない。
|
||||
矛盾の疑いがあれば自ノードのwriterは安全側へ閉じるが、他ノードの昇格は承認しない。
|
||||
|
||||
既知peerへ並列fan-outする。初期同時数4、groupごと最大32 endpoint、1応答256KiB、
|
||||
要求/応答rateは1 nodeあたり10req/sまで。初回は即時、その後5秒±20%jitter。
|
||||
失敗時は最大60秒までbackoff、安定した成功で戻す。タイマー終了はsuspect表示だけを変える。
|
||||
membership変更はoperatorによるexpected revision付き操作。join要求はlearner候補に留め、
|
||||
既存memberやauthority quorumを自動的に増減させない。
|
||||
|
||||
## 4. API境界とエラー
|
||||
|
||||
全URIは予定。通常ユーザーのPath/公開Domainからは独立した管理経路に置く。
|
||||
|
||||
| method / prefix以下のURI | 呼出主体 | 契約 |
|
||||
| --- | --- | --- |
|
||||
| `GET capabilities` | 登録node/operator | protocol、schema/profile能力。対応申告であり同期完了証明ではない |
|
||||
| `POST probes` | group member/learner | 情報収集のみ。grantを発行しない |
|
||||
| `GET groups/{kind}/{id}/status` | node/operator、範囲制限した管理者 | observed/authoritative/as_ofを明示 |
|
||||
| `POST groups/{kind}/{id}/plans` | operator | rejoin / switchover / failover / reseedの副作用なしplan |
|
||||
| `POST operations` | operator/認定済みpolicy executor | plan hashと承認を照合して開始 |
|
||||
| `GET operations/{id}` | 許可された操作主体 | phase、未達条件、証跡、結果 |
|
||||
| `POST operations/{id}/cancel` | operator | cancel可能点だけ。grant移譲後を勝手に巻き戻さない |
|
||||
| `GET groups/{kind}/{id}/checkpoints/{id}` | 承認replica/operator | 署名metadata、transfer manifest参照 |
|
||||
| `POST transfers` | 承認replica/operator | group/checkpoint/recipientを固定した転送session |
|
||||
| `GET transfers/{id}/manifest` | session recipient | paged immutable manifest、snapshot ETag |
|
||||
| `GET transfers/{id}/files/{file_id}` | session recipient | 許可されたopaque file IDのRange取得 |
|
||||
| `POST transfers/{id}/acks` | session recipient | bytes受信/検証/適用ACKを別stageで記録 |
|
||||
| `POST groups/{kind}/{id}/permits/renew` | active holderのみ | node/boot/epoch/resourceを束縛した期限更新 |
|
||||
|
||||
prefixは `/_/api/v1/instance/dr/`。node-local probe/transferはnode agentが処理し、
|
||||
plans/operations/grantはAuthority Serviceが処理する。配置proxyは経路を区別し、
|
||||
node agentがauthority不通時に代わりのgrantを作らない。
|
||||
|
||||
state変更要求は `Idempotency-Key: UUID` とplan/expected revision必須。同じkey・同じbodyは
|
||||
同じoperationを返し、同じkeyで異bodyは409。応答喪失後は元operationをGETして照合する。
|
||||
planの有効期間は60秒。membership、epoch、checkpoint、fence影響範囲が変われば期限内でも失効。
|
||||
grant commit前にはもう一度最新条件を再検査する。
|
||||
|
||||
Web操作はoperator認可gatewayを介し、human actor・scope・承認内容・plan hashを短命の
|
||||
delegationに束縛してAuthority Serviceへ渡す。nodeの秘密鍵やetcd資格情報をブラウザへ渡さない。
|
||||
gatewayが認可しただけでimpact planの承認を省略しない。instance operatorの認可信頼源が
|
||||
接続されるまではWeb applyを無効にし、ホスト運用者のCLIだけを提供する。
|
||||
|
||||
| HTTP | code例 | 呼出側の動作 |
|
||||
| --- | --- | --- |
|
||||
| 400 | INVALID_ENVELOPE / UNSUPPORTED_VERSION | 修正までretryしない |
|
||||
| 401/403 | IDENTITY_REQUIRED / GROUP_FORBIDDEN | 権限修正。未知groupの内容は隠す |
|
||||
| 404 | UNKNOWN_RESOURCE | 他groupの存在を推測できる詳細を返さない |
|
||||
| 409 | STALE_EPOCH / OPERATION_CONFLICT / HISTORY_DIVERGED / WRITER_BOUNDARY_COUPLED | 再probeまたは新plan。自動上書きしない |
|
||||
| 412 | MANIFEST_CHANGED / STALE_PLAN | 同一転送・旧planを継続しない |
|
||||
| 413/429 | LIMIT_EXCEEDED / RATE_LIMITED | 上限内へ縮小、Retry-Afterを遵守 |
|
||||
| 501 | CAPABILITY_UNAVAILABLE | offline/manualへ明示的に再計画。暗黙downgradeしない |
|
||||
| 503 | AUTHORITY_UNAVAILABLE / NOT_READY / FENCE_UNCONFIRMED | 書き込みを閉じて待機 |
|
||||
|
||||
JSON errorは `code, message_key, request_id, retryable, operation_id`。本文・秘密・SQLは含めない。
|
||||
管理レスポンスはno-store。状態取得はETag可、ただしcached statusを昇格承認には使わない。
|
||||
|
||||
### 配信とreadiness
|
||||
|
||||
管理listenerは一般DomainのHost選択/ログインsessionから独立して認証し、learning中もprobeを
|
||||
受けられるようにする。復旧した業務DBの認証設定だけに、再参加の身元検証を依存させない。
|
||||
通常routeはHost→Domain→DG→resource/grantの順に解決し、各要求で対象groupを判定する。
|
||||
コントローラ用routeはCampus→CGを判定する。HTTP methodだけでどちらのprimaryか決めない。
|
||||
|
||||
node全体の `/health` は生存確認。複数groupで混在する場合、従来の `/health/write` は
|
||||
対象listenerの全write groupがreadyなときだけ200とする保守的な集約値で、個別routingには使わない。
|
||||
認証済みgroup statusの `read_ready`, `write_ready`, `state`, `reason`, `as_of` を
|
||||
routing adapterへ渡し、切替時はfresh authorityと実際のgate状態も照合する。
|
||||
PREPARED/ACTIVATINGは通常write readyにしない。既存接続も切替後の各要求で再検査し、
|
||||
古い接続が旧primaryへの書込権を保持することはない。URIやHostをDRノードFQDNへ書き換えない。
|
||||
|
||||
## 5. Checkpointとバックアップ契約
|
||||
|
||||
### 5.1 内容
|
||||
|
||||
checkpoint v2(初版snapshot v1とは別format)は次を持つ。
|
||||
|
||||
- format/protocol version、group kind/id、dataset ID、checkpoint UUID、親checkpoint hash。
|
||||
- source node/boot、trust generation、control/data/resource epoch、membership revision。
|
||||
- snapshot cut ID、cut時刻、capture完了時刻、内容集合digest。
|
||||
- app SemVer、image digest、保存profile、schema component/version/checksumの集合。
|
||||
- DB snapshot descriptor、可変正本manifest一覧、CAS参照集合、総byte数、file数。
|
||||
- 管理manifest受理位置、ACL/session失効watermark、outbox/job再送判定位置。
|
||||
- 暗号化方式・key参照・別保全のsecret一覧。secret値は一覧に含めない。
|
||||
- 操作状態 `capturing/sealed/transferring/verified/activated`。sealed前はservableにしない。
|
||||
|
||||
「送信完了」「受信した」「hash検証済み」「配信可能」「昇格可能」は別。
|
||||
checkpoint sequenceはその系列の順序であり、clientへ成功応答した全変更の境界とは限らない。
|
||||
初段のsnapshot同期は物理snapshot+CAS不足分転送。SQL差分適用やWALファイルの独自転送はしない。
|
||||
オンラインのtransaction log方式は保存層が将来別profileとして保証するまで使わない。
|
||||
|
||||
### 5.2 一貫したcapture
|
||||
|
||||
1. capture対象のbundle/resourceを確定し、schema変更と同時に走らないことを確認する。
|
||||
2. 新規writer受付を閉じ、DB・可変正本の処理中更新をdrainする。GCも対象世代を消せない状態にする。
|
||||
3. 保存層に同一cutのDB snapshotと可変正本manifestを固定させ、参照集合を確定する。
|
||||
4. 参照CAS/月別世代へのdurable pinを確立する。pinの永続化とcut固定を確認する。
|
||||
5. sealedしたDB像・metadataから後続コピーできることを確認してbarrierを解除する。
|
||||
6. 大きな不変payloadのhash確認/転送はforegroundより低優先度で継続する。
|
||||
|
||||
SQLite Backup APIはDB単位の整合コピーであり、別ファイルの同一cutまで自動保証しない。
|
||||
DB像の固定にコピー完了まで必要なprofileでは、その間barrierを維持する。
|
||||
「短時間online」と無条件に表明せず、barrier予算超過ならpublish前にcaptureを中止し、
|
||||
primaryを再検査して通常処理へ戻す。最初はoffline profileだけでもよい。
|
||||
[SQLite Backup API](https://www.sqlite.org/backup.html)
|
||||
|
||||
pinの保持はtransferの期限と独立。transfer sessionが切れても、保全世代/進行中operationから
|
||||
参照されるblobを消さない。完了/中止後もretentionに従って解放する。ノード再起動でpinが
|
||||
失われるprofileはオンラインcapture不可。保持台帳の実装は保存担当の契約に従う。
|
||||
|
||||
### 5.3 受信・再開・切替
|
||||
|
||||
受信は非稼働generationに対して行う。file IDはmanifest内でscope付きに割り当て、
|
||||
任意pathや他groupのhashを直接読めるAPIにしない。manifestは1page最大1,000件/1MiB、
|
||||
sealed manifestのroot digestとpage hashで全体を検証する。各payloadは全体hash/sizeと
|
||||
16MiB単位のchunk hashを持ち、Range再開時にもchunkと全体の両方を検証する。
|
||||
|
||||
転送sessionはrecipient node/boot、group、checkpoint、期限に結び付く。初期期限15分、
|
||||
再認証後に同じsealed checkpointへ再開可能。期限はreaderの権限であり正本の寿命ではない。
|
||||
宛先の空き容量は必要byte+20%と運用予約分を確認し、既存稼働世代を自動削除して空きを作らない。
|
||||
|
||||
受信後:全payload→DB/正本参照整合→schema互換→失効/鍵の可用性→内容digestの順に検証する。
|
||||
DB inspectionはread-onlyで行い、初期化/migrationによって検証対象を変化させない。
|
||||
検証ACKを受けても一般routingは開かず、standbyのread条件または新grantを別途確認する。
|
||||
root切替は新generationをfsyncした後、atomic pointer更新で行う。旧世代を保持し、
|
||||
再起動時にpointerとoperation recordが食い違えばrecoveringで照合する。
|
||||
|
||||
転送負荷の初期値:nodeごとpayload stream最大2、合計10MiB/s、hash worker 1、
|
||||
foreground高負荷時は新chunk受付を停止。制御用probe/permitは別connection・別予算。
|
||||
リソース監視値が取れない場合は固定上限を維持し、無制限へ拡張しない。
|
||||
pause/backoff/cancelの最大応答遅延は1 chunkのI/O期限内。候補値30秒、実測して認定する。
|
||||
通常event schedulerにはcapture/verify/転送等を表示するが、grant更新は専用loopとする。
|
||||
|
||||
### 5.4 保全・秘密・分岐
|
||||
|
||||
複製は保全世代の代替ではない。retention初期案は直近3+日次7+週次4、導入時に容量確認する。
|
||||
世代依存とpinsを検査してから削除し、root trust/復号鍵の保全はsnapshotとは別の障害領域に置く。
|
||||
業務復旧に必要な暗号化鍵は許可済みgroup nodeへ保護して配布するが、物理nodeの専用秘密鍵は
|
||||
他ノードへ配布しない。初版が保全するlegacy instance keyとは移行時に区別する。
|
||||
|
||||
復帰ノードに現primaryの系列にない変更があれば、旧DB/正本を隔離したgenerationとして保全する。
|
||||
件数・由来・時点を示し、手動export/importや内容比較へ渡す。データの新旧をmtimeだけで比較せず、
|
||||
自動マージ、自動削除、旧DBの現primaryへの逆コピーを禁止する。
|
||||
|
||||
## 6. 管理manifestの世代設計
|
||||
|
||||
既存schema_version 1/2、署名と受理checkpointを維持し、新契約は **schema_version 3案** とする。
|
||||
未対応受信先が一つでも対象に含まれる間はv3配信/CG自動移譲を有効化しない。
|
||||
capability応答だけでなく、移行済み受理状態のACKを必要とする。
|
||||
|
||||
v3 payloadは既存管理情報に `control_group_id`, `trust_generation`, `control_epoch`,
|
||||
`manifest_sequence`, `configuration_checkpoint_id`, `previous_manifest_hash`, `payload_hash`,
|
||||
`authority_commit_receipt` を追加する。署名は確定した管理内容を一度だけserializeしたbyte列に行う。
|
||||
|
||||
発行手順:同じ管理snapshotから内容を取得→候補payloadを永続化→有効control grant下で
|
||||
authorityへ `expected previous hash/sequence` によるpublication commitを要求→返却receiptと
|
||||
署名を保存→配信。応答喪失なら同じpayload hashでcommit結果を照合する。新規内容に同じsequenceを
|
||||
割り当てない。receiptのない「大きなepochのmanifest」は配信・受理しない。
|
||||
snapshot内容の取得とcheckpoint固定は保存担当の契約が必要で、既存の連番SQLだけで代替しない。
|
||||
|
||||
受信手順:
|
||||
|
||||
1. Campus/CG/署名鍵/trust世代/対象Domain ownershipを検証する。
|
||||
2. authority receiptと、現在許可されたcontrol epochを確認する。epoch切替時はfresh authority確認必須。
|
||||
3. 同epochの小さいsequence、同sequenceで異hash、親hash不一致は拒否する。
|
||||
4. 同epoch・同sequence・同hashは冪等ACKとする。
|
||||
5. 新epochは署名済み移譲recordとbase管理checkpointを検証する。単なる数値の大小では許可しない。
|
||||
6. 管理内容と受理位置を一つのtransaction境界で保存し、そのcommit後に適用ACKを返す。
|
||||
|
||||
管理ノードprobeから回収した最大受理位置は「これより前へ戻してはいけない」下限の証拠。
|
||||
完全な管理正本の代わりではない。checkpointが不足すればCGはblockedとし、新epochを使って
|
||||
古い権限を再発行しない。復旧snapshotがauthorityの最後のpublicationより古い場合は、
|
||||
正しい履歴の取得または運用者による明示的な再構成・失効再適用を要求する。
|
||||
|
||||
v1/v2からの移行は最後のrevision/hashをmigration anchorとして固定し、最初のv3がそれを参照する。
|
||||
trust pinを削除してやり直す方法は採らない。v3受理後のv1/v2自動fallbackも拒否する。
|
||||
この永続化の追加は将来のDB担当との合意対象であり、本設計作業では実装しない。
|
||||
|
||||
## 7. 計画切替とpreempt
|
||||
|
||||
preemptはpreferred nodeへ向けたswitchover operationをpolicy executorが作るだけであり、
|
||||
特別な高速昇格経路を持たない。offなら現primaryを維持、manualなら提案のみ通知する。
|
||||
automaticでも安定時間/時間帯/cooldown/能力/影響範囲を満たさない限りplanをapplyしない。
|
||||
|
||||
| operation phase | 確定させること | crash/timeout時 |
|
||||
| --- | --- | --- |
|
||||
| PLANNED | target、expected構成、影響、必要能力、見込時間 | 期限切れで再plan。副作用なし |
|
||||
| VALIDATING | authority最新値、target同期/鍵/schema/ACL、fence能力 | 旧primaryの権利は変更せず停止 |
|
||||
| DRAINING | 旧primaryの新規write/job停止、実行中処理の結果 | 旧grantがまだ有効とauthorityで確認できる場合だけdrain解除可能 |
|
||||
| SEALED | final cutと内容集合、targetの最終検証ACK | 不足があれば旧権利の扱いを照合。勝手に切替えない |
|
||||
| REVOKING | 旧permit再発行禁止を永続化 | ここから旧epochの自動復活は禁止 |
|
||||
| FENCING | 旧writerへの外部隔離と、その確認証跡 | 不明ならblocked。新grantなし |
|
||||
| GRANTED | 新epochのgroup/resource許可をPREPAREDで確定 | holderをGETで照合し再開。別targetへretryしない |
|
||||
| ACTIVATING | target root/gate/schema/readinessを検証 | targetを隔離、次のoperationを計画。旧系に単純rollback不可 |
|
||||
| ROUTING | TLS/Host/接続先を更新しread/write確認 | 新primaryは一つのままrouting修復 |
|
||||
| COMPLETED | sourceの降格、監査、Inbox、保持世代を記録 | 重複完了は冪等 |
|
||||
|
||||
planned switchoverの損失許容は常に0。最終cutのDBだけでなくCAS・可変正本・失効・outboxも
|
||||
targetに適用済みでなければSEALEDを超えない。「遅延がほぼ0」「同期率100%表示」だけでは不可。
|
||||
grantを移す瞬間はwriterが一時的に0になってよいが、2になってはいけない。
|
||||
|
||||
fence証拠はkind、provider、対象node/boot、対象resource、操作ID、確認時刻、結果、
|
||||
再起動/再接続を阻止する方法を含める。接続不能やSIGTERM送信済みだけではconfirmedにならない。
|
||||
初段の自動認定は全旧writerを確実に隔離できる外部providerだけ。保存側fencing契約が後で
|
||||
認定されれば、影響範囲を小さくするprofileとして追加できる。
|
||||
|
||||
**fenceで認定する範囲:** HTTP/LB経路を閉じただけではローカルjob/CLIの書込を止められない。
|
||||
プロセス停止なら全writerと再起動経路、電源断なら同居group、保存資格情報の失効なら対象となる
|
||||
すべての正本backendを対象にする。remote backendへ既に送った可変正本更新が遅れて完了する
|
||||
可能性も評価する。認定された保存側世代拒否、drain確認、または明確な処理終了証明がなく、
|
||||
旧更新が後から確定し得るprofileでは新grantを出さない。単にtimeoutを待ったことは終了証明ではない。
|
||||
メール等の既送信副作用はfenceで取り消せないため、outboxの曖昧結果は別途照合・承認対象にする。
|
||||
|
||||
## 8. 障害時昇格と許可喪失
|
||||
|
||||
障害時はprobe失敗でsuspect表示→authority照合→fence確認→最後の検証済み世代と損失評価→
|
||||
新grant、という順。旧primaryと最終cutを交渉できないため、計画切替と同じ0損失を仮定しない。
|
||||
RPO内というだけでは、成功応答済みの更新が失われない証拠にならない。
|
||||
|
||||
DR-D1の既定は未知損失/未複製変更があればoperator承認必須。自動failoverは保存profileが
|
||||
`acknowledged_writes_durable_on_replica` を提供し、authorityがその確定境界を照合できる場合に限る。
|
||||
現在の非同期snapshot profileはこの能力を持たないので、自動preemptは将来可能でも、
|
||||
無人・無損失failoverまで実装済みとはしない。許容損失による自動昇格profileは本版では提供しない。
|
||||
|
||||
短期permitの初期候補はTTL30秒、更新5秒、local safety margin10秒、更新RPC期限2秒。
|
||||
有効期限を受信時刻だけから延長せず、要求開始のmonotonic時刻と署名された有効期間から
|
||||
保守的なlocal deadlineを計算する。遅れた応答、clock異常、別boot、別epochは破棄する。
|
||||
許可喪失でwriter gateを閉じるが、プロセス停止/遅延commitの安全性はそれだけに依存せず、
|
||||
次holderにgrantする前の外部fenceで保証する。TTLが経過しただけの自動grantは禁止。
|
||||
|
||||
旧nodeが復帰しても、既存許可をdiskから復活させない。nonce付きprobeと新bootに束縛した
|
||||
fresh permitが必要。authority自身が復元され旧recordしかない場合は全体をblockedにする。
|
||||
|
||||
## 9. cancellation、監査、rollback
|
||||
|
||||
operationは長時間処理なので202を返し、通常event/queue画面には参照を出す。
|
||||
authorityのphase更新は通常キューの「再試行」ボタンで巻き戻さない。
|
||||
同じ操作を複数executorが拾ってもCAS phase+idempotency key+fence providerの操作IDで重複を抑える。
|
||||
外部副作用のexactly-onceを無条件に約束せず、曖昧な送信結果は照合またはoperator確認にする。
|
||||
|
||||
REVOKINGより前は、現grantが旧holderに有効と確認できる場合にだけcancelして復帰できる。
|
||||
REVOKING以降の失敗は新しい復旧operationと新epochで処理する。以前の設定ファイルに戻すだけの
|
||||
rollback、epoch減少、旧writerの再起動、受理checkpoint削除は禁止。
|
||||
|
||||
監査はactor、group/bundle、plan hash、old/new node/boot、各epoch、checkpoint、損失承認、
|
||||
fence証跡参照、phase、結果、request IDを残す。書き換え可能な業務snapshot内だけを監査の
|
||||
保全先にしない。probe全件は短期集約し、状態変化と操作の証跡は長期保存する。
|
||||
|
||||
## 10. 不変条件
|
||||
|
||||
- N1:同じwriter resourceに二つの有効holderを同時に作らない。
|
||||
- N2:probe、priority、preempt設定、watch通知は単独でwriterを開けない。
|
||||
- N3:新epochで古い管理内容/権限を無条件に正当化しない。
|
||||
- N4:未検証・不完全なgenerationへactive pointerを向けない。
|
||||
- N5:旧primaryの未同期変更を保全せずに削除・上書きしない。
|
||||
- N6:通常DBのrestorationでnode trust/authorityの単調性を巻き戻さない。
|
||||
- N7:すべてのwrite経路と背景処理がgate/隔離の範囲内にある。
|
||||
- N8:control切替とdata切替を区別し、共有resourceの場合だけ明示的に連動する。
|
||||
- N9:grant移譲後の失敗を旧epoch復活で回避しない。
|
||||
- N10:不足能力・到達不能・曖昧な副作用はfail closedにし、成功と表示しない。
|
||||
Reference in new issue
Block a user