BlueGit

timfa filemanager

Merge fix/session-persistence-hardening

timfa Tim Falken · pushed by timfa

Authored 2026-05-25 · 5 months ago

Hash
cff6450e5a16324119a64f165ec6de86fefe2d2f
7 files changed +172 −6
.github/technical-reference.md +4 −2
@@ -18,6 +18,7 @@
18 18 - appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
19 19 - getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
20 20 - pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
21 - subtitleLogFileByContext (LRU) - In-memory context-to-logfile mapping is trimmed with `SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX` (default 512, capped at 4096) to prevent unbounded session-key growth.
21 22 - subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
22 23
23 24 ## server/image-subtitles.js
@@ -32,7 +33,7 @@
32 33
33 34 ## server/thumbnail-cache.js
34 35 - syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
35 - startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
36 - startThumbnailCacheLoop() - Schedules cache sync runs with adaptive cadence: default 5s when idle and heavily throttled while active streams exist (`THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS`, default 120000 ms).
36 37 - stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
37 38 - getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
38 39 - getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
@@ -90,7 +91,7 @@
90 91 - applyListAccessChmod(startDir) - Best-effort shallow chmod pass for folder-access requests; updates the opened folder and its direct children only, skips symlinks, and continues past individual errors.
91 92 - resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
92 93 - resolveRootForUser(absPath, roots, user, config) - Allows admins to access orphaned user folders (deleted-account folders) under userPath.
93 - resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only read-only browse root for the debug menu.
94 - resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only debug root for browse and maintenance actions from the debug menu.
94 95 - canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
95 96 - checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
96 97 - POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
@@ -155,6 +156,7 @@
155 156 - hasInitialHlsAssets(outputDir) - Returns true once master.m3u8 or at least one variant playlist/segment exists in an HLS output directory; accepts named variant filenames (stream_video.m3u8) in addition to numeric ones.
156 157 - purgeStreamRootDir() - Best-effort recursive delete of the temporary HLS stream root; used at startup and by idle sweeps to remove orphaned stream session directories from previous runs.
157 158 - cleanupIdleStreamArtifacts() - Periodic idle-time cleaner that purges stream-root artifacts when there are no active sessions or leases, preventing stale segment directories from accumulating after failures.
159 - pruneExpiredSessions() sweep - A dedicated interval sweep (`VIDEO_STREAM_EXPIRY_SWEEP_MS`, default 60000 ms) reclaims expired leases/sessions even when no new stream requests arrive.
158 160 - getVideoStreamDebugSnapshot() - Returns active stream sessions with viewer counts and output-dir stats (segment counts/bytes), plus orphaned output directories left under the stream root for diagnostics.
159 161 - getVideoStreamDebugSnapshot() - Includes segment retention and prune telemetry per session (segmentRetentionCount, slowestViewerSegmentIndex, segmentPrunedUntil, lastSegmentPrune, streamPruneDeleteBatchSize) to explain growth or cleanup stalls in segment counts.
160 162 - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
@@ -18,6 +18,7 @@
18- appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
18- appendSubtitleDebugEntries({ videoName, entries, context }) - Appends client-side subtitle timing events to a timestamped per-video text log under the local temp cache (`<unix-ms>-videoname-subtitlelog.txt`), reusing one file per playback context and pruning the oldest files when the subtitle log cache exceeds 10 MB.
19- getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
19- getSubtitleDebugLogSnapshot() - Reports the subtitle log cache directory path, existence, file count, byte total, and latest file so the debug dashboard can expose it as a folder.
20- pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
20- pruneSubtitleDebugLogDir() - Enforces the 10 MB total subtitle-log cache budget by deleting the oldest log files first.
21- subtitleLogFileByContext (LRU) - In-memory context-to-logfile mapping is trimmed with `SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX` (default 512, capped at 4096) to prevent unbounded session-key growth.
21- subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
22- subtitleDebugLogFilePath(videoName, timestampMs) - Resolves the timestamped subtitle timing log path for a video name using a filesystem-safe filename.
22
23
23## server/image-subtitles.js
24## server/image-subtitles.js
@@ -32,7 +33,7 @@
32
33
33## server/thumbnail-cache.js
34## server/thumbnail-cache.js
34- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
35- syncThumbnailCacheOnce() - Mirrors configured roots and userPath into public/thumbs and generates 99x99-max WebP thumbnails for image files, video files (ffprobe/ffmpeg frame at ~10%), and 3D model files (STL/OBJ, isometric SVG projection via Sharp); removes stale thumbnails and updates manifest hashes.
35- startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
36- startThumbnailCacheLoop() - Schedules cache sync runs with adaptive cadence: default 5s when idle and heavily throttled while active streams exist (`THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS`, default 120000 ms).
36- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
37- stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
37- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
38- getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
38- getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
39- getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
@@ -90,7 +91,7 @@
90- applyListAccessChmod(startDir) - Best-effort shallow chmod pass for folder-access requests; updates the opened folder and its direct children only, skips symlinks, and continues past individual errors.
91- applyListAccessChmod(startDir) - Best-effort shallow chmod pass for folder-access requests; updates the opened folder and its direct children only, skips symlinks, and continues past individual errors.
91- resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
92- resolveRootForUser(absPath, roots, user, config) - Resolves access for configured roots plus user-owned personal folder.
92- resolveRootForUser(absPath, roots, user, config) - Allows admins to access orphaned user folders (deleted-account folders) under userPath.
93- resolveRootForUser(absPath, roots, user, config) - Allows admins to access orphaned user folders (deleted-account folders) under userPath.
93- resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only read-only browse root for the debug menu.
94- resolveRootForUser(absPath, roots, user, config) - Treats the local subtitle debug log directory as an admin-only debug root for browse and maintenance actions from the debug menu.
94- canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
95- canReadInfo(user, info) / canWriteInfo(user, info) - Permission checks that automatically allow access for personal user-folder roots.
95- checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
96- checkUserFolderSizeLimit(config, username, addedBytes) - Validates a user-folder capacity limit against current usage.
96- POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
97- POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
@@ -155,6 +156,7 @@
155- hasInitialHlsAssets(outputDir) - Returns true once master.m3u8 or at least one variant playlist/segment exists in an HLS output directory; accepts named variant filenames (stream_video.m3u8) in addition to numeric ones.
156- hasInitialHlsAssets(outputDir) - Returns true once master.m3u8 or at least one variant playlist/segment exists in an HLS output directory; accepts named variant filenames (stream_video.m3u8) in addition to numeric ones.
156- purgeStreamRootDir() - Best-effort recursive delete of the temporary HLS stream root; used at startup and by idle sweeps to remove orphaned stream session directories from previous runs.
157- purgeStreamRootDir() - Best-effort recursive delete of the temporary HLS stream root; used at startup and by idle sweeps to remove orphaned stream session directories from previous runs.
157- cleanupIdleStreamArtifacts() - Periodic idle-time cleaner that purges stream-root artifacts when there are no active sessions or leases, preventing stale segment directories from accumulating after failures.
158- cleanupIdleStreamArtifacts() - Periodic idle-time cleaner that purges stream-root artifacts when there are no active sessions or leases, preventing stale segment directories from accumulating after failures.
159- pruneExpiredSessions() sweep - A dedicated interval sweep (`VIDEO_STREAM_EXPIRY_SWEEP_MS`, default 60000 ms) reclaims expired leases/sessions even when no new stream requests arrive.
158- getVideoStreamDebugSnapshot() - Returns active stream sessions with viewer counts and output-dir stats (segment counts/bytes), plus orphaned output directories left under the stream root for diagnostics.
160- getVideoStreamDebugSnapshot() - Returns active stream sessions with viewer counts and output-dir stats (segment counts/bytes), plus orphaned output directories left under the stream root for diagnostics.
159- getVideoStreamDebugSnapshot() - Includes segment retention and prune telemetry per session (segmentRetentionCount, slowestViewerSegmentIndex, segmentPrunedUntil, lastSegmentPrune, streamPruneDeleteBatchSize) to explain growth or cleanup stalls in segment counts.
161- getVideoStreamDebugSnapshot() - Includes segment retention and prune telemetry per session (segmentRetentionCount, slowestViewerSegmentIndex, segmentPrunedUntil, lastSegmentPrune, streamPruneDeleteBatchSize) to explain growth or cleanup stalls in segment counts.
160- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
162- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
server/routes/files.js +1 −1
@@ -711,7 +711,7 @@ function canWriteInfo (user, info)
711 711 if (!info) return false;
712 712 if (info.isUserFolder) return true;
713 713 if (info.isOrphanUserFolder) return !!(user && user.isAdmin);
714 if (info.isDebugLogFolder) return false;
714 if (info.isDebugLogFolder) return !!(user && user.isAdmin);
715 715 return canWrite(user, info.label);
716 716 }
717 717
@@ -711,7 +711,7 @@ function canWriteInfo (user, info)
711 if (!info) return false;
711 if (!info) return false;
712 if (info.isUserFolder) return true;
712 if (info.isUserFolder) return true;
713 if (info.isOrphanUserFolder) return !!(user && user.isAdmin);
713 if (info.isOrphanUserFolder) return !!(user && user.isAdmin);
714 if (info.isDebugLogFolder) return false;
714 if (info.isDebugLogFolder) return !!(user && user.isAdmin);
715 return canWrite(user, info.label);
715 return canWrite(user, info.label);
716}
716}
717
717
server/subtitle-debug-log.js +48 −1
@@ -6,8 +6,19 @@ const path = require('path');
6 6
7 7 const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
8 8 const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
9 const MAX_SUBTITLE_LOG_CONTEXT_KEYS = parseContextLimit(process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX, 512);
9 10 const subtitleLogFileByContext = new Map();
10 11
12 function parseContextLimit (value, fallback)
13 {
14 const parsed = Number.parseInt(String(value || ''), 10);
15 if (Number.isInteger(parsed) && parsed >= 1)
16 {
17 return Math.min(parsed, 4096);
18 }
19 return fallback;
20 }
21
11 22 function normaliseTimestampMs (timestampMs)
12 23 {
13 24 const parsed = Number(timestampMs);
@@ -41,13 +52,43 @@ function resolveSubtitleLogPath (videoName, timestampMs, context)
41 52 {
42 53 const key = subtitleLogContextKey(videoName, context);
43 54 const existing = subtitleLogFileByContext.get(key);
44 if (existing) return existing;
55 if (existing)
56 {
57 // LRU refresh for active contexts.
58 subtitleLogFileByContext.delete(key);
59 subtitleLogFileByContext.set(key, existing);
60 return existing;
61 }
62
63 trimSubtitleLogContextMap();
45 64
46 65 const targetPath = subtitleDebugLogFilePath(videoName, timestampMs);
47 66 subtitleLogFileByContext.set(key, targetPath);
67 trimSubtitleLogContextMap();
48 68 return targetPath;
49 69 }
50 70
71 function trimSubtitleLogContextMap ()
72 {
73 if (subtitleLogFileByContext.size <= MAX_SUBTITLE_LOG_CONTEXT_KEYS) return;
74
75 // Remove oldest references first when they no longer point at existing files.
76 for (const [key, filePath] of subtitleLogFileByContext)
77 {
78 if (subtitleLogFileByContext.size <= MAX_SUBTITLE_LOG_CONTEXT_KEYS) break;
79 if (fs.existsSync(filePath)) continue;
80 subtitleLogFileByContext.delete(key);
81 }
82
83 // Hard cap fallback: evict oldest entries (LRU order) until under limit.
84 while (subtitleLogFileByContext.size > MAX_SUBTITLE_LOG_CONTEXT_KEYS)
85 {
86 const oldestKey = subtitleLogFileByContext.keys().next().value;
87 if (!oldestKey) break;
88 subtitleLogFileByContext.delete(oldestKey);
89 }
90 }
91
51 92 function ensureSubtitleDebugLogDir ()
52 93 {
53 94 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
@@ -154,10 +195,16 @@ function appendSubtitleDebugEntries ({ videoName, entries, context = null })
154 195 }
155 196 }
156 197
198 function getSubtitleDebugLogContextCount ()
199 {
200 return subtitleLogFileByContext.size;
201 }
202
157 203 module.exports = {
158 204 SUBTITLE_DEBUG_LOG_DIR,
159 205 MAX_SUBTITLE_DEBUG_LOG_BYTES,
160 206 getSubtitleDebugLogSnapshot,
207 getSubtitleDebugLogContextCount,
161 208 subtitleDebugLogFilePath,
162 209 pruneSubtitleDebugLogDir,
163 210 appendSubtitleDebugEntries,
@@ -6,8 +6,19 @@ const path = require('path');
6
6
7const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
7const SUBTITLE_DEBUG_LOG_DIR = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
8const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
8const MAX_SUBTITLE_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
9const MAX_SUBTITLE_LOG_CONTEXT_KEYS = parseContextLimit(process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX, 512);
9const subtitleLogFileByContext = new Map();
10const subtitleLogFileByContext = new Map();
10
11
12function parseContextLimit (value, fallback)
13{
14 const parsed = Number.parseInt(String(value || ''), 10);
15 if (Number.isInteger(parsed) && parsed >= 1)
16 {
17 return Math.min(parsed, 4096);
18 }
19 return fallback;
20}
21
11function normaliseTimestampMs (timestampMs)
22function normaliseTimestampMs (timestampMs)
12{
23{
13 const parsed = Number(timestampMs);
24 const parsed = Number(timestampMs);
@@ -41,13 +52,43 @@ function resolveSubtitleLogPath (videoName, timestampMs, context)
41{
52{
42 const key = subtitleLogContextKey(videoName, context);
53 const key = subtitleLogContextKey(videoName, context);
43 const existing = subtitleLogFileByContext.get(key);
54 const existing = subtitleLogFileByContext.get(key);
44 if (existing) return existing;
55 if (existing)
56 {
57 // LRU refresh for active contexts.
58 subtitleLogFileByContext.delete(key);
59 subtitleLogFileByContext.set(key, existing);
60 return existing;
61 }
62
63 trimSubtitleLogContextMap();
45
64
46 const targetPath = subtitleDebugLogFilePath(videoName, timestampMs);
65 const targetPath = subtitleDebugLogFilePath(videoName, timestampMs);
47 subtitleLogFileByContext.set(key, targetPath);
66 subtitleLogFileByContext.set(key, targetPath);
67 trimSubtitleLogContextMap();
48 return targetPath;
68 return targetPath;
49}
69}
50
70
71function trimSubtitleLogContextMap ()
72{
73 if (subtitleLogFileByContext.size <= MAX_SUBTITLE_LOG_CONTEXT_KEYS) return;
74
75 // Remove oldest references first when they no longer point at existing files.
76 for (const [key, filePath] of subtitleLogFileByContext)
77 {
78 if (subtitleLogFileByContext.size <= MAX_SUBTITLE_LOG_CONTEXT_KEYS) break;
79 if (fs.existsSync(filePath)) continue;
80 subtitleLogFileByContext.delete(key);
81 }
82
83 // Hard cap fallback: evict oldest entries (LRU order) until under limit.
84 while (subtitleLogFileByContext.size > MAX_SUBTITLE_LOG_CONTEXT_KEYS)
85 {
86 const oldestKey = subtitleLogFileByContext.keys().next().value;
87 if (!oldestKey) break;
88 subtitleLogFileByContext.delete(oldestKey);
89 }
90}
91
51function ensureSubtitleDebugLogDir ()
92function ensureSubtitleDebugLogDir ()
52{
93{
53 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
94 fs.mkdirSync(SUBTITLE_DEBUG_LOG_DIR, { recursive: true });
@@ -154,10 +195,16 @@ function appendSubtitleDebugEntries ({ videoName, entries, context = null })
154 }
195 }
155}
196}
156
197
198function getSubtitleDebugLogContextCount ()
199{
200 return subtitleLogFileByContext.size;
201}
202
157module.exports = {
203module.exports = {
158 SUBTITLE_DEBUG_LOG_DIR,
204 SUBTITLE_DEBUG_LOG_DIR,
159 MAX_SUBTITLE_DEBUG_LOG_BYTES,
205 MAX_SUBTITLE_DEBUG_LOG_BYTES,
160 getSubtitleDebugLogSnapshot,
206 getSubtitleDebugLogSnapshot,
207 getSubtitleDebugLogContextCount,
161 subtitleDebugLogFilePath,
208 subtitleDebugLogFilePath,
162 pruneSubtitleDebugLogDir,
209 pruneSubtitleDebugLogDir,
163 appendSubtitleDebugEntries,
210 appendSubtitleDebugEntries,
server/thumbnail-cache.js +30 −2
@@ -13,6 +13,7 @@ const THUMBS_DIR = path.resolve(process.env.FILEMANAGER_THUMBS_DIR || path.join(
13 13 const MANIFEST_PATH = path.join(THUMBS_DIR, '.manifest.json');
14 14 const FOLDER_ICONS_PATH = path.join(THUMBS_DIR, '.folder-icons.json');
15 15 const LOOP_DELAY_MS = 5000;
16 const ACTIVE_STREAM_LOOP_DELAY_MS = toPositiveInt(process.env.THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS, 120000);
16 17
17 18 const IMAGE_EXTS = new Set([
18 19 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'avif', 'svg', 'ico',
@@ -128,6 +129,33 @@ function runCommand (command, args)
128 129 });
129 130 }
130 131
132 function toPositiveInt (value, fallback)
133 {
134 const parsed = Number.parseInt(String(value || ''), 10);
135 return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
136 }
137
138 function activeThumbnailLoopDelayMs ()
139 {
140 try
141 {
142 const stream = require('./video-stream');
143 const count = Number(stream && typeof stream.getActiveStreamCount === 'function'
144 ? stream.getActiveStreamCount()
145 : 0);
146 if (Number.isFinite(count) && count > 0)
147 {
148 return Math.max(LOOP_DELAY_MS, ACTIVE_STREAM_LOOP_DELAY_MS);
149 }
150 }
151 catch
152 {
153 // Fallback to normal cadence if stream state is unavailable.
154 }
155
156 return LOOP_DELAY_MS;
157 }
158
131 159 async function probeDurationSeconds (sourceFile)
132 160 {
133 161 const { stdout } = await runCommand(ffprobePath(), [
@@ -773,7 +801,7 @@ function scheduleNextRun (delayMs)
773 801 }
774 802 finally
775 803 {
776 if (loopStarted) scheduleNextRun(LOOP_DELAY_MS);
804 if (loopStarted) scheduleNextRun(activeThumbnailLoopDelayMs());
777 805 }
778 806 }, delayMs);
779 807
@@ -784,7 +812,7 @@ function startThumbnailCacheLoop ()
784 812 {
785 813 if (loopStarted) return;
786 814 loopStarted = true;
787 scheduleNextRun(LOOP_DELAY_MS);
815 scheduleNextRun(activeThumbnailLoopDelayMs());
788 816 }
789 817
790 818 function stopThumbnailCacheLoop ()
@@ -13,6 +13,7 @@ const THUMBS_DIR = path.resolve(process.env.FILEMANAGER_THUMBS_DIR || path.join(
13const MANIFEST_PATH = path.join(THUMBS_DIR, '.manifest.json');
13const MANIFEST_PATH = path.join(THUMBS_DIR, '.manifest.json');
14const FOLDER_ICONS_PATH = path.join(THUMBS_DIR, '.folder-icons.json');
14const FOLDER_ICONS_PATH = path.join(THUMBS_DIR, '.folder-icons.json');
15const LOOP_DELAY_MS = 5000;
15const LOOP_DELAY_MS = 5000;
16const ACTIVE_STREAM_LOOP_DELAY_MS = toPositiveInt(process.env.THUMBNAIL_CACHE_ACTIVE_STREAM_DELAY_MS, 120000);
16
17
17const IMAGE_EXTS = new Set([
18const IMAGE_EXTS = new Set([
18 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'avif', 'svg', 'ico',
19 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'avif', 'svg', 'ico',
@@ -128,6 +129,33 @@ function runCommand (command, args)
128 });
129 });
129}
130}
130
131
132function toPositiveInt (value, fallback)
133{
134 const parsed = Number.parseInt(String(value || ''), 10);
135 return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
136}
137
138function activeThumbnailLoopDelayMs ()
139{
140 try
141 {
142 const stream = require('./video-stream');
143 const count = Number(stream && typeof stream.getActiveStreamCount === 'function'
144 ? stream.getActiveStreamCount()
145 : 0);
146 if (Number.isFinite(count) && count > 0)
147 {
148 return Math.max(LOOP_DELAY_MS, ACTIVE_STREAM_LOOP_DELAY_MS);
149 }
150 }
151 catch
152 {
153 // Fallback to normal cadence if stream state is unavailable.
154 }
155
156 return LOOP_DELAY_MS;
157}
158
131async function probeDurationSeconds (sourceFile)
159async function probeDurationSeconds (sourceFile)
132{
160{
133 const { stdout } = await runCommand(ffprobePath(), [
161 const { stdout } = await runCommand(ffprobePath(), [
@@ -773,7 +801,7 @@ function scheduleNextRun (delayMs)
773 }
801 }
774 finally
802 finally
775 {
803 {
776 if (loopStarted) scheduleNextRun(LOOP_DELAY_MS);
804 if (loopStarted) scheduleNextRun(activeThumbnailLoopDelayMs());
777 }
805 }
778 }, delayMs);
806 }, delayMs);
779
807
@@ -784,7 +812,7 @@ function startThumbnailCacheLoop ()
784{
812{
785 if (loopStarted) return;
813 if (loopStarted) return;
786 loopStarted = true;
814 loopStarted = true;
787 scheduleNextRun(LOOP_DELAY_MS);
815 scheduleNextRun(activeThumbnailLoopDelayMs());
788}
816}
789
817
790function stopThumbnailCacheLoop ()
818function stopThumbnailCacheLoop ()
server/video-stream.js +24 −0
@@ -11,6 +11,7 @@ const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
11 11 const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
12 12 const STREAM_READY_TIMEOUT_MS = 20 * 1000;
13 13 const STREAM_IDLE_STOP_MS = 5 * 60 * 1000;
14 const STREAM_EXPIRY_SWEEP_MS = parseSweepInterval(process.env.VIDEO_STREAM_EXPIRY_SWEEP_MS, 60 * 1000);
14 15 const ESTIMATED_SEGMENT_BYTES = 1024 * 1024;
15 16 const ESTIMATED_SEGMENT_DURATION_SECONDS = 6;
16 17 const STREAM_PRUNE_DELETE_BATCH_SIZE = parsePruneDeleteBatchSize(process.env.VIDEO_STREAM_PRUNE_DELETE_BATCH_SIZE);
@@ -59,6 +60,23 @@ if (streamRootCleanupTimer && typeof streamRootCleanupTimer.unref === 'function'
59 60 streamRootCleanupTimer.unref();
60 61 }
61 62
63 // Ensure expired leases/sessions are reclaimed even without further stream requests.
64 const streamExpirySweepTimer = setInterval(pruneExpiredSessions, STREAM_EXPIRY_SWEEP_MS);
65 if (streamExpirySweepTimer && typeof streamExpirySweepTimer.unref === 'function')
66 {
67 streamExpirySweepTimer.unref();
68 }
69
70 function parseSweepInterval (value, fallbackMs)
71 {
72 const parsed = Number.parseInt(String(value || ''), 10);
73 if (Number.isInteger(parsed) && parsed >= 1000)
74 {
75 return clampNumber(parsed, 1000, 10 * 60 * 1000);
76 }
77 return fallbackMs;
78 }
79
62 80 function parseSegmentRetentionCount (value)
63 81 {
64 82 const parsed = Number.parseInt(String(value || ''), 10);
@@ -1290,6 +1308,11 @@ function getVideoStreamDebugSnapshot ()
1290 1308 };
1291 1309 }
1292 1310
1311 function getActiveStreamCount ()
1312 {
1313 return sessions.size;
1314 }
1315
1293 1316 module.exports = {
1294 1317 STREAM_ROOT_DIR,
1295 1318 STREAM_SESSION_TTL_MS,
@@ -1298,6 +1321,7 @@ module.exports = {
1298 1321 createVideoStreamSession,
1299 1322 sendVideoStreamAsset,
1300 1323 releaseVideoStreamSession,
1324 getActiveStreamCount,
1301 1325 getVideoStreamDebugSnapshot,
1302 1326 cleanupIdleStreamArtifacts,
1303 1327 };
@@ -11,6 +11,7 @@ const STREAM_ROOT_DIR = path.join(os.tmpdir(), 'filemanager-video-streams');
11const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
11const STREAM_SESSION_TTL_MS = 30 * 60 * 1000;
12const STREAM_READY_TIMEOUT_MS = 20 * 1000;
12const STREAM_READY_TIMEOUT_MS = 20 * 1000;
13const STREAM_IDLE_STOP_MS = 5 * 60 * 1000;
13const STREAM_IDLE_STOP_MS = 5 * 60 * 1000;
14const STREAM_EXPIRY_SWEEP_MS = parseSweepInterval(process.env.VIDEO_STREAM_EXPIRY_SWEEP_MS, 60 * 1000);
14const ESTIMATED_SEGMENT_BYTES = 1024 * 1024;
15const ESTIMATED_SEGMENT_BYTES = 1024 * 1024;
15const ESTIMATED_SEGMENT_DURATION_SECONDS = 6;
16const ESTIMATED_SEGMENT_DURATION_SECONDS = 6;
16const STREAM_PRUNE_DELETE_BATCH_SIZE = parsePruneDeleteBatchSize(process.env.VIDEO_STREAM_PRUNE_DELETE_BATCH_SIZE);
17const STREAM_PRUNE_DELETE_BATCH_SIZE = parsePruneDeleteBatchSize(process.env.VIDEO_STREAM_PRUNE_DELETE_BATCH_SIZE);
@@ -59,6 +60,23 @@ if (streamRootCleanupTimer && typeof streamRootCleanupTimer.unref === 'function'
59 streamRootCleanupTimer.unref();
60 streamRootCleanupTimer.unref();
60}
61}
61
62
63// Ensure expired leases/sessions are reclaimed even without further stream requests.
64const streamExpirySweepTimer = setInterval(pruneExpiredSessions, STREAM_EXPIRY_SWEEP_MS);
65if (streamExpirySweepTimer && typeof streamExpirySweepTimer.unref === 'function')
66{
67 streamExpirySweepTimer.unref();
68}
69
70function parseSweepInterval (value, fallbackMs)
71{
72 const parsed = Number.parseInt(String(value || ''), 10);
73 if (Number.isInteger(parsed) && parsed >= 1000)
74 {
75 return clampNumber(parsed, 1000, 10 * 60 * 1000);
76 }
77 return fallbackMs;
78}
79
62function parseSegmentRetentionCount (value)
80function parseSegmentRetentionCount (value)
63{
81{
64 const parsed = Number.parseInt(String(value || ''), 10);
82 const parsed = Number.parseInt(String(value || ''), 10);
@@ -1290,6 +1308,11 @@ function getVideoStreamDebugSnapshot ()
1290 };
1308 };
1291}
1309}
1292
1310
1311function getActiveStreamCount ()
1312{
1313 return sessions.size;
1314}
1315
1293module.exports = {
1316module.exports = {
1294 STREAM_ROOT_DIR,
1317 STREAM_ROOT_DIR,
1295 STREAM_SESSION_TTL_MS,
1318 STREAM_SESSION_TTL_MS,
@@ -1298,6 +1321,7 @@ module.exports = {
1298 createVideoStreamSession,
1321 createVideoStreamSession,
1299 sendVideoStreamAsset,
1322 sendVideoStreamAsset,
1300 releaseVideoStreamSession,
1323 releaseVideoStreamSession,
1324 getActiveStreamCount,
1301 getVideoStreamDebugSnapshot,
1325 getVideoStreamDebugSnapshot,
1302 cleanupIdleStreamArtifacts,
1326 cleanupIdleStreamArtifacts,
1303};
1327};
tests/files.routes.test.js +26 −0
@@ -777,6 +777,32 @@ describe('subtitle debug cache access', () =>
777 777 }
778 778 });
779 779
780 test('admins can delete files in the subtitle debug cache folder', async () =>
781 {
782 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
783 const logFile = path.join(logDir, '2026-05-25-delete-me-subtitlelog.txt');
784 fs.rmSync(logDir, { recursive: true, force: true });
785 fs.mkdirSync(logDir, { recursive: true });
786 fs.writeFileSync(logFile, 'delete me');
787
788 mockUser = {
789 username: 'admin',
790 isAdmin: true,
791 permissions: {},
792 };
793
794 try
795 {
796 const deleteRes = await req('POST', '/api/files/delete', { path: logFile });
797 expect(deleteRes.status).toBe(200);
798 expect(deleteRes.body).toEqual({ ok: true });
799 expect(fs.existsSync(logFile)).toBe(false);
800 } finally
801 {
802 fs.rmSync(logDir, { recursive: true, force: true });
803 }
804 });
805
780 806 test('non-admin users cannot browse the subtitle debug cache folder', async () =>
781 807 {
782 808 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
@@ -777,6 +777,32 @@ describe('subtitle debug cache access', () =>
777 }
777 }
778 });
778 });
779
779
780 test('admins can delete files in the subtitle debug cache folder', async () =>
781 {
782 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
783 const logFile = path.join(logDir, '2026-05-25-delete-me-subtitlelog.txt');
784 fs.rmSync(logDir, { recursive: true, force: true });
785 fs.mkdirSync(logDir, { recursive: true });
786 fs.writeFileSync(logFile, 'delete me');
787
788 mockUser = {
789 username: 'admin',
790 isAdmin: true,
791 permissions: {},
792 };
793
794 try
795 {
796 const deleteRes = await req('POST', '/api/files/delete', { path: logFile });
797 expect(deleteRes.status).toBe(200);
798 expect(deleteRes.body).toEqual({ ok: true });
799 expect(fs.existsSync(logFile)).toBe(false);
800 } finally
801 {
802 fs.rmSync(logDir, { recursive: true, force: true });
803 }
804 });
805
780 test('non-admin users cannot browse the subtitle debug cache folder', async () =>
806 test('non-admin users cannot browse the subtitle debug cache folder', async () =>
781 {
807 {
782 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
808 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
tests/subtitle-debug-log.test.js +39 −0
@@ -8,6 +8,7 @@ describe('subtitle debug log writer', () =>
8 8 {
9 9 const modulePath = require.resolve('../server/subtitle-debug-log');
10 10 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
11 const originalContextLimit = process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX;
11 12
12 13 beforeEach(() =>
13 14 {
@@ -15,6 +16,12 @@ describe('subtitle debug log writer', () =>
15 16 fs.rmSync(logDir, { recursive: true, force: true });
16 17 });
17 18
19 afterEach(() =>
20 {
21 if (originalContextLimit === undefined) delete process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX;
22 else process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX = originalContextLimit;
23 });
24
18 25 test('writes timestamped per-video subtitle log files', () =>
19 26 {
20 27 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
@@ -85,4 +92,36 @@ describe('subtitle debug log writer', () =>
85 92 expect(entries).toHaveLength(1);
86 93 expect(entries[0]).toContain('new-video.mkv-subtitlelog.txt');
87 94 });
95
96 test('evicts old context keys when subtitle log context map reaches cap', () =>
97 {
98 process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX = '2';
99 jest.resetModules();
100 const logModule = require('../server/subtitle-debug-log');
101
102 const firstPath = logModule.appendSubtitleDebugEntries({
103 videoName: 'ctx-video.mkv',
104 context: { source: 'app', sessionId: 'sess-1' },
105 entries: [{ loggedAtMs: 1000, eventType: 'first' }],
106 });
107
108 for (let i = 0; i < 6; i++)
109 {
110 logModule.appendSubtitleDebugEntries({
111 videoName: `ctx-video-${i}.mkv`,
112 context: { source: 'app', sessionId: `sess-${i + 2}` },
113 entries: [{ loggedAtMs: 2000 + i, eventType: 'filler' }],
114 });
115 }
116
117 const secondPath = logModule.appendSubtitleDebugEntries({
118 videoName: 'ctx-video.mkv',
119 context: { source: 'app', sessionId: 'sess-1' },
120 entries: [{ loggedAtMs: 999999, eventType: 'second' }],
121 });
122
123 expect(typeof firstPath).toBe('string');
124 expect(typeof secondPath).toBe('string');
125 expect(logModule.getSubtitleDebugLogContextCount()).toBeLessThanOrEqual(2);
126 });
88 127 });
@@ -8,6 +8,7 @@ describe('subtitle debug log writer', () =>
8{
8{
9 const modulePath = require.resolve('../server/subtitle-debug-log');
9 const modulePath = require.resolve('../server/subtitle-debug-log');
10 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
10 const logDir = path.join(os.tmpdir(), 'filemanager-subtitle-debug-logs');
11 const originalContextLimit = process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX;
11
12
12 beforeEach(() =>
13 beforeEach(() =>
13 {
14 {
@@ -15,6 +16,12 @@ describe('subtitle debug log writer', () =>
15 fs.rmSync(logDir, { recursive: true, force: true });
16 fs.rmSync(logDir, { recursive: true, force: true });
16 });
17 });
17
18
19 afterEach(() =>
20 {
21 if (originalContextLimit === undefined) delete process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX;
22 else process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX = originalContextLimit;
23 });
24
18 test('writes timestamped per-video subtitle log files', () =>
25 test('writes timestamped per-video subtitle log files', () =>
19 {
26 {
20 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
27 const { appendSubtitleDebugEntries } = require('../server/subtitle-debug-log');
@@ -85,4 +92,36 @@ describe('subtitle debug log writer', () =>
85 expect(entries).toHaveLength(1);
92 expect(entries).toHaveLength(1);
86 expect(entries[0]).toContain('new-video.mkv-subtitlelog.txt');
93 expect(entries[0]).toContain('new-video.mkv-subtitlelog.txt');
87 });
94 });
95
96 test('evicts old context keys when subtitle log context map reaches cap', () =>
97 {
98 process.env.SUBTITLE_DEBUG_LOG_CONTEXT_KEYS_MAX = '2';
99 jest.resetModules();
100 const logModule = require('../server/subtitle-debug-log');
101
102 const firstPath = logModule.appendSubtitleDebugEntries({
103 videoName: 'ctx-video.mkv',
104 context: { source: 'app', sessionId: 'sess-1' },
105 entries: [{ loggedAtMs: 1000, eventType: 'first' }],
106 });
107
108 for (let i = 0; i < 6; i++)
109 {
110 logModule.appendSubtitleDebugEntries({
111 videoName: `ctx-video-${i}.mkv`,
112 context: { source: 'app', sessionId: `sess-${i + 2}` },
113 entries: [{ loggedAtMs: 2000 + i, eventType: 'filler' }],
114 });
115 }
116
117 const secondPath = logModule.appendSubtitleDebugEntries({
118 videoName: 'ctx-video.mkv',
119 context: { source: 'app', sessionId: 'sess-1' },
120 entries: [{ loggedAtMs: 999999, eventType: 'second' }],
121 });
122
123 expect(typeof firstPath).toBe('string');
124 expect(typeof secondPath).toBe('string');
125 expect(logModule.getSubtitleDebugLogContextCount()).toBeLessThanOrEqual(2);
126 });
88});
127});