ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
refactor(webhooks): move subscription use cases behind service boundary
Juan Denisb24c0938545b
diff --git a/backend/app/api/event_subscriptions.py b/backend/app/api/event_subscriptions.pyindex c510e878..f228bf62 100644--- a/backend/app/api/event_subscriptions.py+++ b/backend/app/api/event_subscriptions.py@@ -1,74 +1,39 @@-"""Webhook event subscription endpoints."""-from flask import Blueprint, jsonify, request-from flask_jwt_extended import jwt_required, get_jwt_identity-from app.middleware.rbac import get_current_user, auth_required-from app.models.event_subscription import EventSubscription+"""Webhook event-subscription HTTP boundary."""++from flask import Blueprint, jsonify++from app.api.contracts import api_contract+from app.api.schemas.event_subscriptions import (+ CreateEventSubscriptionSchema,+ DeliveryListQuerySchema,+ UpdateEventSubscriptionSchema,+)+from app.middleware.rbac import (+ auth_required,+ developer_required,+ get_current_user,+)+from app.services import event_subscription_servicefrom app.services.event_service import EventService-from app import db+event_subscriptions_bp = Blueprint('event_subscriptions', __name__)@event_subscriptions_bp.route('/', methods=['GET'])-@jwt_required()+@developer_requireddef list_subscriptions():- """List webhook subscriptions."""- user = get_current_user()- if not user or not user.is_developer:- return jsonify({'error': 'Developer access required'}), 403-- if user.is_admin:- subs = EventSubscription.query.order_by(EventSubscription.created_at.desc()).all()- else:- subs = EventSubscription.query.filter_by(user_id=user.id).order_by(- EventSubscription.created_at.desc()- ).all()-- return jsonify({'subscriptions': [s.to_dict() for s in subs]})+ """List webhook subscriptions visible to the caller."""+ subscriptions = event_subscription_service.list_for_user(get_current_user())+ return jsonify({'subscriptions': [item.to_dict() for item in subscriptions]})@event_subscriptions_bp.route('/', methods=['POST'])-@jwt_required()-def create_subscription():+@developer_required+@api_contract(body=CreateEventSubscriptionSchema)+def create_subscription(body):"""Create a new webhook subscription."""- user = get_current_user()- if not user or not user.is_developer:- return jsonify({'error': 'Developer access required'}), 403-- data = request.get_json() or {}- name = data.get('name')- url = data.get('url')- events = data.get('events', [])-- if not name or not url:- return jsonify({'error': 'Name and URL are required'}), 400- if not events:- return jsonify({'error': 'At least one event type is required'}), 400-- sub = EventSubscription(- user_id=user.id,- name=name,- url=url,- retry_count=data.get('retry_count', 3),- timeout_seconds=data.get('timeout_seconds', 10),- )- sub.set_events(events)-- if data.get('generate_secret', True):- sub.secret = EventSubscription.generate_secret()-- custom_headers = data.get('headers')- if custom_headers:- sub.set_headers(custom_headers)-- db.session.add(sub)- db.session.commit()-- result = sub.to_dict()- # Expose secret once at creation- if sub.secret:- result['secret'] = sub.secret-+ result = event_subscription_service.create(get_current_user(), body)return jsonify(result), 201@@ -80,149 +45,70 @@ def list_events():@event_subscriptions_bp.route('/<int:sub_id>', methods=['GET'])-@jwt_required()+@auth_required()def get_subscription(sub_id):"""Get subscription details."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- return jsonify(sub.to_dict())+ subscription = event_subscription_service.get_for_user(+ get_current_user(), sub_id+ )+ return jsonify(subscription.to_dict())@event_subscriptions_bp.route('/<int:sub_id>', methods=['PUT'])-@jwt_required()-def update_subscription(sub_id):+@auth_required()+@api_contract(body=UpdateEventSubscriptionSchema)+def update_subscription(sub_id, body):"""Update a webhook subscription."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- data = request.get_json() or {}-- if 'name' in data:- sub.name = data['name']- if 'url' in data:- sub.url = data['url']- if 'events' in data:- sub.set_events(data['events'])- if 'is_active' in data:- sub.is_active = data['is_active']- if 'headers' in data:- sub.set_headers(data['headers'])- if 'retry_count' in data:- sub.retry_count = data['retry_count']- if 'timeout_seconds' in data:- sub.timeout_seconds = data['timeout_seconds']-- db.session.commit()- return jsonify(sub.to_dict())+ subscription = event_subscription_service.update(+ get_current_user(), sub_id, body+ )+ return jsonify(subscription.to_dict())@event_subscriptions_bp.route('/<int:sub_id>', methods=['DELETE'])-@jwt_required()+@auth_required()def delete_subscription(sub_id):"""Delete a webhook subscription."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- db.session.delete(sub)- db.session.commit()+ event_subscription_service.delete(get_current_user(), sub_id)return jsonify({'message': 'Subscription deleted'})@event_subscriptions_bp.route('/<int:sub_id>/test', methods=['POST'])-@jwt_required()+@auth_required()def test_subscription(sub_id):- """Send a test event to a subscription."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- delivery = EventService.send_test(sub_id)- if not delivery:- return jsonify({'error': 'Failed to send test'}), 500-+ """Queue a test event for a subscription."""+ delivery = event_subscription_service.send_test(get_current_user(), sub_id)return jsonify(delivery.to_dict())@event_subscriptions_bp.route('/<int:sub_id>/deliveries', methods=['GET'])-@jwt_required()-def list_deliveries(sub_id):+@auth_required()+@api_contract(query=DeliveryListQuerySchema)+def list_deliveries(sub_id, query):"""Get delivery history for a subscription."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- page = request.args.get('page', 1, type=int)- per_page = request.args.get('per_page', 50, type=int)-- pagination = EventService.get_deliveries(sub_id, page, per_page)+ pagination = event_subscription_service.list_deliveries(+ get_current_user(),+ sub_id,+ page=query['page'],+ per_page=query['per_page'],+ )return jsonify({- 'deliveries': [d.to_dict() for d in pagination.items],+ 'deliveries': [delivery.to_dict() for delivery in pagination.items],'total': pagination.total,- 'page': page,- 'per_page': per_page,+ 'page': query['page'],+ 'per_page': query['per_page'],'pages': pagination.pages,})-@event_subscriptions_bp.route('/<int:sub_id>/deliveries/<int:delivery_id>/retry', methods=['POST'])-@jwt_required()+@event_subscriptions_bp.route(+ '/<int:sub_id>/deliveries/<int:delivery_id>/retry',+ methods=['POST'],+)+@auth_required()def retry_delivery(sub_id, delivery_id):- """Retry a failed delivery."""- user = get_current_user()- if not user:- return jsonify({'error': 'User not found'}), 404-- sub = EventSubscription.query.get(sub_id)- if not sub:- return jsonify({'error': 'Subscription not found'}), 404- if not user.is_admin and sub.user_id != user.id:- return jsonify({'error': 'Access denied'}), 403-- from app.models.event_subscription import EventDelivery- delivery = EventDelivery.query.filter_by(id=delivery_id, subscription_id=sub_id).first()- if not delivery:- return jsonify({'error': 'Delivery not found'}), 404-- delivery.status = EventDelivery.STATUS_PENDING- delivery.next_retry_at = None- db.session.commit()-- EventService.deliver(delivery_id)-- # Refresh- delivery = EventDelivery.query.get(delivery_id)+ """Reset and enqueue a failed delivery."""+ delivery = event_subscription_service.retry_delivery(+ get_current_user(), sub_id, delivery_id+ )return jsonify(delivery.to_dict())diff --git a/backend/app/api/schemas/event_subscriptions.py b/backend/app/api/schemas/event_subscriptions.pynew file mode 100644index 00000000..f3ab9e56--- /dev/null+++ b/backend/app/api/schemas/event_subscriptions.py@@ -0,0 +1,43 @@+"""Request contracts for event-subscription management."""++from marshmallow import fields, validate++from app.api.contracts import ApiSchema+++class CreateEventSubscriptionSchema(ApiSchema):+ name = fields.String(required=True, validate=validate.Length(min=1, max=100))+ url = fields.String(required=True, validate=validate.Length(min=1, max=2048))+ events = fields.List(+ fields.String(validate=validate.Length(min=1, max=100)),+ required=True,+ validate=validate.Length(min=1),+ )+ retry_count = fields.Integer(load_default=3, validate=validate.Range(min=0, max=20))+ timeout_seconds = fields.Integer(+ load_default=10,+ validate=validate.Range(min=1, max=300),+ )+ generate_secret = fields.Boolean(load_default=True)+ headers = fields.Dict(load_default=None, allow_none=True)+++class UpdateEventSubscriptionSchema(ApiSchema):+ name = fields.String(validate=validate.Length(min=1, max=100))+ url = fields.String(validate=validate.Length(min=1, max=2048))+ events = fields.List(+ fields.String(validate=validate.Length(min=1, max=100)),+ validate=validate.Length(min=1),+ )+ is_active = fields.Boolean()+ retry_count = fields.Integer(validate=validate.Range(min=0, max=20))+ timeout_seconds = fields.Integer(validate=validate.Range(min=1, max=300))+ headers = fields.Dict(allow_none=True)+++class DeliveryListQuerySchema(ApiSchema):+ page = fields.Integer(load_default=1, validate=validate.Range(min=1))+ per_page = fields.Integer(+ load_default=50,+ validate=validate.Range(min=1, max=200),+ )diff --git a/backend/app/services/event_service.py b/backend/app/services/event_service.pyindex 070e0ffd..edc651bf 100644--- a/backend/app/services/event_service.py+++ b/backend/app/services/event_service.py@@ -7,6 +7,7 @@ from app import dbfrom app.models.event_subscription import EventSubscription, EventDeliveryfrom app.queue_bus.consumers.webhook_consumer import enqueue_webhook_deliveryfrom app.services.telemetry_service import generate_correlation_id+from app.services.unit_of_work import unit_of_worklogger = logging.getLogger(__name__)@@ -248,6 +249,21 @@ class EventService:EventDelivery.created_at.desc()).paginate(page=page, per_page=per_page, error_out=False)+ @staticmethod+ def retry_delivery(delivery):+ """Reset a delivery atomically, then enqueue it after commit."""+ with unit_of_work():+ delivery.status = EventDelivery.STATUS_PENDING+ delivery.next_retry_at = None++ try:+ enqueue_webhook_delivery(delivery.id)+ except Exception as exc:+ # The durable pending row remains retryable by the queue sweep.+ logger.error('Failed to enqueue delivery retry %s: %s', delivery.id, exc)+ db.session.refresh(delivery)+ return delivery+@staticmethoddef cleanup_old_deliveries(days=30):"""Purge old delivery records."""@@ -256,4 +272,3 @@ class EventService:db.session.commit()return deleted-diff --git a/backend/app/services/event_subscription_service.py b/backend/app/services/event_subscription_service.pynew file mode 100644index 00000000..4a367779--- /dev/null+++ b/backend/app/services/event_subscription_service.py@@ -0,0 +1,119 @@+"""Use cases for user-owned webhook event subscriptions."""++from app import db+from app.exceptions import (+ AuthenticationError,+ NotFoundError,+ PermissionDeniedError,+ ValidationError,+)+from app.models.event_subscription import EventDelivery, EventSubscription+from app.services.event_service import EventService+from app.services.unit_of_work import unit_of_work+++def _require_user(user):+ if user is None:+ raise AuthenticationError()+ return user+++def get_for_user(user, subscription_id):+ """Resolve one subscription and apply its ownership policy once."""++ user = _require_user(user)+ subscription = db.session.get(EventSubscription, subscription_id)+ if subscription is None:+ raise NotFoundError(+ 'Subscription not found', code='event_subscription_not_found'+ )+ if not user.is_admin and subscription.user_id != user.id:+ raise PermissionDeniedError()+ return subscription+++def list_for_user(user):+ user = _require_user(user)+ if not user.is_developer:+ raise PermissionDeniedError('Developer access required')+ query = EventSubscription.query+ if not user.is_admin:+ query = query.filter_by(user_id=user.id)+ return query.order_by(EventSubscription.created_at.desc()).all()+++def create(user, data):+ user = _require_user(user)+ if not user.is_developer:+ raise PermissionDeniedError('Developer access required')+ if not data.get('name') or not data.get('url'):+ raise ValidationError('Name and URL are required')+ if not data.get('events'):+ raise ValidationError('At least one event type is required')++ subscription = EventSubscription(+ user_id=user.id,+ name=data['name'],+ url=data['url'],+ retry_count=data.get('retry_count', 3),+ timeout_seconds=data.get('timeout_seconds', 10),+ )+ subscription.set_events(data['events'])+ if data.get('generate_secret', True):+ subscription.secret = EventSubscription.generate_secret()+ if data.get('headers'):+ subscription.set_headers(data['headers'])++ with unit_of_work() as session:+ session.add(subscription)++ result = subscription.to_dict()+ if subscription.secret:+ result['secret'] = subscription.secret+ return result+++def update(user, subscription_id, data):+ subscription = get_for_user(user, subscription_id)+ scalar_fields = (+ 'name', 'url', 'is_active', 'retry_count', 'timeout_seconds',+ )+ with unit_of_work():+ for field in scalar_fields:+ if field in data:+ setattr(subscription, field, data[field])+ if 'events' in data:+ subscription.set_events(data['events'])+ if 'headers' in data:+ subscription.set_headers(data['headers'])+ return subscription+++def delete(user, subscription_id):+ subscription = get_for_user(user, subscription_id)+ with unit_of_work() as session:+ session.delete(subscription)+++def send_test(user, subscription_id):+ subscription = get_for_user(user, subscription_id)+ delivery = EventService.send_test(subscription.id)+ if delivery is None:+ raise NotFoundError('Subscription not found')+ return delivery+++def list_deliveries(user, subscription_id, *, page, per_page):+ subscription = get_for_user(user, subscription_id)+ return EventService.get_deliveries(subscription.id, page, per_page)+++def retry_delivery(user, subscription_id, delivery_id):+ subscription = get_for_user(user, subscription_id)+ delivery = EventDelivery.query.filter_by(+ id=delivery_id,+ subscription_id=subscription.id,+ ).first()+ if delivery is None:+ raise NotFoundError('Delivery not found', code='event_delivery_not_found')+ return EventService.retry_delivery(delivery)diff --git a/backend/app/services/unit_of_work.py b/backend/app/services/unit_of_work.pynew file mode 100644index 00000000..d2583014--- /dev/null+++ b/backend/app/services/unit_of_work.py@@ -0,0 +1,23 @@+"""Small transaction boundary for top-level service use cases."""++from contextlib import contextmanager++from app import db+++@contextmanager+def unit_of_work(session=None):+ """Commit one use case atomically and always roll back a failed attempt.++ Lower-level helpers called inside this context may flush, but must not+ commit. External side effects belong after the context so a remote call is+ never mistaken for part of the database transaction.+ """++ active_session = session if session is not None else db.session+ try:+ yield active_session+ active_session.commit()+ except Exception:+ active_session.rollback()+ raisediff --git a/backend/tests/test_event_subscriptions.py b/backend/tests/test_event_subscriptions.pynew file mode 100644index 00000000..ac90f285--- /dev/null+++ b/backend/tests/test_event_subscriptions.py@@ -0,0 +1,170 @@+"""Event-subscription use-case and HTTP-boundary tests."""++import ast+from pathlib import Path++from flask_jwt_extended import create_access_token+from werkzeug.security import generate_password_hash+++def _developer_headers(db, username):+ from app.models import User++ user = User(+ email=f'{username}@test.local',+ username=username,+ password_hash=generate_password_hash('testpass'),+ role=User.ROLE_DEVELOPER,+ is_active=True,+ )+ db.session.add(user)+ db.session.commit()+ return user, {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}+++def _create(client, headers, name='Deploy hook'):+ return client.post('/api/v1/event-subscriptions/', headers=headers, json={+ 'name': name,+ 'url': 'https://hooks.example.test/serverkit',+ 'events': ['app.deployed'],+ 'generate_secret': True,+ })+++def test_subscription_crud_uses_typed_boundary(client, auth_headers):+ created_response = _create(client, auth_headers)+ assert created_response.status_code == 201+ created = created_response.get_json()+ assert created['name'] == 'Deploy hook'+ assert created['secret'].startswith('whsec_')++ listed = client.get(+ '/api/v1/event-subscriptions/', headers=auth_headers+ ).get_json()['subscriptions']+ assert [item['id'] for item in listed] == [created['id']]+ assert 'secret' not in listed[0]++ updated_response = client.put(+ f"/api/v1/event-subscriptions/{created['id']}",+ headers=auth_headers,+ json={'name': 'Release hook', 'retry_count': 5},+ )+ assert updated_response.status_code == 200+ assert updated_response.get_json()['name'] == 'Release hook'+ assert updated_response.get_json()['retry_count'] == 5++ deleted = client.delete(+ f"/api/v1/event-subscriptions/{created['id']}", headers=auth_headers+ )+ assert deleted.status_code == 200++ missing = client.get(+ f"/api/v1/event-subscriptions/{created['id']}", headers=auth_headers+ )+ assert missing.status_code == 404+ assert missing.get_json()['code'] == 'event_subscription_not_found'+++def test_subscription_schema_rejects_unknown_and_invalid_fields(+ client, auth_headers,+):+ response = client.post(+ '/api/v1/event-subscriptions/',+ headers={**auth_headers, 'X-Request-ID': 'subscription-contract'},+ json={+ 'name': 'Hook',+ 'url': 'https://hooks.example.test/serverkit',+ 'events': [],+ 'surprise': True,+ },+ )++ assert response.status_code == 400+ payload = response.get_json()+ assert payload['code'] == 'invalid_body'+ assert payload['request_id'] == 'subscription-contract'+ assert set(payload['details']['fields']) == {'events', 'surprise'}+++def test_non_owner_cannot_read_or_mutate_subscription(client, app):+ from app import db++ owner, owner_headers = _developer_headers(db, 'hook_owner')+ _other, other_headers = _developer_headers(db, 'hook_other')+ created = _create(client, owner_headers, name='Private hook').get_json()++ for method, path, kwargs in (+ ('get', f"/api/v1/event-subscriptions/{created['id']}", {}),+ ('put', f"/api/v1/event-subscriptions/{created['id']}", {+ 'json': {'name': 'Stolen'},+ }),+ ('delete', f"/api/v1/event-subscriptions/{created['id']}", {}),+ ):+ response = getattr(client, method)(path, headers=other_headers, **kwargs)+ assert response.status_code == 403+ assert response.get_json()['code'] == 'permission_denied'++ listed = client.get(+ '/api/v1/event-subscriptions/', headers=other_headers+ ).get_json()['subscriptions']+ assert listed == []+ assert owner.id == created['user_id']+++def test_retry_commits_pending_state_before_enqueue(+ client, auth_headers, monkeypatch,+):+ from app import db+ from app.models.event_subscription import EventDelivery+ from app.services import event_service++ subscription = _create(client, auth_headers).get_json()+ delivery = EventDelivery(+ subscription_id=subscription['id'],+ event_type='app.deployed',+ status=EventDelivery.STATUS_FAILED,+ next_retry_at=None,+ )+ db.session.add(delivery)+ db.session.commit()++ observed = []++ def capture(delivery_id):+ row = db.session.get(EventDelivery, delivery_id)+ observed.append((row.id, row.status))++ monkeypatch.setattr(event_service, 'enqueue_webhook_delivery', capture)+ response = client.post(+ f"/api/v1/event-subscriptions/{subscription['id']}"+ f'/deliveries/{delivery.id}/retry',+ headers=auth_headers,+ )++ assert response.status_code == 200+ assert response.get_json()['status'] == EventDelivery.STATUS_PENDING+ assert observed == [(delivery.id, EventDelivery.STATUS_PENDING)]+++def test_event_subscription_routes_do_not_own_persistence():+ path = (+ Path(__file__).resolve().parents[1]+ / 'app' / 'api' / 'event_subscriptions.py'+ )+ tree = ast.parse(path.read_text(encoding='utf-8'))++ imported_names = {+ alias.name+ for node in ast.walk(tree)+ if isinstance(node, ast.ImportFrom)+ for alias in node.names+ }+ session_calls = [+ node+ for node in ast.walk(tree)+ if isinstance(node, ast.Attribute) and node.attr == 'session'+ ]++ assert 'EventSubscription' not in imported_names+ assert 'EventDelivery' not in imported_names+ assert session_calls == []diff --git a/backend/tests/test_unit_of_work.py b/backend/tests/test_unit_of_work.pynew file mode 100644index 00000000..91f0febb--- /dev/null+++ b/backend/tests/test_unit_of_work.py@@ -0,0 +1,53 @@+"""Transaction ownership contract for top-level service use cases."""++import pytest++from app.services.unit_of_work import unit_of_work+++class FakeSession:+ def __init__(self):+ self.commits = 0+ self.rollbacks = 0++ def commit(self):+ self.commits += 1++ def rollback(self):+ self.rollbacks += 1+++def test_unit_of_work_commits_once_after_success():+ session = FakeSession()++ with unit_of_work(session):+ pass++ assert session.commits == 1+ assert session.rollbacks == 0+++def test_unit_of_work_rolls_back_and_preserves_original_failure():+ session = FakeSession()++ with pytest.raises(RuntimeError, match='operation failed'):+ with unit_of_work(session):+ raise RuntimeError('operation failed')++ assert session.commits == 0+ assert session.rollbacks == 1+++def test_unit_of_work_rolls_back_a_failed_commit():+ class FailedCommitSession(FakeSession):+ def commit(self):+ super().commit()+ raise RuntimeError('commit failed')++ session = FailedCommitSession()+ with pytest.raises(RuntimeError, match='commit failed'):+ with unit_of_work(session):+ pass++ assert session.commits == 1+ assert session.rollbacks == 1