Webservice Core Async Bundle Laravel Package

Product Decisions This Supports

• Shipping features that generate concurrent duplicate traffic. The middleware's core promise—one upstream call per lock, cached replay for waiters—is what makes bursty features safe: dashboards fanning out to a SOAP backend, bulk imports, retry storms from mobile clients. v1.3.11 fixes a defect that inverted this promise: a waiter that reloaded received only the raw response, so its logging, cache-store, and unlock middleware never ran, the lock was held for the full 60s TTL, and throughput collapsed to roughly one request per minute per lock while everything else queued. Any roadmap item that assumes horizontal scalability of read traffic was effectively unshipped until this patch.
• Treating reliability as a funded workstream, not cleanup. The failure-path fixes (lock released when cache-store fails, when TTL callback or tagging fails, or on any Throwable before a response exists; the 423 {"cacheId": ...} placeholder can no longer leak to callers as a success; reloaded-request failures surface with their real cause) remove a class of incidents that present to support as "random 60-second hangs" and "empty 200s." That is a support-cost and trust argument, not a code-quality argument.
• Observability before capacity spend. logs/lock_wait_threshold (default 5s) now emits a <customAction>:lock_wait warning. Lock contention becomes a measurable leading indicator of upstream saturation—usable as an SLO input and as evidence for scaling the downstream service rather than guessing at it.
• Build vs. buy. The edge cases this release closes—re-resolving a reloaded response through its own pipeline, distinguishing a lock placeholder from a real success, releasing locks on non-transport throwables—are precisely what in-house lock-and-replay middleware gets wrong. Building this ourselves means owning that bug surface permanently.
• Upgrade sequencing. v1.3.11 is risk remediation, not feature delivery; it should be scheduled as such. One compatibility item needs a code audit, not a rewrite: CacheManager::awaitUnlock() now returns the seconds waited (float) instead of void. Callers that ignored the return are unaffected, but any subclass override declaring : void, or any interface/mock asserting void, will fatal. The optional autowired MonologLogHandler on LockResponseLoaderResponseModifier and the new public static ReloadLockedResponseResponseModifier::reloadLockedResponse() are additive and safe.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP with a shared cache backend (Redis/Memcached) that supports atomic locks, and you serve concurrent, duplicate, idempotent requests against a slow, expensive, or rate-limited upstream—classic fits are SOAP services and the soap-core-async-bundle stack this release explicitly supports (v2.0.1 relies on the new public static reload helper).
• Serving a cached copy seconds late is acceptable to your users, and the alternative is a stampede that degrades the upstream for everyone.
• You want contention to be observable rather than inferred—the new lock-wait warning makes the trade-off between queueing and calling upstream a tunable you can see.
• Your team can debug middleware pipelines; the behavior here is pipeline-order-sensitive and worth understanding before it is load-bearing.

Look elsewhere when:

• Operations are non-idempotent writes, or responses are user-scoped and must not be replayed across callers.
• The 60s lock TTL semantics don't fit your latency budget—worst-case stalls are bounded by that TTL, so a long default is a product decision you must consciously own.
• Traffic is already serialized or single-worker, where locking adds overhead for no deduplication benefit.
• You need durable, cross-request job deduplication—a queue-level uniqueness model is a better fit than request middleware.
• You require strict semantic-versioning guarantees across a major line; the awaitUnlock() return-type change is a reminder that 1.x patches can carry signature changes.

How to Pitch It (Stakeholders)

To executives (one paragraph): This patch fixes a defect that silently throttled concurrent traffic hitting expensive backend services—under contention, throughput could fall to roughly one request per minute per lock, with the lock held for its full TTL and no trace in the logs. It also turns lock contention into a logged, measurable signal and stops lock placeholders or swallowed errors from reaching customers as successful responses. The practical outcome is fewer "random timeout" incidents, lower support load, and confidence that bursty read features actually scale. Cost is a low-risk patch upgrade plus a short audit of any custom locking code.

To engineering: Take the upgrade; it closes a request-pipeline bug where reloaded responses bypassed their own middleware, and it hardens every failure path (cache-store failure, TTL callback and tagging failures, any Throwable before a response exists) so locks release instead of stalling the next N callers. Two action items: (1) grep for awaitUnlock() overrides, mocks, and interface declarations—the return type moved from void to float and a lingering : void override will fatal; (2) wire <customAction>:lock_wait into your alerting and pick a deliberate logs/lock_wait_threshold rather than inheriting the 5s default. Autowired MonologLogHandler and the new public static reloadLockedResponse() are additive—the latter is what soap-core-async-bundle v2.0.1 expects, so upgrade the two together.