interface capability preflight (#273)

[allenrobel]

Related Issue(s)

Closes #273, #300, #301, #302

Proposed Changes

Pre-flights ND's unpublished /api/v1/manage/fabrics/{fabric}/capableSwitches endpoint before per-switch configuration calls, converting confusing HTTP 400s on incapable switches into a single aggregate error that names the offending switches.

• Endpoint model EpManageFabricsCapableSwitchesGet, inheriting _EpManageFabricsBase for path construction, with required interfaceType / mode query params.
• InterfaceCapabilityPreflight class (plugins/module_utils/interface_capability_preflight.py) mirroring FabricContext shape:
  • (interface_type, mode) cache (switch records + derived switch-id set); one GET per pair per task run
  • Client-side taxonomy enforcement (captured from the ND 4.2 GUI 2026-05-11) — invalid combos raise ValueError without consuming a round trip
  • Optional FabricContext injection enriches error messages with switch_ip
  • invalidate() for cache reset
  • Treats HTTP 404 from capableSwitches as a hard failure (rather than caching an empty capable set that would mislabel every requested switch); returns defensive copies from get_capable_switches / get_capable_switch_ids so callers can't corrupt cached state.
• Orchestrator wiring on NDBaseInterfaceOrchestrator:
  • interface_type / interface_mode ClassVars (both default "") — subclasses opt in by setting both to a valid taxonomy pair
  • Lazy capability_preflight property
  • validate_switches_capable(model_instances) — resolves the target switch-id set, issues a single capableSwitches GET, and raises one RuntimeError naming every incapable switch; also raises a clear RuntimeError if a subclass sets interface_type without interface_mode. Parameter typed Sequence[ModelType] so static analysis rejects generator callers (commit 0157f2f, fixes NDBaseInterfaceOrchestrator.validate_switches_capable consumes its input; bulk callers iterate it twice #300). Resolves all switch_ip values up front and aggregates unresolvable ones into a single RuntimeError so a typo on one entry no longer masks problems on the rest (commit 8835915, fixes validate_switches_capable: a single unresolvable switch_ip masks capability problems on other switches #301). In --check mode, downgrades capability-endpoint failures and capability mismatches to warnings via AnsibleModule.warn so dry-runs stay green when the unpublished endpoint is unavailable (commit 215601a, fixes Capability preflight issues a live GET in --check mode and can fail dry-runs that previously succeeded #302).
• Loopback as reference impl — interface_type = "loopback", interface_mode = "managed"; preflight invoked from create, update, create_bulk. Delete and read paths intentionally skip preflight.

Taxonomy embedded in InterfaceCapabilityPreflight docstring

interface_type	valid modes
loopback	managed
svi	managed
tunnel	managed
ethernet	trunk, access, routed, fex, pvlan, dot1qTunnel, unmanaged
portChannel	trunk, access, routed, fex, pvlan, dot1qTunnel, unmanaged

VPC uses a different endpoint (/vpcPairs?view=intendedPairs) and is handled separately (follow-up). Breakout and subinterface are out of scope (no pre-check available / absent from taxonomy).

Impact on the merged nd_interface_loopback module

nd_interface_loopback is already merged to develop, so this PR is not purely additive — it modifies files owned by that merged module to wire loopback in as the reference implementation:

• plugins/module_utils/orchestrators/loopback_interface.py — adds the interface_type / interface_mode ClassVars and the validate_switches_capable calls in create / update / create_bulk.
• tests/unit/module_utils/orchestrators/test_loopback_interface.py — each mutating test now consumes one capableSwitches GET.
• tests/unit/module_utils/fixtures/fixture_data/test_loopback_interface.json — adds the capableSwitches fixture responses.

No change to plugins/modules/nd_interface_loopback.py, the loopback model, or loopback's user-facing behavior — preflight is internal and runs ahead of the existing API calls. These three files are the "modifies already-merged code" surface for review; anyone with an in-flight branch off loopback should expect a small merge touch-point here.

Code-review follow-ups resolved in this PR

A high-effort /code-review pass on this branch surfaced three additional findings whose fixes touch files originating in develop (base_interface.py, loopback_interface.py, both from PR #220). All three are now resolved in this PR rather than deferred:

• NDBaseInterfaceOrchestrator.validate_switches_capable consumes its input; bulk callers iterate it twice #300 — Resolved (commit 0157f2f). validate_switches_capable accepted Iterable but bulk callers iterate the same parameter twice; a generator caller would have become a silent no-op. Narrowed the base-class signature to Sequence[ModelType] so mypy rejects generator callers at the boundary. The method body and all existing call sites (list[...]) are unchanged.
• validate_switches_capable: a single unresolvable switch_ip masks capability problems on other switches #301 — Resolved (commit 8835915). A single unresolvable switch_ip masked aggregate capability problems for the rest of the batch. Now resolves every switch_ip up front, collects the unresolvable ones, and raises a single aggregate RuntimeError naming every unknown IP; the capability GET only runs on the resolved subset.
• Capability preflight issues a live GET in --check mode and can fail dry-runs that previously succeeded #302 — Resolved (commit 215601a). Capability preflight issues a live GET in --check mode; a 404 (post-Add interface capability pre-flight check as a shared class #273-merge) would now fail a dry-run that previously succeeded. In --check mode, capability-endpoint failures and capability mismatches are downgraded to warnings via AnsibleModule.warn so dry-runs stay green and the information still surfaces. Unresolvable switch_ip values still raise even in check mode because they reflect user input errors.

The two in-branch findings — 404 silently cached as empty capable set, and cache returned by reference — are fixed in interface_capability_preflight.py (commit 7a130c4).

Adopting preflight in downstream interface modules

Once this lands, each new interface orchestrator (svi, ethernet access / trunk-host, port-channel, ...) opts in with no boilerplate beyond two ClassVars:

1. Inherit NDBaseInterfaceOrchestrator — already standard for interface orchestrators; nothing new.

2. Set both ClassVars to a valid taxonomy pair from the table above:

   • interface_type: ClassVar[str] = "..." (e.g. "ethernet", "portChannel", "svi")
   • interface_mode: ClassVar[str] = "..." (e.g. "access", "trunk", "routed", "managed")

   One orchestrator = one (interface_type, interface_mode) pair; per-mode variants (e.g. ethernet access vs. trunk-host) each set their own interface_mode.

3. Call validate_switches_capable(...) at the top of create, update, and create_bulk, before resolving switch IDs or building payloads — [model_instance] for the single-instance methods, the full list for create_bulk. Skip it in delete and query paths (matching loopback).

4. Nothing else to override. _resolve_mode() no longer exists — mode is the interface_mode ClassVar. If a subclass sets interface_type but omits interface_mode, validate_switches_capable raises a clear RuntimeError naming the class.

5. Opt out by leaving interface_type as "" (the base default) — for interface types with no capableSwitches coverage (breakout, subinterface).

6. VPC is separate — vpc orchestrators use a different endpoint (/vpcPairs?view=intendedPairs) and must not set these ClassVars; vpc preflight is a follow-up.

7. Tests — every mutating test gains one capableSwitches GET response immediately after the switches-list response; test_loopback_interface.json shows the fixture shape.

Test Notes

• 50 new unit tests for the preflight feature pass:
  • tests/unit/module_utils/endpoints/test_endpoints_api_v1_manage_fabric_capable_switches.py — 9 tests
  • tests/unit/module_utils/test_interface_capability_preflight.py — 35 tests (incl. 24 parametrized taxonomy cases, plus 404-failure and defensive-copy tests added in commit 7a130c4)
  • tests/unit/module_utils/orchestrators/test_base_interface.py — 6 tests covering validate_switches_capable: opted-out no-op, half-configured RuntimeError, aggregate unresolved-IP error (validate_switches_capable: a single unresolvable switch_ip masks capability problems on other switches #301), check-mode soften on endpoint failure (Capability preflight issues a live GET in --check mode and can fail dry-runs that previously succeeded #302), check-mode soften on capability mismatch (Capability preflight issues a live GET in --check mode and can fail dry-runs that previously succeeded #302), and the regression guard ensuring mismatches still raise outside check mode (Capability preflight issues a live GET in --check mode and can fail dry-runs that previously succeeded #302)
• test_loopback_interface.py updated for the new preflight GET: each mutating test (create / update / create_bulk) now consumes one capableSwitches response after the switches-list. Loopback suite green at 21/21.
• MockAnsibleModule gains a warn() method that records to self.warnings so the check-mode soften tests can assert on emitted warnings.
• Full local unit suite: 586 passed, no regressions
• ansible-test sanity --docker passes on all changed files (compile / import / pep8 / pylint / validate-modules / empty-init / yamllint / ... across Python 3.8–3.13)
• black + isort clean
• Integration smoke against the ND 4.2 lab is deferred to a follow-up — depends on having a reproducer for an incapable switch.

Cisco Nexus Dashboard Version

4.2.1

Related ND API Resource Category

• analyze
• infra
• manage
• onemanage
• other

Checklist

• Latest commit is rebased from develop with merge conflicts resolved
• New or updates to documentation has been made accordingly
• Assigned the proper reviewers

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an interface-capability “preflight” layer to the collection so interface orchestrators can query ND’s unpublished .../capableSwitches endpoint up-front and fail with a single aggregated, switch-specific error instead of scattered per-switch HTTP 400s.

Changes:

• Introduces a new endpoint model for GET /api/v1/manage/fabrics/{fabric}/capableSwitches with query params (interfaceType, mode) and unit tests.
• Adds InterfaceCapabilityPreflight (taxonomy enforcement + per-(interface_type, mode) caching + validation/error aggregation) with fixture-backed unit tests.
• Wires capability preflight into NDBaseInterfaceOrchestrator and enables it for the loopback orchestrator (create/update/create_bulk).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
plugins/module_utils/interface_capability_preflight.py	Implements cached capability lookup + taxonomy enforcement + aggregate validation errors.
plugins/module_utils/endpoints/v1/manage/manage_fabric_capable_switches.py	Adds endpoint model for the unpublished capableSwitches resource.
plugins/module_utils/orchestrators/base_interface.py	Adds orchestrator-level preflight plumbing (interface_type, lazy preflight, grouping/aggregation).
plugins/module_utils/orchestrators/loopback_interface.py	Opts loopback orchestrator into preflight and calls it on create/update/bulk create.
tests/unit/module_utils/test_interface_capability_preflight.py	Unit tests for caching, taxonomy enforcement, and validation behavior.
tests/unit/module_utils/fixtures/fixture_data/test_interface_capability_preflight.json	Fixture responses for preflight unit tests.
tests/unit/module_utils/endpoints/test_endpoints_api_v1_manage_fabric_capable_switches.py	Unit tests for new endpoint params/path behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.