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>
4.9 KiB
Feature Specification: Raft Core Replication
Feature Branch: 002-raft-features
Created: 2025-12-01
Status: Draft
Input: User description: "Raft関連の機能についてお願いします。"
Clarifications
Session 2025-12-01
- Q: Should this phase assume fixed 3-node membership or include dynamic membership? → A: Fixed 3-node, extensible for future scaling.
User Scenarios & Testing (mandatory)
User Story 1 - Single-Node Raft Baseline (Priority: P1)
As a platform engineer, I want a single-node Raft instance to accept proposals, elect a leader, and persist committed entries so I can validate the log/storage plumbing before scaling out.
Why this priority: Establishes correctness of log append/apply and persistence; blocks multi-node rollout.
Independent Test: Start one node, trigger self-election, propose an entry, verify it is committed and applied to storage with the expected data.
Acceptance Scenarios:
- Given a single node started fresh, When it campaigns, Then it becomes leader and can accept proposals.
- Given a proposed entry "e1", When it commits, Then storage contains "e1" and last index increments by 1.
User Story 2 - Multi-Node Replication (Priority: P1)
As a platform engineer, I want a 3-node Raft cluster to replicate entries to a majority so that writes remain durable under follower failure.
Why this priority: Majority replication is the core availability guarantee of Raft.
Independent Test: Start 3 nodes, elect a leader, propose an entry; verify leader and at least one follower store the entry at the same index/term and report commit.
Acceptance Scenarios:
- Given a 3-node cluster, When a leader is elected, Then at least two nodes acknowledge commit for the same index/term.
- Given a committed entry on the leader, When one follower is stopped, Then the other follower still receives and persists the entry.
User Story 3 - Failure and Recovery (Priority: P2)
As an operator, I want a stopped follower to recover and catch up without losing committed data so that the cluster can heal after restarts.
Why this priority: Ensures durability across restarts and supports rolling maintenance.
Independent Test: Commit an entry, stop a follower, commit another entry, restart the follower; verify it restores state and applies all committed entries.
Acceptance Scenarios:
- Given a follower stopped after entry N is committed, When the cluster commits entry N+1 while it is down, Then on restart the follower installs both entries in order.
- Given divergent logs on restart, When leader sends AppendEntries, Then follower truncates/aligns to leader and preserves committed suffix.
Edge Cases
- Leader crash immediately after commit but before followers apply.
- Network partition isolating a minority vs. majority; minority must not commit new entries.
- Log holes or conflicting terms on recovery must be reconciled to leader’s log.
Requirements (mandatory)
Functional Requirements
- FR-001: The system MUST support single-node leader election and proposal handling without external coordination.
- FR-002: The system MUST replicate log entries to a majority in a 3-node cluster before marking them committed.
- FR-003: The system MUST persist log entries, hard state (term, vote), and conf state to durable storage so that restarts preserve committed progress.
- FR-004: The system MUST apply committed entries to the underlying storage engine in log order without gaps.
- FR-005: The system MUST prevent a node in a minority partition from committing new entries while isolated.
- FR-006: On restart, a node MUST reconcile its log with the leader (truncate/append) to match the committed log and reapply missing committed entries.
- FR-007: For this phase, operate a fixed 3-node membership (no dynamic add/remove), but architecture must allow future extension to scale out safely.
Key Entities
- Peer: A Raft node with ID, region scope, in-memory state machine, and access to durable Raft storage.
- Raft Log Entry: Indexed record containing term and opaque command bytes; persisted and replicated.
- Hard State: Term, vote, commit index persisted to ensure safety across restarts.
- Conf State: Voter set defining the quorum for replication.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: Single-node bootstraps and accepts a proposal within 2 seconds, committing it and persisting the entry.
- SC-002: In a 3-node cluster, a committed entry is present on at least two nodes within 3 seconds of proposal.
- SC-003: After a follower restart, all previously committed entries are restored and applied in order within 5 seconds of rejoining a healthy leader.
- SC-004: During a minority partition, isolated nodes do not advance commit index or apply uncommitted entries.