Summary
list_videos_v1 offloads its blocking filesystem work with asyncio.to_thread but is not admitted through the shared _get_fs_walk_gate() budget, so it consumes default-executor workers outside the bound that the gate exists to enforce.
Detail
src/youtube_extension/backend/api/v1/router.py:
total, paginated_videos, past_end = await asyncio.to_thread(
_collect_videos_page, data_service, limit, offset
)Every other filesystem-walking endpoint in this module acquires the gate first:
get_cache_stats_v1 - async with _get_fs_walk_gate():get_video_detail_v1 - async with _get_fs_walk_gate():get_learning_log_v1 - async with _get_fs_walk_gate():
The /videos offload predates the gate: it landed in #1379 and the gate was introduced afterwards in #1386, so the call site was never retrofitted.
Why it matters
_FS_WALK_MAX_CONCURRENCY is 4 against a default ThreadPoolExecutor sized min(32, (os.cpu_count() or 1) + 4), which is as few as 5 workers on a single-core container. The budget is chosen so that gated walks always leave at least one worker free for unrelated to_thread callers. An ungated walker can occupy that reserved headroom, which is precisely the starvation the gate was added to prevent.
Proposed fix
Wrap the existing to_thread call in async with _get_fs_walk_gate(): and extend the cross-endpoint shared-budget regression test to include /videos.
Note
This is a correctness gap in a global invariant rather than a hot-path regression, and it touches an endpoint unrelated to any current change, so it is filed separately rather than folded into an in-flight PR.
Summary
list_videos_v1offloads its blocking filesystem work withasyncio.to_threadbut is not admitted through the shared_get_fs_walk_gate()budget, so it consumes default-executor workers outside the bound that the gate exists to enforce.Detail
src/youtube_extension/backend/api/v1/router.py:Every other filesystem-walking endpoint in this module acquires the gate first:
get_cache_stats_v1-async with _get_fs_walk_gate():get_video_detail_v1-async with _get_fs_walk_gate():get_learning_log_v1-async with _get_fs_walk_gate():The
/videosoffload predates the gate: it landed in #1379 and the gate was introduced afterwards in #1386, so the call site was never retrofitted.Why it matters
_FS_WALK_MAX_CONCURRENCYis 4 against a defaultThreadPoolExecutorsizedmin(32, (os.cpu_count() or 1) + 4), which is as few as 5 workers on a single-core container. The budget is chosen so that gated walks always leave at least one worker free for unrelatedto_threadcallers. An ungated walker can occupy that reserved headroom, which is precisely the starvation the gate was added to prevent.Proposed fix
Wrap the existing
to_threadcall inasync with _get_fs_walk_gate():and extend the cross-endpoint shared-budget regression test to include/videos.Note
This is a correctness gap in a global invariant rather than a hot-path regression, and it touches an endpoint unrelated to any current change, so it is filed separately rather than folded into an in-flight PR.