From 93ba335798256c6f841d438e8e5a5f7569d0cb0a Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Tue, 17 Nov 2026 11:02:51 +0100 Subject: [PATCH] feat(firmware): install the offered firmware through FirmwareUpgradeMixin (NetOrk/netork#2615) start_firmware_upgrade(version) starts an upgrade the device runs by itself and restarts at the end of; get_update_progress follows it. The offer says whether the driver can install it now (installable) and names a later release line it never crosses to (latest_major_version). --- CHANGELOG.md | 10 ++++++++++ napalm_device_types/__init__.py | 3 ++- napalm_device_types/firmware.py | 25 ++++++++++++++++++++++++- napalm_device_types/models.py | 7 +++++++ napalm_device_types/updates.py | 3 ++- tests/test_fact_getters.py | 20 +++++++++++++++++++- 6 files changed, 64 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c50390d..96ca10d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ recorded here; their history is the git log. ## [Unreleased] +### Added +- `FirmwareUpgradeMixin.start_firmware_upgrade(version)`: start installing the firmware a + driver offers; the device runs it by itself and restarts at its end, and + `UpdateMixin.get_update_progress` follows it until then (NetOrk/netork#2615, OpenWrt's + sysupgrade through owut). +- `FirmwareOfferDict.installable`: whether the driver can install `latest_version` itself + now, False while the device lacks what that takes; and + `FirmwareOfferDict.latest_major_version`, the newest of a later release line, shown and + never crossed to by the driver. + ## [4.40.0] - 2026-11-17 ### Added diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 5ade277..6308372 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -138,7 +138,7 @@ from napalm_device_types.dhcp import DhcpApplyError, DhcpServerMixin, normalize_ from napalm_device_types.dns_forward import DnsForwardMixin from napalm_device_types.firewall import FirewallDriver from napalm_device_types.firewall_rules import FirewallRuleMixin -from napalm_device_types.firmware import FirmwareOfferMixin +from napalm_device_types.firmware import FirmwareOfferMixin, FirmwareUpgradeMixin from napalm_device_types.fixes import ( EnsurePackageMixin, LldpAgentMixin, @@ -382,6 +382,7 @@ __all__ = [ "OspfMixin", "UpdateProgressDict", "FirmwareOfferMixin", + "FirmwareUpgradeMixin", "LicenseDict", "LicenseMixin", "EnsurePackageMixin", diff --git a/napalm_device_types/firmware.py b/napalm_device_types/firmware.py index 08b0af1..d1d892b 100644 --- a/napalm_device_types/firmware.py +++ b/napalm_device_types/firmware.py @@ -1,10 +1,13 @@ -"""The firmware a vendor offers for a device. +"""The firmware a vendor offers for a device, and installing it. A fact for the caller (docs/STRUCTURE.md): a driver may know the newer firmware from the vendor's download catalogue or the device's own update check; whether running an older one is a problem is decided above the driver. Comparing the vendor's version strings is vendor knowledge, so the driver says itself whether the offer is newer. Declared only; a driver that can tell implements it. + +Installing it is a capability of its own (``FirmwareUpgradeMixin``): when and +whether is the caller's call, as with package updates; how is the driver's. """ from __future__ import annotations @@ -29,3 +32,23 @@ class FirmwareOfferMixin: "newer": True, "download_url": "https://.../GS308E_1.0.2.12.zip"} """ ... + + +class FirmwareUpgradeMixin: + if TYPE_CHECKING: # pragma: no cover - declared for type checkers only + + def start_firmware_upgrade(self, version: str) -> None: + """Starts installing *version*, an offer's ``latest_version`` that + :meth:`FirmwareOfferMixin.get_firmware_offer` called ``installable``. + + The device runs the upgrade by itself and restarts at its end, which + ends the session; the configuration is kept. Returns once it has + started. ``UpdateMixin.get_update_progress`` follows it until then: + ``"failed"`` when it stopped before the device restarted, which leaves + the running firmware as it was. + + :raises ValueError: *version* is not a version string the driver takes. + :raises RuntimeError: the device cannot start it (what it takes is + missing, an upgrade is already running). + """ + ... diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 8355a18..69fd04a 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1180,6 +1180,13 @@ class FirmwareOfferDict(TypedDict): latest_version: str newer: bool # the offer is newer than what runs, by the vendor's versioning download_url: NotRequired[str] + # The driver can install latest_version itself (FirmwareUpgradeMixin) now; False + # while the device lacks what that takes (OpenWrt without owut). Left out where + # the driver never installs firmware on this device. + installable: NotRequired[bool] + # The newest of a later release line (OpenWrt 25.12 on a 24.10 device), which + # latest_version does not cross to: shown, never installed by the driver. + latest_major_version: NotRequired[str] class HypervisorHostDict(TypedDict): diff --git a/napalm_device_types/updates.py b/napalm_device_types/updates.py index 91c25c4..a24b186 100644 --- a/napalm_device_types/updates.py +++ b/napalm_device_types/updates.py @@ -97,7 +97,8 @@ class UpdateMixin: """ Where an update the device runs by itself stands, for a caller that follows it: a firewall's firmware upgrade, which :meth:`apply_updates` - only starts. ``state`` is ``"running"`` until it ends in ``"done"`` + only starts, or one that ``FirmwareUpgradeMixin.start_firmware_upgrade`` + started. ``state`` is ``"running"`` until it ends in ``"done"`` or ``"failed"``; ``log`` is the device's whole log of it. Declared only: a driver whose :meth:`apply_updates` returns when the diff --git a/tests/test_fact_getters.py b/tests/test_fact_getters.py index d9cc556..06f6b9a 100644 --- a/tests/test_fact_getters.py +++ b/tests/test_fact_getters.py @@ -56,8 +56,26 @@ def test_a_firmware_offer_says_what_runs_and_what_is_offered(): from napalm_device_types import FirmwareOfferDict, FirmwareOfferMixin hints = get_type_hints(FirmwareOfferDict) - assert set(hints) == {"current_version", "latest_version", "newer", "download_url"} + assert set(hints) == { + "current_version", + "latest_version", + "newer", + "download_url", + "installable", + "latest_major_version", + } assert FirmwareOfferDict.__required_keys__ == frozenset( {"current_version", "latest_version", "newer"} ) assert not hasattr(FirmwareOfferMixin, "get_firmware_offer") + + +def test_a_firmware_upgrade_is_started_and_followed_like_a_device_run_update(): + """A driver that can install the firmware it offers starts it and the device + runs it by itself, restarting at its end (OpenWrt's sysupgrade, NetOrk/netork#2615); + the caller follows it through ``get_update_progress``. Declared only, so + ``hasattr`` tells a caller whether the driver offers it.""" + from napalm_device_types import FirmwareUpgradeMixin, UpdateMixin + + assert not hasattr(FirmwareUpgradeMixin, "start_firmware_upgrade") + assert not hasattr(UpdateMixin, "get_update_progress")