super-solid-system 1.0.0__py3-none-any.whl

supersolid/core/registry.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+import inspect
+import threading
+from abc import ABC
+from pydantic import BaseModel
+from typing import Dict, Any, Type, Optional, TypeVar, Generic, List, TYPE_CHECKING
+
+from supersolid.core.discovery import DiscoveryStrategy, InternalLib, EntryPoints, PluginDirectory
+
+if TYPE_CHECKING:
+    from supersolid.core.security import SecurityPolicy
+
+
+class ComponentMetadata(BaseModel):
+    name: str
+    namespace: str
+    version: Optional[str] = None
+    model_config = {
+        "extra": "allow"
+    }
+
+
+ComponentType = TypeVar("ComponentType")
+
+
+class SuperSolidRegistry(Generic[ComponentType], ABC):
+    """
+    Generic Base Registry managing component classes, plugin discovery,
+    type enforcement, instantiation, and active instance caching.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        component_class: Type[ComponentType],
+        policy: Optional[SecurityPolicy] = None,
+        discovery_strategies: Optional[List[DiscoveryStrategy]] = None,
+        root_package: Optional[str] = None,
+    ):
+        self.name = name.lower()
+        self.component_class = component_class
+        self.policy = policy
+        self._root_package = root_package
+        self._registries: Dict[str, Dict[str, Type[ComponentType]]] = {}
+        self._instances: Dict[str, ComponentType] = {}
+        self._lock = threading.RLock()
+        self.discovery_strategies: List[DiscoveryStrategy] = (
+            discovery_strategies
+            if discovery_strategies is not None
+            else [
+                InternalLib(),
+                EntryPoints(),
+                PluginDirectory(),
+            ]
+        )
+
+    @property
+    def root_package(self) -> str:
+        """Dynamically infers or returns the configured root package name."""
+        if self._root_package:
+            return self._root_package
+        parts = self.__class__.__module__.split(".")
+        if parts[0] == "__main__":
+            return "supersolid"
+        return ".".join(parts[:2]) if len(parts) >= 2 and parts[0] == "supersolid" else parts[0]
+
+    def _cache_key(self, component_namespace: str, component_name: str, kwargs: Optional[Dict[str, Any]] = None) -> str:
+        component_namespace = component_namespace.lower()
+        component_name = component_name.lower()
+        if kwargs:
+            kwargs_str = "_".join(
+                f"{k}={v}" for k, v in sorted(kwargs.items()) if isinstance(v, (str, int, float, bool))
+            )
+            if kwargs_str:
+                return f"{component_namespace}.{component_name}:{kwargs_str}"
+        return f"{component_namespace}.{component_name}"
+
+    def set_policy(self, policy: SecurityPolicy) -> None:
+        """Attaches or updates the SecurityPolicy enforced by this registry."""
+        with self._lock:
+            self.policy = policy
+
+    def add_discovery(self, strategy: DiscoveryStrategy) -> None:
+        """Injects a new discovery strategy into the registry pipeline."""
+        with self._lock:
+            self.discovery_strategies.append(strategy)
+
+    def is_registered(self, component_namespace: str, component_name: str) -> bool:
+        """Checks if an item class is currently registered in the registry."""
+        component_namespace = component_namespace.lower()
+        component_name = component_name.lower()
+        with self._lock:
+            return component_namespace in self._registries and component_name in self._registries[component_namespace]
+
+    def register(self, component_namespace: str, component_name: str, component_class: Type[ComponentType]) -> None:
+        """Registers a class in the registry with automatic type enforcement."""
+        component_namespace = component_namespace.lower()
+        component_name = component_name.lower()
+
+        if not issubclass(component_class, self.component_class):
+            raise TypeError(
+                f"Cannot register '{component_class.__name__}' in {self.name} registry. "
+                f"Expected a subclass of '{self.component_class.__name__}'."
+            )
+
+        with self._lock:
+            if component_namespace not in self._registries:
+                self._registries[component_namespace] = {}
+            self._registries[component_namespace][component_name] = component_class
+
+    def get(
+        self,
+        component_namespace: str,
+        component_name: str,
+        expected_class: Optional[Type[ComponentType]] = None,
+        **kwargs: Any
+    ) -> Optional[ComponentType]:
+        """Gets an active loaded instance from the cache."""
+        cache_key = self._cache_key(
+            component_namespace, component_name, kwargs)
+        with self._lock:
+            instance = self._instances.get(cache_key)
+
+            target_class = expected_class or self.component_class
+            if instance is not None and not isinstance(instance, target_class):
+                raise TypeError(
+                    f"Expected instance of {target_class.__name__}, got {type(instance).__name__}!"
+                )
+            return instance
+
+    def discover(self, component_namespace: str, component_name: str) -> None:
+        """Attempts dynamic plugin discovery across registered discovery strategies."""
+        component_namespace = component_namespace.lower()
+        component_name = component_name.lower()
+        for strategy in self.discovery_strategies:
+            if self.policy is not None:
+                # 1. InternalLib fallback check
+                if not self.policy.allow_internal_lib and isinstance(strategy, InternalLib):
+                    continue
+                if not self.policy.allow_external_entrypoints and isinstance(strategy, EntryPoints):
+                    continue
+                if not self.policy.allow_plugin_discovery and isinstance(strategy, PluginDirectory):
+                    continue
+
+            if strategy.discover(self, component_namespace, component_name):
+                return
+
+    def load(
+        self,
+        component_namespace: str,
+        component_name: str,
+        config: Any = {},
+        allowed_namespaces: Optional[List[str]] = None,
+        **kwargs: Any
+    ) -> ComponentType:
+        """
+        Loads, instantiates, and caches an item from the registry.
+        Performs dynamic discovery if the item class is not yet registered.
+        """
+        component_namespace = component_namespace.lower()
+        component_name = component_name.lower()
+        # 1. Namespace Protection & Policy Check
+        if self.policy is not None:
+            self.policy.validate_access(
+                component_namespace, caller_id=kwargs.get("caller_id"))
+        elif allowed_namespaces is not None:
+            allowed_set = {c.lower() for c in allowed_namespaces}
+            if component_namespace not in allowed_set:
+                raise PermissionError(
+                    f"Namespace '{component_namespace}' is restricted in '{self.name}' registry."
+                )
+
+        cache_key = self._cache_key(
+            component_namespace, component_name, kwargs)
+
+        with self._lock:
+            # 1. Return cached instance if already loaded
+            if cache_key in self._instances:
+                return self._instances[cache_key]
+
+            # 2. Dynamic Discovery if not yet registered
+            if not self.is_registered(component_namespace, component_name):
+                self.discover(component_namespace, component_name)
+
+            if not self.is_registered(component_namespace, component_name):
+                raise RuntimeError(
+                    f"Item '{component_name}' in namespace '{component_namespace}' could not be found in '{self.name}' registry."
+                )
+
+            # 3. Instantiate & initialize class
+            cls = self._registries[component_namespace][component_name]
+
+            # Filter kwargs to match constructor signature
+            if cls.__init__ is object.__init__:
+                valid_kwargs = {}
+                has_config_param = False
+            else:
+                sig = inspect.signature(cls.__init__)
+                has_var_keyword = any(
+                    p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+                )
+                has_config_param = "config" in sig.parameters
+                valid_kwargs = kwargs if has_var_keyword else {
+                    k: v for k, v in kwargs.items() if k in sig.parameters
+                }
+
+            instance = cls(
+                config, **valid_kwargs) if has_config_param else cls(**valid_kwargs)
+
+            # Call lifecycle hook if present
+            if hasattr(instance, "initialize"):
+                init_sig = inspect.signature(instance.initialize)
+                init_has_var_kw = any(
+                    p.kind == inspect.Parameter.VAR_KEYWORD for p in init_sig.parameters.values()
+                )
+                valid_init_kwargs = kwargs if init_has_var_kw else {
+                    k: v for k, v in kwargs.items() if k in init_sig.parameters
+                }
+                instance.initialize(**valid_init_kwargs)
+
+            if hasattr(instance, "boot"):
+                boot_sig = inspect.signature(instance.boot)
+                boot_has_var_kw = any(
+                    p.kind == inspect.Parameter.VAR_KEYWORD for p in boot_sig.parameters.values()
+                )
+                valid_boot_kwargs = kwargs if boot_has_var_kw else {
+                    k: v for k, v in kwargs.items() if k in boot_sig.parameters
+                }
+                instance.boot(**valid_boot_kwargs)
+
+            self._instances[cache_key] = instance
+            return instance
+
+    def list(self, component_namespace: Optional[str] = None) -> Dict[str, Any]:
+        """Lists registered component classes."""
+        with self._lock:
+            if component_namespace:
+                return dict(self._registries.get(component_namespace.lower(), {}))
+            return {k: dict(v) for k, v in self._registries.items()}
+
+    def unload(self, component_namespace: str, component_name: str, **kwargs: Any) -> bool:
+        """Unloads an active instance and calls its disconnect/stop lifecycle hook."""
+        cache_key = self._cache_key(
+            component_namespace, component_name, kwargs)
+        with self._lock:
+            instance = self._instances.pop(cache_key, None)
+
+        if instance is not None:
+            if hasattr(instance, "disconnect"):
+                try:
+                    instance.disconnect(**kwargs)
+                except TypeError:
+                    instance.disconnect()
+            elif hasattr(instance, "stop"):
+                try:
+                    instance.stop(**kwargs)
+                except TypeError:
+                    instance.stop()
+            return True
+        return False
+
+
+SolidRegistry = SuperSolidRegistry
+OpenRegistry = SuperSolidRegistry
+
+
+def super_solid_registry(
+    name: str,
+    component_class: Type[ComponentType],
+    policy: Optional[SecurityPolicy] = None,
+    discovery_strategies: Optional[List[DiscoveryStrategy]] = None,
+    root_package: Optional[str] = None,
+) -> SuperSolidRegistry:
+    return SuperSolidRegistry(
+        name=name,
+        component_class=component_class,
+        policy=policy,
+        discovery_strategies=discovery_strategies,
+        root_package=root_package,
+    )
+
+
+solid_registry = super_solid_registry
+open_registry = super_solid_registry
+
+
+def super_solid_component(registry: SuperSolidRegistry, namespace: str, name: str, **metadata: Any):
+    """
+    Creates a wrapper that will register the decorated class with the registry.
+    Args:
+        namespace (str): The namespace of the decorated class.
+        name (str): The name of the decorated class.
+    """
+    def super_solid_decorator(cls: Type[ComponentType]):
+        cls._metadata = ComponentMetadata(
+            name=name, namespace=namespace, **metadata)
+        registry.register(namespace, name, cls)
+        return cls
+    return super_solid_decorator
+
+
+solid_component = super_solid_component
+open_component = super_solid_component

supersolid/core/security.py

@@ -0,0 +1,38 @@
+import hashlib
+from typing import Set, Optional, Callable
+from pydantic import BaseModel, Field
+
+
+class SecurityPolicy(BaseModel):
+    """Pydantic security policy enforced on an OpenRegistry instance."""
+    allowed_namespaces: Optional[Set[str]] = None
+    allowed_callers: Optional[Set[str]] = None
+    allow_internal_lib: bool = True
+    allow_external_entrypoints: bool = True
+    allow_plugin_discovery: bool = True
+    verifier: Optional[Callable[[str], bool]] = None
+
+    model_config = {
+        "arbitrary_types_allowed": True
+    }
+
+    def validate_access(self, namespace: str, caller_id: Optional[str] = None) -> None:
+        if self.allowed_namespaces is not None and namespace.lower() not in self.allowed_namespaces:
+            raise PermissionError(
+                f"Access denied: Namespace '{namespace}' is restricted by policy."
+            )
+        if self.allowed_callers is not None and caller_id and caller_id.lower() not in self.allowed_callers:
+            raise PermissionError(
+                f"Access denied: Caller '{caller_id}' is not authorized."
+            )
+
+
+class PluginVerifier:
+    """Helper for verifying plugin module checksums prior to import."""
+    @staticmethod
+    def verify_sha256(file_path: str, expected_hash: str) -> bool:
+        hasher = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for chunk in iter(lambda: f.read(4096), b""):
+                hasher.update(chunk)
+        return hasher.hexdigest().lower() == expected_hash.lower()

supersolid/core/system.py

@@ -0,0 +1,97 @@
+import logging
+from abc import ABC
+from typing import Dict, Optional, List
+from graphlib import TopologicalSorter
+
+from supersolid.core.engine import SuperSolidEngine
+from supersolid.core.events import (
+    SuperSolidEventBus,
+    EngineBootingEvent,
+    EngineBootedEvent,
+    EngineShutdownEvent,
+    SystemErrorEvent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SuperSolidSystem(ABC):
+    """
+    Top-Level Orchestrator managing multiple SuperSolidEngines.
+    """
+    engines: Dict[str, SuperSolidEngine]
+    events: SuperSolidEventBus
+
+    def __init__(
+        self,
+        engines: Optional[Dict[str, SuperSolidEngine]] = None,
+        events: Optional[SuperSolidEventBus] = None
+    ):
+        self.engines = engines or {}
+        self.events = events or SuperSolidEventBus()
+
+    def add_engine(self, name: str, engine: SuperSolidEngine) -> None:
+        self.engines[name.lower()] = engine
+
+    def get_engine(self, name: str) -> Optional[SuperSolidEngine]:
+        return self.engines.get(name.lower())
+
+    def start(self) -> None:
+        """Starts all system engines in topological dependency order, rolling back on failure."""
+        order = self._resolve_dependency_order()
+        booted: List[str] = []
+
+        for name in order:
+            engine = self.engines.get(name)
+            if not engine:
+                continue
+            try:
+                self.events.publish(EngineBootingEvent(engine_name=name))
+                engine.boot()
+                booted.append(name)
+                self.events.publish(EngineBootedEvent(engine_name=name))
+            except Exception as e:
+                logger.error(
+                    f"Failed to boot engine '{name}': {e}. Initiating rollback...")
+                self.events.publish(SystemErrorEvent(
+                    context=f"boot:{name}", error=str(e)))
+                for booted_name in reversed(booted):
+                    try:
+                        if self.engines.get(booted_name):
+                            self.engines[booted_name].shutdown()
+                            self.events.publish(
+                                EngineShutdownEvent(engine_name=booted_name))
+                    except Exception as rb_err:
+                        logger.error(
+                            f"Error during rollback shutdown of '{booted_name}': {rb_err}")
+                raise
+
+    def stop(self) -> None:
+        """Shuts down all system engines in reverse topological order, ensuring fault-tolerant cleanup."""
+        order = list(reversed(self._resolve_dependency_order()))
+        for name in order:
+            engine = self.engines.get(name)
+            if not engine:
+                continue
+            try:
+                engine.shutdown()
+                self.events.publish(EngineShutdownEvent(engine_name=name))
+            except Exception as e:
+                logger.error(f"Error shutting down engine '{name}': {e}")
+                self.events.publish(SystemErrorEvent(
+                    context=f"shutdown:{name}", error=str(e)))
+
+    def _resolve_dependency_order(self) -> List[str]:
+        sorter = TopologicalSorter()
+        for name, engine in self.engines.items():
+            # engine.depends_on specifies names of prerequisite engines
+            sorter.add(name.lower(), *[dep.lower()
+                       for dep in engine.depends_on])
+        return list(sorter.static_order())
+
+
+# Aliases
+SolidSystem = SuperSolidSystem
+OpenSystem = SuperSolidSystem
+
+

supersolid/py.typed

@@ -0,0 +1 @@
+