feat(sdk): static plugin registry for WASM / no-dlopen builds

facontidavide · claude · facontidavide · commit 2d8554185d09 · 2026-06-21T19:40:29.000+02:00
Add a static-linking path alongside the dlopen one, for Qt-for-WebAssembly
(and any single-binary build) where many plugins are linked into the host:

- PJ_{DATA_SOURCE,TOOLBOX,MESSAGE_PARSER}_PLUGIN, under #ifdef PJ_STATIC_PLUGINS,
  emit a uniquely class-keyed `pj_static_get_*_vtable_&lt;Class&gt;()` instead of the
  fixed `extern "C" PJ_get_*_vtable` symbol (which would collide across plugins
  in one binary). The C-ABI vtable contract is unchanged.
- {DataSource,MessageParser,Toolbox}Library::loadStatic(vtable): wrap a
  statically-linked vtable with a sentinel shared_ptr owner (no DSO), so
  valid()/createHandle() work unchanged.
- PluginRuntimeCatalog::registerStatic{DataSource,MessageParser,Toolbox}(vtable):
  read the embedded manifest JSON and register without a disk scan.
- CMakeLists: append -Wno-error under EMSCRIPTEN (wasm32 size_t is 32-bit).

Pure additions (+243/-0); the dlopen path and desktop behavior are untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -35,6 +35,13 @@ else()
     -Wall -Wextra -Werror -Wshadow -Wnon-virtual-dtor -Wold-style-cast
     -Wcast-qual -Wconversion -Woverloaded-virtual -Wpedantic
   )
+  # On wasm32 size_t is 32-bit, so many uint64_t->size_t conversions trip
+  # -Wshorten-64-to-32 / -Wsign-conversion that never fire on 64-bit desktop
+  # (see SUSTAINABILITY.md T0-3). Keep the warnings visible but don't fail the
+  # build for the WASM prototype. TODO: make the ABI/size types 32-bit-clean.
+  if(EMSCRIPTEN)
+    list(APPEND PJ_WARNING_FLAGS -Wno-error)
+  endif()
 endif()
 
 # ---------------------------------------------------------------------------
diff --git a/pj_base/include/pj_base/sdk/data_source_plugin_base.hpp b/pj_base/include/pj_base/sdk/data_source_plugin_base.hpp
@@ -250,3 +250,26 @@ class DataSourcePluginBase {
         manifest);                                                                                       \
     return vt;                                                                                           \
   }
+
+// --- Static-link variant (WASM / no dlopen) ----------------------------------
+// With PJ_STATIC_PLUGINS the plugin is linked into the host binary. The fixed
+// `extern "C" PJ_get_data_source_vtable` symbol would collide across plugins in
+// one binary, so emit a uniquely-named (class-keyed) C++ function instead. The
+// host's static registry declares these extern and passes them to
+// PluginRuntimeCatalog::registerStaticDataSource().
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_DATA_SOURCE_PLUGIN
+#define PJ_DATA_SOURCE_PLUGIN(ClassName, manifest)                                         \
+  const PJ_data_source_vtable_t* pj_static_get_data_source_vtable_##ClassName() noexcept { \
+    static const PJ_data_source_vtable_t* vt = PJ::DataSourcePluginBase::vtableWithCreate( \
+        []() noexcept -> void* {                                                           \
+          try {                                                                            \
+            return new ClassName();                                                        \
+          } catch (...) {                                                                  \
+            return nullptr;                                                                \
+          }                                                                                \
+        },                                                                                 \
+        manifest);                                                                         \
+    return vt;                                                                             \
+  }
+#endif
diff --git a/pj_base/include/pj_base/sdk/toolbox_plugin_base.hpp b/pj_base/include/pj_base/sdk/toolbox_plugin_base.hpp
@@ -250,3 +250,21 @@ class ToolboxPluginBase {
         manifest);                                                                           \
     return vt;                                                                               \
   }
