Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

refactor(list-queries): one PageQuery door for the page/per_page dialect (C3)

Juan Denis5d7fa225a6ec
diff --git a/backend/app/api/_query.py b/backend/app/api/_query.py
index 065874b5..e962978d 100644
--- a/backend/app/api/_query.py
+++ b/backend/app/api/_query.py
@@ -42,6 +42,8 @@ from datetime import datetime, timedelta
from sqlalchemy import and_, or_, inspect
+from app.exceptions import ValidationError
+
# Hard ceiling on ``$top``. A list endpoint that answers "give me everything"
# is how /apps got to an unbounded ``query.all()``; a caller that genuinely
# wants more than this should page.
@@ -57,8 +59,13 @@ COMPARE_OPS = {
}
-class QueryParseError(ValueError):
- """A malformed query parameter. API layers turn this into a 400."""
+class QueryParseError(ValidationError):
+ """A malformed query parameter.
+
+ A ``ValidationError`` subclass so the global error handler answers it as a
+ 400 with the standard body — routes no longer need their own translation
+ (the existing per-route ``except QueryParseError`` blocks keep working).
+ """
@dataclass(frozen=True)
@@ -103,6 +110,36 @@ class ListQuery:
return cls.from_args(http_request.args, default_top=default_top)
+@dataclass(frozen=True)
+class PageQuery:
+ """Typed ``page``/``per_page`` parameters for offset-paginated lists.
+
+ The page-numbered dialect of :class:`ListQuery` — some list endpoints and
+ their consumers speak ``page``/``per_page`` rather than ``$skip``/``$top``.
+ They are not interchangeable and are not pretended to be; this is the one
+ place that dialect is parsed, defaulted, and bounded.
+ """
+
+ page: int = 1
+ per_page: int = 50
+
+ @property
+ def skip(self) -> int:
+ return (self.page - 1) * self.per_page
+
+ @classmethod
+ def from_args(cls, args, *, default_per_page=50, max_per_page=100):
+ page = _int_arg(args.get('page'), 1, 'page')
+ per_page = _int_arg(args.get('per_page'), default_per_page, 'per_page')
+ return cls(page=max(1, page),
+ per_page=max(1, min(per_page, max_per_page)))
+
+ @classmethod
+ def from_request(cls, http_request, *, default_per_page=50, max_per_page=100):
+ return cls.from_args(http_request.args, default_per_page=default_per_page,
+ max_per_page=max_per_page)
+
+
def _columns(model):
"""The model's real mapped columns — and the field allowlist."""
return {c.key: getattr(model, c.key) for c in inspect(model).mapper.column_attrs}
diff --git a/backend/app/api/admin.py b/backend/app/api/admin.py
index 9b833870..dbb44b11 100644
--- a/backend/app/api/admin.py
+++ b/backend/app/api/admin.py
@@ -2,6 +2,8 @@
from datetime import date, datetime, timedelta
from typing import Dict, List, Optional
from flask import Blueprint, request, jsonify
+
+from app.api._query import PageQuery
from flask_jwt_extended import get_jwt_identity
from sqlalchemy import func
from app import db
@@ -240,18 +242,14 @@ def delete_user(user_id):
@admin_required
def get_audit_logs():
"""Get audit logs with pagination and filtering."""
- page = request.args.get('page', 1, type=int)
- per_page = request.args.get('per_page', 50, type=int)
+ paging = PageQuery.from_request(request)
action = request.args.get('action')
user_id = request.args.get('user_id', type=int)
target_type = request.args.get('target_type')
- # Limit per_page to reasonable values
- per_page = min(per_page, 100)
-
pagination = AuditService.get_logs(
- page=page,
- per_page=per_page,
+ page=paging.page,
+ per_page=paging.per_page,
action=action,
user_id=user_id,
target_type=target_type
@@ -738,8 +736,7 @@ def get_activity_summary():
@admin_required
def get_activity_feed():
"""Get paginated activity feed with filters."""
- page = request.args.get('page', 1, type=int)
- per_page = min(request.args.get('per_page', 50, type=int), 100)
+ paging = PageQuery.from_request(request)
user_id = request.args.get('user_id', type=int)
action = request.args.get('action')
target_type = request.args.get('target_type')
@@ -748,8 +745,8 @@ def get_activity_feed():
end_date = request.args.get('end_date')
kwargs = {
- 'page': page,
- 'per_page': per_page,
+ 'page': paging.page,
+ 'per_page': paging.per_page,
'user_id': user_id,
'action': action,
'target_type': target_type,
diff --git a/backend/app/api/error_logs.py b/backend/app/api/error_logs.py
index 4bf565b1..8bfb5c1e 100644
--- a/backend/app/api/error_logs.py
+++ b/backend/app/api/error_logs.py
@@ -5,6 +5,7 @@ from collections import defaultdict, deque
from flask import Blueprint, jsonify, request
from flask_jwt_extended import get_jwt_identity, verify_jwt_in_request
+from app.api._query import PageQuery
from app.middleware.rbac import admin_required
from app.services import error_log_service
@@ -46,13 +47,13 @@ def list_error_logs():
resolved = None
if resolved_arg is not None:
resolved = resolved_arg.lower() in ('1', 'true', 'yes')
- per_page = min(request.args.get('per_page', 25, type=int), 100)
+ paging = PageQuery.from_request(request, default_per_page=25)
result = error_log_service.list_errors(
source=request.args.get('source'),
resolved=resolved,
search=request.args.get('search'),
- page=request.args.get('page', 1, type=int),
- per_page=per_page,
+ page=paging.page,
+ per_page=paging.per_page,
)
return jsonify(result), 200
diff --git a/backend/app/api/telemetry.py b/backend/app/api/telemetry.py
index c9728bcd..0d00ed25 100644
--- a/backend/app/api/telemetry.py
+++ b/backend/app/api/telemetry.py
@@ -5,6 +5,7 @@ from flask import Blueprint, request, jsonify
from flask_jwt_extended import jwt_required, get_jwt_identity
from sqlalchemy import func
+from app.api._query import PageQuery
from app import db
from app.middleware.rbac import admin_required
from app.models.system_event import SystemEvent
@@ -17,8 +18,7 @@ telemetry_bp = Blueprint('telemetry', __name__)
@jwt_required()
def list_events():
"""List system events with filtering and pagination."""
- page = request.args.get('page', 1, type=int)
- per_page = request.args.get('per_page', 50, type=int)
+ paging = PageQuery.from_request(request, max_per_page=200)
source = request.args.get('source') or None
event_type = request.args.get('event_type') or None
severity = request.args.get('severity') or None
@@ -31,8 +31,8 @@ def list_events():
end_date = _parse_iso_datetime(request.args.get('end_date'))
pagination = TelemetryService.get_events(
- page=page,
- per_page=min(per_page, 200),
+ page=paging.page,
+ per_page=paging.per_page,
source=source,
event_type=event_type,
severity=severity,
diff --git a/backend/tests/test_query_layer.py b/backend/tests/test_query_layer.py
index eeb0672f..11f3ebb3 100644
--- a/backend/tests/test_query_layer.py
+++ b/backend/tests/test_query_layer.py
@@ -257,3 +257,42 @@ def test_server_select_accepts_its_derived_fields(app):
with app.app_context():
fields = parse_select('name,group_name', Server, extra=Server.DERIVED_FIELDS)
assert fields == {'name', 'group_name', 'id'}
+
+
+# --------------------------------------------------------------- PageQuery #
+
+class TestPageQuery:
+ """The page/per_page dialect parses, defaults, and bounds in ONE place."""
+
+ def _pq(self, args, **kw):
+ from app.api._query import PageQuery
+ return PageQuery.from_args(args, **kw)
+
+ def test_defaults(self):
+ pq = self._pq({})
+ assert (pq.page, pq.per_page, pq.skip) == (1, 50, 0)
+
+ def test_parses_and_computes_skip(self):
+ pq = self._pq({'page': '3', 'per_page': '20'})
+ assert (pq.page, pq.per_page, pq.skip) == (3, 20, 40)
+
+ def test_bounds_per_page_to_the_endpoint_cap(self):
+ assert self._pq({'per_page': '9999'}).per_page == 100
+ assert self._pq({'per_page': '9999'}, max_per_page=200).per_page == 200
+
+ def test_floors_page_zero_and_rejects_negatives(self):
+ from app.api._query import QueryParseError
+ assert self._pq({'page': '0'}).page == 1
+ with pytest.raises(QueryParseError):
+ self._pq({'per_page': '-5'})
+
+ def test_garbage_is_a_typed_400_not_a_silent_default(self):
+ from app.api._query import QueryParseError
+ with pytest.raises(QueryParseError):
+ self._pq({'page': 'banana'})
+
+ def test_queryparseerror_is_a_validation_error(self):
+ """The global handler answers it as a 400 — no per-route translation."""
+ from app.api._query import QueryParseError
+ from app.exceptions import ValidationError
+ assert issubclass(QueryParseError, ValidationError)