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.

Let the global handler render queue-bus errors

Juan Denisd8f1d5b2d505
diff --git a/backend/app/api/queue_bus.py b/backend/app/api/queue_bus.py
index 2dccf51d..8f308623 100644
--- a/backend/app/api/queue_bus.py
+++ b/backend/app/api/queue_bus.py
@@ -3,7 +3,6 @@ from flask import Blueprint, request, jsonify
from flask_jwt_extended import jwt_required
from app.queue_bus.service import QueueBusService, QueueBusError
-from app.error_reporting import unexpected_response
from app.middleware.rbac import get_current_user
queue_bus_bp = Blueprint('queue_bus', __name__)
@@ -47,19 +46,6 @@ def _ensure_group_accessible(group_slug):
raise QueueBusError('Access denied', 403)
-def _handle_error(e):
- """Map a caught exception to a response.
-
- A QueueBusError is an expected, caller-actionable failure and keeps its own
- message and status. Anything else is a crash: report it so it reaches
- /monitoring/errors, and answer the standard body instead of handing the
- caller str(e).
- """
- if isinstance(e, QueueBusError):
- return jsonify({'error': e.message}), e.status_code
- return unexpected_response(e)
-
-
# ----------------------------------------------------------------------
# Groups
# ----------------------------------------------------------------------
@@ -67,96 +53,81 @@ def _handle_error(e):
@queue_bus_bp.route('/groups', methods=['GET'])
@jwt_required()
def list_groups():
- try:
- owner_type = request.args.get('owner_type')
- owner_id = request.args.get('owner_id')
- limit = request.args.get('limit', 100, type=int)
- offset = request.args.get('offset', 0, type=int)
- groups = QueueBusService.list_groups(
- owner_type=owner_type,
- owner_id=owner_id,
- limit=limit,
- offset=offset,
- )
- return jsonify({'groups': groups}), 200
- except Exception as e:
- return _handle_error(e)
+ owner_type = request.args.get('owner_type')
+ owner_id = request.args.get('owner_id')
+ limit = request.args.get('limit', 100, type=int)
+ offset = request.args.get('offset', 0, type=int)
+ groups = QueueBusService.list_groups(
+ owner_type=owner_type,
+ owner_id=owner_id,
+ limit=limit,
+ offset=offset,
+ )
+ return jsonify({'groups': groups}), 200
@queue_bus_bp.route('/groups', methods=['POST'])
@jwt_required()
def create_group():
- try:
- data = request.get_json() or {}
- slug = data.get('slug')
- name = data.get('name')
- description = data.get('description')
- owner_type = data.get('owner_type', 'user')
- owner_id = data.get('owner_id')
- config = data.get('config')
-
- if not slug and not name:
- return jsonify({'error': 'name or slug is required'}), 400
-
- user = get_current_user()
- if not _is_admin(user):
- # Non-admins create under their own user ownership.
- owner_type = 'user'
- owner_id = str(user.id) if user else None
-
- group = QueueBusService.create_group(
- slug=slug,
- name=name,
- description=description,
- owner_type=owner_type,
- owner_id=owner_id,
- config=config,
- )
- return jsonify({'group': group}), 201
- except Exception as e:
- return _handle_error(e)
+ data = request.get_json() or {}
+ slug = data.get('slug')
+ name = data.get('name')
+ description = data.get('description')
+ owner_type = data.get('owner_type', 'user')
+ owner_id = data.get('owner_id')
+ config = data.get('config')
+
+ if not slug and not name:
+ return jsonify({'error': 'name or slug is required'}), 400
+
+ user = get_current_user()
+ if not _is_admin(user):
+ # Non-admins create under their own user ownership.
+ owner_type = 'user'
+ owner_id = str(user.id) if user else None
+
+ group = QueueBusService.create_group(
+ slug=slug,
+ name=name,
+ description=description,
+ owner_type=owner_type,
+ owner_id=owner_id,
+ config=config,
+ )
+ return jsonify({'group': group}), 201
@queue_bus_bp.route('/groups/<group_slug>', methods=['GET'])
@jwt_required()
def get_group(group_slug):
- try:
- group = QueueBusService.get_group(group_slug)
- if not group:
- return jsonify({'error': 'Group not found'}), 404
- return jsonify({'group': group}), 200
- except Exception as e:
- return _handle_error(e)
+ group = QueueBusService.get_group(group_slug)
+ if not group:
+ return jsonify({'error': 'Group not found'}), 404
+ return jsonify({'group': group}), 200
@queue_bus_bp.route('/groups/<group_slug>', methods=['PATCH'])
@jwt_required()
def update_group(group_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- group = QueueBusService.update_group(
- slug=group_slug,
- name=data.get('name'),
- description=data.get('description'),
- config=data.get('config'),
- )
- return jsonify({'group': group}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ group = QueueBusService.update_group(
+ slug=group_slug,
+ name=data.get('name'),
+ description=data.get('description'),
+ config=data.get('config'),
+ )
+ return jsonify({'group': group}), 200
@queue_bus_bp.route('/groups/<group_slug>', methods=['DELETE'])
@jwt_required()
def delete_group(group_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- result = QueueBusService.delete_group(group_slug)
- return jsonify(result), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ result = QueueBusService.delete_group(group_slug)
+ return jsonify(result), 200
# ----------------------------------------------------------------------
@@ -166,83 +137,68 @@ def delete_group(group_slug):
@queue_bus_bp.route('/groups/<group_slug>/queues', methods=['GET'])
@jwt_required()
def list_queues(group_slug):
- try:
- limit = request.args.get('limit', 100, type=int)
- offset = request.args.get('offset', 0, type=int)
- queues = QueueBusService.list_queues(group_slug, limit=limit, offset=offset)
- return jsonify({'queues': queues}), 200
- except Exception as e:
- return _handle_error(e)
+ limit = request.args.get('limit', 100, type=int)
+ offset = request.args.get('offset', 0, type=int)
+ queues = QueueBusService.list_queues(group_slug, limit=limit, offset=offset)
+ return jsonify({'queues': queues}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues', methods=['POST'])
@jwt_required()
def create_queue(group_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- slug = data.get('slug')
- name = data.get('name')
- description = data.get('description')
- config = data.get('config')
-
- if not slug and not name:
- return jsonify({'error': 'name or slug is required'}), 400
-
- queue = QueueBusService.create_queue(
- group_slug=group_slug,
- slug=slug,
- name=name,
- description=description,
- config=config,
- )
- return jsonify({'queue': queue}), 201
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ slug = data.get('slug')
+ name = data.get('name')
+ description = data.get('description')
+ config = data.get('config')
+
+ if not slug and not name:
+ return jsonify({'error': 'name or slug is required'}), 400
+
+ queue = QueueBusService.create_queue(
+ group_slug=group_slug,
+ slug=slug,
+ name=name,
+ description=description,
+ config=config,
+ )
+ return jsonify({'queue': queue}), 201
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>', methods=['GET'])
@jwt_required()
def get_queue(group_slug, queue_slug):
- try:
- queue = QueueBusService.get_queue(group_slug, queue_slug)
- if not queue:
- return jsonify({'error': 'Queue not found'}), 404
- return jsonify({'queue': queue}), 200
- except Exception as e:
- return _handle_error(e)
+ queue = QueueBusService.get_queue(group_slug, queue_slug)
+ if not queue:
+ return jsonify({'error': 'Queue not found'}), 404
+ return jsonify({'queue': queue}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>', methods=['PATCH'])
@jwt_required()
def update_queue(group_slug, queue_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- queue = QueueBusService.update_queue(
- group_slug=group_slug,
- slug=queue_slug,
- name=data.get('name'),
- description=data.get('description'),
- config=data.get('config'),
- )
- return jsonify({'queue': queue}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ queue = QueueBusService.update_queue(
+ group_slug=group_slug,
+ slug=queue_slug,
+ name=data.get('name'),
+ description=data.get('description'),
+ config=data.get('config'),
+ )
+ return jsonify({'queue': queue}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>', methods=['DELETE'])
@jwt_required()
def delete_queue(group_slug, queue_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- result = QueueBusService.delete_queue(group_slug, queue_slug)
- return jsonify(result), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ result = QueueBusService.delete_queue(group_slug, queue_slug)
+ return jsonify(result), 200
# ----------------------------------------------------------------------
@@ -252,135 +208,111 @@ def delete_queue(group_slug, queue_slug):
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages', methods=['GET'])
@jwt_required()
def list_messages(group_slug, queue_slug):
- try:
- _ensure_group_accessible(group_slug)
- status = request.args.get('status')
- limit = request.args.get('limit', 100, type=int)
- offset = request.args.get('offset', 0, type=int)
- messages = QueueBusService.list_messages(
- group_slug=group_slug,
- queue_slug=queue_slug,
- status=status,
- limit=limit,
- offset=offset,
- )
- return jsonify({'messages': messages}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_accessible(group_slug)
+ status = request.args.get('status')
+ limit = request.args.get('limit', 100, type=int)
+ offset = request.args.get('offset', 0, type=int)
+ messages = QueueBusService.list_messages(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ status=status,
+ limit=limit,
+ offset=offset,
+ )
+ return jsonify({'messages': messages}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages', methods=['POST'])
@jwt_required()
def send_message(group_slug, queue_slug):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- payload = data.get('payload')
- priority = data.get('priority', 0)
- delay_ms = data.get('delay_ms', 0)
- max_attempts = data.get('max_attempts')
-
- if payload is None:
- return jsonify({'error': 'payload is required'}), 400
-
- message = QueueBusService.send(
- group_slug=group_slug,
- queue_slug=queue_slug,
- payload=payload,
- priority=priority,
- delay_ms=delay_ms,
- max_attempts=max_attempts,
- )
- return jsonify({'message': message}), 201
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ payload = data.get('payload')
+ priority = data.get('priority', 0)
+ delay_ms = data.get('delay_ms', 0)
+ max_attempts = data.get('max_attempts')
+
+ if payload is None:
+ return jsonify({'error': 'payload is required'}), 400
+
+ message = QueueBusService.send(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ payload=payload,
+ priority=priority,
+ delay_ms=delay_ms,
+ max_attempts=max_attempts,
+ )
+ return jsonify({'message': message}), 201
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/receive', methods=['POST'])
@jwt_required()
def receive_messages(group_slug, queue_slug):
- try:
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- visibility_timeout_ms = data.get('visibility_timeout_ms', 30000)
- max_messages = data.get('max_messages', 1)
-
- messages = QueueBusService.receive(
- group_slug=group_slug,
- queue_slug=queue_slug,
- visibility_timeout_ms=visibility_timeout_ms,
- max_messages=max_messages,
- )
- return jsonify({'messages': messages}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ visibility_timeout_ms = data.get('visibility_timeout_ms', 30000)
+ max_messages = data.get('max_messages', 1)
+
+ messages = QueueBusService.receive(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ visibility_timeout_ms=visibility_timeout_ms,
+ max_messages=max_messages,
+ )
+ return jsonify({'messages': messages}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/<message_id>', methods=['GET'])
@jwt_required()
def get_message(group_slug, queue_slug, message_id):
- try:
- _ensure_group_accessible(group_slug)
- message = QueueBusService.get_message(group_slug, queue_slug, message_id)
- if not message:
- return jsonify({'error': 'Message not found'}), 404
- return jsonify({'message': message}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_accessible(group_slug)
+ message = QueueBusService.get_message(group_slug, queue_slug, message_id)
+ if not message:
+ return jsonify({'error': 'Message not found'}), 404
+ return jsonify({'message': message}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/<message_id>/complete', methods=['POST'])
@jwt_required()
def complete_message(group_slug, queue_slug, message_id):
- try:
- _ensure_group_accessible(group_slug)
- message = QueueBusService.complete(group_slug, queue_slug, message_id)
- return jsonify({'message': message}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_accessible(group_slug)
+ message = QueueBusService.complete(group_slug, queue_slug, message_id)
+ return jsonify({'message': message}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/<message_id>/fail', methods=['POST'])
@jwt_required()
def fail_message(group_slug, queue_slug, message_id):
- try:
- _ensure_group_accessible(group_slug)
- data = request.get_json() or {}
- message = QueueBusService.fail(
- group_slug=group_slug,
- queue_slug=queue_slug,
- message_id=message_id,
- error_message=data.get('error_message'),
- requeue=data.get('requeue', False),
- )
- return jsonify({'message': message}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_accessible(group_slug)
+ data = request.get_json() or {}
+ message = QueueBusService.fail(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ message_id=message_id,
+ error_message=data.get('error_message'),
+ requeue=data.get('requeue', False),
+ )
+ return jsonify({'message': message}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/<message_id>/requeue', methods=['POST'])
@jwt_required()
def requeue_message(group_slug, queue_slug, message_id):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- message = QueueBusService.requeue(group_slug, queue_slug, message_id)
- return jsonify({'message': message}), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ message = QueueBusService.requeue(group_slug, queue_slug, message_id)
+ return jsonify({'message': message}), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/<message_id>', methods=['DELETE'])
@jwt_required()
def delete_message(group_slug, queue_slug, message_id):
- try:
- _ensure_group_mutable(group_slug)
- _ensure_group_accessible(group_slug)
- result = QueueBusService.delete_message(group_slug, queue_slug, message_id)
- return jsonify(result), 200
- except Exception as e:
- return _handle_error(e)
+ _ensure_group_mutable(group_slug)
+ _ensure_group_accessible(group_slug)
+ result = QueueBusService.delete_message(group_slug, queue_slug, message_id)
+ return jsonify(result), 200
# ----------------------------------------------------------------------
@@ -406,28 +338,19 @@ def receive_messages_shorthand(group_slug, queue_slug):
@queue_bus_bp.route('/stats', methods=['GET'])
@jwt_required()
def global_stats():
- try:
- stats = QueueBusService.get_stats()
- return jsonify(stats), 200
- except Exception as e:
- return _handle_error(e)
+ stats = QueueBusService.get_stats()
+ return jsonify(stats), 200
@queue_bus_bp.route('/groups/<group_slug>/stats', methods=['GET'])
@jwt_required()
def group_stats(group_slug):
- try:
- stats = QueueBusService.get_stats(group_slug=group_slug)
- return jsonify(stats), 200
- except Exception as e:
- return _handle_error(e)
+ stats = QueueBusService.get_stats(group_slug=group_slug)
+ return jsonify(stats), 200
@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/stats', methods=['GET'])
@jwt_required()
def queue_stats(group_slug, queue_slug):
- try:
- stats = QueueBusService.get_stats(group_slug=group_slug, queue_slug=queue_slug)
- return jsonify(stats), 200
- except Exception as e:
- return _handle_error(e)
+ stats = QueueBusService.get_stats(group_slug=group_slug, queue_slug=queue_slug)
+ return jsonify(stats), 200
diff --git a/backend/app/queue_bus/sqlalchemy_broker.py b/backend/app/queue_bus/sqlalchemy_broker.py
index fbc60e71..794f908b 100644
--- a/backend/app/queue_bus/sqlalchemy_broker.py
+++ b/backend/app/queue_bus/sqlalchemy_broker.py
@@ -4,6 +4,7 @@ from datetime import datetime, timedelta
from sqlalchemy import func
+from app.exceptions import ApplicationError
from app import db
from app.queue_bus.broker import AbstractBroker
from app.queue_bus.models import QueueGroup, Queue, QueueMessage
@@ -11,12 +12,13 @@ from app.queue_bus.models import QueueGroup, Queue, QueueMessage
logger = logging.getLogger(__name__)
-class QueueBusError(Exception):
- """Domain error for queue operations."""
+class QueueBusError(ApplicationError):
+ """Domain error for queue operations; the global handler renders it."""
+
+ code = 'queue_bus'
def __init__(self, message, status_code=400):
super().__init__(message)
- self.message = message
self.status_code = status_code
diff --git a/backend/tests/api_controller_boundary_baseline.json b/backend/tests/api_controller_boundary_baseline.json
index 4e594988..e4465ada 100644
--- a/backend/tests/api_controller_boundary_baseline.json
+++ b/backend/tests/api_controller_boundary_baseline.json
@@ -3,7 +3,7 @@
"policy": "Exact reviewed inventory of direct persistence, subprocess, and filesystem mutation calls in Flask API controllers. New calls are forbidden; remove entries as controllers delegate to services.",
"counts": {
"filesystem": 8,
- "persistence": 471
+ "persistence": 469
},
"owners": {
"api/admin.py": {
@@ -114,10 +114,6 @@
"owner": "ServerKit backend / private urls domain",
"rationale": "Legacy private urls controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."
},
- "api/projects.py": {
- "owner": "ServerKit backend / projects domain",
- "rationale": "Legacy projects controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."
- },
"api/proxy.py": {
"owner": "ServerKit backend / proxy domain",
"rationale": "Legacy proxy controllers still cross a persistence or host-operation boundary; move each call into an app.services use case before removing it."
@@ -489,7 +485,6 @@
"api/domains.py::update_domain::persistence::User.query.get(current_user_id)::1",
"api/domains.py::update_domain::persistence::db.session.commit()::1",
"api/domains.py::verify_domain::persistence::Domain.query_active().filter_by(id=domain_id).first()::1",
- "api/environments.py::_accessible_workspace_ids::persistence::Workspace.query.all()::1",
"api/environments.py::create_environment::persistence::db.session.commit()::1",
"api/files.py::upload_file::filesystem::os.makedirs(parent)::1",
"api/fleet.py::list_targets::persistence::Server.query.get(server_id)::1",
@@ -538,7 +533,6 @@
"api/private_urls.py::update_private_url::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/private_urls.py::update_private_url::persistence::User.query.get(current_user_id)::1",
"api/private_urls.py::update_private_url::persistence::db.session.commit()::1",
- "api/projects.py::_accessible_workspace_ids::persistence::Workspace.query.all()::1",
"api/proxy.py::_require_server::persistence::Server.query.get(server_id)::1",
"api/python.py::create_django_app::persistence::db.session.add(app)::1",
"api/python.py::create_django_app::persistence::db.session.commit()::1",
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
index b115c012..6dbb4d47 100644
--- a/docs/MIGRATION_INVENTORY.md
+++ b/docs/MIGRATION_INVENTORY.md
@@ -16,9 +16,9 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.
| Routes on bare @jwt_required() | auth_required() / role decorators | 600 | 600 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
| HTTP statuses chosen by sniffing error text | typed errors from app.exceptions | 0 | 0 | INVARIANT at 0 - migration completed 2026-08-19 |
| API crashes swallowed without recording | app.error_reporting | 0 | 0 | INVARIANT at 0 |
-| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 849 | 850 | migrate when touched; new endpoints raise |
+| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 848 | 850 | migrate when touched; new endpoints raise |
| Raw subprocess calls outside the runners | app/utils/system.py runners | 23 | 23 | migrate when touched |
-| Controller-boundary violations (routes doing service work) | service layer extraction | 479 | 479 | migrate when touched (first-wave ratchet) |
+| Controller-boundary violations (routes doing service work) | service layer extraction | 477 | 477 | migrate when touched (first-wave ratchet) |
| raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 396 | 398 | migrate when touched |
| per-page toast.error extractions in pages/ | E1: query-layer error presentation | 200 | 206 | migrate when touched |
| hand-rolled form-group blocks | F2: FormField/useForm | 316 | 321 | migrate when touched |