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.

perf(api): opt /servers into the query layer

Juan Denis2eeb58daa03b
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index fb422829..85fd2d1e 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -12,7 +12,9 @@ from datetime import datetime, timedelta
from flask import Blueprint, request, jsonify, Response, current_app, redirect
from flask_jwt_extended import jwt_required, get_jwt_identity
+from sqlalchemy.orm import joinedload
from app import db, limiter
+from app.api._query import apply_query, QueryParseError
from app.models import User
from app.models.server import Server, ServerGroup, ServerMetrics, ServerCommand, AgentSession, AgentVersion, AgentRollout
from app.services.agent_registry import agent_registry
@@ -280,7 +282,24 @@ def list_servers():
if tag:
query = query.filter(Server.tags.contains([tag]))
- servers = query.order_by(Server.name).all()
+ # $select / $filter / $orderby / $skip / $top, all optional. No paging meta
+ # is emitted here: this route answers with a bare JSON array, and wrapping
+ # it in an envelope would break every existing caller.
+ try:
+ narrowed = apply_query(query, Server, request, select_extra=Server.DERIVED_FIELDS)
+ except QueryParseError as exc:
+ return jsonify({'error': str(exc)}), 400
+ query = narrowed.query
+ fields = narrowed.fields
+
+ # `group_name` is a relationship load per row; hoist it when it is wanted.
+ if fields is None or 'group_name' in fields:
+ query = query.options(joinedload(Server.group))
+
+ # An explicit $orderby wins; otherwise keep the by-name default the list UI
+ # has always relied on.
+ servers = (query.all() if request.args.get('$orderby')
+ else query.order_by(Server.name).all())
# Latest metrics per server, under the SAME 'metrics' key the detail
# endpoint uses (see get_server_status below) — the servers list renders
@@ -304,7 +323,7 @@ def list_servers():
result = []
for server in servers:
- server_dict = server.to_dict()
+ server_dict = server.to_dict(fields=fields)
server_dict['is_connected'] = agent_registry.is_agent_connected(server.id)
metrics = metrics_by_server.get(server.id)
if metrics:
diff --git a/backend/app/models/server.py b/backend/app/models/server.py
index 1e29748f..d8023279 100644
--- a/backend/app/models/server.py
+++ b/backend/app/models/server.py
@@ -436,7 +436,20 @@ class Server(db.Model):
except (TypeError, ValueError):
return []
- def to_dict(self, include_metrics=False):
+ # Emitted by to_dict but not mapped columns: each costs a relationship load
+ # or a JSON walk, so `$select` has to know they exist in order to decline
+ # them. Kept next to to_dict so the two cannot drift.
+ DERIVED_FIELDS = ('group_name', 'onboarding_progress', 'latest_metrics')
+
+ def to_dict(self, include_metrics=False, fields=None):
+ """Serialize the server.
+
+ `fields` (normally from ``$select``) narrows the payload AND skips the
+ derived work. `onboarding_progress` alone is ~29% of a row and is read
+ by exactly one screen; `group_name` is a relationship load. A list that
+ only needs {id, name} should pay for neither.
+ """
+ want = fields.__contains__ if fields is not None else (lambda _key: True)
result = {
'id': self.id,
'name': self.name,
@@ -444,14 +457,12 @@ class Server(db.Model):
'hostname': self.hostname,
'ip_address': self.ip_address,
'group_id': self.group_id,
- 'group_name': self.group.name if self.group else None,
'workspace_id': self.workspace_id,
'tags': self.tags or [],
'status': self.status,
'last_seen': self.last_seen.isoformat() if self.last_seen else None,
'last_error': self.last_error,
'onboarding_state': self.onboarding_state,
- 'onboarding_progress': self._onboarding_progress_list(),
'onboarding_updated_at': self.onboarding_updated_at.isoformat() if self.onboarding_updated_at else None,
'agent_version': self.agent_version,
'agent_id': self.agent_id,
@@ -473,8 +484,17 @@ class Server(db.Model):
'created_at': self.created_at.isoformat() if self.created_at else None,
'updated_at': self.updated_at.isoformat() if self.updated_at else None,
}
- if include_metrics:
- # Get latest metrics
+ if fields is not None:
+ result = {key: value for key, value in result.items() if key in fields}
+
+ # The derived three, each skippable.
+ if want('group_name'):
+ result['group_name'] = self.group.name if self.group else None
+ if want('onboarding_progress'):
+ result['onboarding_progress'] = self._onboarding_progress_list()
+ if include_metrics and want('latest_metrics'):
+ # `metrics` is lazy='dynamic', so this is a query per server — the
+ # list route batches it instead and never passes include_metrics.
latest = self.metrics.order_by(ServerMetrics.timestamp.desc()).first()
if latest:
result['latest_metrics'] = latest.to_dict()
diff --git a/backend/tests/test_query_layer.py b/backend/tests/test_query_layer.py
index 18316d8f..4c4d2861 100644
--- a/backend/tests/test_query_layer.py
+++ b/backend/tests/test_query_layer.py
@@ -184,3 +184,39 @@ def test_to_dict_can_opt_into_one_derived_field(app, sample_app):
with app.app_context():
data = sample_app.to_dict(fields={'id', 'name', 'image_scan'})
assert set(data) == {'id', 'name', 'image_scan'}
+
+
+# --------------------------------------------- Server: the same narrowing
+
+def test_server_to_dict_is_unchanged_by_default(app):
+ from app import db
+ from app.models.server import Server
+ with app.app_context():
+ row = Server(id='probe-srv', name='probe')
+ db.session.add(row)
+ db.session.commit()
+ data = row.to_dict()
+ assert 'onboarding_progress' in data
+ assert 'group_name' in data
+
+
+def test_server_to_dict_skips_the_expensive_derived_fields(app):
+ """onboarding_progress alone is ~29% of a server row and is read by exactly
+ one screen; group_name is a relationship load."""
+ from app import db
+ from app.models.server import Server
+ with app.app_context():
+ row = Server(id='probe-srv2', name='probe2')
+ db.session.add(row)
+ db.session.commit()
+ data = row.to_dict(fields={'id', 'name'})
+ assert set(data) == {'id', 'name'}
+ assert 'onboarding_progress' not in data
+ assert 'group_name' not in data
+
+
+def test_server_select_accepts_its_derived_fields(app):
+ from app.models.server import Server
+ with app.app_context():
+ fields = parse_select('name,group_name', Server, extra=Server.DERIVED_FIELDS)
+ assert fields == {'name', 'group_name', 'id'}