GeneralManager 0.87.0__tar.gz → 0.87.1__tar.gz

{generalmanager-0.87.0/src/GeneralManager.egg-info → generalmanager-0.87.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.87.0
+Version: 0.87.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.87.0 → generalmanager-0.87.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.87.0"
+version = "0.87.1"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.87.0 → generalmanager-0.87.1/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.87.0
+Version: 0.87.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.87.0 → generalmanager-0.87.1}/src/GeneralManager.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ src/general_manager/api/graphql_mutations.py
 src/general_manager/api/graphql_ordering.py
 src/general_manager/api/graphql_output.py
 src/general_manager/api/graphql_prefetch.py
+src/general_manager/api/graphql_query_permissions.py
 src/general_manager/api/graphql_relations.py
 src/general_manager/api/graphql_resolvers.py
 src/general_manager/api/graphql_search.py

{generalmanager-0.87.0 → generalmanager-0.87.1}/src/general_manager/api/graphql.py

@@ -36,6 +36,9 @@ import graphene
 from asgiref.sync import async_to_sync
 from channels.layers import BaseChannelLayer
 from django.core.exceptions import ObjectDoesNotExist
+
+from general_manager.interface.requests import RequestNotFoundError
+from general_manager.manager.meta import AttributeEvaluationError
 from django.db import DEFAULT_DB_ALIAS, models, transaction
 from django.utils.module_loading import import_string
 
@@ -120,6 +123,7 @@ from general_manager.api.graphql_resolvers import (
     check_read_permission as _check_read_permission_fn,
     check_read_permission_for_user as _check_read_permission_for_user_fn,
     can_read_instance_for_user as _can_read_instance_for_user_fn,
+    can_read_class_for_user as _can_read_class_for_user_fn,
     create_measurement_resolver as _create_measurement_resolver_fn,
     create_normal_resolver as _create_normal_resolver_fn,
     create_list_resolver as _create_list_resolver_fn,
@@ -2260,17 +2264,32 @@ class GraphQL:
 
         def resolver(
             self: GeneralManager, info: GraphQLResolveInfo, **identification: object
-        ) -> GeneralManager:
+        ) -> GeneralManager | None:
             """
-            Instantiate and return a GeneralManager for the provided identification arguments.
+            Instantiate and authorize a manager before exposing its existence.
 
             Parameters:
                 identification (dict): Mapping of identification argument names to values passed to the manager constructor.
 
             Returns:
-                GeneralManager: The manager instance identified by the provided arguments.
+                GeneralManager | None: The readable manager, or None for missing
+                or unreadable targets.
             """
-            return generalManagerClass(**identification)
+            try:
+                instance = generalManagerClass(**identification)
+            except (ObjectDoesNotExist, RequestNotFoundError):
+                # Missing and unreadable targets share the same public response.
+                return None
+            try:
+                readable = _can_read_instance_for_user_fn(instance, info.context.user)
+            except RequestNotFoundError:
+                return None
+            except AttributeEvaluationError as error:
+                # Request-backed fields hydrate lazily during the row gate.
+                if isinstance(error.__cause__, RequestNotFoundError):
+                    return None
+                raise
+            return instance if readable else None
 
         cls._query_fields[item_field_name] = item_field
         cls._query_fields[f"resolve_{item_field_name}"] = resolver
@@ -2658,6 +2677,12 @@ class GraphQL:
                             continue
                         identification = message.get("identification")
                         if action == "refresh" and identification is None:
+                            if not await asyncio.to_thread(
+                                _can_read_class_for_user_fn,
+                                generalManagerClass,
+                                subscription_user,
+                            ):
+                                continue
                             clear_capability_context(info)
                             yield SubscriptionEvent(item=None, action=action)
                             continue

generalmanager-0.87.1/src/general_manager/api/graphql_query_permissions.py

