### start_server/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts an RA server.

```APIDOC
## start_server/2

### Description
Starts an RA server.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **server_id** (type) - Required - The ID of the server to start.
- **options** (type) - Required - Options for starting the server.

### Request Example
`ra:start_server(ServerID, Options).

### Response
Success: The RA server is started.

```

--------------------------------

### Starting a `ra` Cluster with `ra_kv`

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/STATE_MACHINE_TUTORIAL.md

Demonstrates how to start a `ra` cluster using `ra:start_cluster/3`, configuring it to use the `ra_kv` state machine with specified members and cluster name.

```erlang
start() ->
    %% the initial cluster members
    Members = [{ra_kv1, node()}, {ra_kv2, node()}, {ra_kv3, node()}],
    %% an arbitrary cluster name
    ClusterName = <<"ra_kv">>,
    %% the config passed to `init/1`, must be a `map`
    Config = #{},
    %% the machine configuration
    Machine = {module, ?MODULE, Config},
    %% ensure ra is started
    application:ensure_all_started(ra),
    %% start a cluster instance running the `ra_kv` machine
    ra:start_cluster(ClusterName, Machine, Members).
```

--------------------------------

### Configure Ra Server with User-Provided UID

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/INTERNALS.md

Example configuration for starting a Ra server or cluster, demonstrating how to provide a user-defined UID. The UID must conform to the base64url standard and ensures uniqueness across cluster incarnations.

```erlang
Config = #{cluster_name => <<"ra-cluster-1">>,
           server_id => {ra_cluster_1, ra1@snowman},
           uid => <<"ra_cluster_1_1519808362841">>
           ...},

