netbox-interface-name-rules 1.4.2__tar.gz → 1.4.3__tar.gz

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-interface-name-rules
-Version: 1.4.2
+Version: 1.4.3
 Summary: NetBox plugin for automatic interface renaming when modules are installed
 Author: Marcin Zieba
 License-Expression: Apache-2.0

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/netbox_interface_name_rules/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
 from netbox.plugins import PluginConfig
 
-__version__ = "1.4.2"
+__version__ = "1.4.3"
 
 
 class InterfaceNameRulesConfig(PluginConfig):
@@ -13,7 +13,7 @@ class InterfaceNameRulesConfig(PluginConfig):
     description = "Automatic interface renaming when modules are installed into bays."
     version = __version__
     base_url = "interface-name-rules"
-    min_version = "4.2.0"
+    min_version = "4.3.0"
     required_settings = []
     default_settings = {}
     author = "Marcin Zieba"

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/netbox_interface_name_rules/engine.py

@@ -27,6 +27,9 @@ logger = logging.getLogger(__name__)
 # per call and the set reloaded only when it changes, so it self-invalidates on any
 # create/delete/edit — including raw bulk ``.update()`` of any matching field and SET_NULL
 # cascades that bypass auto_now, and across test transactions — with no signal wiring.
+# A reload publishes the new set by rebinding this name to a fresh dict in one atomic assignment
+# (see _get_enabled_rules), so a concurrent reader on another worker thread sees either the whole
+# old set or the whole new one — never exact/regex/memo torn across two versions.
 _RULE_CACHE = {"version": None, "exact": (), "regex": (), "memo": {}}
 
 # Per-version cap on the find_matching_rule memo. A long-lived worker that sees many distinct
@@ -35,6 +38,13 @@ _RULE_CACHE = {"version": None, "exact": (), "regex": (), "memo": {}}
 # of contexts in any single module-sync render, so it never churns mid-render.
 _MEMO_MAX = 4096
 
+# Sentinel for the memo read. A single ``memo.get(sig, _MEMO_MISS)`` is one atomic dict lookup, so a
+# concurrent ``memo.clear()`` at the cap can't wedge between a membership test and the subscript the
+# way ``if sig in memo: return memo[sig]`` could — that compound read can raise a sporadic KeyError
+# under threaded workers sharing one per-version memo. A real "no rule matched" is memoized as None,
+# so the miss sentinel must be a distinct object, not None.
+_MEMO_MISS = object()
+
 # Per-thread pin depth (see pinned_rule_cache). While > 0 on the current thread, _get_enabled_rules
 # trusts the loaded set without re-reading the fingerprint, so an internal batch that wraps its loop
 # turns N per-call fingerprint queries into one. Thread-local so concurrent requests don't affect
