Quantum\Libraries\Cron\CronLock

Complexity

Total Complexity

41

Size/Duplication

Total Lines	214
Duplicated Lines	0 %

Importance

Changes	1
Bugs	0	Features	0

13 Methods

Rating	Name	Duplication	Size	Complexity
B	cleanupStaleLocks()	0	32	8
A	writeTimestampToHandle()	0	6	1
A	__construct()	0	9	1
A	resolveLockDirectory()	0	4	2
A	readTimestampFromHandle()	0	10	3
A	isLocked()	0	20	4
A	getDefaultLockDirectory()	0	3	1
A	sanitizeTaskName()	0	12	3
A	release()	0	15	3
A	acquire()	0	20	3
A	ensureLockDirectoryExists()	0	10	3
A	createDirectory()	0	14	6
A	refresh()	0	8	3

<?php

namespace Quantum\Libraries\Cron;

use Quantum\Libraries\Cron\Exceptions\CronException;

/**
 * CronLock - file based lock with flock()
 *
 * Changes vs original:
 * - taskName sanitized for safe filename
 * - release() removes lock file
 * - stale cleanup reads timestamp from locked handle (no extra fs()->get)
 * - isLocked() is non-destructive (does NOT delete files); cleanup handles stale deletion
 * - optional refresh() to update timestamp while running
 */
class CronLock
{
    private string $lockDirectory;
    private string $taskName;
    private string $lockFile;

    /** @var resource|null */
    private $lockHandle = null;

    private bool $ownsLock = false;
    private int $maxLockAge;

    private const DEFAULT_MAX_LOCK_AGE = 86400;

    public function __construct(string $taskName, ?string $lockDirectory = null, ?int $maxLockAge = null)
    {
        $this->taskName = $this->sanitizeTaskName($taskName);
        $this->lockDirectory = $this->resolveLockDirectory($lockDirectory);
        $this->lockFile = $this->lockDirectory . DS . $this->taskName . '.lock';
        $this->maxLockAge = $maxLockAge ?? (int) cron_config('max_lock_age', self::DEFAULT_MAX_LOCK_AGE);

        $this->ensureLockDirectoryExists();
        $this->cleanupStaleLocks();
    }

    public function acquire(): bool
    {
        $this->lockHandle = @fopen($this->lockFile, 'c+');

It seems like @fopen($this->lockFile, 'c+') can also be of type false. However, the property $lockHandle is declared as type null|resource. Maybe add an additional type check?

        if ($this->lockHandle === false) {
            $this->lockHandle = null;
            $this->ownsLock = false;
            return false;
        }

        if (!flock($this->lockHandle, LOCK_EX | LOCK_NB)) {
            fclose($this->lockHandle);
            $this->lockHandle = null;
            $this->ownsLock = false;
            return false;
        }

        $this->writeTimestampToHandle($this->lockHandle);
        $this->ownsLock = true;

        return true;
    }

    /**
     * Update lock timestamp (useful for long-running jobs)
     */
    public function refresh(): bool
    {
        if (!$this->ownsLock || $this->lockHandle === null) {
            return false;
        }

        $this->writeTimestampToHandle($this->lockHandle);
        return true;
    }

    public function release(): bool
    {
        if (!$this->ownsLock || $this->lockHandle === null) {
            return true;
        }

        flock($this->lockHandle, LOCK_UN);
        fclose($this->lockHandle);

        $this->lockHandle = null;
        $this->ownsLock = false;

        @fs()->remove($this->lockFile);

It seems like you do not handle an error condition for remove(). This can introduce security issues, and is generally not recommended.

        return true;
    }

    /**
     * Check if another process currently holds the lock.
     */
    public function isLocked(): bool
    {
        if (!fs()->exists($this->lockFile)) {
            return false;
        }

        $handle = @fopen($this->lockFile, 'c+');
        if ($handle === false) {
            return true;
        }

        if (!flock($handle, LOCK_EX | LOCK_NB)) {
            fclose($handle);
            return true;
        }

        flock($handle, LOCK_UN);
        fclose($handle);

        return false;
    }

