How To Use

Contents

1. Choose a Configuration
   1. Independent Configuration
   2. Embedded Configuration
2. Client Requests

Choose a Configuration

You can configure SpringRaft in different ways, using the different versions that exist, which are servlet and reactive, respectively. With either version, there are two different configurations to choose from, which are Independent and Embedded.

To deploy the different configurations, visit this page.

Independent Configuration

(Click for larger view)

Using application servers apart from the Raft cluster requires deploying twice as many servers, as can be seen in the figure above (3 servers in the Raft cluster and 3 application servers).

The Raft cluster serves as a proxy for the application servers as they intercept all client requests, replicate them and only then invoke them on the application servers. All components of the infrastructure communicate using REST protocol.

(Click for larger view)

The figure above represents the whole process from the invocation of a request by a client until it receives a response. In this illustration the Raft node 8002 acts as the cluster leader, however if the request was invoked on another Raft node, it would be forwarded to the leader (8002).

1. The client invokes a REST request on the Raft cluster leader.
2. The leader invokes an appendEntries on the remaining nodes in the cluster with the new request.
3. The servers respond positively, meaning they have added it to their log.
4. The leader commits the entry with the request and in the next heartbeat makes sure to show that it has already committed the new entry, so that the other servers do the same.
5. After the entry is committed, then it can be applied to the state machine, which in this case means applying the client request to the application server.
6. The application server delivers the response to the request to the corresponding Raft node.
7. Finally, the leader delivers the response from the server to the client.

Embedded Configuration

(Click for larger view)

By joining the Raft algorithm with the application, on the same application server, it will be necessary to deploy the exact number of servers that are intended to be operational.

The Raft algorithm serves as an internal proxy for the application because it intercepts all client requests, changes them, replicate them and only then invoke them on the application.

In this case, communication latency is reduced since both the algorithm and the application are on the same server.

In this case, you need to pay attention to the application stack to be used, i.e., if you want to use Spring MVC then you need to embed the Servlet Package of SpringRaft. If you want to use Spring Reactive, then you need to embed the Reactive Package of SpringRaft. If it is not intended to use Spring at all, then the best solution is to adopt the Independent Configuration.

Client Requests

For the algorithm to be useful, it needs to receive requests from the client, insert them as entries in its log, replicate that entries, apply them to its state machine, and finally respond properly to the client. Although there are several configurations (Servlet, Reactive, Independent and Embedded), client requests are made the same way to servers. Always using REST making normal requests to the endpoints of the application servers.

Note: If the configuration is independent, it means that the requests should be made to the Raft cluster instead of to the application servers. Still, despite invoking requests on different machines, the endpoints to be used are the same as the application servers.

Server Responses

The answers returned to the client come mostly from the application logic and have nothing to do with the Raft algorithm. Raft just delivers them to the client in the same way it received them from the application. However, there are two occasions when the answers come from the Raft algorithm and not from the application. Both situations are explained below.

1. The server that received the request is not the leader, so it redirects the request to the leader, returning a 307 (Temporary Redirection) code.
2. The server that received the request is in the candidate state so it can neither handle the request nor redirect it to the leader because none exists. In this case the server returns a 503 (Unavailable Service) code, with a RETRY_AFTER field with the time of a heartbeat from the Raft algorithm, because it is likely that by the end of this time a leader has already been elected.