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
feat(api): centralize typed errors and request correlation
Juan Denisd018a5e979fb
diff --git a/backend/app/__init__.py b/backend/app/__init__.pyindex f9c23a92..254cee33 100644--- a/backend/app/__init__.py+++ b/backend/app/__init__.py@@ -157,7 +157,11 @@ def create_app(config_name=None):app,origins=cors_origins,supports_credentials=True,- allow_headers=['Content-Type', 'Authorization', 'X-Requested-With', 'X-API-Key'],+ allow_headers=[+ 'Content-Type', 'Authorization', 'X-Requested-With', 'X-API-Key',+ 'X-Request-ID',+ ],+ expose_headers=['X-Request-ID'],methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH'],# Every panel request carries an Authorization header, which makes it a# non-simple cross-origin request: without Access-Control-Max-Age the@@ -168,6 +172,11 @@ def create_app(config_name=None):max_age=3600,)+ # Assign one diagnostic ID at the outer API boundary. Downstream handlers,+ # logs and jobs can reuse g.request_id without inventing independent IDs.+ from app.middleware.request_id import register_request_id+ register_request_id(app)+# Register security headers middlewarefrom app.middleware.security import register_security_headersregister_security_headers(app)@@ -891,6 +900,20 @@ def create_app(config_name=None):return send_from_directory(app.static_folder, 'index.html')return {'message': 'ServerKit API is running', 'docs': '/api/v1/'}, 200+ # Expected application failures. Services raise these typed errors and the+ # HTTP boundary owns their public shape and status-code mapping.+ from app.exceptions import ApplicationError+ from app.middleware.request_id import get_request_id++ @app.errorhandler(ApplicationError)+ def application_error(e):+ request_id = get_request_id(create=True)+ app.logger.info(+ 'Application error %s on %s %s [request_id=%s]: %s',+ e.code, request.method, request.path, request_id, e.message,+ )+ return e.to_dict(request_id=request_id), e.status_code+# Unhandled exceptions. Flask only routes here when it is not propagating# (so pytest and the dev server still re-raise with a full traceback);# in production this is the difference between a logged, JSON-shaped 500 and@@ -899,8 +922,10 @@ def create_app(config_name=None):def internal_error(e):original = getattr(e, 'original_exception', None)exc = original or e+ request_id = get_request_id(create=True)app.logger.exception(- 'Unhandled exception on %s %s', request.method, request.path,+ 'Unhandled exception on %s %s [request_id=%s]',+ request.method, request.path, request_id,exc_info=exc)# Roll the failing request's session back BEFORE recording. The 500@@ -938,12 +963,18 @@ def create_app(config_name=None):endpoint=request.path,method=request.method,user_id=user_id,+ context={'request_id': request_id},)except Exception: # noqa: BLE001pass# JSON either way: unlike a 404, there is no sensible SPA fallback for a# crash, and an HTML page tells the caller nothing it can act on.- return {'error': 'Internal server error'}, 500+ return {+ 'error': 'Internal server error',+ 'status': 500,+ 'code': 'internal_error',+ 'request_id': request_id,+ }, 500# Framework-generated HTTP errors (abort(), 405 from the router, 413 from# MAX_CONTENT_LENGTH) rendered Werkzeug's HTML page even under /api/, so an@@ -952,10 +983,17 @@ def create_app(config_name=None):@app.errorhandler(HTTPException)def http_exception(e):if request.path.startswith('/api/'):+ request_id = get_request_id(create=True)app.logger.warning(- 'HTTP %s on %s %s: %s', e.code, request.method, request.path, e.description+ 'HTTP %s on %s %s [request_id=%s]: %s',+ e.code, request.method, request.path, request_id, e.description,)- return {'error': e.description or e.name, 'status': e.code}, e.code+ return {+ 'error': e.description or e.name,+ 'status': e.code,+ 'code': (e.name or 'http_error').lower().replace(' ', '_'),+ 'request_id': request_id,+ }, e.code# Non-API paths keep Werkzeug's standard HTML error page.return e.get_response()@@ -964,7 +1002,12 @@ def create_app(config_name=None):def not_found(e):from flask import requestif request.path.startswith('/api/'):- return {'error': 'Not found'}, 404+ return {+ 'error': 'Not found',+ 'status': 404,+ 'code': 'not_found',+ 'request_id': get_request_id(create=True),+ }, 404# Serve SPA index.html if it exists, otherwise JSON 404index = os.path.join(app.static_folder, 'index.html') if app.static_folder else Noneif index and os.path.isfile(index):diff --git a/backend/app/api/monitors.py b/backend/app/api/monitors.pyindex 80a67dfc..330f3c0a 100644--- a/backend/app/api/monitors.py+++ b/backend/app/api/monitors.py@@ -9,6 +9,7 @@ status page. See app/services/monitor_service.py.from flask import Blueprint, request, jsonifyfrom flask_jwt_extended import jwt_required+from app.exceptions import NotFoundErrorfrom app.services.monitor_service import MonitorServicemonitors_bp = Blueprint('monitors', __name__)@@ -51,10 +52,7 @@ def get_stats():@jwt_required()def create_monitor():data = request.get_json() or {}- try:- monitor = MonitorService.create(data)- except ValueError as e:- return {'error': str(e)}, 400+ monitor = MonitorService.create(data)return jsonify(monitor.to_dict()), 201@@ -63,7 +61,7 @@ def create_monitor():def get_monitor(monitor_id):monitor = MonitorService.get(monitor_id)if not monitor:- return {'error': 'Monitor not found'}, 404+ raise NotFoundError('Monitor not found', code='monitor_not_found')return jsonify(monitor.to_dict())@@ -71,12 +69,9 @@ def get_monitor(monitor_id):@jwt_required()def update_monitor(monitor_id):data = request.get_json() or {}- try:- monitor = MonitorService.update(monitor_id, data)- except ValueError as e:- return {'error': str(e)}, 400+ monitor = MonitorService.update(monitor_id, data)if not monitor:- return {'error': 'Monitor not found'}, 404+ raise NotFoundError('Monitor not found', code='monitor_not_found')return jsonify(monitor.to_dict())diff --git a/backend/app/exceptions.py b/backend/app/exceptions.pynew file mode 100644index 00000000..8ed5ccb3--- /dev/null+++ b/backend/app/exceptions.py@@ -0,0 +1,75 @@+"""Typed application errors rendered consistently at the HTTP boundary.++Services may raise these errors when a caller can act on the failure. Flask+owns their JSON representation; service code therefore does not need to know+about ``jsonify`` or duplicate status-code mapping.++The subclasses of built-in exception types are intentional compatibility+bridges. Existing callers that catch ``ValueError`` or ``LookupError`` keep+working while a feature is migrated incrementally to the typed contract.+"""++from collections.abc import Mapping+++class ApplicationError(Exception):+ """Base class for expected, client-safe application failures."""++ status_code = 500+ code = 'application_error'+ default_message = 'Application error'++ def __init__(self, message=None, *, code=None, details=None):+ self.message = str(message or self.default_message)+ self.code = code or type(self).code+ self.details = dict(details) if isinstance(details, Mapping) else None+ super().__init__(self.message)++ def to_dict(self, *, request_id=None):+ """Return the stable public error body used by API handlers."""+ payload = {+ 'error': self.message,+ 'status': self.status_code,+ 'code': self.code,+ }+ if self.details:+ payload['details'] = self.details+ if request_id:+ payload['request_id'] = request_id+ return payload+++class ValidationError(ApplicationError, ValueError):+ status_code = 400+ code = 'validation_error'+ default_message = 'Invalid request'+++class AuthenticationError(ApplicationError):+ status_code = 401+ code = 'authentication_required'+ default_message = 'Authentication required'+++class PermissionDeniedError(ApplicationError, PermissionError):+ status_code = 403+ code = 'permission_denied'+ default_message = 'Access denied'+++class NotFoundError(ApplicationError, LookupError):+ status_code = 404+ code = 'not_found'+ default_message = 'Resource not found'+++class ConflictError(ApplicationError):+ status_code = 409+ code = 'conflict'+ default_message = 'Resource conflict'+++class DependencyUnavailableError(ApplicationError):+ status_code = 503+ code = 'dependency_unavailable'+ default_message = 'Dependency unavailable'diff --git a/backend/app/middleware/request_id.py b/backend/app/middleware/request_id.pynew file mode 100644index 00000000..98e2bb7c--- /dev/null+++ b/backend/app/middleware/request_id.py@@ -0,0 +1,42 @@+"""Request-ID propagation for API responses, errors, and diagnostic logs."""++import re+import secrets++from flask import g, has_request_context, request+++REQUEST_ID_HEADER = 'X-Request-ID'+_SAFE_REQUEST_ID = re.compile(r'^[A-Za-z0-9._:-]{1,128}$')+++def _new_request_id():+ return secrets.token_hex(16)+++def get_request_id(*, create=False):+ """Return this request's ID, optionally creating it for direct handlers."""+ if not has_request_context():+ return None+ request_id = getattr(g, 'request_id', None)+ if request_id is None and create:+ request_id = _new_request_id()+ g.request_id = request_id+ return request_id+++def register_request_id(app):+ """Accept a safe caller ID or generate one and echo it on API responses."""++ @app.before_request+ def assign_request_id():+ if not request.path.startswith('/api/'):+ return+ supplied = (request.headers.get(REQUEST_ID_HEADER) or '').strip()+ g.request_id = supplied if _SAFE_REQUEST_ID.fullmatch(supplied) else _new_request_id()++ @app.after_request+ def expose_request_id(response):+ if request.path.startswith('/api/'):+ response.headers[REQUEST_ID_HEADER] = get_request_id(create=True)+ return responsediff --git a/backend/app/services/monitor_service.py b/backend/app/services/monitor_service.pyindex 6e68e311..53aad959 100644--- a/backend/app/services/monitor_service.py+++ b/backend/app/services/monitor_service.py@@ -22,6 +22,7 @@ from datetime import datetime, timedeltafrom urllib.parse import urlparsefrom app import db+from app.exceptions import ValidationErrorfrom app.models.status_page import (StatusComponent, HealthCheck, StatusIncident, StatusIncidentUpdate,)@@ -124,23 +125,23 @@ class MonitorService:returnfrom app.models.wordpress_site import WordPressSiteif not WordPressSite.query.get(site_id):- raise ValueError(+ raise ValidationError('wordpress_site_id does not match an existing WordPress site ''(is the WordPress extension installed?)')@staticmethoddef create(data):if not data.get('name'):- raise ValueError('Monitor name is required')+ raise ValidationError('Monitor name is required')check_type = data.get('check_type', 'http')if check_type not in StatusComponent.CHECK_TYPES:- raise ValueError(f'Unknown check type: {check_type}')+ raise ValidationError(f'Unknown check type: {check_type}')if check_type == 'keyword' and not data.get('keyword'):- raise ValueError('A keyword check needs a keyword to look for')+ raise ValidationError('A keyword check needs a keyword to look for')# A monitor needs something to probe unless it is driven by a managed# site's health verdict instead of the network.if not data.get('check_target') and not data.get('wordpress_site_id'):- raise ValueError('Monitor needs a check target or a bound site')+ raise ValidationError('Monitor needs a check target or a bound site')MonitorService._validate_site_binding(data.get('wordpress_site_id'))monitor = StatusComponent(@@ -171,7 +172,7 @@ class MonitorService:if not monitor:return Noneif 'check_type' in data and data['check_type'] not in StatusComponent.CHECK_TYPES:- raise ValueError(f"Unknown check type: {data['check_type']}")+ raise ValidationError(f"Unknown check type: {data['check_type']}")if data.get('wordpress_site_id') is not None:MonitorService._validate_site_binding(data['wordpress_site_id'])for field in MonitorService.WRITABLE_FIELDS:diff --git a/backend/tests/test_api_error_shape.py b/backend/tests/test_api_error_shape.pyindex e74237da..9b56a70d 100644--- a/backend/tests/test_api_error_shape.py+++ b/backend/tests/test_api_error_shape.py@@ -8,6 +8,7 @@ parsing JSON, and unhandled exceptions were never logged with their path."""import logging+import redef test_unknown_api_route_returns_json_404(client):@@ -15,7 +16,10 @@ def test_unknown_api_route_returns_json_404(client):assert response.status_code == 404assert response.is_json- assert response.get_json()['error'] == 'Not found'+ payload = response.get_json()+ assert payload['error'] == 'Not found'+ assert payload['code'] == 'not_found'+ assert payload['request_id'] == response.headers['X-Request-ID']def test_method_not_allowed_on_api_returns_json_not_html(client):@@ -35,6 +39,59 @@ def test_method_not_allowed_on_api_returns_json_not_html(client):payload = response.get_json()assert payload['status'] == 405assert payload['error']+ assert payload['request_id'] == response.headers['X-Request-ID']+++def test_api_request_id_is_propagated(client):+ response = client.get(+ '/api/v1/this-route-does-not-exist',+ headers={'X-Request-ID': 'operator-trace_123'},+ )++ assert response.headers['X-Request-ID'] == 'operator-trace_123'+ assert response.get_json()['request_id'] == 'operator-trace_123'+++def test_unsafe_api_request_id_is_replaced(client):+ response = client.get(+ '/api/v1/this-route-does-not-exist',+ headers={'X-Request-ID': 'x' * 129},+ )++ request_id = response.headers['X-Request-ID']+ assert request_id != 'x' * 129+ assert re.fullmatch(r'[0-9a-f]{32}', request_id)+ assert response.get_json()['request_id'] == request_id+++def test_typed_validation_error_keeps_stable_shape(client, auth_headers):+ response = client.post('/api/v1/monitors', json={}, headers={+ **auth_headers,+ 'X-Request-ID': 'monitor-create-test',+ })++ assert response.status_code == 400+ assert response.get_json() == {+ 'error': 'Monitor name is required',+ 'status': 400,+ 'code': 'validation_error',+ 'request_id': 'monitor-create-test',+ }+ assert response.headers['X-Request-ID'] == 'monitor-create-test'+++def test_typed_not_found_error_has_resource_code(client, auth_headers):+ response = client.get(+ '/api/v1/monitors/999999',+ headers=auth_headers,+ )++ payload = response.get_json()+ assert response.status_code == 404+ assert payload['error'] == 'Monitor not found'+ assert payload['status'] == 404+ assert payload['code'] == 'monitor_not_found'+ assert payload['request_id'] == response.headers['X-Request-ID']def test_non_api_404_is_not_forced_into_json(client):@@ -81,7 +138,10 @@ def test_unhandled_exception_returns_json_500_and_logs_the_path(app, caplog):assert response.is_json, (f'a crash returned {response.content_type}; API clients parse JSON')- assert response.get_json()['error']+ payload = response.get_json()+ assert payload['error']+ assert payload['code'] == 'internal_error'+ assert payload['request_id']# Matched on this handler's own wording, not merely on the path: Flask's# log_exception() already emits "Exception on /path [GET]" before any# handler runs, so asserting the path alone passes even with the handler's