From 874c6c5a92aff65ca7c04bf9ef20b4c00f50d22c Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 30 Oct 2026 08:37:08 +0100 Subject: [PATCH] feat: ARP_AGE_UNKNOWN, the age of a neighbour the device does not report NAPALM requires an age on every entry of get_arp_table and get_ipv6_neighbors_table. Many devices do not report one, and drivers filled in 0.0, which means "confirmed just now". ARP_AGE_UNKNOWN (-1.0, as NAPALM's IOS driver reports) is the value for "not reported"; the README states the contract. NetOrk/netork#1327 --- CHANGELOG.md | 4 ++++ README.md | 11 +++++++++++ napalm_device_types/__init__.py | 2 ++ napalm_device_types/arp.py | 13 +++++++++++++ tests/test_arp_age.py | 27 +++++++++++++++++++++++++++ 5 files changed, 57 insertions(+) create mode 100644 napalm_device_types/arp.py create mode 100644 tests/test_arp_age.py diff --git a/CHANGELOG.md b/CHANGELOG.md index a52306f..7fcabad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ recorded here; their history is the git log. 3.12 venv no longer has. ### Added +- `ARP_AGE_UNKNOWN` (`napalm_device_types.arp`, `-1.0`): the `age` a driver reports + in `get_arp_table` and `get_ipv6_neighbors_table` when the device does not say how + old an entry is. `0.0` means "confirmed just now" and is no stand-in for it + (NetOrk/netork#1327). - `HostShutdownMixin.shutdown_host()`, on `DeviceTypeDriver`: shut the device itself down cleanly through its own means; declared, so `hasattr` says whether a driver can. No forced variant (NetOrk/netork#1636). diff --git a/README.md b/README.md index a206e3f..c982f43 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,17 @@ base; a mixin listed after it loses the MRO to NAPALM's stub. For the same reaso `hasattr` says nothing about NAPALM's getters, and the OS role's account listing is `get_os_users`, not `get_users` -- NAPALM's `get_users` has a different shape. +### NAPALM's getters: an unknown ARP age is `-1.0` + +NAPALM requires an `age` on every entry of `get_arp_table` and +`get_ipv6_neighbors_table`: seconds since the device last confirmed that neighbour. +Many devices do not report one (`ip neigh`, `/proc/net/arp`, a router's host list). +A driver that cannot read the age reports `ARP_AGE_UNKNOWN` (`-1.0`, as NAPALM's IOS +driver does), never `0.0`: `0.0` means "confirmed just now", and an application that +ranks sightings by freshness takes it at its word (NetOrk/netork#1327). An expiry +countdown (FreeBSD's `expires in 1180 seconds`) is not an age either. A driver whose +device does report the age keeps reporting it. + ## Function classes: what a device *can do* Behaviour shared across roles lives in a function class, exactly once, and a role base diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 9cc53bf..8945a20 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -74,6 +74,7 @@ from napalm_device_types.apt_proxy import ( parse_apt_proxy, same_proxy_url, ) +from napalm_device_types.arp import ARP_AGE_UNKNOWN from napalm_device_types.base import DeviceTypeDriver, FingerprintRule, PortSpec, rules_max_weight from napalm_device_types.channel import ( ByteStream, @@ -278,6 +279,7 @@ __all__ = [ "InterfaceFilterMixin", "MacAclMixin", "ManagementControllerDriver", + "ARP_AGE_UNKNOWN", "POWER_ACTIONS", "PowerAction", "PowerStateDict", diff --git a/napalm_device_types/arp.py b/napalm_device_types/arp.py new file mode 100644 index 0000000..c543a89 --- /dev/null +++ b/napalm_device_types/arp.py @@ -0,0 +1,13 @@ +"""The ``age`` of an entry in NAPALM's neighbour tables when the device does not say. + +NAPALM requires an ``age`` on every entry of ``get_arp_table`` and +``get_ipv6_neighbors_table``: seconds since the device last confirmed that +neighbour. Many devices do not report one. ``0.0`` means "confirmed just now" +and must never stand in for "not reported": a caller ranking sightings by +freshness takes it at its word (NetOrk/netork#1327). An expiry countdown is not +an age either. The value is NAPALM's own; its IOS driver reports ``-1.0``. +""" + +from typing import Final + +ARP_AGE_UNKNOWN: Final[float] = -1.0 diff --git a/tests/test_arp_age.py b/tests/test_arp_age.py new file mode 100644 index 0000000..d913dd2 --- /dev/null +++ b/tests/test_arp_age.py @@ -0,0 +1,27 @@ +"""An ARP or neighbour entry whose age the device does not report says so. + +NAPALM's ``get_arp_table`` and ``get_ipv6_neighbors_table`` require an ``age`` +on every entry, and a driver that could not read one used to fill in ``0.0``. +To a caller that is the freshest sighting there is: netOrk took a neighbour the +device had not confirmed for hours as seen this second (NetOrk/netork#1327). +Unknown is ``-1.0``, as in NAPALM's own IOS driver; ``0.0`` means "just now". +""" + +from __future__ import annotations + +from napalm_device_types import ARP_AGE_UNKNOWN +from napalm_device_types.arp import ARP_AGE_UNKNOWN as FROM_MODULE + + +def test_an_unknown_age_is_minus_one(): + assert ARP_AGE_UNKNOWN == -1.0 + assert isinstance(ARP_AGE_UNKNOWN, float) + + +def test_the_package_exports_the_modules_constant(): + assert ARP_AGE_UNKNOWN is FROM_MODULE + + +def test_no_real_age_can_be_mistaken_for_unknown(): + # An age is seconds since the entry was last confirmed: never negative. + assert ARP_AGE_UNKNOWN < 0 -- 2.54.0