TenantAtlas/app/Services/Operations/TargetScopeConcurrencyLimiter.php

<?php

namespace App\Services\Operations;

use Illuminate\Contracts\Cache\Lock;
use Illuminate\Support\Facades\Cache;
use InvalidArgumentException;

final class TargetScopeConcurrencyLimiter
{
    public function __construct(private readonly int $lockTtlSeconds = 900) {}

    /**
     * Acquire a concurrency slot for a given tenant + target scope.
     *
     * Returns a held lock when a slot is available, otherwise null.
     *
     * @param  array{entra_tenant_id?: mixed, directory_context_id?: mixed}  $targetScope
     */
    public function acquireSlot(int $tenantId, array $targetScope): ?Lock
    {
        $max = (int) config('tenantpilot.bulk_operations.concurrency.per_target_scope_max', 1);
        $max = max(0, $max);

        if ($max === 0) {
            return null;
        }

        $scopeKey = $this->scopeKey($targetScope);

        return $this->acquireSlotInternal("bulk_ops:tenant:{$tenantId}:scope:{$scopeKey}:slot:", $max);
    }

    private function acquireSlotInternal(string $prefix, int $max): ?Lock
    {
        $ttlSeconds = (int) config('tenantpilot.bulk_operations.concurrency.lock_ttl_seconds', $this->lockTtlSeconds);
        $ttlSeconds = max(1, $ttlSeconds);

        for ($slot = 0; $slot < $max; $slot++) {
            $lock = Cache::lock($prefix.$slot, $ttlSeconds);

            if ($lock->get()) {
                return $lock;
            }
        }

        return null;
    }

    /**
     * @param  array{entra_tenant_id?: mixed, directory_context_id?: mixed}  $targetScope
     */
    private function scopeKey(array $targetScope): string
    {
        $entraTenantId = $targetScope['entra_tenant_id'] ?? null;
        $directoryContextId = $targetScope['directory_context_id'] ?? null;

        if (is_string($entraTenantId) && trim($entraTenantId) !== '') {
            return 'entra:'.trim($entraTenantId);
        }

        if (is_string($directoryContextId) && trim($directoryContextId) !== '') {
            return 'directory_context:'.trim($directoryContextId);
        }

        if (is_int($directoryContextId)) {
            return 'directory_context:'.$directoryContextId;
        }

        throw new InvalidArgumentException('Target scope must include entra_tenant_id or directory_context_id.');
    }
}