fix(komga): add missing library DTO fields (scanDirectoryExclusions, …

[RawatDevanshu]

Description

Fixes the library endpoint response to include the two fields required by Komelia's KomgaLibrary data class: scanDirectoryExclusions (empty list) and oneshotsDirectory (nullable). Previously these fields were missing from KomgaLibraryDto, causing a JsonConvertException in Komelia when deserializing the library list.

Linked Issue

Refs #164 — implements the library DTO schema fix (missing scanDirectoryExclusions and oneshotsDirectory fields).

Changes

• Added scanDirectoryExclusions (default empty list) and oneshotsDirectory (nullable, defaults to null) to KomgaLibraryDto.
• Annotated oneshotsDirectory with @JsonInclude(ALWAYS) to ensure the null value is serialized (class uses NON_NULL).
• No database or mapper changes — the entity doesn't persist these fields yet; defaults match the Komga client's own defaults.

Manual Testing Steps

Tested against a live instance on localhost:6060:

1. curl -u <OPDSUsername>:<OPDSPassword> "http://localhost:6060/komga/api/v1/libraries" — response includes:

      "scanDirectoryExclusions": [],
      "oneshotsDirectory": null

2. Komelia no longer throws JsonConvertException on library load.
3. Basic auth still works (no regression).
4. Full backend suite passes via just api check.

Screenshots (Optional)

Additional Context (Optional)

• This is a separate fix from the remember-me auth PR (feat(komga): support remember-me authentication cookies #2333). Both address different checklist items on Support Komelia app in the Komga API  #164.

AI Disclosure

Claude — helped identify the missing fields from the Komga client Kotlin model and design the DTO fix. I reviewed and verified the code, tests, and manual curl evidence myself.

Checklist

• This PR links and implements an accepted issue.
• This PR is a single focused change.
• There are new or updated tests validating this change.
• I ran just api check.
• I have added screenshots if there were any UI changes.
• I have disclosed any AI usage as per the organization AI Policy above.
• I understand all of my submitted changes.

Summary by CodeRabbit

• New Features
  • Added support for configuring directories excluded from library scans.
  • Added an optional directory setting for one-shot content.
  • These settings are now included in library configuration data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9b1dceb8-7c99-43cb-b9fd-0879de7fa265

📥 Commits

Reviewing files that changed from the base of the PR and between 2a8d8ea and 90de51c.

📒 Files selected for processing (1)

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• grimmory-tools/grimmory-docs (manual)

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

**/*

⚙️ CodeRabbit configuration file

**/*: This project is being developed using current and future-facing technologies:

• Java 25 with --enable-preview (preview features are INTENTIONAL and encouraged)
• Spring Boot 4 (latest major version, check APIs accordingly)
• Jackson 3 (new package: tools.jackson.* instead of com.fasterxml.jackson.*)
• Hibernate 7.3.x (Jakarta Persistence 3.2, new APIs; avoid deprecated Hibernate 5/6 patterns)
• Angular 21 (signals-based reactivity, no NgModules unless legacy)

Grimmory Internal Tools

• epub4j and pdfium4j are our own internal tools developed by the Grimmory team.
• Always verify behavior and API changes against the upstream repositories:
  • epub4j: https://github.com/grimmory-tools/epub4j
  • pdfium4j: https://github.com/grimmory-tools/pdfium4j
• If you encounter issues with these libraries, check if a fix exists in the upstream grimmory-tools organization.

Metadata Standards and Compliance

• For all metadata writing and parsing logic, double-check against Dublin Core and ANSI standards to ensure perfect official compliance.
• We strictly follow the widespread and official XML-compliant methods for EPUB2, EPUB3, CBX, and PDF formats.

General Java and Spring rules

• ALWAYS prefer modern, idiomatic Java 25 constructs over legacy patterns.
• Preview features (--enable-preview) are enabled and intentional; do NOT flag them as risky unless there is a concrete runtime issue.
• Prefer: records, sealed classes/interfaces, pattern matching (switch expressions, instanceof), structured concurrency (StructuredTaskScope), scoped values, string templates, unnamed patterns/variables.
• Prefer virtual threads (Thread.ofVirtual(), Executors.newVirtualThreadPerTaskExecutor()) over platform threads for I/O-bound work.
• Prefer the new Sequenced Collections API (SequencedCollection, SequencedMap) where applicable.
• Prefer var for local variables when the type is obvious from context.
• Use stream().toList() instead of stream().collect(Collectors.toList()) for imm...

Files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

**/dto/**/*.java

⚙️ CodeRabbit configuration file

**/dto/**/*.java: DTO review; prefer records:

• Prefer Java records over classes for DTOs.
• Jackson 3: use @JsonProperty, @JsonAlias, and @JsonIgnoreProperties(ignoreUnknown = true).
• Flag missing validation annotations (@NotNull, @NotBlank, @Size) on input DTOs.
• Flag ObjectMapper instantiation inside a DTO; must never happen.
• New Jackson 3 package is tools.jackson.; flag any com.fasterxml.jackson. in new files.

Files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

🧠 Learnings (10)

📚 Learning: 2026-04-10T08:15:37.436Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 449
File: booklore-api/src/main/java/org/booklore/service/book/BookDownloadService.java:139-145
Timestamp: 2026-04-10T08:15:37.436Z
Learning: When using Spring `ContentDisposition.builder(...).filename(name, StandardCharsets.UTF_8).build()` (i.e., explicitly providing UTF-8), the resulting header value should include both the quoted `filename="=?UTF-8?..."` and the RFC 5987 `filename*=` parameters. In this case, any extra ASCII fallback computation (e.g., deriving an ASCII `fallbackFilename` via `NON_ASCII_PATTERN` and calling `.filename(fallbackFilename)`) is likely redundant—prefer calling only `.filename(fallbackName?, StandardCharsets.UTF_8)` as appropriate and let Spring handle the UTF-8 header parameters. Verify by comparing the emitted header for `filename` and `filename*` before deciding to keep an ASCII fallback.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-04-14T12:43:08.698Z

Learnt from: balazs-szucs
Repo: grimmory-tools/grimmory PR: 502
File: booklore-api/src/main/java/org/booklore/service/reader/ChapterCacheService.java:0-0
Timestamp: 2026-04-14T12:43:08.698Z
Learning: For this codebase (booklore-api), target Java 25 with `--enable-preview`, so `_` is intentionally used as an unnamed/ignored variable (e.g., lambda parameter or pattern variable) per Java’s preview feature JEP 456. Do not flag `_` in those contexts as an invalid/reserved identifier; only flag it if it’s used in a non-supported position (e.g., where an unnamed variable is not applicable for the Java preview rules).

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-07T21:21:55.233Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1194
File: backend/src/main/java/org/booklore/service/ReadingSessionService.java:0-0
Timestamp: 2026-05-07T21:21:55.233Z
Learning: When reviewing Java 23+ code, treat `java.time.Instant#until(Instant endExclusive)` as a valid API/method call (it returns a `Duration`, equivalent to `Duration.between(this, endExclusive)`). Do not flag `instant.until(otherInstant)` as a compile error or API misuse when the project targets Java 25+ (as in grimmory-tools/grimmory); the call should be considered correct and returns a `Duration`.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-08T06:19:20.621Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1201
File: backend/src/main/java/org/booklore/model/dto/AccessTokenDto.java:3-10
Timestamp: 2026-05-08T06:19:20.621Z
Learning: For Jackson 3 codebases, do not treat imports from `com.fasterxml.jackson.annotation.*` (e.g., `JsonInclude`, `JsonProperty`, `JsonView`) as incorrect. In Jackson 3, `jackson-annotations` intentionally remains under `com.fasterxml.jackson.annotation.*` for backward compatibility, while only the core processing packages (e.g., `jackson-core`, `jackson-databind`) move to the `tools.jackson.*` namespace.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-02T18:47:09.753Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1052
File: backend/src/main/java/org/booklore/model/dto/kobo/KoboDeals.java:14-33
Timestamp: 2026-05-02T18:47:09.753Z
Learning: In this codebase, do not raise review findings suggesting conversion of class-based DTOs to Java `record`s (e.g., DTOs under `org.booklore.model.dto.*` such as `org.booklore.model.dto.kobo`). Although records may be a preferred guideline in general, the team is intentionally avoiding new `record` DTOs right now due to low existing adoption—so class-based DTOs should not be flagged solely for not being records.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-04T20:31:11.075Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1086
File: backend/src/main/java/org/booklore/service/metadata/BookReviewUpdateService.java:63-66
Timestamp: 2026-05-04T20:31:11.075Z
Learning: For this repository, reviewers should treat string truncation done via `String.length()` and `String.substring(0, maxLength)` (UTF-16 code units) as an accepted, consistent convention. Do not flag individual occurrences of this pattern as bugs, even though it is not code-point-aware for surrogate pairs. A separate global effort is already tracked to move toward code-point-aware truncation, so per-site fixes should be avoided during code review.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-13T12:34:49.607Z

Learnt from: balazs-szucs
Repo: grimmory-tools/grimmory PR: 1293
File: backend/src/main/java/org/booklore/service/metadata/DuckDuckGoCoverService.java:246-252
Timestamp: 2026-05-13T12:34:49.607Z
Learning: In this repo’s Java code, when catching Jsoup `org.jsoup.HttpStatusException` (and similar exceptions originating from external libraries) and wrapping/rethrowing them, do not require preserving the original exception stack trace (e.g., as flagged by PMD `PreserveStackTrace`) as long as the application already captures the actionable diagnostics in logs or the thrown exception message (such as HTTP status code and the requested URL). Reviewers should still ensure the log/message contains those details; the intent is to avoid noisy stack traces that only reflect external-library internals rather than application code.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-17T13:38:16.462Z

Learnt from: balazs-szucs
Repo: grimmory-tools/grimmory PR: 1366
File: backend/src/main/java/org/booklore/service/FileStreamingService.java:65-66
Timestamp: 2026-05-17T13:38:16.462Z
Learning: In the grimmory-tools/grimmory repo, it’s an accepted pattern to pass the raw AccessDeniedException.getMessage() (even if it may include filesystem path details) into ApiError.PERMISSION_DENIED.createException(...). During code review, do not raise a security/information-disclosure issue solely based on that exception message being propagated to the API when using ApiError.PERMISSION_DENIED.createException with the AccessDeniedException message.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-05-23T23:01:25.769Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1456
File: backend/src/main/java/org/booklore/service/metadata/parser/GoodReadsParser.java:618-630
Timestamp: 2026-05-23T23:01:25.769Z
Learning: In this codebase (grimmory-tools/grimmory), it’s intentional to omit per-request timeouts on individual Java HttpRequest.Builder instances (e.g., GoodReadsParser.fetchJson). During reviews, do not flag missing builder-level timeouts as a best-practice violation; rely on framework-level and/or HttpClient-level timeouts configured elsewhere for consistent behavior. Only raise an issue if you can verify that no effective timeout is configured at the HttpClient/framework level.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

📚 Learning: 2026-06-12T01:10:31.416Z

Learnt from: imnotjames
Repo: grimmory-tools/grimmory PR: 1724
File: backend/src/main/java/org/booklore/repository/BookRepository.java:58-59
Timestamp: 2026-06-12T01:10:31.416Z
Learning: In this codebase (grimmory-tools/grimmory), reviews should not treat inline `LIMIT`/`OFFSET` clauses inside `Query` JPQL/HQL strings as a JPA compliance risk. This is intentional: `hibernate.jpa.compliance.query=true` is intentionally not set, and Hibernate 7.3+ supports `LIMIT`/`OFFSET` as valid HQL extensions. Therefore, do not flag or require changes to `Query` annotations solely due to `LIMIT`/`OFFSET` usage.

Applied to files:

• backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java

🔇 Additional comments (1)

backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java (1)

3-5: LGTM!

Also applies to: 76-81

---

Walkthrough

KomgaLibraryDto now exposes scan directory exclusions and a oneshot directory option. The exclusions default to an empty list. The oneshot directory field is always included in JSON output.

Changes

Komga library DTO

Layer / File(s)	Summary
Directory configuration fields backend/src/main/java/org/booklore/model/dto/komga/KomgaLibraryDto.java	The DTO adds scanDirectoryExclusions with an empty-list default and oneshotsDirectory with unconditional JSON serialization. Required collection imports were added.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 90de5

The library response now includes the two fields required by Komelia, preventing the reported deserialization failure while preserving existing behavior. No actionable merge-blocking risk remains after normal checks and review.

Suggested labels: backend, enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commit format and clearly describes the added Komga library DTO fields.
Description check	✅ Passed	The description includes the required sections, issue reference, changes, testing steps, AI disclosure, and checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}