Initial commit: DPM core library, CLI, bundled info module, and tests
This commit is contained in:
335
include/dpm/core.h
Normal file
335
include/dpm/core.h
Normal file
@@ -0,0 +1,335 @@
|
||||
/**
|
||||
* @file core.h
|
||||
* @brief Public C API for libdpm-core
|
||||
*
|
||||
* The single entry point for all DPM consumers: the dpm CLI, modules,
|
||||
* and external programs (build systems, Dark Horse tooling). All types
|
||||
* crossing this boundary are C types; state passes through opaque
|
||||
* handles; errors are int codes with per-context detail strings.
|
||||
*
|
||||
* @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/>.
|
||||
*/
|
||||
#ifndef DPM_CORE_H
|
||||
#define DPM_CORE_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Export annotation */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* Marks the public API visible. The library is compiled with hidden
|
||||
* default symbol visibility; these functions are its entire exported
|
||||
* surface.
|
||||
*/
|
||||
#ifndef DPM_API
|
||||
#define DPM_API __attribute__((visibility("default")))
|
||||
#endif
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Opaque handles */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
typedef struct dpm_ctx dpm_ctx;
|
||||
typedef struct dpm_module dpm_module;
|
||||
typedef struct dpm_cursor dpm_cursor;
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Log levels */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
enum {
|
||||
DPM_LOG_FATAL = 0,
|
||||
DPM_LOG_ERROR = 1,
|
||||
DPM_LOG_WARN = 2,
|
||||
DPM_LOG_INFO = 3,
|
||||
DPM_LOG_DEBUG = 4
|
||||
};
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Context configuration overrides */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* Overrides for dpm_open(). Any field may be left NULL (or -1 for
|
||||
* log_level) to accept configuration-file values and built-in defaults.
|
||||
* Every field here is exposed as a dpm CLI flag.
|
||||
*/
|
||||
typedef struct dpm_open_overrides {
|
||||
const char* config_dir; /* NULL = /etc/dpm/conf.d/ */
|
||||
const char* module_path; /* NULL = config value, then built-in */
|
||||
const char* root; /* NULL = "/" (target root for pkg ops) */
|
||||
int log_level; /* -1 = config value; else DPM_LOG_* */
|
||||
} dpm_open_overrides;
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Module information (enumeration results) */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
typedef struct dpm_module_info {
|
||||
const char* name; /* module name (filename minus .so) */
|
||||
const char* version; /* module's own X.Y.Z */
|
||||
const char* description; /* one-line description */
|
||||
const char* core_min; /* minimum core version it supports */
|
||||
} dpm_module_info;
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Module contract structures (layout fixed by the DPM spec) */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/** Magic constant opening every module API table. */
|
||||
#define DPM_API_TABLE_MAGIC 0x314D5044u /* "DPM1" */
|
||||
|
||||
/**
|
||||
* Every module API table begins with this header: the magic constant,
|
||||
* then the full size in bytes of the table struct as the exporting
|
||||
* module compiled it (permits tail-extension within a table version).
|
||||
*/
|
||||
typedef struct dpm_api_table_header {
|
||||
uint32_t magic;
|
||||
uint32_t size;
|
||||
} dpm_api_table_header;
|
||||
|
||||
/** One entry of a module's declared functional surface. */
|
||||
typedef struct dpm_manifest_entry {
|
||||
const char* api_name; /* e.g. "raw" */
|
||||
int table_version; /* e.g. 1 */
|
||||
const char* symbol; /* exact exported symbol carrying the
|
||||
table, e.g. "raw_api_v1" */
|
||||
} dpm_manifest_entry;
|
||||
|
||||
/** A module's manifest: its entire declared functional surface. */
|
||||
typedef struct dpm_manifest {
|
||||
uint32_t count;
|
||||
const dpm_manifest_entry* entries;
|
||||
} dpm_manifest;
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Context lifecycle */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* @brief Creates a core context
|
||||
*
|
||||
* Reads configuration from /etc/dpm/conf.d/ (or the overridden config
|
||||
* directory), resolves the module path (override > config > built-in
|
||||
* default), and initializes logging per configuration. Performs no
|
||||
* module loading. Multiple simultaneous contexts with different roots
|
||||
* are legal.
|
||||
*
|
||||
* @param overrides Optional overrides; NULL accepts configuration
|
||||
* values and built-in defaults
|
||||
* @return A context handle, or NULL on allocation failure or an
|
||||
* unreadable/invalid explicit override (a missing default
|
||||
* config directory is not an error)
|
||||
*/
|
||||
DPM_API dpm_ctx* dpm_open(const dpm_open_overrides* overrides);
|
||||
|
||||
/**
|
||||
* @brief Releases a core context
|
||||
*
|
||||
* Unloads every module handle the context issued, closes log targets,
|
||||
* and frees all memory owned by the context. All handles and strings
|
||||
* obtained through the context are invalid after this call.
|
||||
*
|
||||
* @param ctx The context to release; NULL is a no-op
|
||||
*/
|
||||
DPM_API void dpm_close(dpm_ctx* ctx);
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Module acquisition */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* @brief Loads and returns a validated module
|
||||
*
|
||||
* Resolves the named module in the module path and runs the full
|
||||
* load-time validation sequence if it is not already loaded in this
|
||||
* context. Modules are loaded at most once per context; repeated
|
||||
* calls return the same handle.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @param name The module name (its filename minus .so)
|
||||
* @param min_version Minimum acceptable module version as X.Y.Z;
|
||||
* NULL accepts any version
|
||||
* @return A module handle owned by the context, or NULL on failure
|
||||
* with the precise reason retrievable via dpm_last_error()
|
||||
*/
|
||||
DPM_API dpm_module* dpm_require(dpm_ctx* ctx, const char* name,
|
||||
const char* min_version);
|
||||
|
||||
/**
|
||||
* @brief Returns a module's API table for direct typed calls
|
||||
*
|
||||
* The table was already validated (manifest cross-check, magic,
|
||||
* minimum size) at module load. The caller casts the pointer to the
|
||||
* table struct type for that API and version. The table is valid for
|
||||
* the life of the context.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @param mod A module handle from dpm_require()
|
||||
* @param api_name The API name as declared in the module's manifest
|
||||
* @param table_version The table version to retrieve
|
||||
* @return The table pointer, or NULL if the module does not provide
|
||||
* that api/version pair
|
||||
*/
|
||||
DPM_API const void* dpm_get_api(dpm_ctx* ctx, dpm_module* mod,
|
||||
const char* api_name, int table_version);
|
||||
|
||||
/**
|
||||
* @brief Dispatches a command to a module
|
||||
*
|
||||
* Invokes the module's dpm_module_execute with the context, the
|
||||
* command, and the argument vector. argv[0] is the command when
|
||||
* argc > 0; semantics beyond that are the module's to define.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @param mod A module handle from dpm_require()
|
||||
* @param command The command name; NULL or empty behaves as the
|
||||
* module's help command
|
||||
* @param argc Number of arguments
|
||||
* @param argv Argument vector
|
||||
* @return The module's return value verbatim; 0 on success
|
||||
*/
|
||||
DPM_API int dpm_execute(dpm_ctx* ctx, dpm_module* mod, const char* command,
|
||||
int argc, char** argv);
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Enumeration */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* @brief Enumerates the valid modules in the module path
|
||||
*
|
||||
* Scans the module path and validates each candidate .so; failures
|
||||
* are logged and excluded from the results.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @return A cursor over all valid modules, or NULL on an unreadable
|
||||
* module path
|
||||
*/
|
||||
DPM_API dpm_cursor* dpm_list_modules(dpm_ctx* ctx);
|
||||
|
||||
/**
|
||||
* @brief Advances an enumeration cursor
|
||||
*
|
||||
* Fills `out` with the next module's name, version, description, and
|
||||
* minimum-core version; the string pointers remain valid until
|
||||
* context close.
|
||||
*
|
||||
* @param cur The cursor from dpm_list_modules()
|
||||
* @param out Receives the next module's information
|
||||
* @return 0 while entries remain; nonzero at end
|
||||
*/
|
||||
DPM_API int dpm_cursor_next(dpm_cursor* cur, dpm_module_info* out);
|
||||
|
||||
/**
|
||||
* @brief Releases an enumeration cursor
|
||||
*
|
||||
* @param cur The cursor to release; NULL is a no-op
|
||||
*/
|
||||
DPM_API void dpm_cursor_free(dpm_cursor* cur);
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Services (available to modules and external consumers alike) */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/**
|
||||
* @brief Returns core's own version
|
||||
*
|
||||
* @return Core's version as a static X.Y.Z string; callable without
|
||||
* a context
|
||||
*/
|
||||
DPM_API const char* dpm_core_version(void);
|
||||
|
||||
/**
|
||||
* @brief Returns a configuration value from a module's namespace
|
||||
*
|
||||
* A module's configuration namespace is its own .conf file under the
|
||||
* context's configuration directory; "core" names core's own file.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @param module The configuration namespace to read
|
||||
* @param section The section name within the file
|
||||
* @param key The key within the section
|
||||
* @return The configured value, or NULL if unset; valid until
|
||||
* context close
|
||||
*/
|
||||
DPM_API const char* dpm_config_get(dpm_ctx* ctx, const char* module,
|
||||
const char* section, const char* key);
|
||||
|
||||
/**
|
||||
* @brief Writes a message to the context's configured log targets
|
||||
*
|
||||
* Targets are the console and, when configured, the log file.
|
||||
* Messages above the configured level are dropped.
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @param level The severity (DPM_LOG_FATAL through DPM_LOG_DEBUG)
|
||||
* @param message The message to log; NULL is a no-op
|
||||
*/
|
||||
DPM_API void dpm_log(dpm_ctx* ctx, int level, const char* message);
|
||||
|
||||
/**
|
||||
* @brief Returns the resolved module directory path
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @return The module directory path this context resolved
|
||||
*/
|
||||
DPM_API const char* dpm_module_path(dpm_ctx* ctx);
|
||||
|
||||
/**
|
||||
* @brief Returns the most recent failure recorded on the context
|
||||
*
|
||||
* @param ctx The core context
|
||||
* @return A human-readable description of the most recent failure, or
|
||||
* NULL if none; overwritten by the next failing call
|
||||
*/
|
||||
DPM_API const char* dpm_last_error(dpm_ctx* ctx);
|
||||
|
||||
/* ------------------------------------------------------------------ */
|
||||
/* Module contract (implemented by modules, called by core) */
|
||||
/* ------------------------------------------------------------------ */
|
||||
|
||||
/*
|
||||
* Every module exports, as extern "C":
|
||||
*
|
||||
* int dpm_module_execute(dpm_ctx* ctx, const char* command,
|
||||
* int argc, char** argv);
|
||||
* const char* dpm_module_version(void);
|
||||
* const char* dpm_module_description(void);
|
||||
* const char* dpm_module_core_min(void);
|
||||
* const dpm_manifest* dpm_module_manifest(void);
|
||||
*
|
||||
* plus one exported table symbol per manifest entry. Core refuses to
|
||||
* load any module that does not validate completely (see the DPM
|
||||
* specification: load-time enforcement).
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* DPM_CORE_H */
|
||||
Reference in New Issue
Block a user
