fix(sound-files): preserve uploads when ffmpeg conversion fails (#999)

The custom sound file upload pipeline could silently delete the user's
original file when ffmpeg failed mid-conversion, leaving an orphan DB row
that returned HTTP 422 on the Sound Files page. Defense-in-depth across
four layers:

- ConvertAudioFileAction: harden the unlink gate to require all requested
  formats produced non-empty output, compare paths via realpath() with a
  same-directory case-insensitive fallback, and emit a structured audit
  trail through SystemMessages so post-incident forensics can identify
  why the original was kept or removed.
- SoundFilesConf::convertAudioFile: write each target into a sibling
  ".converting" tempfile and rename() onto the destination only after
  exit==0 && is_file && filesize>0. This eliminates the wav->wav in-place
  corruption window and guarantees the source survives a partial failure.
- SoundFiles::afterDelete: add the missing 'opus' format to the cascade
  cleanup list (drift since 7a9d11a) and sweep stray ".converting"
  tempfiles left by interrupted workers.
- PlaybackAction: return HTTP 410 Gone (instead of the default 422) when
  the audio file is missing or empty on disk, so the admin UI can render a
  clear "Audio file missing on disk, please re-upload" badge instead of a
  generic error. Frontend player marks the row, disables play, and reuses
  the same 410 contract for both HEAD metadata probes and GET playback.

Also: regression tests for the unlink gate (with sentinel-stub ffmpeg to
prove PATH override actually intercepts Util::which), the atomic-rename
loop, and the cascade-delete sweep; new sf_AudioFileMissingWarning
translation across all 26 supported locales.

Author: Alexey Portnov

sites/admin-cabinet/assets/js/pbx/SoundFiles/sound-files-index-player.js

@@ -119,6 +119,13 @@ class IndexSoundPlayer {
             headers
         })
         .then(response => {
+            // 410 Gone: backend tells us the audio file is missing on disk while the DB
+            // record still exists. Mark the row as broken so the user gets a clear hint
+            // (and disables the play button) instead of being confused by a generic 422.
+            if (response.status === 410) {
+                this.markAsMissing();
+                return;
+            }
             if (!response.ok) {
                 return;
             }
@@ -139,6 +146,30 @@ class IndexSoundPlayer {
         });
     }
 
+    /**
+     * Mark this player row as having a missing/broken audio file.
+     * Disables the play button, shows a warning icon and a tooltip explaining what to do.
+     */
+    markAsMissing() {
+        const $row = $(`#${this.id}`);
+        if ($row.hasClass('audio-file-missing')) {
+            return;
+        }
+        $row.addClass('audio-file-missing');
+        const tooltipText = (typeof globalTranslate !== 'undefined'
+            && globalTranslate.sf_AudioFileMissingWarning)
+            ? globalTranslate.sf_AudioFileMissingWarning
+            : 'Audio file is missing on disk, please re-upload';
+        this.$pButton
+            .prop('disabled', true)
+            .addClass('disabled')
+            .attr('title', tooltipText)
+            .find('i')
+            .removeClass('play pause')
+            .addClass('exclamation triangle');
+        this.$spanDuration.text('--:--');
+    }
+
     /**
      * Callback for metadata loaded event.
      */
