Merge pull request 'feat(config-revisions): declare a device's own configuration history' (#117) from feat/config-revisions into main
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 15s
driver / types (push) Successful in 1m11s
driver / test (3.13) (push) Successful in 1m6s
driver / test (3.12) (push) Successful in 1m27s
driver / lowest (push) Successful in 37s
driver / build (push) Successful in 29s
driver / security (push) Successful in 1m5s
CI / driver (push) Successful in 2m58s
driver / publish (push) Skipped
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 15s
driver / types (push) Successful in 1m11s
driver / test (3.13) (push) Successful in 1m6s
driver / test (3.12) (push) Successful in 1m27s
driver / lowest (push) Successful in 37s
driver / build (push) Successful in 29s
driver / security (push) Successful in 1m5s
CI / driver (push) Successful in 2m58s
driver / publish (push) Skipped
This commit was merged in pull request #117.
This commit is contained in:
commit
e43926f1d5
5 files changed
+349
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
@@ -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")
|
||||
Reference in new issue
Block a user