feat(config-revisions): declare a device's own configuration history
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m3s
driver / test (3.13) (pull_request) Successful in 1m12s
driver / test (3.12) (pull_request) Successful in 1m18s
driver / lowest (pull_request) Successful in 47s
driver / build (pull_request) Successful in 34s
driver / security (pull_request) Successful in 3m34s
CI / driver (pull_request) Successful in 5m2s
driver / publish (pull_request) Skipped
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m3s
driver / test (3.13) (pull_request) Successful in 1m12s
driver / test (3.12) (pull_request) Successful in 1m18s
driver / lowest (pull_request) Successful in 47s
driver / build (pull_request) Successful in 34s
driver / security (pull_request) Successful in 3m34s
CI / driver (pull_request) Successful in 5m2s
driver / publish (pull_request) Skipped
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
This commit is contained in:
1 parent
241acef6c1
commit
43e0210ff6
5 files changed
+349
No files matched your search
@@ -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
|
||||
Reference in new issue
Block a user