pluginforge 0.3.0__tar.gz → 0.5.0__tar.gz

{pluginforge-0.3.0 → pluginforge-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pluginforge
-Version: 0.3.0
+Version: 0.5.0
 Summary: Application-agnostic plugin framework built on pluggy
 License: MIT
 License-File: LICENSE
@@ -105,18 +105,24 @@ for plugin in pm.get_active_plugins():
 # Mount FastAPI routes
 from fastapi import FastAPI
 app = FastAPI()
-pm.mount_routes(app)  # Routes at /api/plugins/{name}/
+pm.mount_routes(app)  # Routes under /api/ (configurable prefix)
 ```
 
 ## Features
 
 - **YAML Configuration** - App config, per-plugin config, and i18n strings
 - **Plugin Lifecycle** - init, activate, deactivate with error handling
+- **Hot-Reload** - Swap plugins at runtime without app restart
 - **Enable/Disable** - Control plugins via config lists
 - **Dependency Resolution** - Topological sorting with circular dependency detection
-- **FastAPI Integration** - Auto-mount plugin routes under `/api/plugins/{name}/`
+- **Extension Points** - Query plugins by interface with `get_extensions(type)`
+- **Config Schema Validation** - Declare expected config types per plugin
+- **Health Checks** - Monitor plugin status via `health_check()`
+- **Pre-Activate Hooks** - Reject plugins before activation (license checks, etc.)
+- **FastAPI Integration** - Mount plugin routes with configurable prefix
 - **Alembic Support** - Collect migration directories from plugins
 - **i18n** - Multi-language strings from YAML with fallback
+- **Security** - Plugin name validation and path traversal prevention
 
 For detailed documentation, see the [Wiki](https://github.com/astrapi69/pluginforge/wiki).
 
@@ -161,10 +167,13 @@ The full documentation is available in the [Wiki](https://github.com/astrapi69/p
 - [Discovery and Dependencies](https://github.com/astrapi69/pluginforge/wiki/Discovery-and-Dependencies)
 - [Lifecycle](https://github.com/astrapi69/pluginforge/wiki/Lifecycle)
 - [Hooks](https://github.com/astrapi69/pluginforge/wiki/Hooks)
+- [Extensions](https://github.com/astrapi69/pluginforge/wiki/Extensions)
 - [FastAPI Integration](https://github.com/astrapi69/pluginforge/wiki/FastAPI-Integration)
 - [Alembic Integration](https://github.com/astrapi69/pluginforge/wiki/Alembic-Integration)
 - [i18n](https://github.com/astrapi69/pluginforge/wiki/i18n)
+- [Security](https://github.com/astrapi69/pluginforge/wiki/Security)
 - [Examples](https://github.com/astrapi69/pluginforge/wiki/Examples)
+- [Changelog](https://github.com/astrapi69/pluginforge/wiki/Changelog)
 
 ## Development
 

{pluginforge-0.3.0 → pluginforge-0.5.0}/README.md

@@ -80,18 +80,24 @@ for plugin in pm.get_active_plugins():
 # Mount FastAPI routes
 from fastapi import FastAPI
 app = FastAPI()
-pm.mount_routes(app)  # Routes at /api/plugins/{name}/
+pm.mount_routes(app)  # Routes under /api/ (configurable prefix)
 ```
 
 ## Features
 
 - **YAML Configuration** - App config, per-plugin config, and i18n strings
 - **Plugin Lifecycle** - init, activate, deactivate with error handling
+- **Hot-Reload** - Swap plugins at runtime without app restart
 - **Enable/Disable** - Control plugins via config lists
 - **Dependency Resolution** - Topological sorting with circular dependency detection
-- **FastAPI Integration** - Auto-mount plugin routes under `/api/plugins/{name}/`
+- **Extension Points** - Query plugins by interface with `get_extensions(type)`
+- **Config Schema Validation** - Declare expected config types per plugin
+- **Health Checks** - Monitor plugin status via `health_check()`
+- **Pre-Activate Hooks** - Reject plugins before activation (license checks, etc.)
+- **FastAPI Integration** - Mount plugin routes with configurable prefix
 - **Alembic Support** - Collect migration directories from plugins
 - **i18n** - Multi-language strings from YAML with fallback
+- **Security** - Plugin name validation and path traversal prevention
 
 For detailed documentation, see the [Wiki](https://github.com/astrapi69/pluginforge/wiki).
 
@@ -136,10 +142,13 @@ The full documentation is available in the [Wiki](https://github.com/astrapi69/p
 - [Discovery and Dependencies](https://github.com/astrapi69/pluginforge/wiki/Discovery-and-Dependencies)
 - [Lifecycle](https://github.com/astrapi69/pluginforge/wiki/Lifecycle)
 - [Hooks](https://github.com/astrapi69/pluginforge/wiki/Hooks)
+- [Extensions](https://github.com/astrapi69/pluginforge/wiki/Extensions)
 - [FastAPI Integration](https://github.com/astrapi69/pluginforge/wiki/FastAPI-Integration)
 - [Alembic Integration](https://github.com/astrapi69/pluginforge/wiki/Alembic-Integration)
 - [i18n](https://github.com/astrapi69/pluginforge/wiki/i18n)
+- [Security](https://github.com/astrapi69/pluginforge/wiki/Security)
 - [Examples](https://github.com/astrapi69/pluginforge/wiki/Examples)
+- [Changelog](https://github.com/astrapi69/pluginforge/wiki/Changelog)
 
 ## Development
 

{pluginforge-0.3.0 → pluginforge-0.5.0}/pluginforge/__init__.py

@@ -3,6 +3,12 @@
 from pluginforge.base import BasePlugin
 from pluginforge.discovery import CircularDependencyError
 from pluginforge.manager import PluginManager
+from pluginforge.security import InvalidPluginNameError
 
-__version__ = "0.2.0"
-__all__ = ["BasePlugin", "CircularDependencyError", "PluginManager"]
+__version__ = "0.5.0"
+__all__ = [
+    "BasePlugin",
+    "CircularDependencyError",
+    "InvalidPluginNameError",
+    "PluginManager",
+]

{pluginforge-0.3.0 → pluginforge-0.5.0}/pluginforge/alembic_ext.py

@@ -28,6 +28,15 @@ def collect_migrations_dirs(plugins: list[BasePlugin]) -> dict[str, str]:
                 "Plugin '%s' migrations dir does not exist: %s", plugin.name, migrations_dir
             )
             continue
-        migrations[plugin.name] = str(path)
-        logger.info("Collected migrations for plugin '%s': %s", plugin.name, migrations_dir)
+        # Ensure resolved path doesn't escape via symlinks
+        resolved = path.resolve()
+        if not resolved.is_dir():
+            logger.warning(
+                "Plugin '%s' migrations dir resolves to non-directory: %s",
+                plugin.name,
+                resolved,
+            )
+            continue
+        migrations[plugin.name] = str(resolved)
+        logger.info("Collected migrations for plugin '%s': %s", plugin.name, resolved)
     return migrations

{pluginforge-0.3.0 → pluginforge-0.5.0}/pluginforge/config.py

@@ -46,6 +46,8 @@ def load_app_config(config_path: str | Path) -> dict[str, Any]:
 def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, Any]:
     """Load plugin-specific configuration from config/plugins/{name}.yaml.
 
+    Validates the plugin name to prevent path traversal attacks.
+
     Args:
         config_dir: Base config directory (parent of plugins/).
         plugin_name: Name of the plugin.
@@ -53,6 +55,9 @@ def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, An
     Returns:
         Plugin configuration dict.
     """
+    from pluginforge.security import validate_plugin_name
+
+    validate_plugin_name(plugin_name)
     path = Path(config_dir) / "plugins" / f"{plugin_name}.yaml"
     return load_yaml(path)
 
@@ -60,6 +65,8 @@ def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, An
 def load_i18n(config_dir: str | Path, lang: str) -> dict[str, Any]:
     """Load i18n strings for a specific language.
 
+    Validates the language code to prevent path traversal attacks.
+
     Args:
         config_dir: Base config directory (parent of i18n/).
         lang: Language code (e.g. "en", "de").
@@ -67,5 +74,8 @@ def load_i18n(config_dir: str | Path, lang: str) -> dict[str, Any]:
     Returns:
         i18n strings dict.
     """
+    from pluginforge.security import validate_plugin_name
+
+    validate_plugin_name(lang)
     path = Path(config_dir) / "i18n" / f"{lang}.yaml"
     return load_yaml(path)

{pluginforge-0.3.0 → pluginforge-0.5.0}/pluginforge/lifecycle.py

@@ -135,6 +135,17 @@ class PluginLifecycle:
         """
         return self._initialized.get(name)
 
+    def remove_plugin(self, name: str) -> None:
+        """Remove a plugin from all lifecycle tracking.
+
+        Used during hot-reload to clean up before re-instantiation.
+
+        Args:
+            name: Plugin name.
+        """
+        self._initialized.pop(name, None)
+        self._active.pop(name, None)
+
     def is_active(self, name: str) -> bool:
         """Check if a plugin is currently active.
 

{pluginforge-0.3.0 → pluginforge-0.5.0}/pluginforge/manager.py

@@ -1,6 +1,8 @@
 """Central PluginManager that orchestrates config, discovery, lifecycle, and hooks."""
 
+import importlib
 import logging
+import sys
 from pathlib import Path
 from collections.abc import Callable
 from typing import Any
@@ -18,6 +20,7 @@ from pluginforge.discovery import (
 )
 from pluginforge.i18n import I18n
 from pluginforge.lifecycle import PluginLifecycle
+from pluginforge.security import validate_plugin_name
 
 logger = logging.getLogger(__name__)
 
@@ -165,6 +168,8 @@ class PluginManager:
             plugin: An already instantiated plugin.
             plugin_config: Optional config dict. If None, loaded from YAML.
         """
+        validate_plugin_name(plugin.name)
+
         if plugin_config is None:
             plugin_config = self.get_plugin_config(plugin.name)
 
@@ -208,6 +213,7 @@ class PluginManager:
             order: Topologically sorted list of plugin names.
         """
         for name in order:
+            validate_plugin_name(name)
             cls = plugins[name]
             plugin = cls()
             plugin_config = self.get_plugin_config(name)
@@ -299,18 +305,90 @@ class PluginManager:
     def call_hook(self, hook_name: str, **kwargs: Any) -> list[Any]:
         """Call a named hook on all registered plugins.
 
+        Individual hook implementations that raise exceptions are caught and
+        logged. Other implementations still execute (graceful degradation).
+
+        Args:
+            hook_name: Name of the hook to call.
+            **kwargs: Arguments to pass to hook implementations.
+
+        Returns:
+            List of results from all hook implementations (failed ones are skipped).
+        """
+        hook = getattr(self._pm.hook, hook_name, None)
+        if hook is None:
+            logger.warning("Hook '%s' not found", hook_name)
+            return []
+        try:
+            return hook(**kwargs)
+        except Exception as e:
+            logger.error("Hook '%s' raised an exception: %s", hook_name, e)
+            return []
+
+    def call_hook_safe(self, hook_name: str, **kwargs: Any) -> list[Any]:
+        """Call a hook, collecting results and skipping failed implementations.
+
+        Unlike call_hook(), this calls each implementation individually so one
+        failure does not prevent others from executing.
+
         Args:
             hook_name: Name of the hook to call.
             **kwargs: Arguments to pass to hook implementations.
 
         Returns:
-            List of results from all hook implementations.
+            List of successful results (failed implementations are logged and skipped).
         """
         hook = getattr(self._pm.hook, hook_name, None)
         if hook is None:
             logger.warning("Hook '%s' not found", hook_name)
             return []
-        return hook(**kwargs)
+        results: list[Any] = []
+        callers = hook.get_hookimpls()
+        for impl in callers:
+            try:
+                result = impl.function(**kwargs)
+                results.append(result)
+            except Exception as e:
+                plugin_name = impl.plugin_name or "unknown"
+                logger.error(
+                    "Hook '%s' implementation from '%s' failed: %s",
+                    hook_name,
+                    plugin_name,
+                    e,
+                )
+        return results
+
+    def get_plugin_hooks(self, name: str) -> list[str]:
+        """Return hook names implemented by a specific plugin.
+
+        Useful for debugging, settings UIs, and plugin marketplaces.
+
+        Args:
+            name: Plugin name.
+
+        Returns:
+            List of hook names the plugin implements, or empty list if not found.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            return []
+        impl_marker = f"{self._entry_point_group}_impl"
+        hooks: list[str] = []
+        for attr_name in dir(plugin):
+            if attr_name.startswith("_"):
+                continue
+            method = getattr(plugin, attr_name, None)
+            if callable(method) and hasattr(method, impl_marker):
+                hooks.append(attr_name)
+        return hooks
+
+    def get_all_hook_names(self) -> list[str]:
+        """Return all registered hook spec names.
+
+        Returns:
+            List of hook names from all registered specs.
+        """
+        return [name for name in dir(self._pm.hook) if not name.startswith("_")]
 
     def mount_routes(self, app: object, prefix: str = "/api") -> None:
         """Mount FastAPI routes from all active plugins.
@@ -358,3 +436,79 @@ class PluginManager:
             except Exception as e:
                 results[plugin.name] = {"status": "error", "error": str(e)}
         return results
+
+    def reload_plugin(self, name: str) -> bool:
+        """Hot-reload a plugin: deactivate, re-import module, re-init, activate.
+
+        The plugin's module is reloaded from disk so code changes take effect
+        without restarting the application.
+
+        Args:
+            name: Name of the plugin to reload.
+
+        Returns:
+            True if reload succeeded, False otherwise.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Cannot reload unknown plugin '%s'", name)
+            return False
+
+        plugin_cls = type(plugin)
+        module_name = plugin_cls.__module__
+
+        # Deactivate and unregister
+        if self._lifecycle.is_active(name):
+            self._lifecycle.deactivate_plugin(plugin)
+            self._pm.unregister(name=name)
+
+        # Remove from lifecycle tracking
+        self._lifecycle.remove_plugin(name)
+
+        # Reload the module
+        try:
+            module = sys.modules.get(module_name)
+            if module is not None:
+                module = importlib.reload(module)
+                plugin_cls = getattr(module, plugin_cls.__name__)
+        except Exception as e:
+            logger.error("Failed to reload module '%s': %s", module_name, e)
+            self._load_errors[name] = f"Failed to reload module: {e}"
+            return False
+
+        # Re-instantiate and activate
+        new_plugin = plugin_cls()
+        plugin_config = self.get_plugin_config(name)
+
+        if not self._lifecycle.init_plugin(new_plugin, self._app_config, plugin_config):
+            self._load_errors[name] = "Failed to initialize after reload"
+            return False
+
+        if self._pre_activate is not None:
+            if not self._pre_activate(new_plugin, plugin_config):
+                self._load_errors[name] = "Rejected by pre-activate check after reload"
+                return False
+
+        self._pm.register(new_plugin, name=name)
+
+        if not self._lifecycle.activate_plugin(new_plugin):
+            self._load_errors[name] = "Failed to activate after reload"
+            self._pm.unregister(name=name)
+            return False
+
+        logger.info("Reloaded plugin '%s'", name)
+        return True
+
+    def get_extensions(self, extension_point: type) -> list[BasePlugin]:
+        """Return all active plugins that implement a given extension point.
+
+        An extension point is any class or ABC. This method returns all active
+        plugins that are instances of that type.
+
+        Args:
+            extension_point: The extension point class to filter by.
+
+        Returns:
+            List of active plugins implementing the extension point.
+        """
+        return [p for p in self.get_active_plugins() if isinstance(p, extension_point)]

pluginforge-0.5.0/pluginforge/security.py

@@ -0,0 +1,55 @@
+"""Security utilities for plugin name validation and path traversal prevention."""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# Plugin names must be alphanumeric with underscores/hyphens, max 64 chars
+_PLUGIN_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]{0,63}$")
+
+
+class InvalidPluginNameError(ValueError):
+    """Raised when a plugin name contains invalid characters."""
+
+
+def validate_plugin_name(name: str) -> None:
+    """Validate a plugin name for safety.
+
+    Plugin names are used to construct file paths (config/plugins/{name}.yaml),
+    so they must not contain path separators or traversal sequences.
+
+    Args:
+        name: The plugin name to validate.
+
+    Raises:
+        InvalidPluginNameError: If the name is invalid.
+    """
+    if not _PLUGIN_NAME_RE.match(name):
+        raise InvalidPluginNameError(
+            f"Invalid plugin name '{name}'. "
+            "Names must start with a letter, contain only letters, digits, "
+            "underscores, or hyphens, and be at most 64 characters."
+        )
+
+
+def validate_safe_path(path: str, allowed_base: str) -> bool:
+    """Check that a resolved path stays within the allowed base directory.
+
+    Args:
+        path: The path to validate.
+        allowed_base: The base directory that the path must stay within.
+
+    Returns:
+        True if the path is safe, False otherwise.
+    """
+    from pathlib import Path
+
+    resolved = Path(path).resolve()
+    base = Path(allowed_base).resolve()
+    try:
+        resolved.relative_to(base)
+        return True
+    except ValueError:
+        logger.warning("Path traversal detected: '%s' escapes base '%s'", path, allowed_base)
+        return False

{pluginforge-0.3.0 → pluginforge-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pluginforge"
-version = "0.3.0"
+version = "0.5.0"
 description = "Application-agnostic plugin framework built on pluggy"
 authors = ["Asterios Raptis"]
 license = "MIT"