@@ -316,6 +347,14 @@ class IndexSoundPlayer {
         // Fetch audio file with authentication
         fetch(fullUrl, { headers })
             .then(response => {
+                if (response.status === 410) {
+                    this.markAsMissing();
+                    const friendly = (typeof globalTranslate !== 'undefined'
+                        && globalTranslate.sf_AudioFileMissingWarning)
+                        ? globalTranslate.sf_AudioFileMissingWarning
+                        : 'Audio file is missing on disk, please re-upload';
+                    throw new Error(friendly);
+                }
                 if (!response.ok) {
                     throw new Error(`HTTP ${response.status}: ${response.statusText}`);
                 }

sites/admin-cabinet/assets/js/src/SoundFiles/sound-files-index-player.js

@@ -957,4 +957,5 @@
     'cf_EnterSearchPhrase' => 'Axtarış məlumatlarınızı daxil edin',
     'st_tooltip_note' => 'Qeyd',
     'sf_AudioFileLoadError' => 'Audio faylı yüklənərkən xəta baş verdi',
+    'sf_AudioFileMissingWarning' => 'Səs faylı diskdə yoxdur. Yenidən yükləyin.',
 ];

src/Common/Messages/az/Common.php

@@ -957,4 +957,5 @@
     'cdr_DeleteFailed' => 'Nepodařilo se smazat položku',
     'cdr_NoPermissionToDelete' => 'Nemáte oprávnění k mazání příspěvků.',
     'sf_AudioFileLoadError' => 'Chyba při načítání audio souboru',
+    'sf_AudioFileMissingWarning' => 'Zvukový soubor chybí na disku. Nahrajte jej znovu.',
 ];

src/Common/Messages/cs/Common.php

@@ -957,4 +957,5 @@
     'st_tooltip_note' => 'Note',
     'sf_CsvCategory' => 'CSV-filer',
     'sf_AudioFileLoadError' => 'Fejl ved indlæsning af lydfil',
+    'sf_AudioFileMissingWarning' => 'Lydfilen mangler på disken. Upload den venligst igen.',
 ];

src/Common/Messages/da/Common.php

@@ -619,6 +619,7 @@
     // SF
     'sf_AddNewSoundFile' => 'Neue Audio-Datei',
     'sf_AudioFileLoadError' => 'Fehler beim Laden der Audiodatei',
+    'sf_AudioFileMissingWarning' => 'Audiodatei fehlt auf dem Datenträger. Bitte laden Sie sie erneut hoch.',
     'sf_ColumnFile' => 'Dateiname',
     'sf_ColumnPlayer' => 'Abspielen',
     'sf_CustomSounds' => 'Audiodateien',

src/Common/Messages/de/Common.php

@@ -560,6 +560,7 @@
     // SF
     'sf_AddNewSoundFile' => 'Προσθήκη νέου αρχείου ήχου',
     'sf_AudioFileLoadError' => 'Σφάλμα κατά τη φόρτωση αρχείου ήχου',
+    'sf_AudioFileMissingWarning' => 'Το αρχείο ήχου λείπει από τον δίσκο. Παρακαλούμε ανεβάστε το ξανά.',
     'sf_ColumnFile' => 'Ονομα',
     'sf_ColumnPlayer' => 'Παίχτης',
     'sf_CustomSounds' => 'Αρχεία ήχου',

src/Common/Messages/el/Common.php

@@ -668,6 +668,7 @@
     'sf_AddNewAudioFile' => 'Add new audio file',
     'sf_AddNewSoundFile' => 'Add new sound file',
     'sf_AudioFileLoadError' => 'Error loading audio file',
+    'sf_AudioFileMissingWarning' => 'Audio file is missing on disk. Please re-upload it.',
     'sf_ColumnFile' => 'Name',
     'sf_ColumnPlayer' => 'Player',
     'sf_CustomSounds' => 'Audio files',

src/Common/Messages/en/Common.php

@@ -570,6 +570,7 @@
     // SF
     'sf_AddNewSoundFile' => 'Agregar nuevo archivo de sonido',
     'sf_AudioFileLoadError' => 'Error al cargar el archivo de audio',
+    'sf_AudioFileMissingWarning' => 'El archivo de audio falta en el disco. Por favor, vuelva a subirlo.',
     'sf_ColumnFile' => 'Nombre',
     'sf_ColumnPlayer' => 'Jugador',
     'sf_CustomSounds' => 'Archivos de sonido',

src/Common/Messages/es/Common.php

@@ -642,6 +642,7 @@
     'sf_AddNewAudioFile' => 'Lisää uusi äänitiedosto',
     'sf_AddNewSoundFile' => 'Lisää uusi äänitiedosto',
     'sf_AudioFileLoadError' => 'Virhe ladattaessa äänitiedostoa',
+    'sf_AudioFileMissingWarning' => 'Äänitiedosto puuttuu levyltä. Lataa se uudelleen.',
     'sf_ColumnFile' => 'Nimi',
     'sf_ColumnPlayer' => 'Soitin',
     'sf_CustomSounds' => 'Äänitiedostot',