Trigger immediate pool replenishment after stamp acquisition

[crtahlin]

Problem

Currently, the stamp pool only replenishes during scheduled background checks (every 15 minutes by default). When a user acquires a stamp via POST /api/v1/pool/acquire, the pool reserve decreases but no immediate action is taken to replenish.

This creates a gap where:

1. User acquires a stamp, pool reserve for that size drops below target
2. Next user might find no stamps available for that size
3. Must wait up to 15 minutes for background task to replenish

Proposed Solution

After successfully releasing a stamp to a user, immediately check if the reserve count for that stamp size is now below its target. If so, trigger an asynchronous purchase of a replacement stamp.

Key points:

• Non-blocking: The purchase runs in the background; user receives their stamp immediately
• Targeted: Only purchase a stamp of the same size that was just released
• Single stamp: Purchase one stamp to replace the one just acquired (not a full pool sync)
• Fire-and-forget: Log errors but don't fail the user's acquire request

Implementation Approach

1. Add a new method trigger_replenishment_if_needed(stamp_size: int) to StampPoolManager
2. After release_stamp() succeeds in the acquire endpoint, call this method with the released stamp's size
3. The method checks if current_reserve_count < target_reserve_count for that stamp size
4. If below target, spawn an async task to purchase one replacement stamp
5. Add config option STAMP_POOL_IMMEDIATE_REPLENISH (default: true) to enable/disable

Code Location

• app/services/stamp_pool.py - Add replenishment trigger method
• app/api/endpoints/pool.py - Call trigger after successful release in acquire_stamp()

Acceptance Criteria

• After acquiring a stamp, if pool reserve for that size drops below target, a replacement stamp is purchased
• Replenishment is async - user response is not delayed
• Errors during replenishment are logged but don't affect user response
• Feature can be disabled via config
• Unit tests cover the new behavior

Related

• Original stamp pool implementation: Stamp Pool Management for Low-Latency Provisioning #63