BlueGit

timfa filemanager

fix: periodically clear idle stream output artifacts

Adds periodic cleanup of temporary HLS stream output directories whenever no viewers are active, alongside startup cleanup. This prevents stale segment folders from lingering after crashes or interrupted sessions and improves long-run streaming stability and memory/disk hygiene.

timfa Tim Falken · pushed by timfa

Authored 2026-05-20 · 6 months ago

Hash
6875a133d1369f128a769be39687a3b3c581d546
Parent
7be2c78b
3 files changed +55 −0
.github/technical-reference.md +2 −0
@@ -129,6 +129,8 @@
129 129 - sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
130 130 - releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
131 131 - runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
132 - 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.
133 - 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.
132 134 - 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.
133 135 - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
134 136 - STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
@@ -129,6 +129,8 @@
129- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
129- sendVideoStreamAsset(sessionId, assetPath, req, res) - Resolves viewer leases to a shared stream session, serves HLS assets, tracks lease activity, and prunes segments using the slowest active viewer position.
130- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
130- releaseVideoStreamSession(sessionId) - Releases one viewer lease; only destroys the underlying transcode session when no active leases remain; cleanup also clears image subtitle frame/event caches to prevent memory accumulation.
131- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
131- runSegmentPrune(session) - Removes HLS segment files that fall behind the slowest active viewer and calls pruneImageSubtitleCachesForSession() to drop old subtitle frames once they pass end time + duration + 30 seconds, so subtitle buffers follow the same retention rules as video chunks.
132- 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.
133- 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.
132- 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.
134- 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.
133- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
135- STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
134- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
136- STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
server/video-stream.js +29 −0
@@ -28,6 +28,34 @@ const reusableSessionIdBySource = new Map();
28 28 // Remove any .sup subtitle files left over from a previous server run.
29 29 purgeSubtitleCacheDir();
30 30
31 function purgeStreamRootDir ()
32 {
33 try
34 {
35 fs.rmSync(STREAM_ROOT_DIR, { recursive: true, force: true });
36 } catch
37 {
38 // Best-effort cleanup.
39 }
40 }
41
42 function cleanupIdleStreamArtifacts ()
43 {
44 if (sessions.size > 0) return;
45 if (leases.size > 0) return;
46 purgeStreamRootDir();
47 }
48
49 // Remove stale stream output folders left by previous runs.
50 purgeStreamRootDir();
51
52 // Periodically sweep stream artifacts when no streams are active.
53 const streamRootCleanupTimer = setInterval(cleanupIdleStreamArtifacts, STREAM_IDLE_STOP_MS);
54 if (streamRootCleanupTimer && typeof streamRootCleanupTimer.unref === 'function')
55 {
56 streamRootCleanupTimer.unref();
57 }
58
31 59 function parseSegmentRetentionCount (value)
32 60 {
33 61 const parsed = Number.parseInt(String(value || ''), 10);
@@ -1177,4 +1205,5 @@ module.exports = {
1177 1205 sendVideoStreamAsset,
1178 1206 releaseVideoStreamSession,
1179 1207 getVideoStreamDebugSnapshot,
1208 cleanupIdleStreamArtifacts,
1180 1209 };
@@ -28,6 +28,34 @@ const reusableSessionIdBySource = new Map();
28// Remove any .sup subtitle files left over from a previous server run.
28// Remove any .sup subtitle files left over from a previous server run.
29purgeSubtitleCacheDir();
29purgeSubtitleCacheDir();
30
30
31function purgeStreamRootDir ()
32{
33 try
34 {
35 fs.rmSync(STREAM_ROOT_DIR, { recursive: true, force: true });
36 } catch
37 {
38 // Best-effort cleanup.
39 }
40}
41
42function cleanupIdleStreamArtifacts ()
43{
44 if (sessions.size > 0) return;
45 if (leases.size > 0) return;
46 purgeStreamRootDir();
47}
48
49// Remove stale stream output folders left by previous runs.
50purgeStreamRootDir();
51
52// Periodically sweep stream artifacts when no streams are active.
53const streamRootCleanupTimer = setInterval(cleanupIdleStreamArtifacts, STREAM_IDLE_STOP_MS);
54if (streamRootCleanupTimer && typeof streamRootCleanupTimer.unref === 'function')
55{
56 streamRootCleanupTimer.unref();
57}
58
31function parseSegmentRetentionCount (value)
59function parseSegmentRetentionCount (value)
32{
60{
33 const parsed = Number.parseInt(String(value || ''), 10);
61 const parsed = Number.parseInt(String(value || ''), 10);
@@ -1177,4 +1205,5 @@ module.exports = {
1177 sendVideoStreamAsset,
1205 sendVideoStreamAsset,
1178 releaseVideoStreamSession,
1206 releaseVideoStreamSession,
1179 getVideoStreamDebugSnapshot,
1207 getVideoStreamDebugSnapshot,
1208 cleanupIdleStreamArtifacts,
1180};
1209};
tests/video-stream.test.js +24 −0
@@ -586,6 +586,30 @@ describe('video stream bootstrap', () =>
586 586 expect(purgeSubtitleCacheDir).toHaveBeenCalledTimes(1);
587 587 });
588 588
589 test('purges stream output directory when the module is first loaded', () =>
590 {
591 const streamRoot = path.join(os.tmpdir(), 'filemanager-video-streams');
592 const orphanDir = path.join(streamRoot, 'orphan-after-restart');
593 fs.mkdirSync(orphanDir, { recursive: true });
594 fs.writeFileSync(path.join(orphanDir, 'stream_0_segment_000001.ts'), 'segment');
595
596 require('../server/video-stream');
597 expect(fs.existsSync(orphanDir)).toBe(false);
598 });
599
600 test('cleanupIdleStreamArtifacts removes stream output directory when no streams are active', () =>
601 {
602 const streamRoot = path.join(os.tmpdir(), 'filemanager-video-streams');
603 const orphanDir = path.join(streamRoot, 'orphan-idle-cleanup');
604 fs.mkdirSync(orphanDir, { recursive: true });
605 fs.writeFileSync(path.join(orphanDir, 'stream_0.m3u8'), '#EXTM3U\n');
606
607 const streamModule = require('../server/video-stream');
608 streamModule.cleanupIdleStreamArtifacts();
609
610 expect(fs.existsSync(orphanDir)).toBe(false);
611 });
612
589 613 test('clears subtitle caches for a video when its last stream is released', async () =>
590 614 {
591 615 mockSpawn.mockImplementation((command, args) =>
@@ -586,6 +586,30 @@ describe('video stream bootstrap', () =>
586 expect(purgeSubtitleCacheDir).toHaveBeenCalledTimes(1);
586 expect(purgeSubtitleCacheDir).toHaveBeenCalledTimes(1);
587 });
587 });
588
588
589 test('purges stream output directory when the module is first loaded', () =>
590 {
591 const streamRoot = path.join(os.tmpdir(), 'filemanager-video-streams');
592 const orphanDir = path.join(streamRoot, 'orphan-after-restart');
593 fs.mkdirSync(orphanDir, { recursive: true });
594 fs.writeFileSync(path.join(orphanDir, 'stream_0_segment_000001.ts'), 'segment');
595
596 require('../server/video-stream');
597 expect(fs.existsSync(orphanDir)).toBe(false);
598 });
599
600 test('cleanupIdleStreamArtifacts removes stream output directory when no streams are active', () =>
601 {
602 const streamRoot = path.join(os.tmpdir(), 'filemanager-video-streams');
603 const orphanDir = path.join(streamRoot, 'orphan-idle-cleanup');
604 fs.mkdirSync(orphanDir, { recursive: true });
605 fs.writeFileSync(path.join(orphanDir, 'stream_0.m3u8'), '#EXTM3U\n');
606
607 const streamModule = require('../server/video-stream');
608 streamModule.cleanupIdleStreamArtifacts();
609
610 expect(fs.existsSync(orphanDir)).toBe(false);
611 });
612
589 test('clears subtitle caches for a video when its last stream is released', async () =>
613 test('clears subtitle caches for a video when its last stream is released', async () =>
590 {
614 {
591 mockSpawn.mockImplementation((command, args) =>
615 mockSpawn.mockImplementation((command, args) =>