Track reason for which a geolocation db download was attempted

module/Core/config/entities-mappings/Shlinkio.Shlink.Core.Geolocation.Entity.GeolocationDbUpdate.php

@@ -46,6 +46,11 @@
         ->nullable()
         ->build();
 
+    fieldWithUtf8Charset($builder->createField('reason', Types::STRING), $emConfig)
+        ->columnName('reason')
+        ->length(1024)
+        ->build();
+
     fieldWithUtf8Charset($builder->createField('filesystemId', Types::STRING), $emConfig)
         ->columnName('filesystem_id')
         ->length(512)

module/Core/migrations/Version20241212131058.php

@@ -38,6 +38,7 @@ public function up(Schema $schema): void
         ]);
         $table->addColumn('filesystem_id', Types::STRING, ['length' => 512]);
 
+        $table->addColumn('reason', Types::STRING, ['length' => 1024]);
         $table->addColumn('error', Types::STRING, [
             'length' => 1024,
             'default' => null,

module/Core/src/Geolocation/Entity/GeolocationDbUpdate.php

@@ -13,16 +13,17 @@ class GeolocationDbUpdate extends AbstractEntity
 {
     private function __construct(
         private readonly string $filesystemId,
+        private readonly string $reason,
         private GeolocationDbUpdateStatus $status = GeolocationDbUpdateStatus::IN_PROGRESS,
         private readonly Chronos $dateCreated = new Chronos(),
         private Chronos $dateUpdated = new Chronos(),
         private string|null $error = null,
     ) {
     }
 
-    public static function forFilesystemId(string|null $filesystemId = null): self
+    public static function withReason(string $reason, string|null $filesystemId = null): self
     {
-        return new self($filesystemId ?? self::currentFilesystemId());
+        return new self($reason, $filesystemId ?? self::currentFilesystemId());
     }
 
     public static function currentFilesystemId(): string

module/Core/src/Geolocation/GeolocationDbUpdater.php

@@ -89,12 +89,20 @@ private function downloadIfNeeded(
         }
 
         // Try to download if:
-        // - There are no attempts or the database file does not exist
+        // - There are no attempts tracked
+        // - The database file does not exist
         // - Last update errored (and implicitly, the max amount of consecutive errors has not been reached)
         // - Most recent attempt is older than 30 days (and implicitly, successful)
-        $olderDbExists = $mostRecentDownload !== null && $this->dbUpdater->databaseFileExists();
-        if (! $olderDbExists || $lastAttemptIsError || $mostRecentDownload->isOlderThan(days: 30)) {
-            return $this->downloadAndTrackUpdate($downloadProgressHandler, $olderDbExists);
+        $reasonMatch = match (true) {
+            $mostRecentDownload === null => [false, 'No download attempts tracked for this instance'],
+            $this->dbUpdater->databaseFileExists() => [false, 'Geolocation db file does not exist'],
+            $lastAttemptIsError => [true, 'Max consecutive errors not reached'],
+            $mostRecentDownload->isOlderThan(days: 30) => [true, 'Last successful attempt'],
+            default => null,
+        };
+        if ($reasonMatch !== null) {
+            [$olderDbExists, $reason] = $reasonMatch;
+            return $this->downloadAndTrackUpdate($downloadProgressHandler, $olderDbExists, $reason);
         }
 
         return GeolocationResult::DB_IS_UP_TO_DATE;
@@ -106,8 +114,9 @@ private function downloadIfNeeded(
     private function downloadAndTrackUpdate(
         GeolocationDownloadProgressHandlerInterface|null $downloadProgressHandler,
         bool $olderDbExists,
+        string $reason,
     ): GeolocationResult {
-        $dbUpdate = GeolocationDbUpdate::forFilesystemId();
+        $dbUpdate = GeolocationDbUpdate::withReason($reason);
         $this->em->persist($dbUpdate);
         $this->em->flush();