feat: Koreader plugin by WorldTeacher · Pull Request #2298 · booklore-app/booklore

WorldTeacher · 2026-01-17T01:25:19Z

🚀 Pull Request

📝 Description

This PR adds the koreader plugin to record and synchronize reading sessions to booklore

🛠️ Changes Implemented

added a new API endpoint by-hash to get the bookID based on the calculated hash
updated KoreaderAuth to map the koreader user with the booklore account to sync sessions
added new tests for the by-hash method

🧪 Testing Strategy

I created a docker image and tested the plugin with these conditions:

connected
not connected

and monitored the behavior of the plugin, as well as booklore when sessions were being synced

📸 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) -> here

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)

…umed

…later resolve

WorldTeacher · 2026-01-23T00:19:13Z

converted to draft, as the current implementation messes with the progress sync to/from koreader. A fix will be added soon, latest eta is ~~24.1~~ 28.1

rework settings ui rework calculation of historical sessions to use page count provided by koreader to calculate percentages fix percentage being sent to be xx.x instead of 0.x fix sqlite error by using sqlite by koreader add file logging

add warning and confirmation to historical sync update cache to store paths reduce hash calculations by using cache allow user to set decimals for session percentage set minimum session duration reworked network detection

extract settings from main file add options to sync on suspend, connect to wifi on suspend add option to only manually sync add help texts for various actions rework network handling allow session stored messages to be silent

merge koreader plugin changes

WorldTeacher · 2026-01-27T17:08:00Z

@acx10

I think this is ready for review now and has already been tested by some users and myself

Feedback is appreciated, and changes can be made

…validation

…ccess validation

…derAuthFilter logging

…0 to fix sessions not loading due to max being applied on domain only

…t class

WorldTeacher · 2026-03-08T21:47:53Z

@acx10 ready here as well. Time to get this merged, it has been open for way too long

acx10 · 2026-03-11T17:28:50Z

        return book;
    }

