docs: Document event and message types

Signed-off-by: Free Ekanayaka <free@ekanayaka.io>

docs/api.rst

@@ -9,4 +9,5 @@ API reference
    core
    events
    updates
-   io
+   messages
+   types

docs/core.rst

@@ -57,10 +57,6 @@ Data types
 
     A single raft server in a cluster.
 
-.. c:type:: raft_id
-
-   Hold the value of a raft server ID. Guaranteed to be at least 64-bit long.
-
 
 Public members
 ^^^^^^^^^^^^^^

docs/events.rst

@@ -3,10 +3,85 @@
 :c:struct:`raft_event` --- External events
 ==========================================
 
+The :c:struct:`raft_event` struct holds information about events such as:
+
+- a new message has been received from another server
+- disk I/O has been completed for persisting data
+- new entries have been submitted for replication
+
+Users of the core :c:struct:`raft` struct are responsible for implementing an
+I/O layer that manages the above events, filling :c:struct:`raft_event` objects
+as appropriate and passing them to the :c:func:`raft_step()` function.
+
 Data types
 ----------
 
 .. c:struct:: raft_event
 
     Represents an external event (for example receiving an RPC message from another
     server). These events are what drive a :c:struct:`raft` object forward.
+
+.. c:enum:: raft_event_type
+
+    Event type codes.
+
+    .. code-block:: C
+
+       enum raft_event_type {
+           RAFT_START = 1,          /* Initial event starting loading persisted data */
+           RAFT_RECEIVE,            /* A message has been received from another server */
+           RAFT_PERSISTED_ENTRIES,  /* Some entries have been persisted to disk */
+           RAFT_PERSISTED_SNAPSHOT, /* A snapshot has been persisted */
+           RAFT_CONFIGURATION,      /* A new committed configuration must be applied */
+           RAFT_SNAPSHOT,           /* A snapshot has been taken */
+           RAFT_TIMEOUT,            /* The timeout has expired */
+           RAFT_SUBMIT,             /* New entries have been submitted */
+           RAFT_CATCH_UP,           /* Start catching-up a server */
+           RAFT_TRANSFER            /* Start transferring leadership to another server */
+       };
+
+Public members
+^^^^^^^^^^^^^^
+
+.. c:member:: raft_time raft_event.time
+
+    Event timestamp. Must always be filled with the current time.
+
+.. c:member:: enum raft_event_type raft_event.type
+
+    Event type. Must be filled with the type code of the event.
+
+.. c:member:: unsigned short raft_event.capacity
+
+    Disk capacity that has been reserved and is guaranteed to be available.
+
+.. c:member:: struct @0 raft_event.start
+
+    To be filled when :c:struct:`raft_event.type` is :c:enum:`RAFT_START`.
+
+    It contains all state persisted on disk by the server.
+
+    .. code-block:: C
+
+       struct
+       {
+            raft_term term;                          /* Current term */
+            raft_id voted_for;                       /* Current vote */
+            struct raft_snapshot_metadata *metadata; /* Last snapshot, if any */
+            raft_index start_index;                  /* Index of first entry */
+            struct raft_entry *entries;              /* Persisted entries */
+            unsigned n_entries;                      /* Number of persisted entries */
+        } start;
+
+.. c:member:: struct @0 raft_event.receive
+
+    To be filled when :c:struct:`raft_event.type` is :c:enum:`RAFT_RECEIVE`.
+
+    It contains the :c:struct:`raft_message` being received.
+
+    .. code-block:: C
+
+       struct
+       {
+            struct raft_message *message; /* Message being received */
+       } receive;

docs/messages.rst

