From 56e5e82a594f320456df2338366bf6352e072cc0 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Tue, 10 Nov 2026 23:39:17 +0100 Subject: [PATCH] feat(running-backups): the backups running on a device right now A restart aborts every backup that runs on the device it restarts, and a guest's restart breaks the backup its hypervisor is taking of it. netOrk asks right before it restarts a host after patching (NetOrk/netork#2318), so the reading belongs in the contract first: RunningBackupsMixin declares get_running_backups(), opt-in like VmStopRequestMixin, so hasattr tells a caller whether the driver can tell at all. Release 4.34.0: the drivers that implement it need it on PyPI. --- CHANGELOG.md | 10 ++++ napalm_device_types/__init__.py | 11 ++++ napalm_device_types/running_backups.py | 69 ++++++++++++++++++++++++++ pyproject.toml | 2 +- tests/test_running_backups.py | 51 +++++++++++++++++++ 5 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 napalm_device_types/running_backups.py create mode 100644 tests/test_running_backups.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 237c31c..824fd6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ recorded here; their history is the git log. ## [Unreleased] +## [4.34.0] - 2026-11-10 + +### Added +- `RunningBackupsMixin.get_running_backups()`: the backups running on a device right now -- + a hypervisor's backup of its guests (with the guests it is taking now), a backup server's + backup, sync, verify, garbage collection, prune or tape run, a host's own file-level backup. + Declared only; a driver mixes it in when it can tell, and a driver without it cannot tell. + `RunningBackupDict`, `RunningBackupKind` and `RUNNING_BACKUP_KINDS` are public. An + application asks right before it restarts a device (NetOrk/netork#2318). + ## [4.33.0] - 2026-11-07 ### Added diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 54c27b5..d6555f6 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -56,6 +56,7 @@ instead of being restated on every role that happens to need it: * :class:`~napalm_device_types.nat_vpn.NatVpnMixin` * :class:`~napalm_device_types.packages.PackageManagementMixin` * :class:`~napalm_device_types.ping_sweep.PingSweepMixin` +* :class:`~napalm_device_types.running_backups.RunningBackupsMixin` * :class:`~napalm_device_types.service_clusters.ServiceClustersMixin` * :class:`~napalm_device_types.service_packages.ServicePackagesMixin` * :class:`~napalm_device_types.ssh_server_auth.SshServerAuthMixin` @@ -224,6 +225,12 @@ from napalm_device_types.ping_sweep import PingSweepMixin, driver_supports_ping from napalm_device_types.provisioning import VMProvisionIncomplete from napalm_device_types.residential_gateway import ResidentialGatewayDriver from napalm_device_types.roles import primary_role_of, role_keys_of, roles_of +from napalm_device_types.running_backups import ( + RUNNING_BACKUP_KINDS, + RunningBackupDict, + RunningBackupKind, + RunningBackupsMixin, +) from napalm_device_types.scheduled_jobs import ( ScheduledJobChanged, ScheduledJobDict, @@ -468,6 +475,10 @@ __all__ = [ "VIRTUAL_IPS_COMMAND", "VirtualIpsMixin", "VmStopRequestMixin", + "RUNNING_BACKUP_KINDS", + "RunningBackupDict", + "RunningBackupKind", + "RunningBackupsMixin", "VMProvisionIncomplete", "SERVICE_CLUSTERS_COMMAND", "ServiceClustersMixin", diff --git a/napalm_device_types/running_backups.py b/napalm_device_types/running_backups.py new file mode 100644 index 0000000..ed51dc8 --- /dev/null +++ b/napalm_device_types/running_backups.py @@ -0,0 +1,69 @@ +"""The backups running on a device right now. + +A restart aborts every backup that runs on the device it restarts: a +hypervisor's backup of its guests, a backup server's backup, sync, verify or +garbage collection, a host's own file-level backup (restic, borg and the like). +A guest's restart breaks the backup its hypervisor is taking of it. So an +application that restarts a device asks first, right before the restart. + +Declared under ``if TYPE_CHECKING``: a driver mixes this in when it can tell; +``hasattr`` tells a caller whether it did. No role base carries it, and a driver +without it cannot tell -- which is not the same as "nothing runs". +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Literal, TypedDict, get_args + +#: What a running backup does: the backup itself, or one of a backup server's +#: jobs (``napalm_device_types.backups.BackupJobKind``). +RunningBackupKind = Literal["backup", "sync", "verify", "gc", "prune", "tape"] +RUNNING_BACKUP_KINDS: tuple[str, ...] = get_args(RunningBackupKind) + + +class RunningBackupDict(TypedDict): + """One backup running on the device (``get_running_backups``).""" + + kind: RunningBackupKind + job: str | None # the job it runs for, as the platform names it; None: started by hand + task: str | None # this run's id on the platform: a task id, a unit, a process id + guests: list[str] # the guests (get_vms' ids) it is backing up now; [] for the host's own + since: int | None # unix seconds it started; None when the platform does not say + + +class RunningBackupsMixin: + if TYPE_CHECKING: + + def get_running_backups(self) -> list[RunningBackupDict]: + """ + Returns the backups running on the device now; ``[]`` when none is. + + Every entry runs on this device: restarting the device aborts it. + A hypervisor names in ``guests`` the guests a backup is taking right + now -- a guest that is locked for its backup counts, with or without + a task the platform still shows -- so the application can tell a + guest's own restart not to break it. + + Example:: + + [ + { + "kind": "backup", + "job": "backup-3f2a9c1e-77d1", + "task": "UPID:pve1:0001F2A3:00C4B1D2:6731A0C0:vzdump::root@pam:", + "guests": ["101"], + "since": 1793660400, + }, + { + "kind": "gc", + "job": "store1", + "task": "UPID:localhost:000004D2:...:garbage_collection:store1:root@pam:", + "guests": [], + "since": 1793664000, + }, + ] + + :raises Exception: when the device could not be read; never an + empty list for a failed read. + """ + ... diff --git a/pyproject.toml b/pyproject.toml index 255d5bc..02a6ee3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "napalm-device-types" -version = "4.33.0" +version = "4.34.0" description = "Abstract device-type base classes for NAPALM drivers" readme = "README.md" requires-python = ">=3.12" diff --git a/tests/test_running_backups.py b/tests/test_running_backups.py new file mode 100644 index 0000000..b58e2d3 --- /dev/null +++ b/tests/test_running_backups.py @@ -0,0 +1,51 @@ +"""get_running_backups: the backups running on a device right now. + +An application that restarts a device asks first, right before the restart: a +restart aborts a backup that runs on the device -- a hypervisor's vzdump, a +backup server's backup, sync, verify or garbage collection, a host's own restic +or borg run -- and a guest's restart breaks the backup its hypervisor is taking +of it (NetOrk/netork#2318). A driver mixes it in when it can tell; no role +demands it, and a driver without it cannot tell. +""" + +from __future__ import annotations + +import inspect +from typing import get_type_hints + +from napalm_device_types import ( + RUNNING_BACKUP_KINDS, + BackupServerDriver, + DeviceTypeDriver, + HypervisorDriver, + OSDriver, + RunningBackupDict, + RunningBackupsMixin, +) + + +def test_no_role_demands_it(): + for role in (BackupServerDriver, HypervisorDriver, OSDriver, DeviceTypeDriver): + assert not issubclass(role, RunningBackupsMixin) + + +def test_declared_not_implemented(): + """hasattr is the caller's probe: only a driver that can tell answers True.""" + assert not hasattr(RunningBackupsMixin, "get_running_backups") + + +def test_declaration_documents_the_contract(): + source = inspect.getsource(RunningBackupsMixin) + assert "def get_running_backups(self) -> list[RunningBackupDict]" in source + assert "empty list for a failed read" in source + + +def test_the_kinds_cover_a_backup_servers_jobs_and_the_backup_itself(): + assert set(RUNNING_BACKUP_KINDS) == {"backup", "sync", "verify", "gc", "prune", "tape"} + + +def test_the_shape(): + hints = get_type_hints(RunningBackupDict) + assert set(hints) == {"kind", "job", "task", "guests", "since"} + assert hints["guests"] == list[str] + assert hints["since"] == int | None