termanager2/app/Http/Controllers/Settings/BackupController.php

<?php

namespace App\Http\Controllers\Settings;

use App\Http\Controllers\Controller;
use App\Jobs\CreateBackupArchive;
use App\Jobs\RestoreBackupArchive;
use App\Services\BackupOperationState;
use Illuminate\Http\Request;
use Illuminate\Support\Str;

/**
 * Trasferimento dei file di backup: consegna dell'archivio prodotto e
 * ricezione di quello da ripristinare.
 *
 * Non e' un componente Livewire come il resto della pagina: lo `streamDownload`
 * di Livewire passa il file base64 dentro la risposta JSON, e un archivio con
 * tutti i PDF dei territori non ci sta. L'avvio delle operazioni e la barra di
 * avanzamento vivono invece in Livewire\Settings\BackupManager, che interroga
 * BackupOperationState. Entrambe le rotte sono nel gruppo `settings.manage`.
 */
class BackupController extends Controller
{
    /**
     * Tetto per il pacchetto in ingresso, in kilobyte.
     *
     * Deriva da `app.max_upload_mb`, da cui l'entrypoint ricava anche i limiti
     * di nginx e di PHP. Il valore qui sta *sotto* quelli di un margine: se a
     * fermare la richiesta e' nginx, il browser riceve un 413 senza corpo — o
     * niente affatto — invece di un messaggio; se la ferma la validazione, chi
     * carica legge cosa e' successo. Il margine copre anche l'intestazione
     * multipart, che gonfia il corpo oltre la dimensione del file.
     *
     * La vista lo legge da qui per rifiutare il file prima ancora di iniziare a
     * caricarlo: una sola fonte per un solo numero.
     */
    public static function maxUploadKb(): int
    {
        $mb = max(1, (int) config('app.max_upload_mb', 2048));

        // 2% di margine, minimo 1 MB, per l'incapsulamento multipart.
        return (int) (($mb - max(1, (int) ($mb * 0.02))) * 1000);
    }

    public static function maxUploadMb(): int
    {
        return (int) (self::maxUploadKb() / 1000);
    }

    public function __construct(
        private readonly BackupOperationState $stato,
    ) {
    }

    /**
     * Consegna l'archivio prodotto da un'operazione di backup e annota che e'
     * stato servito.
     *
     * L'annotazione e' meta' del blocco che protegge l'azzeramento: senza un
     * `servito_at` il pulsante di conferma rifiuta di procedere, quindi non
     * esiste una strada che cancelli i dati senza che l'archivio sia almeno
     * uscito dal server. L'altra meta' e' la conferma umana in
     * BackupManager::confermaAzzeramento().
     *
     * Il completamento del trasferimento *non* e' verificabile da qui: con
     * `fastcgi_buffering on` (il default, e docker/nginx/default.conf non lo
     * disattiva) nginx accetta l'intera risposta dal processo PHP e la inoltra
     * per conto suo. PHP finisce di scrivere e prosegue anche se il browser ha
     * chiuso la connessione al primo byte, quindi far scattare l'azzeramento
     * "dopo l'ultimo byte" azzererebbe anche su un download annullato.
     */
    public function file(string $operationId)
    {
        $operazione = $this->stato->get($operationId);

        abort_if($operazione === null, 404, 'Backup non piu\' disponibile: rigeneralo.');

        $percorso = CreateBackupArchive::percorso($operationId);
        abort_unless(is_file($percorso), 404, 'Archivio di backup non trovato: rigeneralo.');

        $nome = $operazione['result']['nome_download'] ?? 'termanager2-backup.zip';

        $this->stato->update($operationId, function (array $state) {
            $state['result']['servito_at'] = now()->toDateTimeString();

            return $state;
        });

        return response()
            ->download($percorso, $nome, [
                'Content-Type' => 'application/zip',
                'Content-Length' => (string) filesize($percorso),
            ]);
    }

    /**
     * Riceve il pacchetto da ripristinare e mette in coda il lavoro.
     *
     * Risponde JSON perche' il form viene inviato via XMLHttpRequest: e' l'unico
     * modo di avere una barra di caricamento reale sull'upload, che per un
     * archivio di centinaia di MB e' la parte piu' lunga dell'operazione.
     */
    public function upload(Request $request)
    {
        $request->validate([
            'backupZip' => ['required', 'file', 'mimes:zip', 'max:' . self::maxUploadKb()],
        ], [
            'backupZip.required' => 'Seleziona il pacchetto di backup da ripristinare.',
            'backupZip.mimes' => 'Il pacchetto di backup deve essere un file .zip.',
            'backupZip.max' => 'Il pacchetto supera i ' . self::maxUploadMb() . ' MB accettati dal server.',
        ]);

        $operationId = (string) Str::uuid();

        // Stesso blocco del componente Livewire, ripetuto qui perche' questa e'
        // una porta d'ingresso separata: un ripristino avviato mentre gira un
        // azzeramento riscriverebbe le tabelle che l'altro sta cancellando.
        // Il posto si prende subito e in un passo solo (occupa()): controllarlo
        // e prenderlo solo dopo aver salvato il file lasciava una finestra in cui
        // un import o un secondo ripristino passavano entrambi.
        $inCorso = $this->stato->occupa($operationId, BackupOperationState::TIPO_RESTORE, 'In coda');
        if ($inCorso !== null) {
            return response()->json([
                'message' => $this->stato->messaggioOccupato($inCorso),
            ], 409);
        }

        try {
            // Il file dell'upload vive in una cartella temporanea che sparisce a
            // fine richiesta: il job lo troverebbe gia' cancellato.
            $percorso = $request->file('backupZip')->storeAs(
                'backup-restore-in',
                $operationId . '.zip',
                'local'
            );
        } catch (\Throwable $e) {
            // Il posto e' gia' preso: senza chiuderlo resterebbe occupato da un
            // ripristino che non partira' mai, per l'ora intera del TTL.
            $this->stato->markFailed($operationId, 'Archivio non salvato sul server: ' . $e->getMessage());

            throw $e;
        }

        if ($percorso === false) {
            $this->stato->markFailed($operationId, 'Archivio non salvato sul server.');

            return response()->json([
                'message' => 'Il server non è riuscito a salvare il pacchetto ricevuto (spazio o permessi sul disco).',
            ], 500);
        }

        $this->stato->log($operationId, 'Archivio ricevuto. In attesa del worker di coda.');

        RestoreBackupArchive::dispatch(
            $operationId,
            storage_path('app/' . $percorso),
            (int) auth()->id()
        );

        return response()->json(['operation_id' => $operationId]);
    }
}