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.

fix(plugins): hot-load extension blueprints on a live app (#144)

Juan Denis0aea7e37875a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc70771d..b55c5ca2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,13 @@ release history; historical `agent-v*` tags are not panel releases.
`/opt`, so the Log Files tab could read — or clear — the backend `.env`
and database. The log viewer now shares the file manager's protected-roots
exclusion.
+- Make extension hot-load work on a live panel. Flask refuses to register a
+ blueprint once the app has served its first request, so an extension
+ installed on a running panel had no API routes until a restart — its pages
+ loaded, but every call failed, with POSTs surfacing as a 405 (the Malware
+ Scanner custom-path scan, #144). Blueprint registration now waives Flask's
+ setup guard for the duration of the call, which is safe in the panel's
+ single-worker threaded deployment.
## [1.11.4] - 2026-09-12
diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.py
index 8ebb3843..89b390dc 100644
--- a/backend/app/services/plugin_service.py
+++ b/backend/app/services/plugin_service.py
@@ -1324,6 +1324,33 @@ def _register_extra_blueprints(register, plugin, manifest):
+ (f' (as {name})' if name else ''))
+def _register_blueprint_live(app, bp, **options):
+ """Register a blueprint on an app that may already be serving requests.
+
+ Flask refuses setup calls once the app has handled its first request
+ (``AssertionError: The setup method 'register_blueprint' can no longer be
+ called...``), so on any live panel — where login and dashboard requests
+ long precede the first extension install — hot-load always failed and the
+ plugin's routes stayed missing until a restart: unmatched POSTs then fell
+ through to the static route and surfaced as a 405 (#144).
+
+ Late registration is safe in this deployment shape: the panel runs a
+ single gunicorn worker with threads (the process installing the plugin is
+ the process serving its routes), and werkzeug rebuilds its URL matcher
+ lazily on the next bind while in-flight requests keep the matcher they
+ already bound. Temporarily clearing the flag only waives Flask's setup
+ guard; it does not touch request state.
+ """
+ if not app._got_first_request:
+ app.register_blueprint(bp, **options)
+ return
+ app._got_first_request = False
+ try:
+ app.register_blueprint(bp, **options)
+ finally:
+ app._got_first_request = True
+
+
def _register_plugin_blueprint(plugin):
"""Dynamically register a plugin's Flask blueprint into the running app."""
from flask import current_app
@@ -1344,10 +1371,12 @@ def _register_plugin_blueprint(plugin):
mod = importlib.import_module(full_module)
bp = getattr(mod, bp_name)
_attach_status_guard(bp, plugin.slug)
- current_app.register_blueprint(bp, url_prefix=plugin.url_prefix)
+ _register_blueprint_live(
+ current_app, bp, url_prefix=plugin.url_prefix)
logger.info(f'Registered blueprint {bp_name} at {plugin.url_prefix}')
_register_extra_blueprints(
- current_app.register_blueprint, plugin, plugin.manifest or {})
+ lambda bp, **opts: _register_blueprint_live(current_app, bp, **opts),
+ plugin, plugin.manifest or {})
except Exception as e:
raise ValueError(f'Failed to register blueprint: {e}')
diff --git a/backend/tests/test_plugins_pipeline.py b/backend/tests/test_plugins_pipeline.py
index f0beb697..dad8bdd0 100644
--- a/backend/tests/test_plugins_pipeline.py
+++ b/backend/tests/test_plugins_pipeline.py
@@ -548,3 +548,65 @@ def test_repair_leaves_intact_installs_alone(app, plugin_dirs, monkeypatch):
plugin_service.repair_missing_plugins()
db.session.refresh(plugin)
assert plugin.status == InstalledPlugin.STATUS_ACTIVE
+
+
+# --------------------------------------------------------------------------- #
+# Hot-load on a live app (#144): install must work after the first request
+# --------------------------------------------------------------------------- #
+
+def test_blueprint_registers_after_first_request(app):
+ """Flask refuses register_blueprint once the app has served a request, and
+ on a live panel that is always the case by the time anyone installs an
+ extension — login and dashboard requests come first. The failed hot-load
+ used to leave the plugin's routes missing until a restart, and an
+ unmatched POST (e.g. the malware scanner's custom-path scan) fell through
+ to the static-file route and surfaced as a 405."""
+ from flask import Blueprint, jsonify
+
+ c = app.test_client()
+ c.get('/') # flip _got_first_request — the state every live panel is in
+
+ bp = Blueprint('live_reg_bp', __name__)
+
+ @bp.route('/ping', methods=['POST'])
+ def ping():
+ return jsonify({'ok': True})
+
+ plugin_service._register_blueprint_live(
+ app, bp, url_prefix='/api/v1/live-reg')
+
+ resp = c.post('/api/v1/live-reg/ping')
+ assert resp.status_code == 200
+ assert resp.get_json() == {'ok': True}
+
+
+def test_register_blueprint_live_preserves_first_request_flag(app):
+ """The setup guard is waived only for the registration call itself."""
+ from flask import Blueprint
+
+ c = app.test_client()
+ c.get('/')
+ assert app._got_first_request is True
+
+ bp = Blueprint('live_reg_flag_bp', __name__)
+ plugin_service._register_blueprint_live(
+ app, bp, url_prefix='/api/v1/live-flag')
+
+ assert app._got_first_request is True
+
+
+def test_register_blueprint_live_on_fresh_app(app):
+ """The no-op branch: an app that has not served a request yet registers
+ through the plain path."""
+ from flask import Blueprint, jsonify
+
+ bp = Blueprint('live_reg_fresh_bp', __name__)
+
+ @bp.route('/ping')
+ def ping():
+ return jsonify({'ok': True})
+
+ plugin_service._register_blueprint_live(
+ app, bp, url_prefix='/api/v1/live-fresh')
+
+ assert app.test_client().get('/api/v1/live-fresh/ping').status_code == 200