Skip to content

fix: an ebook request delete removes only the ebook file that request placed - #532

Merged
kikootwo merged 4 commits into
mainfrom
fix/497-ebook-delete-placed-only
Nov 2, 2026
Merged

kikootwo merged 4 commits into
mainfrom
fix/497-ebook-delete-placed-only

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 2, 2026

Copy link
Copy Markdown
Owner

Closes #497

What changed

  • Ebook import (processEbookOrganization, src/lib/processors/organize-files.processor.ts): after a successful organize, one call to the new recordEbookPlacement() (src/lib/utils/ebook-placement.ts) records the ebook file the import placed in Request.placedEbookFiles as { path, size, sha256, placedAt }. It records only when placeFile returned copied, which is the only status where RMAB created the file. identical, present and differs mean the library already had the file, so nothing is added and the field becomes []. The hash is read from the placed bytes (after the Kindle fix). Later imports of the same request append; the same path is replaced by the newest entry. When there is no record yet but the request had already delivered (an import from before this version, or a record write that failed, then a re-import such as Manual Import), the record starts with an { "earlierImport": "unrecorded" } marker. A hash or database error is a warning and never fails the import; the file is then simply never removed by a delete.
  • Ebook request delete (removeEbookFiles, src/lib/services/request-delete-files.ts): removes only the recorded files. For each entry, the file stays when:
    • the entry is malformed (it needs an absolute path, no NUL, an ebook extension, a safe-integer size and a 64-hex sha256): the placement record could not be read
    • its folder fails library delete guard rules a-c (assertSafeLibraryDelete on the file's own folder, without the audio evidence rule): the existing reasons, e.g. it is also the folder of "<title>"
    • it is no longer a regular file: <name> is no longer the file RMAB placed
    • its size or sha256 changed: <name> changed since RMAB placed it
    • another active ebook request, of any book, recorded the same file: same sha256 and size, and its recorded path reaches the same file (dev/ino), so a symlinked or differently spelled folder counts and a stale entry with other bytes does not: <name> is also the ebook of another request
  • No record removes nothing. NULL on a request that was delivered gives RMAB has no record of the ebook files this request placed (it was imported before RMAB kept one, or the record could not be saved), so no ebook file was removed; a never-delivered request (e.g. failed) gets no reason. [] gives RMAB has no record that this request placed the ebook (its import found it already in the library), so it was not removed. The marker adds an earlier import of this request has no record (...), so its ebook file was not removed, and the recorded files after it are still removed. Each reason shows once. SQL NULL and JSON null read the same; JSON null is never written.
  • The record holds absolute library paths, so no API response carries it: GET and POST /api/requests, GET and PATCH /api/requests/[id] (admins included), manual search, select-torrent, request-with-torrent, admin approve, pending approval and the reported-issue replace all leave it out (hidePlacementRecord(), also inside hideStoredPick(), in src/lib/services/request-detail-query.ts). The owner detail view already used a field list without it.
  • The delete no longer reads Audiobook.filePath for ebooks, so a custom ebook_path_template folder is handled through the recorded path. planEbookDelete (src/lib/utils/library-delete-guard.ts), which guessed from the folder's contents, is removed.
  • Schema: one nullable column, requests.placed_ebook_files (Json?). Nothing renamed, dropped or narrowed.
  • Docs: documentation/admin-features/request-deletion.md (D2, schema note, Fixed Issues Optimize documentation for AI token efficiency #8 with its limits), documentation/integrations/ebook-sidecar.md (Delete Behavior), documentation/phase3/file-organization.md (ebook placement record), documentation/backend/database.md (Requests), documentation/backend/services/api-tokens.md (responses), documentation/testing/e2e-harness.md (the two new specs and the changed R5).

Why

Deleting any ebook request unlinked the only ebook in the book folder, or every ebook there when the folder passed the audio evidence rule, whatever the request's status. A failed ebook request that never downloaded anything removed the user's own epub sitting beside an imported audiobook. Nothing recorded which file an ebook import placed: the organizer knew it in memory only, and the processor stored only the folder. So the delete could only guess, and a user's own file looks the same as RMAB's. The record makes the delete act on what the request actually put there.

Evidence

  • tests/services/request-delete.ebook-placement.test.ts and tests/services/request-delete.ebook-placement-guard.test.ts run the real deleteRequest() on temp library folders (Prisma mocked): the issue's steps, every status with no record, NULL, [] and the earlier-import marker, a second ebook request in another format, a file another request recorded (same path, or through a symlinked folder either way round) and a stale entry of another request that does not keep it, a recycled request, a custom ebook template, a changed, resized, linked or missing file, every malformed entry shape, rules a-c (outside the library, the media root, a configured root, a folder holding another book's folder, a shared flat folder), a reason shared by two files shown once, symlinked title folders, and an unlink failure.
  • tests/processors/organize-ebook-placement.test.ts runs the real processOrganizeFiles() with the real FileOrganizer.organizeEbook() and placeFile() into a temp library: copied writes one entry with the file's size and sha256; present, identical (compared, and in place) and differs (same size, and other size) write [] and leave the library file untouched; earlier entries are kept; a failed record write still ends downloaded.
  • tests/utils/ebook-placement.test.ts: record reading and validation (the marker included), entry building, merging, the write (marker only on a NULL record with an earlier delivery) and its never-throws paths, and the other-requests lookup.
  • tests/api/requests-placement-record.routes.test.ts: GET /api/requests for a user and an admin, POST /api/requests, GET /api/requests/[id] as admin, PATCH /api/requests/[id], pending approval, and the two helpers: no placedEbookFiles in any response.
  • With main's src (efcccc9) and the first set of test files: 46 failed and 8 passed, all 46 on an assertion. The response, shared-file and reason tests fail on the branch's first commit (1423531): 19 of the 20 new tests (17 on an assertion, 2 on the helper that did not exist); the 20th checks that an existing record is never marked.

Checks

  • Unit tests for the changed code (vitest related on the changed src files plus the changed and new test files): PASS, 112 files, 1397 tests
  • Type check and lint: PASS (tsc --noEmit clean; ESLint reports nothing new in the touched files compared with main, and the new files are clean)
  • E2E (disposable harness, image built from this branch): PASS. smoke 1/1, 497-ebook-delete 3/3 (a, b, c), library-delete-guard 15/15 (R5 removes only the recorded ebook), 278-ebook-manual-import 1/1, 242-delete-guard 12/12 (5B and 5C included), and the upgrade from 1.2.12 with 497-ebook-legacy (seed 1/1, verify 1/1; requests 6 -> 6, audiobooks 3 -> 3)
  • Full unit suite: PR Tests (CI)

Risk and rollback

  • Ebook requests imported before this version have no record, so deleting them removes no ebook file. The admin sees why in the "files kept" message and can remove the file by hand. A request that never delivered placed nothing, so its delete now removes nothing (before, it could remove the user's file).
  • In a shared flat folder (Ebooks, a shelf) stored by one book, a delete removes only the recorded file; other ebooks there stay. Before, it refused when the folder held several ebooks. Once two books store that folder, rule c keeps every recorded file there.
  • The upgrade adds one nullable column (prisma db push); existing rows read NULL. Each ebook import reads the placed file once more to hash it.
  • Limits, none of which removes more than before this change. One removes a file another request still shows as downloaded, as before: a second active ebook request on the same book whose import found the file already there does not hold it, so deleting the request that placed it removes it. The rest keep the file: a crash between the copy and the record write, or a failed record write, leaves that file unrecorded; a delete while the import is still running leaves the file that import places afterwards; two organizes of one request at once can lose one entry; recorded paths under an old media_dir are kept after the library moves; the ebook's own folder (custom template) is left empty after its only file goes.
  • Rollback: revert this PR. The extra column is harmless to older code. A downgrade's prisma db push --accept-data-loss drops the column, so a later upgrade treats those requests as imported before the record (files kept).

Release note

  • Deleting an ebook request now removes only the ebook file that request put in the library, so your own ebook in the same folder is never touched (Deleting an ebook request removes ebook files RMAB didn't download #497). Ebook requests imported before this version keep their files when deleted; the delete message says so, and you can remove the file by hand.

🤖 Generated with Claude Code

kikootwo and others added 4 commits October 27, 2026 08:54
… placed

The ebook organize now records the file it copied into the library
(Request.placedEbookFiles: path, size, sha256), and only for a 'copied'
placement. A request delete removes only recorded files that are unchanged,
not recorded by another active request, and in a folder the library delete
guard allows. A request with no record removes nothing; a delivered one says
why. Adds one nullable column.

Closes #497.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…placed-only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ile check and kept reasons

- No response that returns a request row carries placedEbookFiles (absolute
  library paths): GET/POST /api/requests, GET/PATCH /api/requests/[id],
  manual-search, select-torrent, request-with-torrent, admin approve,
  pending-approval and the reported-issue replace.
- "Another request recorded this file" now means the same file: same sha256
  and size, and the other entry's path reaches the same file (dev/ino), so a
  symlinked or differently spelled folder counts and a stale entry does not.
- A request that delivered before its first recorded import gets an
  earlier-import marker; its delete still removes the recorded files and says
  the earlier file was kept. Kept reasons no longer claim a pre-upgrade import
  when the record write failed, and each reason shows once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo marked this pull request as ready for review November 2, 2026 17:21
@kikootwo
kikootwo merged commit ba72744 into main Nov 2, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/497-ebook-delete-placed-only branch November 2, 2026 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Deleting an ebook request removes ebook files RMAB didn't download

1 participant