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(errors): record exceptions via service + admin API + client ingestion

Juan Denisdf126515f317
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 41d7ae52..e38c9eee 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -567,6 +567,10 @@ def create_app(config_name=None):
from app.api.recycle_bin import recycle_bin_bp
app.register_blueprint(recycle_bin_bp, url_prefix='/api/v1/recycle-bin')
+
+ # Register blueprints - Centralized error log tracking
+ from app.api.error_logs import error_logs_bp
+ app.register_blueprint(error_logs_bp, url_prefix='/api/v1/error-logs')
# Teach the bin which models it can restore. Import-time registration keeps
# the API type-agnostic: adding a soft-deletable model touches only this list.
from app.services import recycle_bin_service
@@ -880,10 +884,36 @@ def create_app(config_name=None):
@app.errorhandler(500)
def internal_error(e):
original = getattr(e, 'original_exception', None)
+ exc = original or e
app.logger.exception(
'Unhandled exception on %s %s', request.method, request.path,
- exc_info=original or e
+ exc_info=exc
)
+ # Record into the centralized error log. error_log_service never raises
+ # by contract, but belt-and-braces: a recording failure must never
+ # change this response.
+ try:
+ import traceback as _traceback
+ from flask_jwt_extended import get_jwt_identity
+ from app.services import error_log_service
+ user_id = None
+ try:
+ user_id = get_jwt_identity()
+ except Exception: # noqa: BLE001 - anonymous crashes still count
+ pass
+ error_log_service.record_error(
+ source='backend',
+ exception_type=type(exc).__name__,
+ message=str(exc),
+ traceback=''.join(
+ _traceback.format_exception(type(exc), exc, exc.__traceback__)
+ ),
+ endpoint=request.path,
+ method=request.method,
+ user_id=user_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
diff --git a/backend/app/api/error_logs.py b/backend/app/api/error_logs.py
new file mode 100644
index 00000000..65ea8e68
--- /dev/null
+++ b/backend/app/api/error_logs.py
@@ -0,0 +1,152 @@
+"""Centralized error log endpoints: admin browsing + frontend client ingestion."""
+import time
+from collections import defaultdict, deque
+
+from flask import Blueprint, jsonify, request
+from flask_jwt_extended import jwt_required, get_jwt_identity, verify_jwt_in_request
+
+from app.middleware.rbac import admin_required
+from app.services import error_log_service
+
+error_logs_bp = Blueprint('error_logs', __name__)
+
+# Simple in-memory rate limit for the client ingestion endpoint:
+# max CLIENT_RATE_LIMIT requests per CLIENT_RATE_WINDOW seconds per client IP.
+CLIENT_RATE_LIMIT = 10
+CLIENT_RATE_WINDOW = 60
+_client_hits = defaultdict(deque)
+
+
+def _client_rate_limited(ip):
+ now = time.time()
+ hits = _client_hits[ip]
+ while hits and now - hits[0] > CLIENT_RATE_WINDOW:
+ hits.popleft()
+ if len(hits) >= CLIENT_RATE_LIMIT:
+ return True
+ hits.append(now)
+ return False
+
+
+def _optional_str(data, key, max_len):
+ """Validate an optional string field; raises ValueError(key) when invalid."""
+ value = data.get(key)
+ if value is None:
+ return None
+ if not isinstance(value, str) or len(value) > max_len:
+ raise ValueError(key)
+ return value
+
+
+@error_logs_bp.route('', methods=['GET'])
+@jwt_required()
+@admin_required
+def list_error_logs():
+ """List error log entries with optional filters."""
+ resolved_arg = request.args.get('resolved')
+ 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)
+ 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,
+ )
+ return jsonify(result), 200
+
+
+@error_logs_bp.route('/stats', methods=['GET'])
+@jwt_required()
+@admin_required
+def error_log_stats():
+ """Totals for the admin overview."""
+ return jsonify(error_log_service.get_stats()), 200
+
+
+@error_logs_bp.route('/<int:error_id>', methods=['GET'])
+@jwt_required()
+@admin_required
+def get_error_log(error_id):
+ """Get a single error log entry."""
+ entry = error_log_service.get_error(error_id)
+ if not entry:
+ return jsonify({'error': 'Error log not found'}), 404
+ return jsonify(entry.to_dict()), 200
+
+
+@error_logs_bp.route('/<int:error_id>/resolve', methods=['POST'])
+@jwt_required()
+@admin_required
+def resolve_error_log(error_id):
+ """Set the resolved flag: body {"resolved": true|false}."""
+ data = request.get_json(silent=True) or {}
+ if not isinstance(data.get('resolved'), bool):
+ return jsonify({'error': 'resolved (boolean) is required'}), 400
+ entry = error_log_service.set_resolved(error_id, data['resolved'])
+ if not entry:
+ return jsonify({'error': 'Error log not found'}), 404
+ return jsonify(entry.to_dict()), 200
+
+
+@error_logs_bp.route('/<int:error_id>', methods=['DELETE'])
+@jwt_required()
+@admin_required
+def delete_error_log(error_id):
+ """Delete an error log entry."""
+ if not error_log_service.delete_error(error_id):
+ return jsonify({'error': 'Error log not found'}), 404
+ return jsonify({'success': True}), 200
+
+
+@error_logs_bp.route('/client', methods=['POST'])
+def client_error_log():
+ """Frontend error ingestion. Auth optional: a valid JWT attaches user_id."""
+ ip = request.remote_addr or 'unknown'
+ if _client_rate_limited(ip):
+ return jsonify({'error': 'Rate limit exceeded'}), 429
+
+ data = request.get_json(silent=True)
+ if not isinstance(data, dict):
+ return jsonify({'error': 'JSON body is required'}), 400
+
+ message = data.get('message')
+ if not isinstance(message, str) or not message.strip():
+ return jsonify({'error': 'message is required'}), 400
+ if len(message) > error_log_service.MAX_MESSAGE_LEN:
+ return jsonify({'error': 'message is too long'}), 400
+
+ try:
+ exception_type = _optional_str(data, 'exception_type', 200)
+ tb = _optional_str(data, 'traceback', error_log_service.MAX_TRACEBACK_LEN)
+ endpoint = _optional_str(data, 'endpoint', 255)
+ level = _optional_str(data, 'level', 20)
+ except ValueError as exc:
+ return jsonify({'error': f'invalid field: {exc}'}), 400
+
+ context = data.get('context')
+ if context is not None and not isinstance(context, dict):
+ return jsonify({'error': 'invalid field: context'}), 400
+
+ user_id = None
+ try:
+ verify_jwt_in_request(optional=True)
+ user_id = get_jwt_identity()
+ except Exception: # noqa: BLE001 - anonymous client reports are allowed
+ user_id = None
+
+ entry, deduplicated = error_log_service.record_error(
+ source='frontend',
+ message=message,
+ exception_type=exception_type,
+ traceback=tb,
+ endpoint=endpoint,
+ user_id=user_id,
+ context=context,
+ level=level or 'error',
+ )
+ if entry is None:
+ return jsonify({'error': 'Failed to record error'}), 500
+ return jsonify({'id': entry.id, 'deduplicated': deduplicated}), 201
diff --git a/backend/app/services/error_log_service.py b/backend/app/services/error_log_service.py
new file mode 100644
index 00000000..88af1370
--- /dev/null
+++ b/backend/app/services/error_log_service.py
@@ -0,0 +1,146 @@
+"""Centralized error log service: fingerprint-deduped recording + admin queries."""
+import hashlib
+import logging
+from datetime import datetime, timedelta
+
+from app import db
+from app.models.error_log import ErrorLog
+
+logger = logging.getLogger(__name__)
+
+MAX_MESSAGE_LEN = 2000
+MAX_TRACEBACK_LEN = 10000
+VALID_SOURCES = ('backend', 'frontend')
+
+
+def _fingerprint(source, exception_type, message, endpoint):
+ """sha256 hex of `source|exception_type|message[:200]|endpoint_or_url`."""
+ raw = '|'.join([
+ source or '',
+ exception_type or '',
+ (message or '')[:200],
+ endpoint or '',
+ ])
+ return hashlib.sha256(raw.encode('utf-8')).hexdigest()
+
+
+def record_error(source, message, exception_type=None, traceback=None,
+ endpoint=None, method=None, user_id=None, context=None,
+ level='error'):
+ """Record an error, deduping by fingerprint against unresolved rows.
+
+ If an unresolved row with the same fingerprint exists, its count is
+ incremented and last_seen bumped; otherwise a new row is created.
+
+ Bulletproof by contract: recording an error must never break the code path
+ that raised it, so every failure is swallowed after a session rollback.
+ Returns (entry, deduplicated), or (None, False) on failure.
+ """
+ try:
+ message = str(message or '')[:MAX_MESSAGE_LEN]
+ if traceback is not None:
+ traceback = str(traceback)[:MAX_TRACEBACK_LEN]
+ if exception_type is not None:
+ exception_type = str(exception_type)[:200]
+ if endpoint is not None:
+ endpoint = str(endpoint)[:255]
+ if method is not None:
+ method = str(method)[:10]
+ if source not in VALID_SOURCES:
+ source = 'backend'
+
+ fp = _fingerprint(source, exception_type, message, endpoint)
+ existing = ErrorLog.query.filter_by(fingerprint=fp, resolved=False).first()
+ if existing:
+ existing.count = (existing.count or 1) + 1
+ existing.last_seen = datetime.utcnow()
+ db.session.commit()
+ return existing, True
+
+ entry = ErrorLog(
+ fingerprint=fp,
+ source=source,
+ level=level or 'error',
+ exception_type=exception_type,
+ message=message,
+ traceback=traceback,
+ endpoint=endpoint,
+ method=method,
+ user_id=user_id,
+ )
+ entry.set_context(context)
+ db.session.add(entry)
+ db.session.commit()
+ return entry, False
+ except Exception: # noqa: BLE001 - must never raise into the failing request
+ try:
+ db.session.rollback()
+ except Exception: # noqa: BLE001
+ pass
+ logger.exception('Failed to record error log entry')
+ return None, False
+
+
+def list_errors(source=None, resolved=None, search=None, page=1, per_page=25):
+ """Paginated admin listing with optional source/resolved/search filters."""
+ query = ErrorLog.query
+ if source:
+ query = query.filter_by(source=source)
+ if resolved is not None:
+ query = query.filter_by(resolved=resolved)
+ if search:
+ like = f'%{search}%'
+ query = query.filter(db.or_(
+ ErrorLog.message.ilike(like),
+ ErrorLog.exception_type.ilike(like),
+ ErrorLog.endpoint.ilike(like),
+ ))
+ query = query.order_by(ErrorLog.last_seen.desc())
+ pagination = query.paginate(page=page, per_page=per_page, error_out=False)
+ return {
+ 'items': [entry.to_dict() for entry in pagination.items],
+ 'total': pagination.total,
+ 'page': pagination.page,
+ 'pages': pagination.pages,
+ }
+
+
+def get_error(error_id):
+ """Return one error log entry, or None."""
+ return ErrorLog.query.get(error_id)
+
+
+def set_resolved(error_id, resolved):
+ """Set the resolved flag. Returns the entry, or None when not found."""
+ entry = ErrorLog.query.get(error_id)
+ if not entry:
+ return None
+ entry.resolved = bool(resolved)
+ db.session.commit()
+ return entry
+
+
+def delete_error(error_id):
+ """Delete an entry. Returns True when a row was deleted."""
+ entry = ErrorLog.query.get(error_id)
+ if not entry:
+ return False
+ db.session.delete(entry)
+ db.session.commit()
+ return True
+
+
+def get_stats():
+ """Totals for the admin overview: total, unresolved, last 24h, by source."""
+ since = datetime.utcnow() - timedelta(hours=24)
+ by_source = dict(
+ db.session.query(ErrorLog.source, db.func.count())
+ .group_by(ErrorLog.source)
+ .all()
+ )
+ return {
+ 'total': ErrorLog.query.count(),
+ 'unresolved': ErrorLog.query.filter_by(resolved=False).count(),
+ 'last_24h': ErrorLog.query.filter(ErrorLog.last_seen >= since).count(),
+ 'by_source': by_source,
+ }
diff --git a/backend/tests/test_error_logs.py b/backend/tests/test_error_logs.py
new file mode 100644
index 00000000..810f59dc
--- /dev/null
+++ b/backend/tests/test_error_logs.py
@@ -0,0 +1,195 @@
+"""Tests for the centralized error log: service dedup, admin API, client
+ingestion, and the 500-handler recording hook."""
+import pytest
+
+from app import db
+from app.models.error_log import ErrorLog
+from app.services import error_log_service
+
+
+def _record(message='boom', **kwargs):
+ kwargs.setdefault('source', 'backend')
+ return error_log_service.record_error(message=message, **kwargs)
+
+
+# --------------------------------------------------------------------------- #
+# Service: recording + dedup
+# --------------------------------------------------------------------------- #
+
+def test_record_creates_entry(app):
+ entry, deduplicated = _record(
+ message='something broke', exception_type='RuntimeError',
+ endpoint='/api/v1/apps', method='GET', context={'k': 'v'})
+ assert not deduplicated
+ assert entry.id is not None
+ assert entry.count == 1
+ assert entry.fingerprint
+ assert entry.get_context() == {'k': 'v'}
+ assert entry.resolved is False
+
+
+def test_dedup_increments_count(app):
+ first, _ = _record(message='same crash', exception_type='ValueError')
+ second, deduplicated = _record(message='same crash', exception_type='ValueError')
+ assert deduplicated
+ assert second.id == first.id
+ assert second.count == 2
+ assert ErrorLog.query.count() == 1
+
+
+def test_resolved_error_dedups_no_more(app):
+ first, _ = _record(message='fixed crash')
+ error_log_service.set_resolved(first.id, True)
+ second, deduplicated = _record(message='fixed crash')
+ assert not deduplicated
+ assert second.id != first.id
+ assert ErrorLog.query.count() == 2
+
+
+def test_record_error_never_raises(app, monkeypatch):
+ # Broken query object -> failure is swallowed, session rolled back.
+ monkeypatch.setattr(error_log_service.ErrorLog, 'query', None)
+ entry, deduplicated = _record(message='still safe')
+ assert entry is None and deduplicated is False
+ assert db.session # session usable after rollback
+
+
+# --------------------------------------------------------------------------- #
+# Admin API
+# --------------------------------------------------------------------------- #
+
+def test_list_filters(client, auth_headers):
+ _record(message='backend crash A', endpoint='/api/v1/x')
+ _record(message='frontend crash B', source='frontend')
+ entry, _ = _record(message='backend crash C resolved')
+ error_log_service.set_resolved(entry.id, True)
+
+ res = client.get('/api/v1/error-logs?source=frontend', headers=auth_headers)
+ assert res.status_code == 200
+ data = res.get_json()
+ assert data['total'] == 1
+ assert data['items'][0]['message'] == 'frontend crash B'
+
+ res = client.get('/api/v1/error-logs?resolved=true', headers=auth_headers)
+ assert res.get_json()['total'] == 1
+
+ res = client.get('/api/v1/error-logs?search=crash+A', headers=auth_headers)
+ assert res.get_json()['total'] == 1
+
+
+def test_list_requires_admin(client, app):
+ from app.models import User
+ from flask_jwt_extended import create_access_token
+ from werkzeug.security import generate_password_hash
+ with app.app_context():
+ user = User(email='[email protected]', username='dev',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_DEVELOPER, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ headers = {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}
+ assert client.get('/api/v1/error-logs', headers=headers).status_code == 403
+
+
+def test_resolve_and_unresolve(client, auth_headers):
+ entry, _ = _record(message='to resolve')
+ res = client.post(f'/api/v1/error-logs/{entry.id}/resolve',
+ json={'resolved': True}, headers=auth_headers)
+ assert res.status_code == 200
+ assert res.get_json()['resolved'] is True
+
+ res = client.post(f'/api/v1/error-logs/{entry.id}/resolve',
+ json={'resolved': False}, headers=auth_headers)
+ assert res.get_json()['resolved'] is False
+
+ assert client.post('/api/v1/error-logs/9999/resolve', json={'resolved': True},
+ headers=auth_headers).status_code == 404
+ assert client.post(f'/api/v1/error-logs/{entry.id}/resolve', json={},
+ headers=auth_headers).status_code == 400
+
+
+def test_delete(client, auth_headers):
+ entry, _ = _record(message='to delete')
+ assert client.delete(f'/api/v1/error-logs/{entry.id}',
+ headers=auth_headers).status_code == 200
+ assert ErrorLog.query.count() == 0
+ assert client.delete(f'/api/v1/error-logs/{entry.id}',
+ headers=auth_headers).status_code == 404
+
+
+def test_stats(client, auth_headers):
+ _record(message='s1')
+ _record(message='s2', source='frontend')
+ entry, _ = _record(message='s3')
+ error_log_service.set_resolved(entry.id, True)
+
+ res = client.get('/api/v1/error-logs/stats', headers=auth_headers)
+ assert res.status_code == 200
+ stats = res.get_json()
+ assert stats['total'] == 3
+ assert stats['unresolved'] == 2
+ assert stats['last_24h'] == 3
+ assert stats['by_source'] == {'backend': 2, 'frontend': 1}
+
+
+# --------------------------------------------------------------------------- #
+# Client ingestion endpoint
+# --------------------------------------------------------------------------- #
+
+def test_client_endpoint_requires_message(client):
+ res = client.post('/api/v1/error-logs/client', json={})
+ assert res.status_code == 400
+ res = client.post('/api/v1/error-logs/client', json={'message': 42})
+ assert res.status_code == 400
+
+
+def test_client_endpoint_records_frontend_error(client):
+ res = client.post('/api/v1/error-logs/client', json={
+ 'message': 'TypeError: x is not a function',
+ 'exception_type': 'TypeError',
+ 'endpoint': '/apps/123',
+ 'context': {'component': 'AppList'},
+ })
+ assert res.status_code == 201
+ body = res.get_json()
+ assert body['deduplicated'] is False
+
+ entry = ErrorLog.query.get(body['id'])
+ assert entry.source == 'frontend'
+ assert entry.endpoint == '/apps/123'
+
+ # Same error again dedups.
+ res = client.post('/api/v1/error-logs/client', json={
+ 'message': 'TypeError: x is not a function',
+ 'exception_type': 'TypeError',
+ 'endpoint': '/apps/123',
+ })
+ assert res.get_json()['deduplicated'] is True
+ assert entry.count == 2
+
+
+# --------------------------------------------------------------------------- #
+# 500-handler hook
+# --------------------------------------------------------------------------- #
+
+def test_500_handler_records_error_and_keeps_response(client, app):
+ @app.route('/api/v1/__test_boom')
+ def _boom():
+ raise RuntimeError('kaboom')
+
+ # Flask only routes to the 500 handler when not propagating exceptions.
+ app.config['TESTING'] = False
+ app.config['PROPAGATE_EXCEPTIONS'] = False
+
+ res = client.get('/api/v1/__test_boom')
+ assert res.status_code == 500
+ assert res.get_json() == {'error': 'Internal server error'}
+
+ entry = ErrorLog.query.filter_by(source='backend').first()
+ assert entry is not None
+ assert entry.exception_type == 'RuntimeError'
+ assert 'kaboom' in entry.message
+ assert 'RuntimeError' in entry.traceback
+ assert entry.endpoint == '/api/v1/__test_boom'
+ assert entry.method == 'GET'