+ Origins (full URL, no trailing slash) allowed to open WebSocket connections to this instance — one per line, or comma-separated. Leave empty for same-origin only (the secure default; works for direct access and most reverse-proxy setups). Add your public domain here if you reach SoulSync via a reverse proxy or custom domain and the WebSocket fails to connect. Use * on its own line to allow any origin (insecure — only do this if you understand why you need it).
+
+
diff --git a/webui/static/helper.js b/webui/static/helper.js
index 8c6553c1..cae52460 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3441,6 +3441,11 @@ function closeHelperSearch() {
// projects that span multiple commits before shipping. Strip the flag at
// release time and add a real `date:` line at the top of the version block.
const WHATS_NEW = {
+ '2.4.1': [
+ // --- post-2.4.0 dev work — entries hidden by _getLatestWhatsNewVersion until the build version bumps ---
+ { date: 'Unreleased — 2.4.1 dev cycle' },
+ { title: 'Lock Down Socket.IO CORS', desc: 'socket.io was accepting websocket connections from any origin (cors=*). now defaults to same-origin only. if your websocket fails after updating, the server logs a clear warning with the rejected origin — add it to settings → security → allowed websocket origins.', page: 'settings' },
+ ],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
{ date: 'April 26, 2026 — 2.4.0 release' },
diff --git a/webui/static/settings.js b/webui/static/settings.js
index 7d10dabf..f2026891 100644
--- a/webui/static/settings.js
+++ b/webui/static/settings.js
@@ -996,6 +996,11 @@ async function loadSettingsData() {
const requirePin = settings.security?.require_pin_on_launch || false;
document.getElementById('security-require-pin').checked = requirePin;
+ // CORS origins — stored verbatim as the user typed (string).
+ const corsOrigins = settings.security?.cors_origins || '';
+ const corsField = document.getElementById('security-cors-origins');
+ if (corsField) corsField.value = corsOrigins;
+
// Check if admin has a PIN set
const profilesRes = await fetch('/api/profiles');
const profilesData = await profilesRes.json();
@@ -2587,6 +2592,7 @@ async function saveSettings(quiet = false) {
},
security: {
require_pin_on_launch: document.getElementById('security-require-pin')?.checked || false,
+ cors_origins: document.getElementById('security-cors-origins')?.value?.trim() || '',
}
};
From 0f24739e27b8d18fb6f9824a93399ec9734a6c61 Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 17:32:22 -0700
Subject: [PATCH 005/145] =?UTF-8?q?Socket.IO=20CORS:=20polish=20=E2=80=94?=
=?UTF-8?q?=20match=20engineio=20exactly,=20bound=20dedup,=20validate=20UR?=
=?UTF-8?q?Ls?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Self-review pass on the security fix uncovered five issues, all fixed
here:
1. will_reject scheme handling. Engineio compares full {scheme}://{host}
strings, not just hostnames. A TLS-terminating proxy can leave the
backend seeing http while the browser's Origin is https — engineio
rejects, but the original predictor said "allow" → no helpful log
line. Added request_scheme + forwarded_proto params, build full
candidate strings to match engineio.
2. EITHER-forwarded-header rule. Engineio adds the forwarded candidate
when EITHER X-Forwarded-Proto OR X-Forwarded-Host is present (it
falls back to HTTP_HOST for the missing one). The original predictor
only added it when forwarded_host was set — false negative for
misconfigs sending only X-Forwarded-Proto. Now mirrors engineio.
3. will_reject incorrectly rejected missing-Origin requests. Engineio
(server.py:207: `if origin: validate`) skips CORS validation when
no Origin header is sent — non-browser clients (curl etc.) are
intentionally permitted. The original code rejected them. Test was
asserting the wrong behavior. Both fixed.
4. RejectionLogger had unbounded dedup set growth. A hostile actor
opening connections from many distinct fake origins would fill
memory unboundedly. Capped at 100 unique origins (configurable);
when cap hit, one overflow notice is emitted and further rejections
are silently dropped until restart.
5. Lock pattern: the overflow log path called logger.warning() while
holding the dedup lock, inconsistent with the normal path. Fixed
to pick the message under the lock and log after release. Critical
section is now minimal and uniform.
Plus polish:
- Stale module docstring fixed (said "empty list" instead of "None").
- settings.js validates each cors_origins line against a URL regex on
save; toasts a one-shot warning if entries are malformed (resolver
silently filters them, but user gets feedback now).
- web_server.py wiring passes request.scheme + X-Forwarded-Proto so
the predictor has full proxy info.
Tests:
- 51 unit tests in tests/test_socketio_cors.py (was 45). New cases:
* scheme comparison (5 cases including TLS-terminating proxies)
* forwarded_proto-alone misconfig
* missing-origin matches engineio (was asserting wrong behavior)
* dedup cap with overflow + reset
* default cap is reasonable (uses public DEFAULT_DEDUP_CAP constant)
Engineio behavior independently verified by reading engineio/server.py
and engineio/base_server.py source. Predictor mirrors both files.
604 tests pass.
---
core/socketio_cors.py | 125 ++++++++++++++++++++++++++++--------
tests/test_socketio_cors.py | 121 +++++++++++++++++++++++++++++++++-
web_server.py | 2 +
webui/static/settings.js | 21 ++++++
4 files changed, 241 insertions(+), 28 deletions(-)
diff --git a/core/socketio_cors.py b/core/socketio_cors.py
index 61b4e4ce..ef41206f 100644
--- a/core/socketio_cors.py
+++ b/core/socketio_cors.py
@@ -5,8 +5,9 @@ Three concerns lifted out of `web_server.py`:
- :func:`resolve_cors_origins` — read the user's
``security.cors_origins`` config setting (string, list, or unset) and
return what to hand to Flask-SocketIO's ``cors_allowed_origins``
- parameter: an empty list (same-origin only), the literal ``'*'``
- (wildcard, opt-in), or a list of explicit origin URLs.
+ parameter: ``None`` (engineio same-origin default — the secure
+ default), the literal ``'*'`` (wildcard, opt-in), or a list of
+ explicit origin URLs.
- :func:`will_reject` — predict whether engineio's CORS check will
reject a request, given the resolved allow-list, the request's
@@ -88,9 +89,11 @@ def resolve_cors_origins(config_manager: Any) -> ResolvedOrigins:
def will_reject(
allowed: ResolvedOrigins,
- origin: str,
+ origin: Optional[str],
host: str,
+ request_scheme: str = '',
forwarded_host: str = '',
+ forwarded_proto: str = '',
) -> bool:
"""Predict whether engineio's CORS check will reject this request.
@@ -98,22 +101,64 @@ def will_reject(
a helpful warning *before* the rejection happens. Returns ``True``
when the request will be rejected.
- Same-origin check: ``Origin``'s ``host[:port]`` portion matches the
- request's ``Host`` header OR the ``X-Forwarded-Host`` header. Engineio
- checks both when ``cors_allowed_origins`` is ``None``; we mirror that
- so reverse-proxy users with proper proxy headers don't trigger
- spurious "rejected" log lines.
+ Same-origin check: engineio builds full ``{scheme}://{host}`` strings
+ from the request URL — and adds a second candidate from the
+ forwarded headers when EITHER ``X-Forwarded-Proto`` OR
+ ``X-Forwarded-Host`` is present (engineio falls back to the request
+ Host / scheme for whichever forwarded header is missing). We mirror
+ that exactly. Comparing scheme matters: a TLS-terminating proxy can
+ leave the backend seeing ``http://soulsync.foo`` while the browser's
+ Origin is ``https://soulsync.foo`` — engineio treats those as
+ different strings and rejects, so we should too.
+
+ Defensive against ``None`` / empty origin: returns ``False`` (allow),
+ matching engineio's actual behavior (server.py:207: ``if origin:``
+ skips the validation block entirely when no Origin header is sent).
+ Browsers always send Origin for WebSocket upgrades, so this only
+ matters for non-browser clients like ``curl`` — which engineio
+ intentionally permits.
+
+ Proxy params default to empty so callers without proxy awareness
+ fall back to a host-only same-origin check (still correct for
+ direct-access setups).
"""
if allowed == '*':
return False
+ if not origin:
+ return False # Engineio skips CORS validation when no Origin header
if isinstance(allowed, list) and origin in allowed:
return False
- # Origin is "scheme://host[:port][/path]"; pull just host[:port].
- origin_host = origin.split('://', 1)[-1].split('/', 1)[0]
- if host and origin_host == host:
- return False
- if forwarded_host and origin_host == forwarded_host.split(',')[0].strip():
+
+ # Engineio's same-origin check builds full {scheme}://{host} strings.
+ # Build the candidate set from the request + any forwarded headers.
+ candidates = []
+ if host:
+ scheme = request_scheme or 'http'
+ candidates.append(f"{scheme}://{host}")
+ if forwarded_host or forwarded_proto:
+ # Mirror engineio: when EITHER forwarded header is present, build
+ # a candidate from both, falling back to the request value for
+ # whichever is missing. (engineio/base_server.py:_cors_allowed_origins.)
+ f_host = forwarded_host.split(',')[0].strip() if forwarded_host else host
+ if f_host:
+ f_scheme = (forwarded_proto.split(',')[0].strip()
+ if forwarded_proto
+ else (request_scheme or 'http'))
+ candidates.append(f"{f_scheme}://{f_host}")
+ if origin in candidates:
return False
+
+ # Backwards-compat shim: callers that don't pass scheme info still
+ # get the original host-only same-origin check, so callers / tests
+ # that exercise this predicate without a real Flask request context
+ # don't get spurious rejections. Production callers always pass
+ # scheme, so this branch is inert in normal operation.
+ if not request_scheme and not forwarded_proto:
+ origin_host = origin.split('://', 1)[-1].split('/', 1)[0]
+ if host and origin_host == host:
+ return False
+ if forwarded_host and origin_host == forwarded_host.split(',')[0].strip():
+ return False
return True
@@ -126,22 +171,30 @@ class RejectionLogger:
requests via :meth:`maybe_log` and emits a clear warning the first
time each unique origin appears, telling the user where to add it.
- Bounded by the number of unique origins ever attempted; cleared on
- process restart. The dedup is intentional — a malicious site
- hammering the endpoint shouldn't be able to spam logs.
+ The dedup set is capped (default 100 unique origins) so a hostile
+ actor opening connections from many distinct fake origins can't grow
+ memory unbounded. When the cap is hit, a single overflow warning is
+ emitted and further rejections are silently dropped until the next
+ process restart (or :meth:`reset_for_tests` for tests).
"""
- def __init__(self, logger: Any):
+ DEFAULT_DEDUP_CAP = 100
+
+ def __init__(self, logger: Any, dedup_cap: int = DEFAULT_DEDUP_CAP):
self._logger = logger
self._seen: Set[str] = set()
self._lock = threading.Lock()
+ self._cap = max(1, int(dedup_cap))
+ self._overflow_warned = False
def maybe_log(
self,
allowed: ResolvedOrigins,
origin: Optional[str],
host: str,
+ request_scheme: str = '',
forwarded_host: str = '',
+ forwarded_proto: str = '',
) -> bool:
"""Log a rejection warning if applicable, deduped.
@@ -149,27 +202,49 @@ class RejectionLogger:
be safe to call from a Flask ``before_request`` hook on every
Socket.IO request — it short-circuits early on requests that
won't be rejected (no Origin header, allowed origin, same-origin
- match against either Host or X-Forwarded-Host).
+ match against Host / X-Forwarded-Host with proper scheme).
"""
if not origin:
return False # Non-browser clients (curl, server-to-server)
- if not will_reject(allowed, origin, host, forwarded_host):
+ if not will_reject(allowed, origin, host, request_scheme,
+ forwarded_host, forwarded_proto):
return False
+
+ # Pick the message to emit (or bail) under the lock. Actual
+ # logger.warning() call happens AFTER the lock releases — keeps
+ # the critical section minimal and avoids holding our lock while
+ # the logging framework acquires its own internal locks.
+ msg: Optional[str] = None
with self._lock:
if origin in self._seen:
return False
- self._seen.add(origin)
- self._logger.warning(
- f"[Socket.IO] Rejecting WebSocket connection from origin '{origin}' "
- f"(request Host='{host}'). If this is your reverse-proxy or custom "
- f"domain, add it to Settings → Security → Allowed WebSocket Origins."
- )
+ if len(self._seen) >= self._cap:
+ if self._overflow_warned:
+ return False # Already emitted overflow notice; suppress.
+ self._overflow_warned = True
+ msg = (
+ f"[Socket.IO] Rejection-log dedup cache hit cap "
+ f"({self._cap} unique origins). Suppressing further "
+ f"rejection warnings this session — likely indicates "
+ f"hostile traffic or a misconfigured client. Restart "
+ f"to reset the cache."
+ )
+ else:
+ self._seen.add(origin)
+ msg = (
+ f"[Socket.IO] Rejecting WebSocket connection from origin "
+ f"'{origin}' (request Host='{host}'). If this is your "
+ f"reverse-proxy or custom domain, add it to "
+ f"Settings → Security → Allowed WebSocket Origins."
+ )
+ self._logger.warning(msg)
return True
def reset_for_tests(self) -> None:
"""Clear the dedup cache. Test-only."""
with self._lock:
self._seen.clear()
+ self._overflow_warned = False
def log_startup_status(allowed: ResolvedOrigins, logger: Any) -> None:
diff --git a/tests/test_socketio_cors.py b/tests/test_socketio_cors.py
index 267260e0..278f443a 100644
--- a/tests/test_socketio_cors.py
+++ b/tests/test_socketio_cors.py
@@ -20,7 +20,6 @@ These pin the security-relevant behavior:
Pure unit tests — no Flask, no engineio, no network. Just the logic.
"""
-import logging
import threading
from typing import Any, List
@@ -201,6 +200,82 @@ def test_will_reject_honors_x_forwarded_host():
forwarded_host='') is False
+def test_will_reject_compares_full_scheme_when_known():
+ """When the caller provides scheme info, engineio compares full
+ {scheme}://{host} strings. A TLS-terminating proxy can leave the
+ backend seeing http while the browser's Origin is https — engineio
+ rejects, our predictor must too (otherwise we miss logging it)."""
+ # Backend sees http, browser sent https → engineio rejects → we predict reject
+ assert will_reject(None, 'https://soulsync.foo', 'soulsync.foo',
+ request_scheme='http') is True
+
+ # Backend sees http, browser sent http → match → allow
+ assert will_reject(None, 'http://soulsync.foo', 'soulsync.foo',
+ request_scheme='http') is False
+
+ # X-Forwarded-Proto says the public request was https → match origin's https
+ assert will_reject(None, 'https://soulsync.foo', 'internal:8888',
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https') is False
+
+ # X-Forwarded-Proto says https but Origin is http → mismatch → reject
+ assert will_reject(None, 'http://soulsync.foo', 'internal:8888',
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https') is True
+
+ # Comma-separated X-Forwarded-Proto (proxy chain) — first wins, like engineio
+ assert will_reject(None, 'https://soulsync.foo', 'internal:8888',
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https, http') is False
+
+
+def test_will_reject_falls_back_to_host_only_when_no_scheme_info():
+ """Backwards-compat shim: callers that don't pass scheme info still
+ get the basic Host-only same-origin check (the original behavior).
+ Important for any integration tests that exercise the predicate
+ without a real Flask request context."""
+ # No scheme info → host-only match works
+ assert will_reject(None, 'https://soulsync.foo', 'soulsync.foo') is False
+ assert will_reject(None, 'http://x.com', 'x.com') is False
+ # Cross-origin still rejected
+ assert will_reject(None, 'https://attacker.com', 'soulsync.foo') is True
+
+
+def test_will_reject_allows_missing_origin_matching_engineio():
+ """Engineio (server.py:207: ``if origin:``) skips CORS validation
+ entirely when no Origin header is sent — non-browser clients (curl,
+ server-to-server) are intentionally permitted. Our predictor must
+ match that or we'd log spurious "rejected" warnings for legitimate
+ non-browser traffic. Must also not raise on None input."""
+ # Wildcard permits missing origin — and so does the default policy
+ # (matches engineio's actual behavior).
+ assert will_reject('*', None, 'localhost:8888') is False
+ assert will_reject('*', '', 'localhost:8888') is False
+ assert will_reject(None, None, 'localhost:8888') is False
+ assert will_reject(None, '', 'localhost:8888') is False
+ assert will_reject(['https://x.com'], None, 'localhost:8888') is False
+
+
+def test_will_reject_honors_forwarded_proto_alone():
+ """Engineio adds the forwarded candidate when EITHER X-Forwarded-Proto
+ OR X-Forwarded-Host is present (it falls back to HTTP_HOST for the
+ missing one). Our predictor must mirror that — otherwise a misconfig
+ sending only X-Forwarded-Proto would look like a rejection in our
+ log even though engineio actually allows it."""
+ # forwarded_proto alone: backend host stands in for forwarded_host
+ assert will_reject(None, 'https://localhost:8888', 'localhost:8888',
+ request_scheme='http',
+ forwarded_proto='https') is False
+
+ # forwarded_proto alone but origin's host doesn't match the backend host
+ assert will_reject(None, 'https://attacker.com', 'localhost:8888',
+ request_scheme='http',
+ forwarded_proto='https') is True
+
+
# ── RejectionLogger ───────────────────────────────────────────────────────
@@ -230,8 +305,11 @@ def test_rejection_logger_silent_when_request_would_be_allowed():
rl.maybe_log('*', 'https://x.com', 'localhost:8888')
# In allow-list — no warning
rl.maybe_log(['https://x.com'], 'https://x.com', 'localhost:8888')
- # Same-origin via X-Forwarded-Host — no warning
- rl.maybe_log(None, 'https://soulsync.foo', 'internal:8888', 'soulsync.foo')
+ # Same-origin via X-Forwarded-Host (with proxy scheme info) — no warning
+ rl.maybe_log(None, 'https://soulsync.foo', 'internal:8888',
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https')
assert log.warnings == []
@@ -297,6 +375,43 @@ def test_rejection_logger_reset_for_tests_clears_dedup():
assert len(log.warnings) == 2 # logged again after reset
+def test_rejection_logger_caps_dedup_set_at_configured_limit():
+ """A hostile actor opening connections from many distinct fake origins
+ would otherwise grow the dedup set unbounded. After the cap is hit,
+ further rejections are silently dropped (after one overflow notice)."""
+ log = _CapturingLogger()
+ rl = RejectionLogger(log, dedup_cap=5)
+
+ # Fill the cap
+ for i in range(5):
+ rl.maybe_log(None, f'https://fake{i}.com', 'localhost:8888')
+ assert len(log.warnings) == 5
+
+ # Next unique origin → overflow notice, NOT a per-origin warning
+ rl.maybe_log(None, 'https://fake5.com', 'localhost:8888')
+ assert len(log.warnings) == 6
+ assert 'cap' in log.warnings[5].lower() or 'suppress' in log.warnings[5].lower()
+
+ # Further unique origins → silently dropped (overflow notice already emitted)
+ for i in range(6, 20):
+ rl.maybe_log(None, f'https://fake{i}.com', 'localhost:8888')
+ assert len(log.warnings) == 6 # unchanged
+
+ # After reset, cap restarts
+ rl.reset_for_tests()
+ rl.maybe_log(None, 'https://fake0.com', 'localhost:8888')
+ assert len(log.warnings) == 7
+
+
+def test_rejection_logger_default_cap_is_reasonable():
+ """The default cap should be high enough that legitimate-but-unusual
+ setups (e.g., a power user with a dozen reverse-proxy domains rotating)
+ don't hit the overflow notice during normal use."""
+ assert RejectionLogger.DEFAULT_DEDUP_CAP >= 50, (
+ "default dedup cap should fit normal usage"
+ )
+
+
# ── log_startup_status ────────────────────────────────────────────────────
diff --git a/web_server.py b/web_server.py
index 77690b3b..80e929e9 100644
--- a/web_server.py
+++ b/web_server.py
@@ -235,7 +235,9 @@ def _log_rejected_socketio_origin():
_socketio_cors_origins,
request.headers.get('Origin'),
request.headers.get('Host', ''),
+ request.scheme,
request.headers.get('X-Forwarded-Host', ''),
+ request.headers.get('X-Forwarded-Proto', ''),
)
diff --git a/webui/static/settings.js b/webui/static/settings.js
index f2026891..e1f23f03 100644
--- a/webui/static/settings.js
+++ b/webui/static/settings.js
@@ -2596,6 +2596,27 @@ async function saveSettings(quiet = false) {
}
};
+ // Validate cors_origins entries — backend silently filters malformed
+ // values, so warn the user up-front if any line doesn't look like a
+ // URL (or the special '*' token). One-shot toast; doesn't block save.
+ const corsRaw = settings.security.cors_origins;
+ if (corsRaw) {
+ const entries = corsRaw.replace(/\n/g, ',').split(',')
+ .map(s => s.trim())
+ .filter(s => s);
+ const invalid = entries.filter(e => {
+ if (e === '*') return false;
+ // Accept anything matching scheme://host[:port], no path required
+ return !/^https?:\/\/[^\s/]+$/i.test(e);
+ });
+ if (invalid.length) {
+ showToast(
+ `Allowed Origins: ${invalid.length} entr${invalid.length === 1 ? 'y looks' : 'ies look'} malformed (need full URL like https://soulsync.example.com, no trailing slash). Saving anyway — they\'ll be ignored.`,
+ 'warning'
+ );
+ }
+ }
+
try {
if (!quiet) showLoadingOverlay('Saving settings...');
From 77a781caba3886511ab6af6ee7384feab218bd04 Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 18:02:20 -0700
Subject: [PATCH 006/145] Pin yt-dlp in requirements.txt, drop pip install from
entrypoint
Closes #367 (reported by JohnBaumb).
The Docker entrypoint ran `pip install -U yt-dlp --quiet --no-cache-dir`
on every container start. Three problems with that:
- Non-deterministic startup: each restart could pick up a different
yt-dlp version, making "works on my machine" debugging harder.
- Network dependency at boot: PyPI being slow/unreachable gated the
app coming up.
- In-place upgrades inside running containers can race with active
yt-dlp invocations and aren't a great pattern.
Picked Option A from the issue: pin to an exact version in
requirements.txt (`yt-dlp==2026.3.17`) and remove the entrypoint
install entirely. yt-dlp comes baked into the image now via the
existing `pip install -r requirements.txt` in the Dockerfile.
Tradeoff: YouTube fixes ship via SoulSync releases now instead of
"next container restart". The pin is documented inline with how to
bump it.
Net change: -3 entrypoint lines, requirements.txt pin tightened,
WHATS_NEW '2.4.1' block opened (entries hidden until version bumps).
553 tests pass.
---
entrypoint.sh | 4 ----
requirements.txt | 7 ++++++-
webui/static/helper.js | 5 +++++
3 files changed, 11 insertions(+), 5 deletions(-)
diff --git a/entrypoint.sh b/entrypoint.sh
index 4845aff1..1c9f1382 100644
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -69,10 +69,6 @@ chown -R soulsync:soulsync /app/config /app/data /app/logs /app/downloads /app/T
echo "✅ Configuration initialized successfully"
-# Auto-update yt-dlp — YouTube changes their API frequently and stale versions break downloads
-echo "🔄 Updating yt-dlp..."
-pip install -U yt-dlp --quiet --no-cache-dir 2>/dev/null && echo " ✅ yt-dlp updated" || echo " ⚠️ yt-dlp update failed (will use existing version)"
-
# Display final user info
echo "👤 Running as:"
echo " User: $(id -u soulsync):$(id -g soulsync) ($(id -un soulsync):$(id -gn soulsync))"
diff --git a/requirements.txt b/requirements.txt
index 92cdcc06..107cfa6b 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -28,7 +28,12 @@ beautifulsoup4>=4.12.0
psutil>=6.0.0
# YouTube support
-yt-dlp>=2024.12.13
+# Pinned to an exact version for reproducible builds. The Docker
+# entrypoint used to `pip install -U yt-dlp` on every container start,
+# which made startup non-deterministic and depended on PyPI being
+# reachable. Bump this pin in a SoulSync release when yt-dlp ships a
+# YouTube-fix update — that's the supported upgrade path now.
+yt-dlp==2026.3.17
# Lyrics support
lrclibapi>=0.3.1
diff --git a/webui/static/helper.js b/webui/static/helper.js
index 8c6553c1..0f3233df 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3441,6 +3441,11 @@ function closeHelperSearch() {
// projects that span multiple commits before shipping. Strip the flag at
// release time and add a real `date:` line at the top of the version block.
const WHATS_NEW = {
+ '2.4.1': [
+ // --- post-2.4.0 dev work — entries hidden by _getLatestWhatsNewVersion until the build version bumps ---
+ { date: 'Unreleased — 2.4.1 dev cycle' },
+ { title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.', page: 'settings' },
+ ],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
{ date: 'April 26, 2026 — 2.4.0 release' },
From 22fda5dd9424d396e453ae0de4fcef1db8e11f81 Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 18:30:12 -0700
Subject: [PATCH 007/145] Trim yt-dlp pin comment, drop misleading WHATS_NEW
page link
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Self-review nits on PR #384:
- requirements.txt: 5-line comment for one pin → 1 line. Rationale
lives in commit body and #367; no need to repeat in-tree.
- helper.js: dropped `page: 'settings'` from the yt-dlp WHATS_NEW
entry. Settings page has no yt-dlp UI; the link would have
navigated users somewhere irrelevant.
553 tests pass.
---
requirements.txt | 7 +------
webui/static/helper.js | 2 +-
2 files changed, 2 insertions(+), 7 deletions(-)
diff --git a/requirements.txt b/requirements.txt
index 107cfa6b..16d2b801 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -27,12 +27,7 @@ beautifulsoup4>=4.12.0
# System monitoring
psutil>=6.0.0
-# YouTube support
-# Pinned to an exact version for reproducible builds. The Docker
-# entrypoint used to `pip install -U yt-dlp` on every container start,
-# which made startup non-deterministic and depended on PyPI being
-# reachable. Bump this pin in a SoulSync release when yt-dlp ships a
-# YouTube-fix update — that's the supported upgrade path now.
+# YouTube support — pinned for reproducible builds; bump per release. See #367.
yt-dlp==2026.3.17
# Lyrics support
diff --git a/webui/static/helper.js b/webui/static/helper.js
index 0f3233df..6583b7e9 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3444,7 +3444,7 @@ const WHATS_NEW = {
'2.4.1': [
// --- post-2.4.0 dev work — entries hidden by _getLatestWhatsNewVersion until the build version bumps ---
{ date: 'Unreleased — 2.4.1 dev cycle' },
- { title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.', page: 'settings' },
+ { title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.' },
],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
From dd4cf130d723ef62757aa1fb69273b3a474a04fc Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 19:24:43 -0700
Subject: [PATCH 008/145] Socket.IO CORS: handle self-review nits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Six items from a Cin-style line-by-line pass on PR #383:
- resolve_cors_origins: list of non-string entries (`[None, 123]`) now
drops them instead of coercing to junk strings like `'None'`/`'123'`.
- will_reject: backwards-compat shim removed. Production callers always
pass `request.scheme` (Flask-guaranteed); the shim only existed for
tests/non-Flask callers and made the production code path branchier
than necessary. Tests now pass scheme explicitly.
- maybe_log: redundant `if not origin` early-return dropped. will_reject
handles missing origin (engineio's own behavior — server.py:207).
- RejectionLogger.__init__: `int(dedup_cap)` wrapped in try/except so
bad-type input falls back to DEFAULT_DEDUP_CAP instead of raising.
- web_server.py: docstring on the before_request hook explains why the
hook fires on every request (Flask doesn't scope before_request to a
path prefix; the early-return string compare is the cheapest option).
- settings.js: cors-origins URL regex tightened from `[^\s/]+` to
`[^\s/?#]+` so query/fragment chars don't pass validation. Engineio
would silently fail to match those anyway; better to flag at save.
Test changes:
- parametrize gained an explicit `scheme` column (12 cases updated).
- New explicit case: scheme-mismatch rejects (engineio compares full
`{scheme}://{host}` strings).
- `test_will_reject_falls_back_to_host_only_when_no_scheme_info`
deleted — the shim it tested is gone.
- `test_will_reject_honors_x_forwarded_host` now passes scheme info.
Net: -9 production lines, -3 test lines. Production code path is
straight-line. 603 tests pass.
---
core/socketio_cors.py | 34 +++++++------------
tests/test_socketio_cors.py | 68 +++++++++++++++++--------------------
web_server.py | 8 ++++-
webui/static/settings.js | 5 +--
4 files changed, 53 insertions(+), 62 deletions(-)
diff --git a/core/socketio_cors.py b/core/socketio_cors.py
index ef41206f..425a464e 100644
--- a/core/socketio_cors.py
+++ b/core/socketio_cors.py
@@ -76,7 +76,9 @@ def resolve_cors_origins(config_manager: Any) -> ResolvedOrigins:
return None
parts = [p.strip() for p in raw.replace('\n', ',').split(',')]
elif isinstance(raw, (list, tuple)):
- parts = [str(p).strip() for p in raw]
+ # Drop non-string entries instead of stringifying — `[None]` would
+ # otherwise coerce to ``['None']`` and become a junk allow-list entry.
+ parts = [p.strip() for p in raw if isinstance(p, str)]
else:
return None
parts = [p for p in parts if p]
@@ -118,9 +120,10 @@ def will_reject(
matters for non-browser clients like ``curl`` — which engineio
intentionally permits.
- Proxy params default to empty so callers without proxy awareness
- fall back to a host-only same-origin check (still correct for
- direct-access setups).
+ ``request_scheme`` is required for an accurate same-origin match —
+ engineio compares full ``{scheme}://{host}`` strings, so callers
+ that omit it default to ``'http'``. Production wires Flask's
+ ``request.scheme`` here, which WSGI guarantees to be non-empty.
"""
if allowed == '*':
return False
@@ -145,21 +148,7 @@ def will_reject(
if forwarded_proto
else (request_scheme or 'http'))
candidates.append(f"{f_scheme}://{f_host}")
- if origin in candidates:
- return False
-
- # Backwards-compat shim: callers that don't pass scheme info still
- # get the original host-only same-origin check, so callers / tests
- # that exercise this predicate without a real Flask request context
- # don't get spurious rejections. Production callers always pass
- # scheme, so this branch is inert in normal operation.
- if not request_scheme and not forwarded_proto:
- origin_host = origin.split('://', 1)[-1].split('/', 1)[0]
- if host and origin_host == host:
- return False
- if forwarded_host and origin_host == forwarded_host.split(',')[0].strip():
- return False
- return True
+ return origin not in candidates
class RejectionLogger:
@@ -184,7 +173,10 @@ class RejectionLogger:
self._logger = logger
self._seen: Set[str] = set()
self._lock = threading.Lock()
- self._cap = max(1, int(dedup_cap))
+ try:
+ self._cap = max(1, int(dedup_cap))
+ except (TypeError, ValueError):
+ self._cap = self.DEFAULT_DEDUP_CAP
self._overflow_warned = False
def maybe_log(
@@ -204,8 +196,6 @@ class RejectionLogger:
won't be rejected (no Origin header, allowed origin, same-origin
match against Host / X-Forwarded-Host with proper scheme).
"""
- if not origin:
- return False # Non-browser clients (curl, server-to-server)
if not will_reject(allowed, origin, host, request_scheme,
forwarded_host, forwarded_proto):
return False
diff --git a/tests/test_socketio_cors.py b/tests/test_socketio_cors.py
index 278f443a..b54d94d3 100644
--- a/tests/test_socketio_cors.py
+++ b/tests/test_socketio_cors.py
@@ -139,43 +139,42 @@ def test_resolve_cors_origins_never_silently_returns_wildcard_for_garbage():
# ── will_reject ───────────────────────────────────────────────────────────
-@pytest.mark.parametrize("allowed, origin, host, expected_reject", [
- # Same-origin (Origin's host:port matches the request Host) — allow
- (None, 'http://localhost:8888', 'localhost:8888', False),
- (None, 'http://192.168.1.5:8888','192.168.1.5:8888',False),
- (None, 'https://soulsync.foo', 'soulsync.foo', False),
+@pytest.mark.parametrize("allowed, origin, host, scheme, expected_reject", [
+ # Same-origin (Origin's full {scheme}://{host} matches request) — allow
+ (None, 'http://localhost:8888', 'localhost:8888', 'http', False),
+ (None, 'http://192.168.1.5:8888', '192.168.1.5:8888', 'http', False),
+ (None, 'https://soulsync.foo', 'soulsync.foo', 'https', False),
# Cross-origin with default allow-list — reject
- (None, 'https://x.com', 'localhost:8888', True),
- (None, 'https://soulsync.foo', 'localhost:8888', True), # reverse proxy NOT forwarding Host
+ (None, 'https://x.com', 'localhost:8888', 'http', True),
+ (None, 'https://soulsync.foo', 'localhost:8888', 'http', True), # reverse proxy NOT forwarding Host
+ # Scheme mismatch — engineio rejects, so do we
+ (None, 'https://soulsync.foo', 'soulsync.foo', 'http', True),
# Wildcard short-circuit — allow
- ('*', 'https://x.com', 'localhost:8888', False),
- ('*', 'https://anything.evil', 'localhost:8888', False),
+ ('*', 'https://x.com', 'localhost:8888', 'http', False),
+ ('*', 'https://anything.evil', 'localhost:8888', 'http', False),
# Origin in allow-list — allow
- (['https://x.com'], 'https://x.com', 'localhost:8888', False),
- (['https://soulsync.foo'], 'https://soulsync.foo', 'localhost:8888', False),
+ (['https://x.com'], 'https://x.com', 'localhost:8888', 'http', False),
+ (['https://soulsync.foo'], 'https://soulsync.foo', 'localhost:8888', 'http', False),
# Cross-origin not in allow-list — reject
- (['https://x.com'], 'https://y.com', 'localhost:8888', True),
+ (['https://x.com'], 'https://y.com', 'localhost:8888', 'http', True),
# Same-origin still works even when allow-list has other entries
- (['https://x.com'], 'http://localhost:8888', 'localhost:8888', False),
-
- # Origin with path component — only host:port should be compared
- (None, 'http://x.com:8080/path', 'x.com:8080', False),
+ (['https://x.com'], 'http://localhost:8888', 'localhost:8888', 'http', False),
])
-def test_will_reject_predicts_engineio_decision(allowed, origin, host, expected_reject):
- assert will_reject(allowed, origin, host) is expected_reject
+def test_will_reject_predicts_engineio_decision(allowed, origin, host, scheme, expected_reject):
+ assert will_reject(allowed, origin, host, request_scheme=scheme) is expected_reject
def test_will_reject_with_empty_host_only_uses_allowlist():
"""If the request somehow has no Host header (shouldn't happen but be
safe), same-origin can't be checked — fall through to allow-list only."""
- assert will_reject(None, 'https://x.com', '') is True
- assert will_reject(['https://x.com'], 'https://x.com', '') is False
- assert will_reject('*', 'https://x.com', '') is False
+ assert will_reject(None, 'https://x.com', '', request_scheme='https') is True
+ assert will_reject(['https://x.com'], 'https://x.com', '', request_scheme='https') is False
+ assert will_reject('*', 'https://x.com', '', request_scheme='https') is False
def test_will_reject_honors_x_forwarded_host():
@@ -183,20 +182,27 @@ def test_will_reject_honors_x_forwarded_host():
cors_allowed_origins is None (engineio/base_server.py:_cors_allowed_origins).
Our predictor must mirror that — otherwise reverse-proxy users with
proper proxy headers would trigger spurious "rejected" log lines."""
- # Same-origin via X-Forwarded-Host (typical reverse-proxy setup)
+ # Same-origin via X-Forwarded-Host (typical TLS-terminating reverse proxy)
assert will_reject(None, 'https://soulsync.foo', 'internal:8888',
- forwarded_host='soulsync.foo') is False
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https') is False
# X-Forwarded-Host with comma list (proxy chain) — first entry wins
assert will_reject(None, 'https://soulsync.foo', 'internal:8888',
- forwarded_host='soulsync.foo, edge.proxy') is False
+ request_scheme='http',
+ forwarded_host='soulsync.foo, edge.proxy',
+ forwarded_proto='https') is False
# X-Forwarded-Host doesn't match either — still reject
assert will_reject(None, 'https://attacker.com', 'internal:8888',
- forwarded_host='soulsync.foo') is True
+ request_scheme='http',
+ forwarded_host='soulsync.foo',
+ forwarded_proto='https') is True
# X-Forwarded-Host empty — falls back to Host check (the unset case)
assert will_reject(None, 'https://soulsync.foo', 'soulsync.foo',
+ request_scheme='https',
forwarded_host='') is False
@@ -232,18 +238,6 @@ def test_will_reject_compares_full_scheme_when_known():
forwarded_proto='https, http') is False
-def test_will_reject_falls_back_to_host_only_when_no_scheme_info():
- """Backwards-compat shim: callers that don't pass scheme info still
- get the basic Host-only same-origin check (the original behavior).
- Important for any integration tests that exercise the predicate
- without a real Flask request context."""
- # No scheme info → host-only match works
- assert will_reject(None, 'https://soulsync.foo', 'soulsync.foo') is False
- assert will_reject(None, 'http://x.com', 'x.com') is False
- # Cross-origin still rejected
- assert will_reject(None, 'https://attacker.com', 'soulsync.foo') is True
-
-
def test_will_reject_allows_missing_origin_matching_engineio():
"""Engineio (server.py:207: ``if origin:``) skips CORS validation
entirely when no Origin header is sent — non-browser clients (curl,
diff --git a/web_server.py b/web_server.py
index 80e929e9..b3d47be7 100644
--- a/web_server.py
+++ b/web_server.py
@@ -228,7 +228,13 @@ _plex_pin_requests_lock = threading.Lock()
def _log_rejected_socketio_origin():
"""Hook the WS upgrade path so users see a clear log line when their
Origin is about to be rejected (engineio otherwise just silently 403s
- the upgrade). Dedup + threading lives in `core/socketio_cors`."""
+ the upgrade). Dedup + threading lives in `core/socketio_cors`.
+
+ Note: Flask's ``before_request`` runs on every HTTP request to every
+ endpoint — there's no path-scoped equivalent for arbitrary URL
+ prefixes. We early-return on non-/socket.io/ paths to keep the
+ overhead to one string compare per request.
+ """
if not request.path.startswith('/socket.io/'):
return
_socketio_rejection_logger.maybe_log(
diff --git a/webui/static/settings.js b/webui/static/settings.js
index e1f23f03..fb47a9ec 100644
--- a/webui/static/settings.js
+++ b/webui/static/settings.js
@@ -2606,8 +2606,9 @@ async function saveSettings(quiet = false) {
.filter(s => s);
const invalid = entries.filter(e => {
if (e === '*') return false;
- // Accept anything matching scheme://host[:port], no path required
- return !/^https?:\/\/[^\s/]+$/i.test(e);
+ // Accept scheme://host[:port] only — no path, query, or fragment.
+ // Engineio compares Origin against {scheme}://{host} exactly.
+ return !/^https?:\/\/[^\s/?#]+$/i.test(e);
});
if (invalid.length) {
showToast(
From 01b7d50311ed84b6d4062a306a5c518e02c00312 Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 20:01:01 -0700
Subject: [PATCH 009/145] Gate /api/settings endpoints behind admin profile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Closes #370 (reported by JohnBaumb).
The /api/settings endpoint and three siblings (/log-level,
/config-status, /verify) had no auth check — any logged-in profile
could read or modify service tokens, OAuth secrets, and API keys.
Cin's "minimum" suggestion from the issue: gate to admin profile.
Added an `admin_only` decorator near `get_current_profile_id` that
returns 403 when the current profile isn't admin (id=1). Applied
to all four endpoints.
Auth model note (documented in the decorator docstring): SoulSync's
existing model is "trust local network" — single-admin / no-multi-
profile installs default `get_current_profile_id()` to 1, so the
gate is a no-op for solo users. The decorator is meaningful in
multi-profile setups where non-admin sessions exist. Tightening to
real per-request auth is out of scope.
Did NOT consolidate with api/settings.py (Cin's "better" suggestion):
that endpoint uses API-key auth (for external tools), the web_server.py
copy uses session/profile auth (for the web UI). Different consumers,
different auth models — merging would break one or the other.
603 tests pass.
---
web_server.py | 31 +++++++++++++++++++++++++++++++
webui/static/helper.js | 1 +
2 files changed, 32 insertions(+)
diff --git a/web_server.py b/web_server.py
index b3d47be7..24d55d90 100644
--- a/web_server.py
+++ b/web_server.py
@@ -17,6 +17,7 @@ import re
import sqlite3
import types
import collections
+import functools
from pathlib import Path
from urllib.parse import quote, urljoin, urlparse
@@ -312,6 +313,32 @@ def get_current_profile_id() -> int:
except AttributeError:
return 1
+
+def admin_only(view_fn):
+ """Restrict a Flask view to the admin profile (profile_id == 1).
+
+ Settings-class endpoints expose / mutate service tokens, OAuth
+ secrets, and API keys. Non-admin profiles must not see them.
+
+ NOTE on the underlying auth model: `get_current_profile_id()`
+ defaults to 1 (admin) when no session is present, which means
+ single-admin / no-multi-profile installs have no actual gate here —
+ any request from the local network is treated as admin. This
+ decorator's job is to gate non-admin profiles in MULTI-profile
+ setups, not to authenticate the network. The "trust local network"
+ posture is the project's existing model; tightening it (real auth
+ on every request) is out of scope for this decorator.
+ """
+ @functools.wraps(view_fn)
+ def wrapper(*args, **kwargs):
+ if get_current_profile_id() != 1:
+ return jsonify({
+ "success": False,
+ "error": "Admin access required",
+ }), 403
+ return view_fn(*args, **kwargs)
+ return wrapper
+
# ── Per-profile Spotify client cache ──
_profile_spotify_clients = {} # profile_id -> SpotifyClient
_profile_spotify_lock = threading.Lock()
@@ -6286,6 +6313,7 @@ def revoke_api_key_internal(key_id):
@app.route('/api/settings', methods=['GET', 'POST'])
+@admin_only
def handle_settings():
global tidal_client # Declare that we might modify the global instance
if not config_manager:
@@ -6584,6 +6612,7 @@ def hydrabase_send():
return jsonify({"success": False, "error": str(e)}), 500
@app.route('/api/settings/log-level', methods=['GET', 'POST'])
+@admin_only
def handle_log_level():
"""Get or set the application log level"""
from utils.logging_config import set_log_level, get_current_log_level
@@ -7443,6 +7472,7 @@ def test_connection_endpoint():
@app.route('/api/settings/config-status', methods=['GET'])
+@admin_only
def settings_config_status_endpoint():
"""Return per-service config state for the Settings → Connections page.
Drives the green/yellow header gradient. No API calls — just config reads.
@@ -7516,6 +7546,7 @@ def _run_single_verify(service: str):
@app.route('/api/settings/verify', methods=['POST'])
+@admin_only
def settings_verify_endpoint():
"""Run connection verification for one or more services.
diff --git a/webui/static/helper.js b/webui/static/helper.js
index 1df719bb..be8e1a62 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3446,6 +3446,7 @@ const WHATS_NEW = {
{ date: 'Unreleased — 2.4.1 dev cycle' },
{ title: 'Lock Down Socket.IO CORS', desc: 'socket.io was accepting websocket connections from any origin (cors=*). now defaults to same-origin only. if your websocket fails after updating, the server logs a clear warning with the rejected origin — add it to settings → security → allowed websocket origins.', page: 'settings' },
{ title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.' },
+ { title: 'Settings Endpoints: Admin-Only', desc: 'the /api/settings endpoints (read, write, log-level, config-status, verify) had no auth gate — any logged-in profile could read or change service tokens, oauth secrets, api keys. now admin-only. single-admin setups (no multi-profile config) work transparently as before.', page: 'settings' },
],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
From b0e7dae7c6d130d5338e39272db0f5b71446c94c Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 21:16:41 -0700
Subject: [PATCH 010/145] Cache static assets 1y + cache discover GETs 5min
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Addresses #365 (reported by JohnBaumb), parts 1 & 2 of the proposal.
Service worker, client-side IDB/sessionStorage, and PWA manifest
deferred to follow-up PRs.
1. Static asset cache (CSS/JS/icons/fonts).
`SEND_FILE_MAX_AGE_DEFAULT` flipped from 0 to 31536000 (1 year) in
production. Safe because every static URL is bust-tagged with
`?v=static_v` (computed once per process start), so each server
restart effectively invalidates every cached asset for every user.
Within a single deploy, repeat page loads hit zero round-trips on
static files — was a 304 round-trip per asset before.
Dev override (`SOULSYNC_WEB_DEV_NO_CACHE=1`) keeps it at 0 so
iterating on JS/CSS doesn't need a server restart between edits.
Collateral fixes from the bump:
- Music streaming endpoint (L16140): `response.headers.add('Cache-Control',
'no-cache')` → bracket-assign. Under the old max-age=0, send_file
set `no-cache` and `.add()` duplicated harmlessly. Under the new
max-age=31536000, `.add()` would APPEND a second Cache-Control
value → two conflicting headers, browser-undefined behavior.
Bracket-assign replaces.
- Backup download endpoint (L25181): explicit `Cache-Control:
no-store` on the response so DB backups don't inherit the new
long max-age — sensitive content, must never cache.
2. Discover GET browser cache (5 min).
New `@app.after_request` hook scoped to `/api/discover/` and
`/api/discovery/` paths, GET method, 2xx responses only. Sets
`Cache-Control: public, max-age=300`. Skipped when the endpoint
already set its own Cache-Control. Toggling between Discover
sections within 5 min serves from browser cache, no backend hit.
Try/except wraps the hook body and logs a warning if anything
throws — never let a header-tagging bug turn a successful response
into a 500. (Logging instead of `pass` since silent except-pass is
exactly the anti-pattern issue #369 is about.)
Audited every other Cache-Control set site in web_server.py — only
the two `send_file` callers needed adjustment. Range-branch streaming
uses `Response()` directly, unaffected by the config change.
603 tests pass.
---
web_server.py | 60 ++++++++++++++++++++++++++++++++++++------
webui/static/helper.js | 1 +
2 files changed, 53 insertions(+), 8 deletions(-)
diff --git a/web_server.py b/web_server.py
index 24d55d90..6d500ffe 100644
--- a/web_server.py
+++ b/web_server.py
@@ -171,12 +171,17 @@ app = Flask(
)
app.config['TEMPLATES_AUTO_RELOAD'] = DEV_STATIC_NO_CACHE
app.jinja_env.auto_reload = DEV_STATIC_NO_CACHE
-# Force static assets (library.js / style.css / etc.) to revalidate
-# with ETag on every load instead of Flask's default 12-hour browser
-# cache. Updates ship live without users having to clear cache.
-# Modern browsers still serve 304 Not Modified when the file hasn't
-# changed, so the cost per asset per reload is just a header round-trip.
-app.config['SEND_FILE_MAX_AGE_DEFAULT'] = 0
+# Static assets (library.js / style.css / etc.) get aggressive browser
+# caching (1 year). Safe because every static URL is bust-tagged with
+# `?v=static_v` (computed once per process start — see below) so each
+# server restart effectively invalidates every cached asset for every
+# user. Within a single deploy, repeat page loads hit zero round-trips
+# on static files — was a 304 round-trip per asset under the old
+# max-age=0 setting.
+#
+# In dev, DEV_STATIC_NO_CACHE flips this back to 0 so iterating on JS
+# / CSS doesn't require a server restart between edits.
+app.config['SEND_FILE_MAX_AGE_DEFAULT'] = 0 if DEV_STATIC_NO_CACHE else 31536000
# Cache-bust query string for static assets — appended to every
@@ -306,6 +311,39 @@ def _log_slow_request(response):
return response
+
+@app.after_request
+def _add_discover_cache_headers(response):
+ """Browser-cache discover GETs for 5 minutes.
+
+ The discover surface (hero, similar artists, recent releases, release
+ radar, deep cuts, etc.) returns semi-stable data that's expensive to
+ compute and not user-action-driven within a session. A short browser
+ cache eliminates redundant fetches when the user toggles between
+ Discover sections or navigates back.
+
+ Scope: only `/api/discover/` and `/api/discovery/` paths, only GET,
+ only successful 2xx responses. Any endpoint that explicitly sets
+ its own Cache-Control wins (we don't override).
+ """
+ try:
+ if request.method != 'GET':
+ return response
+ if not (request.path.startswith('/api/discover/')
+ or request.path.startswith('/api/discovery/')):
+ return response
+ if not (200 <= response.status_code < 300):
+ return response
+ if response.headers.get('Cache-Control'):
+ return response
+ response.headers['Cache-Control'] = 'public, max-age=300'
+ except Exception as exc:
+ # Don't let a header-tagging bug turn a successful response into
+ # a 500 — log and ship the response without the cache header.
+ logger.warning(f"[discover-cache-headers] failed for {request.path}: {exc}")
+ return response
+
+
def get_current_profile_id() -> int:
"""Get the current profile ID from Flask g context or default to 1"""
try:
@@ -16099,7 +16137,9 @@ def stream_audio():
response = send_file(file_path, as_attachment=False, mimetype=mimetype)
response.headers.add('Accept-Ranges', 'bytes')
response.headers.add('Content-Length', str(file_size))
- response.headers.add('Cache-Control', 'no-cache')
+ # Override the default static-cache max-age — streaming media
+ # bypasses caching (range requests, mid-track seeks).
+ response.headers['Cache-Control'] = 'no-cache'
return response
except Exception as e:
@@ -25137,7 +25177,11 @@ def download_backup_endpoint(filename):
backup_path = os.path.join(os.path.dirname(db_path), filename)
if not os.path.exists(backup_path):
return jsonify({"success": False, "error": "Backup not found"}), 404
- return send_file(backup_path, as_attachment=True, download_name=filename)
+ # Override the default static-cache max-age — this is a sensitive
+ # DB backup, browsers should never cache it.
+ response = send_file(backup_path, as_attachment=True, download_name=filename)
+ response.headers['Cache-Control'] = 'no-store'
+ return response
except Exception as e:
return jsonify({"success": False, "error": str(e)}), 500
diff --git a/webui/static/helper.js b/webui/static/helper.js
index be8e1a62..e9560b3c 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3447,6 +3447,7 @@ const WHATS_NEW = {
{ title: 'Lock Down Socket.IO CORS', desc: 'socket.io was accepting websocket connections from any origin (cors=*). now defaults to same-origin only. if your websocket fails after updating, the server logs a clear warning with the rejected origin — add it to settings → security → allowed websocket origins.', page: 'settings' },
{ title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.' },
{ title: 'Settings Endpoints: Admin-Only', desc: 'the /api/settings endpoints (read, write, log-level, config-status, verify) had no auth gate — any logged-in profile could read or change service tokens, oauth secrets, api keys. now admin-only. single-admin setups (no multi-profile config) work transparently as before.', page: 'settings' },
+ { title: 'Browser Caching for Static Assets + Discover Pages', desc: 'static assets (js/css/icons) now get a 1-year browser cache instead of revalidating on every page load. safe because the existing ?v=static_v cache-bust query changes every server restart, so deploys still ship live. discover pages (hero, similar artists, recent releases, deep cuts, etc.) now cache 5 minutes browser-side so toggling between sections doesn\'t re-fetch everything. faster repeat loads, fewer round-trips.', page: 'discover' },
],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
From 5d9e5e57811d3c046a279141b810501fb5af0dcc Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 21:27:46 -0700
Subject: [PATCH 011/145] Discover cache: switch from public to private
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Self-review nit on b0e7dae. Discover data is user-specific (hero
artists from your watchlist, similar artists from your taste,
recently-played derivations, etc.) — `Cache-Control: public` would let
intermediate proxies (corporate caching proxy, Cloudflare with cache
rules, Nginx with proxy_cache) store one user's response and serve
it to another. Privacy leak.
Switched to `private, max-age=300`. Browser-only cache, proxies skip.
Static assets stay `public` (shared content — everyone gets the same
library.js). Streaming and backup endpoints already correct
(`no-cache` and `no-store` respectively).
603 tests pass.
---
web_server.py | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/web_server.py b/web_server.py
index 6d500ffe..8ce039e8 100644
--- a/web_server.py
+++ b/web_server.py
@@ -325,6 +325,12 @@ def _add_discover_cache_headers(response):
Scope: only `/api/discover/` and `/api/discovery/` paths, only GET,
only successful 2xx responses. Any endpoint that explicitly sets
its own Cache-Control wins (we don't override).
+
+ Uses `private` not `public` because discover data is user-specific
+ (hero artists from your watchlist, similar artists from your taste,
+ etc.). `private` keeps it browser-only — intermediate proxies
+ (corporate caching proxies, Cloudflare with cache rules, Nginx
+ proxy_cache) won't store one user's response and serve it to another.
"""
try:
if request.method != 'GET':
@@ -336,7 +342,7 @@ def _add_discover_cache_headers(response):
return response
if response.headers.get('Cache-Control'):
return response
- response.headers['Cache-Control'] = 'public, max-age=300'
+ response.headers['Cache-Control'] = 'private, max-age=300'
except Exception as exc:
# Don't let a header-tagging bug turn a successful response into
# a 500 — log and ship the response without the cache header.
From f11b91a5c6fa3886c984fe1b4680cce3d8270707 Mon Sep 17 00:00:00 2001
From: Broque Thomas <26755000+Nezreka@users.noreply.github.com>
Date: Sun, 26 Apr 2026 22:17:52 -0700
Subject: [PATCH 012/145] Service worker for cover art + PWA manifest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Addresses #365 (reported by JohnBaumb), parts 3 & 5. Client-side
IDB / sessionStorage data cache (part 4) deferred to its own PR.
Cover art on Library and Discover used to re-fetch from the source
CDN on every page visit. Now a service worker caches images locally
in CacheStorage with cache-first strategy — second visit serves art
instantly with zero network round-trips. PWA manifest added so the
app is installable to home screen / desktop.
Service worker (`webui/static/sw.js`):
- Cache-first for images: 10 known CDN hosts (Spotify, Last.fm,
Apple, Deezer, Discogs, MusicBrainz CAA, YouTube thumbnails) plus
the local `/api/image-proxy` endpoint plus same-origin .png/.jpg/
.webp/.gif/.svg paths. Cross-origin file-extension matches are
refused so we don't accidentally cache trackers.
- Stale-while-revalidate for `/static/*`: serve cached instantly,
refresh in background. Combined with the existing `?v=static_v`
cache-bust, deploys still ship live (different query → different
cache entry, old ages out).
- HTML / API / everything else: no caching, pass through.
- Cache-versioned (CACHE_VERSION = 'v1'); activate handler wipes any
cache whose name doesn't match the current version.
- skipWaiting + clients.claim so deploys propagate to open tabs
without requiring a full close-and-reopen.
PWA manifest (`webui/static/manifest.json`):
- Standalone display mode, theme color #1db954 (matches --accent-rgb).
- Two icons (192, 512) with both `any` and `maskable` purpose,
generated from favicon.png with aspect-preserving transparent
padding so the existing logo lands inside the safe zone for
OS-applied masks.
Wiring:
- `web_server.py` adds a `/sw.js` route that serves the file from
root scope (a service worker only controls URLs at or below its
served path; `/static/sw.js` would scope to `/static/*` only).
`Cache-Control: no-cache` on the SW response so deploys propagate
on next page load instead of being pinned by the 1yr static cache
the rest of /static/ uses.
- `webui/index.html` adds the manifest link, theme-color meta, and
an apple-touch-icon for iOS.
- `webui/static/init.js` registers the SW on `window.load`.
Feature-detected — no-op on browsers without serviceWorker support
or on non-secure origins (SW requires https or localhost).
One bug caught + fixed during line-by-line self-review:
`_staleWhileRevalidate` could return null to `respondWith()` when
both the cache miss AND the network fetch failed (the `.catch(() =>
null)` collapsed the rejection to null, which then short-circuited
through the falsy chain). Now explicitly awaits the network promise
and falls back to `Response.error()` when it resolves to null —
matches the `_cacheFirst` pattern.
Browser-verified: sw.js registers, status "activated and is running"
in DevTools. 603 tests pass.
---
web_server.py | 21 ++++-
webui/index.html | 3 +
webui/static/helper.js | 1 +
webui/static/init.js | 13 +++
webui/static/manifest.json | 37 ++++++++
webui/static/pwa-icon-192.png | Bin 0 -> 55141 bytes
webui/static/pwa-icon-512.png | Bin 0 -> 310286 bytes
webui/static/sw.js | 162 ++++++++++++++++++++++++++++++++++
8 files changed, 236 insertions(+), 1 deletion(-)
create mode 100644 webui/static/manifest.json
create mode 100644 webui/static/pwa-icon-192.png
create mode 100644 webui/static/pwa-icon-512.png
create mode 100644 webui/static/sw.js
diff --git a/web_server.py b/web_server.py
index 8ce039e8..8d2a06eb 100644
--- a/web_server.py
+++ b/web_server.py
@@ -22,7 +22,7 @@ from pathlib import Path
from urllib.parse import quote, urljoin, urlparse
from concurrent.futures import ThreadPoolExecutor, as_completed
-from flask import Flask, render_template, request, jsonify, redirect, send_file, Response, session, g, abort
+from flask import Flask, render_template, request, jsonify, redirect, send_file, send_from_directory, Response, session, g, abort
from flask_socketio import SocketIO, emit, join_room, leave_room
from utils.logging_config import get_logger, setup_logging
from utils.async_helpers import run_async
@@ -5222,6 +5222,25 @@ def run_detection(server_type):
def index():
return render_template('index.html')
+
+@app.route('/sw.js')
+def service_worker():
+ """Serve sw.js from root scope so the service worker can intercept
+ fetches site-wide. A service worker only controls URLs at or below
+ its own served path — `/static/sw.js` would scope to `/static/*`
+ only. Serving from `/sw.js` (with the file living under static/)
+ grants full-site scope without needing the Service-Worker-Allowed
+ header dance.
+
+ Cache-Control: no-cache so deploys that change the SW propagate on
+ the next page load instead of being pinned by the 1-year static
+ cache the rest of /static/ uses.
+ """
+ response = send_from_directory(app.static_folder, 'sw.js', mimetype='application/javascript')
+ response.headers['Cache-Control'] = 'no-cache'
+ return response
+
+
@app.route('/')
def spa_catch_all(page):
# Serve index.html for client-side routes; let Flask handle real routes first.
diff --git a/webui/index.html b/webui/index.html
index 1bd71056..7bcab176 100644
--- a/webui/index.html
+++ b/webui/index.html
@@ -6,6 +6,9 @@
SoulSync - Music Sync & Manager
+
+
+
diff --git a/webui/static/helper.js b/webui/static/helper.js
index e9560b3c..4b8a260a 100644
--- a/webui/static/helper.js
+++ b/webui/static/helper.js
@@ -3448,6 +3448,7 @@ const WHATS_NEW = {
{ title: 'Faster Docker Startup — yt-dlp Pinned', desc: 'docker startup used to run `pip install -U yt-dlp` on every container start. removed that — yt-dlp is now pinned in requirements.txt so startup is fast and reproducible. tradeoff: youtube fixes ship via soulsync releases now instead of next container restart.' },
{ title: 'Settings Endpoints: Admin-Only', desc: 'the /api/settings endpoints (read, write, log-level, config-status, verify) had no auth gate — any logged-in profile could read or change service tokens, oauth secrets, api keys. now admin-only. single-admin setups (no multi-profile config) work transparently as before.', page: 'settings' },
{ title: 'Browser Caching for Static Assets + Discover Pages', desc: 'static assets (js/css/icons) now get a 1-year browser cache instead of revalidating on every page load. safe because the existing ?v=static_v cache-bust query changes every server restart, so deploys still ship live. discover pages (hero, similar artists, recent releases, deep cuts, etc.) now cache 5 minutes browser-side so toggling between sections doesn\'t re-fetch everything. faster repeat loads, fewer round-trips.', page: 'discover' },
+ { title: 'Service Worker for Cover Art + Installable PWA', desc: 'cover art used to re-fetch from the cdn on every library / discover page visit. now a service worker caches images locally — second visit serves art instantly from disk, no network hit. also added a pwa manifest so soulsync can be installed to home screen / desktop as a standalone app (chrome / edge / safari → install soulsync). cache versioned so future strategy changes invalidate cleanly.' },
],
'2.4.0': [
// --- April 26, 2026 — Search & Artists unification + reorganize queue ---
diff --git a/webui/static/init.js b/webui/static/init.js
index a92a010f..2680518a 100644
--- a/webui/static/init.js
+++ b/webui/static/init.js
@@ -1903,6 +1903,19 @@ async function checkAdminPinRequired() {
}
}
+// Service worker registration. Runs as soon as the JS parses (doesn't
+// need to wait for DOMContentLoaded). Cache-first image strategy +
+// stale-while-revalidate static shell — see /sw.js for details. Skipped
+// when the API isn't available (older browsers, file:// origin) or when
+// the page is loaded from a non-secure origin (SW requires HTTPS or
+// localhost).
+if ('serviceWorker' in navigator) {
+ window.addEventListener('load', () => {
+ navigator.serviceWorker.register('/sw.js', { scope: '/' })
+ .catch((err) => console.warn('[SW] registration failed:', err));
+ });
+}
+
document.addEventListener('DOMContentLoaded', async function () {
console.log('SoulSync WebUI initializing...');
diff --git a/webui/static/manifest.json b/webui/static/manifest.json
new file mode 100644
index 00000000..ccf8acba
--- /dev/null
+++ b/webui/static/manifest.json
@@ -0,0 +1,37 @@
+{
+ "name": "SoulSync",
+ "short_name": "SoulSync",
+ "description": "Music download & sync app — playlists, watchlist, library management.",
+ "start_url": "/",
+ "scope": "/",
+ "display": "standalone",
+ "orientation": "any",
+ "theme_color": "#1db954",
+ "background_color": "#0a0a0a",
+ "icons": [
+ {
+ "src": "/static/pwa-icon-192.png",
+ "sizes": "192x192",
+ "type": "image/png",
+ "purpose": "any"
+ },
+ {
+ "src": "/static/pwa-icon-512.png",
+ "sizes": "512x512",
+ "type": "image/png",
+ "purpose": "any"
+ },
+ {
+ "src": "/static/pwa-icon-192.png",
+ "sizes": "192x192",
+ "type": "image/png",
+ "purpose": "maskable"
+ },
+ {
+ "src": "/static/pwa-icon-512.png",
+ "sizes": "512x512",
+ "type": "image/png",
+ "purpose": "maskable"
+ }
+ ]
+}
diff --git a/webui/static/pwa-icon-192.png b/webui/static/pwa-icon-192.png
new file mode 100644
index 0000000000000000000000000000000000000000..bad488dab2077d38cb4e46f8d7a2ccf1e0602b19
GIT binary patch
literal 55141
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