perf(epub): Replace linear manifest scans with HashMaps in EPUB reader

[balazs-szucs]

🚀 Pull Request

📝 Description

Minor refactor for Epub reading service to improve code quality, and performance.

🛠️ Changes Implemented

1. Pre-computed lookup structures

• Added validPaths Set for O(1) path validation (previously O(n) stream filter)
• Added manifestByHref Map for O(1) manifest item lookup by href
• Eliminates repeated linear searches through manifest on every file access

2. Thread-local DocumentBuilder

• Reuses DocumentBuilder instances per thread instead of creating new factory + builder on every XML parse
• Reduces object allocation and initialization overhead for XML operations

3. Optimized content type detection

• Replaced 20+ string comparisons with static HashMap lookup
• Pre-computed immutable map eliminates repeated string operations
• Faster extension extraction using lastIndexOf + substring

4. I/O buffering

• Added 64KB BufferedInputStream wrapper for zip entry streaming
• Reduces system calls and improves throughput for large files

5. Cache management

• Added touch() method to update last accessed time
• Enables proper LRU eviction for the metadata cache

Performance Impact

• Path validation: O(n) → O(1)
• Manifest lookups: O(n) → O(1)
• Content type detection: ~20 comparisons → 1 map lookup
• XML parsing: Eliminated repeated factory/builder creation
• File streaming: Reduced system calls via buffering

🧪 Testing Strategy

📸 Visual Changes (if applicable)

---

⚠️ Required Pre-Submission Checklist

Please Read - This Checklist is Mandatory

Important Notice: We've experienced several production bugs recently due to incomplete pre-submission checks. To maintain code quality and prevent issues from reaching production, we're enforcing stricter adherence to this checklist.

All checkboxes below must be completed before requesting review. PRs that haven't completed these requirements will be sent back for completion.

Mandatory Requirements (please check ALL boxes):

• Code adheres to project style guidelines and conventions
• Branch synchronized with latest develop branch (please resolve any merge conflicts)
• 🚨 CRITICAL: Automated unit tests added/updated to cover changes (MANDATORY for ALL Spring Boot backend and Angular frontend changes - this is non-negotiable)
• 🚨 CRITICAL: All tests pass locally (run ./gradlew test for Spring Boot backend, and ng test for Angular frontend - NO EXCEPTIONS)
• 🚨 CRITICAL: Manual testing completed in local development environment (verify your changes work AND no existing functionality is broken - test related features thoroughly)
• Flyway migration versioning follows correct sequence (if database schema was modified)
• Documentation PR submitted to booklore-docs (required for features or enhancements that introduce user-facing or visual changes)

Why This Matters:

Recent production incidents have been traced back to:

• Incomplete testing coverage (especially backend)
• Merge conflicts not resolved before merge
• Missing documentation for new features

Backend changes without tests will not be accepted. By completing this checklist thoroughly, you're helping maintain the quality and stability of Booklore for all users.

Note to Reviewers: Please verify the checklist is complete before beginning your review. If items are unchecked, kindly ask the contributor to complete them first.

---

💬 Additional Context (optional)

[Copilot]

Pull request overview

This PR refactors EpubReaderService to reduce per-request overhead when serving EPUB resources by precomputing lookup structures, reusing XML parsers, and improving I/O and content-type detection performance.

Changes:

• Precomputes validPaths (Set) and manifestByHref (Map) inside cached EPUB metadata to avoid repeated linear manifest scans.
• Replaces repeated DocumentBuilderFactory/DocumentBuilder instantiation with a thread-local DocumentBuilder.
• Optimizes streaming and MIME detection via BufferedInputStream and a static extension→content-type map.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.