hexastack-fastapi 0.0.0__tar.gz → 0.2.0__tar.gz

hexastack_fastapi-0.0.0/README.md → hexastack_fastapi-0.2.0/PKG-INFO

@@ -1,9 +1,40 @@
+Metadata-Version: 2.4
+Name: hexastack-fastapi
+Version: 0.2.0
+Summary: FastAPI presentation adapter for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: hexastack-auth ; extra == 'auth'
+Requires-Dist: zensical>=0.0.56 ; extra == 'docs'
+Requires-Dist: limits>=3.14.0 ; extra == 'ratelimit'
+Requires-Dist: slowapi>=0.1.9 ; extra == 'ratelimit'
+Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
+Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
+Requires-Dist: nicegui>=2.0.0 ; extra == 'ui'
+Requires-Python: >=3.13
+Provides-Extra: auth
+Provides-Extra: docs
+Provides-Extra: ratelimit
+Provides-Extra: testing
+Provides-Extra: ui
+Description-Content-Type: text/markdown
+
+![hexastack-fastapi](../../docs/assets/static/logos/packages/hexastack_fastapi.png)
+
 # hexastack-fastapi
 
 > FastAPI presentation adapter for Hexastack: automatic CQRS routing, database session middleware, exception mapping, and health check endpoints.
 
