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(realtime): declarative channel registry; dead pipeline_* retired (plan 77 E2)
Juan Denisc8a5d3a39c85
diff --git a/backend/app/sockets.py b/backend/app/sockets.pyindex dcf5c581..838fcfed 100644--- a/backend/app/sockets.py+++ b/backend/app/sockets.py@@ -23,9 +23,6 @@ container_status_subscribers = set()# Store active container log streamscontainer_log_streams = {} # sid -> {'process': Popen, 'app_id': int, 'thread': Thread, 'stop_event': Event}-# Store active pipeline subscriptions-pipeline_subscribers = {} # sid -> set of project_ids-# Authenticated identity per connected client. Populated at connect time# (after the JWT is verified AND the user is confirmed active) and read by# the room/subscription handlers to make authorization decisions. Without@@ -56,6 +53,101 @@ def _client_is_privileged(sid):return _client_role(sid) in _PRIVILEGED_ROLES+# ==================== DECLARATIVE CHANNEL REGISTRY (plan 77 E2) ====================+#+# Eight hand-rolled subscribe/unsubscribe pairs used four different registry+# shapes and re-checked auth inconsistently. register_channel() generates the+# pair with ONE auth model:+# 1. the socket must be in connected_clients (JWT verified at connect);+# 2. an optional per-channel `auth(sid, data)` gate returning an error+# string (e.g. the terminal role gate) — None means allowed.+# Room names come from room_fn (built on app/sockets_rooms.py); channels with+# process-wide side effects (subscriber sets, broadcast loops) use+# on_subscribe/on_unsubscribe. The two remaining raw handlers+# (subscribe_logs / subscribe_container_logs, which own per-sid OS resources)+# are frozen by tests/test_socket_contract.py.+++class ChannelError(Exception):+ """Raised by a room_fn to reject a subscribe with a client-visible message."""+++CHANNELS = {}+++def register_channel(name, *, room_fn=None, auth=None, on_subscribe=None,+ on_unsubscribe=None, ack=None, ack_unsubscribe=True):+ """Register `subscribe_<name>` / `unsubscribe_<name>` handlers.++ Args:+ name: channel name; also the default ack payload's `channel` value.+ room_fn: callable(data) -> room name to join/leave (may raise+ ChannelError). None for broadcast channels with no room.+ auth: callable(sid, data) -> error string or None.+ on_subscribe / on_unsubscribe: callable(sid, data) side effects.+ ack: callable(data) -> extra dict merged into the subscribed /+ unsubscribed payloads.+ ack_unsubscribe: emit the `unsubscribed` ack (a couple of legacy+ channels never did — keep their wire behavior).+ """+ def _payload(data):+ payload = {'channel': name}+ if ack:+ payload.update(ack(data))+ return payload++ def _subscribe(data=None):+ data = data or {}+ sid = request.sid+ if sid not in connected_clients:+ emit('error', {'message': 'Authentication required'})+ return+ if auth:+ error = auth(sid, data)+ if error:+ emit('error', {'message': error})+ return+ room = None+ if room_fn:+ try:+ room = room_fn(data)+ except ChannelError as exc:+ emit('error', {'message': str(exc)})+ return+ if room:+ join_room(room)+ if on_subscribe:+ on_subscribe(sid, data)+ emit('subscribed', _payload(data))++ def _unsubscribe(data=None):+ data = data or {}+ sid = request.sid+ if room_fn:+ try:+ room = room_fn(data)+ except ChannelError:+ room = None+ if room:+ leave_room(room)+ if on_unsubscribe:+ on_unsubscribe(sid, data)+ if ack_unsubscribe:+ emit('unsubscribed', _payload(data))++ # Handlers are exposed on the registry so the contract tests can drive+ # them directly (the flask-socketio test client is incompatible with the+ # pinned Flask's immutable request context).+ CHANNELS[name] = {+ 'room_fn': room_fn,+ 'auth': auth,+ 'subscribe': _subscribe,+ 'unsubscribe': _unsubscribe,+ }+ socketio.on_event(f'subscribe_{name}', _subscribe)+ socketio.on_event(f'unsubscribe_{name}', _unsubscribe)++def init_socketio(app):"""Initialize SocketIO with the Flask app."""socketio.init_app(@@ -130,9 +222,6 @@ def handle_disconnect():# Stop any container log streams for this clientstop_container_log_stream(sid)- # Remove from pipeline subscribers- pipeline_subscribers.pop(sid, None)-# Drop the authenticated-identity record for this socket.with _connected_clients_lock:connected_clients.pop(sid, None)@@ -151,21 +240,20 @@ metrics_loop = BackgroundLoop()[email protected]('subscribe_metrics')-def handle_subscribe_metrics():- """Subscribe to real-time system metrics."""- metric_subscribers.add(request.sid)+def _metrics_on_subscribe(sid, data):+ metric_subscribers.add(sid)metrics_loop.start()- emit('subscribed', {'channel': 'metrics'})[email protected]('unsubscribe_metrics')-def handle_unsubscribe_metrics():- """Unsubscribe from system metrics."""- sid = request.sid- if sid in metric_subscribers:- metric_subscribers.remove(sid)- emit('unsubscribed', {'channel': 'metrics'})+def _metrics_on_unsubscribe(sid, data):+ metric_subscribers.discard(sid)+++register_channel(+ 'metrics',+ on_subscribe=_metrics_on_subscribe,+ on_unsubscribe=_metrics_on_unsubscribe,+)# ==================== AGGREGATED CONTAINER STATUS ====================@@ -191,75 +279,54 @@ container_status_loop = BackgroundLoop()[email protected]('subscribe_container_status')-def handle_subscribe_container_status():- """Subscribe to aggregated container-status change events.-- Mirrors the metrics pattern: one background loop polls the aggregator and- broadcasts ONLY the apps whose status changed since the last tick- (channel 'container_status'). Clients reconcile by app_id.- """- container_status_subscribers.add(request.sid)+def _container_status_on_subscribe(sid, data):+ container_status_subscribers.add(sid)container_status_loop.start(app=current_app._get_current_object())- emit('subscribed', {'channel': 'container_status'})--[email protected]('unsubscribe_container_status')-def handle_unsubscribe_container_status():- """Unsubscribe from aggregated container-status events."""- sid = request.sid- if sid in container_status_subscribers:- container_status_subscribers.remove(sid)- emit('unsubscribed', {'channel': 'container_status'})[email protected]('subscribe_terminal')-def handle_subscribe_terminal(data):- """Join the stream room for a remote terminal session (agent PTY output).+def _container_status_on_unsubscribe(sid, data):+ container_status_subscribers.discard(sid)- The agent streams base64 PTY output on channel `terminal:<session_id>`;- the agent gateway rebroadcasts it as `server_stream` events into the room- `server_<server_id>_terminal:<session_id>`. This handler is what lets a- browser join that room — without it the output never reaches the UI.- Session ids are unguessable uuids minted by TerminalService for the- authenticated creator.- """- from app.services.terminal_service import TerminalService- # Attaching to a live PTY stream exposes everything typed and printed in- # that shell (often running as root on the agent host). Creating a terminal- # is @developer_required on the REST side, so observing one must demand the- # same role — otherwise a read-only viewer could join the stream room and- # watch a privileged session.- if not _client_is_privileged(request.sid):- emit('error', {'message': 'Developer role required for terminal access'})- return+register_channel(+ 'container_status',+ on_subscribe=_container_status_on_subscribe,+ on_unsubscribe=_container_status_on_unsubscribe,+)- session_id = (data or {}).get('session_id')- if not session_id:- emit('error', {'message': 'session_id required'})- return- session = TerminalService.get_session(session_id)- if not session:- emit('error', {'message': 'Unknown terminal session'})- return+# Remote terminal streams (agent PTY output). The agent streams base64 PTY+# output on channel `terminal:<session_id>`; the gateway rebroadcasts it as+# `server_stream` events into server_<id>_terminal:<session_id>. Attaching+# exposes everything typed/printed in that shell (often root on the agent+# host); creating a terminal is @developer_required on the REST side, so+# observing one demands the same role. Session ids are unguessable uuids+# minted by TerminalService for the authenticated creator.- join_room(rooms.server_terminal_room(session['server_id'], session_id))- emit('subscribed', {'channel': f'terminal:{session_id}'})+def _terminal_auth(sid, data):+ if not _client_is_privileged(sid):+ return 'Developer role required for terminal access'+ return None[email protected]('unsubscribe_terminal')-def handle_unsubscribe_terminal(data):- """Leave a terminal session's stream room."""+def _terminal_room(data):from app.services.terminal_service import TerminalService-- session_id = (data or {}).get('session_id')+ session_id = data.get('session_id')if not session_id:- return+ raise ChannelError('session_id required')session = TerminalService.get_session(session_id)- if session:- leave_room(rooms.server_terminal_room(session['server_id'], session_id))+ if not session:+ raise ChannelError('Unknown terminal session')+ return rooms.server_terminal_room(session['server_id'], session_id)+++register_channel(+ 'terminal',+ room_fn=_terminal_room,+ auth=_terminal_auth,+ ack=lambda data: {'channel': f"terminal:{data.get('session_id')}"},+ ack_unsubscribe=False, # the legacy handler never acked the leave+)@socketio.on('subscribe_logs')@@ -344,36 +411,22 @@ def handle_leave_room(data):# on top of the `GET /deployment-jobs/<id>/logs?after_id=` polling endpoint —# the console stays 100% functional with sockets disabled (D2).[email protected]('subscribe_deploy')-def handle_subscribe_deploy(data):- """Subscribe to live Deploy Console updates for a deployment job.-- Auth mirrors the read API (D3/§8): any authenticated user may watch — job- ids are unguessable UUIDs and the REST read endpoint exposes them the same- way. The connect handler already verified the JWT and recorded identity in- `connected_clients`; a socket missing from that set is not authenticated.- """- sid = request.sid- if sid not in connected_clients:- emit('error', {'message': 'Authentication required'})- return+# Deploy Console: any authenticated user may watch (mirrors the read API —+# job ids are unguessable UUIDs and the REST read endpoint exposes them the+# same way).- job_id = (data or {}).get('job_id')+def _deploy_room(data):+ job_id = data.get('job_id')if not job_id:- emit('error', {'message': 'job_id required'})- return-- join_room(rooms.deploy_room(job_id))- emit('subscribed', {'channel': 'deploy', 'job_id': job_id})+ raise ChannelError('job_id required')+ return rooms.deploy_room(job_id)[email protected]('unsubscribe_deploy')-def handle_unsubscribe_deploy(data=None):- """Leave a deployment job's live room."""- job_id = (data or {}).get('job_id')- if job_id:- leave_room(rooms.deploy_room(job_id))- emit('unsubscribed', {'channel': 'deploy', 'job_id': job_id})+register_channel(+ 'deploy',+ room_fn=_deploy_room,+ ack=lambda data: {'job_id': data.get('job_id')},+)def emit_deploy_log(job_id: str, lines: list):@@ -615,72 +668,3 @@ def emit_container_log(app_id: int, line: str, level: str = 'info'):},'timestamp': time.time()}, room=rooms.app_logs_room(app_id))---# ==================== PIPELINE EVENT STREAMING ====================-[email protected]('subscribe_pipeline')-def handle_subscribe_pipeline(data):- """Subscribe to real-time pipeline events for a WordPress project.-- data: {- 'project_id': int (production site ID)- }-- Emits 'pipeline_event' with:- - project_id: int- - event: string (e.g. 'promotion_started', 'sync_completed')- - data: dict with event-specific details- - timestamp: float- """- sid = request.sid- project_id = data.get('project_id')-- if not project_id:- emit('error', {'message': 'project_id required'})- return-- room = f'pipeline_{project_id}'- join_room(room)-- if sid not in pipeline_subscribers:- pipeline_subscribers[sid] = set()- pipeline_subscribers[sid].add(project_id)-- emit('subscribed', {'channel': 'pipeline', 'project_id': project_id})--[email protected]('unsubscribe_pipeline')-def handle_unsubscribe_pipeline(data):- """Unsubscribe from pipeline events for a project."""- sid = request.sid- project_id = data.get('project_id')-- if project_id:- leave_room(f'pipeline_{project_id}')- if sid in pipeline_subscribers:- pipeline_subscribers[sid].discard(project_id)- if not pipeline_subscribers[sid]:- del pipeline_subscribers[sid]-- emit('unsubscribed', {'channel': 'pipeline', 'project_id': project_id})---def emit_pipeline_event(project_id: int, event: str, data: dict = None):- """Emit a pipeline event to all subscribers of a project.-- Called from EnvironmentPipelineService or API endpoints to notify- the frontend about long-running operations (promote, sync, create).-- Args:- project_id: Production site ID- event: Event type (e.g. 'promotion_started', 'sync_completed',- 'environment_created', 'environment_deleted')- data: Event-specific payload- """- socketio.emit('pipeline_event', {- 'project_id': project_id,- 'event': event,- 'data': data or {},- 'timestamp': time.time()- }, room=f'pipeline_{project_id}')diff --git a/backend/tests/test_channel_registry.py b/backend/tests/test_channel_registry.pynew file mode 100644index 00000000..e18b877e--- /dev/null+++ b/backend/tests/test_channel_registry.py@@ -0,0 +1,113 @@+"""Plan 77 E2 — the declarative channel registry: one auth model, per-channel gates.++Drives the generated handlers directly (the flask-socketio test client is+incompatible with the pinned Flask), with emit/join_room patched and the+authenticated-identity map seeded like the connect handler would.+"""+import re+from pathlib import Path++import pytest++import app.sockets as sk+from app import db+from factories import make_user++BACKEND = Path(__file__).resolve().parents[1]+++def wire(app, monkeypatch):+ """Patch the socket wire functions; returns the captured event list."""+ events = []+ monkeypatch.setattr(sk, 'emit', lambda name, payload=None, **k: events.append((name, payload)))+ monkeypatch.setattr(sk, 'join_room', lambda room: events.append(('__join__', room)))+ monkeypatch.setattr(sk, 'leave_room', lambda room: events.append(('__leave__', room)))+ yield events+ sk.metric_subscribers.clear()+ with sk._connected_clients_lock:+ sk.connected_clients.clear()+++def _run(app, handler, data=None, sid='sid-1'):+ with app.test_request_context('/'):+ from flask import request+ request.sid = sid+ handler(data)+++def _authed(sid='sid-1', role='developer'):+ with sk._connected_clients_lock:+ sk.connected_clients[sid] = {'user_id': 1, 'role': role}+++def test_registered_channels_exist(app):+ assert {'metrics', 'container_status', 'terminal', 'deploy'} <= set(sk.CHANNELS)+++def test_unauthenticated_socket_is_rejected_on_every_channel(app, wire):+ for name, spec in sk.CHANNELS.items():+ wire.clear()+ _run(app, spec['subscribe'], {}, sid='ghost')+ assert wire and wire[0] == ('error', {'message': 'Authentication required'}), name+++def test_metrics_subscribe_ack_and_state(app, wire, monkeypatch):+ # Don't actually start the broadcast thread in tests.+ monkeypatch.setattr(sk.metrics_loop, 'start', lambda *a, **k: True)+ _authed()+ _run(app, sk.CHANNELS['metrics']['subscribe'])+ assert ('subscribed', {'channel': 'metrics'}) in wire+ assert 'sid-1' in sk.metric_subscribers++ wire.clear()+ _run(app, sk.CHANNELS['metrics']['unsubscribe'])+ assert ('unsubscribed', {'channel': 'metrics'}) in wire+ assert 'sid-1' not in sk.metric_subscribers+++def test_deploy_requires_job_id_then_joins_room(app, wire):+ _authed()+ _run(app, sk.CHANNELS['deploy']['subscribe'], {})+ assert ('error', {'message': 'job_id required'}) in wire++ wire.clear()+ _run(app, sk.CHANNELS['deploy']['subscribe'], {'job_id': 'job-1'})+ assert ('__join__', 'deploy_job-1') in wire+ assert ('subscribed', {'channel': 'deploy', 'job_id': 'job-1'}) in wire+++def test_terminal_gate_rejects_viewer(app, wire):+ _authed(role='viewer')+ _run(app, sk.CHANNELS['terminal']['subscribe'], {'session_id': 'whatever'})+ assert wire == [('error', {'message': 'Developer role required for terminal access'})]+++def test_terminal_unknown_session_for_developer(app, wire):+ _authed(role='developer')+ _run(app, sk.CHANNELS['terminal']['subscribe'], {'session_id': 'nope'})+ assert wire == [('error', {'message': 'Unknown terminal session'})]+++def test_terminal_unsubscribe_does_not_ack(app, wire):+ """The legacy handler never acked the leave; the registry preserves that."""+ _authed(role='developer')+ _run(app, sk.CHANNELS['terminal']['unsubscribe'], {'session_id': 'nope'})+ assert wire == [] # no leave (unknown session), no ack+++def test_generic_join_room_still_gates_terminal_rooms(app, wire):+ _authed(role='viewer')+ _run(app, sk.handle_join_room, {'room': 'server_s1_terminal:sess'})+ assert wire == [('error', {'message': 'Developer role required for terminal access'})]+++def test_raw_subscribe_handlers_are_frozen():+ """Ratchet: new channels go through register_channel, not raw handlers."""+ src = (BACKEND / 'app' / 'sockets.py').read_text(encoding='utf-8')+ raw = set(re.findall(r"@socketio\.on\('subscribe_(\w+)'\)", src))+ assert raw == {'logs', 'container_logs'}, (+ f'Raw subscribe handlers changed: {sorted(raw)}. New channels must use '+ 'register_channel() (plan 77 E2); the two legacy handlers own per-sid '+ 'OS resources and are frozen until they migrate.'+ )