statezero 0.1.0b1__py3-none-any.whl

statezero/core/ast_validator.py

@@ -0,0 +1,266 @@
+from enum import Enum
+from typing import Any, Callable, Dict, List, Set, Type
+
+import networkx as nx
+
+from statezero.core.config import Registry
+from statezero.core.exceptions import PermissionDenied, ValidationError
+from statezero.core.interfaces import AbstractPermission
+from statezero.core.types import ActionType, ORMModel, RequestType
+
+
+class ASTValidator:
+    def __init__(
+        self,
+        model_graph: nx.DiGraph,
+        get_model_name: Callable[[Type], str],
+        registry: Registry,
+        request: Any,
+        get_model_by_name: Callable[[str], Type],
+    ):
+        """
+        :param model_graph: The model graph built by the ORM's graph builder.
+        :param get_model_name: A callable that returns a unique name for a given model.
+        :param registry: Global registry mapping models to their ModelConfig.
+        :param request: The current request (for permission checking).
+        :param get_model_by_name: Helper to resolve a model by its unique name.
+        """
+        self.model_graph = model_graph
+        self.get_model_name = get_model_name
+        self.registry = registry
+        self.request = request
+        self.get_model_by_name = get_model_by_name
+
+    def _aggregate_permission_instances(self, model: Type) -> List[AbstractPermission]:
+        """
+        Given a model, return a list of permission instances as specified in its ModelConfig.
+        (You might cache these or use a more sophisticated composition in a real app.)
+        """
+        config = self.registry.get_config(model)
+        # Instantiate each permission class (assuming no extra init parameters).
+        return [perm_class() for perm_class in config.permissions]
+
+    def _allowed_fields_for_model(self, model: Type) -> Set[str]:
+        """
+        Aggregates the visible fields from all permission instances for the given model.
+        """
+        allowed_fields: Set[str] = set()
+        for perm in self._aggregate_permission_instances(model):
+            fields = perm.visible_fields(self.request, model)
+            if fields == "__all__":
+                # If any permission allows all fields, return all available fields
+                from statezero.adaptors.django.config import config
+
+                return config.orm_provider.get_fields(model)
+            allowed_fields |= fields
+        return allowed_fields
+
+    def _has_read_permission(self, model: Type) -> bool:
+        """
+        Checks if any of the permission instances for the model allow the READ action.
+        """
+        for perm in self._aggregate_permission_instances(model):
+            if ActionType.READ in perm.allowed_actions(self.request, model):
+                return True
+        return False
+
+    def _is_additional_field(self, model: Type, field_name: str) -> bool:
+        """
+        Check if a field is an additional (computed) field that doesn't exist in the Django model.
+        """
+        try:
+            config = self.registry.get_config(model)
+            additional_field_names = {f.name for f in config.additional_fields}
+            return field_name in additional_field_names
+        except (ValueError, AttributeError):
+            return False
+
+    def _field_exists_in_django_model(self, model: Type, field_path: str) -> bool:
+        """
+        Check if a field path exists in the actual Django model (not just additional fields).
+        This validates that Django ORM can actually filter/query on this field.
+        """
+        try:
+            # Remove any lookup operators (e.g., 'name__icontains' -> 'name')
+            SUPPORTED_OPERATORS = {
+                "contains",
+                "icontains",
+                "startswith",
+                "istartswith",
+                "endswith",
+                "iendswith",
+                "lt",
+                "gt",
+                "lte",
+                "gte",
+                "in",
+                "eq",
+                "exact",
+                "isnull",
+            }
+
+            field_parts = field_path.split("__")
+            # Find where the lookup operators start
+            base_field_parts = []
+            for part in field_parts:
+                if part in SUPPORTED_OPERATORS:
+                    break
+                base_field_parts.append(part)
+
+            # Traverse the Django model fields
+            current_model = model
+            for field_name in base_field_parts:
+                try:
+                    field = current_model._meta.get_field(field_name)
+                    if field.is_relation and hasattr(field, "related_model"):
+                        current_model = field.related_model
+                except:
+                    # Field doesn't exist in Django model
+                    return False
+
+            return True
+        except:
+            return False
+
+    def is_field_allowed(self, model: Type, field_path: str) -> bool:
+        """
+        Validates a nested field path (e.g. "related__name" or "level2__level3__name")
+        by using the model registry to extract the permission settings for each model
+        encountered along the path. Uses "__" to separate nested fields, and "::" as
+        the delimiter within a field node key.
+        """
+        parts = field_path.split("__")
+        current_model = model
+        current_model_name = self.get_model_name(current_model)
+
+        # Check that the user has READ permission on the root model.
+        if not self._has_read_permission(current_model):
+            return False
+
+        # Get allowed fields from permission settings.
+        allowed = self._allowed_fields_for_model(current_model)
+        for part in parts:
+            # Check that the field is allowed on the current model.
+            if part not in allowed and "__all__" not in str(allowed):
+                return False
+
+            # Construct the field node key.
+            field_node = f"{current_model_name}::{part}"
+            if self.model_graph.has_node(field_node):
+                node_data = self.model_graph.nodes[field_node].get("data")
+                if not node_data:
+                    return False
+                if node_data.is_relation:
+                    # If this is a relation, resolve the related model.
+                    related_model_name = node_data.related_model
+                    if related_model_name:
+                        related_model = self.get_model_by_name(related_model_name)
+                        # Check READ permission on the related model.
+                        if not self._has_read_permission(related_model):
+                            return False
+                        # Move to the related model for the next part.
+                        current_model = related_model
+                        current_model_name = related_model_name
+                        allowed = self._allowed_fields_for_model(current_model)
+                        continue
+                    else:
+                        return False
+                else:
+                    # Terminal (non-relation) field reached.
+                    break
+            else:
+                return False
+
+        return True
+
+    def validate_filterable_field(self, model: Type, field_path: str) -> None:
+        """
+        Validates that a field path can be used for filtering operations.
+        Checks both field existence and user permissions.
+        Raises ValidationError if the field is an additional field or doesn't exist in Django model.
+        Raises PermissionDenied if the user doesn't have permission to access the field.
+        """
+        base_field = field_path.split("__")[0]
+
+        # Check if it's an additional field (these can't be filtered)
+        if self._is_additional_field(model, base_field):
+            raise ValidationError(
+                f"Cannot filter on computed field '{base_field}'. "
+                f"Computed fields are read-only and cannot be used in filters. "
+                f"Consider using Django's computed fields, database annotations, or filter on the underlying fields instead."
+            )
+
+        # Check if the field actually exists in the Django model
+        if not self._field_exists_in_django_model(model, field_path):
+            raise ValidationError(
+                f"Field '{field_path}' does not exist on model {model.__name__}. "
+                f"Please check the field name and ensure it's a valid Django model field."
+            )
+
+        # Check if the user has permission to access this field
+        if not self.is_field_allowed(model, field_path):
+            raise PermissionDenied(
+                f"Permission denied: You do not have access to filter on field '{field_path}'"
+            )
+
+    def validate_filter_conditions(self, ast_node: Dict[str, Any], model: Type) -> None:
+        """
+        Recursively validates filter conditions in an AST node to ensure all fields are filterable.
+        """
+        if not isinstance(ast_node, dict):
+            return
+
+        node_type = ast_node.get("type")
+
+        # Handle filter nodes
+        if node_type == "filter":
+            conditions = ast_node.get("conditions", {})
+            for field_path in conditions.keys():
+                self.validate_filterable_field(model, field_path)
+
+        # Handle exclude nodes (they also filter, so same validation applies)
+        elif node_type == "exclude":
+            if "child" in ast_node:
+                self.validate_filter_conditions(ast_node["child"], model)
+            else:
+                # Direct exclude conditions
+                conditions = ast_node.get("conditions", {})
+                for field_path in conditions.keys():
+                    self.validate_filterable_field(model, field_path)
+
+        # Recursively validate children
+        if "children" in ast_node:
+            for child in ast_node["children"]:
+                self.validate_filter_conditions(child, model)
+
+        if "child" in ast_node:
+            self.validate_filter_conditions(ast_node["child"], model)
+
+    def validate_fields(self, ast: Dict[str, Any], root_model: Type) -> None:
+        """
+        Iterates over the requested fields in the AST's serializerOptions and verifies each
+        field is allowed according to the registry-based permission settings.
+        Raises PermissionDenied if any field is not permitted.
+        """
+        serializer_options = ast.get("serializerOptions", {})
+        requested_fields = serializer_options.get("fields", [])
+        for field in requested_fields:
+            if not self.is_field_allowed(root_model, field):
+                raise PermissionDenied(f"Access to field '{field}' is not permitted.")
+
+    def validate_ast(self, ast: Dict[str, Any], root_model: Type) -> None:
+        """
+        Complete AST validation including both field permissions and filter validation.
+        """
+        # Validate field access permissions
+        self.validate_fields(ast, root_model)
+
+        # Validate filter conditions to ensure no additional fields are used
+        filter_node = ast.get("filter")
+        if filter_node:
+            self.validate_filter_conditions(filter_node, root_model)
+
+        # Also validate any exclude conditions
+        exclude_node = ast.get("exclude")
+        if exclude_node:
+            self.validate_filter_conditions(exclude_node, root_model)

