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>
69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# Implementation Plan: Raft Core Replication
|
|
|
|
**Branch**: `002-raft-features` | **Date**: 2025-12-01 | **Spec**: [specs/002-raft-features/spec.md](specs/002-raft-features/spec.md)
|
|
**Input**: Feature specification from `/specs/002-raft-features/spec.md`
|
|
|
|
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
|
|
## Summary
|
|
|
|
Implement Raft core replication for FlareDB: single-node bootstrap with durable log/hard/conf state, majority replication across a fixed 3-node cluster, and follower recovery/catch-up. Build on the existing Rust workspace (raft-rs, RocksDB) with tonic-based transport already present in the repo.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Rust (stable, via Nix flake)
|
|
**Primary Dependencies**: `raft` (tikv/raft-rs 0.7, prost codec), `tokio`, `tonic`/`prost`, `rocksdb`, `slog`
|
|
**Storage**: RocksDB column families (`raft_log`, `raft_state`) for log, hard state, and conf state
|
|
**Testing**: `cargo test` (unit/integration), scripted multi-node harness to be added for replication scenarios
|
|
**Target Platform**: Linux (x86_64), Nix dev shell
|
|
**Project Type**: Rust workspace (multi-crate: rdb-proto, rdb-storage, rdb-server, rdb-pd, rdb-client, rdb-cli)
|
|
**Performance Goals**: From spec SCs — single-node commit ≤2s; 3-node majority commit ≤3s; follower catch-up ≤5s after rejoin
|
|
**Constraints**: Fixed 3-node membership for this phase; no dynamic add/remove; minority must not commit
|
|
**Scale/Scope**: Cluster size 3; log volume moderate (dev/test scale) sufficient to validate recovery and catch-up
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- Test-First: Plan includes unit/integration tests for Raft storage, proposal/commit, and recovery paths.
|
|
- Reliability & Coverage: CI to run `cargo test`; integration harness to cover cross-node replication.
|
|
- Simplicity & Readability: Use existing crates (raft-rs, rocksdb); avoid bespoke protocols.
|
|
- Observability: Ensure structured logs on Raft events/errors; failures must be actionable.
|
|
- Versioning & Compatibility: Proto changes, if any, must be called out; fixed membership avoids dynamic reconfig in this phase.
|
|
No constitution violations identified; gate PASS.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/002-raft-features/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output
|
|
└── tasks.md # Phase 2 output (via /speckit.tasks)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
Cargo.toml # workspace
|
|
rdb-proto/ # proto definitions
|
|
rdb-storage/ # RocksDB storage + Raft CFs
|
|
rdb-server/ # Raft peer, gRPC services
|
|
rdb-pd/ # placement driver (not primary in this feature)
|
|
rdb-client/ # client SDK/CLI (control hooks if needed)
|
|
rdb-cli/ # auxiliary CLI
|
|
scripts/ # verification scripts
|
|
tests/ # integration harness (to be added under rdb-server or workspace)
|
|
```
|
|
|
|
**Structure Decision**: Use existing Rust workspace layout; place Raft-focused tests/harness under `rdb-server/tests` or workspace `tests/` as appropriate; contracts under `specs/002-raft-features/contracts/`.
|
|
|
|
## Complexity Tracking
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| N/A | | |
|