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")