Merge pull request #3101 from booklore-app/develop

Merge develop into master for release

Author: acx10

.github/pull_request_template.md

@@ -72,7 +72,7 @@ PASTE OUTPUT HERE
 > **All boxes must be checked before requesting review.** Incomplete PRs will be closed without review. No exceptions.
 
 - [ ] This PR is linked to an approved issue
-- [ ] Code follows project style guidelines and conventions
+- [ ] Code follows project [backend and frontend conventions](../CONTRIBUTING.md#backend-conventions)
 - [ ] Branch is up to date with `develop` (merge conflicts resolved)
 - [ ] I ran the full stack locally (backend + frontend + database) and verified the change works
 - [ ] Automated tests added or updated to cover changes (backend **and** frontend)

CONTRIBUTING.md

@@ -9,20 +9,22 @@ Thanks for your interest in contributing to Booklore! Whether you're fixing bugs
 **Tech Stack:**
 
 - **Frontend:** Angular 20, TypeScript, PrimeNG 19
-- **Backend:** Java 21, Spring Boot 3.5
+- **Backend:** Java 25, Spring Boot 3.5
 - **Authentication:** Local JWT + optional OIDC (e.g., Authentik)
 - **Database:** MariaDB
 - **Deployment:** Docker-compatible, reverse proxy-ready
 
 ## Table of Contents
 
+- [Before You Start](#before-you-start)
 - [Where to Start](#where-to-start)
 - [Getting Started](#getting-started)
 - [Development Setup](#development-setup)
 - [Running Tests](#running-tests)
 - [Making Changes](#making-changes)
 - [Submitting a Pull Request](#submitting-a-pull-request)
-- [Code Style](#code-style)
+- [Backend Conventions](#backend-conventions)
+- [Frontend Conventions](#frontend-conventions)
 - [Reporting Bugs](#reporting-bugs)
 - [Community & Support](#community--support)
 - [Code of Conduct](#code-of-conduct)
@@ -42,7 +44,7 @@ This protects both your time and ours. It ensures that the work is actually want
 - No test output pasted in the PR
 - Bulk AI-generated changes that clearly haven't been reviewed or tested
 - Unsolicited refactors, cleanups, or "improvements" nobody asked for
-- PRs over 1000+ changed lines (split them up)
+- PRs with 1000+ changed lines (split them up)
 
 ## Where to Start
 
@@ -51,8 +53,6 @@ Not sure where to begin? Look for issues labeled:
 - [`good first issue`](https://github.com/booklore-app/booklore/labels/good%20first%20issue) - small, well-scoped tasks ideal for newcomers
 - [`help wanted`](https://github.com/booklore-app/booklore/labels/help%20wanted) - tasks where maintainers would appreciate a hand
 
-You can also check the [project roadmap](https://github.com/booklore-app/booklore/projects) for larger initiatives.
-
 ---
 
 ## Getting Started
@@ -89,7 +89,7 @@ git push origin develop
 ```
 booklore/
 ├── booklore-ui/             # Angular frontend (TypeScript, PrimeNG)
-├── booklore-api/            # Spring Boot backend (Java 21, Gradle)
+├── booklore-api/            # Spring Boot backend (Java 25, Gradle)
 ├── dev.docker-compose.yml   # Development Docker stack
 ├── assets/                  # Shared assets (logos, icons)
 └── local/                   # Local development helpers
@@ -127,8 +127,8 @@ For full control over each component or IDE integration (debugging, hot-reload,
 
 | Tool          | Version | Download                                     |
 |---------------|---------|----------------------------------------------|
-| Java          | 21+     | [Adoptium](https://adoptium.net/)            |
-| Node.js + npm | 18+     | [nodejs.org](https://nodejs.org/)            |
+| Java          | 25+     | [Adoptium](https://adoptium.net/)            |
+| Node.js + npm | 20+     | [nodejs.org](https://nodejs.org/)            |
 | MariaDB       | 10.6+   | [mariadb.org](https://mariadb.org/download/) |
 | Git           | latest  | [git-scm.com](https://git-scm.com/)         |
 
@@ -182,7 +182,7 @@ ng serve
 
 The UI will be available at http://localhost:4200 with hot-reload enabled.
 
-> If you hit dependency issues, try `npm install --legacy-peer-deps`.
+> If you hit dependency issues, try `npm ci --force`.
 
 ---
 
@@ -265,8 +265,8 @@ Before opening your PR:
 - [ ] PR is linked to an **approved** issue (PRs without a linked issue will be closed)
 - [ ] All tests pass (`./gradlew test` and `ng test`)
 - [ ] Actual test output is pasted in the PR description
-- [ ] Code follows project conventions (see [Code Style](#code-style))
-- [ ] IntelliJ linter shows no errors
+- [ ] Code follows project conventions (see [Backend Conventions](#backend-conventions), [Frontend Conventions](#frontend-conventions))
+- [ ] No lint errors
 - [ ] Branch is up-to-date with `develop`
 - [ ] You ran the full stack locally and manually verified the change works
 - [ ] PR description includes a screen recording or screenshots proving it works
@@ -276,6 +276,8 @@ Before opening your PR:
 - [ ] **PR is reasonably sized.** PRs with 1000+ changed lines will be closed without review. Break large changes into small, focused PRs.
 - [ ] **For user-facing features:** submit a companion docs PR at [booklore-docs](https://github.com/booklore-app/booklore-docs)
 
+> When you open your PR on GitHub, a **PR template** will appear. Fill it out completely, including test output and screenshots.
+
 ### AI-Assisted Contributions
 
 Contributions using AI tools (Copilot, Claude, ChatGPT, etc.) are welcome, but the quality bar is the same as human-written code. **If you ship it, you own it.**
@@ -293,14 +295,32 @@ We've seen a sharp increase in AI-generated PRs where the contributor clearly ne
 
 ---
 
-## Code Style
+## Backend Conventions
+
+- Use Spring Data JPA repository methods or JPQL. No native queries unless explicitly approved by a maintainer.
+- Constructor injection via Lombok `@AllArgsConstructor`. No `@Autowired`.
+- Logging via Lombok `@Slf4j`. No manual `LoggerFactory.getLogger(...)`.
+- Throw errors via `ApiError` enum (`ApiError.SOME_ERROR.createException()`). No raw `RuntimeException`.
+- Entities use `*Entity` suffix; DTOs drop it (e.g., `BookEntity` vs `Book`).
+- Use MapStruct for entity-to-DTO mapping. No hand-written mapping code.
+- Security: `@PreAuthorize("@securityUtil.isAdmin()")` or `@CheckBookAccess`. No `@Secured` or `@RolesAllowed`.
+- Testing: JUnit 5 + Mockito + AssertJ. `@ExtendWith(MockitoExtension.class)` for unit tests, `@SpringBootTest` only for integration tests.
+- Use modern Java features (records, sealed classes, pattern matching, text blocks, etc.).
+- No fully qualified class names inline. Always use imports.
+- Flyway migrations go in `booklore-api/src/main/resources/db/migration/` with naming `V<number>__<Description>.sql`.
+- Never modify a released migration. Always create a new migration file for changes.
+- Use idempotent guards in migrations (`CREATE TABLE IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, `DROP ... IF EXISTS` before re-creating).
+
+---
+
+## Frontend Conventions
 
-| Area       | Convention                                                         |
-|------------|--------------------------------------------------------------------|
-| Angular    | Follow the [official style guide](https://angular.dev/style-guide) |
-| Java       | Modern Java 21 features, clean structure                           |
-| Formatting | Use IntelliJ IDEA's built-in linter                               |
-| UI         | SCSS with PrimeNG components                                       |
+- Follow the [Angular style guide](https://angular.dev/style-guide).
+- All components are standalone. No NgModules.
+- Use `inject()` for dependency injection. No constructor injection.
+- PrimeNG for UI components. SCSS for styling. Transloco for i18n.
+- Testing with Vitest (not Karma/Jasmine).
+- All UI features must be responsive (desktop + mobile).
 
 ---
 

Dockerfile

@@ -5,7 +5,7 @@ WORKDIR /angular-app
 
 COPY ./booklore-ui/package.json ./booklore-ui/package-lock.json ./
 RUN --mount=type=cache,target=/root/.npm \
-    npm config set registry http://registry.npmjs.org/ \
+    npm config set registry https://registry.npmjs.org/ \
     && npm ci --force
 
 COPY ./booklore-ui /angular-app/
@@ -54,7 +54,7 @@ LABEL org.opencontainers.image.title="BookLore" \
       org.opencontainers.image.licenses="GPL-3.0" \
       org.opencontainers.image.base.name="docker.io/library/eclipse-temurin:25-jre-alpine"
 
-ENV JAVA_TOOL_OPTIONS="-XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+UseStringDeduplication -XX:+UseContainerSupport -XX:+UseCompactObjectHeaders -XX:MaxRAMPercentage=75.0"
+ENV JAVA_TOOL_OPTIONS="-XX:+UseG1GC -XX:+UseCompactObjectHeaders -XX:+UseStringDeduplication -XX:MaxRAMPercentage=75.0 -XX:+ExitOnOutOfMemoryError"
 
 ARG TARGETARCH
 RUN apk update && apk add --no-cache su-exec libstdc++ libgcc && \

Dockerfile.ci

@@ -16,7 +16,7 @@ LABEL org.opencontainers.image.title="BookLore" \
       org.opencontainers.image.licenses="GPL-3.0" \
       org.opencontainers.image.base.name="docker.io/library/eclipse-temurin:25-jre-alpine"
 
-ENV JAVA_TOOL_OPTIONS="-XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+UseStringDeduplication -XX:+UseContainerSupport -XX:+UseCompactObjectHeaders -XX:MaxRAMPercentage=75.0"
+ENV JAVA_TOOL_OPTIONS="-XX:+UseG1GC -XX:+UseCompactObjectHeaders -XX:+UseStringDeduplication -XX:MaxRAMPercentage=75.0 -XX:+ExitOnOutOfMemoryError"
 
 ARG TARGETARCH
 RUN apk update && apk add --no-cache su-exec libstdc++ libgcc

README.md

@@ -212,7 +212,7 @@ volumes:
 | 💬 **Come hang out** | [Discord Server](https://discord.gg/Ee5hd458Uz) |
 
 > [!WARNING]
-> **Before opening a PR:** Open an issue first and get maintainer approval. PRs without a linked issue, without screenshots/video proof, or without pasted test output will be closed. AI-assisted contributions are welcome, but you must run, test, and understand every line you submit. See the [Contributing Guide](CONTRIBUTING.md) for full details.
+> **Before opening a PR:** Open an issue first and get maintainer approval. PRs without a linked issue, without screenshots/video proof, or without pasted test output will be closed. All code must follow project [backend](CONTRIBUTING.md#backend-conventions) and [frontend](CONTRIBUTING.md#frontend-conventions) conventions. AI-assisted contributions are welcome, but you must run, test, and understand every line you submit. See the [Contributing Guide](CONTRIBUTING.md) for full details.
 
 ---
 

booklore-api/build.gradle

@@ -2,7 +2,7 @@ plugins {
     id 'java'
     id 'org.springframework.boot' version '4.0.3'
     id 'io.spring.dependency-management' version '1.1.7'
-    id 'org.hibernate.orm' version '7.2.4.Final'
+    id 'org.hibernate.orm' version '7.2.5.Final'
     id 'com.github.ben-manes.versions' version '0.53.0'
     id 'jacoco'
 }
@@ -44,7 +44,7 @@ dependencies {
     // --- Database & Migration ---
     implementation 'org.mariadb.jdbc:mariadb-java-client:3.5.7'
     implementation 'org.springframework.boot:spring-boot-starter-flyway'
-    implementation 'org.flywaydb:flyway-mysql:12.0.1'
+    implementation 'org.flywaydb:flyway-mysql:12.0.2'
 
     // --- Security & Authentication ---
     implementation 'io.jsonwebtoken:jjwt-api:0.13.0'
@@ -65,18 +65,18 @@ dependencies {
     implementation 'com.github.jai-imageio:jai-imageio-jpeg2000:1.4.0'
 
     // --- TwelveMonkeys ImageIO ---
-    implementation 'com.twelvemonkeys.imageio:imageio-jpeg:3.13.0'
-    implementation 'com.twelvemonkeys.imageio:imageio-tiff:3.13.0'
-    implementation 'com.twelvemonkeys.imageio:imageio-webp:3.13.0'
-    implementation 'com.twelvemonkeys.imageio:imageio-bmp:3.13.0'
+    implementation 'com.twelvemonkeys.imageio:imageio-jpeg:3.13.1'
+    implementation 'com.twelvemonkeys.imageio:imageio-tiff:3.13.1'
+    implementation 'com.twelvemonkeys.imageio:imageio-webp:3.13.1'
+    implementation 'com.twelvemonkeys.imageio:imageio-bmp:3.13.1'
 
     implementation 'io.documentnode:epub4j-core:4.2.3'
 
     // --- Audio Metadata (Audiobook Support) ---
     implementation 'net.jthink:jaudiotagger:3.0.1'
 
     // --- UNRAR Support ---
-    implementation 'com.github.junrar:junrar:7.5.7'
+    implementation 'com.github.junrar:junrar:7.5.8'
 
     // --- JSON & Web Scraping ---
     implementation 'org.jsoup:jsoup:1.22.1'
@@ -99,7 +99,7 @@ dependencies {
     implementation 'org.freemarker:freemarker:2.3.34'
 
     // --- Jackson 3 ---
-    implementation platform('tools.jackson:jackson-bom:3.0.4')
+    implementation platform('tools.jackson:jackson-bom:3.1.0')
     implementation 'tools.jackson.core:jackson-core'
     implementation 'tools.jackson.core:jackson-databind'
     implementation 'tools.jackson.module:jackson-module-blackbird'

booklore-api/src/main/java/org/booklore/config/security/SecurityConfig.java

@@ -222,6 +222,7 @@ public SecurityFilterChain jwtApiSecurityChain(HttpSecurity http) throws Excepti
                 .headers(headers -> headers
                         .referrerPolicy(referrer -> referrer.policy(
                                 ReferrerPolicyHeaderWriter.ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN))
+                        .contentTypeOptions(contentType -> {})
                 )
                 .authorizeHttpRequests(auth -> auth
                         .dispatcherTypeMatchers(DispatcherType.ASYNC).permitAll()
@@ -242,6 +243,7 @@ public SecurityFilterChain staticResourcesSecurityChain(HttpSecurity http) throw
                         .frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin)
                         .referrerPolicy(referrer -> referrer.policy(
                                 ReferrerPolicyHeaderWriter.ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN))
+                        .contentTypeOptions(contentType -> {})
                 )
                 .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
         return http.build();

booklore-api/src/main/java/org/booklore/controller/AudiobookReaderController.java

@@ -46,6 +46,7 @@ public ResponseEntity<AudiobookInfo> getAudiobookInfo(
     @ApiResponse(responseCode = "200", description = "Full audio file returned")
     @ApiResponse(responseCode = "206", description = "Partial content returned (range request)")
     @ApiResponse(responseCode = "416", description = "Range not satisfiable")
+    @CheckBookAccess(bookIdParam = "bookId")
     @GetMapping("/{bookId}/stream")
     public void streamAudiobook(
             @Parameter(description = "ID of the book") @PathVariable Long bookId,
@@ -62,6 +63,7 @@ public void streamAudiobook(
     @ApiResponse(responseCode = "200", description = "Full track file returned")
     @ApiResponse(responseCode = "206", description = "Partial content returned (range request)")
     @ApiResponse(responseCode = "416", description = "Range not satisfiable")
+    @CheckBookAccess(bookIdParam = "bookId")
     @GetMapping("/{bookId}/track/{trackIndex}/stream")
     public void streamTrack(
             @Parameter(description = "ID of the book") @PathVariable Long bookId,
@@ -79,6 +81,7 @@ public void streamTrack(
                     "Uses token query parameter for authentication.")
     @ApiResponse(responseCode = "200", description = "Cover art returned successfully")
     @ApiResponse(responseCode = "404", description = "No embedded cover art found")
+    @CheckBookAccess(bookIdParam = "bookId")
     @GetMapping("/{bookId}/cover")
     public ResponseEntity<byte[]> getEmbeddedCover(
             @Parameter(description = "ID of the book") @PathVariable Long bookId,

booklore-api/src/main/java/org/booklore/controller/AuthorController.java

@@ -12,6 +12,7 @@
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import jakarta.validation.Valid;
 import lombok.AllArgsConstructor;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
@@ -69,7 +70,7 @@ public ResponseEntity<AuthorDetails> getAuthorDetails(
     @PutMapping("/{authorId}")
     public ResponseEntity<AuthorDetails> updateAuthor(
             @Parameter(description = "ID of the author") @PathVariable long authorId,
-            @RequestBody AuthorUpdateRequest request) {
+            @RequestBody @Valid AuthorUpdateRequest request) {
         return ResponseEntity.ok(authorMetadataService.updateAuthor(authorId, request));
     }
 
@@ -101,7 +102,7 @@ public ResponseEntity<List<AuthorSearchResult>> searchAuthorMetadata(
     @PostMapping("/{authorId}/match")
     public ResponseEntity<AuthorDetails> matchAuthor(
             @Parameter(description = "ID of the author") @PathVariable long authorId,
-            @RequestBody AuthorMatchRequest request) {
+            @RequestBody @Valid AuthorMatchRequest request) {
         return ResponseEntity.ok(authorMetadataService.matchAuthor(authorId, request));
     }
 

booklore-api/src/main/java/org/booklore/controller/BookController.java

@@ -36,17 +36,20 @@
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Size;
 import lombok.AllArgsConstructor;
 import org.springframework.core.io.Resource;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
 import java.util.Set;
 
 @Tag(name = "Books", description = "Endpoints for managing books, their metadata, progress, and recommendations")
 @RequestMapping("/api/v1/books")
+@Validated
 @RestController
 @AllArgsConstructor
 public class BookController {
@@ -190,7 +193,7 @@ public ResponseEntity<BookViewerSettings> getBookViewerSettings(
     @PutMapping("/{bookId}/viewer-setting")
     @CheckBookAccess(bookIdParam = "bookId")
     public ResponseEntity<Void> updateBookViewerSettings(
-            @Parameter(description = "Viewer settings to update") @RequestBody BookViewerSettings bookViewerSettings,
+            @Parameter(description = "Viewer settings to update") @RequestBody @Valid BookViewerSettings bookViewerSettings,
             @Parameter(description = "ID of the book") @PathVariable long bookId) {
         bookService.updateBookViewerSetting(bookId, bookViewerSettings);
         return ResponseEntity.noContent().build();
@@ -237,7 +240,7 @@ public List<BookStatusUpdateResponse> updateReadStatus(@RequestBody @Valid ReadS
     })
     @PostMapping("/reset-progress")
     public ResponseEntity<List<BookStatusUpdateResponse>> resetProgress(
-            @Parameter(description = "List of book IDs to reset progress for") @RequestBody List<Long> bookIds,
+            @Parameter(description = "List of book IDs to reset progress for") @RequestBody @Size(max = 500) List<Long> bookIds,
             @Parameter(description = "Type of progress reset") @RequestParam ResetProgressType type) {
         if (bookIds == null || bookIds.isEmpty()) {
             throw ApiError.GENERIC_BAD_REQUEST.createException("No book IDs provided");
@@ -260,7 +263,7 @@ public ResponseEntity<List<PersonalRatingUpdateResponse>> updatePersonalRating(
     })
     @PostMapping("/reset-personal-rating")
     public ResponseEntity<List<PersonalRatingUpdateResponse>> resetPersonalRating(
-            @Parameter(description = "List of book IDs to reset personal rating for") @RequestBody List<Long> bookIds) {
+            @Parameter(description = "List of book IDs to reset personal rating for") @RequestBody @Size(max = 500) List<Long> bookIds) {
         if (bookIds == null || bookIds.isEmpty()) {
             throw ApiError.GENERIC_BAD_REQUEST.createException("No book IDs provided");
         }