+    public Book getBookByHash(String md5Hash, boolean withDescription) {


This doesn't check for admin access. Every other method in this file does user.getPermissions().isAdmin() before the library-scoped check. An admin who isn't explicitly assigned to the library will get a 404 here.

acx10 · 2026-03-11T17:29:54Z


    @Bean
    @Order(3)
+    public SecurityFilterChain readingSessionsSecurityChain(HttpSecurity http, KoreaderAuthFilter koreaderAuthFilter) throws Exception {


This new chain at @order(3) matches all /api/v1/reading-sessions/** requests, which means existing web UI reading session calls now go through this chain instead of the general JWT chain at @order(10). The KOReader filter silently skips when headers are missing so it probably works, but those endpoints are now pulled out of the general chain entirely. Any future security changes to the general chain won't apply to reading sessions anymore. Could this be scoped more narrowly, like just the /batch endpoint?

acx10 · 2026-03-11T17:31:06Z

+    @NotNull(message = "Book type is required")
+    private BookFileType bookType;
+
+    @NotEmpty(message = "Sessions list cannot be empty")


There's no upper bound on the sessions list size. @notempty just means "at least 1". A client could send a million sessions in one request. Needs a @SiZe(max = ...) here.

acx10 · 2026-03-11T17:32:10Z

+        BookLoreUser user = authenticationService.getAuthenticatedUser();
+        boolean isAdmin = user.getPermissions().isAdmin();
+
+        List<BookEntity> allBooks = isAdmin


This loads every book with metadata into memory for fuzzy matching. For someone with 10k+ books that's going to be rough. ISBN matching could easily be an exact DB query, only falling back to in-memory for title fuzzy search.

acx10 · 2026-03-11T17:32:51Z

+        // Validate all session times
+        for (ReadingSessionItemRequest sessionItem : request.getSessions()) {
+            if (sessionItem.getEndTime().isBefore(sessionItem.getStartTime())) {
+                throw new IllegalArgumentException("End time must be after start time");


Raw IllegalArgumentException here, should be ApiError.GENERIC_BAD_REQUEST.createException(...). Same thing on line 97 with UsernameNotFoundException. These might not get caught by the global error handler properly.

acx10 · 2026-03-11T17:36:02Z

+    }
+
+    @Deprecated
+    public List<org.booklore.model.dto.response.BookSearchResult> fuzzySearchByTitle(String searchTitle) {


This method is brand new and already @deprecated. If nothing calls it, just drop it.

acx10 · 2026-03-11T17:36:28Z

+- Books must exist in your Booklore library (matched by MD5 hash)
+- Network connectivity to your Booklore server
+
+Further documentation can be found over in the [docs](link to docs here)


[docs](link to docs here) is still a placeholder.

acx10 · 2026-03-11T17:37:07Z

+
+        // Only log and process if KOReader headers are present
        if (username != null && key != null) {
+            log.info("KoreaderAuthFilter: Processing KOReader auth for user: {}", username);


This will be noisy. Better remove it.

acx10 · 2026-03-11T17:37:12Z

-                            user.isSyncWithBookloreReader(),
-                            bookLoreUserId,
-                            List.of(new SimpleGrantedAuthority("ROLE_USER"))
+                    log.info("KoreaderAuthFilter: Authentication successful for user: {}", username);


This will be noisy. Better remove it.

Completely out of scope for this probably, but would something like this be better behind a debug setting or env variable?

acx10 · 2026-03-11T17:37:38Z

@@ -0,0 +1,14 @@
+package org.booklore.model.dto.response;


This file does not seem to be used anywhere.

WorldTeacher · 2026-03-11T18:55:23Z

@acx10
addressed all review comments, removed the plugin folder

frontend and backend tests pass, docker image builds

WorldTeacher · 2026-03-11T22:20:18Z

Closed due to differences in opinion of open source and how OSS should be handled

davidbaranek · 2026-03-13T12:00:50Z

That's a shame. I was looking forward to this feature for so long. Any chance this would be reopened in the feature?

WorldTeacher and others added 19 commits January 16, 2026 18:06

initial bookloresync plugin, changes to code for login access

cb0ae83

add offline caching of book id and store sessions until access is res…

43e42c8

…umed

chore: extend plugin with sleep/resume functionality

df1bc20

remove hello.koplugin used as initial guide

a808727

add minimum session time in settings, record sessions without id for …

256eada

…later resolve

new session calculation

23d8a57

add historical data mention

c09a238

replace session guesswork with koreader statistics inspiration

c9dc0f4

move folder, re-add password config

cf8d070

remove comment

258096e

replace extensive readme with minimal readme

f982176

change username and password to correctly reflect type

6313bc9

fix: book get hash of primary book file

8a16f8d

add gesture support

fd4a4f9

update readme, add gesture documentation

6153b95

add tests

e79e37f

Merge branch 'develop' into koreader-plugin

7f54f3f

Merge latest changes from upstream develop

ad8415b

move log after filter

e9cb2f4

WorldTeacher marked this pull request as draft January 23, 2026 00:18

WorldTeacher and others added 7 commits January 23, 2026 17:12

Merge branch 'booklore-app:develop' into koreader-plugin-test

e069cd1

fix progress sync by switching to KoreaderUserDetails instead of DTO

c4bda04

various changes

130ff12

rework settings ui rework calculation of historical sessions to use page count provided by koreader to calculate percentages fix percentage being sent to be xx.x instead of 0.x fix sqlite error by using sqlite by koreader add file logging

Merge branch 'booklore-app:develop' into koreader-plugin-test

10303aa

update koreader plugin

be89959

add warning and confirmation to historical sync update cache to store paths reduce hash calculations by using cache allow user to set decimals for session percentage set minimum session duration reworked network detection

various changes

0728e1b

extract settings from main file add options to sync on suspend, connect to wifi on suspend add option to only manually sync add help texts for various actions rework network handling allow session stored messages to be silent

Merge pull request #1 from WorldTeacher/koreader-plugin-test

86eaf55

merge koreader plugin changes

WorldTeacher marked this pull request as ready for review January 27, 2026 17:06

WorldTeacher and others added 19 commits February 24, 2026 13:32

Merge branch 'develop' into koreader-plugin

cbf61a4

Merge branch 'develop' into koreader-plugin

1c5e18b

Merge branch 'develop' into koreader-plugin

0a84e28

fix(api): change api order to prevent potential small issue

abe7388

fix(reading-sessions): add batch recording for reading sessions with …

74ac614

…validation

fix(auth): update security matcher for reading sessions and enhance a…

dc6e59f

…ccess validation

feat(security): add reading sessions security chain and enhance Korea…

1590c60

…derAuthFilter logging

Merge branch 'develop' into koreader-plugin

82ed5ce

Merge branch 'develop' into koreader-plugin

a282585

Merge branch 'develop' into koreader-plugin

d128776

Merge branch 'develop' into koreader-plugin

d5150ae

Merge branch 'develop' into koreader-plugin

d0f6009

increase maximum size parameter for reading sessions endpoint to 1000…

b0e5be4

…0 to fix sessions not loading due to max being applied on domain only

Merge branch 'develop' into koreader-plugin

23e13a4

Merge branch 'develop' into koreader-plugin

372e37b

add link to plugin when koreader sync enabled

f91b34f

Merge branch 'develop' into koreader-plugin

14f0850

Inject BookLoreUserTransformer into AuthenticationService and its tes…

a5d2324

…t class

Merge branch 'develop' into koreader-plugin

3fafad2

WorldTeacher marked this pull request as ready for review March 8, 2026 21:43

Merge branch 'develop' into koreader-plugin

c902714

acx10 reviewed Mar 11, 2026

View reviewed changes

acx10 added the feature Addition of new functionality label Mar 11, 2026

WorldTeacher and others added 2 commits March 11, 2026 19:16

Merge branch 'develop' into koreader-plugin

d5e7157

chore(review): upload files

997f75f

WorldTeacher closed this Mar 11, 2026

Conversation

WorldTeacher commented Jan 17, 2026

🚀 Pull Request

📝 Description

🛠️ Changes Implemented

🧪 Testing Strategy

📸 Visual Changes (if applicable)

⚠️ Required Pre-Submission Checklist

Please Read - This Checklist is Mandatory

Mandatory Requirements (please check ALL boxes):

Why This Matters:

💬 Additional Context (optional)

Uh oh!

WorldTeacher commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

WorldTeacher commented Jan 27, 2026

Uh oh!

WorldTeacher commented Mar 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WorldTeacher commented Mar 11, 2026

Uh oh!

WorldTeacher commented Mar 11, 2026

Uh oh!

davidbaranek commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

WorldTeacher commented Jan 23, 2026 •

edited

Loading