@@ -0,0 +1,168 @@
+"""Authorize query operands before they influence membership or ordering."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from graphql import GraphQLError
+
+from general_manager.bucket.base_bucket import Bucket
+from general_manager.bucket.request_bucket import RequestBucket
+from general_manager.manager.general_manager import GeneralManager
+
+if TYPE_CHECKING:
+    from graphene import ResolveInfo
+
+
+class QueryFieldPermissionError(GraphQLError):
+    """A requested operand is not authorized on the candidate scope."""
+
+    def __init__(self, field: str) -> None:
+        super().__init__(f"Permission denied to use query field '{field}'.")
+
+
+_LIMIT_ERROR = "Query field authorization candidate limit exceeded."
+_AMBIGUOUS_ERROR = "Cannot authorize ambiguous query relation."
+_RELATION_ERROR = "Permission denied to traverse query relation."
+INCOMPLETE_ERROR = "Query field authorization requires a complete candidate set."
+CUSTOM_PROJECTION_ERROR = (
+    "Cannot authorize fields of a custom search document projection."
+)
+
+# Bound field/path decisions; bucket materialization and row checks precede this.
+MAX_QUERY_PERMISSION_CANDIDATES = 1000
+_LOOKUPS = {
+    "exact",
+    "iexact",
+    "in",
+    "isnull",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "contains",
+    "icontains",
+    "startswith",
+    "istartswith",
+    "endswith",
+    "iendswith",
+    "range",
+}
+
+
+def authorize_query_fields(
+    candidates: Iterable[GeneralManager], info: ResolveInfo, paths: Iterable[str]
+) -> None:
+    """Check all operands against every row-visible candidate, never just hits.
+
+    Related rows require their own row permission as well as field permission.
+    Failure leaves the original candidate set unchanged and rejects the query.
+    """
+    from general_manager.api.graphql_relations import (
+        resolve_general_manager_type,
+        get_graphql_manager_registry,
+    )
+    from general_manager.api.graphql_resolvers import (
+        can_read_instance,
+        check_read_permission,
+        relation_id_alias_field,
+    )
+
+    normalized = set()
+    for path in paths:
+        parts = path.split("__")
+        if parts:
+            normalized.add(tuple(parts))
+    if not normalized:
+        return
+    decisions = 0
+
+    def check(instance: GeneralManager, parts: tuple[str, ...]) -> None:
+        nonlocal decisions
+        decisions += 1
+        if decisions > MAX_QUERY_PERMISSION_CANDIDATES:
+            raise GraphQLError(_LIMIT_ERROR)
+        field, *rest = parts
+        attributes = instance.Interface.get_attribute_types()
+        # Backend collection lookup names can differ from public manager names.
+        aliases = [
+            name
+            for name, metadata in attributes.items()
+            if metadata.get("filter_lookup", name) == field
+        ]
+        names = set(aliases or [field])
+        for name in tuple(names):
+            relation = relation_id_alias_field(type(instance), name)
+            if relation is None and name.endswith("_id"):
+                alias = name.removesuffix("_id")
+                metadata: dict[str, object] = dict(attributes.get(alias, {}))
+                if (
+                    resolve_general_manager_type(
+                        metadata.get("type"), get_graphql_manager_registry()
+                    )
+                    is not None
+                ):
+                    relation = alias
+            if relation is not None:
+                names.add(relation)
+        known_fields = set(attributes) | set(instance.identification)
+        known_fields.update(instance.Interface.get_graph_ql_properties())
+        known_fields.update(instance.Interface.get_attributes())
+        if not names.intersection(known_fields):
+            raise QueryFieldPermissionError(field)
+        if any(not check_read_permission(instance, info, name) for name in names):
+            raise QueryFieldPermissionError(field)
+        if not rest:
+            return
+        if len(aliases) > 1:
+            raise GraphQLError(_AMBIGUOUS_ERROR)
+        field_metadata: dict[str, object] = dict(
+            attributes.get(aliases[0] if aliases else field, {})
+        )
+        if (
+            len(rest) == 1
+            and rest[0] in _LOOKUPS
+            and (
+                (field.endswith("_id") and len(names) > 1)
+                or (
+                    field_metadata.get("type") is not None
+                    and resolve_general_manager_type(
+                        field_metadata.get("type"), get_graphql_manager_registry()
+                    )
+                    is None
+                    and field_metadata.get("relation_kind")
+                    not in {"direct", "collection"}
+                )
+            )
+        ):
+            return
+        related_type = resolve_general_manager_type(
+            field_metadata.get("type"), get_graphql_manager_registry()
+        )
+        if len(rest) == 1 and rest[0] in _LOOKUPS and related_type is not None:
+            related_fields = set(related_type.Interface.get_attribute_types())
+            related_fields.update(related_type.Interface.get_attributes())
+            related_fields.update(related_type.Interface.get_graph_ql_properties())
+            if rest[0] not in related_fields:
+                return
+        value = getattr(instance, aliases[0] if aliases else field)
+        if value is None:
+            return
+        related = value if isinstance(value, (Bucket, list, tuple, set)) else [value]
+        for member in related:
+            if not isinstance(member, GeneralManager):
+                # A lookup is an operator only after resolving its preceding
+                # scalar field. A relation's field named "contains" is a field.
+                if len(rest) == 1 and rest[0] in _LOOKUPS:
+                    continue
+                raise GraphQLError(_RELATION_ERROR)
+            if not can_read_instance(member, info):
+                raise GraphQLError(_RELATION_ERROR)
+            check(member, tuple(rest))
+
+    for candidate in candidates:
+        for normalized_parts in sorted(normalized):
+            check(candidate, normalized_parts)
+    if isinstance(candidates, RequestBucket) and not candidates.response_is_complete:
+        raise GraphQLError(INCOMPLETE_ERROR)

{generalmanager-0.87.0 → generalmanager-0.87.1}/src/general_manager/api/graphql_resolvers.py

@@ -36,6 +36,7 @@ from graphql import GraphQLError, OperationType
 from graphql.language.ast import FieldNode, FragmentSpreadNode, InlineFragmentNode
 
 from general_manager.logging import get_logger
+from general_manager.conf import get_setting
 from general_manager.bucket.base_bucket import Bucket
 from general_manager.bucket._materialized_bucket import MaterializedBucket
 from general_manager.bucket.group_bucket import GroupBucket
@@ -822,6 +823,38 @@ class InvalidPaginationValueError(ValueError):
         super().__init__(f"{field_name} must be a positive integer")
 
 
+class PaginationLimitExceededError(ValueError):
+    """Raised when an explicit page exceeds the server maximum."""
+
+    def __init__(self, maximum: int) -> None:
+        super().__init__(f"pageSize must not exceed {maximum}")
+
+
+class InvalidPaginationConfigurationError(ValueError):
+    """Raised when configured pagination cannot provide finite valid pages."""
+
+    def __init__(self, setting: str) -> None:
+        super().__init__(
+            f"{setting} must be a positive integer, with default <= maximum"
+        )
+
+
+def _pagination_sizes() -> tuple[int, int]:
+    default = get_setting("GRAPHQL_DEFAULT_PAGE_SIZE", 10)
+    maximum = get_setting("GRAPHQL_MAX_PAGE_SIZE", 100)
+    for name, value in (
+        ("GRAPHQL_DEFAULT_PAGE_SIZE", default),
+        ("GRAPHQL_MAX_PAGE_SIZE", maximum),
+    ):
+        if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+            raise InvalidPaginationConfigurationError(name)
+    default = cast(int, default)
+    maximum = cast(int, maximum)
+    if default > maximum:
+        raise InvalidPaginationConfigurationError("GRAPHQL_DEFAULT_PAGE_SIZE")
+    return default, maximum
+
+
 @dataclass(frozen=True, slots=True)
 class EffectivePagination:
     """Normalized public pagination arguments and their observable defaults."""
@@ -849,19 +882,19 @@ def normalize_pagination(
     page: int | None,
     page_size: int | None,
 ) -> EffectivePagination:
-    """Normalize list pagination once, preserving the unpaginated no-arg mode."""
-    requested = page is not None or page_size is not None
+    """Resolve finite server defaults and reject oversized explicit pages."""
+    default, maximum = _pagination_sizes()
     for field_name, value in (("page", page), ("pageSize", page_size)):
         if value is not None and (
             not isinstance(value, int) or isinstance(value, bool) or value <= 0
         ):
             raise InvalidPaginationValueError(field_name)
-    if not requested:
-        return EffectivePagination(requested=False, page=1, page_size=None)
+    if page_size is not None and page_size > maximum:
+        raise PaginationLimitExceededError(maximum)
     return EffectivePagination(
         requested=True,
         page=1 if page is None else page,
-        page_size=10 if page_size is None else page_size,
+        page_size=default if page_size is None else page_size,
     )
 
 
@@ -922,6 +955,9 @@ def _forward_remote_request_controls(
         terms = order_by_to_sort_terms(order_by)
     except GraphQLOrderingInputError as exc:
         raise GraphQLError(str(exc)) from exc
+    if not isinstance(queryset, RequestBucket) or queryset.request_plan is None:
+        # Concrete snapshots must be paginated locally, never filtered by controls.
+        return queryset, False
     controls: dict[str, object] = {}
     if pagination.requested:
         controls["page"] = pagination.page
@@ -943,8 +979,8 @@ def apply_pagination(
     """
     Return a paginated slice of *queryset*.
 