@@ -198,6 +208,8 @@ def _get_enabled_rules():
     lookup in the block) the fingerprint query is skipped and the snapshot captured at prime time is
     returned — never the live ``_RULE_CACHE``, which another thread may reload mid-block.
     """
+    global _RULE_CACHE
+
     pinned = getattr(_pin, "depth", 0) > 0
     if pinned and getattr(_pin, "primed", False):
         # Serve the snapshot captured when this block primed, not the shared cache: a concurrent
@@ -207,27 +219,36 @@ def _get_enabled_rules():
 
     from .models import InterfaceNameRule
 
+    # Read the module global exactly once. A reload below publishes the new set by rebinding
+    # _RULE_CACHE to a brand-new dict (a single atomic name assignment) rather than mutating this
+    # one in place, so this local is a consistent snapshot: exact/regex/memo can never be torn
+    # across two rule-set versions even if another thread reloads between the reads at the end.
+    cache = _RULE_CACHE
     version = _enabled_rules_version()
-    if _RULE_CACHE["version"] != version:
+    if cache["version"] != version:
         rules = list(InterfaceNameRule.objects.filter(enabled=True).order_by("module_type__model", "pk"))
-        _RULE_CACHE["exact"] = tuple(r for r in rules if not r.module_type_is_regex)
+        exact = tuple(r for r in rules if not r.module_type_is_regex)
         regex_rules = sorted(
             (r for r in rules if r.module_type_is_regex),
             key=lambda r: (-len(r.module_type_pattern or ""), r.pk),
         )
-        _RULE_CACHE["regex"] = tuple((_compile_pattern(r.module_type_pattern), r) for r in regex_rules)
-        _RULE_CACHE["memo"] = {}
-        _RULE_CACHE["version"] = version
+        regex = tuple((_compile_pattern(r.module_type_pattern), r) for r in regex_rules)
+        # Publish the whole new version atomically: a reader either sees the old dict or this one,
+        # never a mix of the two. Last writer wins; a concurrent reload to the same version just
+        # rebuilds redundantly, never corrupts.
+        cache = {"version": version, "exact": exact, "regex": regex, "memo": {}}
+        _RULE_CACHE = cache
     if pinned:
         # Pin this thread to the freshly-resolved set for the rest of the block. The tuples are
-        # immutable and the memo dict is now this thread's own reference, so a later global reload
-        # leaves our snapshot — and the entries we memoize into it — untouched.
-        _pin.exact = _RULE_CACHE["exact"]
-        _pin.regex = _RULE_CACHE["regex"]
-        _pin.memo = _RULE_CACHE["memo"]
+        # immutable and the memo is COPIED into thread-local state — not aliased — so the pinned batch
+        # neither shares nor races the global memo: another thread clearing the shared memo at the cap
+        # can't evict our warmed entries (or wedge a KeyError) mid-loop, and entries we add stay private.
+        _pin.exact = cache["exact"]
+        _pin.regex = cache["regex"]
+        _pin.memo = dict(cache["memo"])
         _pin.primed = True
         return _pin.exact, _pin.regex, _pin.memo
-    return _RULE_CACHE["exact"], _RULE_CACHE["regex"], _RULE_CACHE["memo"]
+    return cache["exact"], cache["regex"], cache["memo"]
 
 
 def _get_parent_module_type(module_bay):
@@ -675,8 +696,11 @@ def find_matching_rule(module_type, parent_module_type, device_type, platform=No
     # The regex tier matches against module_type.model (a live string), so the memo must key on
     # it too — otherwise a ModuleType.model rename (same pk) would return a stale regex result.
     sig = (module_type.pk, module_type.model, *_scope_ids(parent_module_type, device_type, platform))
-    if sig in memo:
-        return memo[sig]
+    # One atomic lookup, not `if sig in memo: return memo[sig]`: another thread sharing this per-version
+    # memo can clear it at the cap between a membership test and the subscript, raising KeyError.
+    cached = memo.get(sig, _MEMO_MISS)
+    if cached is not _MEMO_MISS:
+        return cached
 
     candidates = _build_candidates(parent_module_type, device_type, platform)
     result = _find_exact_match(module_type, candidates, exact_rules) or _find_regex_match(

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/netbox_interface_name_rules/tests/test_misc.py

@@ -801,3 +801,22 @@ class ModelCSVExportTest(TestCase):
         """csv_headers must not contain dots (regression guard for KeyError 'Ch' bug)."""
         for header in InterfaceNameRule.csv_headers:
             self.assertNotIn(".", header, f"csv_headers entry '{header}' contains a dot — would break import")
+
+
+# ---------------------------------------------------------------------------
+# __init__.py — PluginConfig version gate (must match the documented floor)
+# ---------------------------------------------------------------------------
+
+
+class PluginConfigVersionTest(TestCase):
+    """The enforced min_version gate must match the compatibility floor stated in the docs."""
+
+    def test_min_version_matches_documented_floor(self):
+        """min_version is the gate NetBox uses to refuse loading the plugin, so it must equal the
+        floor advertised in README.md / docs/installation.md (NetBox >= 4.3.0). A drift here would
+        let an unsupported NetBox load the plugin (or reject a supported one) with no other guard —
+        the inconsistency a reviewer flagged when the docs were raised to 4.3.0 but the gate stayed 4.2.0.
+        """
+        from netbox_interface_name_rules import InterfaceNameRulesConfig
+
+        self.assertEqual(InterfaceNameRulesConfig.min_version, "4.3.0")

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/netbox_interface_name_rules/tests/test_rules.py

@@ -485,10 +485,25 @@ class FindMatchingRuleCachingTest(TestCase):
                 ModuleType.objects.create(manufacturer=mfr, model=f"MEMO-{i}", part_number=f"MEMO-{i}")
                 for i in range(5)
             ]
-            for mt in module_types:  # five distinct contexts → five distinct memo keys
+            for i, mt in enumerate(module_types, start=1):  # five distinct contexts → five distinct memo keys
                 find_matching_rule(mt, None, None)
-
-            self.assertLessEqual(len(engine._RULE_CACHE["memo"]), engine._MEMO_MAX)
+                # Check the bound after EVERY insert, not just once at the end. The memo size must never
+                # exceed the cap at any point. A regression that let it leak toward 2*cap before clearing
+                # would slip past an end-of-loop `<=` snapshot (which only sees the post-clear size) but
+                # trips here on the very insert that crosses the cap.
+                self.assertLessEqual(
+                    len(engine._RULE_CACHE["memo"]),
+                    engine._MEMO_MAX,
+                    f"memo exceeded the cap mid-insertion after {i} contexts",
+                )
+
+            # And the eviction actually fired: the final size is below the number of distinct contexts,
+            # so the test isn't vacuously green on a memo that simply never reached the cap.
+            self.assertLess(
+                len(engine._RULE_CACHE["memo"]),
+                len(module_types),
+                "memo never evicted — the cap was never exercised",
+            )
         finally:
             engine._MEMO_MAX = original_max
 
@@ -533,32 +548,141 @@ class FindMatchingRuleCachingTest(TestCase):
         self.assertEqual(find_matching_rule(self.module_type, None, self.device_type), specific)
 
     def test_pinned_block_holds_snapshot_across_concurrent_cache_reload(self):
-        """A pinned batch keeps its rule-set snapshot even if another thread reloads the shared cache.
+        """A pinned batch keeps its rule-set snapshot even when a real second thread reloads the cache.
 
         The pin must capture exact/regex/memo at prime time; if it re-read the live module-level
         _RULE_CACHE, a concurrent request reloading it mid-block would silently switch this batch to a
-        different rule set — renaming one device's modules with mixed rule versions.
+        different rule set — renaming one device's modules with mixed rule versions. This exercises the
+        guarantee across an actual thread: the worker must NOT inherit this thread's pin (``_pin`` is
+        ``threading.local``), and its reload — published the way ``_get_enabled_rules`` does, by
+        rebinding ``_RULE_CACHE`` to a fresh dict — must leave our primed snapshot untouched. A plain
+        global ``_pin`` would leak the pin into the worker and pass the old same-thread test, but fail here.
         """
