Configurable hook script for recording synchronization (#1604)

* feat: Execute recording import hook script if configured

* Add tests

* Update changelog

* fix(docs): Correct wording; add formatting

* doc(CHANGELOG): Add note on changed recording import task scheduling

---------

Co-authored-by: Samuel Weirich <[email protected]>

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   Configurable hook script for recording synchronization ([#1484], [#1604])
+
+### Changed
+
+-   The recording import task is now prevented from running until the previous run has finished ([#1484], [#1604])
+
 ## [v4.1.2] - 2024-11-22
 
 ### Added
@@ -255,6 +263,7 @@ You can find the changelog for older versions there [here](https://github.com/TH
 [#1452]: https://github.com/THM-Health/PILOS/pull/1452
 [#1477]: https://github.com/THM-Health/PILOS/pull/1477
 [#1483]: https://github.com/THM-Health/PILOS/pull/1483
+[#1484]: https://github.com/THM-Health/PILOS/issues/1484
 [#1489]: https://github.com/THM-Health/PILOS/pull/1489
 [#1493]: https://github.com/THM-Health/PILOS/issues/1493
 [#1495]: https://github.com/THM-Health/PILOS/pull/1495
@@ -267,6 +276,7 @@ You can find the changelog for older versions there [here](https://github.com/TH
 [#1561]: https://github.com/THM-Health/PILOS/pull/1561
 [#1565]: https://github.com/THM-Health/PILOS/pull/1565
 [#1569]: https://github.com/THM-Health/PILOS/pull/1569
+[#1604]: https://github.com/THM-Health/PILOS/pull/1604
 [#1607]: https://github.com/THM-Health/PILOS/issues/1607
 [#1608]: https://github.com/THM-Health/PILOS/pull/1608
 [unreleased]: https://github.com/THM-Health/PILOS/compare/v4.1.2...develop

app/Console/Commands/ImportRecordingsCommand.php

@@ -3,7 +3,9 @@
 namespace App\Console\Commands;
 
 use App\Jobs\ProcessRecording;
+use Config;
 use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Process;
 use Illuminate\Support\Facades\Storage;
 use Str;
 
@@ -15,6 +17,17 @@ class ImportRecordingsCommand extends Command
 
     public function handle()
     {
+        $hook_script_path = Config::get('recording.import_before_hook');
+        if ($hook_script_path) {
+            $this->info('Invoking recording import before hook '.$hook_script_path);
+            $result = Process::run($hook_script_path);
+            if ($result->failed()) {
+                $this->error(trim($result->errorOutput()));
+
+                return 1;
+            }
+        }
+
         $files = Storage::disk('recordings-spool')->files();
         foreach ($files as $file) {
             if (! Str::endsWith($file, '.tar')) {

app/Console/Kernel.php

@@ -50,7 +50,7 @@ protected function schedule(Schedule $schedule): void
         $schedule->command(DeleteObsoleteTokensCommand::class)->daily()->onOneServer();
         $schedule->command('telescope:prune')->daily()->onOneServer();
         $schedule->command('horizon:snapshot')->everyFiveMinutes()->onOneServer();
-        $schedule->command(ImportRecordingsCommand::class)->everyMinute()->onOneServer();
+        $schedule->command(ImportRecordingsCommand::class)->everyMinute()->withoutOverlapping()->onOneServer();
     }
 
     /**

config/recording.php

@@ -6,4 +6,5 @@
     'download_allowlist' => env('RECORDING_DOWNLOAD_ALLOWLIST', '.*'),
     'max_retention_period' => (int) env('RECORDING_MAX_RETENTION_PERIOD', -1),
     'description_limit' => (int) env('RECORDING_DESCRIPTION_LIMIT', 1000),
+    'import_before_hook' => env('RECORDING_IMPORT_BEFORE_HOOK', ''),
 ];

docs/docs/administration/08-advanced/02-recording.md

@@ -248,6 +248,16 @@ RECORDING_DESCRIPTION_LIMIT=255
 
 The maximum configurable value is 65,535 characters. As the entire description is displayed in the overview of the recordings, such a high limit is not recommended.
 
+### Recording import hook
+
+If you are unable to push recordings to your PILOS server as described above, you can let PILOS call a hook script before importing recordings.
+
+```shell
+RECORDING_IMPORT_BEFORE_HOOK=/usr/local/bin/pull_recordings.sh
+```
+
+This script should place tar files in the spool directory, just as the proposed BBB `post_publish` script would.
+
 ## Tips and tricks
 
 ### Using a different group id

tests/Backend/Unit/Console/ImportRecordingsCommandTest.php

@@ -17,8 +17,45 @@ public function testImportRecording()
 
         config(['filesystems.disks.recordings-spool.root' => 'tests/Backend/Fixtures/Recordings']);
 
-        $this->artisan('import:recordings');
+        $this->artisan('import:recordings')->assertSuccessful();
 
         Queue::assertCount(3);
     }
+
+    public function testImportRecordingWithHook()
+    {
+        Queue::fake();
+
+        config(['filesystems.disks.recordings-spool.root' => 'tests/Backend/Fixtures/Recordings']);
+
+        // Import hook command to write "OK" to a temp file
+        $tempFile = tempnam(sys_get_temp_dir(), 'recording-import-hook-test');
+        config(['recording.import_before_hook' => 'echo "OK" > '.$tempFile]);
+
+        $this->artisan('import:recordings')->assertSuccessful();
+
+        // Check if hook was executed
+        $this->assertStringContainsString('OK', file_get_contents($tempFile));
+        // Clean up
+        unlink($tempFile);
+
+        // Check if the recordings were queued
+        Queue::assertCount(3);
+    }
+
+    public function testImportRecordingWithFailingHook()
+    {
+        Queue::fake();
+
+        config(['filesystems.disks.recordings-spool.root' => 'tests/Backend/Fixtures/Recordings']);
+
+        // Import hook command to write "OK" to a file that does not exist
+        $file = '/invalidPath/invalidFile';
+        config(['recording.import_before_hook' => 'echo "OK" > '.$file]);
+
+        $this->artisan('import:recordings')->assertFailed();
+
+        // Check if the recordings were not queued
+        Queue::assertCount(0);
+    }
 }