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.

feat(cache): ttl_cached decorator on CacheService; two TTL dicts migrate (plan 77 F2)

Juan Denis01b82955f9c7
diff --git a/backend/app/services/cache_service.py b/backend/app/services/cache_service.py
index 997ef1c2..74a0a5f3 100644
--- a/backend/app/services/cache_service.py
+++ b/backend/app/services/cache_service.py
@@ -138,3 +138,44 @@ def cached(key_template, ttl=300):
return result
return wrapper
return decorator
+
+
+def ttl_cached(ttl, key_fn=None):
+ """Cache a function's return through CacheService for ``ttl`` seconds
+ (plan 77 F2 — replaces hand-rolled module-level ``{'data':…,'timestamp':…}``
+ TTL dicts; Redis benefits apply automatically wherever configured).
+
+ The cached value must be JSON-serializable (the Redis path serializes).
+ ``None`` returns are NOT cached, so a failed computation retries.
+ ``key_fn(*args, **kwargs)`` derives the per-call cache key suffix; without
+ it, the repr of the arguments is used (fine for hashable scalar args).
+ The wrapped function gains ``.invalidate(*args, **kwargs)``.
+ """
+ def decorator(fn):
+ prefix = f'ttlfn:{fn.__module__}.{fn.__qualname__}'
+
+ def _key(args, kwargs):
+ if key_fn is not None:
+ return f'{prefix}:{key_fn(*args, **kwargs)}'
+ if not args and not kwargs:
+ return prefix
+ return f'{prefix}:{repr(args)}:{repr(sorted(kwargs.items()))}'
+
+ @wraps(fn)
+ def wrapper(*args, **kwargs):
+ key = _key(args, kwargs)
+ hit = CacheService.get(key)
+ if hit is not None:
+ return hit
+ value = fn(*args, **kwargs)
+ if value is not None:
+ CacheService.set(key, value, ttl=ttl)
+ return value
+
+ def invalidate(*args, **kwargs):
+ CacheService.delete(_key(args, kwargs))
+
+ wrapper.invalidate = invalidate
+ wrapper.__wrapped__ = fn
+ return wrapper
+ return decorator
diff --git a/backend/app/services/install_profile_service.py b/backend/app/services/install_profile_service.py
index ed98fa88..6c2bafcf 100644
--- a/backend/app/services/install_profile_service.py
+++ b/backend/app/services/install_profile_service.py
@@ -30,6 +30,8 @@ import subprocess
from app.utils.system import run_checked
import time
+from app.services.cache_service import ttl_cached
+
logger = logging.getLogger(__name__)
# The Docker probe shells out and can block for its full timeout on a host with
@@ -37,7 +39,6 @@ logger = logging.getLogger(__name__)
# briefly so a page load never pays that twice, but keep the window short
# enough that installing Docker shows up without a restart.
_CAPABILITY_TTL_SECONDS = 60
-_capability_cache = {'data': None, 'timestamp': 0}
PROFILE_MINIMAL = 'minimal'
PROFILE_STANDARD = 'standard'
@@ -209,16 +210,15 @@ def get_capabilities(force_refresh=False):
The profile says what was *intended*; this says what is *true*. They drift
— an operator can apt-install Docker on a Minimal box, and a Standard box
can have a broken daemon. Cached for _CAPABILITY_TTL_SECONDS because the
- Docker probe can block.
+ Docker probe can block (ttl_cached, plan 77 F2).
"""
- now = time.time()
- if (
- not force_refresh
- and _capability_cache['data'] is not None
- and (now - _capability_cache['timestamp']) < _CAPABILITY_TTL_SECONDS
- ):
- return dict(_capability_cache['data'])
+ if force_refresh:
+ _probe_capabilities.invalidate()
+ return dict(_probe_capabilities())
+
+@ttl_cached(_CAPABILITY_TTL_SECONDS, key_fn=lambda: 'capabilities')
+def _probe_capabilities():
docker = _docker_usable()
capabilities = {
# Tri-state: True / False / None (probe failed = unknown). Consumers
@@ -232,10 +232,7 @@ def get_capabilities(force_refresh=False):
# unknown (None) probe does not advertise app hosting.
'can_host_apps': docker is True,
}
-
- _capability_cache['data'] = capabilities
- _capability_cache['timestamp'] = now
- return dict(capabilities)
+ return capabilities
def get_profile_info(force_refresh=False):
diff --git a/backend/app/services/resource_tier_service.py b/backend/app/services/resource_tier_service.py
index cf44c88c..47122bc3 100644
--- a/backend/app/services/resource_tier_service.py
+++ b/backend/app/services/resource_tier_service.py
@@ -24,17 +24,18 @@ import os
import shutil
import time
+from app.services.cache_service import ttl_cached
+
import psutil
logger = logging.getLogger(__name__)
-# Module-level cache. Specs and the tier label are stable enough to cache for an
-# hour; headroom is recomputed on every call because it is the number that moves.
-_tier_cache = {
- 'data': None,
- 'timestamp': 0,
- 'ttl': 3600 # 1 hour
-}
+# Specs and the tier label are stable enough to cache for an hour (ttl_cached,
+# plan 77 F2); headroom is recomputed on every call because it is the number
+# that moves. _probe_count lets get_resource_tier report whether this response
+# came from cache without a second bookkeeping dict.
+_TIER_TTL_SECONDS = 3600
+_probe_count = 0
# Memory the panel refuses to hand out to workloads. ServerKit's own process
# floor is ~250MB (gunicorn + SQLAlchemy + the Python interpreter's ~76MB
@@ -93,40 +94,15 @@ class ResourceTierService:
'cached': bool
}
"""
- global _tier_cache
-
- current_time = time.time()
- cache_valid = (
- _tier_cache['data'] is not None and
- (current_time - _tier_cache['timestamp']) < _tier_cache['ttl']
- )
-
- if cache_valid and not force_refresh:
- cached = _tier_cache['data']
- # Headroom is never served from cache — it is the live number.
- return {
- **cached,
- 'headroom': cls.get_headroom(cached['specs']),
- 'cached': True,
- }
-
- specs = cls._get_system_specs()
- tier = cls._calculate_tier(specs)
- features = cls._get_features_for_tier(tier, specs)
-
- _tier_cache['data'] = {
- 'tier': tier,
- 'specs': specs,
- 'features': features,
- }
- _tier_cache['timestamp'] = current_time
-
+ if force_refresh:
+ _probe_tier.invalidate()
+ before = _probe_count
+ data = _probe_tier()
+ # Headroom is never served from cache — it is the live number.
return {
- 'tier': tier,
- 'specs': specs,
- 'features': features,
- 'headroom': cls.get_headroom(specs),
- 'cached': False,
+ **data,
+ 'headroom': cls.get_headroom(data['specs']),
+ 'cached': _probe_count == before,
}
@classmethod
@@ -362,3 +338,14 @@ class ResourceTierService:
'cpu_cores': cls.MIN_CORES_FOR_WORDPRESS,
'ram_gb': cls.MIN_RAM_GB_FOR_WORDPRESS
}
+
+
+@ttl_cached(_TIER_TTL_SECONDS, key_fn=lambda: 'tier')
+def _probe_tier():
+ """The cacheable part of the tier answer: specs, label, feature flags."""
+ global _probe_count
+ _probe_count += 1
+ specs = ResourceTierService._get_system_specs()
+ tier = ResourceTierService._calculate_tier(specs)
+ features = ResourceTierService._get_features_for_tier(tier, specs)
+ return {'tier': tier, 'specs': specs, 'features': features}
diff --git a/backend/tests/test_server_capacity.py b/backend/tests/test_server_capacity.py
index 33e64317..198ed9d8 100644
--- a/backend/tests/test_server_capacity.py
+++ b/backend/tests/test_server_capacity.py
@@ -26,10 +26,8 @@ def _clear_caches():
from app.services import resource_tier_service as rts
def reset():
- rts._tier_cache['data'] = None
- rts._tier_cache['timestamp'] = 0
- ips._capability_cache['data'] = None
- ips._capability_cache['timestamp'] = 0
+ rts._probe_tier.invalidate()
+ ips._probe_capabilities.invalidate()
reset()
yield
diff --git a/backend/tests/test_ttl_cached.py b/backend/tests/test_ttl_cached.py
new file mode 100644
index 00000000..1eed1b8d
--- /dev/null
+++ b/backend/tests/test_ttl_cached.py
@@ -0,0 +1,124 @@
+"""Plan 77 F2 — ttl_cached: CacheService-backed TTL memoization.
+
+Replaces hand-rolled module-level `{'data': …, 'timestamp': …}` TTL dicts;
+the ratchet stops new ones from appearing in services/.
+"""
+import re
+import time
+from pathlib import Path
+
+import pytest
+
+from app.services.cache_service import CacheService, ttl_cached
+
+SERVICES = Path(__file__).resolve().parents[1] / 'app' / 'services'
+
+
[email protected](autouse=True)
+def _clean_cache(monkeypatch):
+ # Force the in-memory path: a real Redis on the dev box would persist
+ # cached values across test runs and own TTL expiry itself.
+ import app.services.cache_service as cs
+ monkeypatch.setattr(cs, '_get_redis', lambda: None)
+ cs._memory_cache.clear()
+ yield
+ cs._memory_cache.clear()
+
+
+def test_caches_within_ttl_and_recomputes_after():
+ calls = []
+
+ @ttl_cached(ttl=60)
+ def compute():
+ calls.append(1)
+ return {'n': len(calls)}
+
+ assert compute() == {'n': 1}
+ assert compute() == {'n': 1}
+ assert len(calls) == 1
+
+ compute.invalidate()
+ assert compute() == {'n': 2}
+ assert len(calls) == 2
+
+
+def test_ttl_expiry(monkeypatch):
+ calls = []
+
+ @ttl_cached(ttl=1)
+ def compute():
+ calls.append(1)
+ return len(calls)
+
+ real_time = time.time
+ assert compute() == 1
+ monkeypatch.setattr(time, 'time', lambda: real_time() + 5)
+ assert compute() == 2
+
+
+def test_key_fn_separates_arguments():
+ calls = []
+
+ @ttl_cached(ttl=60, key_fn=lambda name: name)
+ def compute(name):
+ calls.append(name)
+ return f'value-{name}'
+
+ assert compute('a') == 'value-a'
+ assert compute('b') == 'value-b'
+ assert compute('a') == 'value-a'
+ assert calls == ['a', 'b']
+
+
+def test_none_results_are_not_cached():
+ calls = []
+
+ @ttl_cached(ttl=60)
+ def flaky():
+ calls.append(1)
+ return None if len(calls) == 1 else 'ok'
+
+ assert flaky() is None
+ assert flaky() == 'ok'
+ assert len(calls) == 2
+
+
+def test_install_profile_capabilities_ride_the_decorator(app, monkeypatch):
+ from app.services import install_profile_service as ips
+ probes = []
+ monkeypatch.setattr(ips, '_docker_usable', lambda: probes.append(1) or True)
+ monkeypatch.setattr(ips, '_binary_present', lambda name: True)
+
+ ips.get_capabilities(force_refresh=True)
+ first = len(probes)
+ ips.get_capabilities()
+ assert len(probes) == first, 'second call within TTL must not re-probe'
+ ips.get_capabilities(force_refresh=True)
+ assert len(probes) == first + 1, 'force_refresh must re-probe'
+
+
+def test_no_new_module_level_ttl_dicts():
+ """Ratchet: no new `{'data': …, 'timestamp': …}`-style module TTL caches.
+
+ Frozen allowlist (2026-08-19): caches whose semantics genuinely don't fit
+ (non-JSON values, lock-guarded snapshots, explicit invalidation networks).
+ """
+ allowed = {
+ 'container_status_service.py', # lock-guarded non-JSON _ContainerIndex snapshot
+ 'survey_service.py', # cache-forever bundled catalog, force param
+ 'registry_service.py', # remote-index engine (plan 77 F1 owns it)
+ 'theme_registry_service.py', # remote-index engine (plan 77 F1 owns it)
+ 'template_service.py', # remote-index engine (plan 77 F1 owns it)
+ 'security_feed_service.py', # remote-index engine (plan 77 F1 owns it)
+ }
+ pattern = re.compile(r"^_\w*cache\w*\s*(?::[^=]+)?=\s*\{[^}]*'timestamp'", re.M)
+ offenders = []
+ for f in sorted(SERVICES.glob('*.py')):
+ if f.name in allowed:
+ continue
+ if pattern.search(f.read_text(encoding='utf-8', errors='replace')):
+ offenders.append(f.name)
+ assert not offenders, (
+ f'Hand-rolled module TTL caches in {offenders} — use '
+ '@ttl_cached from cache_service (plan 77 F2).'
+ )