statezero/core/classes.py

@@ -0,0 +1,167 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set, Type, Union
+
+import jsonschema
+from fastapi.encoders import jsonable_encoder
+from pydantic import BaseModel, Field
+
+from statezero.core.types import ORMField
+
+
+class ValidatorType(str, Enum):
+    """OpenAPI-aligned validators"""
+
+    # Numeric validators
+    MINIMUM = "minimum"
+    MAXIMUM = "maximum"
+    EXCLUSIVE_MINIMUM = "exclusiveMinimum"
+    EXCLUSIVE_MAXIMUM = "exclusiveMaximum"
+    MULTIPLE_OF = "multipleOf"
+
+    # String validators
+    MIN_LENGTH = "minLength"
+    MAX_LENGTH = "maxLength"
+    PATTERN = "pattern"
+
+    # Array validators
+    MIN_ITEMS = "minItems"
+    MAX_ITEMS = "maxItems"
+    UNIQUE_ITEMS = "uniqueItems"
+
+    # Object validators
+    MIN_PROPERTIES = "minProperties"
+    MAX_PROPERTIES = "maxProperties"
+    REQUIRED = "required"
+
+    # Format validators
+    FORMAT = "format"  # Handles email, url, date-time, etc.
+
+
+@dataclass
+class Validator:
+    type: ValidatorType
+    value: Any  # The constraint value
+    message: str  # Error message to display
+
+    def to_openapi(self) -> dict:
+        """Convert validator to OpenAPI schema fragment"""
+        if self.type == ValidatorType.FORMAT:
+            return {"format": self.value}
+        return {self.type: self.value}
+
+
+class FieldType(str, Enum):
+    """Basic field types from the implementation"""
+
+    STRING = "string"
+    INTEGER = "integer"
+    BOOLEAN = "boolean"
+    NUMBER = "number"
+    ARRAY = "array"
+    OBJECT = "object"
+    FILE = "file"
+
+
+class FieldFormat(str, Enum):
+    """Field formats from the implementation"""
+
+    ID = "id"
+    UUID = "uuid"
+    TEXT = "text"
+    DATE = "date"
+    DATETIME = "date-time"
+    FOREIGN_KEY = "foreign-key"
+    ONE_TO_ONE = "one-to-one"
+    MANY_TO_MANY = "many-to-many"
+    DECIMAL = "decimal"
+    FILE_PATH = "file-path"
+    IMAGE_PATH = "image-path"
+    JSON = "json"
+    MONEY = "money"
+
+
+@dataclass
+class AdditionalField:
+    """
+    Represents configuration for an additional computed field in the schema.
+
+    Attributes:
+        name: The name of the property/method on the model that provides the value
+        field: The Django model field instance that defines the serialization behavior
+        title: Optional override for the field's display title
+    """
+
+    name: str  # The property/method name to pull from
+    field: Type[ORMField]  # The instantiated serializer field (e.g. CharField(max_length=255)) #type:ignore
+    title: Optional[str] # Optional display name override
+
+class SchemaFieldMetadata(BaseModel):
+    type: FieldType
+    title: str
+    required: bool
+    description: Optional[str] = None
+    nullable: bool = False
+    format: Optional[FieldFormat] = None
+    max_length: Optional[int] = None
+    choices: Optional[Dict[str, str]] = None
+    default: Optional[Any] = None
+    validators: List[Validator] = Field(default_factory=list)
+    max_digits: Optional[int] = None  # For decimal fields
+    decimal_places: Optional[int] = None  # For decimal fields
+    read_only: bool = False
+    ref: Optional[str] = None
+
+
+class ModelSchemaMetadata(BaseModel):
+    """Core model metadata needed for frontend operations"""
+
+    model_name: str  # model name for queries
+    title: str  # display name (verbose_name)
+    class_name: str  # class name for generating ts/js classes
+    plural_title: str  # verbose_name_plural
+    primary_key_field: str
+
+    # Query capabilities
+    filterable_fields: Set[str]
+    searchable_fields: Set[str]
+    ordering_fields: Set[str]
+    properties: Dict[str, SchemaFieldMetadata]
+    relationships: Dict[str, Dict[str, Any]]
+    default_ordering: Optional[List[str]] = None
+    # Extra definitions (for schemas referenced via $ref) are merged in if provided.
+    definitions: Dict[str, Any] = field(default_factory=dict)
+    
+    # Date / time formatting templates
+    datetime_format: Optional[str] = None
+    date_format: Optional[str] = None
+    time_format: Optional[str] = None
+
+@dataclass
+class ModelSummaryRepresentation:
+    pk: Any
+    repr: Dict[str, Optional[str]] = field(default_factory=dict)
+    model_name: Optional[str] = field(default=None)
+    pk_field: str = "id"
+
+    def to_dict(self) -> dict:
+        return {
+            self.pk_field: jsonable_encoder(self.pk),
+            "repr": self.repr,
+        }
+
+
+@dataclass
+class ModelNode:
+    model_name: str
+    model: Optional[Type] = None  # The actual model class (if applicable)
+    type: str = "model"
+
+
+@dataclass
+class FieldNode:
+    model_name: str  # The parent model's name
+    field_name: str  # The name of the field
+    is_relation: bool
+    related_model: Optional[str] = None  # The object name of the related model, if any
+    type: str = "field"

