centra
8f94aee1fa
- Remove gitlinks (160000 mode) for chainfire, flaredb, iam - Add workspace contents as regular tracked files - Update flake.nix to use simple paths instead of builtins.fetchGit This resolves the nix build failure where submodule directories appeared empty in the nix store. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
88 lines
6.7 KiB
Markdown
88 lines
6.7 KiB
Markdown
# Feature Specification: Distributed KVS Consistency Modes
|
||
|
||
**Feature Branch**: `003-kvs-consistency`
|
||
**Created**: 2025-12-01
|
||
**Status**: Draft
|
||
**Input**: User description: "とりあえず分散KVSの部分を使えるようにし、強整合性モードと結果整合性モードを実用可能な状態に持っていくまでの仕様を考えてください。"
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - 強整合性クラスタを安全に稼働 (Priority: P1)
|
||
|
||
SRE/オペレータは、固定メンバー（例: 3ノード）のKVSクラスタを強整合性モードで起動し、書き込み・読み出しが常に最新状態で返ることを保証したい。
|
||
|
||
**Why this priority**: 強整合性がS3メタデータやSNSイベントの正確さの土台になるため。
|
||
|
||
**Independent Test**: 少なくとも3ノード構成で、リーダー経由のPut/Getが直ちに反映し、ダウン直後もコミット済みデータが失われないことを検証。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** 3ノードが強整合性モードで起動済み、**When** リーダーにキーを書き込み、**Then** 即座に全ノードで最新値が読み出せる（リーダーからの再取得）。
|
||
2. **Given** 1ノードを停止、**When** 残り2ノードで読み書き、**Then** コミットは継続しデータ欠損がない（クォーラム成立時のみコミット）。
|
||
|
||
---
|
||
|
||
### User Story 2 - 結果整合性モードで高スループット運用 (Priority: P1)
|
||
|
||
オペレータは、イベント処理や一時的なスパイク負荷向けに結果整合性モードを選択し、高スループットな書き込みを許容しつつ、一定時間内に最終的に同期させたい。
|
||
|
||
**Why this priority**: 書き込み偏重ワークロードでの性能確保とコスト最適化のため。
|
||
|
||
**Independent Test**: 結果整合性モードで大量Put後、一定のタイムウィンドウ内に全ノードへ反映し、古い値が一定時間内に整合することを確認。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** 結果整合性モードでキーを書き込み、**When** 1秒以内に別ノードから読み出し、**Then** 必ずしも最新とは限らないが一定時間後（例: 数秒以内）に最新値へ収束する。
|
||
2. **Given** ネットワーク分断後に復旧、**When** 再同期処理が走る、**Then** コンフリクトは定義済みポリシー（例: last-write-wins）で解決される。
|
||
|
||
---
|
||
|
||
### User Story 3 - モード切替と運用観測 (Priority: P2)
|
||
|
||
オペレータは、環境やワークロードに応じて強整合性/結果整合性モードを設定単位で切り替え、状態監視と異常検知ができることを望む。
|
||
|
||
**Why this priority**: 運用現場での柔軟性と安全性の両立が必要なため。
|
||
|
||
**Independent Test**: モード設定変更後の再起動またはローリング適用で、設定が反映され、メトリクス/ログで確認できる。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** クラスタ設定を強整合性→結果整合性に変更、**When** ローリングで適用、**Then** 全ノードが新モードで稼働し、メトリクスにモードが反映される。
|
||
2. **Given** モード不一致のノードが存在、**When** オペレータが状況を確認、**Then** 管理UI/CLI/ログで不一致を検知でき、是正手順が明示される。
|
||
|
||
### Edge Cases
|
||
|
||
- メンバー数がクォーラムを下回った状態での書き込み要求（強整合性では拒否、結果整合性ではキューイング/部分反映）。
|
||
- ネットワーク分断後の再結合時、双方が進んだログを持つ場合の解決順序。
|
||
- モード切替途中に障害が発生した場合のリカバリ手順と一貫性確保。
|
||
- データサイズやホットキー偏重時のスロットリング/バックプレッシャー挙動。
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: システムは強整合性モードでクォーラム書き込み/読み出しを行い、コミット済みデータを即時参照可能にする。
|
||
- **FR-002**: システムは結果整合性モードで書き込みを受け付け、定義された収束時間内に全ノードへ反映させる。
|
||
- **FR-003**: モード設定は名前空間単位で指定でき、クラスタは複数モードを同居させられる。
|
||
- **FR-004**: 結果整合性モードのコンフリクト解決はデフォルトで last-write-wins（LWW）を採用し、設定で他方式を選択できる。
|
||
- **FR-005**: モード変更は安全な手順（ローリング適用または再起動）で反映され、途中失敗時はロールバック手段がある。
|
||
- **FR-006**: 強整合性モードではクォーラム未達時に書き込みを拒否し、明示的なエラーを返す。
|
||
- **FR-007**: 結果整合性モードではクォーラム未達時も書き込みを受け付け、後続の同期で補填し、未反映の可能性をクライアントに示せる。
|
||
- **FR-008**: 再起動/障害復旧後、保存されたログ/スナップショットから整合した状態へ自動復元し、必要な再同期を実行する。
|
||
- **FR-009**: モード別の観測指標（レイテンシ、未同期レプリカ数、収束時間、拒否率）をメトリクス/ログとして出力する。
|
||
- **FR-010**: 運用者がモード状態や不一致を確認できるCLI/ログ/メトリクス情報を提供する。
|
||
|
||
### Key Entities
|
||
|
||
- **ClusterConfig**: クラスタID、ノード一覧、レプリカ数、現在の整合性モード、適用ステータス。
|
||
- **ConsistencyPolicy**: モード種別（強整合/結果整合）、コンフリクト解決ポリシー、収束目標時間、適用範囲（クラスタ/名前空間）。
|
||
- **ReplicationState**: ノードごとのログ進行度、未同期エントリ数、最後の収束時刻、ヘルス状態。
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: 強整合性モードでの書き込み→読み出しがクォーラム成立時に最新値を即時返し、可用ノードがクォーラム未満なら明示的に失敗を返すことが確認できる。
|
||
- **SC-002**: 結果整合性モードでの書き込みは、許容する収束時間内（例: 数秒以内）に全レプリカへ反映し、反映遅延をメトリクスで観測できる。
|
||
- **SC-003**: ネットワーク分断からの復旧時、コンフリクト解決ポリシーに従ってデータが一貫した状態に自動で収束することをテストで確認できる。
|
||
- **SC-004**: モード変更操作が安全に完了し、変更後のモードと各ノードの適用状況をメトリクス/ログで確認できる。
|