-    Returns the full queryset when neither ``page`` nor ``page_size`` is
-    given. Defaults to page 1 / size 10 when only one parameter is provided.
+    Omitted controls use page 1 and the configured finite default size (10).
+    Explicit sizes above the configured maximum (100) are rejected.
     Zero, negative, boolean, and non-integer controls raise ``ValueError``
     before slicing.
     Already-empty grouped buckets are returned unchanged when pagination is
@@ -1268,6 +1304,34 @@ def _is_supported_grouped_annotation(
     )
 
 
+def can_read_class_for_user(
+    manager_class: type[GeneralManager],
+    user: object,
+) -> bool:
+    """Authorize an identity-less notification through the class read gate.
+
+    Construct fresh permissions for every event so revocations take effect.
+    Callers in async code must offload this potentially database-backed check.
+    """
+    from django.contrib.auth import get_user_model
+
+    user_model = get_user_model()
+    if isinstance(user, user_model):
+        if user.pk is None:
+            return False
+        user = (
+            user_model._default_manager.using(user._state.db).filter(pk=user.pk).first()
+        )
+        if user is None or not getattr(user, "is_active", True):
+            return False
+    permission_class: type[BasePermission] | None = getattr(
+        manager_class, "Permission", None
+    )
+    if permission_class is not None:
+        return permission_class(manager_class, user).check_operation_permission("read")
+    return True
+
+
 def can_read_instance_for_user(
     instance: GeneralManager,
     user: object,
@@ -1560,9 +1624,8 @@ def create_list_resolver(
         ``pageInfo`` contains ``total_count``, ``page_size``,
         ``current_page``, and ``total_pages`` using the Python-side field names;
         Graphene exposes them as camelCase in the GraphQL schema. ``current_page``
-        reports effective pagination values: supplied single controls default
-        the missing coordinate to page 1 / size 10, while ordinary no-argument
-        lists remain unpaginated with ``page_size=None``. ``total_pages`` is
+        reports effective pagination values: omitted controls default to page 1
+        and the server-configured finite page size (10 by default). ``total_pages`` is
         zero for an exact empty result and ``None`` when the source total is
         incomplete. Invalid pagination values raise
         ``InvalidPaginationValueError`` before slicing.
@@ -1579,6 +1642,7 @@ def create_list_resolver(
         group_by: list[str] | None = None,
         include_inactive: bool = False,
     ) -> ListResolverPayload:
+        effective_pagination = normalize_pagination(page, page_size)
         _ensure_as_of_compatible(self)
         base_queryset = base_getter(self, include_inactive)
         if base_queryset is None:
@@ -1606,7 +1670,12 @@ def create_list_resolver(
             exclude,
             filter_normalizer=bound_filter_normalizer,
         )
-        effective_pagination = normalize_pagination(page, page_size)
+        from general_manager.api.graphql_query_permissions import authorize_query_fields
+
+        operand_paths = (
+            set(plan.filters) | set(plan.excludes) | set(plan.normalized_excludes)
+        )
+        operand_paths.update(term.field for term in order_by_to_sort_terms(order_by))
         from general_manager.interface import CalculationInterface
 
         interface = getattr(manager_class, "Interface", None)
@@ -1614,30 +1683,105 @@ def create_list_resolver(
         remote_ordering_forwarded = False
         request_provenance: RequestPaginationProvenance | None = None
         authorization_result: ReadAuthorizationResult[GeneralManager]
-        if isinstance(interface, type) and issubclass(interface, CalculationInterface):
-            input_plan, deferred_plan = partition_calculation_query_plan(
-                manager_class,
-                plan,
-            )
-            input_queryset = apply_query_parameter_plan(
-                base_queryset,
-                input_plan,
-                None,
+        complete_disjunction: ReadAuthorizationPreparation[GeneralManager] | None = None
+        if is_request_source and not operand_paths:
+            request_permission_plan = get_read_permission_filter(manager_class, info)
+            if (
+                request_permission_plan.decision != "deny_all"
+                and len(request_permission_plan.filters) > 1
+            ):
+                # Check completeness before RequestBucket union loses provenance.
+                # No client predicates are evaluated on this local union.
+                combined = MaterializedBucket(manager_class, [])
+                for permission_filter in request_permission_plan.filters:
+                    branch = base_queryset.filter(
+                        **permission_filter.get("filter", {})
+                    ).exclude(**permission_filter.get("exclude", {}))
+                    if (
+                        isinstance(branch, RequestBucket)
+                        and not branch.response_is_complete
+                    ):
+                        operation = _requested_request_global_operation(
+                            effective_pagination, group_by, order_by
+                        )
+                        raise _request_global_operation_error(operation or "pagination")
+                    combined = combined | MaterializedBucket(manager_class, branch)
+                shape = get_backend_shape(manager_class)
+                complete_disjunction = ReadAuthorizationPreparation(
+                    queryset=combined,
+                    permission_plan=request_permission_plan,
+                    backend_shape=shape,
+                    instance_check_reasons=resolve_instance_check_reasons(
+                        request_permission_plan, backend_shape=shape
+                    ),
+                )
+        if operand_paths and is_request_source:
+            operand_preparation = prepare_read_authorization(
+                base_queryset, manager_class, info
             )
+            # Inspect the permission-filtered source before a final instance
+            # gate can materialize it and discard upstream provenance. Never
+            # touch the original source when the plan denies all rows.
             if (
-                input_plan.filters
-                or input_plan.excludes
-                or input_plan.normalized_excludes
+                operand_preparation.permission_plan.decision != "deny_all"
+                and isinstance(operand_preparation.queryset, RequestBucket)
+                and not operand_preparation.queryset.response_is_complete
             ):
-                input_queryset = input_queryset.with_instances(input_queryset)
+                from general_manager.api.graphql_query_permissions import (
+                    INCOMPLETE_ERROR,
+                )
+
+                raise GraphQLError(INCOMPLETE_ERROR)
+            operand_candidates = finalize_read_authorization(
+                operand_preparation, manager_class, info, source="query_fields"
+            ).queryset
+            authorize_query_fields(operand_candidates, info, operand_paths)
+        if isinstance(interface, type) and issubclass(interface, CalculationInterface):
             authorization_result = apply_read_authorization(
-                input_queryset,
-                manager_class,
-                info,
-                source="list",
+                base_queryset, manager_class, info, source="list"
             )
             qs = authorization_result.queryset
+            authorize_query_fields(qs, info, operand_paths)
+            # Freeze row authorization before constructor-input filters can
+            # replace the calculation bucket's permission constraints.
+            if operand_paths:
+                qs = qs.with_instances(qs)
+            input_plan, deferred_plan = partition_calculation_query_plan(
+                manager_class, plan
+            )
+
+            def canonical_inputs(mapping: GraphQLFilterMapping) -> GraphQLFilterMapping:
+                normalized = {}
+                for lookup, value in mapping.items():
+                    root, separator, suffix = lookup.partition("__")
+                    alias = (
+                        interface.input_fields.get(root.removesuffix("_id"))
+                        if root.endswith("_id")
+                        else None
+                    )
+                    if alias is not None and safe_issubclass(
+                        alias.type, GeneralManager
+                    ):
+                        lookup = (
+                            root.removesuffix("_id")
+                            + "__id"
+                            + (separator + suffix if separator else "")
+                        )
+                    normalized[lookup] = value
+                return normalized
+
+            input_plan = QueryParameterPlan(
+                canonical_inputs(input_plan.filters),
+                canonical_inputs(input_plan.excludes),
+                canonical_inputs(input_plan.normalized_excludes),
+            )
+            qs = apply_query_parameter_plan(qs, input_plan, None)
             qs = apply_query_parameter_plan(qs, deferred_plan, None)
+        elif complete_disjunction is not None:
+            authorization_result = finalize_read_authorization(
+                complete_disjunction, manager_class, info, source="list"
+            )
+            qs = authorization_result.queryset
         elif is_request_source:
             permission_plan = get_read_permission_filter(manager_class, info)
             if permission_plan.decision == "deny_all":
@@ -1692,12 +1836,6 @@ def create_list_resolver(
                     )
                 assert request_provenance is not None
                 if request_provenance.is_partial:
-                    if effective_pagination.requested and (
-                        request_provenance.page != effective_pagination.page
-                        or request_provenance.page_size
-                        != effective_pagination.page_size
-                    ):
-                        raise _request_global_operation_error("pagination")
                     if group_by is not None:
                         raise _request_global_operation_error("grouping")
                     if order_by is not None and not remote_ordering_forwarded:
@@ -1707,6 +1845,12 @@ def create_list_resolver(
                             raise GraphQLError(str(exc)) from exc
                         if has_ordering:
                             raise _request_global_operation_error("ordering")
+                    if effective_pagination.requested and (
+                        request_provenance.page != effective_pagination.page
+                        or request_provenance.page_size
+                        != effective_pagination.page_size
+                    ):
+                        raise _request_global_operation_error("pagination")
                 authorization_result = finalize_read_authorization(
                     authorization_preparation,
                     manager_class,
@@ -1732,6 +1876,7 @@ def create_list_resolver(
                 source="list",
             )
             qs = authorization_result.queryset
+            authorize_query_fields(qs, info, operand_paths)
             qs = apply_query_parameter_plan(qs, plan, None)
         if grouping_validator is not None:
             grouping_validator(qs, group_by, order_by, info)
@@ -1751,16 +1896,6 @@ def create_list_resolver(
             total_count = request_provenance.total_count
 
         metadata_pagination = effective_pagination
-        if (
-            not effective_pagination.requested
-            and request_provenance is not None
-            and request_provenance.page is not None
-        ):
-            metadata_pagination = EffectivePagination(
-                requested=True,
-                page=request_provenance.page,
-                page_size=request_provenance.page_size,
-            )
 
         upstream_page_matches = (
             request_provenance is not None
@@ -1770,7 +1905,7 @@ def create_list_resolver(
             and group_by is None
         )
         qs_paginated = (
-            qs_sorted
+            qs_sorted[: cast(int, metadata_pagination.page_size)]
             if upstream_page_matches
             else apply_pagination(
                 qs_sorted,