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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
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.pyindex 065874b5..e962978d 100644--- a/backend/app/api/_query.py+++ b/backend/app/api/_query.py@@ -42,6 +42,8 @@ from datetime import datetime, timedeltafrom 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.pyindex 9b833870..dbb44b11 100644--- a/backend/app/api/admin.py+++ b/backend/app/api/admin.py@@ -2,6 +2,8 @@from datetime import date, datetime, timedeltafrom typing import Dict, List, Optionalfrom flask import Blueprint, request, jsonify++from app.api._query import PageQueryfrom flask_jwt_extended import get_jwt_identityfrom sqlalchemy import funcfrom app import db@@ -240,18 +242,14 @@ def delete_user(user_id):@admin_requireddef 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_requireddef 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.pyindex 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, dequefrom flask import Blueprint, jsonify, requestfrom flask_jwt_extended import get_jwt_identity, verify_jwt_in_request+from app.api._query import PageQueryfrom app.middleware.rbac import admin_requiredfrom app.services import error_log_service@@ -46,13 +47,13 @@ def list_error_logs():resolved = Noneif 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), 200diff --git a/backend/app/api/telemetry.py b/backend/app/api/telemetry.pyindex c9728bcd..0d00ed25 100644--- a/backend/app/api/telemetry.py+++ b/backend/app/api/telemetry.py@@ -5,6 +5,7 @@ from flask import Blueprint, request, jsonifyfrom flask_jwt_extended import jwt_required, get_jwt_identityfrom sqlalchemy import func+from app.api._query import PageQueryfrom app import dbfrom app.middleware.rbac import admin_requiredfrom 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 Noneevent_type = request.args.get('event_type') or Noneseverity = 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.pyindex 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)