+
+// --- Static-link variant (WASM / no dlopen) ---  see data_source_plugin_base.hpp
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_TOOLBOX_PLUGIN
+#define PJ_TOOLBOX_PLUGIN(ClassName, manifest)                                       \
+  const PJ_toolbox_vtable_t* pj_static_get_toolbox_vtable_##ClassName() noexcept {    \
+    static const PJ_toolbox_vtable_t* vt = PJ::ToolboxPluginBase::vtableWithCreate(   \
+        []() noexcept -> void* {                                                     \
+          try {                                                                      \
+            return new ClassName();                                                  \
+          } catch (...) {                                                            \
+            return nullptr;                                                          \
+          }                                                                          \
+        },                                                                           \
+        manifest);                                                                   \
+    return vt;                                                                       \
+  }
+#endif
diff --git a/pj_plugins/include/pj_plugins/host/data_source_library.hpp b/pj_plugins/include/pj_plugins/host/data_source_library.hpp
@@ -51,6 +51,10 @@ class DataSourceLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<DataSourceLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<DataSourceLibrary> loadStatic(const PJ_data_source_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/host/message_parser_library.hpp b/pj_plugins/include/pj_plugins/host/message_parser_library.hpp
@@ -51,6 +51,10 @@ class MessageParserLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<MessageParserLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<MessageParserLibrary> loadStatic(const PJ_message_parser_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/host/plugin_runtime_catalog.hpp b/pj_plugins/include/pj_plugins/host/plugin_runtime_catalog.hpp
@@ -81,6 +81,14 @@ class PluginRuntimeCatalog {
   // Reconciles loaded state with disk and returns true if it changed.
   [[nodiscard]] bool reload();
 
+  // --- Static plugin registration (WASM/static builds; no dlopen) -------------
+  // Register a statically-linked plugin by its vtable. The vtable must outlive
+  // this catalog (static storage duration); the manifest is read from
+  // vtable->manifest_json. Returns false (and reports a diagnostic) on failure.
+  bool registerStaticDataSource(const PJ_data_source_vtable_t* vtable);
+  bool registerStaticMessageParser(const PJ_message_parser_vtable_t* vtable);
+  bool registerStaticToolbox(const PJ_toolbox_vtable_t* vtable);
+
   // Returns loaded DataSource plugins.
   [[nodiscard]] const std::vector<RuntimeDataSourcePlugin>& dataSources() const {
     return data_sources_;
diff --git a/pj_plugins/include/pj_plugins/host/toolbox_library.hpp b/pj_plugins/include/pj_plugins/host/toolbox_library.hpp
@@ -51,6 +51,10 @@ class ToolboxLibrary {
   /// Load a plugin from @p path. Returns an error string on failure.
   [[nodiscard]] static Expected<ToolboxLibrary> load(std::string_view path);
 
+  /// Wrap a statically-linked plugin vtable (no dlopen; for WASM/static builds).
+  /// @p vtable must have static storage duration (valid for the program lifetime).
+  [[nodiscard]] static Expected<ToolboxLibrary> loadStatic(const PJ_toolbox_vtable_t* vtable);
+
   /// True if the library was loaded and the vtable resolved successfully.
   [[nodiscard]] bool valid() const {
     return handle_ != nullptr && vtable_ != nullptr;
diff --git a/pj_plugins/include/pj_plugins/sdk/message_parser_plugin_base.hpp b/pj_plugins/include/pj_plugins/sdk/message_parser_plugin_base.hpp
@@ -376,3 +376,21 @@ class MessageParserPluginBase {
         manifest);                                                                                                \
     return vt;                                                                                                    \
   }
+
+// --- Static-link variant (WASM / no dlopen) ---  see data_source_plugin_base.hpp
+#ifdef PJ_STATIC_PLUGINS
+#undef PJ_MESSAGE_PARSER_PLUGIN
+#define PJ_MESSAGE_PARSER_PLUGIN(ClassName, manifest)                                          \
+  const PJ_message_parser_vtable_t* pj_static_get_message_parser_vtable_##ClassName() noexcept {\
+    static const PJ_message_parser_vtable_t* vt = PJ::MessageParserPluginBase::vtableWithCreate(\
+        []() noexcept -> void* {                                                               \
+          try {                                                                                \
+            return new ClassName();                                                            \
+          } catch (...) {                                                                      \
+            return nullptr;                                                                    \
+          }                                                                                    \
+        },                                                                                     \
+        manifest);                                                                             \
+    return vt;                                                                                 \
+  }
+#endif
diff --git a/pj_plugins/src/data_source_library.cpp b/pj_plugins/src/data_source_library.cpp
@@ -70,6 +70,26 @@ Expected<DataSourceLibrary> DataSourceLibrary::load(std::string_view path) {
   return DataSourceLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<DataSourceLibrary> DataSourceLibrary::loadStatic(const PJ_data_source_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static DataSource vtable is null");
+  }
+  if (vtable->protocol_version != PJ_DATA_SOURCE_PROTOCOL_VERSION) {
+    return unexpected("DataSource protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_DATA_SOURCE_MIN_VTABLE_SIZE) {
+    return unexpected("DataSource vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  // Statically linked: no DSO to keep alive, but valid()/createHandle() expect a
+  // non-null owner. Use a sentinel shared_ptr with a no-op deleter.
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return DataSourceLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> DataSourceLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
diff --git a/pj_plugins/src/message_parser_library.cpp b/pj_plugins/src/message_parser_library.cpp
@@ -68,6 +68,24 @@ Expected<MessageParserLibrary> MessageParserLibrary::load(std::string_view path)
   return MessageParserLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<MessageParserLibrary> MessageParserLibrary::loadStatic(const PJ_message_parser_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static MessageParser vtable is null");
+  }
+  if (vtable->protocol_version != PJ_MESSAGE_PARSER_PROTOCOL_VERSION) {
+    return unexpected("MessageParser protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_MESSAGE_PARSER_MIN_VTABLE_SIZE) {
+    return unexpected("MessageParser vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return MessageParserLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> MessageParserLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
diff --git a/pj_plugins/src/plugin_runtime_catalog.cpp b/pj_plugins/src/plugin_runtime_catalog.cpp
@@ -150,6 +150,107 @@ bool PluginRuntimeCatalog::reload() {
   return changed;
 }
 
+namespace {
+
+// Parse a plugin's embedded manifest JSON. Returns false on invalid JSON.
+bool parseStaticManifest(const char* manifest_json, nlohmann::json& out) {
+  try {
+    out = nlohmann::json::parse(manifest_json ? manifest_json : "");
+    return out.is_object();
+  } catch (const std::exception&) {
+    return false;
+  }
+}
+
+std::vector<std::string> readManifestStringArray(const nlohmann::json& j, const char* key) {
+  std::vector<std::string> values;
+  if (auto it = j.find(key); it != j.end() && it->is_array()) {
+    for (const auto& v : *it) {
+      if (v.is_string()) {
+        values.push_back(v.get<std::string>());
+      }
+    }
+  }
+  return values;
+}
+
+}  // namespace
+
+bool PluginRuntimeCatalog::registerStaticDataSource(const PJ_data_source_vtable_t* vtable) {
+  auto result = DataSourceLibrary::loadStatic(vtable);
+  if (!result) {
+    report(DiagnosticLevel::kError, {}, "static DataSource: " + result.error());
+    return false;
+  }
+  nlohmann::json j;
+  if (!parseStaticManifest(vtable->manifest_json, j)) {
+    report(DiagnosticLevel::kError, {}, "static DataSource: invalid manifest JSON");
+    return false;
+  }
+  RuntimeDataSourcePlugin loaded;
+  loaded.library = std::move(*result);
+  loaded.id = j.value("id", std::string{});
+  loaded.name = j.value("name", std::string{});
+  loaded.version = j.value("version", std::string{});
+  loaded.path = "static://" + loaded.id;
+  loaded.loaded_mtime = std::filesystem::file_time_type{};
+  loaded.capabilities = loaded.library.createHandle().capabilities();
+  for (auto& ext : readManifestStringArray(j, "file_extensions")) {
+    loaded.file_extensions.push_back(normalizeExtension(std::move(ext)));
+  }
+  report(DiagnosticLevel::kInfo, loaded.id, "Registered static DataSource " + loaded.name);
+  data_sources_.push_back(std::move(loaded));
+  return true;
+}
+
+bool PluginRuntimeCatalog::registerStaticMessageParser(const PJ_message_parser_vtable_t* vtable) {
+  auto result = MessageParserLibrary::loadStatic(vtable);
+  if (!result) {
+    report(DiagnosticLevel::kError, {}, "static MessageParser: " + result.error());
+    return false;
+  }
+  nlohmann::json j;
+  if (!parseStaticManifest(vtable->manifest_json, j)) {
+    report(DiagnosticLevel::kError, {}, "static MessageParser: invalid manifest JSON");
+    return false;
+  }
+  RuntimeMessageParserPlugin loaded;
+  loaded.library = std::move(*result);
+  loaded.id = j.value("id", std::string{});
+  loaded.name = j.value("name", std::string{});
+  loaded.version = j.value("version", std::string{});
+  loaded.path = "static://" + loaded.id;
+  loaded.loaded_mtime = std::filesystem::file_time_type{};
+  loaded.encodings = readManifestStringArray(j, "encoding");
+  report(DiagnosticLevel::kInfo, loaded.id, "Registered static MessageParser " + loaded.name);
+  message_parsers_.push_back(std::move(loaded));
+  return true;
+}
+
+bool PluginRuntimeCatalog::registerStaticToolbox(const PJ_toolbox_vtable_t* vtable) {
+  auto result = ToolboxLibrary::loadStatic(vtable);
+  if (!result) {
+    report(DiagnosticLevel::kError, {}, "static Toolbox: " + result.error());
+    return false;
+  }
+  nlohmann::json j;
+  if (!parseStaticManifest(vtable->manifest_json, j)) {
+    report(DiagnosticLevel::kError, {}, "static Toolbox: invalid manifest JSON");
+    return false;
+  }
+  RuntimeToolboxPlugin loaded;
+  loaded.library = std::move(*result);
+  loaded.id = j.value("id", std::string{});
+  loaded.name = j.value("name", std::string{});
+  loaded.version = j.value("version", std::string{});
+  loaded.path = "static://" + loaded.id;
+  loaded.loaded_mtime = std::filesystem::file_time_type{};
+  loaded.capabilities = loaded.library.createHandle().capabilities();
+  report(DiagnosticLevel::kInfo, loaded.id, "Registered static Toolbox " + loaded.name);
+  toolbox_plugins_.push_back(std::move(loaded));
+  return true;
+}
+
 bool PluginRuntimeCatalog::loadAndRegister(const PluginDescriptor& descriptor) {
   switch (descriptor.family) {
     case PluginFamily::kDataSource:
diff --git a/pj_plugins/src/toolbox_library.cpp b/pj_plugins/src/toolbox_library.cpp
@@ -67,6 +67,24 @@ Expected<ToolboxLibrary> ToolboxLibrary::load(std::string_view path) {
   return ToolboxLibrary(std::move(handle), vtable, std::string(path));
 }
 
+Expected<ToolboxLibrary> ToolboxLibrary::loadStatic(const PJ_toolbox_vtable_t* vtable) {
+  if (vtable == nullptr) {
+    return unexpected("static Toolbox vtable is null");
+  }
+  if (vtable->protocol_version != PJ_TOOLBOX_PLUGIN_PROTOCOL_VERSION) {
+    return unexpected("Toolbox protocol version mismatch");
+  }
+  if (vtable->struct_size < PJ_TOOLBOX_MIN_VTABLE_SIZE) {
+    return unexpected("Toolbox vtable smaller than v4.0 baseline");
+  }
+  if (auto status = detail::validateRequiredSlots(vtable); !status) {
+    return unexpected(status.error());
+  }
+  static char anchor = 0;
+  std::shared_ptr<void> handle(&anchor, [](void*) {});
+  return ToolboxLibrary(std::move(handle), vtable, "static://");
+}
+
 Expected<const PJ_dialog_vtable_t*> ToolboxLibrary::resolveDialogVtable() const {
   auto sym = detail::resolveSymbol(handle_.get(), "PJ_get_dialog_vtable");
   if (!sym) {
