loom-kernel 2.22.3__tar.gz → 3.0.0__tar.gz

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/CHANGELOG.md

@@ -602,6 +602,37 @@
 
 ### rest
 
+- **rest:** a `QuerySpec` route filters and sorts only on the columns it
+  declares. Before, a client could filter or sort on any field the repository
+  could resolve. Now a filter on an undeclared column answers
+  `400 unsupported_query` naming the field, and so does a sort on one, with the
+  same answer whether or not the column exists. The primary key, which the
+  route orders by when the client names no sort, needs no declaration.
+  Declare `filterable` and `sortable` on the interface (its auto-CRUD `list`
+  route included) or on a route, which overrides it, as field references or
+  column names:
+
+  ```python
+  class OrderRestInterface(RestInterface[Order]):
+      prefix = "/orders"
+      auto = True
+      filterable = (F(Order).status, F(Order).total)
+      sortable = (F(Order).created_at,)
+  ```
+
+  In `app.rest.interfaces` both take column names (`[status, total]`).
+  `ALL` (`all` in YAML) keeps every scalar column and logs a warning naming
+  the route at startup. Only scalar columns of the use case's own model
+  (`UseCase[Model, ...]`) qualify. A related model's column (`warehouse.code`)
+  is refused, and so are JSON, array and text-search columns; lists, dicts
+  and structs, and an `Enum` or `Literal` declared without a column type, are
+  JSON. `InterfaceCompilationError` names the route and the field. It is also
+  raised for a declaration on a use case with no model, and for a route-level
+  declaration on a route without a `QuerySpec`; an inherited one is ignored.
+  `exists` and `not_exists` answer `400 unsupported_query`, and so do `like`
+  and `ilike` on a column that is not `str`. The repository's
+  `allowed_filter_fields` is unchanged: programmatic callers are not
+  restricted.
 - **rest:** every route now resolves its request parameters and decodes its
   body before the use case is built, so a request refused at that point
   never runs the use case's constructor.
@@ -767,6 +798,12 @@
 
 ### core
 
+- **core:** the SQLAlchemy query compiler converts a filter value, and each
+  `in` item, as the repository converts a value it writes
+  (`loom.core.repository.sqlalchemy.values.to_column_value`, now shared by
+  both): an `Enum` member is bound as its value, a JSON column's value is
+  reduced to builtins. A plain `Enum` member as the value of a filter on a
+  string column failed to bind.
 - **core:** a `BoundaryValidationError` no longer echoes the rejected value
   (#347). msgspec's `Invalid enum value 'x'` (an `Enum`, `IntEnum` or `Literal`
   field or dict key) and `Invalid value 'x'` (a tagged-union tag) become
@@ -953,6 +990,29 @@
 
 ### rest
 
+- **rest:** `?sort=` accepted any column. A cursor page put the sort
+  column's raw value of its last row in `nextCursor` (base64 JSON), so any
+  column, a secret one included, could be read through it, and a forged
+  cursor could range-probe it. Offset pages leaked its order, and an unknown
+  column answered `400 unsupported_query` (`Unknown filter field path`) while
+  a known one answered `200`, so the model's columns could be enumerated. A
+  route now sorts only by its declared `sortable` columns and its primary
+  key, so a cursor carries only those values.
+- **rest:** a `page` whose offset, `(page - 1) * limit`, exceeds the largest
+  signed 64-bit integer answers `400 query_validation` on `page` before any
+  query runs.
+- **rest:** a `QuerySpec` filter value was typed by its spelling: `true` and
+  `false` became booleans, text with a `.` a float and digits an integer,
+  whatever the filtered field declared. `?code=0123` on a `str` field compared
+  against `123`, and on Postgres a number bound to a text column answered
+  `500`. Values of `eq`, `ne`, `gt`, `gte`, `lt`, `lte` and each item of `in`
+  are now converted by the type of the declared filterable field, with the
+  strict grammar of `Query()`: a `str` field keeps the text as sent, a
+  boolean accepts only `true` or `false`, an `Enum` or `Literal` only its
+  values, and a value its field's type refuses answers `400 query_validation`
+  with `violations` naming the field. The field's constraints
+  (`msgspec.Meta`) do not apply to a filter value, so `rank__gt=0` is valid
+  on a column declared `ge=1`. `like` and `ilike` keep their pattern as text.
 - **rest:** the OpenAPI `limit` parameter of a `QuerySpec` route published
   `maximum: 1000` and `default: 50` whatever `RestApiDefaults.max_limit` said,
   while the router clamped `?limit=` to `max_limit`. The schema now publishes

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.22.3
+Version: 3.0.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/core/model/introspection.py