+[![PyPI: hexastack-fastapi](https://img.shields.io/pypi/v/hexastack-fastapi.svg)](https://pypi.org/project/hexastack-fastapi/)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_fastapi)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+[![Accessibility: WCAG 2.1 AA](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-brightgreen.svg)](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
+[![Tested with: axe--core](https://img.shields.io/badge/tested%20with-axe--core-4353ff.svg?logo=deque)](https://github.com/dequelabs/axe-core)
 ---
 
 ## 1. Overview & Capabilities
@@ -31,15 +62,17 @@ hexastack_fastapi/
 | Category | Exports |
 |---|---|
 | **Application Factory** | `create_app`, `FastApiBootstrapper` (order=30) |
-| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `RouteMetadata` |
-| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature` |
+| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `@rate_limit`, `RouteMetadata` |
+| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature`, `get_rate_limiter`, `require_rate_limit` |
 | **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
 | **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
 | **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
+| **Rate Limiting** | `SlowapiRateLimiterAdapter`, `get_remote_address`, `get_user_or_ip_key`, `RateLimitConfig` |
 | **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
 | **Routing** | `CqrsRouter`, `autodiscover_routes` |
 | **Testing, E2E & Demo Narration** | `create_test_client`, `check_openapi_conformance`, `EphemeralServer`, `ephemeral_server`, `find_free_port`, `smart_click`, `DemoNarrator`, `VIRTUAL_CURSOR_SCRIPT` |
 
+
 ---
 
 ## 3. Monorepo & Sibling Relationships

hexastack_fastapi-0.0.0/PKG-INFO → hexastack_fastapi-0.2.0/README.md

@@ -1,30 +1,15 @@
-Metadata-Version: 2.3
-Name: hexastack-fastapi
-Version: 0.0.0
-Summary: FastAPI presentation adapter for Hexastack
-Author: Richard West
-Author-email: Richard West <dopplereffect.us@gmail.com>
-Requires-Dist: fastapi>=0.141.1
-Requires-Dist: hexastack-core
-Requires-Dist: hexastack-cqrs
-Requires-Dist: hexastack-auth ; extra == 'auth'
-Requires-Dist: zensical>=0.0.56 ; extra == 'docs'
-Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
-Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
-Requires-Dist: nicegui>=2.0.0 ; extra == 'ui'
-Requires-Python: >=3.13
-Provides-Extra: auth
-Provides-Extra: docs
-Provides-Extra: testing
-Provides-Extra: ui
-Description-Content-Type: text/markdown
+![hexastack-fastapi](../../docs/assets/static/logos/packages/hexastack_fastapi.png)
 
 # hexastack-fastapi
 
 > FastAPI presentation adapter for Hexastack: automatic CQRS routing, database session middleware, exception mapping, and health check endpoints.
 
+[![PyPI: hexastack-fastapi](https://img.shields.io/pypi/v/hexastack-fastapi.svg)](https://pypi.org/project/hexastack-fastapi/)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-
+[![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack_fastapi)](https://codecov.io/github/TheTrueSCU/hexastack)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+[![Accessibility: WCAG 2.1 AA](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-brightgreen.svg)](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
+[![Tested with: axe--core](https://img.shields.io/badge/tested%20with-axe--core-4353ff.svg?logo=deque)](https://github.com/dequelabs/axe-core)
 ---
 
 ## 1. Overview & Capabilities
@@ -52,15 +37,17 @@ hexastack_fastapi/
 | Category | Exports |
 |---|---|
 | **Application Factory** | `create_app`, `FastApiBootstrapper` (order=30) |
-| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `RouteMetadata` |
-| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature` |
+| **Decorators** | `@api_command`, `@api_query`, `@feature_flag_route`, `@rate_limit`, `RouteMetadata` |
+| **Dependencies** | `get_container`, `get_pipeline`, `get_feature_flags`, `require_feature`, `get_rate_limiter`, `require_rate_limit` |
 | **Documentation Mounting** | `mount_zensical_docs`, `DocumentationNotFoundError`, `ZensicalDocsConfig` |
 | **Exception Handlers** | `register_exception_handlers`, `domain_exception_handler` |
 | **Middlewares** | `DbSessionMiddleware`, `AsyncDbSessionMiddleware`, `add_db_session_middleware`, `CorrelationMiddleware`, `HttpLoggingMiddleware` |
+| **Rate Limiting** | `SlowapiRateLimiterAdapter`, `get_remote_address`, `get_user_or_ip_key`, `RateLimitConfig` |
 | **Reactive UI (NiceGUI)** | `dispatch_command`, `dispatch_query`, `mount_devtools_dashboard`, `mount_ui_app`, `ui_page` |
 | **Routing** | `CqrsRouter`, `autodiscover_routes` |
 | **Testing, E2E & Demo Narration** | `create_test_client`, `check_openapi_conformance`, `EphemeralServer`, `ephemeral_server`, `find_free_port`, `smart_click`, `DemoNarrator`, `VIRTUAL_CURSOR_SCRIPT` |
 
+
 ---
 
 ## 3. Monorepo & Sibling Relationships

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/pyproject.toml

@@ -1,8 +1,9 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.0.0"
+version = "0.2.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
+license = "Apache-2.0"
 requires-python = ">=3.13"
 dependencies = [
     "fastapi>=0.141.1",
@@ -17,6 +18,10 @@ email = "dopplereffect.us@gmail.com"
 [project.optional-dependencies]
 auth = ["hexastack-auth"]
 docs = ["zensical>=0.0.56"]
+ratelimit = [
+    "limits>=3.14.0",
+    "slowapi>=0.1.9",
+]
 testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
@@ -41,3 +46,24 @@ workspace = true
 
 [tool.importlinter]
 root_packages = ["hexastack_fastapi"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_fastapi"]
+layers = [
+    "adapters",
+    "infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.adapters"]
+forbidden_modules = ["hexastack_fastapi.testing"]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.infra"]
+forbidden_modules = ["hexastack_fastapi.testing"]

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/pyproject.toml.orig

@@ -1,8 +1,9 @@
 [project]
 name = "hexastack-fastapi"
-version = "0.0.0"
+version = "0.2.0"
 description = "FastAPI presentation adapter for Hexastack"
 readme = "README.md"
+license = "Apache-2.0"
 authors = [
     { name = "Richard West", email = "dopplereffect.us@gmail.com" }
 ]
@@ -20,6 +21,10 @@ auth = [
 docs = [
     "zensical>=0.0.56",
 ]
+ratelimit = [
+    "limits>=3.14.0",
+    "slowapi>=0.1.9",
+]
 testing = [
     "playwright>=1.49.0",
     "schemathesis>=3.39.0",
@@ -28,6 +33,7 @@ ui = [
     "nicegui>=2.0.0",
 ]
 
+
 [project.entry-points."hexastack.bootstrappers"]
 fastapi = "hexastack_fastapi.infra.bootstrap:FastApiBootstrapper"
 
@@ -42,3 +48,28 @@ hexastack-cqrs = { workspace = true }
 
 [tool.importlinter]
 root_packages = ["hexastack_fastapi"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_fastapi"]
+layers = [
+    "adapters",
+    "infra",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for adapters"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.adapters"]
+forbidden_modules = [
+    "hexastack_fastapi.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Forbidden imports for infra"
+type = "forbidden"
+source_modules = ["hexastack_fastapi.infra"]
+forbidden_modules = [
+    "hexastack_fastapi.testing",
+]

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/adapters/__init__.py

@@ -1,17 +1,24 @@
-from hexastack_fastapi.adapters.app import create_fastapi_app
 from hexastack_fastapi.adapters.dependencies import (
     check_openapi_conformance,
     create_test_client,
     get_container,
     get_feature_flags,
     get_pipeline,
+    get_rate_limiter,
     require_feature,
+    require_rate_limit,
 )
 from hexastack_fastapi.adapters.docs import (
     DocumentationNotFoundError,
     mount_zensical_docs,
 )
 from hexastack_fastapi.adapters.health import create_health_router
+from hexastack_fastapi.adapters.ratelimit import (
+    SlowapiRateLimiterAdapter,
+    get_remote_address,
+    get_user_or_ip_key,
+    rate_limit,
+)
 from hexastack_fastapi.adapters.routing import CqrsRouter
 from hexastack_fastapi.adapters.ui import (
     dispatch_command,
@@ -33,9 +40,15 @@ __all__ = [
     "get_container",
     "get_feature_flags",
     "get_pipeline",
+    "get_rate_limiter",
+    "get_remote_address",
+    "get_user_or_ip_key",
     "mount_devtools_dashboard",
     "mount_ui_app",
     "mount_zensical_docs",
+    "rate_limit",
     "require_feature",
+    "require_rate_limit",
+    "SlowapiRateLimiterAdapter",
     "ui_page",
 ]

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/adapters/app.py

@@ -78,6 +78,32 @@ def create_fastapi_app(
     if pipeline is not None:
         app.state.pipeline = pipeline
 
+    # Attach rate limiter if enabled
+    if cfg.ratelimit.enable:
+        try:
+            from hexastack_fastapi.adapters.ratelimit import SlowapiRateLimiterAdapter
+
+            rate_limiter = SlowapiRateLimiterAdapter(
+                default_limits=cfg.ratelimit.default_limits,
+                storage_uri=cfg.ratelimit.storage_uri,
+            )
+            app.state.rate_limiter = rate_limiter
+            if container is not None:
+                from hexastack_core.ports.ratelimit import RateLimiterPort
+
+                container.add_instance(rate_limiter, declared_class=RateLimiterPort)
+        except Exception:
+            # Fall back to InMemoryRateLimiter if slowapi is not installed
+            from hexastack_core.adapters.ratelimit import InMemoryRateLimiter
+            from hexastack_core.ports.ratelimit import RateLimiterPort
+
+            in_memory_limiter = InMemoryRateLimiter()
+            app.state.rate_limiter = in_memory_limiter
+            if container is not None:
+                container.add_instance(
+                    in_memory_limiter, declared_class=RateLimiterPort
+                )
+
     # Attach CORS middleware if enabled
     if cfg.cors.enable:
         app.add_middleware(

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/adapters/dependencies.py

@@ -19,7 +19,9 @@ __all__ = [
     "get_container",
     "get_feature_flags",
     "get_pipeline",
+    "get_rate_limiter",
     "require_feature",
+    "require_rate_limit",
 ]
 
 
@@ -188,3 +190,64 @@ def require_feature(
             )
 
     return _dependency
+
+
+def get_rate_limiter(request: Request) -> Any | None:
+    """FastAPI dependency resolving the registered RateLimiterPort instance if available.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        RateLimiterPort instance from app.state or DI container, or None.
+    """
+    limiter = getattr(request.app.state, "rate_limiter", None)
+    if limiter is not None:
+        return limiter
+
+    container = getattr(request.app.state, "container", None)
+    if isinstance(container, Container):
+        from hexastack_core.ports.ratelimit import RateLimiterPort
+
+        if RateLimiterPort in container:
+            return container.resolve(RateLimiterPort)
+    return None
+
+
+def require_rate_limit(
+    limit: str,
+    *,
+    key_func: Any | None = None,
+    detail: str | None = None,
+) -> Any:
+    """Create a FastAPI dependency that enforces rate limiting on an endpoint.
+
+    Notes/Architectural Intent:
+        Checks rate limit against registered RateLimiterPort. If quota is exceeded,
+        raises an HTTPException with status 429 and Retry-After header.
+
+    Args:
+        limit: Rate limit specification string (e.g. '10/minute').
+        key_func: Optional callable to extract bucket key from request.
+        detail: Optional error message string.
+
+    Returns:
+        A FastAPI dependency callable.
+    """
+    from hexastack_fastapi.adapters.ratelimit import get_user_or_ip_key
+
+    key_extractor = key_func or get_user_or_ip_key
+
+    async def _dependency(request: Request) -> None:
+        limiter = get_rate_limiter(request)
+        if limiter is not None:
+            key = key_extractor(request)
+            if not limiter.hit(key, limit):
+                reset_sec = limiter.get_reset_window(key, limit)
+                raise HTTPException(
+                    status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                    detail=detail or f"Rate limit exceeded: {limit}.",
+                    headers={"Retry-After": str(reset_sec)},
+                )
+
+    return _dependency

hexastack_fastapi-0.2.0/src/hexastack_fastapi/adapters/ratelimit.py

@@ -0,0 +1,208 @@
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from fastapi import HTTPException, Request, status
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_core.ports.ratelimit import RateLimiterPort
+from hexastack_core.utils.context import get_user_context
+
+
+def get_remote_address(request: Request) -> str:
+    """Extract client IP address from FastAPI request headers or client socket.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        Client IP string.
+    """
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    if request.client and request.client.host:
+        return request.client.host
+    return "127.0.0.1"
+
+
+def get_user_or_ip_key(request: Request) -> str:
+    """Extract rate limit bucket key from ambient UserContext or fallback to client IP.
+
+    Args:
+        request: Incoming FastAPI Request object.
+
+    Returns:
+        Rate limit identifier string (e.g. 'user:usr_123', 'tenant:t_456', or 'ip:1.2.3.4').
+    """
+    user_ctx = get_user_context()
+    if user_ctx and user_ctx.user_id:
+        return f"user:{user_ctx.user_id}"
+    if user_ctx and user_ctx.tenant_id:
+        return f"tenant:{user_ctx.tenant_id}"
+    return f"ip:{get_remote_address(request)}"
+
+
+class SlowapiRateLimiterAdapter(RateLimiterPort):
+    """RateLimiterPort implementation backed by slowapi and limits libraries.
+
+    Notes/Architectural Intent:
+        Wraps slowapi Limiter and limits storage backends (memory, redis),
+        enforcing uniform rate limit verification across HTTP endpoints.
+    """
+
+    def __init__(
+        self,
+        key_func: Callable[[Request], str] | None = None,
+        default_limits: list[str] | None = None,
+        storage_uri: str = "memory://",
+    ) -> None:
+        """Initialize SlowapiRateLimiterAdapter.
+
+        Args:
+            key_func: Callable to extract bucket key from Request.
+            default_limits: List of default rate limit strings (e.g. ['100/minute']).
+            storage_uri: Storage URI ('memory://' or 'redis://localhost:6379').
+
+        Raises:
+            MissingDependencyError: If slowapi or limits is not installed.
+        """
+        try:
+            from limits.storage import storage_from_string
+            from slowapi import Limiter
+        except ImportError as e:
+            raise MissingDependencyError(
+                "slowapi and limits are required for SlowapiRateLimiterAdapter. "
+                "Install with 'pip install hexastack-fastapi[ratelimit]'."
+            ) from e
+
+        self._key_func = key_func or get_user_or_ip_key
+        self._default_limits: list[Any] = list(default_limits or ["100/minute"])
+        self._storage: Any = storage_from_string(storage_uri)
+        self._limiter = Limiter(
+            key_func=self._key_func,
+            default_limits=self._default_limits,
+            storage_uri=storage_uri,
+        )
+
+    @property
+    def limiter(self) -> Any:
+        """Underlying slowapi Limiter instance."""
+        return self._limiter
+
+    def hit(self, key: str, limit: str) -> bool:
+        """Record a hit against the rate limit window using limits storage."""
+        from limits import parse
+
+        rate_item = parse(limit)
+        storage: Any = self._storage
+        count = int(storage.incr(rate_item.key_for(key), rate_item.get_expiry()))
+        return count <= rate_item.amount
+
+    def get_reset_window(self, key: str, limit: str) -> int:
+        """Get remaining seconds until rate limit window resets."""
+        from limits import parse
+
+        rate_item = parse(limit)
+        storage: Any = self._storage
+        expiry = float(storage.get_expiry(rate_item.key_for(key)))
+        return max(1, int(expiry)) if expiry > 0 else 0
+
+    def clear(self, key: str | None = None) -> None:
+        """Clear rate limit storage."""
+        storage: Any = self._storage
+        if hasattr(storage, "reset"):
+            storage.reset()
+
+
+def _extract_request(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Request | None:
+    """Extract FastAPI Request instance from positional or keyword arguments."""
+    for v in kwargs.values():
+        if isinstance(v, Request):
+            return v
+    for arg in args:
+        if isinstance(arg, Request):
+            return arg
+    return None
+
+
+def _enforce_rate_limit(
+    request: Request | None,
+    fn_name: str,
+    limit: str,
+    key_extractor: Callable[[Request], str],
+    detail: str | None,
+) -> None:
+    """Check rate limit quota against application rate limiter and raise HTTPException if exceeded."""
+    if request is None:
+        return
+    limiter_port: RateLimiterPort | None = getattr(
+        request.app.state, "rate_limiter", None
+    )
+    if limiter_port is None:
+        return
+
+    base_key = key_extractor(request)
+    key = f"{base_key}:{fn_name}"
+    if not limiter_port.hit(key, limit):
+        reset_sec = limiter_port.get_reset_window(key, limit)
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=detail or f"Rate limit exceeded: {limit}.",
+            headers={"Retry-After": str(reset_sec)},
+        )
+
+
+def rate_limit(
+    limit: str,
+    key_func: Callable[[Request], str] | None = None,
+    detail: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator guarding a FastAPI route endpoint with rate limiting.
+
+    Notes/Architectural Intent:
+        Enforces rate limits on endpoint execution. If quota is exceeded,
+        raises an HTTPException with status 429 Too Many Requests and
+        includes a 'Retry-After' header.
+
+    Args:
+        limit: Rate limit specification string (e.g. '5/minute', '10/second').
+        key_func: Optional custom callable to extract bucket key from request.
+        detail: Optional error detail message.
+
+    Returns:
+        Decorator wrapping the endpoint function.
+    """
+    key_extractor = key_func or get_user_or_ip_key
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        fn_name = getattr(fn, "__name__", "endpoint")
+
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapped(*args: Any, **kwargs: Any) -> Any:
+                req = _extract_request(args, kwargs)
+                _enforce_rate_limit(req, fn_name, limit, key_extractor, detail)
+                return await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @wraps(fn)
+        def sync_wrapped(*args: Any, **kwargs: Any) -> Any:
+            req = _extract_request(args, kwargs)
+            _enforce_rate_limit(req, fn_name, limit, key_extractor, detail)
+            return fn(*args, **kwargs)
+
+        return sync_wrapped
+
+    return decorator
+
+
+__all__ = [
+    "get_remote_address",
+    "get_user_or_ip_key",
+    "rate_limit",
+    "SlowapiRateLimiterAdapter",
+]

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/adapters/routing.py

@@ -29,6 +29,7 @@ class CqrsRouter(APIRouter):
         summary: str | None = None,
         tags: list[str | Enum] | None = None,
         feature_flag: str | None = None,
+        rate_limit: str | None = None,
     ) -> None:
         """Register an HTTP endpoint for executing a domain Command.
 
@@ -41,6 +42,7 @@ class CqrsRouter(APIRouter):
             summary: Optional OpenAPI summary string.
             tags: Optional OpenAPI tags list.
             feature_flag: Optional feature flag key required for endpoint execution.
+            rate_limit: Optional rate limit string (e.g. '10/minute').
 
         Returns:
             None.
@@ -54,6 +56,10 @@ class CqrsRouter(APIRouter):
             from hexastack_fastapi.adapters.dependencies import require_feature
 
             dependencies.append(Depends(require_feature(feature_flag)))
+        if rate_limit:
+            from hexastack_fastapi.adapters.dependencies import require_rate_limit
+
+            dependencies.append(Depends(require_rate_limit(rate_limit)))
 
         self.add_api_route(
             path=path,
@@ -77,6 +83,7 @@ class CqrsRouter(APIRouter):
         summary: str | None = None,
         tags: list[str | Enum] | None = None,
         feature_flag: str | None = None,
+        rate_limit: str | None = None,
     ) -> None:
         """Register an HTTP endpoint for executing a domain Query.
 
@@ -89,6 +96,7 @@ class CqrsRouter(APIRouter):
             summary: Optional OpenAPI summary string.
             tags: Optional OpenAPI tags list.
             feature_flag: Optional feature flag key required for endpoint execution.
+            rate_limit: Optional rate limit string (e.g. '10/minute').
 
         Returns:
             None.
@@ -102,6 +110,10 @@ class CqrsRouter(APIRouter):
             from hexastack_fastapi.adapters.dependencies import require_feature
 
             dependencies.append(Depends(require_feature(feature_flag)))
+        if rate_limit:
+            from hexastack_fastapi.adapters.dependencies import require_rate_limit
+
+            dependencies.append(Depends(require_rate_limit(rate_limit)))
 
         self.add_api_route(
             path=path,

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/adapters/ui.py

@@ -229,15 +229,22 @@ def _render_middleware_chain(middlewares: list[Any]) -> None:
                 ui.chip(
                     f"{idx}. {mw_name}",
                     icon="security" if "Auth" in mw_name else "filter_alt",
-                ).classes(
-                    "bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-200"
-                )
+                    color="blue-9",
+                    text_color="white",
+                ).classes("font-medium")
                 if idx < len(middlewares):
-                    ui.icon("arrow_forward", size="sm").classes("text-slate-400")
-            ui.icon("arrow_forward", size="sm").classes("text-slate-400")
-            ui.chip("Handler Execution", icon="play_circle").classes(
-                "bg-emerald-100 text-emerald-800 dark:bg-emerald-900 dark:text-emerald-200 font-bold"
+                    ui.icon("arrow_forward", size="sm").classes(
+                        "text-slate-600 dark:text-slate-300"
+                    )
+            ui.icon("arrow_forward", size="sm").classes(
+                "text-slate-600 dark:text-slate-300"
             )
+            ui.chip(
+                "Handler Execution",
+                icon="play_circle",
+                color="green-9",
+                text_color="white",
+            ).classes("font-bold")
     else:
         ui.label("No active middlewares attached to CommandBus.").classes(
             "text-slate-500 italic mb-6"
@@ -315,9 +322,9 @@ def _render_live_runner(
                 except Exception as exc:
                     log_output.push(f"❌ [ERROR] Execution failed: {exc}")
 
-            ui.button("Dispatch Ping Command", on_click=_run_ping, icon="send").classes(
-                "bg-blue-600 text-white"
-            )
+            ui.button(
+                "Dispatch Ping Command", on_click=_run_ping, icon="send", color="blue-9"
+            ).classes("text-white font-medium shadow-sm")
 
 
 def _render_cqrs_tab(
@@ -366,15 +373,16 @@ def _render_flags_tab(container: Container) -> None:
                 ],
                 rows=flag_rows,
                 row_key="flag",
+                pagination={"rowsPerPage": 10},
             ).classes("w-full")
         else:
             ui.label("No feature flags currently configured in provider.").classes(
-                "text-slate-500 italic"
+                "text-slate-600 dark:text-slate-400 italic"
             )
     else:
         ui.label(
             "Feature flag provider not available or does not support listing."
-        ).classes("text-slate-500 italic")
+        ).classes("text-slate-600 dark:text-slate-400 italic")
 
 
 def _render_container_tab(container: Container) -> None:
@@ -427,10 +435,11 @@ def _render_container_tab(container: Container) -> None:
             ],
             rows=services,
             row_key="service",
+            pagination={"rowsPerPage": 10},
         ).classes("w-full")
     else:
         ui.label("No direct services found in container introspection.").classes(
-            "text-slate-500 italic"
+            "text-slate-600 dark:text-slate-400 italic"
         )
 
 
@@ -465,7 +474,7 @@ def mount_devtools_dashboard(
 
     @ui.page(path, title=title)
     def devtools_page():
-        ui.colors(primary="#3B82F6", secondary="#10B981", accent="#8B5CF6")
+        ui.colors(primary="#1E40AF", secondary="#065F46", accent="#5B21B6")
 
         with ui.header().classes(
             "items-center justify-between bg-slate-900 text-white px-6 py-3"
@@ -473,7 +482,9 @@ def mount_devtools_dashboard(
             with ui.row().classes("items-center gap-3"):
                 ui.icon("layers", size="md").classes("text-blue-400")
                 ui.label(title).classes("text-xl font-bold tracking-tight")
-            ui.badge("v0.1.0", color="blue").classes("text-xs")
+            ui.badge("v0.1.0", color="blue-10").classes(
+                "text-xs font-semibold text-white"
+            )
 
         with ui.tabs().classes("w-full bg-slate-100 dark:bg-slate-800") as tabs:
             tab_cqrs = ui.tab("CQRS Registry", icon="bolt")

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/infra/autodiscovery.py

@@ -87,6 +87,7 @@ def create_route_visitor(router: CqrsRouter) -> DiscoveryVisitor:
                 summary=meta.summary,
                 tags=tags,
                 feature_flag=meta.feature_flag,
+                rate_limit=meta.rate_limit,
             )
         elif meta.kind == "query" and isinstance(obj, type) and issubclass(obj, Query):
             router.add_query(
@@ -98,6 +99,7 @@ def create_route_visitor(router: CqrsRouter) -> DiscoveryVisitor:
                 summary=meta.summary,
                 tags=tags,
                 feature_flag=meta.feature_flag,
+                rate_limit=meta.rate_limit,
             )
 
     return visitor

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/infra/config.py

@@ -49,6 +49,26 @@ class RequestLoggingConfig(BaseModel):
     )
 
 
+class RateLimitConfig(BaseModel):
+    """Configuration schema for rate limiting and request quota enforcement.
+
+    Notes/Architectural Intent:
+        Controls global and endpoint-level rate limits, key extraction strategy
+        (IP, user_id, tenant_id), and storage backend connection.
+    """
+
+    enable: bool = Field(default=False)
+    default_limits: list[str] = Field(default_factory=lambda: ["100/minute"])
+    key_func: str = Field(
+        default="ip",
+        description="Key extraction strategy: 'ip', 'user', 'tenant', or 'combined'.",
+    )
+    storage_uri: str = Field(
+        default="memory://",
+        description="Backend storage URI: 'memory://' or 'redis://localhost:6379'.",
+    )
+
+
 class ZensicalDocsConfig(BaseModel):
     """Configuration schema for mounting pre-built Zensical documentation onto FastAPI.
 
@@ -83,6 +103,7 @@ class HexastackFastApiConfig(BaseModel):
     cors: CorsConfig = Field(default_factory=CorsConfig)
     health: HealthConfig = Field(default_factory=HealthConfig)
     logging: RequestLoggingConfig = Field(default_factory=RequestLoggingConfig)
+    ratelimit: RateLimitConfig = Field(default_factory=RateLimitConfig)
     zensical: ZensicalDocsConfig = Field(default_factory=ZensicalDocsConfig)
     auto_register_routes: bool = Field(default=True)
     packages_to_scan: list[str] = Field(default_factory=list)
@@ -92,6 +113,7 @@ __all__ = [
     "CorsConfig",
     "HealthConfig",
     "HexastackFastApiConfig",
+    "RateLimitConfig",
     "register_fastapi_config",
     "RequestLoggingConfig",
     "ZensicalDocsConfig",

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/infra/decorators.py

@@ -1,10 +1,13 @@
 from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Literal
+from typing import Any, Literal, TypeVar
 
 from hexastack_core.domain import Command, Query
 
+TCommand = TypeVar("TCommand", bound=Command)
+TQuery = TypeVar("TQuery", bound=Query)
+
 _ROUTE_METADATA_ATTR = "__hexastack_route__"
 
 
@@ -14,7 +17,7 @@ class RouteMetadata:
 
     Notes/Architectural Intent:
         Carries routing parameters attached by decorators for automated endpoint registration,
-        including optional feature flag gating.
+        including optional feature flag gating and rate limiting.
     """
 
     path: str
@@ -25,6 +28,7 @@ class RouteMetadata:
     summary: str | None = None
     tags: tuple[str | Enum, ...] | None = None
     feature_flag: str | None = None
+    rate_limit: str | None = None
 
 
 __all__ = [
@@ -35,7 +39,7 @@ __all__ = [
 ]
 
 
-def api_command[TCommand: Command](
+def api_command(
     path: str,
     *,
     method: str = "POST",
@@ -44,6 +48,7 @@ def api_command[TCommand: Command](
     summary: str | None = None,
     tags: list[str | Enum] | None = None,
     feature_flag: str | None = None,
+    rate_limit: str | None = None,
 ) -> Callable[[type[TCommand]], type[TCommand]]:
     """Decorator marking a Command class for automatic HTTP endpoint exposure.
 
@@ -55,6 +60,7 @@ def api_command[TCommand: Command](
         summary: Optional OpenAPI summary.
         tags: Optional OpenAPI tags list.
         feature_flag: Optional feature flag key required for route access.
+        rate_limit: Optional rate limit string (e.g. '10/minute').
 
     Returns:
         Decorated Command class with attached routing metadata.
@@ -73,6 +79,7 @@ def api_command[TCommand: Command](
             summary=summary,
             tags=tuple(tags) if tags else None,
             feature_flag=feature_flag,
+            rate_limit=rate_limit,
         )
         setattr(cls, _ROUTE_METADATA_ATTR, meta)
         return cls
@@ -80,7 +87,7 @@ def api_command[TCommand: Command](
     return decorator
 
 
-def api_query[TQuery: Query](
+def api_query(
     path: str,
     *,
     method: str = "GET",
@@ -89,6 +96,7 @@ def api_query[TQuery: Query](
     summary: str | None = None,
     tags: list[str | Enum] | None = None,
     feature_flag: str | None = None,
+    rate_limit: str | None = None,
 ) -> Callable[[type[TQuery]], type[TQuery]]:
     """Decorator marking a Query class for automatic HTTP endpoint exposure.
 
@@ -100,6 +108,7 @@ def api_query[TQuery: Query](
         summary: Optional OpenAPI summary.
         tags: Optional OpenAPI tags list.
         feature_flag: Optional feature flag key required for route access.
+        rate_limit: Optional rate limit string (e.g. '10/minute').
 
     Returns:
         Decorated Query class with attached routing metadata.
@@ -118,6 +127,7 @@ def api_query[TQuery: Query](
             summary=summary,
             tags=tuple(tags) if tags else None,
             feature_flag=feature_flag,
+            rate_limit=rate_limit,
         )
         setattr(cls, _ROUTE_METADATA_ATTR, meta)
         return cls

{hexastack_fastapi-0.0.0 → hexastack_fastapi-0.2.0}/src/hexastack_fastapi/infra/exception_handlers.py

@@ -47,7 +47,17 @@ def register_exception_handlers(
             status_code = 404
         elif "conflict" in exc_name or "duplicate" in exc_name:
             status_code = 409
-        elif "unauthorized" in exc_name or "forbidden" in exc_name:
+        elif (
+            "permission" in exc_name
+            or "forbidden" in exc_name
+            or "accessdenied" in exc_name
+        ):
+            status_code = 403
+        elif (
+            "unauthorized" in exc_name
+            or "unauthenticated" in exc_name
+            or "invalidcredential" in exc_name
+        ):
             status_code = 401
         elif "validation" in exc_name:
             status_code = 422