/**
 * @file modules.hpp
 * @brief Module handle, cursor, and loader declarations
 *
 * @copyright Copyright (c) 2026 SILO GROUP LLC
 * @author Chris Punches <chris.punches@silogroup.org>
 *
 * Part of the Dark Horse Linux Package Manager (DPM)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
#pragma once

#include <dpm/core.h>

#include <memory>
#include <string>
#include <vector>

/** @brief A loaded, fully validated module */
struct dpm_module {
    /** Module name, its filename minus .so. */
    std::string name;

    /** The dlopen handle. */
    void* handle = nullptr;

    /** dpm_module_version() as read at load. */
    std::string version;

    /** dpm_module_description() as read at load. */
    std::string description;

    /** dpm_module_aliases() as read at load; empty when it returned NULL. */
    std::string aliases;

    /** Resolved dpm_module_execute; the only path into module code. */
    int (*execute)(dpm_ctx*, const char*, int, char**) = nullptr;
};

/** @brief Enumeration cursor over validated modules */
struct dpm_cursor {
    /** One entry per valid module. */
    std::vector<dpm_module_info> infos;

    /** Position of the next entry. */
    size_t idx = 0;
};

/**
 * @brief Closes a dlopen handle
 *
 * Keeps handle release beside the loader in one translation unit.
 *
 * @param handle The handle to close; NULL is a no-op
 */
void dpm_internal_unload(void* handle);

namespace dpm_core {
    /**
     * @brief Runs the full load-time validation sequence against a module
     *
     * Loads the named module's .so from the context's module path and
     * verifies the complete contract.
     *
     * @param ctx The libdpm-core.so context
     * @param name The module name
     * @param reason Receives the refusal reason on failure
     * @return The validated module (caller owns), or nullptr on failure
     */
    std::unique_ptr<dpm_module> validate_and_load(dpm_ctx* ctx,
                                                  const std::string& name,
                                                  std::string& reason);
} // namespace dpm_core