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(queue-bus): introduce ServerKit Queue Bus under Operations

Juan Denis9b4618b24b73
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index b4fad5ce..0c10b0c9 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -350,6 +350,10 @@ def create_app(config_name=None):
from app.api.plugins import plugins_bp
app.register_blueprint(plugins_bp, url_prefix='/api/v1/plugins')
+ # Register blueprints - Queue Bus
+ from app.api.queue_bus import queue_bus_bp
+ app.register_blueprint(queue_bus_bp, url_prefix='/api/v1/queue')
+
# Register blueprints - Agent Pairing (RustDesk-style short-code flow)
from app.api.pairing import pairing_bp
app.register_blueprint(pairing_bp, url_prefix='/api/v1/pairing')
@@ -403,6 +407,10 @@ def create_app(config_name=None):
if not MetricsHistoryService.is_running():
MetricsHistoryService.start_collection(app)
+ # Start queue-bus webhook consumer
+ from app.queue_bus.consumers import start_webhook_consumer
+ start_webhook_consumer(app)
+
# Start auto-sync scheduler for WordPress environments
_start_auto_sync_scheduler(app)
diff --git a/backend/app/api/queue_bus.py b/backend/app/api/queue_bus.py
new file mode 100644
index 00000000..27868dee
--- /dev/null
+++ b/backend/app/api/queue_bus.py
@@ -0,0 +1,380 @@
+"""REST API for the ServerKit Queue Bus."""
+from flask import Blueprint, request, jsonify
+from flask_jwt_extended import jwt_required, get_jwt_identity
+
+from app.queue_bus.service import QueueBusService, QueueBusError
+from app.models.user import User
+
+queue_bus_bp = Blueprint('queue_bus', __name__)
+
+
+def _current_user():
+ uid = get_jwt_identity()
+ if uid is None:
+ return None
+ try:
+ return User.query.get(int(uid))
+ except (TypeError, ValueError):
+ return None
+
+
+def _is_admin(user):
+ return user is not None and getattr(user, 'role', None) == 'admin'
+
+
+def _handle_error(e):
+ if isinstance(e, QueueBusError):
+ return jsonify({'error': e.message}), e.status_code
+ return jsonify({'error': str(e)}), 500
+
+
+# ----------------------------------------------------------------------
+# Groups
+# ----------------------------------------------------------------------
+
+@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)
+
+
+@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:
+ return jsonify({'error': 'slug is required'}), 400
+
+ user = _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)
+
+
+@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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>', methods=['PATCH'])
+@jwt_required()
+def update_group(group_slug):
+ try:
+ 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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>', methods=['DELETE'])
+@jwt_required()
+def delete_group(group_slug):
+ try:
+ result = QueueBusService.delete_group(group_slug)
+ return jsonify(result), 200
+ except Exception as e:
+ return _handle_error(e)
+
+
+# ----------------------------------------------------------------------
+# Queues
+# ----------------------------------------------------------------------
+
+@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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>/queues', methods=['POST'])
+@jwt_required()
+def create_queue(group_slug):
+ try:
+ data = request.get_json() or {}
+ slug = data.get('slug')
+ name = data.get('name')
+ description = data.get('description')
+ config = data.get('config')
+
+ if not slug:
+ return jsonify({'error': '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)
+
+
+@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_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>', methods=['PATCH'])
+@jwt_required()
+def update_queue(group_slug, queue_slug):
+ try:
+ 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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>', methods=['DELETE'])
+@jwt_required()
+def delete_queue(group_slug, queue_slug):
+ try:
+ result = QueueBusService.delete_queue(group_slug, queue_slug)
+ return jsonify(result), 200
+ except Exception as e:
+ return _handle_error(e)
+
+
+# ----------------------------------------------------------------------
+# Messages
+# ----------------------------------------------------------------------
+
+@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages', methods=['GET'])
+@jwt_required()
+def list_messages(group_slug, queue_slug):
+ try:
+ 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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages', methods=['POST'])
+@jwt_required()
+def send_message(group_slug, queue_slug):
+ try:
+ 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)
+
+
+@queue_bus_bp.route('/groups/<group_slug>/queues/<queue_slug>/messages/receive', methods=['POST'])
+@jwt_required()
+def receive_messages(group_slug, queue_slug):
+ try:
+ 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)
+
+
+@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:
+ 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)
+
+
+@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:
+ message = QueueBusService.complete(group_slug, queue_slug, message_id)
+ return jsonify({'message': message}), 200
+ except Exception as e:
+ return _handle_error(e)
+
+
+@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:
+ 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)
+
+
+@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:
+ message = QueueBusService.requeue(group_slug, queue_slug, message_id)
+ return jsonify({'message': message}), 200
+ except Exception as e:
+ return _handle_error(e)
+
+
+@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:
+ result = QueueBusService.delete_message(group_slug, queue_slug, message_id)
+ return jsonify(result), 200
+ except Exception as e:
+ return _handle_error(e)
+
+
+# ----------------------------------------------------------------------
+# Shorthand routes
+# ----------------------------------------------------------------------
+
+@queue_bus_bp.route('/<group_slug>/<queue_slug>/messages', methods=['POST'])
+@jwt_required()
+def send_message_shorthand(group_slug, queue_slug):
+ return send_message(group_slug, queue_slug)
+
+
+@queue_bus_bp.route('/<group_slug>/<queue_slug>/messages/receive', methods=['POST'])
+@jwt_required()
+def receive_messages_shorthand(group_slug, queue_slug):
+ return receive_messages(group_slug, queue_slug)
+
+
+# ----------------------------------------------------------------------
+# Stats
+# ----------------------------------------------------------------------
+
+@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)
+
+
+@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)
+
+
+@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)
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index e1bb6893..e50fb1db 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -42,6 +42,7 @@ from app.models.passkey import PasskeyCredential
from app.models.secret_vault import SecretVault, Secret
from app.models.webhook_gateway import WebhookEndpoint, WebhookDelivery
from app.models.waf_policy import WafPolicy
+from app.queue_bus.models import QueueGroup, Queue, QueueMessage
__all__ = [
'User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',
@@ -70,4 +71,5 @@ __all__ = [
'SecretVault', 'Secret',
'WebhookEndpoint', 'WebhookDelivery',
'WafPolicy',
+ 'QueueGroup', 'Queue', 'QueueMessage',
]
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.py
index f7d39ef0..3ea1c41e 100644
--- a/backend/app/plugins_sdk/__init__.py
+++ b/backend/app/plugins_sdk/__init__.py
@@ -88,6 +88,9 @@ def audit(action, target_type, target_id=None, details=None, user_id=None):
# tools/context against the core assistant (see plugins_sdk/ai.py). Imported
# lazily-safe: ai.py only depends on the AI tool registry, not on a running app.
from app.plugins_sdk import ai
+from app.queue_bus.sdk import QueueBusSdk
+
+queue = QueueBusSdk()
__all__ = [
'db',
@@ -99,4 +102,5 @@ __all__ = [
'logger',
'audit',
'ai',
+ 'queue',
]
diff --git a/backend/app/queue_bus/__init__.py b/backend/app/queue_bus/__init__.py
new file mode 100644
index 00000000..3f76be9d
--- /dev/null
+++ b/backend/app/queue_bus/__init__.py
@@ -0,0 +1,16 @@
+"""ServerKit Queue Bus.
+
+A pluggable message queue bus for core services and extensions.
+"""
+
+from app.queue_bus.models import QueueGroup, Queue, QueueMessage
+from app.queue_bus.service import QueueBusService
+from app.queue_bus.sdk import QueueBusSdk
+
+__all__ = [
+ 'QueueGroup',
+ 'Queue',
+ 'QueueMessage',
+ 'QueueBusService',
+ 'QueueBusSdk',
+]
diff --git a/backend/app/queue_bus/broker.py b/backend/app/queue_bus/broker.py
new file mode 100644
index 00000000..0a8ac9fd
--- /dev/null
+++ b/backend/app/queue_bus/broker.py
@@ -0,0 +1,86 @@
+"""Abstract broker interface for the ServerKit Queue Bus."""
+from abc import ABC, abstractmethod
+
+
+class AbstractBroker(ABC):
+ """Pluggable backend for the queue bus.
+
+ Implementations must be stateless with respect to in-memory state so that
+ multiple worker processes can share the same logical queue.
+ """
+
+ @abstractmethod
+ def create_group(self, slug, name, description=None, owner_type='system', owner_id=None, config=None):
+ """Create a QueueGroup. Return a dict or raise QueueBusError."""
+
+ @abstractmethod
+ def update_group(self, slug, name=None, description=None, config=None):
+ """Update a QueueGroup."""
+
+ @abstractmethod
+ def delete_group(self, slug):
+ """Delete a QueueGroup and all its queues/messages."""
+
+ @abstractmethod
+ def get_group(self, slug):
+ """Return a QueueGroup dict or None."""
+
+ @abstractmethod
+ def list_groups(self, owner_type=None, owner_id=None, limit=100, offset=0):
+ """Return a list of QueueGroup dicts."""
+
+ @abstractmethod
+ def create_queue(self, group_slug, slug, name, description=None, config=None):
+ """Create a Queue inside a group."""
+
+ @abstractmethod
+ def update_queue(self, group_slug, slug, name=None, description=None, config=None):
+ """Update a Queue."""
+
+ @abstractmethod
+ def delete_queue(self, group_slug, queue_slug):
+ """Delete a Queue and all its messages."""
+
+ @abstractmethod
+ def get_queue(self, group_slug, queue_slug):
+ """Return a Queue dict or None."""
+
+ @abstractmethod
+ def list_queues(self, group_slug, limit=100, offset=0):
+ """Return a list of Queue dicts."""
+
+ @abstractmethod
+ def send(self, group_slug, queue_slug, payload, priority=0, delay_ms=0, max_attempts=None):
+ """Send a message to a queue. Return message id."""
+
+ @abstractmethod
+ def receive(self, group_slug, queue_slug, visibility_timeout_ms=30000, max_messages=1):
+ """Receive up to max_messages pending messages. Return list of message dicts."""
+
+ @abstractmethod
+ def complete(self, group_slug, queue_slug, message_id):
+ """Mark a message as completed."""
+
+ @abstractmethod
+ def fail(self, group_slug, queue_slug, message_id, error_message=None, requeue=False):
+ """Mark a message failed. If requeue is False, retry or dead-letter based on attempts."""
+
+ @abstractmethod
+ def requeue(self, group_slug, queue_slug, message_id):
+ """Move a failed/dead-letter message back to pending."""
+
+ @abstractmethod
+ def delete_message(self, group_slug, queue_slug, message_id):
+ """Permanently delete a message."""
+
+ @abstractmethod
+ def get_message(self, group_slug, queue_slug, message_id):
+ """Return a message dict or None."""
+
+ @abstractmethod
+ def list_messages(self, group_slug, queue_slug, status=None, limit=100, offset=0):
+ """Return a list of message dicts."""
+
+ @abstractmethod
+ def get_stats(self, group_slug=None, queue_slug=None):
+ """Return aggregated stats."""
diff --git a/backend/app/queue_bus/consumers/__init__.py b/backend/app/queue_bus/consumers/__init__.py
new file mode 100644
index 00000000..431316f8
--- /dev/null
+++ b/backend/app/queue_bus/consumers/__init__.py
@@ -0,0 +1,14 @@
+"""Internal consumers for the ServerKit Queue Bus."""
+from app.queue_bus.consumers.webhook_consumer import (
+ WebhookConsumer,
+ start_webhook_consumer,
+ stop_webhook_consumer,
+ enqueue_webhook_delivery,
+)
+
+__all__ = [
+ 'WebhookConsumer',
+ 'start_webhook_consumer',
+ 'stop_webhook_consumer',
+ 'enqueue_webhook_delivery',
+]
diff --git a/backend/app/queue_bus/consumers/webhook_consumer.py b/backend/app/queue_bus/consumers/webhook_consumer.py
new file mode 100644
index 00000000..2fc7360c
--- /dev/null
+++ b/backend/app/queue_bus/consumers/webhook_consumer.py
@@ -0,0 +1,198 @@
+"""Internal consumer that delivers webhooks via the Queue Bus."""
+import hashlib
+import hmac
+import json
+import logging
+import threading
+import time
+import uuid
+from datetime import datetime
+
+import requests as http_requests
+
+from app import db
+from app.queue_bus.service import QueueBusService
+from app.models.event_subscription import EventSubscription, EventDelivery
+
+logger = logging.getLogger(__name__)
+
+GROUP_SLUG = 'serverkit-system'
+QUEUE_SLUG = 'webhook-deliveries'
+
+_webhook_consumer_thread = None
+
+
+class WebhookConsumer:
+ """Polls the queue bus for webhook delivery messages and executes them."""
+
+ def __init__(self, app=None):
+ self.app = app
+ self.running = False
+ self.poll_interval_seconds = 1
+
+ def start(self):
+ if self.running:
+ return
+ self.running = True
+ self._ensure_queue()
+ thread = threading.Thread(target=self._run, daemon=True, name='queue-bus-webhook-consumer')
+ thread.start()
+ logger.info('Webhook queue consumer started')
+
+ def stop(self):
+ self.running = False
+
+ def _ensure_queue(self):
+ with self.app.app_context():
+ QueueBusService.ensure_queue(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ config={'max_attempts': 3, 'visibility_timeout_ms': 60000},
+ )
+
+ def _run(self):
+ while self.running:
+ try:
+ with self.app.app_context():
+ self._process_batch()
+ except Exception as e:
+ logger.error(f'Webhook consumer error: {e}')
+ time.sleep(self.poll_interval_seconds)
+
+ def _process_batch(self):
+ messages = QueueBusService.receive(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ visibility_timeout_ms=60000,
+ max_messages=10,
+ )
+ for message in messages:
+ try:
+ self._deliver(message)
+ except Exception as e:
+ logger.error(f'Webhook delivery failed for message {message["id"]}: {e}')
+ try:
+ QueueBusService.fail(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ message['id'],
+ error_message=str(e)[:500],
+ )
+ except Exception as inner:
+ logger.error(f'Failed to mark webhook message failed: {inner}')
+
+ def _deliver(self, message):
+ payload = message.get('payload', {})
+ delivery_id = payload.get('delivery_id')
+ if not delivery_id:
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ delivery = EventDelivery.query.get(delivery_id)
+ if not delivery:
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ subscription = delivery.subscription
+ if not subscription or not subscription.is_active:
+ delivery.status = EventDelivery.STATUS_FAILED
+ db.session.commit()
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ return
+
+ event_payload = delivery.get_payload()
+ payload_json = json.dumps(event_payload)
+ delivery_uuid = str(uuid.uuid4())
+
+ headers = {
+ 'Content-Type': 'application/json',
+ 'X-ServerKit-Event': delivery.event_type,
+ 'X-ServerKit-Delivery': delivery_uuid,
+ 'User-Agent': 'ServerKit-Webhooks/1.0',
+ }
+
+ if subscription.secret:
+ signature = hmac.new(
+ subscription.secret.encode(),
+ payload_json.encode(),
+ hashlib.sha256,
+ ).hexdigest()
+ headers['X-ServerKit-Signature'] = f'sha256={signature}'
+
+ custom_headers = subscription.get_headers()
+ if custom_headers:
+ headers.update(custom_headers)
+
+ delivery.attempts = (delivery.attempts or 0) + 1
+ start_time = time.time()
+
+ try:
+ resp = http_requests.post(
+ subscription.url,
+ data=payload_json,
+ headers=headers,
+ timeout=subscription.timeout_seconds or 10,
+ )
+ elapsed_ms = (time.time() - start_time) * 1000
+ delivery.http_status = resp.status_code
+ delivery.response_body = resp.text[:1000] if resp.text else None
+ delivery.duration_ms = round(elapsed_ms, 2)
+
+ if 200 <= resp.status_code < 300:
+ delivery.status = EventDelivery.STATUS_SUCCESS
+ delivery.delivered_at = datetime.utcnow()
+ db.session.commit()
+ QueueBusService.complete(GROUP_SLUG, QUEUE_SLUG, message['id'])
+ else:
+ db.session.commit()
+ QueueBusService.fail(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ message['id'],
+ error_message=f'HTTP {resp.status_code}',
+ )
+
+ except Exception as e:
+ elapsed_ms = (time.time() - start_time) * 1000
+ delivery.duration_ms = round(elapsed_ms, 2)
+ delivery.response_body = str(e)[:1000]
+ db.session.commit()
+ QueueBusService.fail(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ message['id'],
+ error_message=str(e)[:500],
+ )
+
+
+def start_webhook_consumer(app):
+ """Start the singleton webhook consumer thread.
+
+ Skipped in testing mode to avoid background noise and race conditions
+ against per-test databases.
+ """
+ global _webhook_consumer_thread
+ if _webhook_consumer_thread is not None:
+ return
+ if app.config.get('ENV') == 'testing' or app.config.get('TESTING'):
+ return
+ consumer = WebhookConsumer(app)
+ consumer.start()
+ _webhook_consumer_thread = consumer
+
+
+def stop_webhook_consumer():
+ global _webhook_consumer_thread
+ if _webhook_consumer_thread is not None:
+ _webhook_consumer_thread.stop()
+ _webhook_consumer_thread = None
+
+
+def enqueue_webhook_delivery(delivery_id):
+ """Enqueue a webhook delivery message on the queue bus."""
+ QueueBusService.ensure_queue(GROUP_SLUG, QUEUE_SLUG)
+ return QueueBusService.send(
+ GROUP_SLUG,
+ QUEUE_SLUG,
+ {'delivery_id': delivery_id},
+ )
diff --git a/backend/app/queue_bus/models.py b/backend/app/queue_bus/models.py
new file mode 100644
index 00000000..9c48f4f5
--- /dev/null
+++ b/backend/app/queue_bus/models.py
@@ -0,0 +1,186 @@
+"""ORM models for the ServerKit Queue Bus."""
+import json
+import uuid
+from datetime import datetime
+
+from app import db
+
+
+class QueueGroup(db.Model):
+ """A namespace for related queues."""
+
+ __tablename__ = 'queue_groups'
+
+ id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+ slug = db.Column(db.String(128), nullable=False, unique=True, index=True)
+ name = db.Column(db.String(256), nullable=False)
+ description = db.Column(db.Text)
+ owner_type = db.Column(db.String(32), default='system', nullable=False)
+ owner_id = db.Column(db.String(128), nullable=True)
+ config_json = db.Column(db.Text)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+ queues = db.relationship('Queue', back_populates='group', lazy='dynamic', cascade='all, delete-orphan')
+
+ def get_config(self):
+ if self.config_json:
+ try:
+ return json.loads(self.config_json)
+ except (TypeError, json.JSONDecodeError):
+ return {}
+ return {}
+
+ def set_config(self, value):
+ self.config_json = json.dumps(value) if value is not None else None
+
+ def to_dict(self, include_stats=False):
+ data = {
+ 'id': self.id,
+ 'slug': self.slug,
+ 'name': self.name,
+ 'description': self.description,
+ 'owner_type': self.owner_type,
+ 'owner_id': self.owner_id,
+ 'config': self.get_config(),
+ '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_stats:
+ data['stats'] = {
+ 'queues': self.queues.count(),
+ }
+ return data
+
+
+class Queue(db.Model):
+ """A named message pipe inside a QueueGroup."""
+
+ __tablename__ = 'queues'
+
+ id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+ group_id = db.Column(db.String(36), db.ForeignKey('queue_groups.id'), nullable=False, index=True)
+ slug = db.Column(db.String(128), nullable=False, index=True)
+ name = db.Column(db.String(256), nullable=False)
+ description = db.Column(db.Text)
+ config_json = db.Column(db.Text)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+ group = db.relationship('QueueGroup', back_populates='queues')
+ messages = db.relationship('QueueMessage', back_populates='queue', lazy='dynamic', cascade='all, delete-orphan')
+
+ __table_args__ = (
+ db.UniqueConstraint('group_id', 'slug', name='uix_queue_group_slug'),
+ )
+
+ def get_config(self):
+ if self.config_json:
+ try:
+ return json.loads(self.config_json)
+ except (TypeError, json.JSONDecodeError):
+ return {}
+ return {}
+
+ def set_config(self, value):
+ self.config_json = json.dumps(value) if value is not None else None
+
+ def to_dict(self, include_stats=False):
+ data = {
+ 'id': self.id,
+ 'group_id': self.group_id,
+ 'group_slug': self.group.slug if self.group else None,
+ 'slug': self.slug,
+ 'name': self.name,
+ 'description': self.description,
+ 'config': self.get_config(),
+ '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_stats:
+ from sqlalchemy import func
+ data['stats'] = {
+ 'pending': self.messages.filter(QueueMessage.status == QueueMessage.STATUS_PENDING).count(),
+ 'in_flight': self.messages.filter(QueueMessage.status == QueueMessage.STATUS_IN_FLIGHT).count(),
+ 'completed': self.messages.filter(QueueMessage.status == QueueMessage.STATUS_COMPLETED).count(),
+ 'failed': self.messages.filter(QueueMessage.status == QueueMessage.STATUS_FAILED).count(),
+ 'dead_letter': self.messages.filter(QueueMessage.status == QueueMessage.STATUS_DEAD_LETTER).count(),
+ 'total': self.messages.count(),
+ }
+ return data
+
+
+class QueueMessage(db.Model):
+ """A single message in a Queue."""
+
+ __tablename__ = 'queue_messages'
+
+ STATUS_PENDING = 'pending'
+ STATUS_IN_FLIGHT = 'in_flight'
+ STATUS_COMPLETED = 'completed'
+ STATUS_FAILED = 'failed'
+ STATUS_DEAD_LETTER = 'dead_letter'
+
+ id = db.Column(db.String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+ queue_id = db.Column(db.String(36), db.ForeignKey('queues.id'), nullable=False, index=True)
+ group_id = db.Column(db.String(36), db.ForeignKey('queue_groups.id'), nullable=False, index=True)
+ status = db.Column(db.String(32), default=STATUS_PENDING, nullable=False, index=True)
+ priority = db.Column(db.Integer, default=0, nullable=False, index=True)
+ payload_json = db.Column(db.Text, nullable=False)
+ result_json = db.Column(db.Text)
+ error_message = db.Column(db.Text)
+ attempts = db.Column(db.Integer, default=0, nullable=False)
+ max_attempts = db.Column(db.Integer, default=3, nullable=False)
+ visible_after = db.Column(db.DateTime, default=datetime.utcnow, nullable=False, index=True)
+ invisible_until = db.Column(db.DateTime, nullable=True, index=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False, index=True)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+ completed_at = db.Column(db.DateTime, nullable=True)
+
+ queue = db.relationship('Queue', back_populates='messages')
+ group = db.relationship('QueueGroup')
+
+ def get_payload(self):
+ if self.payload_json:
+ try:
+ return json.loads(self.payload_json)
+ except (TypeError, json.JSONDecodeError):
+ return {}
+ return {}
+
+ def set_payload(self, value):
+ self.payload_json = json.dumps(value) if value is not None else '{}'
+
+ def get_result(self):
+ if self.result_json:
+ try:
+ return json.loads(self.result_json)
+ except (TypeError, json.JSONDecodeError):
+ return {}
+ return {}
+
+ def set_result(self, value):
+ self.result_json = json.dumps(value) if value is not None else None
+
+ def to_dict(self, include_payload=True):
+ data = {
+ 'id': self.id,
+ 'queue_id': self.queue_id,
+ 'group_id': self.group_id,
+ 'group_slug': self.group.slug if self.group else None,
+ 'queue_slug': self.queue.slug if self.queue else None,
+ 'status': self.status,
+ 'priority': self.priority,
+ 'attempts': self.attempts,
+ 'max_attempts': self.max_attempts,
+ 'error_message': self.error_message,
+ 'visible_after': self.visible_after.isoformat() if self.visible_after else None,
+ 'invisible_until': self.invisible_until.isoformat() if self.invisible_until else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ 'completed_at': self.completed_at.isoformat() if self.completed_at else None,
+ }
+ if include_payload:
+ data['payload'] = self.get_payload()
+ data['result'] = self.get_result()
+ return data
diff --git a/backend/app/queue_bus/sdk.py b/backend/app/queue_bus/sdk.py
new file mode 100644
index 00000000..907d9f41
--- /dev/null
+++ b/backend/app/queue_bus/sdk.py
@@ -0,0 +1,84 @@
+"""Plugin SDK for the ServerKit Queue Bus."""
+from app.queue_bus.service import QueueBusService
+
+
+class ReceivedMessage:
+ """Handle returned by QueueBusSdk.receive() so callers can complete/fail."""
+
+ def __init__(self, group_slug, queue_slug, message_dict):
+ self.group_slug = group_slug
+ self.queue_slug = queue_slug
+ self.message_id = message_dict['id']
+ self.payload = message_dict.get('payload')
+ self._raw = message_dict
+
+ def complete(self):
+ return QueueBusService.complete(self.group_slug, self.queue_slug, self.message_id)
+
+ def fail(self, error_message=None, requeue=False):
+ return QueueBusService.fail(
+ self.group_slug,
+ self.queue_slug,
+ self.message_id,
+ error_message=error_message,
+ requeue=requeue,
+ )
+
+ def to_dict(self):
+ return self._raw
+
+
+class QueueBusSdk:
+ """Stable queue surface for plugins and internal consumers.
+
+ Plugins do:
+
+ from app.plugins_sdk import queue
+ queue.send('git-server', 'sync-jobs', {'repo': 'foo/bar'})
+ """
+
+ def ensure(self, group_slug, queue_slug, config=None):
+ """Ensure the group and queue exist."""
+ return QueueBusService.ensure_queue(group_slug, queue_slug, config=config)
+
+ def send(self, group_slug, queue_slug, payload, priority=0, delay_ms=0, max_attempts=None, ensure=True):
+ """Send a message to a queue."""
+ if ensure:
+ self.ensure(group_slug, queue_slug)
+ return QueueBusService.send(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ payload=payload,
+ priority=priority,
+ delay_ms=delay_ms,
+ max_attempts=max_attempts,
+ )
+
+ def receive(self, group_slug, queue_slug, visibility_timeout_ms=30000, ensure=True):
+ """Receive a single message. Returns ReceivedMessage or None."""
+ if ensure:
+ self.ensure(group_slug, queue_slug)
+ messages = QueueBusService.receive(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ visibility_timeout_ms=visibility_timeout_ms,
+ max_messages=1,
+ )
+ if not messages:
+ return None
+ return ReceivedMessage(group_slug, queue_slug, messages[0])
+
+ def receive_many(self, group_slug, queue_slug, visibility_timeout_ms=30000, max_messages=10, ensure=True):
+ """Receive multiple messages. Returns list of ReceivedMessage."""
+ if ensure:
+ self.ensure(group_slug, queue_slug)
+ messages = QueueBusService.receive(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ visibility_timeout_ms=visibility_timeout_ms,
+ max_messages=max_messages,
+ )
+ return [ReceivedMessage(group_slug, queue_slug, m) for m in messages]
+
+ def stats(self, group_slug=None, queue_slug=None):
+ return QueueBusService.get_stats(group_slug, queue_slug)
diff --git a/backend/app/queue_bus/service.py b/backend/app/queue_bus/service.py
new file mode 100644
index 00000000..768d0a46
--- /dev/null
+++ b/backend/app/queue_bus/service.py
@@ -0,0 +1,161 @@
+"""High-level service for the ServerKit Queue Bus."""
+import logging
+
+from app.queue_bus.sqlalchemy_broker import SQLAlchemyBroker, QueueBusError
+
+logger = logging.getLogger(__name__)
+
+
+class QueueBusService:
+ """Thin wrapper around the configured broker.
+
+ The service is the single entry point used by API routes, internal
+ consumers, and the plugin SDK. Today it always uses SQLAlchemyBroker;
+ in the future it can select a broker from config.
+ """
+
+ _broker = None
+
+ @classmethod
+ def broker(cls):
+ if cls._broker is None:
+ cls._broker = SQLAlchemyBroker()
+ return cls._broker
+
+ @classmethod
+ def reset_broker(cls):
+ """Reset the broker singleton. Useful for tests."""
+ cls._broker = None
+
+ # ------------------------------------------------------------------
+ # Groups
+ # ------------------------------------------------------------------
+ @classmethod
+ def create_group(cls, slug, name=None, description=None, owner_type='system', owner_id=None, config=None):
+ return cls.broker().create_group(
+ slug=slug,
+ name=name or slug,
+ description=description,
+ owner_type=owner_type,
+ owner_id=owner_id,
+ config=config,
+ )
+
+ @classmethod
+ def update_group(cls, slug, name=None, description=None, config=None):
+ return cls.broker().update_group(slug, name, description, config)
+
+ @classmethod
+ def delete_group(cls, slug):
+ return cls.broker().delete_group(slug)
+
+ @classmethod
+ def get_group(cls, slug):
+ return cls.broker().get_group(slug)
+
+ @classmethod
+ def list_groups(cls, owner_type=None, owner_id=None, limit=100, offset=0):
+ return cls.broker().list_groups(owner_type, owner_id, limit, offset)
+
+ # ------------------------------------------------------------------
+ # Queues
+ # ------------------------------------------------------------------
+ @classmethod
+ def create_queue(cls, group_slug, slug, name=None, description=None, config=None):
+ return cls.broker().create_queue(
+ group_slug=group_slug,
+ slug=slug,
+ name=name or slug,
+ description=description,
+ config=config,
+ )
+
+ @classmethod
+ def update_queue(cls, group_slug, slug, name=None, description=None, config=None):
+ return cls.broker().update_queue(group_slug, slug, name, description, config)
+
+ @classmethod
+ def delete_queue(cls, group_slug, queue_slug):
+ return cls.broker().delete_queue(group_slug, queue_slug)
+
+ @classmethod
+ def get_queue(cls, group_slug, queue_slug):
+ return cls.broker().get_queue(group_slug, queue_slug)
+
+ @classmethod
+ def list_queues(cls, group_slug, limit=100, offset=0):
+ return cls.broker().list_queues(group_slug, limit, offset)
+
+ # ------------------------------------------------------------------
+ # Messages
+ # ------------------------------------------------------------------
+ @classmethod
+ def send(cls, group_slug, queue_slug, payload, priority=0, delay_ms=0, max_attempts=None):
+ return cls.broker().send(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ payload=payload,
+ priority=priority,
+ delay_ms=delay_ms,
+ max_attempts=max_attempts,
+ )
+
+ @classmethod
+ def receive(cls, group_slug, queue_slug, visibility_timeout_ms=30000, max_messages=1):
+ return cls.broker().receive(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ visibility_timeout_ms=visibility_timeout_ms,
+ max_messages=max_messages,
+ )
+
+ @classmethod
+ def complete(cls, group_slug, queue_slug, message_id):
+ return cls.broker().complete(group_slug, queue_slug, message_id)
+
+ @classmethod
+ def fail(cls, group_slug, queue_slug, message_id, error_message=None, requeue=False):
+ return cls.broker().fail(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ message_id=message_id,
+ error_message=error_message,
+ requeue=requeue,
+ )
+
+ @classmethod
+ def requeue(cls, group_slug, queue_slug, message_id):
+ return cls.broker().requeue(group_slug, queue_slug, message_id)
+
+ @classmethod
+ def delete_message(cls, group_slug, queue_slug, message_id):
+ return cls.broker().delete_message(group_slug, queue_slug, message_id)
+
+ @classmethod
+ def get_message(cls, group_slug, queue_slug, message_id):
+ return cls.broker().get_message(group_slug, queue_slug, message_id)
+
+ @classmethod
+ def list_messages(cls, group_slug, queue_slug, status=None, limit=100, offset=0):
+ return cls.broker().list_messages(
+ group_slug=group_slug,
+ queue_slug=queue_slug,
+ status=status,
+ limit=limit,
+ offset=offset,
+ )
+
+ @classmethod
+ def get_stats(cls, group_slug=None, queue_slug=None):
+ return cls.broker().get_stats(group_slug, queue_slug)
+
+ @classmethod
+ def ensure_queue(cls, group_slug, queue_slug, config=None):
+ """Idempotently ensure a group and queue exist. Used by SDK/consumers."""
+ group = cls.get_group(group_slug)
+ if not group:
+ cls.create_group(group_slug, name=group_slug.replace('-', ' ').title())
+ queue = cls.get_queue(group_slug, queue_slug)
+ if not queue:
+ return cls.create_queue(group_slug, queue_slug, name=queue_slug.replace('-', ' ').title(), config=config)
+ return queue
diff --git a/backend/app/queue_bus/sqlalchemy_broker.py b/backend/app/queue_bus/sqlalchemy_broker.py
new file mode 100644
index 00000000..8f5824fd
--- /dev/null
+++ b/backend/app/queue_bus/sqlalchemy_broker.py
@@ -0,0 +1,314 @@
+"""SQLAlchemy-backed broker for the ServerKit Queue Bus."""
+import logging
+from datetime import datetime, timedelta
+
+from sqlalchemy import func
+
+from app import db
+from app.queue_bus.broker import AbstractBroker
+from app.queue_bus.models import QueueGroup, Queue, QueueMessage
+
+logger = logging.getLogger(__name__)
+
+
+class QueueBusError(Exception):
+ """Domain error for queue operations."""
+
+ def __init__(self, message, status_code=400):
+ super().__init__(message)
+ self.message = message
+ self.status_code = status_code
+
+
+class SQLAlchemyBroker(AbstractBroker):
+ """Default broker implementation using the existing SQLAlchemy database."""
+
+ # ------------------------------------------------------------------
+ # Groups
+ # ------------------------------------------------------------------
+ def create_group(self, slug, name, description=None, owner_type='system', owner_id=None, config=None):
+ if not slug or not _valid_slug(slug):
+ raise QueueBusError('Invalid group slug', 400)
+ if QueueGroup.query.filter_by(slug=slug).first():
+ raise QueueBusError('Group already exists', 409)
+
+ group = QueueGroup(
+ slug=slug,
+ name=name or slug,
+ description=description,
+ owner_type=owner_type,
+ owner_id=owner_id,
+ )
+ group.set_config(config or {})
+ db.session.add(group)
+ db.session.commit()
+ return group.to_dict(include_stats=True)
+
+ def update_group(self, slug, name=None, description=None, config=None):
+ group = QueueGroup.query.filter_by(slug=slug).first()
+ if not group:
+ raise QueueBusError('Group not found', 404)
+ if name is not None:
+ group.name = name
+ if description is not None:
+ group.description = description
+ if config is not None:
+ group.set_config(config)
+ db.session.commit()
+ return group.to_dict(include_stats=True)
+
+ def delete_group(self, slug):
+ group = QueueGroup.query.filter_by(slug=slug).first()
+ if not group:
+ raise QueueBusError('Group not found', 404)
+ db.session.delete(group)
+ db.session.commit()
+ return {'success': True}
+
+ def get_group(self, slug):
+ group = QueueGroup.query.filter_by(slug=slug).first()
+ if not group:
+ return None
+ return group.to_dict(include_stats=True)
+
+ def list_groups(self, owner_type=None, owner_id=None, limit=100, offset=0):
+ query = QueueGroup.query
+ if owner_type:
+ query = query.filter_by(owner_type=owner_type)
+ if owner_id:
+ query = query.filter_by(owner_id=owner_id)
+ groups = query.order_by(QueueGroup.created_at.desc()).limit(limit).offset(offset).all()
+ return [g.to_dict(include_stats=True) for g in groups]
+
+ # ------------------------------------------------------------------
+ # Queues
+ # ------------------------------------------------------------------
+ def create_queue(self, group_slug, slug, name, description=None, config=None):
+ if not slug or not _valid_slug(slug):
+ raise QueueBusError('Invalid queue slug', 400)
+ group = QueueGroup.query.filter_by(slug=group_slug).first()
+ if not group:
+ raise QueueBusError('Group not found', 404)
+ if Queue.query.filter_by(group_id=group.id, slug=slug).first():
+ raise QueueBusError('Queue already exists in group', 409)
+
+ queue = Queue(
+ group_id=group.id,
+ slug=slug,
+ name=name or slug,
+ description=description,
+ )
+ queue.set_config(config or {})
+ db.session.add(queue)
+ db.session.commit()
+ return queue.to_dict(include_stats=True)
+
+ def update_queue(self, group_slug, slug, name=None, description=None, config=None):
+ queue = self._get_queue_or_raise(group_slug, slug)
+ if name is not None:
+ queue.name = name
+ if description is not None:
+ queue.description = description
+ if config is not None:
+ queue.set_config(config)
+ db.session.commit()
+ return queue.to_dict(include_stats=True)
+
+ def delete_queue(self, group_slug, queue_slug):
+ queue = self._get_queue_or_raise(group_slug, queue_slug)
+ db.session.delete(queue)
+ db.session.commit()
+ return {'success': True}
+
+ def get_queue(self, group_slug, queue_slug):
+ queue = self._get_queue(group_slug, queue_slug)
+ if not queue:
+ return None
+ return queue.to_dict(include_stats=True)
+
+ def list_queues(self, group_slug, limit=100, offset=0):
+ group = QueueGroup.query.filter_by(slug=group_slug).first()
+ if not group:
+ raise QueueBusError('Group not found', 404)
+ queues = Queue.query.filter_by(group_id=group.id).order_by(Queue.created_at.desc()).limit(limit).offset(offset).all()
+ return [q.to_dict(include_stats=True) for q in queues]
+
+ # ------------------------------------------------------------------
+ # Messages
+ # ------------------------------------------------------------------
+ def send(self, group_slug, queue_slug, payload, priority=0, delay_ms=0, max_attempts=None):
+ queue = self._get_queue_or_raise(group_slug, queue_slug)
+ visible_after = datetime.utcnow()
+ if delay_ms:
+ visible_after += timedelta(milliseconds=delay_ms)
+
+ queue_config = queue.get_config()
+ message_max_attempts = max_attempts or queue_config.get('max_attempts', 3)
+
+ message = QueueMessage(
+ queue_id=queue.id,
+ group_id=queue.group_id,
+ status=QueueMessage.STATUS_PENDING,
+ priority=priority,
+ max_attempts=message_max_attempts,
+ visible_after=visible_after,
+ )
+ message.set_payload(payload)
+ db.session.add(message)
+ db.session.commit()
+ return message.to_dict()
+
+ def receive(self, group_slug, queue_slug, visibility_timeout_ms=30000, max_messages=1):
+ queue = self._get_queue_or_raise(group_slug, queue_slug)
+ now = datetime.utcnow()
+ invisible_until = now + timedelta(milliseconds=visibility_timeout_ms)
+
+ # Pending messages that are visible (no delay) and not currently invisible.
+ messages = QueueMessage.query.filter(
+ QueueMessage.queue_id == queue.id,
+ QueueMessage.status == QueueMessage.STATUS_PENDING,
+ QueueMessage.visible_after <= now,
+ db.or_(
+ QueueMessage.invisible_until.is_(None),
+ QueueMessage.invisible_until <= now,
+ ),
+ ).order_by(
+ QueueMessage.priority.desc(),
+ QueueMessage.created_at.asc(),
+ ).limit(max_messages).with_for_update().all()
+
+ for message in messages:
+ message.status = QueueMessage.STATUS_IN_FLIGHT
+ message.invisible_until = invisible_until
+ message.attempts += 1
+
+ db.session.commit()
+ return [m.to_dict() for m in messages]
+
+ def complete(self, group_slug, queue_slug, message_id):
+ message = self._get_message_or_raise(group_slug, queue_slug, message_id)
+ message.status = QueueMessage.STATUS_COMPLETED
+ message.completed_at = datetime.utcnow()
+ message.invisible_until = None
+ db.session.commit()
+ return message.to_dict()
+
+ def fail(self, group_slug, queue_slug, message_id, error_message=None, requeue=False):
+ message = self._get_message_or_raise(group_slug, queue_slug, message_id)
+ message.error_message = (message.error_message or '') + f'[{datetime.utcnow().isoformat()}] {error_message}\n' if error_message else message.error_message
+
+ if requeue:
+ message.status = QueueMessage.STATUS_PENDING
+ message.invisible_until = None
+ db.session.commit()
+ return message.to_dict()
+
+ if message.attempts >= message.max_attempts:
+ message.status = QueueMessage.STATUS_DEAD_LETTER
+ message.invisible_until = None
+ else:
+ # Exponential backoff: 10s, 30s, 90s, ...
+ delay_seconds = 10 * (3 ** (message.attempts - 1))
+ message.status = QueueMessage.STATUS_PENDING
+ message.visible_after = datetime.utcnow() + timedelta(seconds=delay_seconds)
+ message.invisible_until = None
+
+ db.session.commit()
+ return message.to_dict()
+
+ def requeue(self, group_slug, queue_slug, message_id):
+ message = self._get_message_or_raise(group_slug, queue_slug, message_id)
+ if message.status not in (QueueMessage.STATUS_FAILED, QueueMessage.STATUS_DEAD_LETTER):
+ raise QueueBusError('Only failed or dead-letter messages can be requeued', 400)
+ message.status = QueueMessage.STATUS_PENDING
+ message.visible_after = datetime.utcnow()
+ message.invisible_until = None
+ db.session.commit()
+ return message.to_dict()
+
+ def delete_message(self, group_slug, queue_slug, message_id):
+ message = self._get_message_or_raise(group_slug, queue_slug, message_id)
+ db.session.delete(message)
+ db.session.commit()
+ return {'success': True}
+
+ def get_message(self, group_slug, queue_slug, message_id):
+ message = self._get_message(group_slug, queue_slug, message_id)
+ if not message:
+ return None
+ return message.to_dict()
+
+ def list_messages(self, group_slug, queue_slug, status=None, limit=100, offset=0):
+ queue = self._get_queue_or_raise(group_slug, queue_slug)
+ query = QueueMessage.query.filter_by(queue_id=queue.id)
+ if status:
+ query = query.filter_by(status=status)
+ messages = query.order_by(QueueMessage.created_at.desc()).limit(limit).offset(offset).all()
+ return [m.to_dict() for m in messages]
+
+ def get_stats(self, group_slug=None, queue_slug=None):
+ query = db.session.query(
+ QueueMessage.status,
+ func.count(QueueMessage.id),
+ ).group_by(QueueMessage.status)
+
+ if queue_slug:
+ queue = self._get_queue_or_raise(group_slug, queue_slug)
+ query = query.filter(QueueMessage.queue_id == queue.id)
+ elif group_slug:
+ group = QueueGroup.query.filter_by(slug=group_slug).first()
+ if not group:
+ raise QueueBusError('Group not found', 404)
+ query = query.filter(QueueMessage.group_id == group.id)
+
+ counts = {status: 0 for status in (
+ QueueMessage.STATUS_PENDING,
+ QueueMessage.STATUS_IN_FLIGHT,
+ QueueMessage.STATUS_COMPLETED,
+ QueueMessage.STATUS_FAILED,
+ QueueMessage.STATUS_DEAD_LETTER,
+ )}
+ for status, count in query.all():
+ counts[status] = count
+
+ result = {'messages': counts}
+ if queue_slug:
+ result['total'] = sum(counts.values())
+ return result
+
+ # ------------------------------------------------------------------
+ # Helpers
+ # ------------------------------------------------------------------
+ def _get_queue(self, group_slug, queue_slug):
+ return Queue.query.join(QueueGroup).filter(
+ QueueGroup.slug == group_slug,
+ Queue.slug == queue_slug,
+ ).first()
+
+ def _get_queue_or_raise(self, group_slug, queue_slug):
+ queue = self._get_queue(group_slug, queue_slug)
+ if not queue:
+ raise QueueBusError('Queue not found', 404)
+ return queue
+
+ def _get_message(self, group_slug, queue_slug, message_id):
+ return QueueMessage.query.join(Queue).join(QueueGroup).filter(
+ QueueGroup.slug == group_slug,
+ Queue.slug == queue_slug,
+ QueueMessage.id == message_id,
+ ).first()
+
+ def _get_message_or_raise(self, group_slug, queue_slug, message_id):
+ message = self._get_message(group_slug, queue_slug, message_id)
+ if not message:
+ raise QueueBusError('Message not found', 404)
+ return message
+
+
+def _valid_slug(slug):
+ """Slugs are lowercase alphanumeric plus hyphen/underscore."""
+ if not slug:
+ return False
+ if slug.startswith('-') or slug.startswith('_'):
+ return False
+ return all(c.isalnum() or c in '-_' for c in slug)
diff --git a/backend/app/services/event_service.py b/backend/app/services/event_service.py
index 54f7534e..6ee0a4a2 100644
--- a/backend/app/services/event_service.py
+++ b/backend/app/services/event_service.py
@@ -1,17 +1,11 @@
"""Service for event emission and webhook delivery."""
-import hashlib
-import hmac
import json
import logging
-import time
-import threading
-import uuid
from datetime import datetime, timedelta
-import requests as http_requests
-
from app import db
from app.models.event_subscription import EventSubscription, EventDelivery
+from app.queue_bus.consumers.webhook_consumer import enqueue_webhook_delivery
logger = logging.getLogger(__name__)
@@ -109,7 +103,7 @@ class EventService:
db.session.commit()
- # Dispatch deliveries in background
+ # Dispatch deliveries via the queue bus
for sub in matching:
pending = EventDelivery.query.filter_by(
subscription_id=sub.id,
@@ -118,12 +112,10 @@ class EventService:
).order_by(EventDelivery.created_at.desc()).first()
if pending:
- thread = threading.Thread(
- target=EventService._deliver_in_thread,
- args=(pending.id,),
- daemon=True,
- )
- thread.start()
+ try:
+ enqueue_webhook_delivery(pending.id)
+ except Exception as e:
+ logger.error(f'Failed to enqueue webhook delivery {pending.id}: {e}')
@staticmethod
def emit_for_audit(action, target_type, target_id, details, user_id):
@@ -146,90 +138,9 @@ class EventService:
except Exception as e:
logger.error(f'Failed to emit event {event_type}: {e}')
- @staticmethod
- def _deliver_in_thread(delivery_id):
- """Deliver a webhook in a background thread."""
- from flask import current_app
- try:
- app = current_app._get_current_object()
- except RuntimeError:
- # No app context - need to import create_app
- return
-
- with app.app_context():
- EventService.deliver(delivery_id)
-
- @staticmethod
- def deliver(delivery_id):
- """Deliver a webhook to the subscription URL."""
- delivery = EventDelivery.query.get(delivery_id)
- if not delivery:
- return
-
- subscription = delivery.subscription
- if not subscription or not subscription.is_active:
- delivery.status = EventDelivery.STATUS_FAILED
- db.session.commit()
- return
-
- payload = delivery.get_payload()
- payload_json = json.dumps(payload)
- delivery_uuid = str(uuid.uuid4())
-
- headers = {
- 'Content-Type': 'application/json',
- 'X-ServerKit-Event': delivery.event_type,
- 'X-ServerKit-Delivery': delivery_uuid,
- 'User-Agent': 'ServerKit-Webhooks/1.0',
- }
-
- # HMAC signature if secret is set
- if subscription.secret:
- signature = hmac.new(
- subscription.secret.encode(),
- payload_json.encode(),
- hashlib.sha256,
- ).hexdigest()
- headers['X-ServerKit-Signature'] = f'sha256={signature}'
-
- # Add custom headers
- custom_headers = subscription.get_headers()
- if custom_headers:
- headers.update(custom_headers)
-
- delivery.attempts = (delivery.attempts or 0) + 1
- start_time = time.time()
-
- try:
- resp = http_requests.post( # nosec B113
- subscription.url,
- data=payload_json,
- headers=headers,
- timeout=subscription.timeout_seconds or 10,
- )
- elapsed_ms = (time.time() - start_time) * 1000
-
- delivery.http_status = resp.status_code
- delivery.response_body = resp.text[:1000] if resp.text else None
- delivery.duration_ms = round(elapsed_ms, 2)
-
- if 200 <= resp.status_code < 300:
- delivery.status = EventDelivery.STATUS_SUCCESS
- delivery.delivered_at = datetime.utcnow()
- else:
- _schedule_retry(delivery, subscription)
-
- except Exception as e:
- elapsed_ms = (time.time() - start_time) * 1000
- delivery.duration_ms = round(elapsed_ms, 2)
- delivery.response_body = str(e)[:1000]
- _schedule_retry(delivery, subscription)
-
- db.session.commit()
-
@staticmethod
def retry_failed():
- """Retry failed deliveries that are due."""
+ """Retry failed deliveries that are due by re-enqueueing them."""
now = datetime.utcnow()
pending = EventDelivery.query.filter(
EventDelivery.status == EventDelivery.STATUS_PENDING,
@@ -238,11 +149,14 @@ class EventService:
).all()
for delivery in pending:
- EventService.deliver(delivery.id)
+ try:
+ enqueue_webhook_delivery(delivery.id)
+ except Exception as e:
+ logger.error(f'Failed to enqueue retry for delivery {delivery.id}: {e}')
@staticmethod
def send_test(subscription_id):
- """Send a test event to a subscription."""
+ """Send a test event to a subscription via the queue bus."""
sub = EventSubscription.query.get(subscription_id)
if not sub:
return None
@@ -260,7 +174,10 @@ class EventService:
db.session.add(delivery)
db.session.commit()
- EventService.deliver(delivery.id)
+ try:
+ enqueue_webhook_delivery(delivery.id)
+ except Exception as e:
+ logger.error(f'Failed to enqueue test delivery {delivery.id}: {e}')
return delivery
@staticmethod
@@ -281,13 +198,3 @@ class EventService:
return deleted
-def _schedule_retry(delivery, subscription):
- """Schedule a retry with exponential backoff."""
- max_retries = subscription.retry_count or 3
- if delivery.attempts >= max_retries:
- delivery.status = EventDelivery.STATUS_FAILED
- else:
- # Exponential backoff: 10s, 30s, 90s
- delay_seconds = 10 * (3 ** (delivery.attempts - 1))
- delivery.next_retry_at = datetime.utcnow() + timedelta(seconds=delay_seconds)
- delivery.status = EventDelivery.STATUS_PENDING
diff --git a/backend/migrations/versions/022_queue_bus.py b/backend/migrations/versions/022_queue_bus.py
new file mode 100644
index 00000000..2f29db02
--- /dev/null
+++ b/backend/migrations/versions/022_queue_bus.py
@@ -0,0 +1,102 @@
+"""Queue Bus foundation.
+
+Adds:
+- queue_groups
+- queues
+- queue_messages
+
+Idempotent: MigrationService runs db.create_all() on boot before Alembic,
+so guard on the live schema.
+
+Revision ID: 022_queue_bus
+Revises: 021_secrets_webhooks_workspace
+Create Date: 2026-06-21
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '022_queue_bus'
+down_revision = '021_secrets_webhooks_workspace'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ if 'queue_groups' not in tables:
+ op.create_table(
+ 'queue_groups',
+ sa.Column('id', sa.String(36), nullable=False),
+ sa.Column('slug', sa.String(128), nullable=False),
+ sa.Column('name', sa.String(256), nullable=False),
+ sa.Column('description', sa.Text, nullable=True),
+ sa.Column('owner_type', sa.String(32), nullable=False, server_default='system'),
+ sa.Column('owner_id', sa.String(128), nullable=True),
+ sa.Column('config_json', sa.Text, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=False),
+ sa.Column('updated_at', sa.DateTime, nullable=False),
+ sa.PrimaryKeyConstraint('id'),
+ sa.UniqueConstraint('slug'),
+ )
+ op.create_index('ix_queue_groups_slug', 'queue_groups', ['slug'])
+
+ if 'queues' not in tables:
+ op.create_table(
+ 'queues',
+ sa.Column('id', sa.String(36), nullable=False),
+ sa.Column('group_id', sa.String(36), nullable=False),
+ sa.Column('slug', sa.String(128), nullable=False),
+ sa.Column('name', sa.String(256), nullable=False),
+ sa.Column('description', sa.Text, nullable=True),
+ sa.Column('config_json', sa.Text, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=False),
+ sa.Column('updated_at', sa.DateTime, nullable=False),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['group_id'], ['queue_groups.id']),
+ sa.UniqueConstraint('group_id', 'slug', name='uix_queue_group_slug'),
+ )
+ op.create_index('ix_queues_group_id', 'queues', ['group_id'])
+ op.create_index('ix_queues_slug', 'queues', ['slug'])
+
+ if 'queue_messages' not in tables:
+ op.create_table(
+ 'queue_messages',
+ sa.Column('id', sa.String(36), nullable=False),
+ sa.Column('queue_id', sa.String(36), nullable=False),
+ sa.Column('group_id', sa.String(36), nullable=False),
+ sa.Column('status', sa.String(32), nullable=False),
+ sa.Column('priority', sa.Integer, nullable=False),
+ sa.Column('payload_json', sa.Text, nullable=False),
+ sa.Column('result_json', sa.Text, nullable=True),
+ sa.Column('error_message', sa.Text, nullable=True),
+ sa.Column('attempts', sa.Integer, nullable=False),
+ sa.Column('max_attempts', sa.Integer, nullable=False),
+ sa.Column('visible_after', sa.DateTime, nullable=False),
+ sa.Column('invisible_until', sa.DateTime, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=False),
+ sa.Column('updated_at', sa.DateTime, nullable=False),
+ sa.Column('completed_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['queue_id'], ['queues.id']),
+ sa.ForeignKeyConstraint(['group_id'], ['queue_groups.id']),
+ )
+ op.create_index('ix_queue_messages_queue_id', 'queue_messages', ['queue_id'])
+ op.create_index('ix_queue_messages_group_id', 'queue_messages', ['group_id'])
+ op.create_index('ix_queue_messages_status', 'queue_messages', ['status'])
+ op.create_index('ix_queue_messages_priority', 'queue_messages', ['priority'])
+ op.create_index('ix_queue_messages_visible_after', 'queue_messages', ['visible_after'])
+ op.create_index('ix_queue_messages_invisible_until', 'queue_messages', ['invisible_until'])
+ op.create_index('ix_queue_messages_created_at', 'queue_messages', ['created_at'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ for table in ('queue_messages', 'queues', 'queue_groups'):
+ if table in tables:
+ op.drop_table(table)
diff --git a/backend/tests/test_queue_bus.py b/backend/tests/test_queue_bus.py
new file mode 100644
index 00000000..c3c91576
--- /dev/null
+++ b/backend/tests/test_queue_bus.py
@@ -0,0 +1,192 @@
+"""Tests for the ServerKit Queue Bus."""
+import pytest
+from datetime import datetime, timedelta
+
+from app import db
+from app.queue_bus.service import QueueBusService, QueueBusError
+from app.queue_bus.models import QueueGroup, Queue, QueueMessage
+
+
[email protected](autouse=True)
+def reset_broker(app):
+ """Reset the service broker singleton before each test."""
+ QueueBusService.reset_broker()
+
+
+def _create_group_queue(group='test-group', queue='test-queue'):
+ QueueBusService.create_group(group, name='Test Group')
+ QueueBusService.create_queue(group, queue, name='Test Queue', config={'max_attempts': 3})
+
+
+class TestGroups:
+ def test_create_group(self, app):
+ group = QueueBusService.create_group('my-group', name='My Group')
+ assert group['slug'] == 'my-group'
+ assert group['name'] == 'My Group'
+ assert QueueGroup.query.filter_by(slug='my-group').first() is not None
+
+ def test_create_group_duplicate_fails(self, app):
+ QueueBusService.create_group('my-group')
+ with pytest.raises(QueueBusError) as exc:
+ QueueBusService.create_group('my-group')
+ assert exc.value.status_code == 409
+
+ def test_list_groups(self, app):
+ QueueBusService.create_group('g1')
+ QueueBusService.create_group('g2')
+ groups = QueueBusService.list_groups()
+ assert len(groups) == 2
+
+ def test_update_group(self, app):
+ QueueBusService.create_group('g1')
+ updated = QueueBusService.update_group('g1', name='Updated', config={'retention_hours': 24})
+ assert updated['name'] == 'Updated'
+ assert updated['config'] == {'retention_hours': 24}
+
+ def test_delete_group_cascades(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'hello': 'world'})
+ QueueBusService.delete_group('g1')
+ assert QueueGroup.query.filter_by(slug='g1').first() is None
+ assert Queue.query.filter_by(slug='q1').first() is None
+ assert QueueMessage.query.count() == 0
+
+
+class TestQueues:
+ def test_create_queue(self, app):
+ QueueBusService.create_group('g1')
+ queue = QueueBusService.create_queue('g1', 'q1', name='Q1', config={'visibility_timeout_ms': 60000})
+ assert queue['slug'] == 'q1'
+ assert queue['config']['visibility_timeout_ms'] == 60000
+
+ def test_create_queue_duplicate_fails(self, app):
+ QueueBusService.create_group('g1')
+ QueueBusService.create_queue('g1', 'q1')
+ with pytest.raises(QueueBusError) as exc:
+ QueueBusService.create_queue('g1', 'q1')
+ assert exc.value.status_code == 409
+
+ def test_list_queues(self, app):
+ QueueBusService.create_group('g1')
+ QueueBusService.create_queue('g1', 'q1')
+ QueueBusService.create_queue('g1', 'q2')
+ queues = QueueBusService.list_queues('g1')
+ assert len(queues) == 2
+
+
+class TestMessages:
+ def test_send_and_receive(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'})
+ messages = QueueBusService.receive('g1', 'q1')
+ assert len(messages) == 1
+ assert messages[0]['payload'] == {'task': 'hello'}
+ assert messages[0]['status'] == QueueMessage.STATUS_IN_FLIGHT
+
+ def test_complete_message(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'})
+ received = QueueBusService.receive('g1', 'q1')[0]
+ completed = QueueBusService.complete('g1', 'q1', received['id'])
+ assert completed['status'] == QueueMessage.STATUS_COMPLETED
+ assert completed['completed_at'] is not None
+
+ def test_fail_then_retry(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'})
+ received = QueueBusService.receive('g1', 'q1')[0]
+ failed = QueueBusService.fail('g1', 'q1', received['id'], error_message='boom')
+ assert failed['status'] == QueueMessage.STATUS_PENDING
+ assert failed['attempts'] == 1
+ assert failed['error_message'] is not None
+
+ def test_dead_letter_after_max_attempts(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'}, max_attempts=2)
+ m1 = QueueBusService.receive('g1', 'q1')[0]
+ # First failure is requeued immediately to bypass the retry delay.
+ QueueBusService.fail('g1', 'q1', m1['id'], error_message='attempt 1', requeue=True)
+ m2 = QueueBusService.receive('g1', 'q1')[0]
+ QueueBusService.fail('g1', 'q1', m2['id'], error_message='attempt 2')
+ # No more pending messages.
+ assert QueueBusService.receive('g1', 'q1') == []
+ message = QueueBusService.get_message('g1', 'q1', m1['id'])
+ assert message['status'] == QueueMessage.STATUS_DEAD_LETTER
+
+ def test_visibility_timeout_blocks_re_receive(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'})
+ QueueBusService.receive('g1', 'q1', visibility_timeout_ms=60000)
+ second = QueueBusService.receive('g1', 'q1')
+ assert second == []
+
+ def test_requeue_failed_message(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'}, max_attempts=1)
+ m = QueueBusService.receive('g1', 'q1')[0]
+ QueueBusService.fail('g1', 'q1', m['id'], error_message='boom')
+ requeued = QueueBusService.requeue('g1', 'q1', m['id'])
+ assert requeued['status'] == QueueMessage.STATUS_PENDING
+ assert QueueBusService.receive('g1', 'q1') != []
+
+ def test_delayed_message(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'hello'}, delay_ms=3600000)
+ assert QueueBusService.receive('g1', 'q1') == []
+
+ def test_priority_ordering(self, app):
+ _create_group_queue('g1', 'q1')
+ QueueBusService.send('g1', 'q1', {'task': 'low'}, priority=0)
+ QueueBusService.send('g1', 'q1', {'task': 'high'}, priority=10)
+ messages = QueueBusService.receive('g1', 'q1', max_messages=2)
+ assert messages[0]['payload']['task'] == 'high'
+ assert messages[1]['payload']['task'] == 'low'
+
+
+class TestApi:
+ def test_create_group_via_api(self, client, auth_headers, app):
+ resp = client.post('/api/v1/queue/groups', json={
+ 'slug': 'api-group',
+ 'name': 'API Group',
+ }, headers=auth_headers)
+ assert resp.status_code == 201
+ assert resp.get_json()['group']['slug'] == 'api-group'
+
+ def test_send_and_receive_via_api(self, client, auth_headers, app):
+ client.post('/api/v1/queue/groups', json={'slug': 'g1', 'name': 'G1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues', json={'slug': 'q1', 'name': 'Q1'}, headers=auth_headers)
+ send_resp = client.post('/api/v1/queue/groups/g1/queues/q1/messages', json={
+ 'payload': {'hello': 'world'},
+ }, headers=auth_headers)
+ assert send_resp.status_code == 201
+
+ receive_resp = client.post('/api/v1/queue/groups/g1/queues/q1/messages/receive', json={
+ 'max_messages': 1,
+ }, headers=auth_headers)
+ assert receive_resp.status_code == 200
+ data = receive_resp.get_json()
+ assert len(data['messages']) == 1
+ assert data['messages'][0]['payload'] == {'hello': 'world'}
+
+ def test_complete_via_api(self, client, auth_headers, app):
+ client.post('/api/v1/queue/groups', json={'slug': 'g1', 'name': 'G1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues', json={'slug': 'q1', 'name': 'Q1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues/q1/messages', json={'payload': {'x': 1}}, headers=auth_headers)
+ msg = client.post('/api/v1/queue/groups/g1/queues/q1/messages/receive', json={}, headers=auth_headers).get_json()['messages'][0]
+ resp = client.post(f'/api/v1/queue/groups/g1/queues/q1/messages/{msg["id"]}/complete', json={}, headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json()['message']['status'] == QueueMessage.STATUS_COMPLETED
+
+ def test_stats_endpoint(self, client, auth_headers, app):
+ client.post('/api/v1/queue/groups', json={'slug': 'g1', 'name': 'G1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues', json={'slug': 'q1', 'name': 'Q1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues/q1/messages', json={'payload': {'x': 1}}, headers=auth_headers)
+ resp = client.get('/api/v1/queue/stats', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json()['messages']['pending'] == 1
+
+ def test_shorthand_send(self, client, auth_headers, app):
+ client.post('/api/v1/queue/groups', json={'slug': 'g1', 'name': 'G1'}, headers=auth_headers)
+ client.post('/api/v1/queue/groups/g1/queues', json={'slug': 'q1', 'name': 'Q1'}, headers=auth_headers)
+ resp = client.post('/api/v1/queue/g1/q1/messages', json={'payload': {'x': 1}}, headers=auth_headers)
+ assert resp.status_code == 201
diff --git a/backend/tests/test_queue_bus_webhooks.py b/backend/tests/test_queue_bus_webhooks.py
new file mode 100644
index 00000000..dd4428c3
--- /dev/null
+++ b/backend/tests/test_queue_bus_webhooks.py
@@ -0,0 +1,114 @@
+"""Tests for webhook delivery integration with the Queue Bus."""
+from app import db
+from app.models.user import User
+from app.models.event_subscription import EventSubscription, EventDelivery
+from app.services.event_service import EventService
+from app.queue_bus.service import QueueBusService
+from app.queue_bus.models import QueueGroup
+
+
+def _seed_subscription(user_id, url='https://example.com/webhook', events=None):
+ sub = EventSubscription(
+ user_id=user_id,
+ name='Test Webhook',
+ url=url,
+ )
+ sub.set_events(events or ['app.created'])
+ db.session.add(sub)
+ db.session.commit()
+ return sub
+
+
+class TestWebhookQueueIntegration:
+ def test_emit_enqueues_webhook_delivery(self, app, auth_headers):
+ from app.models import User
+ user = User.query.filter_by(username='testadmin').first()
+ sub = _seed_subscription(user.id)
+
+ EventService.emit('app.created', {'app_id': 1, 'name': 'test'})
+
+ delivery = EventDelivery.query.filter_by(subscription_id=sub.id).first()
+ assert delivery is not None
+ assert delivery.status == EventDelivery.STATUS_PENDING
+
+ # A message should exist on the system webhook queue.
+ QueueBusService.ensure_queue('serverkit-system', 'webhook-deliveries')
+ messages = QueueBusService.receive('serverkit-system', 'webhook-deliveries')
+ assert len(messages) == 1
+ assert messages[0]['payload']['delivery_id'] == delivery.id
+
+ def test_emit_no_subscription_no_message(self, app, auth_headers):
+ EventService.emit('app.created', {'app_id': 1})
+ QueueBusService.ensure_queue('serverkit-system', 'webhook-deliveries')
+ messages = QueueBusService.receive('serverkit-system', 'webhook-deliveries')
+ assert messages == []
+
+ def test_webhook_consumer_delivers_success(self, app, monkeypatch, auth_headers):
+ from app.models import User
+ from app.queue_bus.consumers.webhook_consumer import WebhookConsumer
+
+ user = User.query.filter_by(username='testadmin').first()
+ sub = _seed_subscription(user.id)
+ EventService.emit('app.created', {'app_id': 1})
+ delivery = EventDelivery.query.filter_by(subscription_id=sub.id).first()
+
+ calls = []
+
+ def fake_post(url, data, headers, timeout):
+ class Resp:
+ status_code = 200
+ text = 'ok'
+ calls.append((url, data, headers, timeout))
+ return Resp()
+
+ monkeypatch.setattr('app.queue_bus.consumers.webhook_consumer.http_requests.post', fake_post)
+
+ consumer = WebhookConsumer(app)
+ consumer._process_batch()
+
+ assert len(calls) == 1
+ delivery_after = EventDelivery.query.get(delivery.id)
+ assert delivery_after.status == EventDelivery.STATUS_SUCCESS
+
+ def test_webhook_consumer_retries_then_dead_letters(self, app, monkeypatch, auth_headers):
+ from app.models import User
+ from app.queue_bus.consumers.webhook_consumer import WebhookConsumer
+
+ user = User.query.filter_by(username='testadmin').first()
+ sub = _seed_subscription(user.id)
+ EventService.emit('app.created', {'app_id': 1})
+ delivery = EventDelivery.query.filter_by(subscription_id=sub.id).first()
+
+ QueueBusService.ensure_queue('serverkit-system', 'webhook-deliveries')
+ from app.queue_bus.models import Queue
+ queue = Queue.query.join(Queue.group).filter(
+ QueueGroup.slug == 'serverkit-system',
+ Queue.slug == 'webhook-deliveries',
+ ).first()
+
+ def fake_post(*args, **kwargs):
+ class Resp:
+ status_code = 500
+ text = 'error'
+ return Resp()
+
+ monkeypatch.setattr('app.queue_bus.consumers.webhook_consumer.http_requests.post', fake_post)
+
+ consumer = WebhookConsumer(app)
+ # Three attempts: initial + 2 retries. Bypass the bus retry delay in tests
+ # by resetting visible_after between iterations.
+ from app.queue_bus.models import QueueMessage
+ from datetime import datetime
+ for _ in range(3):
+ consumer._process_batch()
+ msg = QueueMessage.query.filter_by(queue_id=queue.id).first()
+ if msg and msg.status == QueueMessage.STATUS_PENDING:
+ msg.visible_after = datetime.utcnow()
+ db.session.commit()
+
+ delivery_after = EventDelivery.query.get(delivery.id)
+ assert delivery_after.attempts == 3
+ # The bus message should be dead-lettered after max_attempts.
+ QueueBusService.ensure_queue('serverkit-system', 'webhook-deliveries')
+ pending = QueueBusService.receive('serverkit-system', 'webhook-deliveries')
+ assert pending == []
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index 3c036144..3f222f29 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -67,6 +67,7 @@ import Documentation from './pages/Documentation';
import Deployments from './pages/Deployments';
import GpuMonitor from './pages/GpuMonitor';
import DynamicDns from './pages/DynamicDns';
+import QueueOperations from './pages/QueueOperations';
import useExtensionRoutes from './plugins/ExtensionRoutes';
import { useContributions } from './plugins/contributions';
@@ -117,6 +118,7 @@ const PAGE_TITLES = {
'/documentation': 'Documentation',
'/gpu': 'GPU Monitor',
'/dynamic-dns': 'Dynamic DNS',
+ '/queue': 'Queue Bus',
};
function PageTitleUpdater() {
@@ -343,6 +345,7 @@ function AppRoutes() {
<Route path="terminal/:tab" element={<Terminal />} />
<Route path="secrets" element={<SecretsWebhooks />} />
<Route path="secrets/:tab" element={<SecretsWebhooks />} />
+ <Route path="queue" element={<QueueOperations />} />
<Route path="settings" element={<Settings />} />
<Route path="settings/:tab" element={<Settings />} />
{dashboardRoutes}
diff --git a/frontend/src/components/sidebarItems.js b/frontend/src/components/sidebarItems.js
index bc6838a6..d2a7f657 100644
--- a/frontend/src/components/sidebarItems.js
+++ b/frontend/src/components/sidebarItems.js
@@ -158,6 +158,13 @@ export const SIDEBAR_ITEMS = [
category: 'operations',
icon: '<path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"/><polyline points="22,6 12,13 2,6"/>'
},
+ {
+ id: 'queue',
+ label: 'Queue Bus',
+ route: '/queue',
+ category: 'operations',
+ icon: '<rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/>'
+ },
{
id: 'workspaces',
label: 'Workspaces',
diff --git a/frontend/src/pages/QueueOperations.jsx b/frontend/src/pages/QueueOperations.jsx
new file mode 100644
index 00000000..88d08bb7
--- /dev/null
+++ b/frontend/src/pages/QueueOperations.jsx
@@ -0,0 +1,657 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import {
+ Layers, List, Inbox, Send, Trash2, RefreshCw, Plus
+} from 'lucide-react';
+import api from '../services/api';
+import { useToast } from '../contexts/ToastContext';
+import { useConfirm } from '../hooks/useConfirm';
+import { ConfirmDialog } from '../components/ConfirmDialog';
+import EmptyState from '../components/EmptyState';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
+import { PageTopbar, MetricCard, Pill } from '@/components/ds';
+
+const STATUS_KINDS = {
+ pending: 'blue',
+ in_flight: 'yellow',
+ completed: 'green',
+ failed: 'red',
+ dead_letter: 'gray',
+};
+
+const POLL_INTERVAL = 3000;
+
+const QueueOperations = () => {
+ const toast = useToast();
+ const { confirm, confirmState, handleConfirm, handleCancel } = useConfirm();
+
+ const [activeTab, setActiveTab] = useState('overview');
+ const [loading, setLoading] = useState(true);
+ const [groups, setGroups] = useState([]);
+ const [selectedGroup, setSelectedGroup] = useState('');
+ const [selectedQueue, setSelectedQueue] = useState('');
+ const [queues, setQueues] = useState([]);
+ const [messages, setMessages] = useState([]);
+ const [stats, setStats] = useState(null);
+ const [messageFilter, setMessageFilter] = useState('all');
+
+ const [showGroupModal, setShowGroupModal] = useState(false);
+ const [groupForm, setGroupForm] = useState({ slug: '', name: '', description: '' });
+
+ const [showQueueModal, setShowQueueModal] = useState(false);
+ const [queueForm, setQueueForm] = useState({ slug: '', name: '', description: '', config: '{}' });
+
+ const [sendForm, setSendForm] = useState({ payload: '{}', priority: 0, delay_ms: 0 });
+
+ const [selectedMessage, setSelectedMessage] = useState(null);
+
+ const pollRef = useRef(null);
+
+ const loadData = useCallback(async () => {
+ try {
+ const [groupsRes, statsRes] = await Promise.all([
+ api.getQueueGroups(),
+ api.getGlobalQueueStats(),
+ ]);
+ setGroups(groupsRes.groups || []);
+ setStats(statsRes);
+ } catch (err) {
+ toast.error(err.message);
+ } finally {
+ setLoading(false);
+ }
+ }, [toast]);
+
+ const loadQueues = useCallback(async (groupSlug) => {
+ if (!groupSlug) return;
+ try {
+ const res = await api.getQueues(groupSlug);
+ setQueues(res.queues || []);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ }, [toast]);
+
+ const loadMessages = useCallback(async (groupSlug, queueSlug) => {
+ if (!groupSlug || !queueSlug) return;
+ try {
+ const status = messageFilter === 'all' ? undefined : messageFilter;
+ const res = await api.getMessages(groupSlug, queueSlug, { status, limit: 100 });
+ setMessages(res.messages || []);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ }, [toast, messageFilter]);
+
+ useEffect(() => {
+ loadData();
+ pollRef.current = setInterval(() => {
+ loadData();
+ if (selectedGroup) loadQueues(selectedGroup);
+ if (selectedGroup && selectedQueue) loadMessages(selectedGroup, selectedQueue);
+ }, POLL_INTERVAL);
+ return () => {
+ if (pollRef.current) clearInterval(pollRef.current);
+ };
+ }, [selectedGroup, selectedQueue, loadData, loadQueues, loadMessages]);
+
+ const handleCreateGroup = async (e) => {
+ e.preventDefault();
+ try {
+ await api.createQueueGroup(groupForm);
+ toast.success('Queue group created');
+ setShowGroupModal(false);
+ setGroupForm({ slug: '', name: '', description: '' });
+ loadData();
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleDeleteGroup = async (slug) => {
+ const confirmed = await confirm({
+ title: 'Delete Queue Group',
+ message: `Are you sure you want to delete "${slug}" and all its queues and messages?`,
+ variant: 'danger',
+ });
+ if (!confirmed) return;
+ try {
+ await api.deleteQueueGroup(slug);
+ toast.success('Queue group deleted');
+ if (selectedGroup === slug) {
+ setSelectedGroup('');
+ setSelectedQueue('');
+ setQueues([]);
+ setMessages([]);
+ }
+ loadData();
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleCreateQueue = async (e) => {
+ e.preventDefault();
+ try {
+ let config = {};
+ try {
+ config = JSON.parse(queueForm.config);
+ } catch {
+ toast.error('Config must be valid JSON');
+ return;
+ }
+ await api.createQueue(selectedGroup, {
+ slug: queueForm.slug,
+ name: queueForm.name,
+ description: queueForm.description,
+ config,
+ });
+ toast.success('Queue created');
+ setShowQueueModal(false);
+ setQueueForm({ slug: '', name: '', description: '', config: '{}' });
+ loadQueues(selectedGroup);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleDeleteQueue = async (groupSlug, queueSlug) => {
+ const confirmed = await confirm({
+ title: 'Delete Queue',
+ message: `Are you sure you want to delete "${queueSlug}" and all its messages?`,
+ variant: 'danger',
+ });
+ if (!confirmed) return;
+ try {
+ await api.deleteQueue(groupSlug, queueSlug);
+ toast.success('Queue deleted');
+ if (selectedQueue === queueSlug) {
+ setSelectedQueue('');
+ setMessages([]);
+ }
+ loadQueues(groupSlug);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleSendMessage = async (e) => {
+ e.preventDefault();
+ try {
+ let payload = {};
+ try {
+ payload = JSON.parse(sendForm.payload);
+ } catch {
+ toast.error('Payload must be valid JSON');
+ return;
+ }
+ await api.sendMessage(selectedGroup, selectedQueue, payload, {
+ priority: parseInt(sendForm.priority, 10) || 0,
+ delay_ms: parseInt(sendForm.delay_ms, 10) || 0,
+ });
+ toast.success('Message sent');
+ setActiveTab('messages');
+ setSendForm({ payload: '{}', priority: 0, delay_ms: 0 });
+ loadMessages(selectedGroup, selectedQueue);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleRequeueMessage = async (msg) => {
+ try {
+ await api.requeueMessage(msg.group_slug, msg.queue_slug, msg.id);
+ toast.success('Message requeued');
+ loadMessages(selectedGroup, selectedQueue);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const handleDeleteMessage = async (msg) => {
+ const confirmed = await confirm({
+ title: 'Delete Message',
+ message: 'Permanently delete this message?',
+ variant: 'danger',
+ });
+ if (!confirmed) return;
+ try {
+ await api.deleteMessage(msg.group_slug, msg.queue_slug, msg.id);
+ toast.success('Message deleted');
+ loadMessages(selectedGroup, selectedQueue);
+ } catch (err) {
+ toast.error(err.message);
+ }
+ };
+
+ const totalMessages = stats ? Object.values(stats.messages || {}).reduce((a, b) => a + b, 0) : 0;
+
+ if (loading) {
+ return (
+ <div className="page-container queue-operations-page">
+ <EmptyState loading size="lg" title="Loading queue bus..." />
+ </div>
+ );
+ }
+
+ return (
+ <div className="page-container queue-operations-page">
+ <PageTopbar
+ icon={<Layers size={18} />}
+ title="Queue Bus"
+ actions={(
+ <Button variant="outline" size="sm" onClick={loadData}>
+ <RefreshCw size={14} className="mr-2" /> Refresh
+ </Button>
+ )}
+ />
+
+ <div className="queue-kpis">
+ <MetricCard label="Groups" value={groups.length} />
+ <MetricCard label="Queues" value={groups.reduce((acc, g) => acc + (g.stats?.queues || 0), 0)} />
+ <MetricCard label="Total Messages" value={totalMessages} />
+ <MetricCard label="Dead Letter" value={stats?.messages?.dead_letter || 0} kind="danger" />
+ </div>
+
+ <Tabs value={activeTab} onValueChange={setActiveTab} className="queue-tabs">
+ <TabsList>
+ <TabsTrigger value="overview"><Layers size={14} className="mr-2" /> Overview</TabsTrigger>
+ <TabsTrigger value="groups"><List size={14} className="mr-2" /> Groups</TabsTrigger>
+ <TabsTrigger value="messages"><Inbox size={14} className="mr-2" /> Messages</TabsTrigger>
+ <TabsTrigger value="send"><Send size={14} className="mr-2" /> Send Message</TabsTrigger>
+ </TabsList>
+
+ <TabsContent value="overview" className="queue-tab-content">
+ {groups.length === 0 ? (
+ <EmptyState
+ icon={Layers}
+ title="No Queue Groups"
+ description="Create a group to start using the queue bus."
+ action={<Button onClick={() => setShowGroupModal(true)}><Plus size={14} className="mr-2" /> Create Group</Button>}
+ />
+ ) : (
+ <div className="queue-group-tree">
+ {groups.map(group => (
+ <div key={group.id} className="queue-group-card">
+ <div className="queue-group-header">
+ <span className="queue-group-name">{group.name}</span>
+ <span className="queue-group-slug">/{group.slug}</span>
+ <span className="queue-group-meta">{group.stats?.queues || 0} queues</span>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => {
+ setSelectedGroup(group.slug);
+ setActiveTab('messages');
+ loadQueues(group.slug);
+ }}
+ >
+ View Queues
+ </Button>
+ </div>
+ </div>
+ ))}
+ </div>
+ )}
+ </TabsContent>
+
+ <TabsContent value="groups" className="queue-tab-content">
+ <div className="queue-listhead">
+ <h2>Queue Groups</h2>
+ <Button size="sm" onClick={() => setShowGroupModal(true)}><Plus size={14} className="mr-2" /> Create Group</Button>
+ </div>
+ {groups.length === 0 ? (
+ <EmptyState
+ icon={Layers}
+ title="No Groups"
+ description="Create your first queue group."
+ />
+ ) : (
+ <table className="sk-dtable queue-table">
+ <thead>
+ <tr>
+ <th>Group</th>
+ <th>Slug</th>
+ <th>Queues</th>
+ <th>Owner</th>
+ <th aria-label="Actions" />
+ </tr>
+ </thead>
+ <tbody>
+ {groups.map(group => (
+ <tr key={group.id}>
+ <td>{group.name}</td>
+ <td><code>{group.slug}</code></td>
+ <td>{group.stats?.queues || 0}</td>
+ <td>{group.owner_type}{group.owner_id ? `:${group.owner_id}` : ''}</td>
+ <td>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => {
+ setSelectedGroup(group.slug);
+ setActiveTab('messages');
+ loadQueues(group.slug);
+ }}
+ >
+ View
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => handleDeleteGroup(group.slug)}
+ >
+ <Trash2 size={14} />
+ </Button>
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ )}
+ </TabsContent>
+
+ <TabsContent value="messages" className="queue-tab-content">
+ <div className="queue-messages-toolbar">
+ <div className="queue-messages-selects">
+ <select
+ className="queue-select"
+ value={selectedGroup}
+ onChange={(e) => {
+ setSelectedGroup(e.target.value);
+ setSelectedQueue('');
+ setQueues([]);
+ setMessages([]);
+ loadQueues(e.target.value);
+ }}
+ >
+ <option value="">Select group</option>
+ {groups.map(g => <option key={g.id} value={g.slug}>{g.name}</option>)}
+ </select>
+ <select
+ className="queue-select"
+ value={selectedQueue}
+ onChange={(e) => {
+ setSelectedQueue(e.target.value);
+ loadMessages(selectedGroup, e.target.value);
+ }}
+ disabled={!selectedGroup}
+ >
+ <option value="">Select queue</option>
+ {queues.map(q => <option key={q.id} value={q.slug}>{q.name}</option>)}
+ </select>
+ <select
+ className="queue-select"
+ value={messageFilter}
+ onChange={(e) => setMessageFilter(e.target.value)}
+ >
+ <option value="all">All statuses</option>
+ <option value="pending">Pending</option>
+ <option value="in_flight">In Flight</option>
+ <option value="completed">Completed</option>
+ <option value="failed">Failed</option>
+ <option value="dead_letter">Dead Letter</option>
+ </select>
+ {selectedGroup && selectedQueue && (
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => handleDeleteQueue(selectedGroup, selectedQueue)}
+ title="Delete queue"
+ >
+ <Trash2 size={14} />
+ </Button>
+ )}
+ </div>
+ <div className="queue-messages-actions">
+ <Button
+ size="sm"
+ disabled={!selectedGroup}
+ onClick={() => setShowQueueModal(true)}
+ >
+ <Plus size={14} className="mr-2" /> Create Queue
+ </Button>
+ <Button
+ size="sm"
+ disabled={!selectedGroup || !selectedQueue}
+ onClick={() => setActiveTab('send')}
+ >
+ <Send size={14} className="mr-2" /> Send Message
+ </Button>
+ </div>
+ </div>
+
+ {!selectedGroup || !selectedQueue ? (
+ <EmptyState icon={Inbox} title="Select a Queue" description="Choose a group and queue to browse messages." />
+ ) : messages.length === 0 ? (
+ <EmptyState icon={Inbox} title="No Messages" description="This queue is empty. Send a message to get started." />
+ ) : (
+ <table className="sk-dtable queue-table">
+ <thead>
+ <tr>
+ <th>Status</th>
+ <th>Payload</th>
+ <th>Attempts</th>
+ <th>Created</th>
+ <th aria-label="Actions" />
+ </tr>
+ </thead>
+ <tbody>
+ {messages.map(msg => (
+ <tr key={msg.id} className="is-clickable" onClick={() => setSelectedMessage(msg)}>
+ <td><Pill kind={STATUS_KINDS[msg.status] || 'gray'}>{msg.status}</Pill></td>
+ <td><code className="queue-payload-preview">{JSON.stringify(msg.payload).slice(0, 80)}</code></td>
+ <td>{msg.attempts} / {msg.max_attempts}</td>
+ <td>{new Date(msg.created_at).toLocaleString()}</td>
+ <td onClick={e => e.stopPropagation()}>
+ <div className="queue-actions">
+ {(msg.status === 'failed' || msg.status === 'dead_letter') && (
+ <Button variant="ghost" size="sm" onClick={() => handleRequeueMessage(msg)}>
+ <RefreshCw size={14} />
+ </Button>
+ )}
+ <Button variant="ghost" size="sm" onClick={() => handleDeleteMessage(msg)}>
+ <Trash2 size={14} />
+ </Button>
+ </div>
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ )}
+ </TabsContent>
+
+ <TabsContent value="send" className="queue-tab-content">
+ <div className="queue-send-card">
+ <div className="queue-messages-toolbar">
+ <div className="queue-messages-selects">
+ <select
+ className="queue-select"
+ value={selectedGroup}
+ onChange={(e) => {
+ setSelectedGroup(e.target.value);
+ setSelectedQueue('');
+ loadQueues(e.target.value);
+ }}
+ >
+ <option value="">Select group</option>
+ {groups.map(g => <option key={g.id} value={g.slug}>{g.name}</option>)}
+ </select>
+ <select
+ className="queue-select"
+ value={selectedQueue}
+ onChange={(e) => setSelectedQueue(e.target.value)}
+ disabled={!selectedGroup}
+ >
+ <option value="">Select queue</option>
+ {queues.map(q => <option key={q.id} value={q.slug}>{q.name}</option>)}
+ </select>
+ </div>
+ </div>
+ {(!selectedGroup || !selectedQueue) ? (
+ <EmptyState icon={Send} title="Select a Queue" description="Choose a destination group and queue first." />
+ ) : (
+ <form onSubmit={handleSendMessage} className="queue-send-form">
+ <div className="form-group">
+ <Label htmlFor="payload">Payload (JSON)</Label>
+ <Textarea
+ id="payload"
+ value={sendForm.payload}
+ onChange={(e) => setSendForm({ ...sendForm, payload: e.target.value })}
+ rows={6}
+ required
+ />
+ </div>
+ <div className="form-row">
+ <div className="form-group">
+ <Label htmlFor="priority">Priority</Label>
+ <Input
+ id="priority"
+ type="number"
+ value={sendForm.priority}
+ onChange={(e) => setSendForm({ ...sendForm, priority: e.target.value })}
+ />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="delay_ms">Delay (ms)</Label>
+ <Input
+ id="delay_ms"
+ type="number"
+ value={sendForm.delay_ms}
+ onChange={(e) => setSendForm({ ...sendForm, delay_ms: e.target.value })}
+ />
+ </div>
+ </div>
+ <div className="form-actions">
+ <Button type="submit"><Send size={14} className="mr-2" /> Send Message</Button>
+ </div>
+ </form>
+ )}
+ </div>
+ </TabsContent>
+ </Tabs>
+
+ {/* Create Group Modal */}
+ {showGroupModal && (
+ <div className="modal-overlay" onClick={() => setShowGroupModal(false)}>
+ <div className="modal" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h2>Create Queue Group</h2>
+ <button className="modal-close" onClick={() => setShowGroupModal(false)}>&times;</button>
+ </div>
+ <form onSubmit={handleCreateGroup}>
+ <div className="modal-body">
+ <div className="form-group">
+ <Label htmlFor="group-slug">Slug</Label>
+ <Input id="group-slug" value={groupForm.slug} onChange={(e) => setGroupForm({ ...groupForm, slug: e.target.value })} required />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="group-name">Name</Label>
+ <Input id="group-name" value={groupForm.name} onChange={(e) => setGroupForm({ ...groupForm, name: e.target.value })} required />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="group-description">Description</Label>
+ <Input id="group-description" value={groupForm.description} onChange={(e) => setGroupForm({ ...groupForm, description: e.target.value })} />
+ </div>
+ </div>
+ <div className="modal-footer">
+ <Button type="button" variant="outline" onClick={() => setShowGroupModal(false)}>Cancel</Button>
+ <Button type="submit">Create Group</Button>
+ </div>
+ </form>
+ </div>
+ </div>
+ )}
+
+ {/* Create Queue Modal */}
+ {showQueueModal && (
+ <div className="modal-overlay" onClick={() => setShowQueueModal(false)}>
+ <div className="modal" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h2>Create Queue</h2>
+ <button className="modal-close" onClick={() => setShowQueueModal(false)}>&times;</button>
+ </div>
+ <form onSubmit={handleCreateQueue}>
+ <div className="modal-body">
+ <div className="form-group">
+ <Label htmlFor="queue-slug">Slug</Label>
+ <Input id="queue-slug" value={queueForm.slug} onChange={(e) => setQueueForm({ ...queueForm, slug: e.target.value })} required />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="queue-name">Name</Label>
+ <Input id="queue-name" value={queueForm.name} onChange={(e) => setQueueForm({ ...queueForm, name: e.target.value })} required />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="queue-description">Description</Label>
+ <Input id="queue-description" value={queueForm.description} onChange={(e) => setQueueForm({ ...queueForm, description: e.target.value })} />
+ </div>
+ <div className="form-group">
+ <Label htmlFor="queue-config">Config (JSON)</Label>
+ <Textarea id="queue-config" value={queueForm.config} onChange={(e) => setQueueForm({ ...queueForm, config: e.target.value })} rows={4} />
+ </div>
+ </div>
+ <div className="modal-footer">
+ <Button type="button" variant="outline" onClick={() => setShowQueueModal(false)}>Cancel</Button>
+ <Button type="submit">Create Queue</Button>
+ </div>
+ </form>
+ </div>
+ </div>
+ )}
+
+ {/* Message Detail Modal */}
+ {selectedMessage && (
+ <div className="modal-overlay" onClick={() => setSelectedMessage(null)}>
+ <div className="modal modal--wide" onClick={e => e.stopPropagation()}>
+ <div className="modal-header">
+ <h2>Message Detail</h2>
+ <button className="modal-close" onClick={() => setSelectedMessage(null)}>&times;</button>
+ </div>
+ <div className="modal-body">
+ <div className="queue-message-detail">
+ <div><strong>ID:</strong> <code>{selectedMessage.id}</code></div>
+ <div><strong>Status:</strong> <Pill kind={STATUS_KINDS[selectedMessage.status] || 'gray'}>{selectedMessage.status}</Pill></div>
+ <div><strong>Attempts:</strong> {selectedMessage.attempts} / {selectedMessage.max_attempts}</div>
+ <div><strong>Created:</strong> {new Date(selectedMessage.created_at).toLocaleString()}</div>
+ {selectedMessage.error_message && (
+ <div className="queue-message-error"><strong>Error:</strong> {selectedMessage.error_message}</div>
+ )}
+ <div className="queue-message-section"><strong>Payload:</strong>
+ <pre>{JSON.stringify(selectedMessage.payload, null, 2)}</pre>
+ </div>
+ {selectedMessage.result && (
+ <div className="queue-message-section"><strong>Result:</strong>
+ <pre>{JSON.stringify(selectedMessage.result, null, 2)}</pre>
+ </div>
+ )}
+ </div>
+ </div>
+ <div className="modal-footer">
+ <Button type="button" variant="outline" onClick={() => setSelectedMessage(null)}>Close</Button>
+ {(selectedMessage.status === 'failed' || selectedMessage.status === 'dead_letter') && (
+ <Button onClick={() => { handleRequeueMessage(selectedMessage); setSelectedMessage(null); }}>Requeue</Button>
+ )}
+ </div>
+ </div>
+ </div>
+ )}
+
+ <ConfirmDialog
+ isOpen={confirmState.isOpen}
+ title={confirmState.title}
+ message={confirmState.message}
+ confirmText={confirmState.confirmText}
+ cancelText={confirmState.cancelText}
+ variant={confirmState.variant}
+ onConfirm={handleConfirm}
+ onCancel={handleCancel}
+ />
+ </div>
+ );
+};
+
+export default QueueOperations;
diff --git a/frontend/src/services/api/index.js b/frontend/src/services/api/index.js
index 9651d93b..9ef1833c 100644
--- a/frontend/src/services/api/index.js
+++ b/frontend/src/services/api/index.js
@@ -18,6 +18,7 @@ import * as aiMethods from './ai.js';
import * as tunnelMethods from './tunnels.js';
import * as secretsWebhooksMethods from './secretsWebhooks.js';
import * as containerOpsMethods from './containerOps.js';
+import * as queueBusMethods from './queueBus.js';
class ApiService extends ApiClient {
constructor() {
@@ -43,6 +44,7 @@ class ApiService extends ApiClient {
tunnelMethods,
secretsWebhooksMethods,
containerOpsMethods,
+ queueBusMethods,
];
for (const mod of modules) {
for (const [key, fn] of Object.entries(mod)) {
diff --git a/frontend/src/services/api/queueBus.js b/frontend/src/services/api/queueBus.js
new file mode 100644
index 00000000..96958db6
--- /dev/null
+++ b/frontend/src/services/api/queueBus.js
@@ -0,0 +1,120 @@
+// Queue Bus API methods
+
+export async function getQueueGroups(params = {}) {
+ const query = new URLSearchParams();
+ if (params.owner_type) query.append('owner_type', params.owner_type);
+ if (params.owner_id) query.append('owner_id', params.owner_id);
+ if (params.limit) query.append('limit', params.limit);
+ if (params.offset) query.append('offset', params.offset);
+ const suffix = query.toString() ? `?${query}` : '';
+ return this.request(`/queue/groups${suffix}`);
+}
+
+export async function createQueueGroup(data) {
+ return this.request('/queue/groups', { method: 'POST', body: JSON.stringify(data) });
+}
+
+export async function getQueueGroup(groupSlug) {
+ return this.request(`/queue/groups/${groupSlug}`);
+}
+
+export async function updateQueueGroup(groupSlug, data) {
+ return this.request(`/queue/groups/${groupSlug}`, { method: 'PATCH', body: JSON.stringify(data) });
+}
+
+export async function deleteQueueGroup(groupSlug) {
+ return this.request(`/queue/groups/${groupSlug}`, { method: 'DELETE' });
+}
+
+export async function getQueues(groupSlug, params = {}) {
+ const query = new URLSearchParams();
+ if (params.limit) query.append('limit', params.limit);
+ if (params.offset) query.append('offset', params.offset);
+ const suffix = query.toString() ? `?${query}` : '';
+ return this.request(`/queue/groups/${groupSlug}/queues${suffix}`);
+}
+
+export async function createQueue(groupSlug, data) {
+ return this.request(`/queue/groups/${groupSlug}/queues`, { method: 'POST', body: JSON.stringify(data) });
+}
+
+export async function getQueue(groupSlug, queueSlug) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}`);
+}
+
+export async function updateQueue(groupSlug, queueSlug, data) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}`, { method: 'PATCH', body: JSON.stringify(data) });
+}
+
+export async function deleteQueue(groupSlug, queueSlug) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}`, { method: 'DELETE' });
+}
+
+export async function getMessages(groupSlug, queueSlug, params = {}) {
+ const query = new URLSearchParams();
+ if (params.status) query.append('status', params.status);
+ if (params.limit) query.append('limit', params.limit);
+ if (params.offset) query.append('offset', params.offset);
+ const suffix = query.toString() ? `?${query}` : '';
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages${suffix}`);
+}
+
+export async function sendMessage(groupSlug, queueSlug, payload, options = {}) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages`, {
+ method: 'POST',
+ body: JSON.stringify({
+ payload,
+ priority: options.priority ?? 0,
+ delay_ms: options.delay_ms ?? 0,
+ max_attempts: options.max_attempts,
+ }),
+ });
+}
+
+export async function receiveMessages(groupSlug, queueSlug, options = {}) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/receive`, {
+ method: 'POST',
+ body: JSON.stringify({
+ visibility_timeout_ms: options.visibility_timeout_ms ?? 30000,
+ max_messages: options.max_messages ?? 1,
+ }),
+ });
+}
+
+export async function getMessage(groupSlug, queueSlug, messageId) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/${messageId}`);
+}
+
+export async function completeMessage(groupSlug, queueSlug, messageId) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/${messageId}/complete`, { method: 'POST' });
+}
+
+export async function failMessage(groupSlug, queueSlug, messageId, options = {}) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/${messageId}/fail`, {
+ method: 'POST',
+ body: JSON.stringify({
+ error_message: options.error_message,
+ requeue: options.requeue ?? false,
+ }),
+ });
+}
+
+export async function requeueMessage(groupSlug, queueSlug, messageId) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/${messageId}/requeue`, { method: 'POST' });
+}
+
+export async function deleteMessage(groupSlug, queueSlug, messageId) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/messages/${messageId}`, { method: 'DELETE' });
+}
+
+export async function getQueueStats(groupSlug, queueSlug) {
+ return this.request(`/queue/groups/${groupSlug}/queues/${queueSlug}/stats`);
+}
+
+export async function getGroupStats(groupSlug) {
+ return this.request(`/queue/groups/${groupSlug}/stats`);
+}
+
+export async function getGlobalQueueStats() {
+ return this.request('/queue/stats');
+}
diff --git a/frontend/src/styles/main.scss b/frontend/src/styles/main.scss
index d07e5c42..8f09da0c 100644
--- a/frontend/src/styles/main.scss
+++ b/frontend/src/styles/main.scss
@@ -116,3 +116,4 @@
@import 'pages/_secrets';
@import 'pages/_gpu';
@import 'pages/_dynamic-dns';
+@import 'pages/_queue-operations';
diff --git a/frontend/src/styles/pages/_queue-operations.scss b/frontend/src/styles/pages/_queue-operations.scss
new file mode 100644
index 00000000..4214d4a1
--- /dev/null
+++ b/frontend/src/styles/pages/_queue-operations.scss
@@ -0,0 +1,223 @@
+.queue-operations-page {
+ .queue-kpis {
+ display: grid;
+ grid-template-columns: repeat(4, 1fr);
+ gap: $space-4;
+ margin-bottom: $space-5;
+
+ @media (max-width: $breakpoint-md) {
+ grid-template-columns: repeat(2, 1fr);
+ }
+ }
+
+ .queue-tabs {
+ margin-top: $space-4;
+ }
+
+ .queue-tab-content {
+ margin-top: $space-4;
+ }
+
+ .queue-listhead {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ margin-bottom: $space-4;
+
+ h2 {
+ flex: 1;
+ margin: 0;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ font-weight: $font-weight-semibold;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--text-faint);
+ }
+ }
+
+ .queue-table {
+ width: 100%;
+
+ code {
+ font-size: $font-size-xs;
+ color: var(--text-secondary);
+ }
+ }
+
+ .queue-group-tree {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+ }
+
+ .queue-group-card {
+ background: var(--surface);
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ overflow: hidden;
+ }
+
+ .queue-group-header {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ padding: $space-4;
+ cursor: pointer;
+ transition: background 0.15s ease;
+
+ &:hover {
+ background: var(--bg-hover);
+ }
+
+ .queue-group-name {
+ font-weight: $font-weight-semibold;
+ color: var(--text-primary);
+ }
+
+ .queue-group-slug {
+ color: var(--text-tertiary);
+ font-size: $font-size-sm;
+ font-family: var(--mono);
+ }
+
+ .queue-group-meta {
+ margin-left: auto;
+ font-size: $font-size-sm;
+ color: var(--text-secondary);
+ }
+ }
+
+ .queue-group-queues {
+ border-top: 1px solid var(--border-soft);
+ }
+
+ .queue-group-queue {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ padding: $space-3 $space-4 $space-3 $space-8;
+ cursor: pointer;
+ transition: background 0.15s ease;
+
+ &:hover {
+ background: var(--bg-hover);
+ }
+
+ &-stats {
+ font-size: $font-size-sm;
+ color: var(--text-tertiary);
+ font-family: var(--mono);
+ }
+
+ &-empty {
+ padding: $space-4 $space-4 $space-4 $space-8;
+ color: var(--text-tertiary);
+ font-size: $font-size-sm;
+ }
+ }
+
+ .queue-messages-toolbar {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ margin-bottom: $space-4;
+ flex-wrap: wrap;
+ }
+
+ .queue-messages-selects {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ flex-wrap: wrap;
+ }
+
+ .queue-messages-actions {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ }
+
+ .queue-select {
+ background: var(--surface);
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ padding: $space-2 $space-3;
+ color: var(--text-primary);
+ font-size: $font-size-sm;
+ min-width: 160px;
+
+ &:disabled {
+ opacity: 0.5;
+ cursor: not-allowed;
+ }
+ }
+
+ .queue-payload-preview {
+ display: inline-block;
+ max-width: 300px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ .queue-actions {
+ display: flex;
+ align-items: center;
+ gap: $space-1;
+ }
+
+ .queue-send-card {
+ background: var(--surface);
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ padding: $space-5;
+ }
+
+ .queue-send-form {
+ display: flex;
+ flex-direction: column;
+ gap: $space-4;
+
+ .form-row {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: $space-4;
+ }
+
+ .form-actions {
+ display: flex;
+ justify-content: flex-end;
+ margin-top: $space-2;
+ }
+ }
+
+ .queue-message-detail {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+
+ pre {
+ background: var(--bg-elevated);
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ padding: $space-3;
+ overflow: auto;
+ font-size: $font-size-sm;
+ max-height: 300px;
+ }
+ }
+
+ .queue-message-error {
+ color: var(--danger);
+ background: var(--danger-bg);
+ border: 1px solid var(--danger-border);
+ border-radius: var(--radius);
+ padding: $space-3;
+ }
+
+ .queue-message-section {
+ margin-top: $space-2;
+ }
+}