appkit-commons 0.10.0__py3-none-any.whl

appkit_commons/database/sessionmanager.py

@@ -0,0 +1,52 @@
+import contextlib
+from collections.abc import AsyncIterator, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class AsyncSessionManager:
+    def __init__(self, host: str, engine_kwargs: dict[str, Any] | None = None):
+        self._engine = create_async_engine(host, **(engine_kwargs or {}))
+        self._sessionmaker = async_sessionmaker(bind=self._engine)
+
+    async def close(self) -> None:
+        if self._engine:
+            await self._engine.dispose()
+
+    @contextlib.asynccontextmanager
+    async def session(self) -> AsyncIterator[AsyncSession]:
+        async with self._sessionmaker() as session:
+            try:
+                yield session
+                await session.commit()
+            except Exception:
+                await session.rollback()
+                raise
+
+
+class SessionManager:
+    def __init__(self, host: str, engine_kwargs: dict[str, Any] | None = None):
+        self._engine = create_engine(host, **(engine_kwargs or {}))
+        self._sessionmaker = sessionmaker(bind=self._engine)
+
+    def close(self) -> None:
+        if self._engine:
+            self._engine.dispose()
+
+    @contextmanager
+    def session(self) -> Iterator[Session]:
+        with self._sessionmaker() as session:
+            try:
+                yield session
+                session.commit()
+            except Exception:
+                session.rollback()
+                raise

appkit_commons/middleware.py

@@ -0,0 +1,19 @@
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+# Redirect HTTP to HTTPS when behind a proxy (Azure) that sets X-Forwarded-Proto
+class ForceHTTPSMiddleware:
+    def __init__(self, app: ASGIApp):
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send):
+        if scope["type"] in ("http", "websocket"):
+            # Read headers to find X-Forwarded-Proto
+            headers = dict(scope["headers"])
+            # If Azure says it was HTTPS, force the scope to HTTPS
+            if (
+                b"x-forwarded-proto" in headers
+                and headers[b"x-forwarded-proto"] == b"https"
+            ):
+                scope["scheme"] = "https"
+        await self.app(scope, receive, send)

appkit_commons/registry.py

