feat(backup): BackupServerDriver, a role base for backup servers (#82)
driver / lint (pull_request) Successful in 15s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m6s
driver / test (3.13) (pull_request) Successful in 1m7s
driver / test (3.12) (pull_request) Successful in 1m15s
driver / lowest (pull_request) Successful in 30s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m22s
driver / publish (pull_request) Skipped

A backup server keeps datastores, one backup group per source with its
snapshots, and the jobs that keep them healthy: garbage collection,
verify, prune, sync and tape. None of that is a pool, a volume or a
replication job, so it is a role of its own instead of being bent into
StorageDriver. A server that manages its own disks lists StorageDriver
second.

The role declares the reads (datastores, groups with their newest
snapshot, a group's snapshots, jobs, remotes) and the actions (garbage
collection, running a job, verifying, protecting and deleting a
snapshot), which start a task and return its id for get_backup_task.
The shapes live in napalm_device_types.backups.

ClusterStorageDict gains an optional backup_server: which server,
datastore and namespace a hypervisor's backup storage writes to, with
the fingerprint it pins. Matching that to a server is the application's.
This commit is contained in:
christianmanivong committed 2026-11-02 20:46:40 +01:00
1 parent a0901e3277
commit 95e3aa1e26
12 files changed
+668 -3

No files matched your search

+234
View File
@@ -0,0 +1,234 @@
"""A backup server is a role of its own (NAPALM/napalm-device-types#82).
What makes a device a backup server -- datastores, the backup groups in them,
the jobs that keep them (garbage collection, verify, prune, sync, tape) and the
remotes it syncs with -- has no counterpart in ``StorageDriver``. A backup
server that also manages its own disks lists ``StorageDriver`` as a second role.
The declarations sit under ``TYPE_CHECKING`` (see test_role_contracts), so the
signatures are read from the source rather than from the class.
"""
from __future__ import annotations
import ast
import inspect
from typing import NotRequired, get_args, get_type_hints
import pytest
import napalm_device_types.backup_server as backup_server_module
from napalm_device_types import (
BACKUP_JOB_KINDS,
BackupDatastoreDict,
BackupGroupDict,
BackupRemoteDict,
BackupServerDriver,
BackupServerJobDict,
BackupServerRefDict,
BackupSnapshotDict,
BackupSnapshotRefDict,
BackupTaskDict,
BackupTaskStatusDict,
ClusterStorageDict,
OSDriver,
StorageDriver,
)
from napalm_device_types.backups import BackupJobKind, BackupRunState, BackupVerifyState
from napalm_device_types.roles import primary_role_of, role_keys_of
def _declared(name: str) -> ast.FunctionDef:
tree = ast.parse(inspect.getsource(backup_server_module))
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef) and node.name == name:
return node
raise AssertionError(f"BackupServerDriver does not declare {name}()")
def _signature(name: str) -> tuple[list[str], str]:
fn = _declared(name)
params = ast.unparse(fn.args).split(", ")[1:]
return params, ast.unparse(fn.returns) if fn.returns else ""
class TestRole:
def test_role_key_and_label(self):
assert vars(BackupServerDriver)["ROLE"] == "backup_server"
assert BackupServerDriver.TYPE_LABEL == "Backup Server"
def test_backup_server_first_storage_second(self):
"""A PBS manages its disks and ZFS pools too; that part is storage."""
class Pbs(BackupServerDriver, StorageDriver, OSDriver):
pass
assert role_keys_of(Pbs) == ["backup_server", "storage", "linux"]
assert primary_role_of(Pbs) == "backup_server"
class TestDeclarations:
@pytest.mark.parametrize(
("name", "params", "returns"),
[
("get_backup_datastores", [], "list[BackupDatastoreDict]"),
("get_backup_groups", ["datastore: str=''"], "list[BackupGroupDict]"),
(
"get_backup_snapshots",
["datastore: str", "namespace: str", "group_type: str", "group_id: str"],
"list[BackupSnapshotDict]",
),
("get_backup_jobs", [], "list[BackupServerJobDict]"),
("get_backup_remotes", [], "list[BackupRemoteDict]"),
("start_garbage_collection", ["datastore: str"], "BackupTaskDict"),
("run_backup_job", ["kind: BackupJobKind", "job_id: str"], "BackupTaskDict"),
("verify_backup_snapshot", ["snapshot: BackupSnapshotRefDict"], "BackupTaskDict"),
(
"set_backup_snapshot_protected",
["snapshot: BackupSnapshotRefDict", "protected: bool"],
"None",
),
("delete_backup_snapshot", ["snapshot: BackupSnapshotRefDict"], "None"),
("get_backup_task", ["task: str"], "BackupTaskStatusDict"),
],
)
def test_declared_with_its_signature(self, name, params, returns):
got_params, got_returns = _signature(name)
assert [p.replace(" ", "") for p in got_params] == [p.replace(" ", "") for p in params]
assert got_returns == returns
@pytest.mark.parametrize(
"name",
[
"get_backup_datastores",
"get_backup_groups",
"get_backup_snapshots",
"get_backup_jobs",
"get_backup_remotes",
"start_garbage_collection",
"run_backup_job",
"verify_backup_snapshot",
"set_backup_snapshot_protected",
"delete_backup_snapshot",
"get_backup_task",
],
)
def test_absent_until_a_driver_implements_it(self, name):
assert not hasattr(BackupServerDriver, name)
def test_every_declaration_has_a_docstring(self):
tree = ast.parse(inspect.getsource(backup_server_module))
missing = [
n.name
for n in ast.walk(tree)
if isinstance(n, ast.FunctionDef) and not ast.get_docstring(n)
]
assert missing == []
class TestShapes:
"""Neutral names: nothing here is Proxmox's. A value the platform does not
report is None; it is never guessed."""
def test_datastore(self):
assert set(get_type_hints(BackupDatastoreDict)) == {
"name",
"path",
"backend",
"total",
"used",
"available",
"estimated_full",
"maintenance",
"comment",
}
def test_group_carries_its_newest_snapshot_not_all_of_them(self):
assert set(get_type_hints(BackupGroupDict)) == {
"datastore",
"namespace",
"type",
"id",
"owner",
"count",
"newest",
"oldest_time",
"comment",
}
assert get_type_hints(BackupGroupDict)["newest"] == BackupSnapshotDict | None
def test_snapshot(self):
assert set(get_type_hints(BackupSnapshotDict)) == {
"time",
"size",
"verify",
"protected",
"comment",
}
assert set(get_args(BackupVerifyState)) == {"ok", "failed"}
def test_snapshot_reference_names_one_snapshot(self):
assert set(get_type_hints(BackupSnapshotRefDict)) == {
"datastore",
"namespace",
"group_type",
"group_id",
"time",
}
def test_job_kinds_include_garbage_collection(self):
"""GC is a job with a schedule and a last run like the others, so it is
listed with them rather than restated on the datastore."""
assert set(get_args(BackupJobKind)) == {"gc", "verify", "prune", "sync", "tape"}
assert set(BACKUP_JOB_KINDS) == set(get_args(BackupJobKind))
def test_job(self):
assert set(get_type_hints(BackupServerJobDict)) == {
"id",
"kind",
"datastore",
"namespace",
"schedule",
"enabled",
"last_run",
"last_state",
"last_error",
"next_run",
"remote",
"direction",
"comment",
}
assert set(get_args(BackupRunState)) == {"ok", "warning", "error", "running"}
def test_remote_never_carries_its_secret(self):
fields = set(get_type_hints(BackupRemoteDict))
assert fields == {"name", "host", "port", "fingerprint", "auth_id", "comment"}
assert not fields & {"password", "secret", "token"}
def test_task(self):
assert set(get_type_hints(BackupTaskDict)) == {"task"}
assert set(get_type_hints(BackupTaskStatusDict)) == {
"task",
"running",
"state",
"error",
"log",
}
class TestClusterStorageNamesItsBackupServer:
"""A hypervisor's backup storage says which server and datastore it points
at, so an application can tie the server's groups to the cluster's guests."""
def test_backup_server_reference_is_optional_on_a_storage(self):
hints = get_type_hints(ClusterStorageDict, include_extras=True)
assert hints["backup_server"] == NotRequired[BackupServerRefDict | None]
def test_reference(self):
assert set(get_type_hints(BackupServerRefDict)) == {
"server",
"port",
"datastore",
"namespace",
"fingerprint",
}
+6 -1
View File
@@ -25,6 +25,7 @@ import napalm_device_types.hypervisor as hypervisor_module
from napalm_device_types import (
BackupDict,
BackupJobDict,
BackupServerRefDict,
ClusterDict,
ClusterNetworkDict,
ClusterNodeDict,
@@ -92,7 +93,8 @@ class TestClusterShape:
assert "votes" not in ClusterNodeDict.__required_keys__
def test_storage(self):
assert get_type_hints(ClusterStorageDict) == {
hints = get_type_hints(ClusterStorageDict, include_extras=True)
assert hints == {
"name": str,
"type": str,
"shared": bool,
@@ -100,7 +102,10 @@ class TestClusterShape:
"nodes": list[str],
"total": int | None,
"used": int | None,
"backup_server": NotRequired[BackupServerRefDict | None],
}
# A driver written before backup servers were part of the report stays valid.
assert "backup_server" not in ClusterStorageDict.__required_keys__
def test_network(self):
hints = get_type_hints(ClusterNetworkDict, include_extras=True)
+2 -1
View File
@@ -11,6 +11,7 @@ import pytest
from napalm_device_types import (
AccessPointDriver,
BackupServerDriver,
EnsurePackageMixin,
FirewallDriver,
HypervisorDriver,
@@ -28,7 +29,7 @@ from napalm_device_types import (
)
ROLE_BASES = [
AccessPointDriver, FirewallDriver, HypervisorDriver, ManagementControllerDriver, MediaDriver,
AccessPointDriver, BackupServerDriver, FirewallDriver, HypervisorDriver, ManagementControllerDriver, MediaDriver,
OSDriver, PhoneDriver, ResidentialGatewayDriver, StorageDriver, SwitchDriver,
] # fmt: skip
+4
View File
@@ -18,6 +18,7 @@ import pytest
from napalm_device_types import (
AccessPointDriver,
BackupServerDriver,
DeviceTypeDriver,
FirewallDriver,
HypervisorDriver,
@@ -33,6 +34,7 @@ from napalm_device_types.roles import primary_role_of, roles_of
ROLE_BASES = [
AccessPointDriver,
BackupServerDriver,
FirewallDriver,
HypervisorDriver,
ManagementControllerDriver,
@@ -75,6 +77,8 @@ class TestDeclaredMethodsDoNotExistAtRuntime:
@pytest.mark.parametrize(
("base", "method"),
[
(BackupServerDriver, "get_backup_datastores"),
(BackupServerDriver, "run_backup_job"),
(StorageDriver, "get_disks"),
(StorageDriver, "get_volumes"),
(HypervisorDriver, "get_vms"),
+2
View File
@@ -4,6 +4,7 @@ import pytest
from napalm_device_types import (
AccessPointDriver,
BackupServerDriver,
FirewallDriver,
HypervisorDriver,
ManagementControllerDriver,
@@ -15,6 +16,7 @@ from napalm_device_types import (
BASE_CLASSES = [
(AccessPointDriver, "Access Point"),
(BackupServerDriver, "Backup Server"),
(FirewallDriver, "Firewall"),
(HypervisorDriver, "Hypervisor"),
(ManagementControllerDriver, "Management Controller"),