SOFAJRaft Documentation

For detailed information, refer to the following official resources:

• User Guide: https://www.sofastack.tech/projects/sofa-jraft/overview
• Counter Example Detailed Explanation: https://www.sofastack.tech/projects/sofa-jraft/counter-example
• Release Logs: https://www.sofastack.tech/projects/sofa-jraft/release-log

You can perform a smooth hot upgrade to LogitLogStorage by leveraging Raft's membership change capabilities. This method avoids direct storage migration by letting new nodes sync data from the leader.

Steps for Hot Upgrade:

1. Start with an existing cluster (e.g., nodes A, B, C) running the old version.
2. Use CliService.changePeers to add new nodes (e.g., D, E, F) running the new version. These nodes will automatically replicate the existing logs from the current Leader.
3. Once the new nodes are caught up, use CliService.transferLeader to move the leadership to one of the new nodes (e.g., node D).
4. Shut down the old nodes (A, B, C).

For detailed usage and implementation guidance, refer to the following official resources:

• User Guide: Overview and detailed documentation
• Counter Example: Specific details on the Counter implementation example
• Release Notes: Version history and changelogs

To compile SOFAJRaft from source, ensure you have the following installed:

• JDK 8 or higher
• Maven 3.2.5 or higher

To compile SOFAJRaft from source, you must meet the following requirements:

• JDK: 8 or higher
• Maven: 3.2.5 or higher

To upgrade from the legacy RocksDBLogStorage to the new Java-based LogitLogStorage without data loss, use the HybridLogStorage implementation. This hybrid storage manages both old and new storage engines simultaneously.

Upgrade Process:

1. Set the default service factory to LogitLogJRaftServiceFactory in your node options.
2. Upon startup, HybridLogStorage calculates a thresholdIndex (the last index in RocksDBLogStorage + 1).
3. As Raft snapshots are taken, the truncateIndex (the point where old logs are removed) will eventually exceed the thresholdIndex.
4. Once the truncateIndex is beyond the thresholdIndex, the old RocksDBLogStorage is no longer needed and can be safely shut down.

nodeOptions.setServiceFactory(new LogitLogJRaftServiceFactory());

The client_benchmark_start.sh script is used to launch client benchmark processes for SOFAJRaft. It automatically calculates JVM memory settings based on the system's total memory and requires Java 1.8. The script runs the benchmark in the background using nohup and redirects output to client_stdout.

Usage:

./client_benchmark_start.sh <arg1> <arg2> <arg3> <arg4> <arg5> <arg6> <arg7> <arg8>

Requirements:

• Java Version: Must be Java 1.8. The script will exit with an error if other versions are detected.
• Environment: Requires $JAVA_HOME to be set correctly.
• Arguments: The script accepts up to 8 positional arguments which are passed directly to the com.alipay.sofa.jraft.benchmark.BenchmarkBootstrap class.

The server_benchmark_start.sh script is used to launch SOFAJRaft server benchmark instances in the background. It automatically calculates optimal JVM memory settings based on the system's total available memory and requires Java 1.8.

To run a benchmark server, execute the script from the jraft-example/bin/ directory, providing the required positional arguments for the benchmark configuration.

Usage:

./server_benchmark_start.sh <arg1> <arg2>

Requirements:

• Java Version: Must be Java 1.8. The script will exit with an error if other versions are detected.
• Environment: Requires JAVA_HOME to be set correctly.
• Output: Standard output and error are redirected to server_stdout in the execution directory.
• Execution Mode: The process is started using nohup in the background.

SOFAJRaft supports a replication pipeline mode to optimize AppendEntries requests. When enabled, the AppendEntriesRequestProcessor uses a specialized PeerExecutorSelector and SequenceRpcRequestClosure to handle requests in a pipelined fashion, ensuring responses are sent in the correct sequence.

To enable this behavior, ensure that isReplicatorPipeline() is set to true in your RaftOptions.

Note: When pipeline mode is active, the system tracks the number of pending responses. If the number of pending responses exceeds maxReplicatorInflightMsgs (configured in RaftOptions), the connection to that peer will be closed to prevent resource exhaustion.

The LogitLogStorage system uses two primary file types: IndexFile and SegmentFile.

IndexFile

Stores fixed-size index entries (10 bytes each). An entry consists of:

• Magic byte: [0x57] (1 byte)
• Index type: Indicates if the log is a regular log or a Conf type log (1 byte)
• Offset: The entry's offset relative to the start of the file (4 bytes)
• Position: The physical position of the log in the SegmentFile (4 bytes)

SegmentFile

Stores the actual log data. An entry consists of:

• Magic bytes: [0x57, 0x8A] (2 bytes)
• Data length: The size of the log data (4 bytes)
• Data: The actual log payload (variable bytes)