#ifndef LOGOS_MODULE_IMPL_H #define LOGOS_MODULE_IMPL_H /* =========================================================================== * logos_module_impl.h — the COMMON module-impl C ABI. * * ONE contract for module implementations in every language: a Logos module * compiles to a cdylib exporting exactly these symbols. The C++ SDK emits * this wrapper around a universal C++ impl class; the Rust SDK emits it * around a Rust impl. The uniform generated Qt-plugin glue (and, later, a * no-Qt host) talks to the cdylib ONLY through this ABI — the glue is * identical regardless of the module's source language, which is what makes * the eventual Qt-glue removal a host swap instead of a per-language change. * * Data model mirrors the lp_* consumer ABI (logos_protocol.h): * - method args / event payloads: JSON array (UTF-8 const char*) * - results: JSON value * - bytes: the canonical {"_bytes":""} tagged form * - errors from dispatch: NULL return, or a canonical error object * {"code","message","origin"} returned as the result of a failed call * when the implementation prefers structured errors. * * Ownership: every char* RETURNED by the module is heap-allocated and the * CALLER frees it with logos_module_string_free (exported by the module so * allocator domains never mix). Every const char* passed IN is borrowed. * * Threading: the host serializes dispatch calls (one at a time) unless a * future capability negotiates otherwise. The emit callback may be invoked * from any module thread; the host marshals. * * Versioning: logos_module_get_protocol_version() returns the * logos-protocol semver the module was COMPILED against (forwarded from * LOGOS_PROTOCOL_VERSION_STRING, never minted). Hosts apply the same rule * as the metadata stamp: equal MAJOR ⇔ compatible. This runtime handshake * complements the build-time metadata stamp and is what a no-Qt host (no * Qt plugin metadata) negotiates with. * =========================================================================== */ #ifdef __cplusplus extern "C" { #endif #if defined(_WIN32) #define LOGOS_MODULE_IMPL_EXPORT __declspec(dllexport) #else #define LOGOS_MODULE_IMPL_EXPORT __attribute__((visibility("default"))) #endif /* Event-emission callback installed by the host/glue. `data_json` is a JSON * array payload, borrowed for the duration of the call. */ typedef void (*logos_module_emit_cb)(const char* event_name, const char* data_json, void* user_data); /* --------------------------------------------------------------------------- * Exported by every module cdylib (generated by the SDK of the module's * language; module authors never write these by hand). * ------------------------------------------------------------------------- */ /* Dispatch a method call. Returns the result JSON value as a heap string * (free with logos_module_string_free), or NULL when the method is unknown * or dispatch failed structurally. */ LOGOS_MODULE_IMPL_EXPORT char* logos_module_dispatch(const char* method, const char* args_json); /* The module's method/event metadata as a JSON array — same shape as * LogosProviderObject::getMethods() (entries tagged "method"/"event"). */ LOGOS_MODULE_IMPL_EXPORT char* logos_module_get_methods(void); /* Module identity/context, stamped by the host before the first dispatch: * module path, instance id, per-instance persistence path. Mirrors * LogosModuleContext / RustModuleContext. Any argument may be NULL. */ LOGOS_MODULE_IMPL_EXPORT void logos_module_set_context( const char* module_path, const char* instance_id, const char* instance_persistence_path); /* Install the host's event-emission callback. The module keeps (cb, * user_data) and invokes cb once per emitted event. Passing NULL clears it; * after the clearing call returns, the module must not invoke the old cb. */ LOGOS_MODULE_IMPL_EXPORT void logos_module_set_emit_callback( logos_module_emit_cb cb, void* user_data); /* Deliver an auth token for `module_name` (the provider-side * informModuleToken). Returns 0 on acceptance. */ LOGOS_MODULE_IMPL_EXPORT int logos_module_accept_token(const char* module_name, const char* token); /* Grant the module the privileged host services named in `services_json` (a * JSON array from the closed set lp_grant_host_services documents). Returns 0 * on acceptance; the generated implementation simply forwards to * lp_grant_host_services. * * Called by the host AFTER it has verified the module's identity, and only for * the modules its policy designates as a trust root — nothing about this ABI * decides who deserves the grant. * * It has to travel this way, and that is the subtle part: the host binary and * the module cdylib each link their own copy of logos-protocol, so each has its * own process-global grant state, exactly as each has its own TokenManager. A * grant the host records for itself is invisible to the gate the cdylib checks. * Pushing it in over this ABI — the same route the auth token above already * takes — is what puts the grant in the image whose gates it must open. */ LOGOS_MODULE_IMPL_EXPORT int logos_module_grant_host_services( const char* services_json); /* Teardown completion callback, installed by the glue before it asks the module * to unload. May be invoked from any module thread. */ typedef void (*logos_module_unload_done_cb)(void* user_data); /* Install the teardown-completion callback. Called before * logos_module_about_to_unload(); a NULL cb clears it. */ LOGOS_MODULE_IMPL_EXPORT void logos_module_set_unload_done_callback( logos_module_unload_done_cb cb, void* user_data); /* Ask the module to prepare for teardown. Returns 0 when it is already * quiescent, 1 when it has work to finish and will invoke the callback * installed above exactly once when done. * * The wait is BOUNDED by the host: returning 1 buys a grace period, not a veto. * A module that never signals delays every teardown by that period and is torn * down anyway, so the deadline is real rather than a courtesy. * * CONDITIONAL on the protocol version, which is not the same as optional at * load time. The glue emits a DIRECT call — no dlsym, no null check — so a * module generated for >= 0.5 whose backend omits the definition links cleanly * and then fails at dlopen(), on ELF, with "undefined symbol". The pair is * skippable only where the CALLER was generated below 0.5 and emitted no call. * * An earlier version of this comment argued the arrangement was safe because * "the glue is generated alongside the module". That does not follow, and the * ABI has now been broken twice on the strength of it. Being generated in the * same build makes the two agree on the protocol VERSION; it says nothing about * which SYMBOLS a given language backend's emitter writes for that version, * because each backend implements this ABI independently. Both breakages — * grant_host_services at 0.3 and this pair at 0.5 — happened at perfect version * agreement, and both were invisible on macOS (plugins link * -undefined dynamic_lookup) and fatal on Linux (nixpkgs' -Wl,-z,now binds * eagerly). * * So every backend owes a build-time check that its generated scaffold defines * everything declared here. nix/module-impl-abi.nix publishes this file's * export list as data for exactly that purpose. */ LOGOS_MODULE_IMPL_EXPORT int logos_module_about_to_unload(void); /* The logos-protocol semver this module was compiled against. Static * string — do NOT free. */ LOGOS_MODULE_IMPL_EXPORT const char* logos_module_get_protocol_version(void); /* Free a string returned by this module. Safe on NULL. */ LOGOS_MODULE_IMPL_EXPORT void logos_module_string_free(char* s); #ifdef __cplusplus } #endif #endif /* LOGOS_MODULE_IMPL_H */