<?php

declare(strict_types=1);

namespace App\Framework\Filesystem;

/**
 * Interface für File-Locking Storage-Operationen
 *
 * Ermöglicht exklusiven Zugriff auf Dateien für kritische Operationen.
 * Verhindert Data Corruption bei Concurrent Access.
 */
interface LockableStorage
{
    /**
     * Führt Operation mit exklusivem File-Lock aus
     */
    public function withExclusiveLock(string $path, callable $operation): mixed;

    /**
     * Führt Operation mit Shared-Lock (Read-Lock) aus
     */
    public function withSharedLock(string $path, callable $operation): mixed;

    /**
     * Prüft ob Datei gesperrt ist
     */
    public function isLocked(string $path): bool;

    /**
     * Schreibt mit File-Lock
     */
    public function putWithLock(string $path, string $content): void;

    /**
     * Update mit File-Lock
     */
    public function updateWithLock(string $path, callable $updateCallback): void;

    /**
     * Append mit File-Lock
     */
    public function appendWithLock(string $path, string $content): void;
}
