br-optimistic-locking

Better Route optimistic locking

Use optimistic locking on updates or deletes where overwriting a newer state is unsafe. Resolve the current version from storage while the critical section is held.

use BetterRoute\Middleware\Write\CallbackOptimisticLockVersionResolver;
use BetterRoute\Middleware\Write\OptimisticLockMiddleware;
use BetterRoute\Middleware\Write\WpdbOptimisticLockCriticalSection;

$lock = new OptimisticLockMiddleware(
    versionResolver: new CallbackOptimisticLockVersionResolver(
        static function ($context): string|int|null {
            $id = (int) $context->request->get_param('id');
            return my_current_record_version($id);
        }
    ),
    required: true,
    headerName: 'if-match',
    paramName: 'version',
    criticalSection: new WpdbOptimisticLockCriticalSection(timeoutSeconds: 2)
);

$router->patch('/records/(?P<id>\d+)', $handler)
    ->middleware([$auth, $lock])
    ->protectedByMiddleware('bearerAuth');

The middleware prefers If-Match, then falls back to the configured request parameter. It accepts quoted or weak ETag-like values by normalizing W/"value" to value; numeric values become strings. * accepts any available current version.

Response contract

• Missing precondition with required: true returns 428 Precondition Required.
• A supplied version that differs from current storage returns 412 optimistic_lock_failed with expected/current details.
• An unavailable current version returns 409 version_unavailable.
• Lock acquisition failure throws and becomes an internal failure unless the application maps it deliberately.
• On success, context attribute optimisticLock contains expected, current, and atomic: true.

Atomicity boundary

The default WpdbOptimisticLockCriticalSection derives a MySQL named lock from route path plus canonicalized URL parameters. It holds that lock around both the current-version read and the downstream handler. Concurrent Better Route writers using the same route identity cannot both pass the same stale check.