@@ -0,0 +1,98 @@
+.. _messages:
+
+:c:struct:`raft_message` --- RPC messages
+=========================================
+
+The :c:struct:`raft_message` struct holds information about a single RPC message
+being received or sent over the network.
+
+Data types
+----------
+
+.. c:enum:: raft_message_type
+
+    RPC message type codes.
+
+    .. code-block:: C
+
+       enum raft_event_type {
+           RAFT_APPEND_ENTRIES = 1,
+           RAFT_APPEND_ENTRIES_RESULT,
+           RAFT_REQUEST_VOTE,
+           RAFT_REQUEST_VOTE_RESULT,
+           RAFT_INSTALL_SNAPSHOT,
+           RAFT_TIMEOUT_NOW
+       };
+
+.. c:struct:: raft_request_vote
+
+    Holds the parameters of a `RequestVote` RPC request message.
+
+    .. code-block:: C
+
+       struct raft_request_vote
+       {
+           unsigned char version;     /* Message format version. */
+           raft_term term;            /* Candidate's term */
+           raft_id candidate_id;      /* ID of the server requesting the vote */
+           raft_index last_log_index; /* Index of candidate's last log entry */
+           raft_index last_log_term;  /* Term of log entry at last_log_index */
+           bool disrupt_leader;       /* True if current leader should be discarded */
+           bool pre_vote;             /* True if this is a pre-vote request */
+       };
+
+.. c:struct:: raft_request_vote_result
+
+    Holds the parameters of a `RequestVote` RPC result message.
+
+    .. code-block:: C
+
+       struct raft_append_entries_result
+       {
+           unsigned char version;     /* Message format version */
+           raft_term term;            /* Receiver's current_term */
+           raft_index rejected;       /* If non-zero, the index that was rejected */
+           raft_index last_log_index; /* Receiver's last log entry index, as hint */
+           unsigned short features;   /* Feature flags (since version 1) */
+           unsigned short capacity;   /* Reserved disk capacity for log entries */
+       };
+
+.. c:struct:: raft_append_entries
+
+    Holds the parameters of an `AppendEntries` RPC request message.
+
+    .. code-block:: C
+
+       struct raft_append_entries
+       {
+           unsigned char version;      /* Message format version */
+           raft_term term;             /* Leader's term */
+           raft_index prev_log_index;  /* Index of log entry preceeding new ones */
+           raft_term prev_log_term;    /* Term of entry at prev_log_index */
+           raft_index leader_commit;   /* Leader's commit index */
+           struct raft_entry *entries; /* Log entries to append */
+           unsigned n_entries;         /* Size of the log entries array */
+       };
+
+.. c:struct:: raft_message
+
+    Union of all RPC message structs, plus information about the sender or the
+    receiver (depending on whether the message is being sent or received).
+
+    .. code-block:: C
+
+       struct raft_message
+       {
+           enum raft_message_type type; /* RPC type code */
+           raft_id server_id;           /* ID of sending or destination server */
+           const char *server_address;  /* Address of sending or destination server */
+           union {                      /* Type-specific data */
+               struct raft_request_vote request_vote;
+               struct raft_request_vote_result request_vote_result;
+               struct raft_append_entries append_entries;
+               struct raft_append_entries_result append_entries_result;
+               struct raft_install_snapshot install_snapshot;
+               struct raft_timeout_now timeout_now;
+           };
+       };
+

docs/types.rst

@@ -0,0 +1,51 @@
+.. _types:
+
+Basic types
+===========
+
+Basic types and utilities.
+
+Data types
+----------
+
+.. c:type:: raft_id
+
+   Hold the value of a Raft server ID. Guaranteed to be at least 64-bit long.
+
+.. c:type:: raft_term
+
+   Hold the value of a Raft term. Guaranteed to be at least 64-bit long.
+
+.. c:type:: raft_index
+
+   Hold the value of a raft entry index. Guaranteed to be at least 64-bit long.
+
+.. c:type:: raft_time
+
+    Hold a time value expressed in milliseconds since the epoch.
+
+.. c:struct:: raft_buffer
+
+    A data buffer.
+
+    .. code-block:: C
+
+       struct raft_buffer
+       {
+           void *base; /* Pointer to the buffer data */
+           size_t len; /* Length of the buffer */
+       };
+
+.. c:struct:: raft_entry
+
+    A single entry in the raft log.
+
+    .. code-block:: C
+
+       struct raft_entry
+       {
+           raft_term term;         /* Term in which the entry was created */
+           unsigned short type;    /* Type (FSM command, barrier, config change) */
+           struct raft_buffer buf; /* Entry data */
+           void *batch;            /* Batch that buf's memory points to, if any */
+       };