coracle/vthumbs
2
1
Fork 1
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Feat: Add Bounded Concurrency and Timeout Controls for /thumbnail #5

New Issue
Closed
opened 2026-04-15 19:17:58 +00:00 by priyanshu_bharti · 3 comments
priyanshu_bharti commented 2026-04-15 19:17:58 +00:00
Contributor
Copy Link
Copy Source

Problem

Today, each /thumbnail request can start ffmpeg work immediately. This is fine for light traffic, but during spikes (or when upstream media is slow/unreachable), the service can get overloaded and response times become unpredictable.

Proposal

Add a small in-process job controller with configurable limits:

  • MAX_CONCURRENT_JOBS (default: 4)
  • MAX_QUEUE_SIZE (default: 100)
  • REQUEST_TIMEOUT_MS (default: 15000)
  • FFMPEG_TIMEOUT_MS (default: 12000)

Expected behavior:

  1. If a worker slot is free, process immediately.
  2. If workers are busy, enqueue up to MAX_QUEUE_SIZE.
  3. If queue is full, fail fast with 429 (or 503) and a clear JSON message.
  4. If timeout is reached, terminate ffmpeg and return a timeout error.
  5. If client disconnects, cancel the running ffmpeg job.

Example Error Responses

{ "error": "Server busy, try again later" }

{ "error": "Thumbnail generation timed out" }

Acceptance Criteria

  • Max concurrent ffmpeg jobs is bounded and configurable.
  • Queue size is bounded and configurable.
  • Over-capacity requests return deterministic overload response.
  • Timeouts produce deterministic timeout response.
  • ffmpeg is cleaned up on timeout and client disconnect.
  • README documents new environment variables and behavior.
  • Tests cover normal flow, queue saturation, timeout, and client abort.

Why This Helps

This keeps the current API simple while making the service much safer and more predictable in real production traffic.

## Problem Today, each `/thumbnail` request can start ffmpeg work immediately. This is fine for light traffic, but during spikes (or when upstream media is slow/unreachable), the service can get overloaded and response times become unpredictable. ## Proposal Add a small in-process job controller with configurable limits: - `MAX_CONCURRENT_JOBS` (default: `4`) - `MAX_QUEUE_SIZE` (default: `100`) - `REQUEST_TIMEOUT_MS` (default: `15000`) - `FFMPEG_TIMEOUT_MS` (default: `12000`) Expected behavior: 1. If a worker slot is free, process immediately. 2. If workers are busy, enqueue up to `MAX_QUEUE_SIZE`. 3. If queue is full, fail fast with `429` (or `503`) and a clear JSON message. 4. If timeout is reached, terminate ffmpeg and return a timeout error. 5. If client disconnects, cancel the running ffmpeg job. ## Example Error Responses ```json { "error": "Server busy, try again later" } ``` ```json { "error": "Thumbnail generation timed out" } ``` ## Acceptance Criteria - Max concurrent ffmpeg jobs is bounded and configurable. - Queue size is bounded and configurable. - Over-capacity requests return deterministic overload response. - Timeouts produce deterministic timeout response. - ffmpeg is cleaned up on timeout and client disconnect. - README documents new environment variables and behavior. - Tests cover normal flow, queue saturation, timeout, and client abort. ## Why This Helps This keeps the current API simple while making the service much safer and more predictable in real production traffic.
hodlbod commented 2026-04-15 21:24:19 +00:00
Owner
Copy Link
Copy Source

YAGNI, I don't think we need to invest any more effort into this project right now. We'll hyperscale when it starts causing problems. We can leave this open though because it's not a bad idea in theory.

YAGNI, I don't think we need to invest any more effort into this project right now. We'll hyperscale when it starts causing problems. We can leave this open though because it's not a bad idea in theory.
priyanshu_bharti commented 2026-04-16 17:27:48 +00:00
Author
Contributor
Copy Link
Copy Source

Hey @hodlbod,
I’m a bit confused about which project I should focus on for Summer of Bitcoin.
Could you please suggest which one would be best to work on right now?

The options I’m considering are: flotilla, vthumbs, zoid, nostrlib, caravel, or any other project you think is more suitable.

Also, on the Summer of Bitcoin website, I only see flotilla listed as a project.
So, could you please confirm, should I focus only on flotilla for the application?

I want to focus properly on just one project, so your guidance would really help me decide.
Thanks!

Hey @hodlbod, I’m a bit confused about which project I should focus on for Summer of Bitcoin. Could you please suggest which one would be best to work on right now? The options I’m considering are: flotilla, vthumbs, zoid, nostrlib, caravel, or any other project you think is more suitable. Also, on the Summer of Bitcoin website, I only see flotilla listed as a project. So, could you please confirm, should I focus only on flotilla for the application? I want to focus properly on just one project, so your guidance would really help me decide. Thanks!
hodlbod commented 2026-04-16 17:46:15 +00:00
Owner
Copy Link
Copy Source

Your proposal should focus on flotilla, that's where most of the long term work will be done. vthumbs is a separate repository, but it's really part of the main flotilla project as supporting infrastructure.

Your proposal should focus on flotilla, that's where most of the long term work will be done. vthumbs is a separate repository, but it's really part of the main flotilla project as supporting infrastructure.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
hodlbod (hodlbod)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: coracle/vthumbs#5
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?