```

--------------------------------

### Example Live Indexes Implementation for ra_kv

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

An example implementation of the `live_indexes/1` callback for the `ra_kv` key-value store, retaining only indexes associated with keys.

```erlang
live_indexes(#state{keys = Keys}) ->
    [Idx || _K := {Idx, _Hash} <- Keys].
```

--------------------------------

### Snapshot Install Protocol Sequence Diagram

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

Illustrates the communication flow between Leader and Follower during the snapshot installation process, including initialization, pre-phase entry transfer, and final chunk transfer.

```mermaid
sequenceDiagram
    participant Leader
    participant Follower

    Leader->>Follower: install_snapshot_rpc (init phase)
    Follower-->>Leader: install_snapshot_result

    Leader->>Leader: Query follower's last_applied
    Leader->>Leader: Filter live indexes > last_applied

    loop For each chunk of live indexes
        Leader->>Leader: Read entries from log
        Leader->>Follower: install_snapshot_rpc (pre phase, entries)
        Follower->>Follower: write_sparse entries to log
        Follower-->>Leader: install_snapshot_result
    end

    loop For each snapshot chunk
        Leader->>Follower: install_snapshot_rpc (next/last phase, chunk)
        Follower->>Follower: Accept chunk
        Follower-->>Leader: install_snapshot_result
    end

    Follower->>Follower: Complete snapshot, recover state
    Follower->>Follower: Calculate live_indexes from state
    Follower->>Follower: Write indexes file
```

--------------------------------

### start/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts the RA application.

```APIDOC
## start/0

### Description
Starts the RA application.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
None.

### Request Example
`ra:start().`

### Response
Success: The RA application is started.

```

--------------------------------

### start_default/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_system.html

Starts the RA system with default configuration settings. This is a convenience function for quick initialization.

```APIDOC
## start_default/0

### Description
Starts the RA system with default configuration settings.

### Function Signature
start_default()

### Parameters
None.
```

--------------------------------

### start/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts the RA application.

```APIDOC
## start/1

### Description
Starts the RA application.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **param1** (type) - Required - Description not specified.

### Request Example
`ra:start(Arg1).`

### Response
Success: The RA application is started.

```

--------------------------------

### Checkpoint Configuration Example

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

Shows how to configure the maximum number of checkpoints to retain on the system.

```erlang
#{max_checkpoints => 3}  %% Maximum number of checkpoints to retain
```

--------------------------------

### start_in/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts the RA application with a specified data directory. This is equivalent to calling ra:start with the data_dir option. If the application is running, it will be stopped and restarted.

```APIDOC
## start_in/1

### Description
Starts the RA application using a specified data directory. Restarts the application if it is already running.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **DataDir** (file:filename) - Required - The directory to use for data storage.

### Request Example
N/A

### Response
#### Success Response (ok)
- **Started** (term) - A list of started server identifiers.

#### Response Example
```json
{
  "ok": [
    "server1_id",
    "server2_id"
  ]
}
```
```

--------------------------------

### start_cluster/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts a new distributed RA cluster using a list of server configurations. It returns the list of successfully started and not started server IDs, or an error if the cluster cannot be formed. Servers that could not be started need to be retried.

```APIDOC
## start_cluster/2

### Description
Starts a new distributed RA cluster using a list of initial server configurations. This function is suitable for setting up a cluster with detailed server settings.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **System** (atom()) - The system name.
- **ServerConfigs** ([[ra_server:ra_server_config()]]) - A list of initial server configurations.

### Returns
- **{ok, Started, NotStarted}** - A tuple where `Started` is a list of successfully started `ra_server_id()` and `NotStarted` is a list of `ra_server_id()` that could not be started. This is returned if a cluster could be successfully started (more than half of the servers provided could be started).
- **{error, cluster_not_formed}** - Returned if a cluster could not be started. If a cluster could not be formed, any servers that did manage to start are forcefully deleted.

### See also
[start_server/1](#start_server-1)
```

--------------------------------

### start_cluster/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts a new distributed RA cluster with a specified timeout, using a list of server configurations. It returns the list of successfully started and not started server IDs, or an error if the cluster cannot be formed. Servers that could not be started need to be retried.

```APIDOC
## start_cluster/3

### Description
Starts a new distributed RA cluster with a custom timeout, using a list of initial server configurations. This function provides more control over the cluster startup process by allowing a specific timeout to be set.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **System** (atom()) - The system name.
- **ServerConfigs** ([[ra_server:ra_server_config()]]) - A list of initial server configurations.
- **Timeout** (non_neg_integer()) - The timeout to use for starting the cluster.

### Returns
- **{ok, Started, NotStarted}** - A tuple where `Started` is a list of successfully started `ra_server_id()` and `NotStarted` is a list of `ra_server_id()` that could not be started. This is returned if a cluster could be successfully started (more than half of the servers provided could be started).
- **{error, cluster_not_formed}** - Returned if a cluster could not be started. If a cluster could not be formed, any servers that did manage to start are forcefully deleted.

### See also
[start_cluster/2](#start_cluster-2), [start_server/1](#start_server-1)
```

--------------------------------

### Start Ra Cluster and Process Commands

Source: https://github.com/rabbitmq/ra/blob/main/README.md

This snippet demonstrates starting a Ra cluster with a simple state machine and processing commands. Ensure Erlang nodes are running and have distribution enabled.

```erlang
ErlangNodes = ['ra1@hostname.local', 'ra2@hostname.local', 'ra3@hostname.local'],
[io:format("Attempting to communicate with node ~s, response: ~s~n", [N, net_adm:ping(N)]) || N <- ErlangNodes],
[rpc:call(N, ra, start, []) || N <- ErlangNodes],
ServerIds = [{quick_start, N} || N <- ErlangNodes],
ClusterName = quick_start,
Machine = {simple, fun erlang:'+'/2, 0},
{ok, ServersStarted, _ServersNotStarted} = ra:start_cluster(default, ClusterName, Machine, ServerIds),
{ok, StateMachineResult, LeaderId} = ra:process_command(hd(ServersStarted), 5),
{ok, 12, LeaderId1} = ra:process_command(LeaderId, 7).
```

--------------------------------

### start_cluster/4

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts a new distributed RA cluster with a specified list of server IDs. It returns the list of successfully started and not started server IDs, or an error if the cluster cannot be formed. Servers that could not be started need to be retried.

```APIDOC
## start_cluster/4

### Description
Starts a new distributed RA cluster. This function is used to initiate a cluster with a predefined set of servers. It provides feedback on which servers were successfully started and which require further attention.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **System** (atom()) - The system name.
- **ClusterName** ([ra_cluster_name()]) - The name of the cluster.
- **Machine** ([ra_server:machine_conf()]) - The machine configuration.
- **ServerIds** ([[ra_server_id()]]) - The list of RA server IDs.

### Returns
- **{ok, Started, NotStarted}** - A tuple where `Started` is a list of successfully started `ra_server_id()` and `NotStarted` is a list of `ra_server_id()` that could not be started. This is returned if a cluster could be successfully started (more than half of the servers provided could be started).
- **{error, cluster_not_formed}** - Returned if a cluster could not be started. If a cluster could not be formed, any servers that did manage to start are forcefully deleted.

### See also
[start_server/1](#start_server-1)
```

--------------------------------

### start/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_system.html

Starts the RA system with a given configuration. This function takes a configuration record and initiates the system's processes.

```APIDOC
## start/1

### Description
Starts the RA system with a given configuration.

### Function Signature
start(Config :: config())

### Parameters
* **Config** (config()) - Required - The configuration for the RA system.
```

--------------------------------

### start_server/5

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts an individual RA server of a cluster.

```APIDOC
## start_server/5

### Description
Starts an individual RA server of a cluster.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **server_id** (type) - Required - The ID of the server to start.
- **options** (type) - Required - Options for starting the server.
- **timeout** (integer) - Required - The timeout for the operation.
- **retry_delay** (integer) - Required - The delay between retries.

### Request Example
`ra:start_server(ClusterID, ServerID, Options, Timeout, RetryDelay).

### Response
Success: The individual RA server is started.

```

--------------------------------

### start_server/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts an RA server with a given system name and configuration. The configuration is expected to be a map conforming to `ra_server:ra_server_config()`. Returns an 'ok' tuple or an error tuple.

```APIDOC
## start_server/2

### Description
Starts a RA server.

### Parameters
#### Path Parameters
- **System** (atom()) - The system name.
- **Conf** ([ra_server:ra_server_config()]) - A `ra_server_config()` configuration map.

### Returns
- ok | {error, term()} - `{ok | error, Error}`
```

--------------------------------

### start_in/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts the RA application with a provided data directory.

```APIDOC
## start_in/1

### Description
Starts the RA application with a provided data directory.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **data_dir** (string) - Required - The directory to use for data.

### Request Example
`ra:start_in("/path/to/data").`

### Response
Success: The RA application is started with the specified data directory.

```

--------------------------------

### init/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_leaderboard.html

Initializes the leaderboard system. This function is typically called once at the start of the system.

```APIDOC
## init/0

### Description
Initializes the leaderboard system.

### Function Signature
`init() -> ok`
```

--------------------------------

### Example of Follower's Needed Live Indexes

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

Demonstrates how the follower determines which live indexes it needs based on its 'last_applied' index during snapshot recovery.

```text
- Snapshot at index 2000, term 3
- Live indexes:  [100, 600, 1200, 1777]
- Follower `last_applied` = 1500: needs  [1777] only
- Follower `last_applied` = 1100: needs  [1200, 1777]
```

--------------------------------

### start_or_restart_cluster/5

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts or restarts an RA cluster with a specified timeout. It returns the list of successfully started and not started server IDs, or an error if the cluster cannot be formed. A cluster is considered successfully started if more than half of the provided servers are started.

```APIDOC
## start_or_restart_cluster/5

### Description
Starts or restarts an RA cluster. This function is useful for ensuring cluster availability and can handle both initial cluster formation and recovery scenarios. It returns the status of server startups, indicating which servers were successfully started and which require retries.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **System** (atom()) - The system name.
- **ClusterName** ([ra_cluster_name()]) - The name of the cluster.
- **Machine** ([ra_server:machine_conf()]) - The machine configuration.
- **RemServers** ([[ra_server_id()]]) - A list of remote server IDs.
- **Timeout** (non_neg_integer()) - The time to wait for any server to restart or start.

### Returns
- **{ok, Started, NotStarted}** - A tuple where `Started` is a list of successfully started `ra_server_id()` and `NotStarted` is a list of `ra_server_id()` that could not be started. This is returned if a cluster could be successfully started (more than half of the servers provided could be started).
- **{error, cluster_not_formed}** - Returned if a cluster could not be started. If no existing cluster was found and a new one could not be formed, any servers that did manage to start are forcefully deleted.

### See also
[start_or_restart_cluster/4](#start_or_restart_cluster-4)
```

--------------------------------

### start/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts the RA application with optional environment parameters. If the application is already running, it will be stopped and restarted.

```APIDOC
## start/1

### Description
Starts the RA application with provided parameters. Restarts the application if it is already running.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **Params** (array of environment_param) - Required - A list of environment parameters.

### Request Example
N/A

### Response
#### Success Response (ok)
- **Started** (term) - A list of started server identifiers.

#### Response Example
```json
{
  "ok": [
    "server1_id",
    "server2_id"
  ]
}
```
```

--------------------------------

### Start Erlang Node for Ra Cluster

Source: https://github.com/rabbitmq/ra/blob/main/README.md

This command starts an Erlang node that can be used to host Ra nodes. Replace 'hostname.local' with your actual hostname.

```shell
rebar3 shell --name ra1@hostname.local
```

--------------------------------

### Start Erlang Node with Ra Modules

Source: https://github.com/rabbitmq/ra/blob/main/README.md

Starts an Erlang node using rebar3, ensuring Ra modules are on the code path. Replace 'hostname.local' with your actual hostname.

```shell
# replace hostname.local with your actual hostname
rebar3 shell --name ra1@hostname.local
```

```shell
# replace hostname.local with your actual hostname
rebar3 shell --name ra2@hostname.local
```

--------------------------------

### init/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_directory.html

Initializes the RA directory system. This function starts the necessary components for the directory service.

```APIDOC
## init/1

### Description
Initializes the RA directory system.

### Parameters
#### Path Parameters
- **System** (atom()) - The name of the system to initialize.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (ok)
- Returns `ok` if the system was started successfully.

#### Error Response
- `{error, system_not_started}`: Returned if the system could not be started.
```

--------------------------------

### start_cluster/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts a new distributed RA cluster.

```APIDOC
## start_cluster/2

### Description
Starts a new distributed RA cluster.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **members** (list) - Required - A list of members in the cluster.

### Request Example
`ra:start_cluster(ClusterID, Members).

### Response
Success: A new distributed RA cluster is started.

```

--------------------------------

### start_cluster/4

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts a new distributed RA cluster.

```APIDOC
## start_cluster/4

### Description
Starts a new distributed RA cluster.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **members** (list) - Required - A list of members in the cluster.
- **options** (type) - Required - Options for starting the cluster.
- **timeout** (integer) - Required - The timeout for the operation.

### Request Example
`ra:start_cluster(ClusterID, Members, Options, Timeout).

### Response
Success: A new distributed RA cluster is started.

```

--------------------------------

### Start Second Erlang Node for Ra Cluster

Source: https://github.com/rabbitmq/ra/blob/main/README.md

This command starts a second Erlang node for a Ra cluster. Replace 'hostname.local' with your actual hostname.

```shell
rebar3 shell --name ra2@hostname.local
```

--------------------------------

### restart_server/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Restarts a previously successfully started RA server.

```APIDOC
## restart_server/3

### Description
Restarts a previously successfully started RA server.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **server_id** (type) - Required - The ID of the server to restart.
- **options** (type) - Required - Options for restarting the server.
- **timeout** (integer) - Required - The timeout for the restart operation.

### Request Example
`ra:restart_server(ServerID, Options, Timeout).

### Response
Success: The RA server is restarted.

```

--------------------------------

### snapshot_installed/5

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_machine.html

Callback function invoked when a snapshot has been successfully installed. It receives the current and previous snapshot metadata and states.

```APIDOC
## snapshot_installed/5

### Description
Callback function invoked when a snapshot has been successfully installed. It receives the current and previous snapshot metadata and states.

### Function Signature
snapshot_installed(Module, Meta, State, OldMeta, OldState) -> [effects()](#type-effects)

* Module = module()
* Meta = [ra_snapshot:meta()](ra_snapshot.html#type-meta)
* State = [state()](#type-state)
* OldMeta = [ra_snapshot:meta()](ra_snapshot.html#type-meta)
* OldState = [state()](#type-state)
```

--------------------------------

### Start a Ra Server

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/INTERNALS.md

Initiates a Ra server process. This is a prerequisite for adding a member to an existing cluster.

```erlang
ra:start_server/1
```

--------------------------------

### Compaction Group Example

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/COMPACTION.md

Illustrates the process of forming compaction groups based on live entry percentages and size limits, including handling of dense segments.

```text
Segments to evaluate (oldest to newest):
  Seg1: 1000 entries, 200 live (20%) 
  Seg2: 1000 entries, 300 live (30%) 
  Seg3: 1000 entries, 800 live (80%) 
  Seg4: 1000 entries, 100 live (10%) 
  Seg5: 1000 entries, 150 live (15%) 

Result: 
  Group A: [Seg1, Seg2] 
  Group B: [Seg4, Seg5] 
  Seg3: unchanged (too dense to benefit from compaction)
```

--------------------------------

### restart_server/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Restarts a previously successfully started RA server.

```APIDOC
## restart_server/2

### Description
Restarts a previously successfully started RA server.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **server_id** (type) - Required - The ID of the server to restart.
- **options** (type) - Required - Options for restarting the server.

### Request Example
`ra:restart_server(ServerID, Options).

### Response
Success: The RA server is restarted.

```

--------------------------------

### Implementing State Machine Versioning

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/STATE_MACHINE_TUTORIAL.md

An example demonstrating how to implement state machine versioning by bumping the version number and mapping old and new versions to their respective modules. This ensures deterministic outcomes when applying log entries across different versions.

```erlang
version() -> 1.

which_module(1) -> my_machine;
which_module(0) -> my_machine_v0.
```

--------------------------------

### Trigger Major Compaction Configuration

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/COMPACTION.md

Provides examples of Erlang syntax for configuring the trigger strategy for major compaction.

```erlang
#{major_strategy => {num_minors, 5}}
#{major_strategy => manual}
```

--------------------------------

### stop_default/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_system.html

Stops the RA system that was started with the default configuration. Returns ok or an error tuple.

```APIDOC
## stop_default/0

### Description
Stops the RA system that was started with the default configuration.

### Function Signature
stop_default()

### Returns
- ok | {error, any()} - Ok on successful stop, or an error tuple.
```

--------------------------------

### restart_server/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Restarts a previously started RA server. Returns an error if the server is not found or not registered.

```APIDOC
## restart_server/2

### Description
Restarts a previously started RA server.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **System** (atom) - Required - The system identifier.
- **ServerId** (ra_server_id) - Required - The ID of the server to restart.

### Request Example
N/A

### Response
#### Success Response (ok)
Returns `ok` on successful restart.

#### Error Response
- **error** (term) - Can be `not_found` or `name_not_registered`.

#### Response Example
```json
{
  "ok": null
}
```

```json
{
  "error": "not_found"
}
```
```

--------------------------------

### start_cluster/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_kv.html

Starts a new Ra cluster. It takes the system name, cluster name, and configuration including the list of initial members. Returns the list of server IDs and the leader ID upon successful formation, or an error if the cluster cannot be formed.

```APIDOC
## start_cluster/3

### Description
Starts a new Ra cluster.

### Method
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **System** (atom) - The name of the system.
* **ClusterName** (atom) - The name of the cluster.
* **Config** (map) - Configuration map, must contain a `members` key with a list of `ra_server_id()`.

### Response
* **{ok, [ra_server_id()], [ra_server_id()]}** - On success, returns ok and lists of server IDs and the leader ID.
* **{error, cluster_not_formed}** - If the cluster fails to form.
```

--------------------------------

### Build Ra Project

Source: https://github.com/rabbitmq/ra/blob/main/CONTRIBUTING.md

Build the Ra project using the standard erlang.mk build system. Ensure you have the necessary build tools installed.

```shell
make
```

--------------------------------

### WAL Resend Protocol Example

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

A sequence diagram illustrating the resend protocol between a Ra server and the WAL when a log entry gap is detected.

```erlang
Ra Server                         WAL
    |                              |
    |-- write(Idx=10) -----------> |  writers[UId] = {in_seq, 10}
    |   (Idx=11 lost/delayed)      |
    |-- write(Idx=12) -----------> |  Gap! Expected prev=11, have=10
    |                              |  writers[UId] = {out_of_seq, 10}
    |<-- {resend_write, 11} ------ |
    |                              |
    |-- resend(Idx=11) ----------> |  Prev=10 ✓, write succeeds
    |                              |  writers[UId] = {in_seq, 11}
    |-- resend(Idx=12) ----------> |  Prev=11 ✓, write succeeds
    |                              |  writers[UId] = {in_seq, 12}
```

--------------------------------

### Interacting with the `ra` Cluster using `ra:process_command/2`

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/STATE_MACHINE_TUTORIAL.md

Shows examples of using `ra:process_command/2` to send 'write' and 'read' commands to the `ra_kv` state machine in a running `ra` cluster. This method blocks until consensus is reached.

```erlang
2> ra:process_command(ra_kv1, {write, k, v}).
{ok, ok, {ra_kv1,nonode@nohost}}
3> ra:process_command(ra_kv1, {read, k}).
{ok, v, {ra_kv1,nonode@nohost}}
4> ra:process_command(ra_kv1, {write, k, v2}).
{ok, ok, {ra_kv1,nonode@nohost}}
5> ra:process_command(ra_kv1, {read, k}).
{ok, v2, {ra_kv1,nonode@nohost}}
```

--------------------------------

### leave_and_delete_server/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

A safe way to remove an active server from its cluster. The server will be force removed after a membership transition command was added to the log. The command is added to the log by the `ServerRef` node. Use this to decommission a node that's unable to start or is permanently lost.

```APIDOC
## leave_and_delete_server/3

### Description
A safe way to remove an active server from its cluster. The server will be force removed after a membership transition command was added to the log. The command is added to the log by the `ServerRef` node. Use this to decommission a node that's unable to start or is permanently lost.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **System** (atom()) - The system identifier.
- **ServerRef** (ra_server_id | [ra_server_id]) - The ra server to send the command to and to remove.
- **ServerId** (ra_server_id) - The ra server to force remove.

### Returns
- `ok`
- `timeout`
- `{error, noproc}`

### See also
- `leave_and_delete_server/4`
```

--------------------------------

### begin_snapshot/5

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_snapshot.html

Initiates a snapshot process. It takes metadata, module, module state, snapshot kind, and the current state, returning the new state and a list of effects.

```APIDOC
## begin_snapshot/5

### Description
Initiates a snapshot process. It takes metadata, module, module state, snapshot kind, and the current state, returning the new state and a list of effects.

### Function Signature
begin_snapshot(Meta :: meta(), MacModule :: module(), MacState :: term(), SnapKind :: kind(), State :: state()) -> {state(), [effect()]} 

### Parameters
#### Path Parameters
- **Meta** (meta) - Metadata for the snapshot.
- **MacModule** (module) - The module to use for the snapshot.
- **MacState** (term) - The state of the module.
- **SnapKind** (kind) - The kind of snapshot to begin.
- **State** (state) - The current state.

#### Return Value
- **{state(), [effect()]}** - A tuple containing the updated state and a list of effects.
```

--------------------------------

### begin_accept/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_snapshot.html

Begins the acceptance process for new data. It takes metadata and the current state, returning an 'ok' status and the updated state.

```APIDOC
## begin_accept/2

### Description
Begins the acceptance process for new data. It takes metadata and the current state, returning an 'ok' status and the updated state.

### Function Signature
begin_accept(Meta :: meta(), State :: state()) -> {ok, state()}

### Parameters
#### Path Parameters
- **Meta** (meta) - Metadata for the acceptance process.
- **State** (state) - The current state.

#### Return Value
- **{ok, state()}** - A tuple indicating success and the updated state.
```

--------------------------------

### Ra Sequence Data Structure Example

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/COMPACTION.md

Example illustrating how the `ra_seq` module represents sparse sequences of indexes by compacting adjacent indexes into ranges. The representation is from high to low indexes.

```erlang
%% Example: [100, 101, 102, 500, 501, 600]
%% Stored as: [600, {500, 501}, {100, 102}]  (high to low, ranges compacted)
```

--------------------------------

### Start Ra Cluster with UID Generation

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/INTERNALS.md

Invokes the start cluster function where Ra automatically generates a unique identifier (UID) for each server. This UID is crucial for persistent data identification on disk.

```erlang
ra:start_cluster/3
```

--------------------------------

### init/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_directory.html

Initializes the RA directory system with a specified directory and set of names. This is an alternative initialization method.

```APIDOC
## init/2

### Description
Initializes the RA directory system with a specified directory and set of names.

### Parameters
#### Path Parameters
- **Dir** (file:filename()) - The directory to use for initialization.
- **X2** (ra_system:names()) - A set of names to initialize.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (ok)
- Returns `ok` upon successful initialization.
```

--------------------------------

### Start Ra Server with UID Generation

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/INTERNALS.md

Invokes the start server function where Ra automatically generates a unique identifier (UID). This UID is used for interactions with log and snapshot writer processes.

```erlang
ra:start_server/4
```

--------------------------------

### init_aux/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_machine.html

Initializes auxiliary data for a given machine and name.

```APIDOC
## init_aux/2

### Description
Initializes auxiliary data for a given machine and name.

### Function Signature
init_aux(Mod :: module(), Name :: atom()) -> term()
```

--------------------------------

### start_or_restart_cluster/4

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Starts or restarts an RA cluster.

```APIDOC
## start_or_restart_cluster/4

### Description
Starts or restarts an RA cluster.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **members** (list) - Required - A list of members in the cluster.
- **options** (type) - Required - Options for starting or restarting the cluster.
- **timeout** (integer) - Required - The timeout for the operation.

### Request Example
`ra:start_or_restart_cluster(ClusterID, Members, Options, Timeout).

### Response
Success: The RA cluster is started or restarted.

```

--------------------------------

### start_cluster/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Same as `start_cluster/2` but accepts a custom timeout.

```APIDOC
## start_cluster/3

### Description
Same as `start_cluster/2` but accepts a custom timeout.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **members** (list) - Required - A list of members in the cluster.
- **timeout** (integer) - Required - The custom timeout for the operation.

### Request Example
`ra:start_cluster(ClusterID, Members, Timeout).

### Response
Success: A new distributed RA cluster is started with a custom timeout.

```

--------------------------------

### init/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_machine.html

Initializes a new RA machine. This function is called only during startup if no snapshot is available to recover from. It is never called again once a snapshot has been taken.

```APIDOC
## init/3

### Description
Initializes a new machine. This is only called on startup if there isn't yet a snapshot to recover from. Once a snapshot has been taken this is never called again.

### Function Signature
init(Machine :: [machine()](#type-machine), Name :: atom(), Version :: [version()](#type-version)) -> [state()](#type-state)
```

--------------------------------

### start_or_restart_cluster/5

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Same as `start_or_restart_cluster/4` but accepts a custom timeout.

```APIDOC
## start_or_restart_cluster/5

### Description
Same as `start_or_restart_cluster/4` but accepts a custom timeout.

### Method
Not specified (likely a function call in the RA system).

### Endpoint
Not applicable (function call).

### Parameters
- **cluster_id** (type) - Required - The ID of the cluster.
- **members** (list) - Required - A list of members in the cluster.
- **options** (type) - Required - Options for starting or restarting the cluster.
- **timeout** (integer) - Required - The custom timeout for the operation.
- **custom_timeout** (integer) - Required - A custom timeout value.

### Request Example
`ra:start_or_restart_cluster(ClusterID, Members, Options, Timeout, CustomTimeout).

### Response
Success: The RA cluster is started or restarted with a custom timeout.

```

--------------------------------

### stop_server/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Stops a specified RA server. Returns an error if the node is down or the system is not started.

```APIDOC
## stop_server/2

### Description
Stops a specified RA server.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **System** (atom) - Required - The system name.
- **ServerId** (ra_server_id) - Required - The ID of the server to stop.

### Request Example
N/A

### Response
#### Success Response (ok)
Returns `ok` when the server is stopped successfully.

#### Error Response
- **error** (nodedown | system_not_started) - Indicates if the node is down or the system is not started.

#### Response Example
```json
{
  "ok": null
}
```

```json
{
  "error": "nodedown"
}
```
```

--------------------------------

### overview/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_leaderboard.html

Provides an overview of the leaderboard system. Returns a list containing general information.

```APIDOC
## overview/0

### Description
Provides an overview of the leaderboard system.

### Function Signature
`overview() -> list()`

### Response
*   **Success Response** - Returns a `list()` containing overview information.
```

--------------------------------

### begin_read/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_snapshot.html

Begins a read operation. It takes the current state and a context map, returning either an 'ok' status with metadata and read state, or an error.

```APIDOC
## begin_read/2

### Description
Begins a read operation. It takes the current state and a context map, returning either an 'ok' status with metadata and read state, or an error.

### Function Signature
begin_read(State :: state(), Context :: map()) -> {ok, Meta :: meta(), ReadState} | {error, term()}

### Parameters
#### Path Parameters
- **State** (state) - The current state.
- **Context** (map) - The context for the read operation.

#### Return Value
- **{ok, Meta :: meta(), ReadState} | {error, term()}** - Either a success tuple with metadata and read state, or an error tuple.
```

--------------------------------

### Snapshot Configuration Parameters

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

Outlines the configuration settings for snapshots, including minimum intervals for snapshots and checkpoints, the maximum number of checkpoints to retain, and the module used for snapshot implementation.

```erlang
#{min_snapshot_interval => 4096,     %% Min entries between snapshots
  min_checkpoint_interval => 16384,  %% Min entries between checkpoints
  max_checkpoints => 3,              %% Max checkpoints to retain
  snapshot_module => ra_log_snapshot} %% Snapshot implementation module
```

--------------------------------

### Start Ra Application on a Node

Source: https://github.com/rabbitmq/ra/blob/main/README.md

Initiates the Ra application on a specific node. This is a prerequisite for cluster operations.

```erlang
ra:start().
```

--------------------------------

### Compaction Configuration Parameters

Source: https://github.com/rabbitmq/ra/blob/main/docs/internals/LOG.md

Details the configuration for the compaction process, including the strategy for triggering major compactions, and the maximum entry count and size for compacted segments.

```erlang
#{major_strategy => {num_minors, 8}, %% Trigger major after N minors
  max_count => 4096,                  %% Max entries in compacted segment
  max_size => 64_000_000}             %% Max compacted segment size
```

--------------------------------

### execute/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_log_read_plan.html

Executes a read plan with a given state and options, returning commands and the updated state.

```APIDOC
## execute/3

### Description
Executes a read plan with a given state and specific options. This function is similar to `execute/2` but allows for additional options to control the execution.

### Function Signature
`execute(Plan :: [ra_log:read_plan()], Flru :: undefined | [ra_flru:state()], Options :: [ra_log_segments:read_plan_options()]) -> {#{[ra:index()] => Command :: term()}, [ra_flru:state()]}`

### Parameters
*   **Plan** (`[ra_log:read_plan()]`) - The read plan to execute.
*   **Flru** (`undefined | [ra_flru:state()]`) - The initial FLRU state, or undefined.
*   **Options** (`[ra_log_segments:read_plan_options()]`) - Options to customize the read plan execution.

### Returns
A tuple containing:
*   A map where keys are `ra:index()` and values are `Command :: term()`.
*   The updated `[ra_flru:state()].
```

--------------------------------

### fetch/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_system.html

Fetches a configuration by its name. Returns the configuration if found, otherwise undefined.

```APIDOC
## fetch/1

### Description
Fetches a configuration by its name.

### Function Signature
fetch(Name :: atom())

### Parameters
* **Name** (atom()) - Required - The name of the configuration to fetch.

### Returns
- config() | undefined - The configuration if found, otherwise undefined.
```

--------------------------------

### restart_server/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra.html

Restarts a previously started RA server with additional mutable configuration parameters. These parameters are merged with the original configuration.

```APIDOC
## restart_server/3

### Description
Restarts a previously started RA server with additional configuration parameters.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **System** (atom) - Required - The system identifier.
- **ServerId** (ra_server_id) - Required - The ID of the server to restart.
- **AddConfig** (ra_server:mutable_config) - Required - Additional configuration parameters to merge.

### Request Example
N/A

### Response
#### Success Response (ok)
Returns `ok` on successful restart.

#### Error Response
- **error** (term) - Can be `not_found` or `name_not_registered`.

#### Response Example
```json
{
  "ok": null
}
```

```json
{
  "error": "not_found"
}
```
```

--------------------------------

### lookup_name/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_system.html

Looks up a specific key within a system's configuration. Returns the atom name or an error if the system is not started.

```APIDOC
## lookup_name/2

### Description
Looks up a specific key within a system's configuration.

### Function Signature
lookup_name(System :: atom(), Key :: atom())

### Parameters
* **System** (atom()) - Required - The name of the system.
* **Key** (atom()) - Required - The key to look up within the system's configuration.

### Returns
- {ok, atom()} | {error, system_not_started} - The atom name if found, or an error tuple if the system is not started.
```

--------------------------------

### execute/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_log_read_plan.html

Executes a read plan with a given state, returning a map of commands and the updated state.

```APIDOC
## execute/2

### Description
Executes a read plan with a given state. It processes the plan and returns a map of commands indexed by RA index, along with the potentially updated FLRU state.

### Function Signature
`execute(Plan :: [ra_log:read_plan()], Flru :: undefined | [ra_flru:state()]) -> {#{[ra:index()] => Command :: term()}, [ra_flru:state()]}`

### Parameters
*   **Plan** (`[ra_log:read_plan()]`) - The read plan to execute.
*   **Flru** (`undefined | [ra_flru:state()]`) - The initial FLRU state, or undefined.

### Returns
A tuple containing:
*   A map where keys are `ra:index()` and values are `Command :: term()`.
*   The updated `[ra_flru:state()]`.
```

--------------------------------

### effective_machine_version/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_aux.html

Gets the effective version of the Ra machine. It takes the internal state and returns the Ra machine's version.

```APIDOC
## effective_machine_version/1

### Description
Gets the effective version of the Ra machine.

### Function Signature
effective_machine_version(State :: ra_aux:internal_state()) -> ra_machine:version()

### Parameters
* **State** (ra_aux:internal_state()) - The current internal state of the Ra instance.

### Returns
* ra_machine:version() - The effective version of the Ra machine.
```

--------------------------------

### Start Ra Cluster

Source: https://github.com/rabbitmq/ra/blob/main/README.md

Forms a new Ra cluster with a specified name, using a simple machine configuration and designating an initial member.

```erlang
ClusterName = dyn_members,
Machine = {simple, fun erlang:'+'/2, 0},

% Start a cluster
{ok, _, _} =  ra:start_cluster(default, ClusterName, Machine, [{dyn_members, 'ra2@hostname.local'}]).
```

--------------------------------

### overview/2

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_machine.html

Retrieves an overview of the RA machine's current state as a map.

```APIDOC
## overview/2

### Description
Retrieves an overview of the RA machine's current state as a map.

### Function Signature
overview(Mod :: module(), State :: [state()](#type-state)) -> map()
```

--------------------------------

### current_term/1

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_aux.html

Gets the current term number of the Ra consensus algorithm. The term is a monotonically increasing number representing different leadership periods.

```APIDOC
## current_term/1

### Description
Gets the current term number of the Ra consensus algorithm.

### Function Signature
current_term(State :: ra_aux:internal_state()) -> ra_term()

### Parameters
* **State** (ra_aux:internal_state()) - The current internal state of the Ra instance.

### Returns
* ra_term() - The current term number.
```

--------------------------------

### init/0

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_counters.html

Initializes the RA counters system. This function should be called before any other counter operations.

```APIDOC
## init/0

### Description
Initializes the RA counters system.

### Function
init()

### Returns
- ok
```

--------------------------------

### Add Another Member to Ra Cluster

Source: https://github.com/rabbitmq/ra/blob/main/README.md

Demonstrates adding a third member to the Ra cluster, following the same pattern of adding the member and starting its server.

```erlang
% Add a new member
{ok, _, _} = ra:add_member({dyn_members, 'ra2@hostname.local'}, {dyn_members, 'ra3@hostname.local'}),

% Start the server
ok = ra:start_server(default, ClusterName, {dyn_members, 'ra3@hostname.local'}, Machine, [{dyn_members, 'ra2@hostname.local'}]).
```

--------------------------------

### make_snapshot_dir/3

Source: https://github.com/rabbitmq/ra/blob/main/docs/ra_snapshot.html

Creates a snapshot directory. The exact return type and parameters are not fully specified in the source.

```APIDOC
## make_snapshot_dir/3

### Description
Creates a snapshot directory. The exact return type and parameters are not fully specified in the source.

### Function Signature
`make_snapshot_dir(Dir, Index, Term) -> any()`

### Parameters
- **Dir** - The directory for the snapshot.
- **Index** - The index to include in the snapshot.
- **Term** - Additional term for the snapshot.
```

--------------------------------

### Clean Ra Project Artifacts

Source: https://github.com/rabbitmq/ra/blob/main/CONTRIBUTING.md

Remove compilation artifacts from the Ra project to ensure a clean build environment. This command is useful for starting a fresh build.

```shell
make clean
```