Resource.hpp

1. Overview

The Resource.hpp header defines an inline utility function, resource(), used to resolve and locate application data resources within BastionGuard. It implements a prioritized lookup mechanism that searches for resource files across environment-defined paths, system installation directories, and user-local data directories.

Functionally, this module provides:

  • A centralized mechanism for resolving data file paths
  • Support for environment-based overrides
  • Fallback handling for system and user installations
  • Basic diagnostics when resources are missing
  • A consistent abstraction for resource access across the application

2. Dependencies and Includes

#include <string>
#include <filesystem>
#include <iostream>
#include <cstdlib>
  • <string> – string manipulation and path construction
  • <filesystem> – filesystem existence checks
  • <iostream> – diagnostic output for missing resources
  • <cstdlib> – access to environment variables

3. Configuration Macros

#ifndef DATA_DIR
#define DATA_DIR "/usr/share/BastionGuard/data"
#endif

The DATA_DIR macro defines the default system-wide data directory used when BastionGuard is installed in standard locations. It may be overridden at compile time to support custom packaging or deployment environments.

4. Public Interface

4.1 Resource Lookup Function

inline std::string resource(const std::string& rel);

Resolves the absolute path of a resource given its relative path inside the BastionGuard data hierarchy. The function performs a prioritized search and returns the first matching path.

  • rel – relative path of the requested resource
  • Return value – resolved filesystem path (may be a fallback)

5. Lookup Resolution Strategy

The resource() function follows a multi-step resolution strategy. Each step is executed in order, and the first valid path is returned.

5.1 Environment Override (Highest Priority)

BastionGuard_DATA

If the environment variable BastionGuard_DATA is defined, the function prepends this directory to the requested relative path and checks for existence. This allows developers, testers, and system administrators to override the default data location without recompiling.

5.2 System Installation Path

DATA_DIR / rel

If no environment override is found, the function checks the system-wide installation directory defined by DATA_DIR. This is the typical location for packaged deployments.

5.3 User Data Directory

~/.local/share/BastionGuard/data/

As a third fallback, the function attempts to resolve resources inside the user’s local data directory. The base path is determined using:

  • XDG_DATA_HOME (if defined)
  • $HOME/.local/share (fallback)

This supports per-user overrides and local resource installations.

5.4 Missing Resource Handling

std::cerr << "⚠ Risorsa non trovata"

If no valid path is found, the function logs a warning message to standard error. This provides lightweight diagnostics for missing or misconfigured resources.

5.5 Final Fallback

return DATA_DIR / rel;

As a final safeguard, the function returns the system path constructed from DATA_DIR and rel, even if the file does not exist. This allows downstream code to attempt access and handle errors explicitly.

6. Internal State and Data Model

This module does not maintain internal state. All resolution logic is performed dynamically on each invocation using:

  • Environment variables
  • Filesystem existence checks
  • Compile-time configuration

7. Usage Context

The resource() helper is intended to be used wherever BastionGuard needs to load static or semi-static assets, such as:

  • Icons and images
  • Configuration templates
  • Policy files
  • Database or signature resources
  • Localization assets

By centralizing resource resolution, the application avoids hard-coded paths and improves portability.

8. Inline and Header-Only Design

The function is declared inline and fully implemented in the header. This provides:

  • Zero linkage overhead
  • Ease of reuse across translation units
  • Consistent behavior in all modules

As a result, no separate implementation file is required.

9. Auto-Update (Scheduled Refresh)

This component does not implement timers or scheduled updates. Resource resolution is performed on demand at call time.

10. Settings Storage

No direct settings persistence is implemented. Configuration is derived from:

  • Compile-time macro DATA_DIR
  • Runtime environment variables
  • User directory conventions

Persistent configuration of resource paths is therefore delegated to the deployment environment.

11. Filesystem Layout

A typical resource layout supported by this module may resemble:

/usr/share/BastionGuard/data/
  ├── icons/
  ├── templates/
  ├── rules/
  └── locales/

/home/user/.local/share/BastionGuard/data/
  ├── icons/
  └── overrides/

Environment overrides may point to alternative directory trees for development or testing purposes.

12. Runtime and Security Considerations

  • Path trust: environment-based overrides should only be used in trusted contexts, as they may redirect the application to unverified resources.
  • Validation: callers should validate file contents when loading critical resources to prevent tampering.
  • Error handling: returning a fallback path does not guarantee file existence; callers must handle I/O errors gracefully.
  • Information disclosure: diagnostic output should be reviewed in production environments to avoid leaking internal paths.
  • Portability: reliance on XDG and HOME variables improves cross-distro compatibility but requires consistent environment configuration.
Published on:
Last updated on: