Horizontal Worker scaling with PostgreSQL claim coordination

[bitbiter-dev]

Problem

A single Worker is a processing bottleneck when a deployment has many users or very large libraries. There is no way to add capacity without architectural changes.

Proposed mechanism

Add two columns to MediaAsset:

• claimed_by_worker_id (guid, nullable)
• claimed_at (datetime, nullable)

Before processing a file, a Worker atomically claims it:

UPDATE media_assets
SET claimed_by_worker_id = @workerId, claimed_at = NOW()
WHERE id = @id AND claimed_by_worker_id IS NULL

If the claim succeeds the Worker processes the file; if not, another Worker already has it. Stale claims (Worker crashed mid-job) expire after a configurable timeout and become available again.

Workers without WORKER__USER all draw from the global pool safely — the claim prevents duplicates. Fair round-robin scheduling still applies per-Worker across users.

No external coordinator needed — PostgreSQL row-level locking or advisory locks are sufficient. No Redis, no Hangfire.

Questions to resolve before implementing

• What is the right stale-claim timeout? (5 min? 30 min? configurable?)
• Should the Worker ID be set via env var (WORKER__ID) or auto-generated (UUID on startup)?
• Should worker count and queue depth be exposed as metrics (OTEL)?
• How does the claim mechanism interact with the crawl interval — do claims persist across crawl cycles or reset?
• Is there a risk of thundering herd when many Workers start simultaneously after a deploy?

Not in scope for v1.0

Revisit after Epic 4 (reconciliation) is stable and single-Worker performance has been measured in practice.