@@ -316,6 +316,32 @@ def generic_type_arg(annotation: Any, origin: Any) -> type | None:
     return args[0]
 
 
+_NON_SCALAR_COLUMN_TYPES = frozenset(
+    {"JSON", "Postgres.JSONB", "Postgres.ARRAY", "Postgres.TSVECTOR"}
+)
+
+
+def scalar_column_annotations(model: type) -> dict[str, Any]:
+    """Return the annotation of each scalar column of *model*, ``Annotated`` metadata removed.
+
+    A JSON, array or text-search column is not scalar; lists, dicts and
+    structs, and an ``Enum`` or ``Literal`` declared without a column type,
+    are inferred as JSON.
+
+    Args:
+        model: Model whose columns are read.
+
+    Returns:
+        Mapping of column name to its annotation, in declaration order.
+    """
+    hints = get_type_hints(model)
+    return {
+        name: hints[name]
+        for name, info in get_column_fields(model).items()
+        if info.column_type.type_name not in _NON_SCALAR_COLUMN_TYPES
+    }
+
+
 def _extract_origin_type(annotation: Any) -> type[Any]:
     """Return the base type from ``Annotated[T, ...]``."""
     origin = getattr(annotation, "__origin__", None)

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/core/repository/sqlalchemy/mixins.py

@@ -3,10 +3,7 @@ from __future__ import annotations
 from abc import abstractmethod
 from collections.abc import Sequence
 from contextlib import AbstractAsyncContextManager
-from datetime import date, datetime, time
-from decimal import Decimal
 from typing import Any, ClassVar, Generic, cast
-from uuid import UUID
 
 import msgspec
 from sqlalchemy import and_, exists, func, insert, inspect, select, tuple_
@@ -36,11 +33,9 @@ from loom.core.repository.mutation import MutationEvent
 from loom.core.repository.sqlalchemy.integrity import handle_integrity_errors
 from loom.core.repository.sqlalchemy.query_compiler.compiler import QuerySpecCompiler
 from loom.core.repository.sqlalchemy.transactional import record_mutation
+from loom.core.repository.sqlalchemy.values import is_json_column, to_column_value
 
 _SENTINEL = object()
-# Values SQLAlchemy binds natively; encoding them to strings breaks typed columns.
-_NATIVE_COLUMN_TYPES = (bytes, datetime, date, time, Decimal, UUID)
-_JSON_TYPE_NAMES = frozenset({"JSON", "Postgres.JSONB"})
 _TOTAL_COUNT_ALIAS = "__loom_total_count"
 
 
@@ -77,9 +72,7 @@ class SQLAlchemyContextMixin(Generic[OutputT, IdT]):
         column_field_names = frozenset(column_fields.keys())
         self._column_field_names = column_field_names
         self._json_column_names = frozenset(
-            name
-            for name, info in column_fields.items()
-            if info.column_type.type_name in _JSON_TYPE_NAMES
+            name for name in column_fields if is_json_column(getattr(sa, name, None))
         )
         self._relations_cache = get_relations(self.model)
         self._core_model = get_compiled_core(self.model)
@@ -165,7 +158,7 @@ class SQLAlchemyContextMixin(Generic[OutputT, IdT]):
 
     def _serialize_input(self, data: msgspec.Struct | dict[str, Any]) -> dict[str, Any]:
         if isinstance(data, msgspec.Struct):
-            builtins = msgspec.to_builtins(data, builtin_types=_NATIVE_COLUMN_TYPES)
+            builtins = to_column_value(data)
             if not isinstance(builtins, dict):
                 raise TypeError("Struct payload must serialize to dict")
             return self._encode_json_columns(_to_internal_field_names(type(data), builtins))
@@ -174,7 +167,7 @@ class SQLAlchemyContextMixin(Generic[OutputT, IdT]):
     def _encode_json_columns(self, values: dict[str, Any]) -> dict[str, Any]:
         """Reduce JSON-column payloads to JSON-serialisable builtins."""
         for key in self._json_column_names.intersection(values):
