python-flashapi 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

flashapi/adapters/django.py

@@ -9,9 +9,10 @@ from flashapi.core.custom_routes import (
 )
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.docs.openapi import generate_openapi_schema, get_swagger_html
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
+from flashapi.features.health import get_health_check
 from flashapi.inspectors import inspect_model
 from flashapi.storage.orm import DjangoORMStorage
 
@@ -77,6 +78,7 @@ def generate_urls(
         schema.scope = wrapper.scope
         schema.tenant_field = wrapper.tenant_field
         schema.owner_field = wrapper.owner_field
+        schema.current_user_field = wrapper.current_user_field
 
         from flashapi.core.schema import validate_soft_delete
         validate_soft_delete(wrapper.model_class, wrapper.soft_delete)
@@ -113,6 +115,7 @@ def generate_urls(
         ))
 
     urlpatterns.extend(_create_api_root_view(all_schemas, docs))
+    urlpatterns.extend(_create_health_views())
 
     return urlpatterns
 
@@ -264,6 +267,7 @@ def _create_django_views(
     model_scope = schema.scope
     model_tenant_field = schema.tenant_field
     model_owner_field = schema.owner_field
+    model_current_user_field = schema.current_user_field
     patterns = []
 
     def _check_auth(request, operation):
@@ -333,6 +337,7 @@ def _create_django_views(
                 sort = params.get("sort")
                 search = params.get("search")
                 deleted_param = params.get("deleted", "false").lower() == "true"
+                fields_param = params.get("fields")  # Field selection: ?fields=id,name,price
 
                 only_deleted = deleted_param and supports_soft_delete
                 items = storage.list_all(_table, only_deleted=only_deleted)
@@ -348,6 +353,12 @@ def _create_django_views(
                 items = apply_sorting(items, sort, _fields)
                 page_items, total = paginate(items, page, size)
                 page_items = [filter_response(item, _schema) for item in page_items]
+
+                # Apply field selection if ?fields parameter provided
+                if fields_param:
+                    field_list = [f.strip() for f in fields_param.split(",")]
+                    page_items = [select_fields(item, field_list, _schema) for item in page_items]
+
                 if metrics:
                     metrics.record("READ", entity_name)
                 return JsonResponse(
@@ -369,6 +380,24 @@ def _create_django_views(
                 if scope_filter:
                     data.update(scope_filter)
 
+                # Auto-inject current user if current_user_field specified
+                if model_current_user_field and user and auth_backend:
+                    user_id = auth_backend.get_owner_id(user)
+                    if user_id is not None:
+                        # For ForeignKey fields, Django expects field_id
+                        # For non-FK fields, use field directly
+                        # Try FK syntax first (most common case)
+                        try:
+                            storage._model._meta.get_field(model_current_user_field)
+                            field = storage._model._meta.get_field(model_current_user_field)
+                            if field.many_to_one:  # ForeignKey
+                                data[f"{model_current_user_field}_id"] = user_id
+                            else:
+                                data[model_current_user_field] = user_id
+                        except Exception:
+                            # Fallback: assume FK
+                            data[f"{model_current_user_field}_id"] = user_id
+
                 item = storage.create(_table, data)
                 if metrics:
                     metrics.record("CREATE", entity_name, str(item.get("id", "")))
@@ -659,6 +688,13 @@ def _create_django_views(
                     return JsonResponse(create_error_response("Not found", 404), status=404)
 
                 item = filter_response(item, _schema)
+
+                # Apply field selection if ?fields parameter provided
+                fields_param = request.GET.get("fields")
+                if fields_param:
+                    field_list = [f.strip() for f in fields_param.split(",")]
+                    item = select_fields(item, field_list, _schema)
+
                 return JsonResponse(create_item_response(item, formatter))
 
             if request.method == "PUT" and "update" in _schema.permissions:
@@ -769,3 +805,38 @@ def _create_django_views(
             patterns.append(path(f"{table}/<str:item_id>/history/", history_view, name=f"{table}_history"))
 
     return patterns
+
+
+def _create_health_views():
+    """Create health check views for production monitoring."""
+    from django.http import JsonResponse
+    from django.urls import path
+
+    health_check = get_health_check()
+
+    def liveness_view(request):
+        """Liveness probe — is the application running?"""
+        return JsonResponse(health_check.liveness())
+
+    def readiness_view(request):
+        """Readiness probe — is the application ready to serve traffic?"""
+        data, status_code = health_check.readiness()
+        return JsonResponse(data, status=status_code)
+
+    # Register database check for Django ORM
+    def check_database():
+        try:
+            from django.db import connection
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT 1")
+            return True
+        except Exception:
+            return False
+
+    health_check.register_check("database", check_database)
+    health_check.mark_ready()
+
+    return [
+        path("health/", liveness_view, name="health_liveness"),
+        path("ready/", readiness_view, name="health_readiness"),
+    ]

flashapi/adapters/fastapi.py

@@ -10,10 +10,11 @@ from pydantic import BaseModel, create_model
 from flashapi.core.relations import find_expandable_fields, resolve_relations
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import FieldType, Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
 from flashapi.features.dashboard import DASHBOARD_HTML, MetricsCollector
 from flashapi.features.export import CONTENT_TYPES, EXPORTERS
+from flashapi.features.health import get_health_check
 from flashapi.inspectors import inspect_model
 from flashapi.storage.auto import AutoStorage
 from flashapi.storage.sqlalchemy import SQLAlchemyStorage
@@ -143,6 +144,7 @@ class FlashAPI:
         self._add_dashboard_routes()
         self._add_websocket_route()
         self._add_api_root()
+        self._add_health_routes()
 
     def _prepare_model(self, model_entry) -> None:
         wrapper = model_entry if isinstance(model_entry, Model) else Model(model_entry)
@@ -248,6 +250,36 @@ class FlashAPI:
             }
             return {"resources": resources, "links": links}
 
+    def _add_health_routes(self) -> None:
+        """Add health check endpoints for production monitoring."""
+        health_check = get_health_check()
+
+        @self._app.get("/health", tags=["Health"], include_in_schema=False)
+        async def liveness():
+            """Liveness probe — is the application running?"""
+            return health_check.liveness()
+
+        @self._app.get("/ready", tags=["Health"], include_in_schema=False)
+        async def readiness():
+            """Readiness probe — is the application ready to serve traffic?"""
+            data, status_code = health_check.readiness()
+            return JSONResponse(content=data, status_code=status_code)
+
+        # Register database check if using SQLAlchemy
+        if self._session_factory:
+            def check_database():
+                try:
+                    session = self._session_factory()
+                    session.execute("SELECT 1")
+                    session.close()
+                    return True
+                except Exception:
+                    return False
+            health_check.register_check("database", check_database)
+
+        # Mark ready after all routes are registered
+        health_check.mark_ready()
+
     def _add_rate_limit_middleware(self) -> None:
         from starlette.middleware.base import BaseHTTPMiddleware
 
@@ -418,6 +450,13 @@ class FlashAPI:
 
             metrics.record("READ", tag)
             page_items = [filter_response(item, model_schema) for item in page_items]
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.query_params.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                page_items = [select_fields(item, field_list, model_schema) for item in page_items]
+
             return create_list_response(page_items, total, page, size, formatter)
 
     def _add_read_route(self, table, formatter, storage, tag, expandable, model_schema, lookup_field="id") -> None:
@@ -449,6 +488,13 @@ class FlashAPI:
                 item = self._expand_items([item], expand, expandable)[0]
 
             item = filter_response(item, model_schema)
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.query_params.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                item = select_fields(item, field_list, model_schema)
+
             return create_item_response(item, formatter)
 
     def _add_history_route(self, table, entity_name, lookup_field="id", model_schema=None) -> None:

flashapi/adapters/flask.py

@@ -10,9 +10,10 @@ from flashapi.core.custom_routes import (
 from flashapi.core.relations import find_expandable_fields, resolve_relations
 from flashapi.core.response import create_error_response, create_item_response, create_list_response
 from flashapi.core.schema import Model, ModelSchema
-from flashapi.core.visibility import export_fields, filter_response, writable_fields
+from flashapi.core.visibility import export_fields, filter_response, select_fields, writable_fields
 from flashapi.docs.openapi import generate_openapi_schema, get_swagger_html
 from flashapi.features import apply_filters, apply_search, apply_sorting, paginate
+from flashapi.features.health import get_health_check
 from flashapi.inspectors import inspect_model
 from flashapi.storage.auto import AutoStorage
 from flashapi.storage.sqlalchemy import SQLAlchemyStorage
@@ -138,6 +139,7 @@ def register_models(
         _add_docs_routes(blueprint, all_schemas, custom_routes or [], flask_app=app)
 
     _add_api_root_route(blueprint, all_schemas, base_path, docs)
+    _add_health_routes(app, session_factory)
 
     app.register_blueprint(blueprint)
 
@@ -439,6 +441,13 @@ def _create_flask_routes(
             if _metrics:
                 _metrics.record("READ", entity_name)
             page_items = [filter_response(item, _schema) for item in page_items]
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.args.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                page_items = [select_fields(item, field_list, _schema) for item in page_items]
+
             return jsonify(create_list_response(page_items, total, page, size, formatter))
 
     if "read" in schema.permissions:
@@ -461,6 +470,13 @@ def _create_flask_routes(
                 item = _expand_items([item], expand, _exp, storage)[0]
 
             item = filter_response(item, _schema)
+
+            # Apply field selection if ?fields parameter provided
+            fields_param = request.args.get("fields")
+            if fields_param:
+                field_list = [f.strip() for f in fields_param.split(",")]
+                item = select_fields(item, field_list, _schema)
+
             return jsonify(create_item_response(item, formatter))
 
     if "read" in schema.permissions and entity_audit:
@@ -726,3 +742,35 @@ def _create_flask_routes(
                 mimetype=CONTENT_TYPES[fmt],
                 headers={"Content-Disposition": f'attachment; filename="{_table}.{fmt}"'},
             )
+
+
+def _add_health_routes(app, session_factory) -> None:
+    """Add health check endpoints for production monitoring."""
+    from flask import jsonify
+    health_check = get_health_check()
+
+    @app.route("/health")
+    def liveness():
+        """Liveness probe — is the application running?"""
+        return jsonify(health_check.liveness())
+
+    @app.route("/ready")
+    def readiness():
+        """Readiness probe — is the application ready to serve traffic?"""
+        data, status_code = health_check.readiness()
+        return jsonify(data), status_code
+
+    # Register database check if using SQLAlchemy
+    if session_factory:
+        def check_database():
+            try:
+                session = session_factory()
+                session.execute("SELECT 1")
+                session.close()
+                return True
+            except Exception:
+                return False
+        health_check.register_check("database", check_database)
+
+    # Mark ready after all routes are registered
+    health_check.mark_ready()

flashapi/core/custom_routes.py

@@ -121,6 +121,8 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
     """Scan Django URL patterns for @api_doc-decorated views and build OpenAPI paths."""
     paths: dict[str, dict] = {}
 
+    import re
+
     for pattern in url_patterns:
         callback = getattr(pattern, "callback", None)
         if callback is None:
@@ -130,8 +132,9 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
         if doc is None:
             continue
 
-        # Build path from Django pattern
+        # Build path from Django pattern, converting <type:name> to {name}
         path_str = "/" + str(pattern.pattern)
+        path_str = re.sub(r"<(?:\w+:)?(\w+)>", r"{\1}", path_str)
         if trailing_slash and not path_str.endswith("/"):
             path_str += "/"
 
@@ -143,8 +146,27 @@ def discover_django_views(url_patterns, trailing_slash: bool = True) -> dict[str
         if path_str not in paths:
             paths[path_str] = {}
 
+        # Extract path parameters from URL pattern
+        path_params = re.findall(r"\{(\w+)\}", path_str)
+
         for method in methods:
-            paths[path_str][method] = _build_openapi_operation(doc, method)
+            operation = _build_openapi_operation(doc, method)
+            if path_params:
+                if "parameters" not in operation:
+                    operation["parameters"] = []
+                # Remove any query params that are actually path params
+                operation["parameters"] = [
+                    p for p in operation["parameters"] if p["name"] not in path_params
+                ]
+                for pname in path_params:
+                    ptype = doc.get("params", {}).get(pname, "string") if doc.get("params") else "string"
+                    operation["parameters"].append({
+                        "name": pname,
+                        "in": "path",
+                        "required": True,
+                        "schema": TYPE_MAP.get(ptype, {"type": "string"}),
+                    })
+            paths[path_str][method] = operation
 
     return paths
 

flashapi/core/schema.py

@@ -59,6 +59,7 @@ class ModelSchema:
     scope: str | None = None  # "tenant", "owner", or "both"
     tenant_field: str | None = None
     owner_field: str | None = None
+    current_user_field: str | None = None  # Auto-inject authenticated user on CREATE
 
 
 ALL_OPERATIONS = ["list", "read", "create", "update", "delete"]
@@ -112,12 +113,13 @@ class Model:
         only: list[str] | None = None,
         plural: str | None = None,
         soft_delete: bool = False,
-        audit: bool = False,
+        audit: bool = True,  # Enabled by default for full traceability
         lookup_field: str = "id",
         access: str | dict | bool | None = None,
         scope: str | None = None,
         tenant_field: str | None = None,
         owner_field: str | None = None,
+        current_user_field: str | None = None,
     ) -> None:
         self.model_class = model_class
         self.plural = plural
@@ -128,6 +130,7 @@ class Model:
         self.scope = scope
         self.tenant_field = tenant_field
         self.owner_field = owner_field
+        self.current_user_field = current_user_field
         self.permissions = self._resolve_permissions(readonly, exclude, only)
 
     def _resolve_permissions(

flashapi/core/visibility.py

@@ -44,3 +44,39 @@ def filter_input(data: dict, schema: ModelSchema) -> dict:
     """Remove readonly/hidden fields from input dict."""
     allowed = writable_fields(schema)
     return {k: v for k, v in data.items() if k in allowed}
+
+
+def select_fields(data: dict, fields: list[str] | None, schema: ModelSchema) -> dict:
+    """
+    Select only requested fields from response data.
+
+    Field selection (?fields=id,name,price) allows clients to request only specific fields,
+    reducing payload size and improving performance.
+
+    Args:
+        data: Response dict to filter
+        fields: List of field names to include (None = return all visible fields)
+        schema: Model schema for validation
+
+    Returns:
+        Dict containing only requested fields that exist and are visible (id always included)
+
+    Example:
+        >>> select_fields({"id": 1, "name": "Laptop", "price": 999, "stock": 10}, ["name"], schema)
+        {"id": 1, "name": "Laptop"}  # id always included
+    """
+    if not fields:
+        return data
+
+    # Get visible fields from schema
+    visible = response_fields(schema)
+
+    # Filter: requested fields + always include id
+    result = {}
+    for k, v in data.items():
+        if k == "id":
+            result[k] = v  # Always include id
+        elif k in fields and k in visible:
+            result[k] = v
+
+    return result

flashapi/features/cache.py

@@ -0,0 +1,229 @@
+"""
+Cache layer for FlashAPI with graceful fallback.
+
+Prevents Bug #4 (cache failure crash) by catching exceptions and continuing without cache.
+Supports Redis, Memcached, and in-memory stores.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CacheBackend(ABC):
+    """Abstract cache interface."""
+
+    @abstractmethod
+    def get(self, key: str) -> Any | None:
+        """Get value from cache. Returns None if not found or error."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl: int = 300) -> bool:
+        """Set value in cache with TTL (seconds). Returns success."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str) -> bool:
+        """Delete key from cache. Returns success."""
+        ...
+
+    @abstractmethod
+    def clear(self) -> bool:
+        """Clear all cache. Returns success."""
+        ...
+
+
+class InMemoryCache(CacheBackend):
+    """In-memory cache (for development/testing)."""
+
+    def __init__(self):
+        self._store: dict[str, tuple[Any, float]] = {}  # {key: (value, expire_at)}
+
+    def get(self, key: str) -> Any | None:
+        if key not in self._store:
+            return None
+        value, expire_at = self._store[key]
+        if time.time() > expire_at:
+            del self._store[key]
+            return None
+        return value
+
+    def set(self, key: str, value: Any, ttl: int = 300) -> bool:
+        self._store[key] = (value, time.time() + ttl)
+        return True
+
+    def delete(self, key: str) -> bool:
+        if key in self._store:
+            del self._store[key]
+            return True
+        return False
+
+    def clear(self) -> bool:
+        self._store.clear()
+        return True
+
+
+class RedisCache(CacheBackend):
+    """Redis cache with graceful fallback."""
+
+    def __init__(self, host: str = "localhost", port: int = 6379, db: int = 0):
+        try:
+            import redis
+            self._redis = redis.Redis(host=host, port=port, db=db, decode_responses=True)
+            self._redis.ping()  # Test connection
+            self._available = True
+        except Exception:
+            self._redis = None
+            self._available = False
+
+    def get(self, key: str) -> Any | None:
+        if not self._available:
+            return None
+        try:
+            value = self._redis.get(key)
+            if value is None:
+                return None
+            return json.loads(value)
+        except Exception:
+            return None
+
+    def set(self, key: str, value: Any, ttl: int = 300) -> bool:
+        if not self._available:
+            return False
+        try:
+            self._redis.setex(key, ttl, json.dumps(value))
+            return True
+        except Exception:
+            return False
+
+    def delete(self, key: str) -> bool:
+        if not self._available:
+            return False
+        try:
+            self._redis.delete(key)
+            return True
+        except Exception:
+            return False
+
+    def clear(self) -> bool:
+        if not self._available:
+            return False
+        try:
+            self._redis.flushdb()
+            return True
+        except Exception:
+            return False
+
+
+class CacheLayer:
+    """
+    Cache layer with graceful fallback for FlashAPI.
+
+    Usage:
+        from flashapi.features.cache import CacheLayer, RedisCache
+
+        cache = CacheLayer(RedisCache(host='localhost'))
+
+        # Get (never crashes)
+        value = cache.get('users:123')  # Returns None if cache down
+
+        # Set (never crashes)
+        cache.set('users:123', {'name': 'John'}, ttl=600)
+
+    Features:
+        - Automatic exception handling (never crashes app)
+        - Graceful fallback if cache unavailable
+        - Logging for debugging
+    """
+
+    def __init__(self, backend: CacheBackend | None = None, log_errors: bool = True):
+        self.backend = backend or InMemoryCache()
+        self.log_errors = log_errors
+
+    def get(self, key: str) -> Any | None:
+        """Get value from cache. Never crashes."""
+        try:
+            return self.backend.get(key)
+        except Exception as e:
+            if self.log_errors:
+                print(f"[FlashAPI Cache] GET error: {e}")
+            return None
+
+    def set(self, key: str, value: Any, ttl: int = 300) -> bool:
+        """Set value in cache. Never crashes."""
+        try:
+            return self.backend.set(key, value, ttl)
+        except Exception as e:
+            if self.log_errors:
+                print(f"[FlashAPI Cache] SET error: {e}")
+            return False
+
+    def delete(self, key: str) -> bool:
+        """Delete key from cache. Never crashes."""
+        try:
+            return self.backend.delete(key)
+        except Exception as e:
+            if self.log_errors:
+                print(f"[FlashAPI Cache] DELETE error: {e}")
+            return False
+
+    def clear(self) -> bool:
+        """Clear all cache. Never crashes."""
+        try:
+            return self.backend.clear()
+        except Exception as e:
+            if self.log_errors:
+                print(f"[FlashAPI Cache] CLEAR error: {e}")
+            return False
+
+
+# Global cache instance
+_CACHE: CacheLayer | None = None
+
+
+def register_cache(cache: CacheLayer) -> None:
+    """Register global cache instance."""
+    global _CACHE
+    _CACHE = cache
+
+
+def get_cache() -> CacheLayer | None:
+    """Get global cache instance."""
+    return _CACHE
+
+
+# Convenience decorators for route caching
+def cached(ttl: int = 300, key_prefix: str = ""):
+    """
+    Decorator to cache route responses.
+
+    Usage:
+        @cached(ttl=600, key_prefix='users')
+        def get_user(user_id):
+            return {...}
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            cache = get_cache()
+            if cache is None:
+                return func(*args, **kwargs)
+
+            # Build cache key
+            cache_key = f"{key_prefix}:{func.__name__}:{args}:{kwargs}"
+
+            # Try cache first
+            cached_value = cache.get(cache_key)
+            if cached_value is not None:
+                return cached_value
+
+            # Cache miss: compute and store
+            result = func(*args, **kwargs)
+            cache.set(cache_key, result, ttl)
+            return result
+
+        return wrapper
+    return decorator

flashapi/features/health.py

@@ -0,0 +1,69 @@
+"""
+Health check endpoints for production monitoring.
+
+Provides /health (liveness) and /ready (readiness) endpoints for Kubernetes,
+load balancers, and monitoring systems.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class HealthCheck:
+    """Health check manager with liveness and readiness probes."""
+
+    def __init__(self) -> None:
+        self._start_time = time.time()
+        self._ready = False
+        self._checks: dict[str, callable] = {}
+
+    def mark_ready(self) -> None:
+        """Mark the application as ready to receive traffic."""
+        self._ready = True
+
+    def register_check(self, name: str, check_fn: callable) -> None:
+        """Register a custom readiness check (e.g., database connection)."""
+        self._checks[name] = check_fn
+
+    def liveness(self) -> dict[str, Any]:
+        """
+        Liveness probe — is the application running?
+        Returns 200 if alive, should return 5xx if deadlocked/crashed.
+        """
+        uptime = int(time.time() - self._start_time)
+        return {"status": "ok", "uptime": uptime}
+
+    def readiness(self) -> tuple[dict[str, Any], int]:
+        """
+        Readiness probe — is the application ready to serve traffic?
+        Returns 200 if ready, 503 if not yet ready or dependencies failing.
+        """
+        if not self._ready:
+            return {"status": "not_ready", "reason": "Application still initializing"}, 503
+
+        failed_checks = []
+        for name, check_fn in self._checks.items():
+            try:
+                if not check_fn():
+                    failed_checks.append(name)
+            except Exception as e:
+                failed_checks.append(f"{name}: {e}")
+
+        if failed_checks:
+            return {
+                "status": "not_ready",
+                "failed_checks": failed_checks,
+            }, 503
+
+        uptime = int(time.time() - self._start_time)
+        return {"status": "ready", "uptime": uptime, "checks_passed": len(self._checks)}, 200
+
+
+_health = HealthCheck()
+
+
+def get_health_check() -> HealthCheck:
+    """Get the global health check instance."""
+    return _health

flashapi/features/idempotency.py

@@ -0,0 +1,375 @@
+"""
+Idempotency key support for FlashAPI.
+
+Prevents duplicate operations (double-click, retry, network replay) by storing
+request/response pairs keyed by a client-provided UUID.
+
+HTTP Spec v1 compliant:
+- Header: Idempotency-Key (UUID)
+- Behavior: Same key + same request → replay stored response
+- Conflict: Same key + different request → 422 Unprocessable Entity
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class IdempotencyRecord:
+    """Stored idempotency record."""
+
+    key: str
+    method: str
+    path: str
+    body_hash: str
+    response_status: int
+    response_body: str
+    response_headers: dict[str, str]
+    created_at: float
+
+
+class IdempotencyStore:
+    """Abstract storage interface for idempotency records."""
+
+    def get(self, key: str) -> IdempotencyRecord | None:
+        """Retrieve stored record by key."""
+        raise NotImplementedError
+
+    def store(
+        self,
+        key: str,
+        method: str,
+        path: str,
+        body_hash: str,
+        response_status: int,
+        response_body: str,
+        response_headers: dict[str, str],
+    ) -> None:
+        """Store a new idempotency record."""
+        raise NotImplementedError
+
+    def cleanup_expired(self, max_age_seconds: int = 86400) -> int:
+        """Remove records older than max_age_seconds. Returns count deleted."""
+        raise NotImplementedError
+
+
+class InMemoryIdempotencyStore(IdempotencyStore):
+    """In-memory idempotency store (for development/testing)."""
+
+    def __init__(self):
+        self._store: dict[str, IdempotencyRecord] = {}
+
+    def get(self, key: str) -> IdempotencyRecord | None:
+        return self._store.get(key)
+
+    def store(
+        self,
+        key: str,
+        method: str,
+        path: str,
+        body_hash: str,
+        response_status: int,
+        response_body: str,
+        response_headers: dict[str, str],
+    ) -> None:
+        self._store[key] = IdempotencyRecord(
+            key=key,
+            method=method,
+            path=path,
+            body_hash=body_hash,
+            response_status=response_status,
+            response_body=response_body,
+            response_headers=response_headers,
+            created_at=time.time(),
+        )
+
+    def cleanup_expired(self, max_age_seconds: int = 86400) -> int:
+        now = time.time()
+        expired_keys = [
+            k for k, v in self._store.items() if now - v.created_at > max_age_seconds
+        ]
+        for key in expired_keys:
+            del self._store[key]
+        return len(expired_keys)
+
+
+class SQLiteIdempotencyStore(IdempotencyStore):
+    """SQLite-based idempotency store (production-ready for single-instance)."""
+
+    def __init__(self, db_path: str = ":memory:"):
+        import sqlite3
+
+        self._conn = sqlite3.connect(db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._init_table()
+
+    def _init_table(self):
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS idempotency_keys (
+                key TEXT PRIMARY KEY,
+                method TEXT NOT NULL,
+                path TEXT NOT NULL,
+                body_hash TEXT NOT NULL,
+                response_status INTEGER NOT NULL,
+                response_body TEXT NOT NULL,
+                response_headers TEXT NOT NULL,
+                created_at REAL NOT NULL
+            )
+        """)
+        self._conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_created_at ON idempotency_keys(created_at)"
+        )
+        self._conn.commit()
+
+    def get(self, key: str) -> IdempotencyRecord | None:
+        row = self._conn.execute(
+            "SELECT * FROM idempotency_keys WHERE key = ?", (key,)
+        ).fetchone()
+        if row is None:
+            return None
+        return IdempotencyRecord(
+            key=row["key"],
+            method=row["method"],
+            path=row["path"],
+            body_hash=row["body_hash"],
+            response_status=row["response_status"],
+            response_body=row["response_body"],
+            response_headers=json.loads(row["response_headers"]),
+            created_at=row["created_at"],
+        )
+
+    def store(
+        self,
+        key: str,
+        method: str,
+        path: str,
+        body_hash: str,
+        response_status: int,
+        response_body: str,
+        response_headers: dict[str, str],
+    ) -> None:
+        self._conn.execute(
+            """
+            INSERT OR REPLACE INTO idempotency_keys
+            (key, method, path, body_hash, response_status, response_body, response_headers, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                key,
+                method,
+                path,
+                body_hash,
+                response_status,
+                response_body,
+                json.dumps(response_headers),
+                time.time(),
+            ),
+        )
+        self._conn.commit()
+
+    def cleanup_expired(self, max_age_seconds: int = 86400) -> int:
+        cutoff = time.time() - max_age_seconds
+        cursor = self._conn.execute(
+            "DELETE FROM idempotency_keys WHERE created_at < ?", (cutoff,)
+        )
+        self._conn.commit()
+        return cursor.rowcount
+
+
+def compute_body_hash(body: bytes | str) -> str:
+    """Compute SHA-256 hash of request body for comparison."""
+    if isinstance(body, str):
+        body = body.encode("utf-8")
+    return hashlib.sha256(body).hexdigest()
+
+
+def check_idempotency_conflict(
+    stored: IdempotencyRecord, method: str, path: str, body_hash: str
+) -> bool:
+    """Check if request conflicts with stored record (same key, different request)."""
+    return (
+        stored.method != method or stored.path != path or stored.body_hash != body_hash
+    )
+
+
+class IdempotencyMiddleware:
+    """
+    Idempotency middleware for FlashAPI.
+
+    Usage (Django):
+        from flashapi.features.idempotency import IdempotencyMiddleware, SQLiteIdempotencyStore
+
+        # In settings.py MIDDLEWARE
+        MIDDLEWARE = [
+            'flashapi.features.idempotency.DjangoIdempotencyMiddleware',
+            ...
+        ]
+
+        # Register store globally
+        from flashapi.features.idempotency import register_idempotency_store
+        register_idempotency_store(SQLiteIdempotencyStore('idempotency.db'))
+    """
+
+    def __init__(self, store: IdempotencyStore | None = None):
+        self.store = store or InMemoryIdempotencyStore()
+
+    def process_request(
+        self, method: str, path: str, headers: dict[str, str], body: bytes | str
+    ) -> tuple[bool, Any]:
+        """
+        Process request for idempotency.
+
+        Returns:
+            (is_replay, response_or_none):
+                - If is_replay=True, response_or_none contains the stored response to replay
+                - If is_replay=False, response_or_none is None (continue normal processing)
+                - If is_replay=False but response_or_none is dict, it's a 422 conflict error
+        """
+        # Only apply to POST/PUT/DELETE
+        if method not in ("POST", "PUT", "DELETE"):
+            return False, None
+
+        idempotency_key = headers.get("idempotency-key") or headers.get(
+            "Idempotency-Key"
+        )
+        if not idempotency_key:
+            return False, None
+
+        # Validate UUID format (basic check)
+        if len(idempotency_key) < 32:
+            return False, {
+                "error": "Invalid Idempotency-Key format (must be UUID)",
+                "status": 400,
+            }
+
+        # Check if key exists
+        stored = self.store.get(idempotency_key)
+        if stored is None:
+            return False, None
+
+        # Check for conflict (same key, different request)
+        body_hash = compute_body_hash(body)
+        if check_idempotency_conflict(stored, method, path, body_hash):
+            return False, {
+                "error": {
+                    "code": "IDEMPOTENCY_CONFLICT",
+                    "message": "Idempotency key reused with different request",
+                    "status": 422,
+                },
+                "status": 422,
+            }
+
+        # Replay stored response
+        return True, {
+            "status": stored.response_status,
+            "body": stored.response_body,
+            "headers": stored.response_headers,
+            "replay": True,
+        }
+
+    def store_response(
+        self,
+        idempotency_key: str,
+        method: str,
+        path: str,
+        body: bytes | str,
+        response_status: int,
+        response_body: str,
+        response_headers: dict[str, str] | None = None,
+    ) -> None:
+        """Store response for future replay."""
+        if method not in ("POST", "PUT", "DELETE"):
+            return
+
+        body_hash = compute_body_hash(body)
+        self.store.store(
+            key=idempotency_key,
+            method=method,
+            path=path,
+            body_hash=body_hash,
+            response_status=response_status,
+            response_body=response_body,
+            response_headers=response_headers or {},
+        )
+
+
+# Global store registry (for Django middleware)
+_IDEMPOTENCY_STORE: IdempotencyStore | None = None
+
+
+def register_idempotency_store(store: IdempotencyStore) -> None:
+    """Register global idempotency store."""
+    global _IDEMPOTENCY_STORE
+    _IDEMPOTENCY_STORE = store
+
+
+def get_idempotency_store() -> IdempotencyStore | None:
+    """Get global idempotency store."""
+    return _IDEMPOTENCY_STORE
+
+
+# Django middleware class
+class DjangoIdempotencyMiddleware:
+    """Django middleware for idempotency support."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.middleware = IdempotencyMiddleware(get_idempotency_store())
+
+    def __call__(self, request):
+        from django.http import JsonResponse
+
+        # Extract request data
+        method = request.method
+        path = request.path
+        headers = {k.lower(): v for k, v in request.META.items() if k.startswith("HTTP_")}
+        headers = {k.replace("http_", ""): v for k, v in headers.items()}
+        body = request.body
+
+        # Check idempotency
+        is_replay, result = self.middleware.process_request(method, path, headers, body)
+
+        if result and "status" in result and result["status"] in (400, 422):
+            # Error response (invalid key or conflict)
+            return JsonResponse(result.get("error", result), status=result["status"])
+
+        if is_replay and result:
+            # Replay stored response
+            response = JsonResponse(
+                json.loads(result["body"]), status=result["status"], safe=False
+            )
+            for key, value in result.get("headers", {}).items():
+                response[key] = value
+            response["Idempotency-Replay"] = "true"
+            return response
+
+        # Process request normally
+        response = self.get_response(request)
+
+        # Store response if idempotency key present and success
+        idempotency_key = headers.get("idempotency-key")
+        if (
+            idempotency_key
+            and method in ("POST", "PUT", "DELETE")
+            and 200 <= response.status_code < 300
+        ):
+            response_body = response.content.decode("utf-8")
+            response_headers = {
+                k: v for k, v in response.items() if k.lower() in ("content-type",)
+            }
+            self.middleware.store_response(
+                idempotency_key=idempotency_key,
+                method=method,
+                path=path,
+                body=body,
+                response_status=response.status_code,
+                response_body=response_body,
+                response_headers=response_headers,
+            )
+
+        return response

flashapi/storage/orm.py

@@ -38,6 +38,9 @@ class DjangoORMStorage(Storage):
         instance = self._get_instance(item_id, lookup_field)
         if instance is None:
             return None
+        # Fix Bug #3: Respect soft delete in GET /{id}
+        if self._has_deleted_at and getattr(instance, SOFT_DELETE_FIELD, None) is not None:
+            return None
         return self._to_dict(instance)
 
     def list_all(self, table: str, *, include_deleted: bool = False, only_deleted: bool = False) -> list[dict[str, Any]]:

{python_flashapi-0.2.0.dist-info → python_flashapi-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-flashapi
-Version: 0.2.0
+Version: 0.4.0
 Summary: Define your models. FlashAPI does the rest.
 Project-URL: Homepage, https://github.com/HackermanMe/flashapi
 Project-URL: Documentation, https://github.com/HackermanMe/flashapi#readme
@@ -64,10 +64,12 @@ Description-Content-Type: text/markdown
 
 ---
 
-FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, and a live dashboard — from your existing models, in one line.
+FlashAPI generates a full REST API with CRUD, pagination, filtering, sorting, full-text search, relations, soft delete, bulk operations, export, audit trail, webhooks, rate limiting, **idempotency keys**, **cache layer**, **currentUser auto-injection**, and a live dashboard — from your existing models, in one line.
 
 Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across all backends (Python, Java Spring, Node.js).
 
+**New in 0.4.0:** Idempotency keys (prevent double-click/retry duplicates), cache layer with graceful fallback, currentUserField auto-injection, and audit enabled by default.
+
 ---
 
 ## Documentation
@@ -88,7 +90,12 @@ Part of the **FlashAPI Ecosystem** — ensuring SDK client compatibility across
 ## Installation
 
 ```bash
-pip install python-flashapi[fastapi]   # or python-flashapi[flask] or python-flashapi[all]
+# x-release-please-start-version
+pip install python-flashapi==0.3.0
+# x-release-please-end
+
+# With framework extras:
+pip install python-flashapi[fastapi]   # or [flask] or [django] or [all]
 ```
 
 ---
@@ -226,8 +233,9 @@ FlashAPI(
         Model(Config, readonly=True, access="admin"),      # GET only, admin
         Model(Log, only=["list"]),                         # List only
         Model(Animal, plural="animaux"),                   # Custom plural
-        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features
+        Model(Invoice, soft_delete=True, audit=True),      # Opt-in features (audit=True by default)
         Model(Eleve, access="staff", scope="tenant", tenant_field="ecole_id"),
+        Model(Post, current_user_field="author"),          # Auto-inject authenticated user on create
     ],
     base_path="/api",       # Configurable prefix (default: /api)
     auth_backend=MyAuth(),  # Your AuthBackend implementation
@@ -235,6 +243,14 @@ FlashAPI(
     rate_limit=100,         # 100 requests per window
     rate_window=60,         # 60 seconds window
 )
+
+# Enable idempotency (prevents duplicate operations from double-click/retry)
+# Client sends: Idempotency-Key: <uuid> header
+# Same key + same request → returns stored response (no duplicate created)
+
+# Enable cache layer (graceful fallback if Redis down)
+from flashapi.features.cache import CacheLayer, RedisCache, register_cache
+register_cache(CacheLayer(RedisCache(host='localhost')))
 ```
 
 See [Customization docs](docs/customization.md) for all options.

{python_flashapi-0.2.0.dist-info → python_flashapi-0.4.0.dist-info}/RECORD

@@ -5,24 +5,27 @@ flashapi/flask.py,sha256=v-uSb9QSxj20w2iyDgaM4uED82XHLWEO9CRxGT8KCVc,137
 flashapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 flashapi/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 flashapi/adapters/base.py,sha256=DbXmwMZzZYums4YaJ-OlY8bJxTbGJTxApSfmf5NO-0w,329
-flashapi/adapters/django.py,sha256=6rs_mFkkF4qmnJ8DB69nV8mbYuMde1bHCzLBrN5MypI,32633
-flashapi/adapters/fastapi.py,sha256=63lcUoK2a6k1RdwRb1kIH2zz-D0tqouJ3MUALUMJ0WI,36820
-flashapi/adapters/flask.py,sha256=peVQQ8NTGDLpuplAvUbYTuXGF59eeBbFb_9HTEcxvfE,29121
+flashapi/adapters/django.py,sha256=KVkPjL8kPHfeXnJb67h0mf6K0_SjRSpPo1B5zfpexHY,35743
+flashapi/adapters/fastapi.py,sha256=OvdcBVT9j17ldLymzs4Hm3r-zzotDiHdht6cA5sZPYE,38779
+flashapi/adapters/flask.py,sha256=pwYqy-X2ABmbCeWz5NMOXWKYvp2ZHlE_digouKvY-xs,30880
 flashapi/core/__init__.py,sha256=8Ex4oCFI34F4xkA6Q6zSSQ-jE2uw1w-C20yl-Yg3f3c,297
-flashapi/core/custom_routes.py,sha256=-K0xDx-bW1yJtcJxh5ZdFUI0MzwIKoNKMJCuocdZuWI,8432
+flashapi/core/custom_routes.py,sha256=iPaupBqc_j0yaCsxZeoGS6iEqlSD4s26EpM27XoIAwg,9456
 flashapi/core/pluralize.py,sha256=nL_JwNHwEbz6n3HXdfA1We9_MRNR-cLn4VT-Hz1RW1g,2406
 flashapi/core/relations.py,sha256=vhy3qJeL_cwJFNq1h-3OtE9hXr6MJ9P23hSBtmX-7Zg,2236
 flashapi/core/response.py,sha256=6jJ2xIiSn48WKWOBHjM_LnnpScVjcJjA4idCKOaWfqc,847
-flashapi/core/schema.py,sha256=bxuQv2knRj_SqZQa3fHhS_aO72TKwpXYNFu0xti5Cms,4176
-flashapi/core/visibility.py,sha256=ZPa7zK3-Dp0AoaFH7VA04eWE4vw7oia5aH8wCz0nHxw,1398
+flashapi/core/schema.py,sha256=Ers-rmUoYS4-cLbgoWj1_87hNBqDPic6J1H13SG5AYY,4405
+flashapi/core/visibility.py,sha256=HJsySZ_PuRA0dTO5YPmd2pBv3opCRW0nty5ZKzUKI4A,2526
 flashapi/docs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 flashapi/docs/openapi.py,sha256=jfrQMC3wPAv3AcLRBXDmaB45D-LctCWbBFLiq5lsUuI,10931
 flashapi/features/__init__.py,sha256=EHYe6pSe74LegaSRdX09X--a0M022fkRZFomWn84kFc,280
 flashapi/features/audit.py,sha256=kJ9U1FbA6HQI-bjUjcOiwsY3J300O2aoF9fvrLFI4k8,2870
 flashapi/features/auth.py,sha256=FVYb6x6VAIEvAp2xY8LL5I2E2PFdPe5v8dDGmWQfWLc,4585
+flashapi/features/cache.py,sha256=gBoUiU0oQNAbVyBhVTLnlRDNrWo5iOm-VqWvdyd3vsc,6350
 flashapi/features/dashboard.py,sha256=eaOJmrJ5lRxDDyo4BhCp5qaNHDn0AUW4IlqhAIL38as,18239
 flashapi/features/export.py,sha256=M7RryPDgDZn1VlouZNzhvhrZ00k1e0HyyZlAfjYMSiE,4912
 flashapi/features/filtering.py,sha256=ONPWbVVTHlTRlxUoOcRNkL_a67osr12CJHKKBXHwDPg,3826
+flashapi/features/health.py,sha256=g-vLoIAmS2L8pq7cvG9TX7h60rPEAa6YMlog71AW-u4,2140
+flashapi/features/idempotency.py,sha256=cdrIJeTLGZHRoqn_zAu-UPOU2_kCgL9E7qGOEjsmoOA,11812
 flashapi/features/pagination.py,sha256=396lvL_c6j3tNNodpPHkYDRkxkDmex2q9HmrUeOpLRA,464
 flashapi/features/rate_limit.py,sha256=LEI8UqWHEH7TREqaD0lDhhR5jZz8VF5qdu0gBxOVBSc,1313
 flashapi/features/search.py,sha256=0V0S8Mo2zb_BEeGbNYg8Y4ZF9njLNhwZAkrVrODW3Dc,611
@@ -39,10 +42,10 @@ flashapi/inspectors/sqlalchemy.py,sha256=mVCnBCA7MhGqGsrhtZJA2LS5luZiU8wcXHpvv4U
 flashapi/storage/__init__.py,sha256=h8bXTCL-y6P_waQ3L2JNEh8lVaSJ_WiEVkaolUsOhUs,126
 flashapi/storage/auto.py,sha256=6K6_TSFU2NJSIaFqE3qbGFIY1H8uaL0iLGBEVvUpifs,7611
 flashapi/storage/base.py,sha256=8C6DL9LAWQ3lIDFKTKD3chXuDNr2LTc5yWoZYQPpKq4,1089
-flashapi/storage/orm.py,sha256=F_hOxspYkKzH1l_m48jRNdv7TGvp4OM6EwpMixfeP9E,4556
+flashapi/storage/orm.py,sha256=q_PeFaoS6UrJnxsaSwXx2H1bzv2vUK2G8KbmH-msRoY,4727
 flashapi/storage/sqlalchemy.py,sha256=FoSHWDydicRvns8ufO1vnb2o0dGwvASd88sQ3wh1SAI,6651
-python_flashapi-0.2.0.dist-info/METADATA,sha256=nRRFMQ3s7x8n0HomOcd-B1bh1pGITxazny9vczB-1tU,10793
-python_flashapi-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-python_flashapi-0.2.0.dist-info/licenses/LICENSE,sha256=thh4-7oEXj4Tz_CHQciJHSnRqxCNRRuse5ac-BwBU5c,10772
-python_flashapi-0.2.0.dist-info/licenses/NOTICE,sha256=5-7uAManZL-6L6TGoHqSVBioA5MZ_UAzCPi97Ahtvw8,164
-python_flashapi-0.2.0.dist-info/RECORD,,
+python_flashapi-0.4.0.dist-info/METADATA,sha256=AYSQHfaX8gI_dpw0TQ1UzKj0_ZITpnB8s-8BqL6p90Q,11655
+python_flashapi-0.4.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+python_flashapi-0.4.0.dist-info/licenses/LICENSE,sha256=thh4-7oEXj4Tz_CHQciJHSnRqxCNRRuse5ac-BwBU5c,10772
+python_flashapi-0.4.0.dist-info/licenses/NOTICE,sha256=5-7uAManZL-6L6TGoHqSVBioA5MZ_UAzCPi97Ahtvw8,164
+python_flashapi-0.4.0.dist-info/RECORD,,

{python_flashapi-0.2.0.dist-info → python_flashapi-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.3
 Root-Is-Purelib: true
 Tag: py3-none-any