[6.x] Fix static cache urls map race conditions under concurrent requests

[panda4man]

The problem

The static cache keeps a slug => path urls map under one cache key per domain (static-cache:{md5(domain)}.urls). Every write to it was an unguarded read–modify–write:

 time │ Request A — caches /blog │  urls map (single key)  │ Request B — caches /about
──────┼──────────────────────────┼─────────────────────────┼──────────────────────────
  t1  │ read  ──────────────────►│ { }                     │
  t2  │                          │ { } ◄───────────────────│ read
  t3  │ write ──────────────────►│ { /blog }               │
  t4  │                          │ { /about } ◄────────────│ write
      │                          │      ▲                  │
      │                          │      └── /blog entry silently lost

The middleware's existing lock is per-URL, so two requests caching different URLs never contend — but they share the same map.

after t4	page on disk / in cache	in urls map	invalidation can find it?
/about	✅	✅	yes
/blog	✅	❌	never — stale until a full cache clear

On high-traffic and load-balanced sites this happens routinely.

The fix

1. Serialize map writes with an atomic lock

 cacheUrl · forgetUrl · cacheDomain · invalidate · flush
                      │
                      ▼
        ┌────────────────────────────────┐
        │ Cache::lock('<urls key>:lock') │  per domain, same store as the map
        └────────────────────────────────┘
                      │
             read → modify → write         serialized, no lost updates

 serving a cached page (reads) ──► no lock, unaffected
 store without LockProvider    ──► runs unlocked, exactly as before

Works on the file, redis, database, and array stores.

2. Never leave an orphan on lock timeout

 before │ render ─► write file ─► can't get lock ─► 503 refresh page, file left orphaned
 after  │ render ─► write file ─► can't get lock ─► undo the write ─► serve response uncached

FileCacher deletes the file it just wrote; ApplicationCacher skips storing the response. Either way the rendered response is still served.

3. Hold the lock for map bookkeeping only

 before — invalidating 500 urls
   lock ├─────────────────────────────────────────────────────────────────┤
        │ 500 × (read map · delete file · write map · dispatch event)     │
        └─ seconds under lock: visitors block, lock can expire mid-run ───┘

 after
   lock ├────┤
        │ resolve matches · one map write │
        └────┘──► unlocked: delete files · dispatch UrlInvalidated events

Lock holds are milliseconds regardless of batch size, so bulk invalidation (e.g. the CP "Invalidate URLs" utility) can no longer stall visitor requests, time out, or outlive the lock's expiry. Flushing wipes the urls map before deleting stored pages, so a page cached mid-flush can't become untracked. As a bonus, FileCacher runs its untracked-file scan once per batch instead of once per URL, and bulk invalidation writes the map once per domain instead of once per entry.

The worst remaining interleaving is a map entry whose cached copy was just deleted — self-healing, since the next request re-caches under the same key. The dangerous direction, a cached page invisible to the map, can no longer occur.

Behavior notes

• The CP "Invalidate URLs" utility shows a friendly "cache was locked, try again" message instead of a 500 if the lock is genuinely contended.
• UrlInvalidated still fires for every requested URL (including ones not in the map), with wildcards expanding to the entries they matched — CDN-purger listeners are unaffected.
• On the database cache driver, locks use the cache_locks table, which upgraded apps without the default Laravel cache migration may need to add.

One breaking change for custom cachers

Custom cachers extending AbstractCacher must now implement the cleanupInvalidatedUrls() hook, and invalidateUrls() no longer routes through invalidateUrl(). Deliberately abstract, so existing subclasses fail loudly instead of silently skipping their storage cleanup. Cachers implementing the Cacher interface directly are unaffected. (Happy to add hints for an upgrade-guide note.)

Tests

Written test-first. Concurrency tests assert: the lock is shared per domain, batches acquire it once and write the map once, cleanup and events run after the lock is released, flush wipes the map before deleting pages, and a contended lock during page caching leaves no orphan while still serving the rendered response. Existing invalidation suites (query-string variants, multisite paths, wildcard expansion, event payloads) pass unchanged except CacherTest::it_invalidates_urls, which asserted the old internal routing and now asserts the same outcomes and event counts through the new path.

🤖 Generated with Claude Code

[duncanmcclean]

Thanks for the pull request!

Does this fix an open issue or is just something you've run into?

[panda4man]

@duncanmcclean This is something I've run in to. If I missed something in the PR guidelines for how to submit this, let me know and I'll revisit to see what changes I need to make.

[duncanmcclean]

No problem - was just curious if it closed something. 🙂