fix: improve Raft log compaction safety, refine election logic, and u…

[samuel025]

…pdate repository documentation

Summary by CodeRabbit

Release Notes

• Documentation
  • Added official documentation link in README
• Chores
  • Updated build artifact exclusions for additional directories
• Refactor
  • Improved concurrency handling in log compaction and snapshot management
  • Enhanced replication mechanism with better state isolation
  • Optimized committed entry application with asynchronous compaction scheduling

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5793ce05-d924-4267-970e-efcd95505fc1

📥 Commits

Reviewing files that changed from the base of the PR and between 9d19269 and 644d9af.

📒 Files selected for processing (4)

• .gitignore
• README.md
• drmq-broker/src/main/java/com/drmq/broker/raft/RaftLog.java
• drmq-broker/src/main/java/com/drmq/broker/raft/RaftNode.java

---

📝 Walkthrough

Walkthrough

RaftLog.compact is refactored from method-level synchronization to fine-grained locking with concurrent-modification detection and atomic file swap. RaftNode adds per-peer snapshotInProgress tracking, an isCompacting guard for async compaction, propagates an explicit proposed term through election entry points, locks resetElectionTimer, captures replication locals under lock, and counts snapshotting peers in quorum checks.

Changes

Raft Concurrency Improvements

Layer / File(s)	Summary
New concurrency state fields drmq-broker/src/main/java/com/drmq/broker/raft/RaftNode.java	Adds snapshotInProgress per-peer Map and isCompacting AtomicBoolean to gate asynchronous compaction and track active snapshot installations.
RaftLog.compact fine-grained locking and concurrent-modification handling drmq-broker/src/main/java/com/drmq/broker/raft/RaftLog.java	Removes method-level synchronized; wraps initial index calculations in synchronized(this). Disk-rewrite phase verifies log size at swap time, appends concurrently added entries, performs atomic file swap with error recovery, and rebuilds entries/filePositions.
Election flow with explicit proposed term drmq-broker/src/main/java/com/drmq/broker/raft/RaftNode.java	resetElectionTimer is locked. Pre-vote success calls startElection(proposedTerm). startElection(long proposedTerm) aborts when currentTerm >= proposedTerm, assigns currentTerm = proposedTerm, and calls savePersistentState + resetElectionTimer.
Snapshot in-progress tracking and quorum adjustment drmq-broker/src/main/java/com/drmq/broker/raft/RaftNode.java	sendInstallSnapshotToPeer sets snapshotInProgress=true before creation, updates lastContactTime during transfer, and clears the flag in finally. checkQuorum counts peers with active snapshot installs as reachable.
replicateTo local capture and async compaction scheduling drmq-broker/src/main/java/com/drmq/broker/raft/RaftNode.java	replicateTo copies currentTerm, commitIndex, and leaderId into locals under lock before constructing AppendEntriesRequest. Committed-entry application dispatches raftLog.compact to raftExecutor behind an isCompacting CAS.

Project Housekeeping

Layer / File(s)	Summary
.gitignore patterns and README documentation link .gitignore, README.md	Adds ignore entries for drmq-ts-client/build/, .agent/, and drmq-docs/; README gains a link to the official documentation site.

Sequence Diagram(s)

sequenceDiagram
    participant Leader as RaftNode (Leader)
    participant RaftExecutor as raftExecutor
    participant RaftLog as RaftLog.compact
    participant Peer as Peer

    rect rgba(70, 130, 180, 0.5)
        note over Leader,Peer: Snapshot Installation Flow
        Leader->>Leader: snapshotInProgress.put(peer, true)
        Leader->>Peer: sendInstallSnapshot (chunks)
        Peer-->>Leader: ack per chunk
        Leader->>Leader: lastContactTime.put(peer, now)
        Leader->>Leader: finally: snapshotInProgress.put(peer, false)
    end

    rect rgba(34, 139, 34, 0.5)
        note over Leader,RaftLog: Async Compaction on Commit
        Leader->>Leader: isCompacting.compareAndSet(false, true)
        Leader->>RaftExecutor: submit compact(finalCompactIndex)
        RaftExecutor->>RaftLog: compact(finalCompactIndex)
        RaftLog->>RaftLog: synchronized(this) — compute remainingEntries
        RaftLog->>RaftLog: write temp file, verify size, atomic swap
        RaftLog->>RaftLog: rebuild entries/filePositions
        RaftLog-->>RaftExecutor: done
        RaftExecutor->>Leader: finally: isCompacting.set(false)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• samuel025/DRMQ#17: Introduced the pre-vote phase and quorum-loss stepdown in RaftNode, which is the direct foundation for the election term propagation and quorum adjustment changes in this PR.
• samuel025/DRMQ#19: Modified RaftLog.compact and the RaftNode snapshot/compaction flow at the exact same code paths extended here with concurrent-modification handling and async scheduling.

Poem

🐇 Hop, hop, the Raft log spins,
No tangled threads — fine locks begin!
The snapshot peers are counted right,
Elections term-proposed, polite.
Compact async, the disk swaps clean,
The smoothest Raft I've ever seen! 🌿

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/log-compaction

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}