Compare commits

..
Author SHA1 Message Date
timothyandClaude Opus 4.8 7d71fb9f94 fix(410): log scan cancellation below ERROR (user-initiated, not a failure)
Build ErsatzTV Image / CI image pin matches docker/ci (pull_request) Successful in 6s
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 5s
Build ErsatzTV Image / decisions.md append-only (pull_request) Successful in 8s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 6m56s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 7s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 39s
Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 14m20s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 19m2s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Scan cancellation surfaces as ScanCanceled, an ordinary BaseError, so all
four scan handlers (Jellyfin/Emby/Plex/local) logged it at ERROR alongside
genuine failures. A user cancelling a scan (or a container restart mid-scan)
is not an error; this was training operators to ignore scanner ERROR lines,
corrosive precisely because #264 showed scanner failures can be silent.

Each handler's Left-result loop now branches on `error is ScanCanceled`:
logs Information ("Scan of {Name} was canceled") for cancellation, keeps
LogError for every other BaseError. No behavior change to LastScan
stamping (still correctly skipped on any Left, cancellation included).

fixes #410

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-18 16:42:13 +02:00
8 changed files with 159 additions and 85 deletions
@@ -1,5 +1,6 @@
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Jellyfin;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Core.Jellyfin;
@@ -95,5 +96,83 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests
Arg.Any<CancellationToken>());
await libraryRepository.Received(1).UpdateLastScan(library);
}
[Test]
public async Task Should_Not_Log_Error_When_Scan_Is_Canceled()
{
var scannerProxy = Substitute.For<IScannerProxy>();
var mediaSourceRepository = Substitute.For<IMediaSourceRepository>();
var jellyfinSecretStore = Substitute.For<IJellyfinSecretStore>();
var jellyfinMovieLibraryScanner = Substitute.For<IJellyfinMovieLibraryScanner>();
var jellyfinTelevisionLibraryScanner = Substitute.For<IJellyfinTelevisionLibraryScanner>();
var jellyfinMusicVideoLibraryScanner = Substitute.For<IJellyfinMusicVideoLibraryScanner>();
var libraryRepository = Substitute.For<ILibraryRepository>();
var configElementRepository = Substitute.For<IConfigElementRepository>();
var logger = Substitute.For<ILogger<SynchronizeJellyfinLibraryByIdHandler>>();
var library = new JellyfinLibrary
{
Id = 42,
Name = "Concerts",
MediaKind = LibraryMediaKind.MusicVideos,
MediaSourceId = 7
};
var mediaSource = new JellyfinMediaSource
{
Id = 7,
Connections =
[
new JellyfinConnection
{
Address = "http://jellyfin.example",
JellyfinMediaSourceId = 7
}
]
};
mediaSourceRepository.GetJellyfinByLibraryId(library.Id).Returns(Some(mediaSource).AsTask());
mediaSourceRepository.GetJellyfinLibrary(library.Id).Returns(Some(library).AsTask());
jellyfinSecretStore.ReadSecrets().Returns(new JellyfinSecrets
{
Address = "http://jellyfin.example",
ApiKey = "abc"
});
configElementRepository.GetValue<int>(
Arg.Is<ConfigElementKey>(key => key.Key == ConfigElementKey.LibraryRefreshInterval.Key),
Arg.Any<CancellationToken>())
.Returns(Task.FromResult<Option<int>>(Some(0)));
jellyfinMusicVideoLibraryScanner.ScanLibrary(
Arg.Any<JellyfinConnectionParameters>(),
library,
true,
Arg.Any<CancellationToken>())
.Returns(Left<BaseError, Unit>(new ScanCanceled()).AsTask());
var handler = new SynchronizeJellyfinLibraryByIdHandler(
scannerProxy,
mediaSourceRepository,
jellyfinSecretStore,
jellyfinMovieLibraryScanner,
jellyfinTelevisionLibraryScanner,
jellyfinMusicVideoLibraryScanner,
libraryRepository,
configElementRepository,
logger);
await handler.Handle(
new SynchronizeJellyfinLibraryById("http://ersatztv.example", library.Id, true, true),
CancellationToken.None);
// a user-initiated cancellation is not a failure and must not be logged at ERROR (#410)
await libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any<Library>());
logger.ReceivedCalls()
.Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString()
== "Error synchronizing jellyfin library: Scan was canceled")
.ShouldBeFalse();
logger.ReceivedCalls()
.Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString()
== "Scan of jellyfin library Concerts was canceled")
.ShouldBeTrue();
}
}
}
@@ -1,5 +1,6 @@
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Scanner.Application.MediaSources;
using ErsatzTV.Scanner.Core.Interfaces;
@@ -96,6 +97,27 @@ public class ScanLocalLibraryHandlerTests
ShouldHaveLogged("Error scanning local library path /movies: scan failed");
}
[Test]
public async Task Should_Not_Log_Error_When_A_Path_Scan_Is_Canceled()
{
ScanResult(Left<BaseError, Unit>(new ScanCanceled()));
await Handler().Handle(
new ScanLocalLibrary("http://ersatztv.example", _library.Id, true),
CancellationToken.None);
// a user-initiated cancellation is not a failure and must not be logged at ERROR (#410);
// it's still correctly excluded from the "last scan" stamp, same as any other failure
_library.LastScan.ShouldBeNull();
await _libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any<Library>());
_logger.ReceivedCalls()
.Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString()
== "Error scanning local library path /movies: Scan was canceled")
.ShouldBeFalse();
ShouldHaveLogged("Scan of local library path /movies was canceled");
}
[Test]
public async Task Should_Not_Set_Library_LastScan_When_A_Later_Path_Fails()
{
@@ -1,6 +1,7 @@
using ErsatzTV.Core;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Emby;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Emby;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Scanner.Core.Interfaces;
@@ -86,7 +87,14 @@ public class SynchronizeEmbyLibraryByIdHandler : IRequestHandler<SynchronizeEmby
foreach (BaseError error in result.LeftToSeq())
{
_logger.LogError("Error synchronizing emby library: {Error}", error);
if (error is ScanCanceled)
{
_logger.LogInformation("Scan of emby library {Name} was canceled", parameters.Library.Name);
}
else
{
_logger.LogError("Error synchronizing emby library: {Error}", error);
}
}
return result.Map(_ => parameters.Library.Name);
@@ -1,5 +1,6 @@
using ErsatzTV.Core;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Jellyfin;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Core.Jellyfin;
@@ -95,7 +96,16 @@ public class
foreach (BaseError error in result.LeftToSeq())
{
_logger.LogError("Error synchronizing jellyfin library: {Error}", error);
if (error is ScanCanceled)
{
_logger.LogInformation(
"Scan of jellyfin library {Name} was canceled",
parameters.Library.Name);
}
else
{
_logger.LogError("Error synchronizing jellyfin library: {Error}", error);
}
}
return result.Map(_ => parameters.Library.Name);
@@ -1,6 +1,7 @@
using System.Diagnostics;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Scanner.Core.Interfaces;
using ErsatzTV.Scanner.Core.Interfaces.Metadata;
@@ -152,13 +153,23 @@ public class ScanLocalLibraryHandler : IRequestHandler<ScanLocalLibrary, Either<
// a failed path now suppresses the library-level scan time below, so without this the
// user sees "Never scanned" with nothing explaining why. The remote scanners log the
// same way.
// same way. A cancellation is user-initiated, not a failure, so it's logged separately
// at a lower level; genuine errors still log at ERROR.
foreach (BaseError error in result.LeftToSeq())
{
_logger.LogError(
"Error scanning local library path {Path}: {Error}",
libraryPath.Path,
error);
if (error is ScanCanceled)
{
_logger.LogInformation(
"Scan of local library path {Path} was canceled",
libraryPath.Path);
}
else
{
_logger.LogError(
"Error scanning local library path {Path}: {Error}",
libraryPath.Path,
error);
}
}
}
}
@@ -1,5 +1,6 @@
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Interfaces.Plex;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Core.Plex;
@@ -96,7 +97,14 @@ public class SynchronizePlexLibraryByIdHandler : IRequestHandler<SynchronizePlex
foreach (BaseError error in result.LeftToSeq())
{
_logger.LogError("Error synchronizing plex library: {Error}", error);
if (error is ScanCanceled)
{
_logger.LogInformation("Scan of plex library {Name} was canceled", parameters.Library.Name);
}
else
{
_logger.LogError("Error synchronizing plex library: {Error}", error);
}
}
return result.Map(_ => parameters.Library.Name);
+6 -19
View File
@@ -566,25 +566,12 @@ running product from outside our C#/review stack.
several minutes, and is noisy (expect to tune, not take raw). The continuous layer is the per-PR
white-box gates + the weekly `dependency-scan`; this is the per-release black-box pass. Re-run it each
release and before any change to the exposure posture.
- **Exit-code contract (ersatztv#338).** `zap-api-scan.py`'s raw exit code is NOT a simple pass/fail — it
conflates a clean run with a warnings-only run unless you know its wrapper contract: **0** clean (no
FAIL or WARN alerts), **2** WARN-only (triage required, but **not** release-blocking), **1** FAIL (at
least one FAIL-level alert — release-blocking), **124** the script's own `timeout` wrapper killed a
hung post-scan cleanup (the report written before the hang is still usable — triage it), any other
code means the scanner/tool itself errored (not a scan result at all). `scripts/security-scan.sh`
encodes this in `classify_zap_exit()` and prints an unambiguous `==> ZAP result: <PASS|WARN|FAIL|
TIMEOUT|TOOL ERROR> ...` line; the script's own exit status reflects that classification (0 for
clean/WARN, 1 for FAIL/timeout/tool-error) rather than ZAP's raw code, so a warnings-only run no longer
reads as a failed scan. Found when the v26.8.0 release scan (#335) returned raw exit 2 for a report with
`FAIL-NEW: 0` and two known/expected warning classes — the shell result looked like a failure though the
release gate had actually passed. Run `scripts/security-scan.sh --selftest` for a docker-free regression
check of the classification logic.
- **Triage.** Triage each WARN/FAIL finding false-positive vs real. Real, in-scope, go-live-blocking
findings get fixed (e.g. the security headers from the #319 baseline; the Microsoft.OpenApi pin above);
LAN-expected noise (Private-IP disclosure) is revisited only for genuine remote exposure. nuclei
(template-based CVE fingerprinting) is an optional third pass — deferred while its template fetch is
blocked in the runner env (pre-seed a template volume to add it); ZAP covers the DAST baseline and
semgrep the SAST, so it is not on the critical path.
- **Triage.** ZAP exits non-zero on any FAIL-level alert; the tooling is noisy, so triage each finding
false-positive vs real. Real, in-scope, go-live-blocking findings get fixed (e.g. the security headers
from the #319 baseline; the Microsoft.OpenApi pin above); LAN-expected noise (Private-IP disclosure) is
revisited only for genuine remote exposure. nuclei (template-based CVE fingerprinting) is an optional
third pass — deferred while its template fetch is blocked in the runner env (pre-seed a template volume
to add it); ZAP covers the DAST baseline and semgrep the SAST, so it is not on the critical path.
## Static analysis & formatting
+5 -56
View File
@@ -23,60 +23,12 @@
# ETV_SCAN_OUT host dir for reports (default: /tmp/etv-scan-out)
# ETV_SCAN_SKIP_SEMGREP=1 skip the SAST pass (DAST only)
#
# Reports land in $ETV_SCAN_OUT: zap-api-report.{html,md,json}. zap-api-scan.py's exit code is NOT a
# simple pass/fail — its wrapper contract (ersatztv#338, found via the #335 exact-image release scan
# returning 2 for a clean-enough report):
# 0 clean — no FAIL or WARN alerts
# 2 WARN — only WARN-level alerts (triage, but NOT release-blocking) — do not fail the job on this
# 1 FAIL — at least one FAIL-level alert — release-blocking
# 124 our own `timeout` wrapper killed a hung wrapper (see the NOTE below) — report is still usable
# other the scanner/tool itself errored (bad args, crash) — not a scan result at all
# classify_zap_exit() (below) is the single place this contract is encoded; the script's own final exit
# code reflects the CLASSIFICATION (0 for clean/WARN, 1 for FAIL/timeout/tool-error), not ZAP's raw code.
# Reports land in $ETV_SCAN_OUT: zap-api-report.{html,md,json}. Exit code is ZAP's:
# 0 = no FAIL-level alerts, non-zero = at least one FAIL (triage it — this tooling is noisy; expect to
# tune the ignore list in .zap/ rather than take the raw report at face value).
set -euo pipefail
# classify_zap_exit RC — sets ZAP_CLASS_MSG to an unambiguous one-line classification of ZAP's raw exit
# code and returns the exit status this SCRIPT should use for that outcome (see contract above). Kept as
# a standalone function (not inlined) so `--selftest` can exercise it without docker/ZAP.
classify_zap_exit() {
local rc="$1"
case "$rc" in
0) ZAP_CLASS_MSG="PASS — no FAIL or WARN alerts"; return 0 ;;
2) ZAP_CLASS_MSG="WARN — WARN-level alerts only; triage required, NOT release-blocking"; return 0 ;;
1) ZAP_CLASS_MSG="FAIL — at least one FAIL-level alert; release-blocking, do not ship"; return 1 ;;
124) ZAP_CLASS_MSG="TIMEOUT — wrapper hit ETV_SCAN_TIMEOUT; triage the partial report before shipping"; return 1 ;;
*) ZAP_CLASS_MSG="TOOL ERROR (raw exit $rc) — scanner itself failed, this is not a scan result"; return 1 ;;
esac
}
if [ "${1:-}" = "--selftest" ]; then
# Lightweight regression check for the classification contract above (ersatztv#338 Done-when) — no
# docker/ZAP required, so it can run anywhere (incl. off bumblebee, incl. in per-PR CI if ever added).
selftest_failed=0
selftest_check() {
local rc="$1" want_status="$2" want_substr="$3" got_status
if classify_zap_exit "$rc"; then got_status=0; else got_status=$?; fi
if [ "$got_status" != "$want_status" ] || [[ "$ZAP_CLASS_MSG" != *"$want_substr"* ]]; then
echo "SELFTEST FAIL: rc=$rc -> status=$got_status msg='$ZAP_CLASS_MSG' (want status=$want_status, msg containing '$want_substr')" >&2
selftest_failed=1
else
echo "selftest ok: rc=$rc -> status=$got_status ($ZAP_CLASS_MSG)"
fi
}
selftest_check 0 0 "PASS"
selftest_check 2 0 "WARN"
selftest_check 1 1 "FAIL"
selftest_check 124 1 "TIMEOUT"
selftest_check 3 1 "TOOL ERROR"
selftest_check 77 1 "TOOL ERROR"
if [ "$selftest_failed" = 0 ]; then
echo "selftest: all ZAP exit classifications OK"; exit 0
else
echo "selftest: FAILURES ABOVE" >&2; exit 1
fi
fi
IMAGE="${1:-192.168.1.95:3000/timothy/ersatztv:latest}"
PORT="${2:-8411}"
OUT="${ETV_SCAN_OUT:-/tmp/etv-scan-out}"
@@ -135,13 +87,10 @@ timeout "${ETV_SCAN_TIMEOUT:-45m}" docker run --rm --network host -v "$OUT":/zap
-z "replacer.full_list(0).description=apikey;replacer.full_list(0).enabled=true;replacer.full_list(0).matchtype=REQ_HEADER;replacer.full_list(0).matchstr=X-Api-Key;replacer.full_list(0).regex=false;replacer.full_list(0).replacement=$KEY"
zap_rc=$?
[ "$zap_rc" = 124 ] && echo "NOTE: ZAP wrapper hit the ${ETV_SCAN_TIMEOUT:-45m} timeout (usually a post-scan cleanup hang) — the report written before the hang is still valid; triage it."
classify_zap_exit "$zap_rc"
zap_class_status=$?
set -e
# (The ZAP container + target + temp dir are reaped by cleanup() on the EXIT trap — every path, incl.
# a `timeout` kill or Ctrl-C mid-scan.)
echo "==> ZAP report: $OUT/zap-api-report.html (+ .md/.json)"
echo "==> ZAP result: $ZAP_CLASS_MSG (raw exit $zap_rc)"
echo "==> ZAP report: $OUT/zap-api-report.html (+ .md/.json). Exit code: $zap_rc"
if [ "${ETV_SCAN_SKIP_SEMGREP:-0}" = "1" ]; then
echo "==> semgrep SAST skipped (ETV_SCAN_SKIP_SEMGREP=1)"
@@ -155,4 +104,4 @@ else
"$REPO_ROOT" || echo "(semgrep reported findings — triage in the report above)"
fi
exit "$zap_class_status"
exit "$zap_rc"