    private function sanitizeTaskName(string $taskName): string
    {
        $taskName = trim($taskName);
        if ($taskName === '') {
            return 'default';
        }

        // Keep safe filename chars only
        $taskName = preg_replace('/[^a-zA-Z0-9._-]+/', '_', $taskName) ?? 'default';
        $taskName = trim($taskName, '._-');

        return $taskName !== '' ? $taskName : 'default';
    }

    private function resolveLockDirectory(?string $lockDirectory): string
    {
        $path = $lockDirectory ?? cron_config('lock_path');
        return $path === null ? $this->getDefaultLockDirectory() : $path;
    }

    private function getDefaultLockDirectory(): string
    {
        return base_dir() . DS . 'runtime' . DS . 'cron' . DS . 'locks';
    }

    private function ensureLockDirectoryExists(): void
    {
        if ($this->lockDirectory === '') {
            throw CronException::lockDirectoryNotWritable('');
        }

        $this->createDirectory($this->lockDirectory);

        if (!fs()->isWritable($this->lockDirectory)) {
            throw CronException::lockDirectoryNotWritable($this->lockDirectory);
        }
    }

    private function createDirectory(string $directory): void
    {
        if (fs()->isDirectory($directory)) {
            return;
        }

        $parent = dirname($directory);
        if ($parent && $parent !== $directory) {
            $this->createDirectory($parent);
        }

        // @phpstan-ignore-next-line
        if (!fs()->makeDirectory($directory) && !fs()->isDirectory($directory)) {
            throw CronException::lockDirectoryNotWritable($directory);
        }
    }

    /**
     * Removes stale lock files that are NOT currently locked by any process.
     * Safe because we take LOCK_EX before removing.
     */
    private function cleanupStaleLocks(): void
    {
        if (!fs()->isDirectory($this->lockDirectory)) {
            return;
        }

        $files = fs()->glob($this->lockDirectory . DS . '*.lock') ?: [];
        $now = time();

        foreach ($files as $file) {
            $handle = @fopen($file, 'c+');
            if ($handle === false) {
                continue;
            }

            // If someone holds it, skip
            if (!flock($handle, LOCK_EX | LOCK_NB)) {
                fclose($handle);
                continue;
            }

            $timestamp = $this->readTimestampFromHandle($handle);

            if ($timestamp !== null && ($now - $timestamp) > $this->maxLockAge) {
                @flock($handle, LOCK_UN);

It seems like you do not handle an error condition for flock(). This can introduce security issues, and is generally not recommended.

                @fclose($handle);

It seems like you do not handle an error condition for fclose(). This can introduce security issues, and is generally not recommended.

                @fs()->remove($file);

It seems like you do not handle an error condition for remove(). This can introduce security issues, and is generally not recommended.

                continue;
            }

            @flock($handle, LOCK_UN);
            @fclose($handle);
        }
    }

    private function writeTimestampToHandle($handle): void
    {
        @ftruncate($handle, 0);

It seems like you do not handle an error condition for ftruncate(). This can introduce security issues, and is generally not recommended.

        @rewind($handle);

It seems like you do not handle an error condition for rewind(). This can introduce security issues, and is generally not recommended.

        @fwrite($handle, (string) time());

It seems like you do not handle an error condition for fwrite(). This can introduce security issues, and is generally not recommended.

        @fflush($handle);

It seems like you do not handle an error condition for fflush(). This can introduce security issues, and is generally not recommended.

    }

    private function readTimestampFromHandle($handle): ?int
    {
        @rewind($handle);

It seems like you do not handle an error condition for rewind(). This can introduce security issues, and is generally not recommended.

        $content = stream_get_contents($handle);
        if ($content === false) {
            return null;
        }

        $timestamp = (int) trim((string) $content);
        return $timestamp > 0 ? $timestamp : null;
    }
}