Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions documentation/admin-features/request-deletion.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ model Request {

**Unique Constraint:** Removed from schema, enforced in application code

**Ebook placement record (#497):** `placedEbookFiles Json? @map("placed_ebook_files")` on Request: the ebook files the request's imports copied (D2 below). Nullable, no default (added by `prisma db push`; existing rows NULL)

### Deletion Logic Flow

**Service:** `src/lib/services/request-delete.service.ts`; download handling in `src/lib/services/request-delete-download.ts` (`cleanUpRequestDownload()`, never throws)
Expand Down Expand Up @@ -122,7 +124,20 @@ model Request {
- Stale record: the stored folder is gone AND outside the current `media_dir` (library moved): nothing removed or protected; the delete clears only `filePath`/`filesHash`/`fileFormat` (no backend call, records and status kept; message says so), a replace goes on
- `rm` failure: kept (`the folder was partly removed (permission denied); remove the rest manually`); `fs.rm` stops at the first error, so earlier files are gone; backend and row untouched
- After removal: empty parents swept up to the nearest root (`sweepEmptyParents`)
- **Ebook requests (D2):** rules a-c on `filePath`, then unlink every ebook file directly in it if the folder passes the evidence rule, or the only one if it holds exactly one; otherwise kept (`it holds N ebook files and is not provably this book's folder (...)`). A shared `{author}` or flat `Ebooks` folder fails rule c when another book points at it. Never a sweep of other books' ebooks
- **Ebook requests (D2, #497):** only the files the request's imports recorded in `Request.placedEbookFiles` (`[{ path, size, sha256, placedAt }]`, `src/lib/utils/ebook-placement.ts`); status and the rest of the folder never count. `Audiobook.filePath` is not read. Per entry, in order (kept reasons joined `; `, each reason once):
| Check | Kept reason |
|-------|-------------|
| entry well-formed: absolute path, no NUL, ebook extension (`isEbookFile`), safe-integer size ≥ 0, 64-hex sha256 (non-array value = one bad entry) | `the placement record could not be read` |
| rules a-c on the file's folder (`assertSafeLibraryDelete(dir, book, { evidence: false })`; symlinked folder: target + link location) | rule a-c reasons above |
| `lstat` regular file (not a symlink/folder) | `<name> is no longer the file RMAB placed` |
| size and sha256 match the entry | `<name> changed since RMAB placed it` |
| not the same file as an entry of another active (`deletedAt null`) ebook request, any book: same sha256 + size and its path reaches the same file (`lstat` dev/ino, so a symlinked folder or another spelling of the folder counts; a stale entry with other bytes does not) | `<name> is also the ebook of another request` (that lstat fails other than ENOENT/ENOTDIR: `<name> could not be compared with another request's record (<code>)`) |
| `unlink` | `<name> could not be removed (<why>)` |
- File or its folder already gone (library mounted): nothing, no reason
- No record: SQL NULL or JSON null (imported before the field, a record write that failed, or never imported). Kept reason only when the request ever delivered (`status = 'downloaded'` or `completedAt`): `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`; otherwise none (`Request deleted successfully`)
- `[]` (the import found the file already in the library: `identical`/`present`/`differs`): `RMAB has no record that this request placed the ebook (its import found it already in the library), so it was not removed`
- Earlier-import marker `{ "earlierImport": "unrecorded" }` (first item; `recordEbookPlacement` writes it when the stored value is NULL but `completedAt` is already set, i.e. the request delivered before: a pre-upgrade import or a failed record write, then a re-import such as Manual Import): never removable; adds `an earlier import of this request has no record (it was imported before RMAB kept one, or the record could not be saved), so its ebook file was not removed`; the recorded entries after it are still removed
- Never a folder sweep: a flat `Ebooks`/shelf folder loses only the recorded file (foreign ebooks stay); a folder another book stores still fails rule c
- Not handled (needs a separate ebook location, PR2): an ebook in a separate folder (custom `ebook_path_template`) is not removed by the audiobook delete

4. **Files kept: library left exactly as it is**
Expand Down Expand Up @@ -305,6 +320,20 @@ where: {
- **Issue:** `select-torrent`, `interactive-search`, `manual-search` and `fetch-ebook` (`/api/requests/[id]/`) and admin approve/deny (`/api/admin/requests/[id]/approve`) loaded the request by id only, so a deleted request could still start a download or a search
- **Fix:** each loads with `deletedAt: null` (as `select-ebook`/`interactive-search-ebook` do since #463); a deleted request answers that route's usual "Request not found" 404

**8. Ebook Request Delete Removed the User's Own Ebook (#497)**
- **Issue:** every ebook request delete (any status, e.g. a `failed` one that never downloaded) unlinked the only ebook in `Audiobook.filePath`, or every ebook there when the folder passed the audio evidence rule: the user's own epub beside an imported audiobook went
- **Cause:** nothing recorded which file an ebook import placed; `planEbookDelete` guessed from the folder
- **Fix:** the ebook organize records the file it copied (`Request.placedEbookFiles`, only for placeFile `copied`); the delete removes only recorded, unchanged files behind rules a-c (D2 above). `planEbookDelete` removed
- **Responses:** the record holds absolute library paths and is read only by the delete: every response that returns a request row leaves it out, for admins too (`hidePlacementRecord()`/`hideStoredPick()` in `src/lib/services/request-detail-query.ts`; `GET /api/requests` sets it `undefined` as it does `audiobook.filePath`)
- **Limits** (none removes more than before #497; all but the second keep the file):
- Ebook requests imported before this version have no record: their delete removes no ebook file (reason shown; remove by hand). A crash between the copy and the record write, or a failed record write, leaves that file unrecorded (kept)
- Another active ebook request on the same book whose import found this file already there (`[]`) does not hold it: deleting the request that placed it removes it, and the other request still shows `downloaded` (as before #497)
- A delete while the request's import is still running: the file that import places afterwards is not recorded on a live request, so RMAB never removes it
- Two organizes of one request at once (e.g. a Manual Import while a stalled job re-runs) can lose one entry: that file is kept
- A flat ebook shelf stored by two books (`ebook_path_template = Ebooks`): rule c keeps every recorded file there (`it is also the folder of "<title>"`)
- After `media_dir` moves, recorded paths under the old location fail rule a (`it is outside the media library (...)`) and are kept
- The ebook's own folder (custom `ebook_path_template`) is left empty after its only file goes (no empty-parent sweep)

## File Structure

```
Expand All @@ -314,7 +343,8 @@ Backend:
- src/lib/services/request-delete-download.ts (download in the client: remove / keep seeding / leave alone)
- src/lib/utils/torrent-ownership.ts (whether RMAB added the torrent)
- src/lib/services/request-delete-files.ts (library files, backend items, plex_library records)
- src/lib/utils/library-delete-guard.ts (assertSafeLibraryDelete, planEbookDelete)
- src/lib/utils/library-delete-guard.ts (assertSafeLibraryDelete)
- src/lib/utils/ebook-placement.ts (Request.placedEbookFiles: record write, read, per-file delete checks)
- src/lib/services/replace-library-content.ts (replace with no active request)
- src/app/api/admin/requests/[id]/route.ts (DELETE endpoint)
- src/lib/processors/cleanup-seeded-torrents.processor.ts (orphaned cleanup)
Expand Down
1 change: 1 addition & 0 deletions documentation/backend/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ PostgreSQL database storing users, audiobooks, requests, downloads, configuratio
- `search_attempts`, `download_attempts`, `import_attempts`, `max_import_retries` (default 5)
- `auto_rerequest_count` (Int, default 0) - Automatic re-requests after a failure with no new block (shelf sync / watched lists backoff step); user requests and retries reset it to 0. See [release-blocklist.md](../admin-features/release-blocklist.md#automatic-re-requests-409)
- `last_search_at`, `last_import_at`, `created_at`, `updated_at`, `completed_at`
- `placed_ebook_files` (Json, nullable) - Ebook requests: files this request's imports copied into the library, `[{ path, size, sha256, placedAt }]`; `[]` = imported but the file was already there; NULL = no record (pre-#497, a failed record write, or never imported); a first item `{ earlierImport: 'unrecorded' }` = the request delivered before its first recorded import. The request delete removes only these. Never in an API response. See [request-deletion.md](../admin-features/request-deletion.md)
- Unique: `(user_id, audiobook_id)`
- Indexes: `user_id`, `audiobook_id`, `status`, `created_at DESC`

Expand Down
2 changes: 1 addition & 1 deletion documentation/backend/services/api-tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Source of truth: `src/lib/constants/api-tokens.ts` (`API_TOKEN_ALLOWED_ENDPOINTS

## GET `/api/requests/:id`
- Returns request including `audiobook`, `downloadHistory` (selected), and recent `jobs`.
- Non-admin callers (owner sessions, user-role tokens): explicit field list `OWNER_REQUEST_DETAIL_SELECT` (`src/lib/services/request-detail-query.ts`) — omits `Request.selectedTorrent`, `DownloadHistory.magnetLink/torrentUrl/downloadPath`, `Audiobook.filePath`, `Job.payload/result/stackTrace`; remaining strings pass through `stripProwlarrKeyFromResults()`. Admins get the full include.
- Non-admin callers (owner sessions, user-role tokens): explicit field list `OWNER_REQUEST_DETAIL_SELECT` (`src/lib/services/request-detail-query.ts`) — omits `Request.selectedTorrent`, `DownloadHistory.magnetLink/torrentUrl/downloadPath`, `Audiobook.filePath`, `Job.payload/result/stackTrace`; remaining strings pass through `stripProwlarrKeyFromResults()`. Admins get the full include, minus `Request.placedEbookFiles` (never returned by any request response: `GET /api/requests` list, `POST /api/requests` and this route included).
- Ownership enforced: `requestRecord.userId === req.user.id || role === 'admin'` → otherwise 403.
- Soft-deleted requests (`deletedAt != null`) return 404.
- BigInt columns (`downloadHistory[].torrentSizeBytes`, `audiobook.fileSizeBytes`) go out as JSON numbers via `toJsonSafe()` (`src/lib/utils/json-safe.ts`).
Expand Down
2 changes: 1 addition & 1 deletion documentation/integrations/ebook-sidecar.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ Ebook torrent ranking uses unified algorithm with ebook-specific scoring:
## Delete Behavior

**Ebook deletion is different from audiobook deletion:**
- Only deletes ebook files (`.epub`, `.pdf`, `.mobi`, etc.)
- Deletes only the ebook files this request's imports placed (`Request.placedEbookFiles`, written by the ebook organize for a `copied` file), each only while unchanged (size + sha256) and in a folder the library delete guard allows (#497). A user's own ebook in the book folder is never removed. No record (imported before the field, or the file was already there): nothing removed, the admin sees why. See [request-deletion.md](../admin-features/request-deletion.md) D2
- Does NOT delete the title folder (audiobook files remain)
- Does NOT delete from backend library (Plex/ABS)
- Does NOT clear audiobook availability linkage
Expand Down
2 changes: 2 additions & 0 deletions documentation/phase3/file-organization.md
Original file line number Diff line number Diff line change
Expand Up @@ -343,6 +343,8 @@ When user deletes and re-requests the same audiobook:
- Permissions (`applyFileMode` → `applied` / `refused` / `missing`): after a copy is published, `chmod(file_chmod)` is best-effort. mergerfs/NFS/FUSE/SMB often refuse it (EPERM, ENOTSUP, EACCES, …) though the write succeeded → placement stays `copied` with `PlaceResult.warning` (path, octal mode, code). ENOENT/ENOTDIR mean no file at the path → `failed`, never verified. Same for downloaded/cached cover art (missing = cover failed). No `chown` is done
- Warnings collect in `OrganizationResult.permissionWarnings` / `EbookOrganizationResult.permissionWarnings` (never in `errors`); `reportImportStatus` logs one summary per job (`summarizePermissionWarnings`) and the request message gets `permissions could not be applied to <n> file(s)`

**Ebook placement record (#497):** after a successful ebook organize, `recordEbookPlacement` (`src/lib/utils/ebook-placement.ts`, one call in `processEbookOrganization`) appends `{ path, size, sha256, placedAt }` of the placed target to `Request.placedEbookFiles`, only when placeFile returned `copied` (RMAB created the file; hash read from the placed bytes, after the Kindle fix). `identical`/`present`/`differs` add nothing (field becomes at least `[]`). Append-only, same path replaced by the newest entry; a NULL record on a request whose `completedAt` is already set (an earlier delivery with no record) starts with `{ earlierImport: 'unrecorded' }`; never fails the import (a hash or DB error is a warning and leaves the field as it was). The ebook request delete removes only these files ([request-deletion.md](../admin-features/request-deletion.md) D2).

**Stale partials:** before placing, regular files in that one target folder matching the exact pattern are removed when they belong to this target name or are older than 24 h.

**`placeFile(source, target)` statuses** (records keyed on the original source path):
Expand Down
Loading
Loading