multiversion part two

Author: Alfagun74

CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### Breaking Changes & Migration
 
+- [#236](https://github.com/Phalcode/gamevault-backend/issues/236) Introduced support for multiple game versions -> **Existing game rows are migrated automatically.**
+
+- Removed legacy top-level game version fields (`version`, `file_path`, `size`, `release_date`, `early_access`, `type`) in favor of the new `game_version` table. -> **If you rely on these fields, update your clients to use the new version structure before migrating.**
+
+- Duplicate handling now merges files with the same title into one game entity more consistently (year-tagged files merge by matching release year, untagged files merge into a no-year bucket first). -> **If you previously relied on same-title duplicates as separate game entries, rename titles explicitly (e.g. with square brackets) to keep them separate.**
+
 ### Changes
 
 - Updated automatic Web UI version selection: if no compatible stable release is found, the backend now falls back to the nearest newer stable release before falling back to `unstable`.
@@ -1021,7 +1027,7 @@ Recommended Gamevault App Version: `v1.5.0.0`
 
 ### Breaking Changes
 
-- When adding the same game multiple times to your GameVault server, [follow this documentation.](https://gamevau.lt/docs/server-docs/adding-games#adding-the-same-game-multiple-times)
+- When adding the same game multiple times to your GameVault server, [follow this documentation.](https://gamevau.lt/docs/server-docs/adding-games#keeping-multiple-versions-of-the-same-game)
 
 ### Changes
 

src/logging.ts

@@ -68,10 +68,14 @@ const stream = {
 };
 
 function logGamevaultGame(game: GamevaultGame) {
+  const resolvedPath =
+    game?.file_path ||
+    game?.versions?.find((version) => !!version.file_path)?.file_path;
+
   return {
     id: game?.id,
     title: game?.title,
-    file_path: game?.file_path,
+    file_path: resolvedPath,
   };
 }
 

src/modules/games/files.service.spec.ts

@@ -181,7 +181,7 @@ describe("FilesService", () => {
   });
 
   describe("deleteGameFile", () => {
-    it("should reject deletion when game has no file path", async () => {
+    it("should reject deletion when game has no available versions", async () => {
       gamesService.findOneByGameIdOrFail.mockResolvedValue({
         id: 1,
         file_path: null,
@@ -217,14 +217,118 @@ describe("FilesService", () => {
       );
     });
 
-    it("should remove game file from disk", async () => {
+    it("should remove all game version files from disk when no version is provided", async () => {
       const game = { id: 1, file_path: "/tmp/test-files/My Game.zip" } as any;
       gamesService.findOneByGameIdOrFail.mockResolvedValue(game);
+      gameVersionRepository.find.mockResolvedValueOnce([
+        {
+          file_path: "/tmp/test-files/My Game (v1.0.0).zip",
+          version: "v1.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-01"),
+        },
+        {
+          file_path: "/tmp/test-files/My Game (v2.0.0).zip",
+          version: "v2.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-02"),
+        },
+      ] as any);
+      fsExtra.pathExists.mockResolvedValue(true);
+
+      await service.deleteGameFile(1);
+
+      expect(fsExtra.rm).toHaveBeenCalledTimes(2);
+      expect(fsExtra.rm).toHaveBeenCalledWith(
+        "/tmp/test-files/My Game (v1.0.0).zip",
+      );
+      expect(fsExtra.rm).toHaveBeenCalledWith(
+        "/tmp/test-files/My Game (v2.0.0).zip",
+      );
+    });
+
+    it("should delete selected normalized version when legacy file path is missing", async () => {
+      gamesService.findOneByGameIdOrFail.mockResolvedValue({
+        id: 1,
+        file_path: undefined,
+      } as any);
+      gameVersionRepository.find.mockResolvedValueOnce([
+        {
+          file_path: "/tmp/test-files/My Game (v2.0.0).zip",
+          version: "v2.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-02"),
+        },
+      ] as any);
       fsExtra.pathExists.mockResolvedValueOnce(true);
 
       await service.deleteGameFile(1);
 
-      expect(fsExtra.rm).toHaveBeenCalledWith(game.file_path);
+      expect(fsExtra.rm).toHaveBeenCalledWith(
+        "/tmp/test-files/My Game (v2.0.0).zip",
+      );
+    });
+
+    it("should delete explicitly requested version", async () => {
+      gamesService.findOneByGameIdOrFail.mockResolvedValue({
+        id: 1,
+        file_path: "/tmp/test-files/My Game (v1.0.0).zip",
+      } as any);
+      gameVersionRepository.find.mockResolvedValueOnce([
+        {
+          file_path: "/tmp/test-files/My Game (v1.0.0).zip",
+          version: "v1.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-01"),
+        },
+        {
+          file_path: "/tmp/test-files/My Game (v2.0.0).zip",
+          version: "v2.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-02"),
+        },
+      ] as any);
+      fsExtra.pathExists.mockResolvedValueOnce(true);
+
+      await service.deleteGameFile(1, "v1.0.0");
+
+      expect(fsExtra.rm).toHaveBeenCalledWith(
+        "/tmp/test-files/My Game (v1.0.0).zip",
+      );
+    });
+
+    it("should reject deletion when requested version does not exist", async () => {
+      fsExtra.rm.mockClear();
+
+      gamesService.findOneByGameIdOrFail.mockResolvedValue({
+        id: 1,
+        file_path: "/tmp/test-files/My Game (v1.0.0).zip",
+      } as any);
+      gameVersionRepository.find.mockResolvedValueOnce([
+        {
+          file_path: "/tmp/test-files/My Game (v1.0.0).zip",
+          version: "v1.0.0",
+          size: 1000n,
+          type: "WINDOWS_SETUP",
+          early_access: false,
+          indexed_at: new Date("2026-01-01"),
+        },
+      ] as any);
+
+      await expect(service.deleteGameFile(1, "v9.9.9")).rejects.toThrow(
+        NotFoundException,
+      );
+      expect(fsExtra.rm).not.toHaveBeenCalled();
     });
   });
 

src/modules/games/files.service.ts

@@ -140,20 +140,65 @@ export class FilesService implements OnApplicationBootstrap {
    * The file indexer will automatically soft-delete the game from the database
    * once it detects the file is missing.
    */
-  public async deleteGameFile(gameId: number): Promise<void> {
+  public async deleteGameFile(
+    gameId: number,
+    requestedVersion?: string,
+  ): Promise<void> {
     const game = await this.gamesService.findOneByGameIdOrFail(gameId, {
       loadDeletedEntities: false,
     });
 
-    if (!game.file_path) {
+    const availableVersions = sortGameVersions(
+      await this.listAvailableVersionsFromStorage(game),
+    );
+
+    if (availableVersions.length === 0) {
       throw new NotFoundException(
-        `Game with id ${gameId} has no file path associated.`,
+        `Game with id ${gameId} has no downloadable versions associated.`,
+      );
+    }
+
+    let versionsToDelete: GameVersion[];
+    if (requestedVersion) {
+      const explicitVersion = availableVersions.find(
+        (version) => version.version === requestedVersion,
       );
+
+      if (!explicitVersion) {
+        throw new NotFoundException(
+          `Version "${requestedVersion}" not found. Available versions: ${availableVersions
+            .map((v) => v.version || "(unversioned)")
+            .join(", ")}`,
+        );
+      }
+
+      versionsToDelete = [explicitVersion];
+    } else {
+      versionsToDelete = availableVersions;
     }
 
-    if (!(await pathExists(game.file_path))) {
+    if (versionsToDelete.some((version) => !version.file_path)) {
       throw new NotFoundException(
-        `Game file not found on disk at "${game.file_path}".`,
+        `Game with id ${gameId} has no valid version file path associated.`,
+      );
+    }
+
+    const existingVersionPaths: string[] = [];
+    for (const version of versionsToDelete) {
+      if (await pathExists(version.file_path)) {
+        existingVersionPaths.push(version.file_path);
+      }
+    }
+
+    if (existingVersionPaths.length === 0) {
+      if (requestedVersion) {
+        throw new NotFoundException(
+          `Game file not found on disk for requested version "${requestedVersion}".`,
+        );
+      }
+
+      throw new NotFoundException(
+        `No downloadable game files were found on disk for game id ${gameId}.`,
       );
     }
 
@@ -166,11 +211,16 @@ export class FilesService implements OnApplicationBootstrap {
       );
     }
 
-    await rm(game.file_path);
+    for (const filePath of existingVersionPaths) {
+      await rm(filePath);
+    }
+
     this.logger.log({
       message: "Game file deleted from disk.",
       gameId,
-      path: game.file_path,
+      version: requestedVersion || "all",
+      count: existingVersionPaths.length,
+      paths: existingVersionPaths,
     });
   }
 
@@ -344,10 +394,7 @@ export class FilesService implements OnApplicationBootstrap {
     const availableVersions =
       await this.listAvailableVersionsFromStorage(gameToUpdate);
 
-    const selectedVersion = selectDefaultGameVersion(
-      availableVersions,
-      gameToUpdate.file_path,
-    );
+    const selectedVersion = selectDefaultGameVersion(availableVersions);
 
     this.applyVersionToGame(gameToUpdate, selectedVersion);
     gameToUpdate.title = indexedGame.title;
@@ -860,10 +907,7 @@ export class FilesService implements OnApplicationBootstrap {
             },
           );
 
-          const selectedVersion = selectDefaultGameVersion(
-            existingVersions,
-            gameToUpdate.file_path,
-          );
+          const selectedVersion = selectDefaultGameVersion(existingVersions);
           this.applyVersionToGame(gameToUpdate, selectedVersion);
           await this.gamesService.save(gameToUpdate);
         }
@@ -1008,7 +1052,38 @@ export class FilesService implements OnApplicationBootstrap {
       return selectedVersion;
     }
 
-    return selectDefaultGameVersion(availableVersions, game.file_path);
+    const selectedVersion = selectDefaultGameVersion(availableVersions);
+
+    if (configuration.TESTING.MOCK_FILES) {
+      return selectedVersion;
+    }
+
+    if (await pathExists(selectedVersion.file_path)) {
+      return selectedVersion;
+    }
+
+    const existingFallbackVersion =
+      await this.findFirstExistingVersion(availableVersions);
+
+    if (existingFallbackVersion) {
+      return existingFallbackVersion;
+    }
+
+    throw new NotFoundException(
+      `The game has no downloadable version files available on disk.`,
+    );
+  }
+
+  private async findFirstExistingVersion(
+    versions: GameVersion[],
+  ): Promise<GameVersion | undefined> {
+    for (const version of versions) {
+      if (version.file_path && (await pathExists(version.file_path))) {
+        return version;
+      }
+    }
+
+    return undefined;
   }
 
   /** Schedules the deletion of a temporary file after a fixed timeout. */

src/modules/games/games.controller.spec.ts

@@ -94,8 +94,14 @@ describe("GamesController", () => {
   describe("deleteGame", () => {
     it("should delete a game file from disk", async () => {
       filesService.deleteGameFile.mockResolvedValue(undefined);
-      await controller.deleteGame({ game_id: 42 });
-      expect(filesService.deleteGameFile).toHaveBeenCalledWith(42);
+      await controller.deleteGame({ game_id: 42 }, undefined);
+      expect(filesService.deleteGameFile).toHaveBeenCalledWith(42, undefined);
+    });
+
+    it("should delete a specific game version when provided", async () => {
+      filesService.deleteGameFile.mockResolvedValue(undefined);
+      await controller.deleteGame({ game_id: 42 }, "v2.0.0");
+      expect(filesService.deleteGameFile).toHaveBeenCalledWith(42, "v2.0.0");
     });
   });
 

src/modules/games/games.controller.ts

@@ -100,10 +100,19 @@ export class GamesController {
       "Permanently deletes the physical game file from the filesystem. The file indexer will automatically detect the missing file and soft-delete the game from the database. Only administrators can use this endpoint. The server must have write permissions on the files volume.",
     operationId: "deleteGame",
   })
+  @ApiQuery({
+    name: "version",
+    required: false,
+    description:
+      "Optional game version string (e.g. v1.0.0). If omitted, all versions of the game are deleted.",
+  })
   @MinimumRole(Role.ADMIN)
   @DisableApiIf(configuration.SERVER.DEMO_MODE_ENABLED)
-  async deleteGame(@Param() params: GameIdDto): Promise<void> {
-    return this.filesService.deleteGameFile(Number(params.game_id));
+  async deleteGame(
+    @Param() params: GameIdDto,
+    @Query("version") version?: string,
+  ): Promise<void> {
+    return this.filesService.deleteGameFile(Number(params.game_id), version);
   }
 
   /** Upload a game file to the server. */

src/modules/games/games.service.spec.ts

@@ -5,6 +5,7 @@ import {
 import { Repository } from "typeorm";
 import { GameMetadataService } from "../metadata/games/game.metadata.service";
 import { MetadataService } from "../metadata/metadata.service";
+import { GameVersionEntity } from "./game-version.entity";
 import { GamesService } from "./games.service";
 import { GamevaultGame } from "./gamevault-game.entity";
 import { GameExistence } from "./models/game-existence.enum";
@@ -13,6 +14,7 @@ import { GameType } from "./models/game-type.enum";
 describe("GamesService", () => {
   let service: GamesService;
   let gamesRepository: jest.Mocked<Repository<GamevaultGame>>;
+  let gameVersionRepository: jest.Mocked<Repository<GameVersionEntity>>;
   let metadataService: jest.Mocked<MetadataService>;
   let gameMetadataService: jest.Mocked<GameMetadataService>;
 
@@ -55,8 +57,13 @@ describe("GamesService", () => {
       save: jest.fn(),
     } as any;
 
+    gameVersionRepository = {
+      findOne: jest.fn(),
+    } as any;
+
     service = new GamesService(
       gamesRepository,
+      gameVersionRepository,
       metadataService,
       gameMetadataService,
     );