Object File Fetch Module

Relevant source files

The following files were used as context for generating this wiki page:

• plugins/modules/object_file_fetch.py
• plugins/action/object_file_fetch.py
• dev/guides/creating-a-module.md
• dev/constitution.md
• dev/knowledge/plugin-patterns.md
• plugins/AGENTS.md

The Object File Fetch module downloads binary file content from a CoreFileObject node in the Infrahub platform. It identifies specific nodes using either a Unique Universal Identifier (UUID) or a Human-Friendly ID (HFID) and returns base64-encoded binary content alongside file metadata.

This module follows the Action Plugin Pattern where the module file serves as a stub for documentation and argument validation, while the execution logic resides in a corresponding action plugin that runs on the Ansible controller.
Sources: plugins/modules/object_file_fetch.py:12-20, dev/guides/creating-a-module.md:12-16, dev/constitution.md:43-47

Architecture and Design

The module implements a controller-side execution model to handle Infrahub API calls directly through an action plugin.

Action Plugin Pattern

The system splits functionality between two files:

1. Module Stub: Located in plugins/modules/object_file_fetch.py, it contains the DOCUMENTATION, EXAMPLES, and RETURN YAML strings. It uses AnsibleModule to validate parameters but does not execute logic.
2. Action Plugin: Located in plugins/action/object_file_fetch.py, it inherits from ActionBase and contains the ActionModule class. It manages credentials, initializes the SDK wrapper, and performs the actual file download.

Sources: dev/constitution.md:45-47, dev/guides/creating-a-module.md:21-25, plugins/modules/object_file_fetch.py:136-150

Execution Flow

The following diagram illustrates the data flow from the Ansible task to the Infrahub API:

The Action Plugin manages controller-side API calls and is used for operations that are read-only or cannot be made idempotent.
Sources: dev/constitution.md:45-48, plugins/AGENTS.md:32-34, dev/guides/creating-a-module.md:92-108

Configuration and Parameters

The module requires specific parameters to locate nodes and manage connection security.

Module Options

Parameter	Type	Required	Default	Description
kind	str	Yes	-	Schema kind inheriting from CoreFileObject.
node_id	str	No	-	UUID of the node to fetch.
hfid	list	No	-	Human-friendly ID component values.
dest	str	No	null	Local path to save the file.
api_endpoint	str	No	-	Infrahub API endpoint (Env: INFRAHUB_ADDRESS).
token	str	No	-	API token (Env: INFRAHUB_API_TOKEN).
branch	str	No	main	Branch name for the request.
validate_certs	bool	No	True	Whether to validate SSL certificates.

Sources: plugins/modules/object_file_fetch.py:25-69, dev/constitution.md:73-77

Argument Validation Logic

The module stub enforces that you provide exactly one of node_id or hfid.

    AnsibleModule(
        argument_spec=argument_spec,
        required_one_of=[("node_id", "hfid")],
        supports_check_mode=False,
    )

Sources: plugins/modules/object_file_fetch.py:146-150

Return Values

Regardless of whether you provide a dest path, the module returns the file content and associated metadata.

Key	Type	Description
binary	str	Base64-encoded file content.
text	str	UTF-8 decoded content for text MIME types; null for binary.
file_name	str	Original filename stored in Infrahub.
file_type	str	MIME type detected by Infrahub.
file_size	int	Size of the file in bytes.
checksum	str	SHA-1 hex digest of the file content.
dest	str	The resolved local path where the file was saved.

Sources: plugins/modules/object_file_fetch.py:98-132

Implementation Standards

SDK Abstraction

The module must not call InfrahubClientSync directly. Instead, it utilizes InfrahubclientWrapper for all API interactions. This ensures consistent exception handling and environment variable fallback for credentials.
Sources: dev/constitution.md:65-72, plugins/AGENTS.md:52-54

Conditional Imports

All plugin files must guard SDK imports to allow ansible-doc to parse the file even if the SDK is missing.

try:
    from infrahub_sdk import InfrahubClientSync
    HAS_INFRAHUBCLIENT = True
except ImportError:
    HAS_INFRAHUBCLIENT = False

The Action Plugin checks HAS_INFRAHUBCLIENT at runtime and raises an AnsibleError if the SDK is not installed.
Sources: dev/knowledge/plugin-patterns.md:126-140, dev/constitution.md:68-70

Security and Compatibility

• Boilerplate: Every file includes __metaclass__ = type and from __future__ imports for compatibility.
• no_log: The token parameter is marked no_log=True to prevent sensitive credentials from appearing in logs.
• Synchronous Only: The module only uses synchronous SDK methods; async methods are prohibited.

Sources: dev/constitution.md:16-20, dev/constitution.md:78, dev/constitution.md:103

Summary

The Object File Fetch Module provides a controlled interface for retrieving binary assets from Infrahub. By utilizing the Action Plugin pattern, it centralizes API logic on the controller while providing a standard Ansible interface for node selection and file persistence. It adheres to strict collection standards regarding SDK abstraction, parameter validation, and security.
Sources: plugins/modules/object_file_fetch.py:12-20, dev/constitution.md:43-50