fix(backend): resolve NodeNotFoundError node_type to a string

Merged
SA
4mo ago
+107-17

Why

A GraphQL request that produced a NodeNotFoundError whose node_type was a schema/protocol class (not a kind string) crashed the error formatter itself — pydantic rejected the non-str node_kind, the exception escaped the formatter, and the request returned an uncaught HTTP 500 instead of a normal NODE_NOT_FOUND (404). Observed in production as thousands of uncaught 500s.

Closes #9926

Supersedes #9952, which took a different approach: widening NodeNotFoundError.node_type to accept a class plus a defensive str() guard in the formatter. This PR instead fixes the two raise sites at the source and keeps the exception's str contract.

What changed

Behavioral: a node-not-found lookup now always returns a catalogued NODE_NOT_FOUND (404) GraphQL error, whether the internal kind was a string or a class.

Implementation:

  • NodeManager.get_one and get_one_by_id_or_default_filter resolve kind to its kind string at the raise site, so NodeNotFoundError.node_type is always a plain string (the sibling lookup methods already did this).
  • Re-enabled mypy arg-type on infrahub.core.manager so a non-str node_type is caught at type-check time; fixed the pre-existing violations it surfaced (or scoped the two genuine type-system limitations with a documented # type: ignore).
  • Documented the practice ("a wrong-type bug means a checker was suppressed — re-enable it and fix the typing chain") in dev/guidelines/backend/python.md, and tightened comment guidance in .agents/rules/code-doc-style.md.

Unchanged: NodeNotFoundError.node_type keeps its str contract (not widened to accept a class); the error formatter is untouched — the fix is at the source, not a defensive coercion.

How to review

  • Start with backend/infrahub/core/manager.py — the two raise sites.
  • pyproject.toml — one line: arg-type re-enabled for infrahub.core.manager.
  • Tests: test_manager_node.py (3 raise-site cases) and test_20_graphql.py (end-to-end 404).

How to test

uv run pytest backend/tests/component/core/test_manager_node.py -k reports_str_node_type
uv run pytest backend/tests/component/api/test_20_graphql.py -k menu_delete_missing
uv run invoke backend.lint   # arg-type now enforced on manager

Impact & rollout

Backend-only. No schema, API-contract, or migration changes.

A remaining hardening follow-up — two other modules (infrahub.core.node, infrahub.graphql.mutations.main) raise NodeNotFoundError with arg-type still disabled, both passing str today — is tracked in INBOX-1.


Summary by cubic

Fixes GraphQL requests that returned HTTP 500 when a missing node used a class kind. Missing nodes now return NODE_NOT_FOUND (404), and stricter typing prevents regressions; also fixes a fetch_peers KeyError by normalizing peer IDs.

  • Bug Fixes

    • Resolve kind to a string at raise sites in NodeManager.get_one and get_one_by_id_or_default_filter; ensure lookups pass kind strings (e.g., get_one_by_hfid).
    • Normalize peer IDs to str on both sides of fetch_peers mapping to prevent KeyError.
    • Re-enabled mypy arg-type for infrahub.core.manager; added targeted # type: ignore[...]; NodeNotFoundError.node_type stays str.
    • Tests: GraphQL CoreMenuItemDelete with a missing ID returns NODE_NOT_FOUND (404); manager errors assert string node_type. Updated backend guidelines and .agents/rules/code-doc-style.md; added changelog entry.
  • Refactors

    • Trimmed the get_one kind-normalization comment to keep only the non-obvious why.