@@ -0,0 +1,188 @@
+import logging
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+if TYPE_CHECKING:
+    from appkit_commons.configuration.configuration import (
+        ApplicationConfig,
+        Configuration,
+    )
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+ConfigT = TypeVar("ConfigT", bound="ApplicationConfig")
+
+
+class ServiceRegistry:
+    """Registry for storing and retrieving initialized instances by their class type."""
+
+    def __init__(self) -> None:
+        self._instances: dict[type[Any], Any] = {}
+
+    def _register_config_recursively(  # noqa: PLR0912
+        self, obj: Any, visited: set[int] | None = None
+    ) -> None:
+        """Recursively register configuration objects and their attributes."""
+        if visited is None:
+            visited = set()
+
+        # Avoid infinite recursion by tracking visited objects
+        obj_id = id(obj)
+        if obj_id in visited:
+            return
+        visited.add(obj_id)
+
+        # Use __dict__ to get instance attributes directly
+        if hasattr(obj, "__dict__"):
+            for attr_name, attr_value in obj.__dict__.items():
+                # Skip private attributes and None values
+                if attr_name.startswith("_") or attr_value is None:
+                    continue
+
+                try:
+                    # Check if this is a configuration object (not a basic type)
+                    if hasattr(attr_value, "__class__"):
+                        attr_class = attr_value.__class__
+
+                        # Skip built-in types, pydantic types, and already registered
+                        if (
+                            attr_class.__module__ != "builtins"
+                            and attr_class.__name__ not in ("SecretStr", "StrEnum")
+                            and not self.has(attr_class)
+                        ):
+                            self.register_as(attr_class, attr_value)
+                            logger.debug(
+                                "Registered service configuration: %s from attribute %s",  # noqa: E501
+                                attr_class.__name__,
+                                attr_name,
+                            )
+
+                            # Recursively register nested configurations
+                            self._register_config_recursively(attr_value, visited)
+
+                except Exception as e:
+                    logger.warning(
+                        "Failed to process attribute %s: %s", attr_name, str(e)
+                    )
+
+        # Also check class annotations to handle properties/descriptors
+        if hasattr(obj.__class__, "__annotations__"):
+            for attr_name in obj.__class__.__annotations__:
+                if attr_name.startswith("_"):
+                    continue
+
+                try:
+                    attr_value = getattr(obj, attr_name, None)
+                    if attr_value is not None and hasattr(attr_value, "__class__"):
+                        attr_class = attr_value.__class__
+
+                        if (
+                            attr_class.__module__ != "builtins"
+                            and attr_class.__name__ not in ("SecretStr", "StrEnum")
+                            and not self.has(attr_class)
+                        ):
+                            self.register_as(attr_class, attr_value)
+                            logger.debug(
+                                "Registered service configuration: %s from annotated attribute %s",  # noqa: E501
+                                attr_class.__name__,
+                                attr_name,
+                            )
+
+                            # Recursively register nested configurations
+                            self._register_config_recursively(attr_value, visited)
+
+                except Exception as e:
+                    logger.warning(
+                        "Failed to access annotated attribute %s: %s", attr_name, str(e)
+                    )
+
+    def configure(
+        self, app_config_class: type[ConfigT], env_file: str = ".env"
+    ) -> "Configuration[ConfigT]":
+        """Configure and register the application configuration."""
+        from appkit_commons.configuration.configuration import (  # noqa: PLC0415
+            Configuration,
+        )
+
+        logger.debug(
+            "Configuring application with config class: %s", app_config_class.__name__
+        )
+
+        # Create the configuration instance
+        configuration = Configuration[app_config_class](_env_file=env_file)
+
+        # Register the configuration instance
+        self.register_as(Configuration, configuration)
+        self._register_config_recursively(configuration)
+
+        logger.info("Application configuration initialized and registered")
+        logger.info("Total registered instances: %d", len(self._instances))
+        for registered_type in self.list_registered():
+            logger.debug("Registered: %s", registered_type.__name__)
+
+        return configuration
+
+    def register(self, instance: object) -> None:
+        """Register an initialized instance using its class type as the key."""
+        instance_type = type(instance)
+
+        if instance_type in self._instances:
+            logger.warning(
+                "Overwriting existing instance of type: %s", instance_type.__name__
+            )
+
+        self._instances[instance_type] = instance
+        logger.debug("Registered instance of type %s", instance_type.__name__)
+
+    def register_as(self, instance_type: type[T], instance: T) -> None:
+        """Register an initialized instance with a specific type as the key."""
+        if instance_type in self._instances:
+            logger.warning(
+                "Overwriting existing instance of type: %s", instance_type.__name__
+            )
+
+        self._instances[instance_type] = instance
+        logger.debug("Registered instance as type %s", instance_type.__name__)
+
+    def get(self, instance_type: type[T]) -> T:
+        """Retrieve an instance by its class type, returning None if not found."""
+        instance: type[T] | None = self._instances.get(instance_type)
+        if instance is None:
+            logger.error(
+                "Instance of type %s not found in registry", instance_type.__name__
+            )
+            raise KeyError(
+                f"Instance of type {instance_type.__name__} not found in registry"
+            )
+        return cast(T, instance)
+
+    def unregister(self, instance_type: type[T]) -> None:
+        """Remove an instance from the registry by its class type."""
+        if instance_type in self._instances:
+            del self._instances[instance_type]
+            logger.debug("Unregistered instance of type: %s", instance_type.__name__)
+        else:
+            logger.warning(
+                "Attempted to unregister non-existent type: %s", instance_type.__name__
+            )
+
+    def list_registered(self) -> list[type[Any]]:
+        """Get a list of all registered class types."""
+        return list(self._instances.keys())
+
+    def has(self, instance_type: type[T]) -> bool:
+        """Check if an instance is registered for the given class type."""
+        return instance_type in self._instances
+
+    def clear(self) -> None:
+        """Clear all registered instances."""
+        count = len(self._instances)
+        self._instances.clear()
+        logger.debug("Cleared %d instances from registry", count)
+
+
+@lru_cache(maxsize=1)
+def service_registry() -> ServiceRegistry:
+    logger.debug("Creating the service registry instance")
+    return ServiceRegistry()

