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.
398 lines
30 KiB
Markdown
398 lines
30 KiB
Markdown
# 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にし、成功と表示しない。
|