+        import threading
+
         from netbox_interface_name_rules import engine
         from netbox_interface_name_rules.engine import pinned_rule_cache
 
         universal = InterfaceNameRule.objects.create(module_type=self.module_type, name_template="a{bay_position}")
 
+        worker_pin_depth = []
+
+        def concurrent_reload():
+            # A genuine second thread. _pin is thread-local, so this worker must see depth 0 — it never
+            # inherits the main thread's active pin. It then publishes a different rule-set version the
+            # way _get_enabled_rules() does: one atomic rebind of the module global. (No DB access — a
+            # separate thread has its own connection and cannot see this TestCase's uncommitted rows.)
+            worker_pin_depth.append(getattr(engine._pin, "depth", 0))
+            engine._RULE_CACHE = {"version": "concurrent-reload-other-version", "exact": (), "regex": (), "memo": {}}
+
+        try:
+            with pinned_rule_cache():
+                self.assertEqual(find_matching_rule(self.module_type, None, self.device_type), universal)  # primes
+
+                worker = threading.Thread(target=concurrent_reload)
+                worker.start()
+                worker.join()
+
+                # The worker did not inherit our pin — proves _pin is per-thread, not a shared global.
+                self.assertEqual(worker_pin_depth, [0], "pin leaked across threads — _pin is not thread-local")
+                # ...and its reload really did replace the shared cache.
+                self.assertEqual(engine._RULE_CACHE["version"], "concurrent-reload-other-version")
+
+                # Still inside the pin: must serve the snapshot captured at entry, not the worker's reload.
+                self.assertEqual(
+                    find_matching_rule(self.module_type, None, self.device_type),
+                    universal,
+                    "pinned block switched rule sets after a concurrent _RULE_CACHE reload",
+                )
+        finally:
+            # This test deliberately rebinds the module global from another thread; restore a clean
+            # sentinel so the simulated reload can't leak into sibling tests even if setUp() is weakened.
+            engine._RULE_CACHE = {"version": None, "exact": (), "regex": (), "memo": {}}
+
+    def test_reload_publishes_a_fresh_cache_dict_atomically(self):
+        """A version change rebinds _RULE_CACHE to a new dict instead of mutating the old one in place.
+
+        This is what makes the unpinned three-key read a consistent snapshot: a reader that grabbed the
+        cache before a concurrent reload keeps one whole rule-set version, never exact from V1 paired
+        with memo from V2. We assert the published dict is a *new object* and that a reference captured
+        before the reload is left untouched — the in-place mutation the previous code did would fail both.
+        """
+        from netbox_interface_name_rules import engine
+
+        InterfaceNameRule.objects.create(module_type=self.module_type, name_template="a{bay_position}")
+        find_matching_rule(self.module_type, None, self.device_type)  # prime version 1
+
+        snap = engine._RULE_CACHE
+        snap_version = snap["version"]
+        snap_exact = snap["exact"]
+
+        # Change the rule set so the next lookup must reload to a new version.
+        InterfaceNameRule.objects.create(
+            module_type=self.module_type, device_type=self.device_type, name_template="b{bay_position}"
+        )
+        find_matching_rule(self.module_type, None, self.device_type)  # reload to version 2
+
+        self.assertIsNot(
+            engine._RULE_CACHE, snap, "reload mutated the cache dict in place instead of publishing a new one"
+        )
+        self.assertEqual(snap["version"], snap_version, "a reload mutated a previously-published cache dict")
+        self.assertEqual(snap["exact"], snap_exact, "the captured exact snapshot changed under a concurrent reload")
+
+    def test_find_matching_rule_survives_concurrent_memo_clear(self):
+        """A memo cleared between the membership check and the lookup must not raise KeyError.
+
+        Threaded workers share one per-version memo dict; if one thread clears it at the cap while
+        another is mid-read, the old ``if sig in memo: return memo[sig]`` raised KeyError because the
+        membership test and the subscript are two operations with a thread switch possible between them.
+        We reproduce that exact interleave deterministically with a dict whose membership test clears
+        itself, then assert find_matching_rule still returns the rule. The sentinel ``.get()`` read is a
+        single atomic lookup, so it never performs the separate membership test the race needs.
+        """
+        from netbox_interface_name_rules import engine
+
+        rule = InterfaceNameRule.objects.create(module_type=self.module_type, name_template="p{bay_position}")
+        self.assertEqual(find_matching_rule(self.module_type, None, self.device_type), rule)  # warm the memo
+
+        class _RacingMemo(dict):
+            # Emulate another thread clearing the shared memo the instant a membership test sees the key.
+            def __contains__(self, key):
+                present = super().__contains__(key)
+                if present:
+                    self.clear()
+                return present
+
+        # Same version → no reload; the racing memo is what find_matching_rule reads next.
+        engine._RULE_CACHE["memo"] = _RacingMemo(engine._RULE_CACHE["memo"])
+
+        self.assertEqual(
+            find_matching_rule(self.module_type, None, self.device_type),
+            rule,
+            "find_matching_rule raised/missed when the shared memo was cleared mid-read",
+        )
+
+    def test_pinned_block_uses_a_private_memo_copy(self):
+        """A pinned batch gets its own memo copy, so another thread clearing the shared memo can't
+        evict the batch's warmed entries (or wedge a KeyError) mid-loop."""
+        from netbox_interface_name_rules import engine
+        from netbox_interface_name_rules.engine import pinned_rule_cache
+
+        rule = InterfaceNameRule.objects.create(module_type=self.module_type, name_template="p{bay_position}")
+
         with pinned_rule_cache():