appkit_commons/security.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+SALT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+DEFAULT_PBKDF2_ITERATIONS = 1_000_000
+
+
+def _gen_salt(length: int) -> str:
+    """Generate a random string of SALT_CHARS with specified ``length``."""
+    if length <= 0:
+        raise ValueError("Salt length must be at least 1.")
+
+    return "".join(secrets.choice(SALT_CHARS) for _ in range(length))
+
+
+def _hash_internal(method: str, salt: str, password: str) -> tuple[str, str]:
+    method, *args = method.split(":")
+    salt_bytes = salt.encode()
+    password_bytes = password.encode()
+
+    if method == "scrypt":
+        if not args:
+            n = 2**15
+            r = 8
+            p = 1
+        else:
+            try:
+                n, r, p = map(int, args)
+            except ValueError:
+                raise ValueError("'scrypt' takes 3 arguments.") from None
+
+        maxmem = 132 * n * r * p  # ideally 128, but some extra seems needed
+        return (
+            hashlib.scrypt(
+                password_bytes, salt=salt_bytes, n=n, r=r, p=p, maxmem=maxmem
+            ).hex(),
+            f"scrypt:{n}:{r}:{p}",
+        )
+    if method == "pbkdf2":
+        len_args = len(args)
+
+        if len_args == 0:
+            hash_name = "sha256"
+            iterations = DEFAULT_PBKDF2_ITERATIONS
+        elif len_args == 1:
+            hash_name = args[0]
+            iterations = DEFAULT_PBKDF2_ITERATIONS
+        elif len_args == 2:  # noqa: PLR2004
+            hash_name = args[0]
+            iterations = int(args[1])
+        else:
+            raise ValueError("'pbkdf2' takes 2 arguments.")
+
+        return (
+            hashlib.pbkdf2_hmac(
+                hash_name, password_bytes, salt_bytes, iterations
+            ).hex(),
+            f"pbkdf2:{hash_name}:{iterations}",
+        )
+    raise ValueError(f"Invalid hash method '{method}'.")
+
+
+def generate_password_hash(
+    password: str, method: str = "scrypt", salt_length: int = 16
+) -> str:
+    """Securely hash a password for storage. A password can be compared to a stored hash
+    using :func:`check_password_hash`.
+
+    The following methods are supported:
+
+    -   ``scrypt``, the default. The parameters are ``n``, ``r``, and ``p``, the default
+        is ``scrypt:32768:8:1``. See :func:`hashlib.scrypt`.
+    -   ``pbkdf2``, less secure. The parameters are ``hash_method`` and ``iterations``,
+        the default is ``pbkdf2:sha256:600000``. See :func:`hashlib.pbkdf2_hmac`.
+
+    Default parameters may be updated to reflect current guidelines, and methods may be
+    deprecated and removed if they are no longer considered secure. To migrate old
+    hashes, you may generate a new hash when checking an old hash, or you may contact
+    users with a link to reset their password.
+
+    :param password: The plaintext password.
+    :param method: The key derivation function and parameters.
+    :param salt_length: The number of characters to generate for the salt.
+
+    .. versionchanged:: 3.1
+        The default iterations for pbkdf2 was increased to 1,000,000.
+    """
+    salt = _gen_salt(salt_length)
+    h, actual_method = _hash_internal(method, salt, password)
+    return f"{actual_method}${salt}${h}"
+
+
+def check_password_hash(pwhash: str, password: str) -> bool:
+    """Securely check that the given stored password hash, previously generated using
+    :func:`generate_password_hash`, matches the given password.
+
+    Methods may be deprecated and removed if they are no longer considered secure. To
+    migrate old hashes, you may generate a new hash when checking an old hash, or you
+    may contact users with a link to reset their password.
+
+    :param pwhash: The hashed password.
+    :param password: The plaintext password.
+    """
+    try:
+        method, salt, hashval = pwhash.split("$", 2)
+    except ValueError:
+        return False
+
+    return hmac.compare_digest(_hash_internal(method, salt, password)[0], hashval)