# `Concord.Backup`
[🔗](https://github.com/gsmlg-dev/concord/blob/main/lib/concord/backup.ex#L1)

Backup and restore functionality for Concord distributed KV store.

Provides comprehensive backup management including:
- Local and remote backup creation
- Point-in-time recovery
- Backup verification and integrity checks
- Compressed backup storage
- Metadata tracking

## Backup Format

Backups are stored as compressed Erlang term files (.backup) containing:
- Metadata (timestamp, cluster info, entry count)
- Full snapshot of all key-value pairs
- Checksum for integrity verification

## Examples

    # Create a backup
    {:ok, path} = Concord.Backup.create("/path/to/backups")

    # Restore from backup
    :ok = Concord.Backup.restore("/path/to/backup.backup")

    # List available backups
    {:ok, backups} = Concord.Backup.list("/path/to/backups")

    # Verify backup integrity
    {:ok, :valid} = Concord.Backup.verify("/path/to/backup.backup")

# `backup`

```elixir
@type backup() :: %{metadata: metadata(), data: [{term(), term()}]}
```

Backup content

# `metadata`

```elixir
@type metadata() :: %{
  timestamp: DateTime.t(),
  node: node(),
  cluster_name: atom(),
  entry_count: non_neg_integer(),
  memory_bytes: non_neg_integer(),
  version: String.t(),
  checksum: binary()
}
```

Backup metadata

# `cleanup`

```elixir
@spec cleanup(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}
```

Deletes old backups based on retention policy.

## Options

- `:keep_count` - Number of backups to keep (default: 10)
- `:keep_days` - Keep backups newer than N days (default: 30)

## Returns

- `{:ok, deleted_count}` - Number of backups deleted
- `{:error, reason}` - Error during cleanup

## Examples

    iex> Concord.Backup.cleanup(keep_count: 5)
    {:ok, 3}

    iex> Concord.Backup.cleanup(keep_days: 7)
    {:ok, 10}

# `create`

```elixir
@spec create(keyword()) :: {:ok, Path.t()} | {:error, term()}
```

Creates a backup of the current cluster state.

## Options

- `:path` - Directory to store backup (default: "./backups")
- `:compress` - Compress backup file (default: true)
- `:include_metadata` - Include cluster metadata (default: true)

## Returns

- `{:ok, backup_path}` - Path to created backup file
- `{:error, :cluster_not_ready}` - Ra cluster is unavailable; start Concord or retry after the cluster is ready
- `{:error, reason}` - Error creating backup

## Examples

    iex> Concord.Backup.create()
    {:ok, "./backups/concord_backup_20251023_143052.backup"}

    iex> Concord.Backup.create(path: "/mnt/backups")
    {:ok, "/mnt/backups/concord_backup_20251023_143052.backup"}

# `list`

```elixir
@spec list(Path.t()) :: {:ok, [map()]} | {:error, term()}
```

Lists all available backups in a directory.

## Returns

- `{:ok, backup_list}` - List of backup file information
- `{:error, reason}` - Error reading directory

## Examples

    iex> Concord.Backup.list()
    {:ok, [
      %{
        path: "./backups/concord_backup_20251023_143052.backup",
        timestamp: ~U[2025-10-23 14:30:52Z],
        size_bytes: 1048576,
        entry_count: 1000
      }
    ]}

# `restore`

```elixir
@spec restore(
  Path.t(),
  keyword()
) :: :ok | {:error, term()}
```

Restores cluster state from a backup file.

**Warning**: This operation will overwrite all existing data in the cluster.
It's recommended to create a backup before restoring.

## Options

- `:force` - Skip confirmation prompts (default: false)
- `:verify` - Verify backup integrity before restore (default: true)

## Returns

- `:ok` - Restore completed successfully
- `{:error, reason}` - Error during restore

## Examples

    iex> Concord.Backup.restore("/path/to/backup.backup")
    :ok

    iex> Concord.Backup.restore("/path/to/backup.backup", force: true)
    :ok

# `verify`

```elixir
@spec verify(Path.t()) :: {:ok, :valid | :invalid} | {:error, term()}
```

Verifies the integrity of a backup file.

## Returns

- `{:ok, :valid}` - Backup is valid
- `{:ok, :invalid}` - Backup is corrupted
- `{:error, reason}` - Error reading backup

## Examples

    iex> Concord.Backup.verify("/path/to/backup.backup")
    {:ok, :valid}