Laravel Waiting Request

The article describes a common concurrency problem in web applications where a background job processes data while a subsequent request attempts to read that same data, potentially returning stale or incorrect information. It introduces the `aihimel/laravel-waiting-request` Laravel package, which solves this by allowing a request to "park" and wait until the background job signals that the resource is ready, using a cache-backed system of blockers and resolvers. The package provides a simple API with methods like `addBlocker`, `whenResolved`, and `resolveBlocker`, and includes safety features such as automatic expiry for crashed jobs to prevent indefinite waiting.

The Problem You are processing some data through background job. But before the processing is done, another request had been made to read the related data. In this case you are either providing a historic data or serving wrong information. Solution Holding the request until the job is executed, could be the simplest solution. I am not saying it is the only solution, but the simplest one. Some Scenarios Lets discuss about some possible scenarios. Booking Job When a user request to book a resource between two specifics dates. Let's assume that it is done by a job. So it might take some time in production load. In the meantime if another request is asking for that specific users booking data. File Importing Job User uploads a file like CSV or XML, you have accepted the file but it also needs processing, which should be done in by a job. If the user ask for the status of the CSV resource in another request. The Package aihimel/laravel-waiting-request https://packagist.org/packages/aihimel/laravel-waiting-request is a small Laravel package that solves exactly this — it lets one request park until another piece of work a job, a sync, a long-running controller action signals that the resource is ready to read. Install composer require aihimel/laravel-waiting-request Optionally publish the config: php artisan vendor:publish --tag="waiting-request-config" How it works The package exposes a tiny API around four ideas: block , wait , check , resolve . Under the hood it is backed by your Laravel cache — no extra infrastructure, no queue plumbing. A blocker is identified by a class path and a resource id . That pair becomes a unique cache key, so blockers are per-resource booking 42 does not interfere with booking 43 . php use Aihimel\LaravelWaitingRequest\Facades\LWRequest; // 1. Block — call this where the background work starts LWRequest::addBlocker Booking::class, $booking- id ; // 2. Wait — call this in the request that wants to read the resource $resolved = LWRequest::whenResolved Booking::class, $booking- id ; if $resolved { return BookingResource::make $booking- fresh ; } return response - json 'message' = 'Still processing, try again' , 202 ; // 3. Resolve — call this when the background work finishes LWRequest::resolveBlocker Booking::class, $booking- id ; You can also peek without waiting: php if LWRequest::isBlocked Booking::class, $booking- id { // resource is mid-flight } Applying it to the scenarios Booking job. The controller that accepts the booking calls addBlocker Booking::class, $id and dispatches the job. The job calls resolveBlocker ... in its handle or in a finally block . Any reader that hits GET /bookings/{id} in the meantime calls whenResolved ... first and only reads the model once the writer is done. File importing job. Same shape: addBlocker Import::class, $import- id when the upload is accepted, resolveBlocker ... when the parser finishes success or failure — both should release . The status endpoint calls whenResolved ... so the client gets a settled answer instead of a half-imported snapshot. Sensible defaults you can tune Every knob lives in config/waiting-request.php and is overridable via env: | Config | Env | Default | What it does | |---|---|---|---| cache prefix | LW REQUEST CACHE PREFIX | lw request | Namespace for cache keys | timeout | LW REQUEST MAX WAITING TIME | 5 | How long whenResolved waits before giving up seconds | check interval | LW REQUEST CHECK INTERVAL | 250 | Poll interval inside whenResolved milliseconds | max blocking time | LW REQUEST MAX BLOCKING TIME | 10 | Max lifetime of a blocker before it auto-expires seconds | addBlocker takes an optional third argument so you can bump the TTL per call when you know a particular job runs longer: php LWRequest::addBlocker Import::class, $import- id, 120 ; // 2 minutes Why the blocker has a lifetime If a job crashes before calling resolveBlocker , you do not want readers to wait forever. From v2.x every blocker carries a Unix expiry timestamp. The next isBlocked / whenResolved call after that timestamp will: - Forget the cache entry, and - Emit Log::warning 'Waiting-request blocker expired without being resolved', ... So even if your job dies, traffic recovers on its own and you get a log line telling you it happened. Do's and Don'ts Do - Do release the blocker in Wrap your job body so a thrown exception still hits finally . resolveBlocker . Auto-expiry is a backstop, not a happy path. - Do set If your import averages 8s and worst-cases at 25s, a 10s default will auto-release while the job is still running — defeating the lock. max blocking time to comfortably exceed your worst-case job duration. - Do tune If a client is willing to wait 2s for a synchronous response, set timeout to match your UX budget. timeout=2 ; do not let whenResolved hold an HTTP worker for 30s. - Do flush the cache when upgrading from 1.x to 2.x. Pre-upgrade values stored as true will be read as 1 , treated as already-expired, and produce a one-time burst of warning logs. - Do treat a Respond with false return from whenResolved as "still pending". 202 Accepted or similar and let the client poll — do not pretend the data is ready. Don't - Don't put It evicts expired entries and writes a log line. That is intentional, but worth knowing. isBlocked on a hot, read-only path you expect to be side-effect-free. - Don't use it as a distributed mutex for This package is for writes . readers waiting on writers on a best-effort basis. If two writers race, Cache::add will reject the second addBlocker it returns false , but the package does not give you queueing, fairness, or strict mutual exclusion. - Don't share a single blocker across unrelated resources. Key it by the real resource Booking::class + $id , not by something coarse like the user id, or you will block requests that have nothing to do with each other. - Don't forget the cache driver matters. array or file drivers will not work across processes. In production, use redis / memcached so the worker that resolves the blocker and the web process that is waiting actually share the same cache. - Don't lean on Polling inside a worker burns a worker slot. Workers should whenResolved from a queue worker. resolve blockers, not wait on them. That's the whole package — a couple of facade calls, a cache key per resource, and a sane expiry so nothing wedges. If you've ever shipped a ?retry=true hack or a sleep-and-pray in a controller, this is the cleaner version of that. Source & issues: github.com/aihimel/laravel-waiting-request https://github.com/aihimel/laravel-waiting-request