-            self.assertEqual(find_matching_rule(self.module_type, None, self.device_type), universal)  # primes
+            find_matching_rule(self.module_type, None, self.device_type)  # primes + memoizes into the copy
 
-            # Simulate a concurrent request on another thread reloading _RULE_CACHE to a different
-            # version mid-block — exactly what _get_enabled_rules() does on a version change.
-            engine._RULE_CACHE["version"] = "concurrent-reload-other-version"
-            engine._RULE_CACHE["exact"] = ()
-            engine._RULE_CACHE["regex"] = ()
-            engine._RULE_CACHE["memo"] = {}
+            self.assertIsNot(
+                engine._pin.memo,
+                engine._RULE_CACHE["memo"],
+                "pinned memo aliases the shared cache memo instead of holding a private copy",
+            )
 
-            # Still inside the pin: must serve the snapshot captured at entry, not the now-empty global.
+            # An unpinned thread clearing the shared memo at the cap must not disturb the pinned batch.
+            engine._RULE_CACHE["memo"].clear()
             self.assertEqual(
                 find_matching_rule(self.module_type, None, self.device_type),
-                universal,
-                "pinned block switched rule sets after a concurrent _RULE_CACHE reload",
+                rule,
+                "pinned lookup was disturbed by a clear of the shared memo",
             )
 
     def test_fingerprint_resists_separator_injection_in_text_fields(self):
