diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a8e0c8..4004bb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ All notable changes to this driver. The format follows ## [Unreleased] ### Added +- The firewall's configuration history (NetOrk/netork#2511): `get_config_revisions()` + lists the revisions OPNsense keeps of config.xml, newest first, each with its id, its + time in UTC, its description, its user and its size; `get_config_revision(id)` + returns one revision's config.xml; `revert_config_revision(id)` makes it the + configuration again through `/api/core/backup/revert_backup`, refuses an id that is + not in the history (`UnknownConfigRevision`), and raises `ConfigRevertFailed` when the + newest revision afterwards does not hold the revision's configuration -- OPNsense + answers "reverted" even when it kept the previous file. `config_revision_content()` + compares config.xml without the `` block every save writes. The contract is + napalm-device-types 4.38.0's `ConfigRevisionsMixin`. A revert saves config.xml and + nothing else: no service is reloaded and the firewall does not reboot. - Time sync (NetOrk/netork#2363): `get_time_sync()` from napalm-device-types 4.35.0's `TimeSyncMixin` reads the time servers (``, in their order) and the zone (``, an IANA name; none is the `Etc/UTC` OPNsense runs @@ -19,6 +30,11 @@ All notable changes to this driver. The format follows ### Changed - Requires napalm-device-types 4.35.0, which declares the time-sync contract. +- Requires napalm-device-types 4.38.0, which declares the configuration-history + contract. +- `load_replace_candidate` is `None` instead of NAPALM's stub that raised, so a caller + can tell that the driver replaces no configuration: OPNsense has no API that takes an + uploaded config.xml. ### Fixed - `get_ntp_servers()` lists the configured servers of config.xml, the same list as diff --git a/README.md b/README.md index 2bfb827..678a701 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ NAPALM community driver for **OPNsense** firewalls (read-only, via REST API). |---|---| | Python | 3.12 | | NAPALM | 4.0 | -| napalm-device-types | 4.35.0 | +| napalm-device-types | 4.38.0 | | requests | 2.28 | ## Installation @@ -85,6 +85,9 @@ arguments. | `get_ntp_servers` | ✅ ⁵ | `GET /api/core/backup/download/this`: `` of config.xml | | `get_time_sync` | ✅ ⁵ | `GET /api/core/backup/download/this` (servers, zone) + `GET /api/ntpd/service/status` (system peer) | | `get_config` | ✅ | `GET /api/core/backup/download/this` (XML) | +| `get_config_revisions()` | ✅ ⁶ | `GET /api/core/backup/backups/this` | +| `get_config_revision(revision_id)` | ✅ ⁶ | `GET /api/core/backup/download/this/` (XML) | +| `revert_config_revision(revision_id)` | ✅ ⁶ | `POST /api/core/backup/revert_backup/` | | `is_alive` | ✅ | TCP socket check | | `get_bgp_neighbors` | ✅ ² | `GET /api/quagga/bgp/get` + `GET /api/quagga/diagnostics/bgpneighbors` | | `get_vlans` | ✅ | `GET /api/interfaces/vlan_settings/search_item` | @@ -103,6 +106,7 @@ arguments. > ³ Overrides the generic per-host loop from `napalm-device-types`. > ⁴ See [Scheduled jobs](#scheduled-jobs). > ⁵ See [Time sync](#time-sync). +> ⁶ See [Configuration history](#configuration-history). ### Ping @@ -185,6 +189,52 @@ person where to set them. Which interfaces ntpd serves time on is not touched. I HA pair the configuration sync carries the servers to the backup when its "Network Time" item (`ntpd`) is ticked; the zone is not synchronised. +### Configuration history + +OPNsense keeps a copy of config.xml for every save in `/conf/backup` +(*System → Configuration → History*), `` of them (100 when unset); +the next save drops the oldest. `get_config_revisions()` lists them newest first, the +first being the configuration in place now: + +```python +[ + { + "id": "config-1794603885.1239.xml", # what the two methods below take + "time": "2026-11-13T21:04:45+00:00", # UTC, whatever zone the firewall runs in + "description": "/api/firewall/filter/apply made changes", # None when empty + "user": "apiuser@192.0.2.10", # None when empty + "size": 58213, # bytes + }, +] +``` + +The contract is napalm-device-types' `ConfigRevisionsMixin`; this driver does the API +calls. `get_config_revision(revision_id)` returns that revision's config.xml as text. +`revert_config_revision(revision_id)` makes it the configuration again and returns the +revision in place afterwards. It refuses an id that is not in the history now +(`UnknownConfigRevision`, a `ValueError`) before anything changes, reads the revision, +calls `revert_backup`, and then checks that the newest revision holds the revision's +configuration: OPNsense answers `reverted` even when it could not load the file and kept +the previous one. A refusal of the firewall (for a user with `user-config-readonly`) or +a failed check raises `ConfigRevertFailed`, a `RuntimeError`. That is five requests. +`config_revision_content(text)` is config.xml without the `` block every save +writes (who, when, from where), in canonical XML, with the indentation between elements +left out: two revisions with the same configuration compare equal through it. + +**What a revert does.** OPNsense copies the revision over config.xml and saves it. The +history gets a new newest entry with the revision's content, described as +`/api/core/backup/revert_backup/ made changes` by the API key's user, and the +oldest entry may drop out. That is all, and it is done when the request returns: +**no service is reloaded and the firewall does not reboot**, so it keeps running with +the settings it had until a subsystem's settings are applied or it restarts. The +`config` system hooks run afterwards; core installs none, a plugin such as git-backup +does. The revert starts no HA configuration sync. + +There is no API that takes an uploaded config.xml (the full restore exists only on the +legacy page `diag_backup.php`, behind a GUI login), so the driver offers no +`load_replace_candidate`: it is `None`. A configuration that is no longer in the +history cannot be put back through the API. The API key needs the backup privilege. + ## Config management OPNsense does not expose a single generic "push config" endpoint. Config is @@ -247,7 +297,9 @@ d.close() ### Limitations -- `load_replace_candidate` is not supported (no XML upload endpoint in the JSON API). +- `load_replace_candidate` is `None` (no XML upload endpoint in the JSON API); a revision + of the firewall's own history can be reverted to instead, see + [Configuration history](#configuration-history). - Non-route config (firewall rules, DHCP, DNS, interfaces, …) must be managed via OPNsense module-specific controllers — outside the scope of this driver. - `rollback()` reverts the entire `config.xml` to the pre-commit state (not just diff --git a/napalm_opnsense/config_revisions.py b/napalm_opnsense/config_revisions.py new file mode 100644 index 0000000..b925344 --- /dev/null +++ b/napalm_opnsense/config_revisions.py @@ -0,0 +1,204 @@ +"""The firewall's own configuration history (NetOrk/netork#2511). + +napalm-device-types' ``ConfigRevisionsMixin`` is the contract: it declares the listing +and the reading and runs the revert as a template -- refuse an id that is not in the +history, read the revision, revert, check that the newest revision holds it. This +module talks to the firewall: the three API calls, and ``config_revision_content``, +which leaves out the ```` block every save writes into config.xml. + +OPNsense keeps a copy of config.xml for every save, as ``/conf/backup/config-.xml`` -- *System → Configuration → History*. It keeps ```` +of them (100 when unset) and drops the oldest on the next save. The newest is the +copy of the configuration in place now. + +No API takes an uploaded config.xml: the backup API (``/api/core/backup/``) lists the +history, hands out a revision and reverts to one, but only to a revision that is +already on the firewall; a full replace exists only on the legacy page +``diag_backup.php``. So the driver has no ``load_replace_candidate``, and an +application restores a configuration by reverting to the revision that holds it. + +A revert (``revert_backup``) copies the revision over config.xml and saves it: the +history gets a new newest entry with the revision's content, described as +``/api/core/backup/revert_backup/ made changes`` and by the API key's user, and +the oldest entry may drop out. That is all, and it is done when the request returns: +OPNsense reloads no service and does not reboot, so the running firewall keeps the +state it had until a subsystem's settings are applied or it restarts. The ``config`` +system hooks run afterwards (``/usr/local/etc/rc.syshook.d/config``, from syslog); +core installs none, a plugin such as git-backup does. The revert starts no HA +configuration sync. +""" + +from __future__ import annotations + +import logging +import re + +# config.xml as the firewall's own API hands it over; ElementTree resolves no external +# entities, and expat limits entity expansion since 2.4.1. +import xml.etree.ElementTree as ET # nosec B405 +from datetime import UTC, datetime +from typing import TYPE_CHECKING, Any + +from napalm_device_types import ( + ConfigRevertFailed, + ConfigRevisionDict, + ConfigRevisionsMixin, + UnknownConfigRevision, +) + +logger = logging.getLogger(__name__) + +#: The history of this firewall, newest first. +HISTORY_PATH = "/api/core/backup/backups/this" +#: One revision's config.xml; the answer is empty for a name with no file. +DOWNLOAD_PATH = "/api/core/backup/download/this/{revision_id}" +#: Copy a revision over config.xml and save it. +REVERT_PATH = "/api/core/backup/revert_backup/{revision_id}" +#: What ``revert_backup`` answers for a revision it has no file for. +_NOT_FOUND = "not_found" +_REVERTED = "reverted" +#: What every save writes into config.xml anew: who saved it, when, from where. +_STAMP = "revision" +#: A revision's file name in /conf/backup: its unix time, and ``_`` after a save +#: within the same microsecond. Nothing else may reach a request path. +_REVISION_ID = re.compile(r"config-([0-9]+(?:\.[0-9]+)?)(?:_[0-9]+)?\.xml") + + +def _checked_id(revision_id: object) -> str: + if not isinstance(revision_id, str) or not _REVISION_ID.fullmatch(revision_id): + raise UnknownConfigRevision(revision_id) + return revision_id + + +def _utc(value: Any) -> str | None: + try: + seconds = float(value) + except (TypeError, ValueError): + return None + return datetime.fromtimestamp(seconds, UTC).isoformat(timespec="seconds") + + +def _text(value: Any) -> str | None: + return value.strip() or None if isinstance(value, str) else None + + +def _stamp(revision: ConfigRevisionDict) -> float: + found = _REVISION_ID.fullmatch(revision["id"]) + return float(found.group(1)) if found else 0.0 + + +def _revision(item: Any) -> ConfigRevisionDict | None: + if not isinstance(item, dict): + return None + revision_id = item.get("id") + if not isinstance(revision_id, str): + return None + found = _REVISION_ID.fullmatch(revision_id) + if found is None: + return None + size = item.get("filesize") + return { + "id": revision_id, + # The revision's own time; the file name's when it has none. + "time": _utc(item.get("time")) or _utc(found.group(1)), + "description": _text(item.get("description")), + "user": _text(item.get("username")), + "size": size if isinstance(size, int) and not isinstance(size, bool) else None, + } + + +def config_revisions(answer: Any) -> list[ConfigRevisionDict]: + """The revisions of a ``backups/this`` *answer*, newest first. + + An entry without a usable id is left out: nothing could read or revert it. + + :raises ValueError: for an answer that is no history, which is not "no revisions". + """ + items = answer.get("items") if isinstance(answer, dict) else None + if not isinstance(items, list): + raise ValueError("the firewall answered with no configuration history") + revisions = [r for r in map(_revision, items) if r is not None] + # By the file name's time, as OPNsense itself orders them. + revisions.sort(key=_stamp, reverse=True) + return revisions + + +class OPNsenseConfigRevisionsMixin(ConfigRevisionsMixin): + """List, read and revert to the firewall's configuration revisions; see the module.""" + + #: No API takes an uploaded config.xml (NAPALM's base stub would only raise). + load_replace_candidate = None + + if TYPE_CHECKING: # pragma: no cover - the driver's REST helpers + + def _get(self, path: str) -> dict[str, Any]: ... + + def _get_text(self, path: str) -> str: ... + + def _post(self, path: str, data: dict[str, Any] | None = None) -> dict[str, Any]: ... + + def get_config_revisions(self) -> list[ConfigRevisionDict]: + """The firewall's configuration history, newest first; the first is in place now. + + :raises Exception: when the history cannot be read, e.g. by a key without the + backup privilege. + """ + return config_revisions(self._get(HISTORY_PATH)) + + def get_config_revision(self, revision_id: str) -> str: + """The config.xml of revision *revision_id*, as the firewall keeps it. + + :raises UnknownConfigRevision: for an id that is not in the history. + :raises Exception: when the firewall cannot be read. + """ + checked = _checked_id(revision_id) + text = self._get_text(DOWNLOAD_PATH.format(revision_id=checked)) + if not text.strip(): + raise UnknownConfigRevision(checked) + return text + + def config_revision_content(self, text: str) -> str: + """config.xml without the root's ```` block, canonical (XML C14N). + + The indentation between elements does not count; a value's own blanks do. + + :raises xml.etree.ElementTree.ParseError: for a text that is no XML. + """ + # The firewall's own config.xml: see the import. + root = ET.fromstring(text) # nosec B314 + for stamp in root.findall(_STAMP): + root.remove(stamp) + for element in root.iter(): + if element.text is not None and not element.text.strip(): + element.text = None + if element.tail is not None and not element.tail.strip(): + element.tail = None + return ET.canonicalize(ET.tostring(root, encoding="unicode")) + + def _revert_to_config_revision(self, revision_id: str) -> None: + """``revert_backup``: config.xml becomes the revision, saved as the newest one.""" + checked = _checked_id(revision_id) + answer = self._post(REVERT_PATH.format(revision_id=checked)) + status = answer.get("status") if isinstance(answer, dict) else None + if status == _NOT_FOUND: + raise UnknownConfigRevision(checked) + if status != _REVERTED: + reason = answer.get("errorMessage") if isinstance(answer, dict) else None + raise ConfigRevertFailed( + f"The firewall did not revert to {checked}: {reason or status}" + ) + + def _get_latest_backup_id(self) -> str | None: + """Return the ID of the most recent server-side config backup, or ``None``. + + Calls ``GET /api/core/backup/backups/this``. The response is sorted + newest-first by OPNsense. Returns ``None`` when no backups exist or + the request fails. + """ + try: + data = self._get(HISTORY_PATH) + items = data.get("items", []) + return items[0]["id"] if items else None + except Exception as exc: + logger.debug("No backup snapshots found: %s", exc) + return None diff --git a/napalm_opnsense/opnsense.py b/napalm_opnsense/opnsense.py index c061705..fd3a1df 100644 --- a/napalm_opnsense/opnsense.py +++ b/napalm_opnsense/opnsense.py @@ -62,6 +62,7 @@ from napalm_device_types.models import ( from requests.exceptions import RequestException from napalm_opnsense.api_endpoint import ALIVE_TIMEOUT, api_endpoint +from napalm_opnsense.config_revisions import OPNsenseConfigRevisionsMixin from napalm_opnsense.ha import config_sync, dhcp_ha from napalm_opnsense.kea_reservations import ( lease_held, @@ -99,6 +100,7 @@ def _opnsense_version(versions: Any) -> str: class OPNsenseDriver( + OPNsenseConfigRevisionsMixin, OPNsenseTimeSyncMixin, OPNsenseScheduledJobsMixin, OPNsenseSshSettingsMixin, @@ -1091,21 +1093,6 @@ class OPNsenseDriver( # Internal helpers (config management) # ------------------------------------------------------------------ - def _get_latest_backup_id(self) -> str | None: - """Return the ID of the most recent server-side config backup, or ``None``. - - Calls ``GET /api/core/backup/backups/this``. The response is sorted - newest-first by OPNsense. Returns ``None`` when no backups exist or - the request fails. - """ - try: - data = self._get("/api/core/backup/backups/this") - items = data.get("items", []) - return items[0]["id"] if items else None - except Exception as exc: - logger.debug("No backup snapshots found: %s", exc) - return None - def _fetch_current_routes(self) -> list[dict[str, Any]]: """Return the current static routes from the OPNsense API. diff --git a/pyproject.toml b/pyproject.toml index 5e9d87b..f671c45 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ classifiers = [ ] dependencies = [ "napalm>=5.1", # older releases import pkg_resources, which a 3.12 venv lacks - "napalm-device-types>=4.35.0", + "napalm-device-types>=4.38.0", "requests>=2.28.0", ] diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index f794000..99918ad 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -55,7 +55,7 @@ "napalm_opnsense.resolver_mixin" ], "python_file_lines": { - "napalm_opnsense/opnsense.py": 3035 + "napalm_opnsense/opnsense.py": 3022 }, "untyped_public": [ "napalm_opnsense/opnsense.py::OPNsenseDriver.get_snmp_config" diff --git a/tests/unit/fixtures/core_backup_backups_this.json b/tests/unit/fixtures/core_backup_backups_this.json new file mode 100644 index 0000000..4c72086 --- /dev/null +++ b/tests/unit/fixtures/core_backup_backups_this.json @@ -0,0 +1,36 @@ +{ + "items": [ + { + "time": "1794603885.12", + "time_iso": "2026-11-13T22:04:45+01:00", + "description": "/api/firewall/filter/apply made changes", + "username": "apiuser@192.0.2.10", + "filesize": 58213, + "id": "config-1794603885.1239.xml" + }, + { + "time": "1794603482.87", + "time_iso": "2026-11-13T21:58:02+01:00", + "description": "/system_general.php made changes", + "username": "root@192.0.2.20", + "filesize": 58190, + "id": "config-1794603482.8721.xml" + }, + { + "time": "1794475810.05", + "time_iso": "2026-11-12T10:30:10+01:00", + "description": "/api/core/backup/revert_backup/config-1793516400.0012.xml made changes", + "username": "apiuser@192.0.2.10", + "filesize": 57944, + "id": "config-1794475810.0548_123456789.xml" + }, + { + "time": "1793516400.00", + "time_iso": "2026-11-01T08:00:00+01:00", + "description": "", + "username": "", + "filesize": 57944, + "id": "config-1793516400.0012.xml" + } + ] +} diff --git a/tests/unit/test_config_revisions.py b/tests/unit/test_config_revisions.py new file mode 100644 index 0000000..3ae55f2 --- /dev/null +++ b/tests/unit/test_config_revisions.py @@ -0,0 +1,415 @@ +"""The firewall's own configuration history: list it, read a revision, revert to one. + +NetOrk/netork#2511: OPNsense has no API that takes an uploaded config.xml, so an +application restores a configuration by finding the revision in the firewall's own +history whose content it wants and reverting to that one. + +``core_backup_backups_this.json`` has the shape ``/api/core/backup/backups/this`` answers +with on 24.7 up to 26.7 and ``master`` (``OPNsense\\Core\\Api\\BackupController``): +newest first, ``time`` the revision's unix time with two decimals, ``time_iso`` the same +in the firewall's own zone (here +01:00), ``id`` the file name in ``/conf/backup``. The +values are made up; the oldest is a revision without description and user, as the +first configuration of a new install is. +""" + +from __future__ import annotations + +import copy +import json +from pathlib import Path +from unittest.mock import MagicMock, patch +from xml.etree.ElementTree import ParseError + +import pytest +import requests +from napalm_device_types import ConfigRevertFailed, ConfigRevisionsMixin, UnknownConfigRevision + +from napalm_opnsense.opnsense import OPNsenseDriver + +FIXTURES = Path(__file__).parent / "fixtures" +HISTORY = json.loads((FIXTURES / "core_backup_backups_this.json").read_text()) +CONFIG_XML = (FIXTURES / "config_xml_sample.xml").read_text() + +HISTORY_PATH = "/api/core/backup/backups/this" +NEWEST = "config-1794603885.1239.xml" +OLDEST = "config-1793516400.0012.xml" +WITH_SUFFIX = "config-1794475810.0548_123456789.xml" +#: The id of the revision a revert saves, as the fake firewall names it. +REVERTED = "config-1794700000.0001.xml" + + +def _stamped(config: str, user: str, time: str) -> str: + """*config* with the block every save writes into config.xml.""" + block = ( + f" \n {user}\n \n" + " /api/core/backup/revert_backup made changes\n" + " \n" + ) + return config.replace("", block + "") + + +#: The oldest revision is the sample; every later one names the host otherwise. +FILES = { + OLDEST: _stamped(CONFIG_XML, "root@192.0.2.20", "1793516400.00"), + WITH_SUFFIX: _stamped(CONFIG_XML, "apiuser@192.0.2.10", "1794475810.05"), + "config-1794603482.8721.xml": _stamped( + CONFIG_XML.replace("OPNsense", "gw"), + "root@192.0.2.20", + "1794603482.87", + ), + NEWEST: _stamped( + CONFIG_XML.replace("OPNsense", "gw1"), + "apiuser@192.0.2.10", + "1794603885.12", + ), +} + + +class Firewall: + """Answers as the firewall's backup API would; every request is recorded. + + A revert it takes saves the revision as a new newest one, restamped; one it does + not take (``takes=False``) still answers "reverted", as OPNsense does when it falls + back to the previous file. + """ + + def __init__(self, history=HISTORY, files=None, revert_answer=None, takes=True): + self.history = copy.deepcopy(history) + self.files = dict(FILES if files is None else files) + self.revert_answer = revert_answer or {"status": "reverted"} + self.takes = takes + self.requests: list[tuple[str, str]] = [] + + def get(self, url, timeout=None): + path = url.removeprefix("https://fw") + self.requests.append(("GET", path)) + response = MagicMock() + response.raise_for_status.return_value = None + if path == HISTORY_PATH: + if isinstance(self.history, Exception): + response.raise_for_status.side_effect = self.history + response.json.return_value = self.history + return response + prefix = "/api/core/backup/download/this/" + if path.startswith(prefix): + # BackupController::downloadAction sends nothing for a name it has no file for. + response.text = self.files.get(path.removeprefix(prefix), "") + response.json.side_effect = json.JSONDecodeError("Expecting value", "<", 0) + return response + raise AssertionError(f"unexpected GET {path}") + + def post(self, url, json=None, timeout=None): + path = url.removeprefix("https://fw") + self.requests.append(("POST", path)) + response = MagicMock() + response.raise_for_status.return_value = None + if isinstance(self.revert_answer, Exception): + response.raise_for_status.side_effect = self.revert_answer + elif self.revert_answer.get("status") == "reverted" and self.takes: + self._save(path.rsplit("/", 1)[1]) + response.json.return_value = self.revert_answer + return response + + def _save(self, revision_id): + body = self.files[revision_id].split(" ")[0] + "\n" + self.files[REVERTED] = _stamped(body, "apiuser@192.0.2.10", "1794700000.00") + item = {"time": "1794700000.00", "description": "", "username": "", "id": REVERTED} + self.history["items"].insert(0, item) + + @property + def posts(self) -> list[str]: + return [path for method, path in self.requests if method == "POST"] + + +@pytest.fixture +def driver(): + with patch("napalm_opnsense.opnsense.requests.Session"): + drv = OPNsenseDriver( + hostname="fw", username="k", password="s", optional_args={"verify": False} + ) + drv.session = MagicMock() + yield drv + + +def _on(driver, firewall: Firewall) -> Firewall: + driver.session.get.side_effect = firewall.get + driver.session.post.side_effect = firewall.post + return firewall + + +class TestGetConfigRevisions: + def test_every_revision_newest_first(self, driver): + _on(driver, Firewall()) + + revisions = driver.get_config_revisions() + + assert [r["id"] for r in revisions] == [ + NEWEST, + "config-1794603482.8721.xml", + WITH_SUFFIX, + OLDEST, + ] + + def test_a_revision_as_the_firewall_describes_it(self, driver): + _on(driver, Firewall()) + + assert driver.get_config_revisions()[0] == { + "id": NEWEST, + "time": "2026-11-13T21:04:45+00:00", + "description": "/api/firewall/filter/apply made changes", + "user": "apiuser@192.0.2.10", + "size": 58213, + } + + def test_the_time_is_utc_whatever_zone_the_firewall_runs_in(self, driver): + # time_iso is in the firewall's zone (+01:00 here); time is unix seconds. + _on(driver, Firewall()) + + times = [r["time"] for r in driver.get_config_revisions()] + + assert times == [ + "2026-11-13T21:04:45+00:00", + "2026-11-13T20:58:02+00:00", + "2026-11-12T09:30:10+00:00", + "2026-11-01T07:00:00+00:00", + ] + + def test_no_description_and_no_user_are_none(self, driver): + _on(driver, Firewall()) + + oldest = driver.get_config_revisions()[-1] + + assert (oldest["description"], oldest["user"]) == (None, None) + + def test_newest_first_even_when_the_answer_is_not_sorted(self, driver): + items = list(reversed(HISTORY["items"])) + _on(driver, Firewall(history={"items": items})) + + assert driver.get_config_revisions()[0]["id"] == NEWEST + + def test_without_a_time_the_file_name_tells_it(self, driver): + item = {"id": OLDEST, "description": "", "username": "", "filesize": 1} + _on(driver, Firewall(history={"items": [item]})) + + assert driver.get_config_revisions()[0]["time"] == "2026-11-01T07:00:00+00:00" + + def test_a_time_and_size_of_another_shape_are_none(self, driver): + item = {"id": "config-1.xml", "time": "soon", "filesize": "big", "description": 7} + _on(driver, Firewall(history={"items": [item, "noise"]})) + + assert driver.get_config_revisions() == [ + { + "id": "config-1.xml", + "time": "1970-01-01T00:00:01+00:00", + "description": None, + "user": None, + "size": None, + } + ] + + def test_an_entry_without_a_usable_id_is_left_out(self, driver): + # Nothing could read or revert it: the id goes into the request path. + items = [ + {"id": "../config.xml", "time": "1"}, + {"id": "config-1/../../x.xml", "time": "1"}, + {"time": "1"}, + HISTORY["items"][0], + ] + _on(driver, Firewall(history={"items": items})) + + assert [r["id"] for r in driver.get_config_revisions()] == [NEWEST] + + def test_no_history_is_an_empty_list(self, driver): + _on(driver, Firewall(history={"items": []})) + + assert driver.get_config_revisions() == [] + + def test_a_failed_read_raises(self, driver): + _on(driver, Firewall(history=requests.HTTPError("403 Forbidden"))) + + with pytest.raises(requests.HTTPError, match="403"): + driver.get_config_revisions() + + @pytest.mark.parametrize("answer", [[], {"items": "x"}, {}], ids=["list", "items", "empty"]) + def test_an_answer_of_another_shape_raises(self, driver, answer): + # "No history" would be a reading; this is none. + _on(driver, Firewall(history=answer)) + + with pytest.raises(ValueError, match="history"): + driver.get_config_revisions() + + def test_a_reading_only_reads(self, driver): + firewall = _on(driver, Firewall()) + + driver.get_config_revisions() + + assert firewall.requests == [("GET", HISTORY_PATH)] + + +class TestGetConfigRevision: + def test_the_revisions_config_xml(self, driver): + firewall = _on(driver, Firewall()) + + assert driver.get_config_revision(OLDEST) == FILES[OLDEST] + assert firewall.requests == [("GET", f"/api/core/backup/download/this/{OLDEST}")] + + def test_a_revision_the_firewall_has_no_file_for_raises(self, driver): + # Rotated out of the history: the download answers with nothing. + _on(driver, Firewall(files={})) + + with pytest.raises(UnknownConfigRevision, match=OLDEST): + driver.get_config_revision(OLDEST) + + @pytest.mark.parametrize( + "revision_id", + ["", "config.xml", "../config.xml", "config-1/../../x.xml", "config-1.xml?x=1", None], + ) + def test_an_id_that_names_no_revision_is_refused_before_any_request(self, driver, revision_id): + firewall = _on(driver, Firewall()) + + with pytest.raises(UnknownConfigRevision): + driver.get_config_revision(revision_id) + + assert firewall.requests == [] + + def test_a_failed_read_raises(self, driver): + resp = MagicMock() + resp.raise_for_status.side_effect = requests.HTTPError("403 Forbidden") + driver.session.get.return_value = resp + + with pytest.raises(requests.HTTPError, match="403"): + driver.get_config_revision(OLDEST) + + +class TestRevertConfigRevision: + def test_reverts_through_the_backup_api_and_checks_the_result(self, driver): + firewall = _on(driver, Firewall()) + + now = driver.revert_config_revision(OLDEST) + + assert now["id"] == REVERTED + assert firewall.requests == [ + ("GET", HISTORY_PATH), + ("GET", f"/api/core/backup/download/this/{OLDEST}"), + ("POST", f"/api/core/backup/revert_backup/{OLDEST}"), + ("GET", HISTORY_PATH), + ("GET", f"/api/core/backup/download/this/{REVERTED}"), + ] + + def test_an_id_with_the_suffix_of_a_fast_save(self, driver): + firewall = _on(driver, Firewall()) + + driver.revert_config_revision(WITH_SUFFIX) + + assert firewall.posts == [f"/api/core/backup/revert_backup/{WITH_SUFFIX}"] + + def test_a_revert_the_firewall_did_not_take_fails(self, driver): + # restoreBackup() falls back to the previous file and the answer is "reverted". + _on(driver, Firewall(takes=False)) + + with pytest.raises(ConfigRevertFailed, match=OLDEST): + driver.revert_config_revision(OLDEST) + + def test_a_revision_not_in_the_history_is_refused(self, driver): + firewall = _on(driver, Firewall()) + + with pytest.raises(UnknownConfigRevision, match="config-1000000000.5.xml"): + driver.revert_config_revision("config-1000000000.5.xml") + + assert firewall.posts == [] + + @pytest.mark.parametrize("revision_id", ["", "../config.xml", "config-1.xml/x", None]) + def test_an_id_that_names_no_revision_never_reaches_a_request_path(self, driver, revision_id): + firewall = _on(driver, Firewall()) + + with pytest.raises(UnknownConfigRevision): + driver.revert_config_revision(revision_id) + + assert firewall.requests == [("GET", HISTORY_PATH)] + + def test_a_history_that_cannot_be_read_reverts_nothing(self, driver): + firewall = _on(driver, Firewall(history=requests.HTTPError("403 Forbidden"))) + + with pytest.raises(requests.HTTPError): + driver.revert_config_revision(OLDEST) + + assert firewall.posts == [] + + def test_a_revision_gone_by_the_time_of_the_revert_is_unknown(self, driver): + _on(driver, Firewall(revert_answer={"status": "not_found"})) + + with pytest.raises(UnknownConfigRevision, match=OLDEST): + driver.revert_config_revision(OLDEST) + + def test_a_key_that_may_not_write_is_refused_with_the_firewalls_reason(self, driver): + # user-config-readonly: throwReadOnly() answers with an errorMessage. + reason = "User apiuser denied for write access (user-config-readonly set)" + _on(driver, Firewall(revert_answer={"errorMessage": reason, "errorTitle": "Error"})) + + with pytest.raises(ConfigRevertFailed, match="user-config-readonly"): + driver.revert_config_revision(OLDEST) + + def test_any_other_answer_is_a_failed_revert(self, driver): + _on(driver, Firewall(revert_answer={"status": "failed"})) + + with pytest.raises(ConfigRevertFailed, match="failed"): + driver.revert_config_revision(OLDEST) + + def test_an_http_error_raises(self, driver): + _on(driver, Firewall(revert_answer=requests.HTTPError("500 Server Error"))) + + with pytest.raises(requests.HTTPError, match="500"): + driver.revert_config_revision(OLDEST) + + +class TestConfigRevisionContent: + def test_the_revision_block_does_not_count(self, driver): + # Same configuration, saved by someone else at another time. + assert driver.config_revision_content(FILES[OLDEST]) == driver.config_revision_content( + FILES[WITH_SUFFIX] + ) + + def test_a_changed_setting_counts(self, driver): + assert driver.config_revision_content(FILES[OLDEST]) != driver.config_revision_content( + FILES[NEWEST] + ) + + def test_a_configuration_without_a_revision_block(self, driver): + stamped = driver.config_revision_content(FILES[OLDEST]) + + assert driver.config_revision_content(CONFIG_XML) == stamped + + def test_a_revision_element_deeper_down_counts(self, driver): + # Only the root's is the save's stamp. + deeper = CONFIG_XML.replace("", "7", 1) + + assert driver.config_revision_content(deeper) != driver.config_revision_content(CONFIG_XML) + + def test_how_the_xml_is_written_does_not_count(self, driver): + # Attribute order, quotes and empty elements are no difference of the configuration. + a = '\n' + b = "" + + assert driver.config_revision_content(a) == driver.config_revision_content(b) + + def test_the_blanks_of_a_value_count(self, driver): + padded = CONFIG_XML.replace("opnsense", "opnsense ") + + assert driver.config_revision_content(padded) != driver.config_revision_content(CONFIG_XML) + + def test_text_that_is_no_xml_raises(self, driver): + with pytest.raises(ParseError): + driver.config_revision_content("Login") + + +class TestWhatTheDriverOffers: + def test_it_keeps_the_contract_of_device_types(self): + assert issubclass(OPNsenseDriver, ConfigRevisionsMixin) + + def test_it_reads_and_reverts_revisions(self): + for name in ("get_config_revisions", "get_config_revision", "revert_config_revision"): + assert callable(getattr(OPNsenseDriver, name, None)), name + + def test_it_replaces_no_configuration(self): + # No API takes an uploaded config.xml: an application asks for this and gets no. + assert getattr(OPNsenseDriver, "load_replace_candidate", None) is None