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.

feat(api): centralize typed errors and request correlation

Juan Denisd018a5e979fb
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 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 middleware
from app.middleware.security import register_security_headers
register_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: BLE001
pass
# 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 request
if 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 404
index = os.path.join(app.static_folder, 'index.html') if app.static_folder else None
if index and os.path.isfile(index):
diff --git a/backend/app/api/monitors.py b/backend/app/api/monitors.py
index 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, jsonify
from flask_jwt_extended import jwt_required
+from app.exceptions import NotFoundError
from app.services.monitor_service import MonitorService
monitors_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 response
diff --git a/backend/app/services/monitor_service.py b/backend/app/services/monitor_service.py
index 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, timedelta
from urllib.parse import urlparse
from app import db
+from app.exceptions import ValidationError
from app.models.status_page import (
StatusComponent, HealthCheck, StatusIncident, StatusIncidentUpdate,
)
@@ -124,23 +125,23 @@ class MonitorService:
return
from app.models.wordpress_site import WordPressSite
if 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?)')
@staticmethod
def 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 None
if '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.py
index 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 re
def 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 == 404
assert 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'] == 405
assert 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