From 43e0210ff657342f1fb5f3392c9e07699e4ff7d8 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 13 Nov 2026 22:28:30 +0100 Subject: [PATCH] feat(config-revisions): declare a device's own configuration history Some devices keep a copy of their configuration for every save and can go back to one. An application restores a configuration there by reverting to the revision that holds it; on OPNsense that is the only way, since its API takes no uploaded config.xml (NetOrk/netork#2511). ConfigRevisionsMixin declares get_config_revisions() (newest first, as ConfigRevisionDict) and get_config_revision(revision_id). revert_config_revision(revision_id) is a template over the driver's _revert_to_config_revision step: it refuses an id that is not in the history (UnknownConfigRevision), reads the revision before the revert can rotate it out, and afterwards checks that the newest revision holds its configuration (ConfigRevertFailed otherwise), since a device may report a revert it did not make. config_revision_content(text) is the hook where a driver leaves out what its device stamps into every save, so revisions with the same configuration compare equal. Refs NetOrk/netork#2511 --- CHANGELOG.md | 9 ++ README.md | 17 +++ napalm_device_types/__init__.py | 11 ++ napalm_device_types/config_revisions.py | 140 +++++++++++++++++++ tests/test_config_revisions.py | 172 ++++++++++++++++++++++++ 5 files changed, 349 insertions(+) create mode 100644 napalm_device_types/config_revisions.py create mode 100644 tests/test_config_revisions.py diff --git a/CHANGELOG.md b/CHANGELOG.md index df82a2c..4a30fb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ recorded here; their history is the git log. ## [Unreleased] ### Added +- `ConfigRevisionsMixin`: a device's own configuration history (NetOrk/netork#2511). + `get_config_revisions()` (newest first, the first in place now, as + `ConfigRevisionDict`: id, UTC time, description, user, size) and + `get_config_revision(revision_id)` are declared. `revert_config_revision(revision_id)` + is a template over the driver's `_revert_to_config_revision`: it refuses an id that is + not in the history (`UnknownConfigRevision`), and after the revert checks that the + newest revision holds the revision's configuration, else `ConfigRevertFailed`; it + returns that revision. `config_revision_content(text)` leaves out what a device stamps + into every save, so an application can compare revisions with a configuration it has. - `add_service_account(..., replaces=[...])`: netOrk's keys the new one takes the place of go from its account once the new key is in it (step `old keys`), never the new key itself; while the new key could not be added they stay, so netOrk keeps its way in. diff --git a/README.md b/README.md index 7852913..f8fc9b9 100644 --- a/README.md +++ b/README.md @@ -374,6 +374,23 @@ that 4.35.0 commented out comes back on the next write -- and systemd-timesyncd' `LinkNTPServers` stay. ntpd and OpenNTPD are read, not written; what DHCP gives them is unknown. +`ConfigRevisionsMixin` (`get_config_revisions`, `get_config_revision`, +`revert_config_revision`) is a device's own configuration history: a copy of the +configuration for every save, which the device can go back to. An application restores a +configuration there by reverting to the revision that holds it -- on OPNsense the only way, +since its API takes no uploaded config.xml (NetOrk/netork#2511). Listing (newest first, the +first in place now: id, UTC time, description, user, size as `ConfigRevisionDict`) and +reading one revision are declared only. `revert_config_revision(revision_id)` is a +template: it refuses an id that is not in the history (`UnknownConfigRevision`, a +`ValueError`) before anything changes, reads the revision -- before the revert, which may +rotate it out -- lets the driver revert (`_revert_to_config_revision`), and checks that the +newest revision afterwards holds the revision's configuration (`ConfigRevertFailed` +otherwise: a device may say it reverted when it did not). It returns that newest revision. +`config_revision_content(text)` is what of a revision is its configuration; a driver whose +device stamps every save (who, when) strips the stamp there, and an application that looks +for the revision holding a configuration compares through it too. A driver that can list +but not revert sets `revert_config_revision = None`. + ### Access channels: why there is no container model here `CommandChannelMixin` declares a driver's public channel to its host: diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 0e7efe6..f1abe2d 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -38,6 +38,7 @@ instead of being restated on every role that happens to need it: * :class:`~napalm_device_types.channel.CommandChannelMixin` * :class:`~napalm_device_types.config_lifecycle.ConfigLifecycleMixin` +* :class:`~napalm_device_types.config_revisions.ConfigRevisionsMixin` * :class:`~napalm_device_types.config_sync.ConfigSyncMixin` * :class:`~napalm_device_types.container_engine.ContainerEngineMixin` * :class:`~napalm_device_types.dhcp.DhcpServerMixin` @@ -121,6 +122,12 @@ from napalm_device_types.clusters import ( HAResourceDict, ) from napalm_device_types.config_lifecycle import ConfigLifecycleMixin +from napalm_device_types.config_revisions import ( + ConfigRevertFailed, + ConfigRevisionDict, + ConfigRevisionsMixin, + UnknownConfigRevision, +) from napalm_device_types.config_sync import ConfigSyncMixin from napalm_device_types.container_engine import ( ContainerEngineConnection, @@ -401,6 +408,10 @@ __all__ = [ "open_stream_on_transport", "run_on_transport", "ConfigLifecycleMixin", + "ConfigRevisionsMixin", + "ConfigRevisionDict", + "ConfigRevertFailed", + "UnknownConfigRevision", "ConfigSyncDict", "ConfigSyncMixin", "DhcpHaDict", diff --git a/napalm_device_types/config_revisions.py b/napalm_device_types/config_revisions.py new file mode 100644 index 0000000..4768d2a --- /dev/null +++ b/napalm_device_types/config_revisions.py @@ -0,0 +1,140 @@ +"""A device's own configuration history: list it, read a revision, revert to one. + +Some devices keep their earlier configurations themselves: a copy of the +configuration for every save, which the device can go back to. An application +restores a configuration there by reverting to the revision that holds it -- on a +device whose API takes no uploaded configuration (OPNsense), the only way +(NetOrk/netork#2511). :class:`ConfigRevisionsMixin` is the contract: + +* ``get_config_revisions()`` and ``get_config_revision(revision_id)`` -- declared + only, so ``callable(getattr(driver, "get_config_revisions", None))`` is the + truthful answer to "does this device keep a history"; +* ``revert_config_revision(revision_id)`` -- a template: it refuses an id that is not + in the history, reads the revision, lets the driver revert + (``_revert_to_config_revision``), and reads the configuration in place afterwards + to check that it holds the revision's. A device may answer that it reverted when it + did not; the check does not take its word; +* ``config_revision_content(text)`` -- what of a revision is its configuration. Every + save may stamp a revision anew (OPNsense writes who saved it and when into + config.xml), so two revisions with the same configuration differ as text. A driver + whose device does that strips the stamp here; by default the whole text counts. An + application that looks for the revision holding a configuration compares through + it too. + +A driver mixes it in when its device keeps a history; no role base carries it. One +that can list the history but not revert to it sets ``revert_config_revision`` to +``None``. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, TypedDict + + +class ConfigRevisionDict(TypedDict): + """One revision of the device's configuration (``get_config_revisions``).""" + + id: str # what get_config_revision and revert_config_revision take, as the device names it + time: str | None # when it was saved, UTC ISO 8601; None when the device does not say + description: str | None # what made the change, as the device records it; None: none + user: str | None # who saved it, as the device names them; None when it names nobody + size: int | None # its size in bytes; None when not given + + +class UnknownConfigRevision(ValueError): + """The device's configuration history has no revision of that id.""" + + def __init__(self, revision_id: object) -> None: + super().__init__(f"no configuration revision {revision_id!r} in the device's history") + + +class ConfigRevertFailed(RuntimeError): + """The device refused the revert, or its configuration afterwards is not the revision's.""" + + +class ConfigRevisionsMixin: + """List, read and revert to the device's configuration revisions; see the module.""" + + if TYPE_CHECKING: # pragma: no cover - declared for type checkers only + + def get_config_revisions(self) -> list[ConfigRevisionDict]: + """The device's configuration history, newest first. + + The first revision is the configuration in place now. + + Example:: + + [ + { + "id": "config-1794603885.1239.xml", + "time": "2026-11-13T21:04:45+00:00", + "description": "/api/firewall/filter/apply made changes", + "user": "apiuser@192.0.2.10", + "size": 58213, + }, + ] + + :raises Exception: when the history could not be read; never an empty + list for a failed read. + """ + ... + + def get_config_revision(self, revision_id: str) -> str: + """The configuration of revision *revision_id*, as the device keeps it. + + :raises UnknownConfigRevision: for an id that is not in the history. + :raises Exception: when the device could not be read. + """ + ... + + # The step a driver implements: + + def _revert_to_config_revision(self, revision_id: str) -> None: + """Make revision *revision_id* the device's configuration; return once it is + in place, as the newest revision of the history. + + :raises UnknownConfigRevision: when the device no longer has it. + :raises ConfigRevertFailed: when the device refuses. + """ + ... + + def config_revision_content(self, text: str) -> str: + """What of a revision's *text* is its configuration: the whole text by default. + + A driver whose device stamps every save into the configuration (who, when) + returns the text without that stamp, so that two revisions with the same + configuration compare equal. + """ + return text + + def revert_config_revision(self, revision_id: str) -> ConfigRevisionDict: + """Make revision *revision_id* the device's configuration again. + + Returns the revision in place afterwards: the newest of the history, which + holds the configuration of *revision_id* (on most devices a new revision the + revert saved). What the device does beyond that -- reload its services, + restart, nothing -- is the driver's to document. + + :raises UnknownConfigRevision: for an id that is not in the history now; + nothing has changed then. + :raises ConfigRevertFailed: when the device refuses, or when the configuration + in place afterwards is not the revision's. + :raises Exception: when the device could not be reached. + """ + if revision_id not in {r["id"] for r in self.get_config_revisions()}: + raise UnknownConfigRevision(revision_id) + # Read before the revert: saving it may rotate the revision out of the history. + wanted = self.config_revision_content(self.get_config_revision(revision_id)) + self._revert_to_config_revision(revision_id) + revisions = self.get_config_revisions() + if not revisions: + raise ConfigRevertFailed( + f"the device has no configuration after reverting to {revision_id!r}" + ) + now = revisions[0] + if self.config_revision_content(self.get_config_revision(now["id"])) != wanted: + raise ConfigRevertFailed( + f"the configuration in place ({now['id']!r}) is not revision {revision_id!r}" + " after the revert" + ) + return now diff --git a/tests/test_config_revisions.py b/tests/test_config_revisions.py new file mode 100644 index 0000000..e3950d3 --- /dev/null +++ b/tests/test_config_revisions.py @@ -0,0 +1,172 @@ +"""ConfigRevisionsMixin: a device's own configuration history (NetOrk/netork#2511). + +Some devices keep their earlier configurations themselves. An application restores a +configuration there by reverting to the revision that holds it -- on OPNsense the only +way, since no API takes an uploaded config.xml. Listing and reading are declared only, +so ``callable(getattr(driver, "get_config_revisions", None))`` is the truthful answer; +``revert_config_revision`` is a template: it refuses an id that is not in the history, +lets the driver revert, and checks that the configuration in place now is the +revision's. +""" + +from __future__ import annotations + +import inspect +from typing import get_type_hints + +import pytest + +from napalm_device_types import ( + ConfigRevertFailed, + ConfigRevisionDict, + ConfigRevisionsMixin, + DeviceTypeDriver, + FirewallDriver, + OSDriver, + SwitchDriver, + UnknownConfigRevision, +) + + +def test_the_shape(): + assert get_type_hints(ConfigRevisionDict) == { + "id": str, + "time": str | None, + "description": str | None, + "user": str | None, + "size": int | None, + } + + +def test_no_role_demands_it(): + for role in (FirewallDriver, OSDriver, SwitchDriver, DeviceTypeDriver): + assert not issubclass(role, ConfigRevisionsMixin) + + +def test_listing_and_reading_are_declared_not_implemented(): + assert not hasattr(ConfigRevisionsMixin, "get_config_revisions") + assert not hasattr(ConfigRevisionsMixin, "get_config_revision") + source = inspect.getsource(ConfigRevisionsMixin) + assert "def get_config_revisions(self) -> list[ConfigRevisionDict]" in source + assert "def get_config_revision(self, revision_id: str) -> str" in source + assert "def _revert_to_config_revision(self, revision_id: str) -> None" in source + + +def test_an_unknown_revision_is_a_value_error_that_names_it(): + error = UnknownConfigRevision("r9") + + assert isinstance(error, ValueError) + assert "'r9'" in str(error) + + +def test_a_failed_revert_is_a_runtime_error(): + assert issubclass(ConfigRevertFailed, RuntimeError) + + +def _revision(revision_id: str, time: str) -> ConfigRevisionDict: + return {"id": revision_id, "time": time, "description": None, "user": None, "size": None} + + +class _Device(ConfigRevisionsMixin): + """A device that keeps its history in memory, newest first, and saves a revert as a + new newest revision with a stamp of its own on the first line.""" + + def __init__(self) -> None: + self.history = [ + (_revision("r3", "2026-11-13T21:00:00+00:00"), "#saved 3\nb\n"), + (_revision("r2", "2026-11-12T21:00:00+00:00"), "#saved 2\na\n"), + (_revision("r1", "2026-11-11T21:00:00+00:00"), "#saved 1\na\n"), + ] + self.calls: list[str] = [] + + def get_config_revisions(self) -> list[ConfigRevisionDict]: + self.calls.append("list") + return [revision for revision, _ in self.history] + + def get_config_revision(self, revision_id: str) -> str: + self.calls.append(f"read {revision_id}") + for revision, text in self.history: + if revision["id"] == revision_id: + return text + raise UnknownConfigRevision(revision_id) + + def _revert_to_config_revision(self, revision_id: str) -> None: + self.calls.append(f"revert {revision_id}") + body = self.get_config_revision(revision_id).split("\n", 1)[1] + self.history.insert(0, (_revision("r4", "2026-11-14T08:00:00+00:00"), f"#saved 4\n{body}")) + + def config_revision_content(self, text: str) -> str: + return text.split("\n", 1)[1] + + +class TestRevertConfigRevision: + def test_reverts_and_answers_with_the_revision_now_in_place(self): + device = _Device() + + now = device.revert_config_revision("r1") + + assert now["id"] == "r4" + assert device.calls == ["list", "read r1", "revert r1", "read r1", "list", "read r4"] + + def test_the_revision_is_read_before_the_revert_which_may_rotate_it_out(self): + class Rotating(_Device): + def _revert_to_config_revision(self, revision_id: str) -> None: + super()._revert_to_config_revision(revision_id) + self.history.pop() # the oldest, r1, drops out + + assert Rotating().revert_config_revision("r1")["id"] == "r4" + + def test_a_revision_not_in_the_history_is_refused_before_anything_changes(self): + device = _Device() + + with pytest.raises(UnknownConfigRevision, match="r9"): + device.revert_config_revision("r9") + + assert device.calls == ["list"] + + def test_a_revert_the_device_did_not_take_fails(self): + # OPNsense answers "reverted" even when it fell back to the previous file. + class Deaf(_Device): + def _revert_to_config_revision(self, revision_id: str) -> None: + self.calls.append(f"revert {revision_id}") + + with pytest.raises(ConfigRevertFailed, match="r1"): + Deaf().revert_config_revision("r1") + + def test_a_history_that_is_empty_afterwards_fails(self): + class Forgetful(_Device): + def _revert_to_config_revision(self, revision_id: str) -> None: + self.history.clear() + + with pytest.raises(ConfigRevertFailed): + Forgetful().revert_config_revision("r1") + + def test_what_a_save_stamps_anew_does_not_count(self): + # r2 and r1 differ only in their stamp: reverting to r2 leaves r1's content. + device = _Device() + + assert device.revert_config_revision("r2")["id"] == "r4" + + def test_a_refusal_of_the_device_reaches_the_caller(self): + class Refusing(_Device): + def _revert_to_config_revision(self, revision_id: str) -> None: + raise ConfigRevertFailed("read-only user") + + with pytest.raises(ConfigRevertFailed, match="read-only"): + Refusing().revert_config_revision("r1") + + +class TestConfigRevisionContent: + def test_by_default_the_whole_text(self): + class Plain(ConfigRevisionsMixin): + pass + + assert Plain().config_revision_content("a\nb\n") == "a\nb\n" + + def test_without_a_stamp_every_save_differs(self): + class Plain(_Device): + def config_revision_content(self, text: str) -> str: + return ConfigRevisionsMixin.config_revision_content(self, text) + + with pytest.raises(ConfigRevertFailed): + Plain().revert_config_revision("r1")