Add RestSend framework, enums, and shared unit test infrastructure

[allenrobel]

Summary

Adds the RestSend HTTP request framework, enums.py, and the shared unit test infrastructure for the ND collection. This PR is one of two companion PRs targeting nd42_integration:

• This PR nd42_rest_send — RestSend framework, enums.py, and all shared test infrastructure (merge first)
• Add Log class and logging config #184 nd42_logging — Log class, logging config, and test_log.py

Note: Imports of Log (log.py) will show as broken until nd42_logging (#184) is merged into nd42_integration. The unit tests in this PR also have a dependency on log.py (via common_utils) and will not run until both branches are merged.

---

TODO

1. 2026-02-03 - Add unit tests for sender_file.py as well.

Plugin files added

File	Description
plugins/module_utils/enums.py	HttpVerbEnum and OperationType enums — required by RestSend, Results, ResponseHandler, and Sender
plugins/module_utils/rest_send.py	RestSend — orchestrates HTTP requests via a pluggable Sender, with retries, timeout, and unit-test mode
plugins/module_utils/results.py	Results — tracks changed/failed state and diff output across a task's lifetime
plugins/module_utils/protocol_response_handler.py	ResponseHandlerProtocol — structural protocol for response handler implementations
plugins/module_utils/response_handler_nd.py	ResponseHandler — ND-specific response handler; normalises HTTP status codes and extracts error messages
plugins/module_utils/protocol_sender.py	SenderProtocol — structural protocol for sender implementations
plugins/module_utils/sender_nd.py	Sender — ND-specific sender using Ansible's httpapi connection plugin
plugins/module_utils/pydantic_compat.py	Pydantic v1/v2 compatibility shim used by Results
plugins/module_utils/protocol_response_validation.py	ResponseValidationStrategy protocol for version-specific ND API response validation
plugins/module_utils/response_validation_nd_v1.py	ND API v1 implementation of ResponseValidationStrategy

Shared unit test infrastructure added

File	Description
plugins/module_utils/enums.py	(see above)
tests/unit/__init__.py	Package marker
tests/unit/module_utils/__init__.py	Package marker
tests/unit/module_utils/common_utils.py	does_not_raise() and other shared test helpers
tests/unit/module_utils/fixtures/load_fixture.py	JSON fixture loader
tests/unit/module_utils/mock_ansible_module.py	Lightweight AnsibleModule mock
tests/unit/module_utils/response_generator.py	Generator-based mock response sequencer
tests/unit/module_utils/sender_file.py	File-based Sender for replaying canned HTTP responses in tests

Unit tests added

File	Tests
tests/unit/module_utils/test_rest_send.py	RestSend class
tests/unit/module_utils/test_response_handler_nd.py	ResponseHandler class
tests/unit/module_utils/test_sender_nd.py	Sender class
tests/unit/module_utils/fixtures/fixture_data/test_rest_send.json	Canned HTTP responses for RestSend tests

Merge order

1. Merge this PR → nd42_integration (provides enums.py and shared test infrastructure needed by nd42_logging)
2. Merge nd42_logging (Add Log class and logging config #184) → nd42_integration

Test plan

• After merging both PRs into nd42_integration: python -m pytest tests/unit/module_utils/ passes cleanly
• tox -e linters passes (black, isort, pylint, mypy)
• ansible-test sanity --docker passes

🤖 Generated with Claude Code

[lhercot]

I don't think we need those anymore if we only support 3.10+ anyway?

[lhercot]

As we discussed yesterday I would adapt this to raise an exception and not use module / fail_json in here specifically so we keep it all in the module itself.

Is there a clever way for us to know this is executed from main() and just raised the exception without forcing it to call this method in every module main()?

[allenrobel]

Hi @lhercot , there's no clever solution here that reduces total boilerplate, rather just one that distributes it differently. The current approach is pragmatic for Ansible. The module parameter is a mild coupling but it gives us missing_required_lib's installation instructions, the traceback, and proper exit formatting for free.

There may be a way to use a @requires_pydantic decorator on main(), which would cleaner than an explicit call, but would require main() to accept an instantiated ansible_module as an argument, which isn't really standard Ansible practice (I'm not sure this would even work). Can we explore this in a separate PR (in the interest of time)?

  import functools

  def requires_pydantic(func):
      """Decorator for module main() functions that require pydantic."""
      @functools.wraps(func)
      def wrapper(module, *args, **kwargs):
          if not HAS_PYDANTIC:
              from ansible.module_utils.basic import missing_required_lib
              module.fail_json(msg=missing_required_lib("pydantic"), exception=PYDANTIC_IMPORT_ERROR)
          return func(module, *args, **kwargs)
      return wrapper

  Then in each module:

  from ansible_collections.cisco.nd.plugins.module_utils.common.pydantic_compat import requires_pydantic

  @requires_pydantic
  def main(module):
      # pydantic is guaranteed available here
      ...

[lhercot]

I think we need to expand the signature here to support analyzing the whole response for success.
We have had cases where the API returns a 200 or other "successful" code but the answer contains an error message or code.

[mikewiebe]

This is a good call but I think we have what we need for that in def extract_error_message below?

[allenrobel]

@mikewiebe I think @lhercot is right here. While extract_error_message does do what it says on the tin, it's not actually integrated into the determination of success. Callers would need to reference extract_error_message separately, which is fragile.

Addressed with commit: d22f1e7

This also removes ad hoc handling in ResponseHandler, making NdV1Strategy the single authority determining success/failure.

[lhercot]

shouldn't this be plural if it returns a list?

[allenrobel]

IIRC, my thinking at the time (couple years ago) was that there is a single list, hence result -> singular. But, I can change this if you feel strongly. Would be a breaking change for any existing modules in progress, but better to address now rather than later if plural makes more sense here. Let me know.

[lhercot]

Shouldn't we also put this data in the _tasks data so we have a consistent view of all data irrespective if they come from Task or from Legacy use of _response_data?

[allenrobel]

This seems to contradict the previous comment to deprecate add_response_data (which I just committed).

Two options then:

1. Deprecate and remove — keep the deprecation notices we just added, and callers should migrate to using register_api_call() to store response data in _tasks.
2. Integrate into _tasks — remove the deprecation notices and instead have add_response_data() also store data in the task pipeline, giving a unified view.

Option 1 seems cleaner architecturally — _response_data is a parallel data path that bypasses the Pydantic-validated _tasks lifecycle. Rather than bridging two systems, it's simpler to migrate callers to the standard path.

What was the use-case you envisioned for add_response_data assuming you don't want to deprecate it?

[mikewiebe]

LGTM

[mikewiebe]

LGTM