@@ -599,3 +723,44 @@ class FindMatchingRuleCachingTest(TestCase):
             fp_forged_one_rule,
             "distinct rule sets collided — a text-field separator forged a row boundary in the fingerprint",
         )
+
+
+class EnabledRuleFingerprintColumnsTest(TestCase):
+    """_VERSION_COLUMNS must stay exhaustive over the model's match-affecting columns."""
+
+    def test_version_columns_account_for_every_concrete_column(self):
+        """Every concrete InterfaceNameRule column must be fingerprinted or deliberately excluded.
+
+        The enabled-rule fingerprint (engine._enabled_rules_version) hashes exactly
+        engine._VERSION_COLUMNS. If a future field that affects matching is added to the model but not
+        to that hand-maintained tuple, edits to it won't change the fingerprint and find_matching_rule
+        will keep serving a stale cached rule. This guard fails the moment a new concrete column appears
+        that hasn't been consciously classified — forcing the author to either add it to _VERSION_COLUMNS
+        (so the cache invalidates on its edits) or list it below with a reason it can't affect a match.
+        """
+        from netbox_interface_name_rules import engine
+        from netbox_interface_name_rules.models import InterfaceNameRule
+
+        # Columns intentionally NOT in the fingerprint, each with the reason it cannot change a match:
+        excluded = {
+            # the fingerprint's own filter predicate (filter(enabled=True)) — toggling it adds/removes
+            # the row from the aggregate, so the hash already changes; it must not also be a column
+            "enabled",
+            "description",  # operator notes; never consulted by the engine
+            "created",  # audit timestamp
+            "last_updated",  # audit timestamp
+            "custom_field_data",  # NetBox custom fields; not part of rule matching
+        }
+        concrete_columns = {
+            f.column
+            for f in InterfaceNameRule._meta.get_fields()
+            if getattr(f, "concrete", False) and not f.many_to_many and f.column
+        }
+        classified = set(engine._VERSION_COLUMNS) | excluded
+        self.assertEqual(
+            concrete_columns,
+            classified,
+            "InterfaceNameRule has concrete columns that are neither fingerprinted nor excluded. "
+            "Classify each: add match-affecting columns to engine._VERSION_COLUMNS so the rule cache "
+            "invalidates when they change, or add audit/notes columns to this test's `excluded` set.",
+        )

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/netbox_interface_name_rules.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-interface-name-rules
-Version: 1.4.2
+Version: 1.4.3
 Summary: NetBox plugin for automatic interface renaming when modules are installed
 Author: Marcin Zieba
 License-Expression: Apache-2.0

{netbox_interface_name_rules-1.4.2 → netbox_interface_name_rules-1.4.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "netbox-interface-name-rules"
-version = "1.4.2"
+version = "1.4.3"
 description = "NetBox plugin for automatic interface renaming when modules are installed"
 readme = "README.md"
 requires-python = ">=3.12.0"