statezero/core/config.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional, Set, Type, Union, Literal
+import networkx as nx
+
+
+from statezero.core.classes import AdditionalField
+from statezero.core.event_bus import EventBus
+from statezero.core.interfaces import (AbstractCustomQueryset,
+                                       AbstractDataSerializer,
+                                       AbstractORMProvider, AbstractPermission,
+                                       AbstractSchemaGenerator, AbstractSearchProvider, AbstractQueryOptimizer)
+from statezero.core.types import ORMField
+
+class AppConfig(ABC):
+    """
+    Global configuration for the system.
+    Developers configure:
+      - The global web engine (including serializer and schema generator)
+      - The ORM provider (e.g. SQLAlchemyORMProvider, etc.)
+      - The event emitter (e.g. FastAPIEventEmitter, etc.)
+
+    Global overrides for both serializer and schema generation are provided,
+    keyed by ORMField. These overrides apply to all models unless a per-model override
+    is provided in the model's configuration.
+    """
+
+    serializer: Optional[AbstractDataSerializer] = None
+    schema_generator: Optional[AbstractSchemaGenerator] = None
+
+    # Global custom overrides for ALL models.
+    custom_serializers: Dict[ORMField, Callable] = {}  # type:ignore
+    schema_overrides: Dict[ORMField, dict] = {}  # type:ignore
+
+    event_bus: EventBus = None
+    default_limit: Optional[int] = 100
+    orm_provider: AbstractORMProvider = None
+    search_provider: AbstractSearchProvider = None
+
+    # Query optimizers
+    query_optimizer: Optional[AbstractQueryOptimizer] = None
+    file_upload_callbacks: Optional[List[str]] = None
+
+    def __init__(self) -> None:
+        self._orm_provider: Optional[AbstractORMProvider] = None
+
+    def configure(self, **kwargs) -> None:
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+            else:
+                raise AttributeError(f"Invalid configuration key: {key}")
+
+    @abstractmethod
+    def initialize(self) -> None:
+        """
+        Initialize the global configuration for the system.
+
+        This method sets up all core components needed by the framework, including:
+        - The data serializer and schema generator.
+        - The ORM provider for database interactions.
+        - The event bus along with its associated event emitters.
+        - Caching and dependency tracking mechanisms.
+
+        It must be implemented by each subclass of AppConfig to ensure that all required
+        components are properly configured and wired together before the application starts
+        processing requests.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+        pass
+
+    def validate_exposed_models(self, registry: Registry) -> bool:
+        """
+        Validate that all registered models only expose fields 
+        that reference other registered models.
+        
+        This implementation is ORM-agnostic, using the configured orm_provider
+        to access model relationships.
+        
+        Args:
+            registry: The global registry containing registered models
+            
+        Returns:
+            bool: True if validation passes
+            
+        Raises:
+            ValueError: If a registered model exposes an unregistered model
+        """
+        if not self.orm_provider:
+            raise ValueError("ORM provider must be initialized before validation")
+            
+        # Build complete model graph for all registered models
+        model_graph = nx.DiGraph()
+        for model in registry._models_config.keys():
+            model_graph = self.orm_provider.build_model_graph(model, model_graph)
+            
+        # Check each registered model
+        for model, config in registry._models_config.items():
+            # Get model name for error messages and graph lookup
+            model_name = self.orm_provider.get_model_name(model)
+            
+            # Get all field nodes from the graph for this model
+            all_model_fields = set()
+            for _, field_node in model_graph.out_edges(model_name):
+                if "::" in field_node:
+                    field_name = field_node.split("::")[-1]
+                    all_model_fields.add(field_name)
+                    
+            # Determine which fields to check based on config.fields
+            fields_to_check = config.fields if config.fields != "__all__" else all_model_fields
+            
+            # Check each field to see if it's a relation to an unregistered model
+            for field_name in fields_to_check:
+                field_node = f"{model_name}::{field_name}"
+                
+                if model_graph.has_node(field_node):
+                    node_data = model_graph.nodes[field_node].get("data")
+                    if node_data and node_data.is_relation:
+                        related_model_name = node_data.related_model
+                        if related_model_name:
+                            # Get the related model from its name
+                            related_model = self.orm_provider.get_model_by_name(related_model_name)
+                            
+                            # Check if related model is registered
+                            if related_model not in registry._models_config:
+                                raise ValueError(
+                                    f"Model '{model_name}' exposes relation '{field_name}' "
+                                    f"to unregistered model '{related_model_name}'. "
+                                    f"Please register '{related_model_name}' with StateZero "
+                                    f"or restrict access to this field by excluding it from the 'fields' parameter."
+                                )
+                                
+        return True
+
+
+class ModelConfig:
+    """
+    Initialize model-specific configuration.
+
+    Parameters:
+    -----------
+    model: Type
+        The model class to register
+    custom_querysets: Dict[str, Type[AbstractCustomQueryset]], optional
+        Custom queryset methods for this model
+    permissions: List[Type[AbstractPermission]], optional
+        Permission classes that control access to this model
+    pre_hooks: List[Callable], optional
+        Functions to run before serialization/deserialization
+    post_hooks: List[Callable], optional
+        Functions to run after serialization/deserialization
+    additional_fields: List[AdditionalField], optional
+        Additional computed fields to add to the model schema
+    filterable_fields: Optional[Union[Set[str], Literal["__all__"]]], optional
+        Fields that can be used in filter queries
+    searchable_fields: Optional[Union[Set[str], Literal["__all__"]]], optional
+        Fields that can be used in search queries
+    ordering_fields: Optional[Union[Set[str], Literal["__all__"]]], optional
+        Fields that can be used for ordering
+    fields: Optional[Optional[Union[Set[str], Literal["__all__"]]]]
+        Expose just a subset of the model fields
+    DEBUG: bool, default=False
+        Enable debug mode for this model
+    """
+
+    def __init__(
+        self,
+        model: Type,
+        custom_querysets: Optional[Dict[str, Type[AbstractCustomQueryset]]] = None,
+        custom_querysets_user_scoped: Optional[Dict[str, bool]] = None,
+        permissions: Optional[List[Type[AbstractPermission]]] = None,
+        pre_hooks: Optional[List] = None,
+        post_hooks: Optional[List] = None,
+        additional_fields: Optional[List[AdditionalField]] = None,
+        filterable_fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
+        searchable_fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
+        ordering_fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
+        fields: Optional[Union[Set[str], Literal["__all__"]]] = None,
+        DEBUG: bool = False,
+    ):
+        self.model = model
+        self._custom_querysets = custom_querysets or {}
+        self._custom_querysets_user_scoped = custom_querysets_user_scoped or {}
+        self._permissions = permissions or []
+        self.pre_hooks = pre_hooks or []
+        self.post_hooks = post_hooks or []
+        self.additional_fields = additional_fields or []
+        self.filterable_fields = filterable_fields or set()
+        self.searchable_fields = searchable_fields or set()
+        self.ordering_fields = ordering_fields or set()
+        self.fields = fields or "__all__"
+        self.DEBUG = DEBUG or False
+
+    @property
+    def permissions(self):
+        """Resolve permission class strings to actual classes on each access"""
+        resolved = []
+        for perm in self._permissions:
+            if isinstance(perm, str):
+                from django.utils.module_loading import import_string
+                try:
+                    perm_class = import_string(perm)
+                    resolved.append(perm_class)
+                except ImportError:
+                    raise ImportError(f"Could not import permission class: {perm}")
+            else:
+                resolved.append(perm)
+        return resolved
+
+    @property
+    def custom_querysets(self):
+        """Resolve queryset class strings to actual classes on each access"""
+        resolved = {}
+        for key, queryset in self._custom_querysets.items():
+            if isinstance(queryset, str):
+                from django.utils.module_loading import import_string
+                try:
+                    qs_class = import_string(queryset)
+                    resolved[key] = qs_class
+                except ImportError:
+                    raise ImportError(f"Could not import queryset class: {queryset}")
+            else:
+                resolved[key] = queryset
+        return resolved
+    
+    @property
+    def custom_querysets_user_scoped(self):
+        """Resolve queryset class strings to actual classes on each access"""
+        resolved = {}
+        for key, queryset in self._custom_querysets_user_scoped.items():
+            if isinstance(queryset, str):
+                from django.utils.module_loading import import_string
+                try:
+                    qs_class = import_string(queryset)
+                    resolved[key] = qs_class
+                except ImportError:
+                    raise ImportError(f"Could not import queryset class: {queryset}")
+            else:
+                resolved[key] = queryset
+        return resolved
+
+class Registry:
+    """
+    Global registry mapping models to their ModelConfig.
+    """
+
+    _models_config: Dict[Type, ModelConfig] = {}
+
+    @classmethod
+    def register(cls, model: Type, config: ModelConfig) -> None:
+        if model in cls._models_config:
+            raise ValueError(f"Model {model.__name__} is already registered.")
+        cls._models_config[model] = config
+
+    @classmethod
+    def get_config(cls, model: Type) -> ModelConfig:
+        config = cls._models_config.get(model)
+        if not config:
+            raise ValueError(f"Model {model.__name__} is not registered.")
+        return config