-            values[key] = msgspec.to_builtins(values[key])
+            values[key] = to_column_value(values[key], json=True)
         return values
 
     def _column_for_field(self, field: str) -> Any:

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/core/repository/sqlalchemy/query_compiler/filters.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import Any
 
 from sqlalchemy import and_, or_
+from sqlalchemy.sql.expression import ClauseElement
 
 from loom.core.repository.abc.query import FilterGroup, FilterOp, FilterSpec
 from loom.core.repository.sqlalchemy.query_compiler.errors import UnsafeFilterError
@@ -14,6 +15,7 @@ from loom.core.repository.sqlalchemy.query_compiler.subquery import (
     compile_exists,
     compile_not_exists,
 )
+from loom.core.repository.sqlalchemy.values import is_json_column, to_column_value
 
 _RELATION_OPS = frozenset([FilterOp.EXISTS, FilterOp.NOT_EXISTS])
 _SIMPLE_OPS: dict[FilterOp, Callable[[Any, Any], Any]] = {
@@ -74,7 +76,19 @@ def _compile_spec(
 
 
 def _apply_op(col: Any, op: FilterOp, value: Any) -> Any:
+    """Apply *op*, converting *value* as the repository converts a value it writes.
+
+    A SQLAlchemy expression, and an ``IN`` value that is a string or not
+    iterable, reach SQLAlchemy as they are.
+    """
     handler = _SIMPLE_OPS.get(op)
-    if handler is not None:
+    if handler is None:
+        raise ValueError(f"Unsupported FilterOp: {op!r}")
+    if isinstance(value, ClauseElement):
+        return handler(col, value)
+    json = is_json_column(col)
+    if op is not FilterOp.IN:
+        return handler(col, to_column_value(value, json=json))
+    if isinstance(value, str | bytes) or not isinstance(value, Iterable):
         return handler(col, value)
-    raise ValueError(f"Unsupported FilterOp: {op!r}")
+    return handler(col, [to_column_value(item, json=json) for item in value])

loom_kernel-3.0.0/src/loom/core/repository/sqlalchemy/values.py

@@ -0,0 +1,51 @@
+"""Column form of model values in SQLAlchemy rows.
+
+SQLAlchemy binds ``bytes``, ``datetime``, ``date``, ``time``, ``Decimal`` and
+``UUID`` natively; every other value is reduced to msgspec builtins (an
+``Enum`` to its value, a struct to a dict). A JSON column holds builtins only,
+so its values are reduced completely.
+
+:func:`to_column_value` is the conversion the repository applies to a value it
+writes and the query compiler to a filter value, so a filter compares against
+exactly what the row holds.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time
+from decimal import Decimal
+from typing import Any
+from uuid import UUID
+
+import msgspec
+from sqlalchemy import JSON
+
+# Values SQLAlchemy binds natively; encoding them to strings breaks typed columns.
+_NATIVE_COLUMN_TYPES = (bytes, datetime, date, time, Decimal, UUID)
+
+
+def to_column_value(value: object, *, json: bool = False) -> Any:
+    """Return the form ``value`` takes in a column.
+
+    Args:
+        value: A model value or a filter value.
+        json: ``True`` when the column is a JSON column.
+
+    Returns:
+        ``value`` reduced to msgspec builtins, keeping the natively bound
+        types unless the column is a JSON column.
+    """
+    if json:
+        return msgspec.to_builtins(value)
+    return msgspec.to_builtins(value, builtin_types=_NATIVE_COLUMN_TYPES)
+
+
+def is_json_column(column: object) -> bool:
+    """Whether *column*, a SQLAlchemy column or mapped attribute, holds JSON.
+
+    ``JSON`` and the dialect types derived from it (Postgres ``JSONB``) count.
+    """
+    return isinstance(getattr(column, "type", None), JSON)
+
+
+__all__ = ["is_json_column", "to_column_value"]

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/rest/__init__.py

@@ -19,6 +19,7 @@ from loom.rest.config import RestInterfaceConfigError
 from loom.rest.errors import HttpErrorMapper
 from loom.rest.middleware import TraceIdMiddleware
 from loom.rest.model import (
+    ALL,
     PaginationMode,
     RestApiDefaults,
     RestInterface,
@@ -27,6 +28,7 @@ from loom.rest.model import (
 from loom.rest.rest_adapter import LoomRestAdapter
 
 __all__ = [
+    "ALL",
     "CompiledRoute",
     "HttpErrorMapper",
     "InterfaceCompilationError",

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/rest/compiler.py

@@ -21,6 +21,10 @@ Compilation steps per interface:
    - Read the fields of a ``Query()`` parameter, refusing a non-scalar field,
      a name shared with a path parameter or ``profile``, or a ``QuerySpec``
      parameter next to it.
+   - Resolve the filterable and sortable columns of a ``QuerySpec`` route
+     (route → interface) against its use case's model, refusing a field
+     reference rooted elsewhere, a name that is not a scalar column of that
+     model, and a route-level declaration on a route without a ``QuerySpec``.
    - Refuse ``expose_profile`` without ``allowed_profiles``.
 """
 
@@ -28,6 +32,7 @@ from __future__ import annotations
 
 import functools
 import inspect
+import logging
 import operator
 import types
 import typing
@@ -40,12 +45,23 @@ from typing import Any, NamedTuple
 from loom.core.engine.compiler import UseCaseCompiler
 from loom.core.engine.metrics import MetricsAdapter
 from loom.core.engine.plan import ExecutionPlan
-from loom.core.model import loom_type
+from loom.core.model import UnsupportedBoundaryType, get_column_fields, loom_type, msgspec_type
 from loom.core.model._json_schema import DEFS, DEFS_PREFIX, REF, definition, without_null
+from loom.core.model.introspection import scalar_column_annotations
 from loom.core.repository.abc.query import QuerySpec
+from loom.core.use_case.field_ref import FieldRef
 from loom.core.use_case.outcome import Created
 from loom.rest.constants import QueryParam
-from loom.rest.model import PaginationMode, RestApiDefaults, RestInterface, RestRoute
+from loom.rest.model import (
+    ALL,
+    DeclaredFields,
+    PaginationMode,
+    RestApiDefaults,
+    RestInterface,
+    RestRoute,
+)
+
+_logger = logging.getLogger(__name__)
 
 
 class _RouteOrigin(Enum):
@@ -333,6 +349,11 @@ class CompiledRoute:
             parameter of this route.
         query_fields: Parameters the route's ``Query()`` declares; empty
             when the use case declares none.
+        filter_fields: ``(column, annotation)`` of each column a client may
+            filter the route's ``QuerySpec`` on, the annotation without its
+            ``Annotated`` metadata; empty when the route filters nothing.
+        sort_fields: Columns a client may sort the route's ``QuerySpec`` by:
+            the declared ``sortable`` ones and the primary key.
         result_type: Result type of ``execute`` without its ``Created``
             member, answered with the route's ``status_code``.
         created_type: Type a ``Created`` result wraps, answered with ``201``;
@@ -356,10 +377,109 @@ class CompiledRoute:
     effective_requires_roles: tuple[str, ...] = ()
     effective_max_limit: int = 1000
     query_fields: tuple[QueryField, ...] = ()
+    filter_fields: tuple[tuple[str, Any], ...] = ()
+    sort_fields: tuple[str, ...] = ()
     result_type: Any = Any
     created_type: Any = None
 
 
+@dataclass(frozen=True)
+class _ColumnPolicy:
+    """Resolves the columns a route lets a client filter or sort on (route → interface).
+
+    Args:
+        where: Route label used in compilation errors and warnings.
+        model: The use case's model, ``None`` when it declares none.
+        takes_query_spec: Whether the use case takes a ``QuerySpec``.
+    """
+
+    where: str
+    model: type[Any] | None
+    takes_query_spec: bool
+
+    def resolve(
+        self, kind: str, on_route: DeclaredFields | None, on_interface: DeclaredFields | None
+    ) -> dict[str, Any]:
+        """Return ``{column: annotation}`` for the declared *kind* (``filterable``/``sortable``).
+
+        A declaration inherited by a route without a ``QuerySpec`` is ignored.
+
+        Raises:
+            InterfaceCompilationError: The route itself declares *kind* but
+                takes no ``QuerySpec``, the use case declares no model, or an
+                entry is not a scalar column of the route's model.
+        """
+        if on_route is not None and not self.takes_query_spec:
+            raise InterfaceCompilationError(
+                f"{self.where} declares {kind} fields, but its use case takes no QuerySpec."
+            )
+        declared = on_route if on_route is not None else on_interface
+        if not declared or not self.takes_query_spec:
+            return {}
+        if self.model is None:
+            source = "declares" if on_route is not None else "inherits"
+            raise InterfaceCompilationError(
+                f"{self.where} {source} {kind} fields, but its use case declares no model; "
+                "declare it as UseCase[Model, ...]."
+            )
+        columns = scalar_column_annotations(self.model)
+        if declared is ALL:
+            _logger.warning(
+                "%s makes every scalar column of %s %s (ALL); declare the columns instead.",
+                self.where,
+                self.model.__name__,
+                kind,
+            )
+            return columns
+        resolved: dict[str, Any] = {}
+        for entry in declared:
+            name = self._column_name(kind, entry)
+            if name not in columns:
+                raise InterfaceCompilationError(
+                    f"{self.where}: {kind} field {name!r} is not a scalar column of "
+                    f"{self.model.__name__}."
+                )
+            resolved[name] = columns[name]
+        return resolved
+
+    def filter_fields(
+        self, on_route: DeclaredFields | None, on_interface: DeclaredFields | None
+    ) -> tuple[tuple[str, Any], ...]:
+        """Resolve ``filterable``, refusing a column whose type a query value cannot decode.
+
+        Raises:
+            InterfaceCompilationError: As :meth:`resolve`, or msgspec cannot
+                describe a declared column's type.
+        """
+        columns = self.resolve("filterable", on_route, on_interface)
+        for name, annotation in columns.items():
+            try:
+                msgspec_type(annotation).schema()
+            except (TypeError, UnsupportedBoundaryType) as exc:
+                raise InterfaceCompilationError(
+                    f"{self.where}: filterable field {name!r} has a type a query value "
+                    f"cannot be decoded into: {exc}"
+                ) from exc
+        return tuple(columns.items())
+
+    def default_order(self) -> tuple[str, ...]:
+        """Primary-key columns, the order the route applies when the client names none."""
+        if self.model is None or not self.takes_query_spec:
+            return ()
+        fields = get_column_fields(self.model)
+        return tuple(name for name, info in fields.items() if info.field.primary_key)
+
+    def _column_name(self, kind: str, entry: FieldRef | str) -> str:
+        if not isinstance(entry, FieldRef):
+            return entry
+        if entry.root is not self.model:
+            raise InterfaceCompilationError(
+                f"{self.where}: {kind} field {'.'.join(entry.path)!r} is rooted at "
+                f"{entry.root!r}, not at the route's model."
+            )
+        return ".".join(entry.path)
+
+
 class RestInterfaceCompiler:
     """Compiles RestInterface declarations into CompiledRoute records.
 
@@ -509,6 +629,13 @@ class RestInterfaceCompiler:
             seen[key] = route
 
             full_path = f"{prefix}{route.path}" if route.path else prefix or "/"
+            where = f"{iface_name}: route ({route.method.upper()}, {route.path!r})"
+            takes_query_spec = any(names_query_spec(pb.annotation) for pb in plan.param_bindings)
+            columns = _ColumnPolicy(
+                where=where,
+                model=route.use_case.describe_main_repo()[0],
+                takes_query_spec=takes_query_spec,
+            )
 
             compiled.append(
                 CompiledRoute(
@@ -527,7 +654,16 @@ class RestInterfaceCompiler:
                     execute_param_types=self._resolve_execute_param_types(route.use_case),
                     effective_requires_roles=self._resolve_requires_roles(route, interface),
                     effective_max_limit=self._defaults.max_limit,
-                    query_fields=self._resolve_query_fields(iface_name, route, plan),
+                    query_fields=self._resolve_query_fields(where, takes_query_spec, route, plan),
+                    filter_fields=columns.filter_fields(route.filterable, interface.filterable),
+                    sort_fields=tuple(
+                        dict.fromkeys(
+                            (
+                                *columns.resolve("sortable", route.sortable, interface.sortable),
+                                *columns.default_order(),
+                            )
+                        )
+                    ),
                     result_type=result_type,
                     created_type=created_type,
                 )
@@ -583,13 +719,12 @@ class RestInterfaceCompiler:
 
     @staticmethod
     def _resolve_query_fields(
-        iface_name: str, route: RestRoute, plan: ExecutionPlan
+        where: str, takes_query_spec: bool, route: RestRoute, plan: ExecutionPlan
     ) -> tuple[QueryField, ...]:
         binding = plan.query_binding
         if binding is None:
             return ()
-        where = f"{iface_name}: route ({route.method.upper()}, {route.path!r})"
-        if any(names_query_spec(pb.annotation) for pb in plan.param_bindings):
+        if takes_query_spec:
             raise InterfaceCompilationError(
                 f"{where}: Query() cannot be combined with a QuerySpec parameter."
             )

{loom_kernel-2.22.3 → loom_kernel-3.0.0}/src/loom/rest/config.py

@@ -29,7 +29,7 @@ from __future__ import annotations
 
 import types
 from collections.abc import Mapping, Sequence
-from typing import Any
+from typing import Any, Literal
 
 import msgspec
 
@@ -38,7 +38,7 @@ from loom.core.repository.abc.query import PaginationMode
 from loom.core.symbols import import_symbol
 from loom.core.use_case.constants import CrudOp
 from loom.core.use_case.use_case import UseCase
-from loom.rest.model import RestInterface, RestRoute
+from loom.rest.model import ALL, DeclaredFields, RestInterface, RestRoute
 
 __all__ = [
     "DisableRouteConfig",
@@ -89,6 +89,9 @@ class RestRouteConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
         allowed_profiles: Profiles callers may request.
         expose_profile: Whether ``?profile=`` is publicly accepted.
         requires_roles: Roles that grant access to this route.
+        filterable: Columns callers may filter on, or ``all`` for
+            :data:`~loom.rest.model.ALL`.
+        sortable: Columns callers may sort by, or ``all``.
     """
 
     use_case: str
@@ -103,6 +106,8 @@ class RestRouteConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
     allowed_profiles: tuple[str, ...] = ()
     expose_profile: bool = False
     requires_roles: tuple[str, ...] = ()
+    filterable: tuple[str, ...] | Literal["all"] | None = None
+    sortable: tuple[str, ...] | Literal["all"] | None = None
 
 
 class RestInterfaceConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
@@ -134,6 +139,9 @@ class RestInterfaceConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=Tr
         allowed_profiles: Profiles available to callers of this interface.
         expose_profile: Whether ``?profile=`` is publicly accepted by default.
         requires_roles: Roles granting access to every route of this interface.
+        filterable: Columns callers may filter the interface's routes on, or
+            ``all`` for :data:`~loom.rest.model.ALL`.
+        sortable: Columns callers may sort the interface's routes by, or ``all``.
     """
 
     prefix: str = ""
@@ -148,6 +156,8 @@ class RestInterfaceConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=Tr
     allowed_profiles: tuple[str, ...] = ()
     expose_profile: bool = False
     requires_roles: tuple[str, ...] = ()
+    filterable: tuple[str, ...] | Literal["all"] | None = None
+    sortable: tuple[str, ...] | Literal["all"] | None = None
 
 
 class DisableRouteConfig(msgspec.Struct, kw_only=True, forbid_unknown_fields=True):
@@ -214,9 +224,16 @@ def _build_route(interface_name: str, route_cfg: RestRouteConfig) -> RestRoute:
         allowed_profiles=route_cfg.allowed_profiles,
         expose_profile=route_cfg.expose_profile,
         requires_roles=route_cfg.requires_roles,
+        filterable=_declared_fields(route_cfg.filterable),
+        sortable=_declared_fields(route_cfg.sortable),
     )
 
 
+def _declared_fields(value: tuple[str, ...] | Literal["all"] | None) -> DeclaredFields | None:
+    """Map the YAML ``all`` spelling to :data:`~loom.rest.model.ALL`."""
+    return ALL if isinstance(value, str) else value
+
+
 def _class_name(interface_name: str) -> str:
     """Build a readable class name from *interface_name*, always distinct."""
     # Embeds the config key verbatim instead of sanitising it into an
@@ -308,6 +325,8 @@ def _build_interface_class(
         "allowed_profiles": cfg.allowed_profiles,
         "expose_profile": cfg.expose_profile,
         "requires_roles": cfg.requires_roles,
+        "filterable": _declared_fields(cfg.filterable),
+        "sortable": _declared_fields(cfg.sortable),
         # types.new_class defaults __module__ to this function's caller frame
         # (typically "types" itself, via __set_name__ machinery), which would
         # make every traceback, repr, and log line naming this class point at