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>
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Implementation Plan: Distributed KVS Consistency Modes
|
||
|
||
**Branch**: `003-kvs-consistency` | **Date**: 2025-12-01 | **Spec**: specs/003-kvs-consistency/spec.md
|
||
**Input**: Feature specification from `/specs/003-kvs-consistency/spec.md`
|
||
|
||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
||
|
||
## Summary
|
||
|
||
Deliver a deployable distributed KVS supporting strong consistency (quorum read/write) and eventual consistency (LWW default), with namespace-level mode selection, safe mode switching, convergence/recovery behavior, and observability.
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: Rust (stable, via Nix flake)
|
||
**Primary Dependencies**: raft-rs, tonic/prost gRPC, RocksDB, tokio
|
||
**Storage**: RocksDB for raft log/state and KV data
|
||
**Testing**: cargo test (unit/integration), extend rdb-server multi-node tests for namespace/mode behaviors
|
||
**Target Platform**: Linux server (Nix dev shell)
|
||
**Project Type**: Distributed server (rdb-server) with gRPC API/CLI
|
||
**Performance Goals**: Strong mode quorum commit p95 ~1–2s; eventual mode convergence within a few seconds under normal network; observable lag metrics
|
||
**Constraints**: Constitution (test-first, observability, compatibility); fixed membership scope for this phase; namespace-level mode config
|
||
**Scale/Scope**: Small cluster (3–5 nodes) dev target; multiple namespaces with per-namespace mode
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
- Test-First: Add/extend integration tests for strong/eventual modes, namespace config, convergence/recovery.
|
||
- Reliability & Coverage: Keep existing Raft tests green; new tests cover mode behaviors and failures.
|
||
- Simplicity & Readability: Reuse existing crates and current server structure; avoid bespoke protocols.
|
||
- Observability: Structured logs/metrics for mode, convergence lag, quorum status, config state.
|
||
- Versioning & Compatibility: Call out any gRPC/contract changes; fixed membership scope maintained.
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/003-kvs-consistency/
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
├── contracts/
|
||
└── tasks.md # via /speckit.tasks
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
rdb-server/
|
||
src/
|
||
peer.rs
|
||
peer_manager.rs
|
||
raft_service.rs
|
||
config/ # add namespace/mode config handling
|
||
api/ # gRPC handlers (mode/config endpoints if needed)
|
||
tests/
|
||
test_replication.rs (extend for mode/namespace cases)
|
||
|
||
rdb-proto/
|
||
src/*.proto # update if API exposes mode/config
|
||
|
||
scripts/
|
||
verify-raft.sh # update or add mode verification script
|
||
```
|
||
|
||
**Structure Decision**: Extend existing rdb-server layout with namespace/mode config, tests under rdb-server/tests, contracts under specs/003-kvs-consistency/contracts.
|
||
|
||
## Complexity Tracking
|
||
|
||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||
|
||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||
|-----------|------------|-------------------------------------|
|
||
| N/A | | |
|