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.

refactor(realtime): declarative channel registry; dead pipeline_* retired (plan 77 E2)

Juan Denisc8a5d3a39c85
diff --git a/backend/app/sockets.py b/backend/app/sockets.py
index 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 streams
container_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 client
stop_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.py
new file mode 100644
index 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.'
+ )