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: share backend lifecycle and fleet metrics operations

Juan Denisf490d75bee2c
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index e2fe5b85..c23840f1 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -21,11 +21,13 @@ from app.services.source_connection_service import SourceConnectionService
from app.services.remote_docker_service import RemoteDockerService
from app.services.container_registry_service import ContainerRegistryService
from app.services.image_update_service import ImageUpdateService
-from app.services import container_status_service
+from app.services import container_status_service, application_lifecycle_service
+from app.services.application_lifecycle_service import (
+ _compose_target, _local_compose_file, _agent_result_failed,
+ _agent_result_error, _assert_managed_app_path,
+)
from app.services.container_sleep_service import ContainerSleepService
from app.services.container_scale_service import ContainerScaleService
-from app.services.unit_compose_service import UnitComposeService
-from app.services.app_port_service import AppPortService
from app.services.log_service import LogService
from app.services.process_service import ProcessService
from app.services.backup_policy_service import BackupPolicyService, BackupPolicyError
@@ -48,18 +50,6 @@ from app.middleware.rbac import get_current_user, require_admin_user
apps_bp = Blueprint('apps', __name__)
-def _compose_target(app):
- """Return the effective compose file path for remote agent deployments."""
- if app.server_id and app.root_path:
- return os.path.join(app.root_path, app.compose_file or 'docker-compose.yml')
- return os.path.join(app.root_path, app.compose_file or 'docker-compose.yml') if app.root_path else None
-
-
-def _local_compose_file(app):
- """Return the compose file to pass to DockerService for local deployments."""
- return app.compose_file if app.compose_file else None
-
-
def _remove_data_flag(app):
"""Should ``DELETE /apps/<id>`` take the data volumes down with the app?
@@ -99,18 +89,6 @@ def _sync_manual_app_status(app):
db.session.commit()
-def _agent_result_failed(result):
- data = result.get('data') if isinstance(result, dict) else None
- return isinstance(data, dict) and data.get('success') is False
-
-
-def _agent_result_error(result, fallback):
- data = result.get('data') if isinstance(result, dict) else None
- if isinstance(data, dict):
- return data.get('error') or result.get('error') or fallback
- return result.get('error') or fallback
-
-
def _service_slug(value):
return slugify(value)
@@ -129,91 +107,6 @@ def _derive_repo_app_type(detection):
return 'static'
-def _assert_managed_app_path(app_name):
- base_dir = os.path.abspath(paths.APPS_DIR)
- app_path = os.path.abspath(os.path.join(base_dir, app_name))
- if app_path != base_dir and app_path.startswith(base_dir + os.sep):
- return app_path
- raise ValueError('Invalid application path')
-
-
-def _is_single_container_app(app):
- """True when this app's deploy produced one container, not a compose project.
-
- ``app_type == 'docker'`` is not the same as "compose-managed". The build
- pack deploys by building an image and running a single container
- (``DeploymentService._deploy_docker``, named ``serverkit-app-<id>``) and
- nothing in that path ever writes a compose file, so ``compose_file`` stays
- NULL. Handing that directory to ``docker compose`` fails with "no
- configuration file provided: not found" -- which is what start, stop and
- restart did for every build-pack app.
-
- Deliberately narrow, and phrased as a positive test rather than "has no
- compose file": compose stays the default for everything, including an app
- whose compose file has not been rendered yet. Only a local build-pack app
- with no compose file recorded and none on disk takes the container path.
- """
- if app.server_id or app.compose_file or not app.root_path:
- return False
- if not app.buildpack_type:
- return False
- return not any(
- os.path.isfile(os.path.join(app.root_path, name))
- for name in ('docker-compose.yml', 'docker-compose.yaml',
- 'compose.yml', 'compose.yaml')
- )
-
-
-def _app_container_name(app):
- """The single container a build-pack deploy creates for this app.
-
- Must match ``DeploymentService._deploy_docker``, which names it
- ``serverkit-app-<id>``.
- """
- return f'serverkit-app-{app.id}'
-
-
-def _ensure_local_image_compose(app):
- """Materialize a compose project for a local docker app that carries a
- ``docker_image`` but has no source on disk yet.
-
- A BYO-image app (e.g. an ``image:`` manifest service with no repository)
- is created with ``docker_image`` set but ``root_path``/``compose_file``
- NULL, so it has nothing to launch. Render a one-service compose from the
- image and its typed ports, write it under APPS_DIR, and persist the paths;
- the normal ``compose_up`` overlay then injects the app's effective env
- (including resolved vault secrets), so nothing sensitive is written here.
-
- No-op when a source already exists, the app has no image, or it targets a
- remote server (the file must live where the deploy actually runs).
- """
- if app.root_path or not app.docker_image or app.server_id:
- return
- app_path = _assert_managed_app_path(app.name)
- os.makedirs(app_path, exist_ok=True)
-
- container = {'name': 'app', 'image': app.docker_image}
- ports = AppPortService.get_ports(app)
- if not ports and app.port:
- # Bind the legacy scalar port to loopback — nginx fronts it; publishing
- # 0.0.0.0 (AppPortService._clean's default) would expose it past nginx.
- ports = [{'host_port': app.port, 'container_port': app.port, 'expose': 'local'}]
- if ports:
- container['ports'] = ports
- if app.healthcheck_path:
- container['health_check'] = {'http_path': app.healthcheck_path}
-
- compose_yaml = UnitComposeService.render_yaml(app.name, [container])
- with open(os.path.join(app_path, 'docker-compose.yml'), 'w') as f:
- f.write(compose_yaml)
-
- app.root_path = app_path
- app.compose_file = 'docker-compose.yml'
- if not app.managed_by:
- app.managed_by = 'docker_compose'
- db.session.commit()
-
-
def _safe_repo_url(repo_url):
return re.sub(r'^(https?://)[^@]+@', r'\1', repo_url or '')
@@ -1544,51 +1437,10 @@ def start_app(app_id):
if not _can_edit_app(user, app):
return jsonify({'error': 'Access denied'}), 403
- # A local BYO-image docker app (image set, no source yet) has no compose to
- # launch — materialize one on first start so it can actually run.
- if app.app_type == 'docker' and not app.root_path and app.docker_image and not app.server_id:
- try:
- _ensure_local_image_compose(app)
- except ValueError as e:
- return jsonify({'error': str(e)}), 400
-
- # Handle Docker apps
- if app.app_type == 'docker' and app.root_path:
- if app.server_id:
- result = RemoteDockerService.compose_up(
- app.server_id,
- _compose_target(app),
- detach=True,
- user_id=current_user_id
- )
- elif _is_single_container_app(app):
- # Build-pack app: one container, created by the deploy.
- container = _app_container_name(app)
- if not DockerService.get_container(container):
- return jsonify({'error': 'This application has not been deployed yet. '
- 'Run a deploy to build its image and create '
- 'the container.'}), 400
- result = DockerService.start_container(container)
- else:
- # Authenticate a bound private registry before compose pulls the
- # image; best-effort, always logs back out. No-op without registry_id.
- _registry = ContainerRegistryService.login_for_app(app)
- try:
- result = DockerService.compose_up(
- app.root_path,
- detach=True,
- compose_file=_local_compose_file(app)
- )
- finally:
- ContainerRegistryService.logout_for_app(_registry)
- if not result.get('success') or _agent_result_failed(result):
- return jsonify({'error': _agent_result_error(result, 'Failed to start containers')}), 400
-
- app.status = 'running'
- db.session.commit()
- # The cached aggregate now describes the pre-start world. Drop it: a status
- # pill that survives the action that changed it reads as a broken panel.
- container_status_service.invalidate(app_id)
+ try:
+ application_lifecycle_service.start_application(app, user_id=current_user_id)
+ except application_lifecycle_service.ApplicationLifecycleError as exc:
+ return jsonify({'error': str(exc)}), 400
return jsonify({
'message': 'Application started',
@@ -1997,31 +1849,10 @@ def stop_app(app_id):
if not _can_edit_app(user, app):
return jsonify({'error': 'Access denied'}), 403
- # Handle Docker apps
- if app.app_type == 'docker' and app.root_path:
- if app.server_id:
- result = RemoteDockerService.compose_down(
- app.server_id,
- _compose_target(app),
- user_id=current_user_id
- )
- elif _is_single_container_app(app):
- # A container that no longer exists is already stopped -- reporting
- # that as a failure would strand the app in `running` forever.
- container = _app_container_name(app)
- result = ({'success': True} if not DockerService.get_container(container)
- else DockerService.stop_container(container))
- else:
- result = DockerService.compose_down(
- app.root_path,
- compose_file=_local_compose_file(app)
- )
- if not result.get('success') or _agent_result_failed(result):
- return jsonify({'error': _agent_result_error(result, 'Failed to stop containers')}), 400
-
- app.status = 'stopped'
- db.session.commit()
- container_status_service.invalidate(app_id)
+ try:
+ application_lifecycle_service.stop_application(app, user_id=current_user_id)
+ except application_lifecycle_service.ApplicationLifecycleError as exc:
+ return jsonify({'error': str(exc)}), 400
return jsonify({
'message': 'Application stopped',
@@ -2042,32 +1873,10 @@ def restart_app(app_id):
if not _can_edit_app(user, app):
return jsonify({'error': 'Access denied'}), 403
- # Handle Docker apps
- if app.app_type == 'docker' and app.root_path:
- if app.server_id:
- result = RemoteDockerService.compose_restart(
- app.server_id,
- _compose_target(app),
- user_id=current_user_id
- )
- elif _is_single_container_app(app):
- container = _app_container_name(app)
- if not DockerService.get_container(container):
- return jsonify({'error': 'This application has not been deployed yet. '
- 'Run a deploy to build its image and create '
- 'the container.'}), 400
- result = DockerService.restart_container(container)
- else:
- result = DockerService.compose_restart(
- app.root_path,
- compose_file=_local_compose_file(app)
- )
- if not result.get('success') or _agent_result_failed(result):
- return jsonify({'error': _agent_result_error(result, 'Failed to restart containers')}), 400
-
- app.status = 'running'
- db.session.commit()
- container_status_service.invalidate(app_id)
+ try:
+ application_lifecycle_service.restart_application(app, user_id=current_user_id)
+ except application_lifecycle_service.ApplicationLifecycleError as exc:
+ return jsonify({'error': str(exc)}), 400
return jsonify({
'message': 'Application restarted',
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index 0a4ee3cf..d8cda7a6 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -15,6 +15,7 @@ from flask_jwt_extended import jwt_required, get_jwt_identity
from sqlalchemy.orm import joinedload
from app import db, limiter
+from app.services.server_metrics_service import latest_metrics_by_server
from app.api._query import apply_query, QueryParseError
from app.models import User
from app.models.server import Server, ServerGroup, ServerMetrics, ServerCommand, AgentSession, AgentVersion, AgentRollout
@@ -301,25 +302,10 @@ def list_servers():
servers = (query.all() if request.args.get('$orderby')
else query.order_by(Server.name).all())
- # Latest metrics per server, under the SAME 'metrics' key the detail
- # endpoint uses (see get_server_status below) — the servers list renders
- # CPU/Memory/Disk gauges from it, and without it every one of those cells
- # fell back to the "no data" dash on a live panel.
- #
- # Batched deliberately: `server.metrics` is lazy='dynamic', so doing this
- # per row inside the loop would be one extra SELECT per server. Newest row
- # per server = highest id, because the id autoincrements on insert — that
- # also avoids the tie a max(timestamp) join would hit for same-second rows.
- metrics_by_server = {}
- if servers:
- server_ids = [s.id for s in servers]
- newest = (
- db.session.query(db.func.max(ServerMetrics.id))
- .filter(ServerMetrics.server_id.in_(server_ids))
- .group_by(ServerMetrics.server_id)
- )
- for row in ServerMetrics.query.filter(ServerMetrics.id.in_(newest)).all():
- metrics_by_server[row.server_id] = row.to_dict()
+ # Keep the list's insertion-order contract; monitoring uses sample time.
+ metrics_by_server = latest_metrics_by_server(
+ (server.id for server in servers), order_by='id',
+ )
result = []
for server in servers:
@@ -327,7 +313,7 @@ def list_servers():
server_dict['is_connected'] = agent_registry.is_agent_connected(server.id)
metrics = metrics_by_server.get(server.id)
if metrics:
- server_dict['metrics'] = metrics
+ server_dict['metrics'] = metrics.to_dict()
result.append(server_dict)
return jsonify(result)
@@ -930,7 +916,8 @@ def compare_server_metrics():
@jwt_required()
def get_servers_overview():
"""Get overview of all servers health"""
- servers = Server.query.all()
+ servers = Server.query.options(joinedload(Server.group)).all()
+ metrics_by_server = latest_metrics_by_server(server.id for server in servers)
connected_ids = set(agent_registry.get_connected_servers())
total = len(servers)
@@ -945,7 +932,7 @@ def get_servers_overview():
is_online = server.id in connected_ids
# Get latest metrics
- latest = server.metrics.order_by(ServerMetrics.timestamp.desc()).first()
+ latest = metrics_by_server.get(server.id)
server_summary = {
'id': server.id,
diff --git a/backend/app/services/application_lifecycle_service.py b/backend/app/services/application_lifecycle_service.py
new file mode 100644
index 00000000..955c6e8a
--- /dev/null
+++ b/backend/app/services/application_lifecycle_service.py
@@ -0,0 +1,244 @@
+"""Application start/stop/restart operations for HTTP, jobs and automation.
+
+Callers authorize access before entering this service. Successful operations
+commit their status then invalidate container aggregates; a rejected runtime
+operation leaves both untouched. Image materialization retains its separate
+commit so a failed first start can be retried using the saved compose project.
+"""
+
+import os
+
+from app import db, paths
+from app.services.docker_service import DockerService
+from app.services.remote_docker_service import RemoteDockerService
+from app.services.container_registry_service import ContainerRegistryService
+from app.services.unit_compose_service import UnitComposeService
+from app.services.app_port_service import AppPortService
+from app.services import container_status_service
+
+
+class ApplicationLifecycleError(Exception):
+ """An operation rejected by the runtime, safe to present to the caller."""
+
+
+def _compose_target(app):
+ """Return the effective compose file path for remote agent deployments."""
+ return os.path.join(app.root_path, app.compose_file or 'docker-compose.yml') if app.root_path else None
+
+
+def _local_compose_file(app):
+ """Return the compose file to pass to DockerService for local deployments."""
+ return app.compose_file if app.compose_file else None
+
+
+def _agent_result_failed(result):
+ data = result.get('data') if isinstance(result, dict) else None
+ return isinstance(data, dict) and data.get('success') is False
+
+
+def _agent_result_error(result, fallback):
+ data = result.get('data') if isinstance(result, dict) else None
+ if isinstance(data, dict):
+ return data.get('error') or result.get('error') or fallback
+ return result.get('error') or fallback
+
+
+def _assert_managed_app_path(app_name):
+ base_dir = os.path.abspath(paths.APPS_DIR)
+ app_path = os.path.abspath(os.path.join(base_dir, app_name))
+ if app_path != base_dir and app_path.startswith(base_dir + os.sep):
+ return app_path
+ raise ValueError('Invalid application path')
+
+
+def _is_single_container_app(app):
+ """True when this app's deploy produced one container, not a compose project.
+
+ ``app_type == 'docker'`` is not the same as "compose-managed". The build
+ pack deploys by building an image and running a single container
+ (``DeploymentService._deploy_docker``, named ``serverkit-app-<id>``) and
+ nothing in that path ever writes a compose file, so ``compose_file`` stays
+ NULL. Handing that directory to ``docker compose`` fails with "no
+ configuration file provided: not found" -- which is what start, stop and
+ restart did for every build-pack app.
+
+ Deliberately narrow, and phrased as a positive test rather than "has no
+ compose file": compose stays the default for everything, including an app
+ whose compose file has not been rendered yet. Only a local build-pack app
+ with no compose file recorded and none on disk takes the container path.
+ """
+ if app.server_id or app.compose_file or not app.root_path:
+ return False
+ if not app.buildpack_type:
+ return False
+ return not any(
+ os.path.isfile(os.path.join(app.root_path, name))
+ for name in ('docker-compose.yml', 'docker-compose.yaml',
+ 'compose.yml', 'compose.yaml')
+ )
+
+
+def _app_container_name(app):
+ """The single container a build-pack deploy creates for this app.
+
+ Must match ``DeploymentService._deploy_docker``, which names it
+ ``serverkit-app-<id>``.
+ """
+ return f'serverkit-app-{app.id}'
+
+
+def _ensure_local_image_compose(app):
+ """Materialize a compose project for a local docker app that carries a
+ ``docker_image`` but has no source on disk yet.
+
+ A BYO-image app (e.g. an ``image:`` manifest service with no repository)
+ is created with ``docker_image`` set but ``root_path``/``compose_file``
+ NULL, so it has nothing to launch. Render a one-service compose from the
+ image and its typed ports, write it under APPS_DIR, and persist the paths;
+ the normal ``compose_up`` overlay then injects the app's effective env
+ (including resolved vault secrets), so nothing sensitive is written here.
+
+ No-op when a source already exists, the app has no image, or it targets a
+ remote server (the file must live where the deploy actually runs).
+ """
+ if app.root_path or not app.docker_image or app.server_id:
+ return
+ app_path = _assert_managed_app_path(app.name)
+ os.makedirs(app_path, exist_ok=True)
+
+ container = {'name': 'app', 'image': app.docker_image}
+ ports = AppPortService.get_ports(app)
+ if not ports and app.port:
+ # Bind the legacy scalar port to loopback — nginx fronts it; publishing
+ # 0.0.0.0 (AppPortService._clean's default) would expose it past nginx.
+ ports = [{'host_port': app.port, 'container_port': app.port, 'expose': 'local'}]
+ if ports:
+ container['ports'] = ports
+ if app.healthcheck_path:
+ container['health_check'] = {'http_path': app.healthcheck_path}
+
+ compose_yaml = UnitComposeService.render_yaml(app.name, [container])
+ with open(os.path.join(app_path, 'docker-compose.yml'), 'w') as f:
+ f.write(compose_yaml)
+
+ app.root_path = app_path
+ app.compose_file = 'docker-compose.yml'
+ if not app.managed_by:
+ app.managed_by = 'docker_compose'
+ db.session.commit()
+
+
+def start_application(app, *, user_id=None):
+ """Start the configured runtime, materializing local image apps if needed."""
+ # A local BYO-image docker app (image set, no source yet) has no compose to
+ # launch — materialize one on first start so it can actually run.
+ if app.app_type == 'docker' and not app.root_path and app.docker_image and not app.server_id:
+ try:
+ _ensure_local_image_compose(app)
+ except ValueError as e:
+ raise ApplicationLifecycleError(str(e)) from e
+
+ # Handle Docker apps
+ if app.app_type == 'docker' and app.root_path:
+ if app.server_id:
+ result = RemoteDockerService.compose_up(
+ app.server_id,
+ _compose_target(app),
+ detach=True,
+ user_id=user_id
+ )
+ elif _is_single_container_app(app):
+ # Build-pack app: one container, created by the deploy.
+ container = _app_container_name(app)
+ if not DockerService.get_container(container):
+ raise ApplicationLifecycleError(
+ 'This application has not been deployed yet. '
+ 'Run a deploy to build its image and create the container.'
+ )
+ result = DockerService.start_container(container)
+ else:
+ # Authenticate a bound private registry before compose pulls the
+ # image; best-effort, always logs back out. No-op without registry_id.
+ _registry = ContainerRegistryService.login_for_app(app)
+ try:
+ result = DockerService.compose_up(
+ app.root_path,
+ detach=True,
+ compose_file=_local_compose_file(app)
+ )
+ finally:
+ ContainerRegistryService.logout_for_app(_registry)
+ if not result.get('success') or _agent_result_failed(result):
+ raise ApplicationLifecycleError(
+ _agent_result_error(result, 'Failed to start containers')
+ )
+
+ app.status = 'running'
+ db.session.commit()
+ # The cached aggregate now describes the pre-start world. Drop it: a status
+ # pill that survives the action that changed it reads as a broken panel.
+ container_status_service.invalidate(app.id)
+
+
+def stop_application(app, *, user_id=None):
+ """Stop the configured runtime; a vanished single container is stopped."""
+ # Handle Docker apps
+ if app.app_type == 'docker' and app.root_path:
+ if app.server_id:
+ result = RemoteDockerService.compose_down(
+ app.server_id,
+ _compose_target(app),
+ user_id=user_id
+ )
+ elif _is_single_container_app(app):
+ # A container that no longer exists is already stopped -- reporting
+ # that as a failure would strand the app in `running` forever.
+ container = _app_container_name(app)
+ result = ({'success': True} if not DockerService.get_container(container)
+ else DockerService.stop_container(container))
+ else:
+ result = DockerService.compose_down(
+ app.root_path,
+ compose_file=_local_compose_file(app)
+ )
+ if not result.get('success') or _agent_result_failed(result):
+ raise ApplicationLifecycleError(
+ _agent_result_error(result, 'Failed to stop containers')
+ )
+
+ app.status = 'stopped'
+ db.session.commit()
+ container_status_service.invalidate(app.id)
+
+
+def restart_application(app, *, user_id=None):
+ """Restart the configured runtime, requiring a deployed single container."""
+ # Handle Docker apps
+ if app.app_type == 'docker' and app.root_path:
+ if app.server_id:
+ result = RemoteDockerService.compose_restart(
+ app.server_id,
+ _compose_target(app),
+ user_id=user_id
+ )
+ elif _is_single_container_app(app):
+ container = _app_container_name(app)
+ if not DockerService.get_container(container):
+ raise ApplicationLifecycleError(
+ 'This application has not been deployed yet. '
+ 'Run a deploy to build its image and create the container.'
+ )
+ result = DockerService.restart_container(container)
+ else:
+ result = DockerService.compose_restart(
+ app.root_path,
+ compose_file=_local_compose_file(app)
+ )
+ if not result.get('success') or _agent_result_failed(result):
+ raise ApplicationLifecycleError(
+ _agent_result_error(result, 'Failed to restart containers')
+ )
+
+ app.status = 'running'
+ db.session.commit()
+ container_status_service.invalidate(app.id)
diff --git a/backend/app/services/cf_ops_change_service.py b/backend/app/services/cf_ops_change_service.py
index b7efd8cb..73542437 100644
--- a/backend/app/services/cf_ops_change_service.py
+++ b/backend/app/services/cf_ops_change_service.py
@@ -5,11 +5,12 @@ Tunnels, storage) is recorded here, keyed by ``provider_zone_id``.
The ops-layer sibling of :class:`DnsChangeService` (which covers DNS *record*
writes). Recording is best-effort and **never raises** — an audit write must not
break the operation it describes. The current user is captured opportunistically
-from the JWT when called inside a request.
+from the JWT or API-key identity when called inside a request.
"""
import logging
from app import db
+from app.utils.actor import current_actor_id
from app.models.cf_ops_change import CfOpsChange
logger = logging.getLogger(__name__)
@@ -17,19 +18,7 @@ logger = logging.getLogger(__name__)
class CfOpsChangeService:
- @staticmethod
- def _current_user_id():
- """Best-effort current user id (None outside a request context).
-
- Via rbac.get_current_user() so an API-key caller is attributed to the
- key's owner; reading the JWT directly raises for those requests and
- the blanket except turned that into a silent None."""
- try:
- from app.middleware.rbac import get_current_user
- user = get_current_user()
- return user.id if user else None
- except Exception:
- return None
+ _current_user_id = staticmethod(current_actor_id)
@staticmethod
def record(*, provider_zone_id, product, action, target=None, result='ok',
diff --git a/backend/app/services/connect_format.py b/backend/app/services/connect_format.py
new file mode 100644
index 00000000..52270eb7
--- /dev/null
+++ b/backend/app/services/connect_format.py
@@ -0,0 +1,16 @@
+"""Serialization shared by Connect protocol snapshots."""
+
+from datetime import datetime, timezone
+
+
+def iso_datetime(value):
+ """Preserve strings; serialize naive panel timestamps as UTC."""
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ if isinstance(value, datetime):
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.isoformat()
+ return None
diff --git a/backend/app/services/connect_policy.py b/backend/app/services/connect_policy.py
index a20690c5..01f3f286 100644
--- a/backend/app/services/connect_policy.py
+++ b/backend/app/services/connect_policy.py
@@ -21,24 +21,13 @@ import logging
from datetime import datetime, timezone
from app.services.connect_commands import handler
+from app.services.connect_format import iso_datetime as _iso
logger = logging.getLogger(__name__)
FACTS_VERSION = 1
-def _iso(value):
- if value is None:
- return None
- if isinstance(value, str):
- return value
- if isinstance(value, datetime):
- if value.tzinfo is None:
- value = value.replace(tzinfo=timezone.utc)
- return value.isoformat()
- return None
-
-
# ==================== facts ====================
diff --git a/backend/app/services/connect_storage.py b/backend/app/services/connect_storage.py
index 0b28c6aa..e4a3f7a9 100644
--- a/backend/app/services/connect_storage.py
+++ b/backend/app/services/connect_storage.py
@@ -18,9 +18,9 @@ config would race, and the operator should be told where it is coming from
rather than watching their edit disappear.
"""
import logging
-from datetime import datetime, timezone
from app.services.connect_commands import handler
+from app.services.connect_format import iso_datetime as _iso
from app.services.storage_provider_service import StorageProviderService
logger = logging.getLogger(__name__)
@@ -31,18 +31,6 @@ logger = logging.getLogger(__name__)
PANEL_PROVIDER = 's3'
-def _iso(value):
- if value is None:
- return None
- if isinstance(value, str):
- return value
- if isinstance(value, datetime):
- if value.tzinfo is None:
- value = value.replace(tzinfo=timezone.utc)
- return value.isoformat()
- return None
-
-
# ==================== commands ====================
diff --git a/backend/app/services/fleet_monitor_service.py b/backend/app/services/fleet_monitor_service.py
index e8e86bda..7be04e08 100644
--- a/backend/app/services/fleet_monitor_service.py
+++ b/backend/app/services/fleet_monitor_service.py
@@ -13,11 +13,13 @@ from datetime import datetime, timedelta
from typing import List, Dict, Optional, Any
from sqlalchemy import func, and_
+from sqlalchemy.orm import joinedload
from app import db
from app.models.server import Server, ServerMetrics, ServerGroup
from app.models.metric_alert import ServerAlertThreshold, MetricAlert
from app.services.agent_registry import agent_registry
+from app.services.server_metrics_service import latest_metrics_by_server
logger = logging.getLogger(__name__)
@@ -42,13 +44,12 @@ class FleetMonitorService:
if group_id:
query = query.filter_by(group_id=group_id)
- servers = query.all()
+ servers = query.options(joinedload(Server.group)).all()
+ metrics_by_server = latest_metrics_by_server(server.id for server in servers)
result = []
for server in servers:
- latest = ServerMetrics.query.filter_by(
- server_id=server.id
- ).order_by(ServerMetrics.timestamp.desc()).first()
+ latest = metrics_by_server.get(server.id)
result.append({
'id': server.id,
@@ -520,6 +521,7 @@ class FleetMonitorService:
"""Generate Prometheus exposition format metrics for all servers."""
lines = []
servers = Server.query.all()
+ metrics_by_server = latest_metrics_by_server(server.id for server in servers)
metrics_defs = [
('serverkit_cpu_percent', 'CPU usage percentage', 'cpu_percent'),
@@ -533,9 +535,7 @@ class FleetMonitorService:
lines.append(f'# TYPE {metric_name} gauge')
for server in servers:
- latest = ServerMetrics.query.filter_by(
- server_id=server.id
- ).order_by(ServerMetrics.timestamp.desc()).first()
+ latest = metrics_by_server.get(server.id)
if latest:
val = getattr(latest, col_name)
diff --git a/backend/app/services/resource_tier_service.py b/backend/app/services/resource_tier_service.py
index 47122bc3..f0ba94f3 100644
--- a/backend/app/services/resource_tier_service.py
+++ b/backend/app/services/resource_tier_service.py
@@ -153,29 +153,9 @@ class ResourceTierService:
@staticmethod
def _detect_container():
- """
- Identify container virtualisation, or None on bare metal / a full VM.
-
- This matters more than core count on small hosts: Docker frequently
- cannot run inside an unprivileged LXC or OpenVZ container at all, so a
- box can look adequate on paper and still be unable to host anything.
- """
- try:
- if os.path.exists('/.dockerenv'):
- return 'docker'
- if os.path.isdir('/proc/vz') and not os.path.isdir('/proc/bc'):
- return 'openvz'
- # systemd-nspawn and LXC both advertise themselves here.
- with open('/proc/1/environ', 'rb') as fh:
- environ = fh.read().decode('utf-8', 'replace')
- for entry in environ.split('\0'):
- if entry.startswith('container='):
- return entry.split('=', 1)[1] or 'container'
- except Exception:
- # /proc is absent on Windows dev boxes and restricted in some
- # sandboxes — "unknown" is the honest answer, not an error.
- return None
- return None
+ """Share host inventory's container capability detection."""
+ from app.services import host_inventory_service
+ return host_inventory_service._detect_container()
@classmethod
def get_headroom(cls, specs=None):
diff --git a/backend/app/services/server_metrics_service.py b/backend/app/services/server_metrics_service.py
index 3371ee19..8f0c1564 100644
--- a/backend/app/services/server_metrics_service.py
+++ b/backend/app/services/server_metrics_service.py
@@ -424,3 +424,37 @@ class ServerMetricsService:
'memory_max': round(max(memory_values), 1) if memory_values else None,
'disk_avg': round(sum(disk_values) / len(disk_values), 1) if disk_values else None,
}
+
+
+def latest_metrics_by_server(server_ids, *, order_by='timestamp'):
+ """Return one model per requested server, with one query (none if empty).
+
+ The server list historically uses insertion order; monitoring uses sample
+ time so late arrivals cannot replace a newer observation. Callers choose
+ explicitly when they need insertion order. Equal timestamps resolve to the
+ highest insertion ID, making ties deterministic without duplicating rows.
+ Authorization belongs to the caller: only its selected IDs are queried.
+ """
+ if order_by not in ('timestamp', 'id'):
+ raise ValueError('Latest metrics order must be timestamp or id')
+ server_ids = list(server_ids)
+ if not server_ids:
+ return {}
+ if order_by == 'id':
+ # Preserve the list's existing grouped max query without a window sort.
+ newest = db.session.query(func.max(ServerMetrics.id)).filter(
+ ServerMetrics.server_id.in_(server_ids),
+ ).group_by(ServerMetrics.server_id)
+ rows = ServerMetrics.query.filter(ServerMetrics.id.in_(newest)).all()
+ else:
+ ranked = db.session.query(
+ ServerMetrics.id.label('id'),
+ func.row_number().over(
+ partition_by=ServerMetrics.server_id,
+ order_by=[ServerMetrics.timestamp.desc(), ServerMetrics.id.desc()],
+ ).label('rank'),
+ ).filter(ServerMetrics.server_id.in_(server_ids)).subquery()
+ rows = ServerMetrics.query.join(
+ ranked, ServerMetrics.id == ranked.c.id,
+ ).filter(ranked.c.rank == 1).all()
+ return {row.server_id: row for row in rows}
diff --git a/backend/app/services/shared_resource_service.py b/backend/app/services/shared_resource_service.py
index 3889a26b..62c8a70f 100644
--- a/backend/app/services/shared_resource_service.py
+++ b/backend/app/services/shared_resource_service.py
@@ -19,6 +19,7 @@ provenance.
import re
from app import db
+from app.utils.actor import current_actor_id as _current_user_id
from app.models.shared_resource import (
ResourceTag,
SharedVariable,
@@ -48,21 +49,6 @@ def _audit(action, **kwargs):
pass
-def _current_user_id():
- """Resolve the acting user id, or None outside a request.
-
- Goes through rbac.get_current_user() rather than get_jwt_identity() so an
- API-key caller is attributed to the key's owner. Reading the JWT directly
- *raises* for those requests, and the blanket except below turned that into
- a silent user_id=None on every row written here."""
- try:
- from app.middleware.rbac import get_current_user
- user = get_current_user()
- return user.id if user else None
- except Exception:
- return None
-
-
class SharedResourceService:
"""Static facade for tags and shared variable groups."""
diff --git a/backend/app/utils/actor.py b/backend/app/utils/actor.py
new file mode 100644
index 00000000..2fdb1f31
--- /dev/null
+++ b/backend/app/utils/actor.py
@@ -0,0 +1,15 @@
+"""Optional identity attribution for best-effort service audit records."""
+
+
+def current_actor_id():
+ """Return the JWT/API-key owner ID, or None if unavailable.
+
+ This helper is for attribution only, never for access control. Background
+ jobs and audit callers without a request keep their existing None actor.
+ """
+ try:
+ from app.middleware.rbac import get_current_user
+ user = get_current_user()
+ return user.id if user else None
+ except Exception:
+ return None
diff --git a/backend/tests/api_controller_boundary_baseline.json b/backend/tests/api_controller_boundary_baseline.json
index a10e1291..a7d0c55a 100644
--- a/backend/tests/api_controller_boundary_baseline.json
+++ b/backend/tests/api_controller_boundary_baseline.json
@@ -2,8 +2,8 @@
"schema_version": 1,
"policy": "Exact reviewed inventory of direct persistence, subprocess, and filesystem mutation calls in Flask API controllers. New calls are forbidden; remove entries as controllers delegate to services.",
"counts": {
- "filesystem": 11,
- "persistence": 500
+ "filesystem": 9,
+ "persistence": 494
},
"owners": {
"api/admin.py": {
@@ -245,7 +245,6 @@
"api/ai.py::chat_confirm::persistence::db.session.get(AiPendingAction, token)::1",
"api/ai.py::chat_stream.producer::persistence::db.session.get(AiConversation, conversation_id)::1",
"api/ai.py::chat_stream.producer::persistence::db.session.get(AiConversation, conversation_id)::2",
- "api/ai.py::chat_stream.producer::persistence::db.session.get(User, user_id)::1",
"api/ai.py::create_conversation::persistence::db.session.add(row)::1",
"api/ai.py::create_conversation::persistence::db.session.commit()::1",
"api/ai.py::delete_conversation::persistence::db.session.commit()::1",
@@ -253,9 +252,6 @@
"api/ai.py::list_conversations::persistence::AiConversation.query.filter_by(user_id=user.id).order_by(AiConversation.updated_at.desc()).limit(100).all()::1",
"api/ai.py::rename_conversation::persistence::db.session.commit()::1",
"api/app_volumes.py::_load_app_for::persistence::Application.query_active().filter_by(id=app_id).first()::1",
- "api/apps.py::_ensure_local_image_compose::filesystem::open(os.path.join(app_path, 'docker-compose.yml'), 'w')::1",
- "api/apps.py::_ensure_local_image_compose::filesystem::os.makedirs(app_path, exist_ok=True)::1",
- "api/apps.py::_ensure_local_image_compose::persistence::db.session.commit()::1",
"api/apps.py::_load_app_for_backup::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::_resolve_project_env::persistence::Environment.query.get(environment_id)::1",
"api/apps.py::_resolve_project_env::persistence::Project.query.get(project_id)::1",
@@ -326,7 +322,6 @@
"api/apps.py::purge_micro_cache::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::restart_app::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::restart_app::persistence::User.query.get(current_user_id)::1",
- "api/apps.py::restart_app::persistence::db.session.commit()::1",
"api/apps.py::revoke_app_access::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::rollback_app_version::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::rollback_app_version::persistence::User.query.get(current_user_id)::1",
@@ -340,10 +335,8 @@
"api/apps.py::sleep_app::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::start_app::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::start_app::persistence::User.query.get(current_user_id)::1",
- "api/apps.py::start_app::persistence::db.session.commit()::1",
"api/apps.py::stop_app::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::stop_app::persistence::User.query.get(current_user_id)::1",
- "api/apps.py::stop_app::persistence::db.session.commit()::1",
"api/apps.py::unlink_apps::persistence::Application.query.get(app.linked_app_id)::1",
"api/apps.py::unlink_apps::persistence::Application.query_active().filter_by(id=app_id).first()::1",
"api/apps.py::unlink_apps::persistence::User.query.get(current_user_id)::1",
@@ -381,6 +374,8 @@
"api/auth.py::login::persistence::db.session.commit()::2",
"api/auth.py::login::persistence::db.session.commit()::3",
"api/auth.py::login::persistence::db.session.commit()::4",
+ "api/auth.py::logout::persistence::db.session.add(RevokedSession(session_id=get_jwt()['session_id'], user_id=g.session_user.id))::1",
+ "api/auth.py::logout::persistence::db.session.commit()::1",
"api/auth.py::passkey_auth_options::persistence::User.query.get(user_id)::1",
"api/auth.py::passkey_authenticate::persistence::User.query.get(user_id)::1",
"api/auth.py::passkey_authenticate::persistence::db.session.commit()::1",
@@ -631,11 +626,9 @@
"api/servers.py::get_server_onboarding_status::persistence::Server.query.get(server_id)::1",
"api/servers.py::get_server_security_alerts::persistence::Server.query.get(server_id)::1",
"api/servers.py::get_server_status::persistence::Server.query.get(server_id)::1",
- "api/servers.py::get_servers_overview::persistence::Server.query.all()::1",
+ "api/servers.py::get_servers_overview::persistence::Server.query.options(joinedload(Server.group)).all()::1",
"api/servers.py::list_agent_versions::persistence::AgentVersion.query.order_by(AgentVersion.version.desc()).all()::1",
"api/servers.py::list_groups::persistence::ServerGroup.query.all()::1",
- "api/servers.py::list_servers::persistence::ServerMetrics.query.filter(ServerMetrics.id.in_(newest)).all()::1",
- "api/servers.py::list_servers::persistence::db.session.query(db.func.max(ServerMetrics.id))::1",
"api/servers.py::ping_server::persistence::Server.query.get(server_id)::1",
"api/servers.py::regenerate_token::persistence::Server.query.get(server_id)::1",
"api/servers.py::regenerate_token::persistence::db.session.commit()::1",
@@ -700,7 +693,6 @@
"api/two_factor.py::get_2fa_status::persistence::User.query.get(current_user_id)::1",
"api/two_factor.py::initiate_2fa_setup::persistence::User.query.get(current_user_id)::1",
"api/two_factor.py::regenerate_backup_codes::persistence::User.query.get(current_user_id)::1",
- "api/two_factor.py::verify_2fa_code::persistence::User.query.get(user_id)::1",
"api/two_factor.py::verify_2fa_code::persistence::db.session.commit()::1",
"api/two_factor.py::verify_2fa_code::persistence::db.session.commit()::2",
"api/two_factor.py::verify_2fa_code::persistence::db.session.commit()::3",
diff --git a/backend/tests/test_app_lifecycle_noncompose.py b/backend/tests/test_app_lifecycle_noncompose.py
index b2235b2d..56857c0e 100644
--- a/backend/tests/test_app_lifecycle_noncompose.py
+++ b/backend/tests/test_app_lifecycle_noncompose.py
@@ -20,7 +20,7 @@ from unittest.mock import patch
import pytest
-from app.api.apps import _is_single_container_app
+from app.services.application_lifecycle_service import _is_single_container_app
from app.models import Application
from factories import headers_for, make_application, make_user
@@ -62,10 +62,10 @@ def test_a_non_buildpack_app_keeps_the_compose_path(buildpack_app):
# ── start ────────────────────────────────────────────────────────────────────
def test_start_drives_the_container_and_never_compose(client, buildpack_app, owner):
- with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
- patch('app.api.apps.DockerService.start_container',
+ with patch('app.services.application_lifecycle_service.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.services.application_lifecycle_service.DockerService.start_container',
return_value={'success': True}) as start, \
- patch('app.api.apps.DockerService.compose_up') as compose:
+ patch('app.services.application_lifecycle_service.DockerService.compose_up') as compose:
response = client.post(f'/api/v1/apps/{buildpack_app.id}/start',
headers=headers_for(owner))
@@ -75,8 +75,8 @@ def test_start_drives_the_container_and_never_compose(client, buildpack_app, own
def test_start_before_any_deploy_says_so(client, buildpack_app, owner):
- with patch('app.api.apps.DockerService.get_container', return_value=None), \
- patch('app.api.apps.DockerService.compose_up') as compose:
+ with patch('app.services.application_lifecycle_service.DockerService.get_container', return_value=None), \
+ patch('app.services.application_lifecycle_service.DockerService.compose_up') as compose:
response = client.post(f'/api/v1/apps/{buildpack_app.id}/start',
headers=headers_for(owner))
@@ -88,10 +88,10 @@ def test_start_before_any_deploy_says_so(client, buildpack_app, owner):
# ── restart ──────────────────────────────────────────────────────────────────
def test_restart_drives_the_container_and_never_compose(client, buildpack_app, owner):
- with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
- patch('app.api.apps.DockerService.restart_container',
+ with patch('app.services.application_lifecycle_service.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.services.application_lifecycle_service.DockerService.restart_container',
return_value={'success': True}) as restart, \
- patch('app.api.apps.DockerService.compose_restart') as compose:
+ patch('app.services.application_lifecycle_service.DockerService.compose_restart') as compose:
response = client.post(f'/api/v1/apps/{buildpack_app.id}/restart',
headers=headers_for(owner))
@@ -103,8 +103,8 @@ def test_restart_drives_the_container_and_never_compose(client, buildpack_app, o
# ── stop ─────────────────────────────────────────────────────────────────────
def test_stop_of_a_vanished_container_is_not_a_failure(client, buildpack_app, owner):
- with patch('app.api.apps.DockerService.get_container', return_value=None), \
- patch('app.api.apps.DockerService.compose_down') as compose:
+ with patch('app.services.application_lifecycle_service.DockerService.get_container', return_value=None), \
+ patch('app.services.application_lifecycle_service.DockerService.compose_down') as compose:
response = client.post(f'/api/v1/apps/{buildpack_app.id}/stop',
headers=headers_for(owner))
@@ -114,10 +114,10 @@ def test_stop_of_a_vanished_container_is_not_a_failure(client, buildpack_app, ow
def test_stop_drives_the_container_when_it_exists(client, buildpack_app, owner):
- with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
- patch('app.api.apps.DockerService.stop_container',
+ with patch('app.services.application_lifecycle_service.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.services.application_lifecycle_service.DockerService.stop_container',
return_value={'success': True}) as stop, \
- patch('app.api.apps.DockerService.compose_down') as compose:
+ patch('app.services.application_lifecycle_service.DockerService.compose_down') as compose:
response = client.post(f'/api/v1/apps/{buildpack_app.id}/stop',
headers=headers_for(owner))
diff --git a/backend/tests/test_application_lifecycle_service.py b/backend/tests/test_application_lifecycle_service.py
new file mode 100644
index 00000000..d691778b
--- /dev/null
+++ b/backend/tests/test_application_lifecycle_service.py
@@ -0,0 +1,153 @@
+"""Lifecycle dispatch, failure handling and side effects without HTTP context."""
+
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from app.services import application_lifecycle_service as lifecycle
+
+
+def runtime(monkeypatch, tmp_path):
+ docker = Mock()
+ remote = Mock()
+ registry = Mock()
+ session = Mock()
+ invalidate = Mock()
+ monkeypatch.setattr(lifecycle, 'DockerService', docker)
+ monkeypatch.setattr(lifecycle, 'RemoteDockerService', remote)
+ monkeypatch.setattr(lifecycle, 'ContainerRegistryService', registry)
+ monkeypatch.setattr(lifecycle, 'db', SimpleNamespace(session=session))
+ monkeypatch.setattr(lifecycle.container_status_service, 'invalidate', invalidate)
+ app = SimpleNamespace(
+ id=42, app_type='docker', root_path=str(tmp_path), server_id=None,
+ compose_file='custom.yml', buildpack_type=None, docker_image=None,
+ status='original',
+ )
+ return SimpleNamespace(
+ app=app, docker=docker, remote=remote, registry=registry,
+ session=session, invalidate=invalidate,
+ )
+
+
[email protected]('operation,method,status', [
+ ('start', 'up', 'running'), ('stop', 'down', 'stopped'),
+ ('restart', 'restart', 'running'),
+])
[email protected]('target', ['local', 'remote', 'single'])
+def test_dispatch_and_commit_before_invalidation(runtime, operation, method, status, target):
+ app = runtime.app
+ if target == 'remote':
+ app.server_id = 'remote-server'
+ service = runtime.remote
+ else:
+ service = runtime.docker
+ if target == 'single':
+ app.compose_file = None
+ app.buildpack_type = 'nixpacks'
+ command = getattr(service, f'{operation}_container')
+ else:
+ command = getattr(service, f'compose_{method}')
+ command.return_value = {'success': True}
+ effects = []
+ runtime.session.commit.side_effect = lambda: effects.append('commit')
+ runtime.invalidate.side_effect = lambda value: effects.append(('invalidate', value))
+
+ getattr(lifecycle, f'{operation}_application')(app, user_id=7)
+
+ assert app.status == status
+ assert effects == ['commit', ('invalidate', 42)]
+ kwargs = {'detach': True} if operation == 'start' else {}
+ if target == 'remote':
+ command.assert_called_once_with(
+ 'remote-server', lifecycle._compose_target(app), user_id=7, **kwargs,
+ )
+ assert not runtime.docker.mock_calls
+ elif target == 'single':
+ command.assert_called_once_with('serverkit-app-42')
+ else:
+ command.assert_called_once_with(app.root_path, compose_file='custom.yml', **kwargs)
+ if operation == 'start':
+ runtime.registry.login_for_app.assert_called_once_with(app)
+ runtime.registry.logout_for_app.assert_called_once_with(runtime.registry.login_for_app.return_value)
+
+
[email protected]('operation,method', [('start', 'up'), ('stop', 'down'), ('restart', 'restart')])
+def test_agent_failure_preserves_status_and_cache(runtime, operation, method):
+ runtime.app.server_id = 'remote-server'
+ getattr(runtime.remote, f'compose_{method}').return_value = {
+ 'success': True, 'data': {'success': False, 'error': 'agent rejected'},
+ }
+ with pytest.raises(lifecycle.ApplicationLifecycleError, match='agent rejected'):
+ getattr(lifecycle, f'{operation}_application')(runtime.app, user_id=7)
+ assert runtime.app.status == 'original'
+ runtime.session.commit.assert_not_called()
+ runtime.invalidate.assert_not_called()
+
+
+def test_registry_logout_even_when_compose_raises(runtime):
+ runtime.docker.compose_up.side_effect = RuntimeError('docker unavailable')
+ with pytest.raises(RuntimeError, match='docker unavailable'):
+ lifecycle.start_application(runtime.app)
+ runtime.registry.logout_for_app.assert_called_once_with(runtime.registry.login_for_app.return_value)
+ runtime.session.commit.assert_not_called()
+ runtime.invalidate.assert_not_called()
+
+
+def test_commit_failure_does_not_invalidate(runtime):
+ runtime.docker.compose_up.return_value = {'success': True}
+ runtime.session.commit.side_effect = RuntimeError('database unavailable')
+ with pytest.raises(RuntimeError, match='database unavailable'):
+ lifecycle.start_application(runtime.app)
+ runtime.invalidate.assert_not_called()
+
+
+def test_first_image_start_persists_compose_before_runtime_failure(runtime, monkeypatch, tmp_path):
+ app = runtime.app
+ app.root_path = None
+ app.compose_file = None
+ app.docker_image = 'example/private:latest'
+ app.name = 'image-app'
+ app.port = 8080
+ app.healthcheck_path = '/health'
+ app.managed_by = None
+ monkeypatch.setattr(lifecycle.paths, 'APPS_DIR', str(tmp_path))
+ monkeypatch.setattr(lifecycle.AppPortService, 'get_ports', lambda value: [])
+ render = Mock(return_value='services: {}\n')
+ monkeypatch.setattr(lifecycle.UnitComposeService, 'render_yaml', render)
+ runtime.docker.compose_up.return_value = {'success': False, 'error': 'pull failed'}
+
+ with pytest.raises(lifecycle.ApplicationLifecycleError, match='pull failed'):
+ lifecycle.start_application(app)
+
+ assert (tmp_path / 'image-app' / 'docker-compose.yml').read_text() == 'services: {}\n'
+ assert app.compose_file == 'docker-compose.yml'
+ assert app.managed_by == 'docker_compose'
+ assert app.status == 'original'
+ runtime.session.commit.assert_called_once()
+ runtime.invalidate.assert_not_called()
+ render.assert_called_once_with('image-app', [{
+ 'name': 'app', 'image': 'example/private:latest',
+ 'ports': [{'host_port': 8080, 'container_port': 8080, 'expose': 'local'}],
+ 'health_check': {'http_path': '/health'},
+ }])
+ # A retry uses the saved project instead of writing/committing it again.
+ runtime.docker.compose_up.return_value = {'success': True}
+ lifecycle.start_application(app)
+ assert runtime.session.commit.call_count == 2
+ assert render.call_count == 1
+ runtime.invalidate.assert_called_once_with(app.id)
+
+
+def test_image_path_validation_rejects_escape_before_write(runtime, monkeypatch, tmp_path):
+ app = runtime.app
+ app.root_path = None
+ app.docker_image = 'example/image:latest'
+ app.name = '../outside'
+ monkeypatch.setattr(lifecycle.paths, 'APPS_DIR', str(tmp_path))
+ with pytest.raises(lifecycle.ApplicationLifecycleError, match='Invalid application path'):
+ lifecycle.start_application(app)
+ assert not list(tmp_path.iterdir())
+ runtime.session.commit.assert_not_called()
+ runtime.invalidate.assert_not_called()
diff --git a/backend/tests/test_fleet_metrics_batching.py b/backend/tests/test_fleet_metrics_batching.py
new file mode 100644
index 00000000..7d7b07d3
--- /dev/null
+++ b/backend/tests/test_fleet_metrics_batching.py
@@ -0,0 +1,123 @@
+"""Fleet readers share one bounded query without changing latest semantics."""
+
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+
+import pytest
+from sqlalchemy import event
+
+from app import db
+from app.models.server import Server, ServerMetrics
+from app.services.fleet_monitor_service import FleetMonitorService
+from app.services.server_metrics_service import latest_metrics_by_server
+
+
+@contextmanager
+def metric_queries():
+ queries = []
+
+ def before(conn, cursor, statement, params, context, executemany):
+ if 'server_metrics' in statement.lower():
+ queries.append(statement)
+
+ engine = db.engine
+ event.listen(engine, 'before_cursor_execute', before)
+ try:
+ yield queries
+ finally:
+ event.remove(engine, 'before_cursor_execute', before)
+
+
+def seed_server(name):
+ server = Server(name=name, hostname=f'{name}.test', status='online')
+ db.session.add(server)
+ db.session.flush()
+ return server
+
+
+def seed_sample(server, when, value):
+ sample = ServerMetrics(
+ server_id=server.id, timestamp=when, cpu_percent=value,
+ memory_percent=value + 1, disk_percent=value + 2,
+ container_running=int(value), container_count=int(value) + 1,
+ )
+ db.session.add(sample)
+ db.session.flush()
+ return sample
+
+
+def test_latest_order_scope_missing_rows_and_ties(app, db_session):
+ server = seed_server('ordering')
+ missing = seed_server('missing')
+ excluded = seed_server('excluded')
+ now = datetime(2026, 9, 5, 12)
+ seed_sample(server, now, 10)
+ tie = seed_sample(server, now, 20)
+ late = seed_sample(server, now - timedelta(hours=1), 30)
+ seed_sample(excluded, now, 99)
+ db.session.commit()
+ ids = [server.id, missing.id]
+
+ assert latest_metrics_by_server(ids) == {server.id: tie}
+ assert latest_metrics_by_server(ids, order_by='id') == {server.id: late}
+ with metric_queries() as queries:
+ assert latest_metrics_by_server([]) == {}
+ assert not queries
+ with pytest.raises(ValueError):
+ latest_metrics_by_server(ids, order_by='invalid')
+
+
[email protected]('size', [1, 8, 31])
[email protected]('reader', ['heatmap', 'prometheus', 'overview', 'list'])
+def test_each_fleet_reader_uses_one_metrics_query(
+ app, client, auth_headers, db_session, size, reader,
+):
+ now = datetime(2026, 9, 5, 12)
+ for index in range(size):
+ server = seed_server(f'fleet-{index}')
+ seed_sample(server, now, 10)
+ # Arrives later, but describes an older observation.
+ seed_sample(server, now - timedelta(hours=1), 20)
+ db.session.commit()
+
+ with metric_queries() as queries:
+ if reader == 'heatmap':
+ result = FleetMonitorService.get_fleet_heatmap()
+ assert len(result) == size
+ assert all(row['cpu'] == 10 for row in result)
+ elif reader == 'prometheus':
+ result = FleetMonitorService.get_prometheus_metrics()
+ samples = [line for line in result.splitlines() if line.startswith('serverkit_cpu_percent{')]
+ assert len(samples) == size
+ assert all(line.endswith(' 10.0') for line in samples)
+ elif reader == 'overview':
+ response = client.get('/api/v1/servers/overview', headers=auth_headers)
+ assert response.status_code == 200
+ result = response.get_json()
+ assert result['summary']['running_containers'] == size * 10
+ assert all(row['cpu_percent'] == 10 for row in result['servers'])
+ else:
+ response = client.get('/api/v1/servers', headers=auth_headers)
+ assert response.status_code == 200
+ result = response.get_json()
+ assert len(result) == size
+ assert all(row['metrics']['cpu_percent'] == 20 for row in result)
+ assert len(queries) == 1
+
+
+def test_heatmap_keeps_group_scope_and_missing_metrics(app, db_session):
+ from app.models.server import ServerGroup
+
+ group = ServerGroup(name='selected')
+ db.session.add(group)
+ db.session.flush()
+ included = seed_server('included')
+ included.group_id = group.id
+ seed_server('excluded')
+ db.session.commit()
+ result = FleetMonitorService.get_fleet_heatmap(group.id)
+ assert len(result) == 1
+ assert result[0]['id'] == included.id
+ assert result[0]['group_name'] == 'selected'
+ assert result[0]['cpu'] is None
+ assert result[0]['last_update'] is None
diff --git a/backend/tests/test_shared_service_helpers.py b/backend/tests/test_shared_service_helpers.py
new file mode 100644
index 00000000..2773157b
--- /dev/null
+++ b/backend/tests/test_shared_service_helpers.py
@@ -0,0 +1,60 @@
+"""Shared protocol/actor/host helpers retain their callers' contracts."""
+
+from datetime import datetime, timedelta, timezone
+import pytest
+from flask import g
+from flask_jwt_extended import create_access_token, verify_jwt_in_request
+
+from app.services.cf_ops_change_service import CfOpsChangeService
+from app.services.connect_format import iso_datetime
+from app.services.resource_tier_service import ResourceTierService
+from app.services.shared_resource_service import _current_user_id
+from app.utils.actor import current_actor_id
+from factories import make_user
+
+
[email protected]('lookup', [current_actor_id, _current_user_id, CfOpsChangeService._current_user_id])
+def test_optional_actor_without_request(lookup):
+ assert lookup() is None
+
+
[email protected]('kind', ['jwt', 'api-key'])
+def test_shared_actor_preserves_authenticated_owner(app, db_session, kind):
+ user = make_user(db_session, role='admin', username=f'actor-{kind}')
+ headers = {}
+ if kind == 'jwt':
+ headers['Authorization'] = f'Bearer {create_access_token(identity=str(user.id))}'
+ with app.test_request_context(headers=headers):
+ if kind == 'jwt':
+ verify_jwt_in_request()
+ else:
+ g.api_key_user = user
+ assert current_actor_id() == user.id
+ assert _current_user_id() == user.id
+ assert CfOpsChangeService._current_user_id() == user.id
+
+
+def test_actor_lookup_failure_remains_best_effort(monkeypatch):
+ def unavailable():
+ raise RuntimeError('identity unavailable')
+ monkeypatch.setattr('app.middleware.rbac.get_current_user', unavailable)
+ assert current_actor_id() is None
+
+
[email protected]('value,expected', [
+ (None, None), ('already formatted', 'already formatted'), (123, None),
+ (datetime(2026, 9, 5), '2026-09-05T00:00:00+00:00'),
+ (datetime(2026, 9, 5, tzinfo=timezone(timedelta(hours=2))), '2026-09-05T00:00:00+02:00'),
+])
+def test_connect_date_serialization(value, expected):
+ from app.services.connect_policy import _iso as policy_iso
+ from app.services.connect_storage import _iso as storage_iso
+ assert iso_datetime(value) == expected
+ assert policy_iso(value) == expected
+ assert storage_iso(value) == expected
+
+
[email protected]('container', [None, 'docker', 'lxc', 'openvz'])
+def test_resource_tier_uses_host_inventory_detection(monkeypatch, container):
+ monkeypatch.setattr('app.services.host_inventory_service._detect_container', lambda: container)
+ assert ResourceTierService._detect_container() == container