BlueGit

timfa filemanager

Update navigation docs index

The technical reference now documents last-folder persistence and browser-history navigation behaviour.\nThe generated test index was refreshed to include the new route and page-load scenarios.

timfa Tim Falken · pushed by timfa

Authored 2026-05-26 · 5 months ago

Hash
6eddbc616ef783627376eecfaac7bbc1e529f566
Parent
cf7e6032
2 files changed +7 −0
.github/technical-reference.md +6 −0
@@ -44,6 +44,7 @@
44 44
45 45 ## server/db.js
46 46 - initDb() - Initializes SQLite schema for users, file metadata (including watched_by), and auth_sessions (idle timeout/revocation support), and migrates watched_by for existing DB files.
47 - initDb() - Also creates `user_last_navigation` to persist each user's last visited folder path and timestamp across sessions.
47 48 - getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
48 49 - closeDb() - Closes singleton DB handle to release file locks.
49 50
@@ -85,6 +86,7 @@
85 86 ## server/routes/files.js
86 87 - GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
87 88 - GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
89 - GET /api/files/roots - Returns `lastDir` when the authenticated user's previously visited folder is still accessible and exists; clears stale/inaccessible saved folders.
88 90 - loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
89 91 - parseOctalMode(rawValue, fallback) - Parses optional octal chmod mode overrides from environment variables and falls back to secure defaults when invalid.
90 92 - envFlagEnabled(name) - Boolean environment flag parser for file-route runtime feature toggles.
@@ -105,6 +107,7 @@
105 107 - POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
106 108 - GET /api/files/search - Fuzzy-searches all readable roots (and personal folder when configured) for files, returning ranked matches with path metadata.
107 109 - GET /api/files/list - Returns directory items including name/path/isDir plus size, mtime, and uploadedAt; uploadedAt comes from persisted `file_meta.uploaded_at` when present, otherwise it is backfilled from filesystem creation/change metadata and saved.
110 - GET /api/files/list - Persists the authenticated user's most recently opened folder in `user_last_navigation` after a successful directory listing.
108 111 - GET /api/files/list - When FILEMANAGER_LIST_ACCESS_CHMOD=1, runs a best-effort shallow chmod on the opened folder before listing (opened folder + direct children only; defaults: dirs 0777, files 0666; overrides via FILEMANAGER_LIST_ACCESS_CHMOD_DIR_MODE and FILEMANAGER_LIST_ACCESS_CHMOD_FILE_MODE).
109 112 - GET /api/files/search-images - Fuzzy-searches readable roots for image files with ready thumbnails, returning capped results plus scan-truncation metadata for scalable global favicon selection.
110 113 - GET /api/files/global-favicon-image - Publicly serves the configured global favicon thumbnail file so browsers can load `<link rel="icon">` without auth headers.
@@ -214,7 +217,10 @@
214 217 - getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
215 218 - saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
216 219 - loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
220 - loadRoots(opts) - Prefers local restoreDir/rootPath, then server-provided `lastDir`, and opens that folder automatically when still accessible.
217 221 - api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
222 - Browser popstate navigation - Maintains an in-app folder navigation array mirrored to History API state; browser back/forward steps through folder history.
223 - onBrowserPopState(event) - When history reaches browse index 0, shows: "Do you want to close the application and return to the previous webpage?" and on Yes runs normal browser back navigation.
218 224 - renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action.
219 225 - performLogout() - Explicit logout path that revokes server session and clears local session state.
220 226 - initAuth() - Restores prior session when valid and auto-logins without credential prompt.
@@ -44,6 +44,7 @@
44
44
45## server/db.js
45## server/db.js
46- initDb() - Initializes SQLite schema for users, file metadata (including watched_by), and auth_sessions (idle timeout/revocation support), and migrates watched_by for existing DB files.
46- initDb() - Initializes SQLite schema for users, file metadata (including watched_by), and auth_sessions (idle timeout/revocation support), and migrates watched_by for existing DB files.
47- initDb() - Also creates `user_last_navigation` to persist each user's last visited folder path and timestamp across sessions.
47- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
48- getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
48- closeDb() - Closes singleton DB handle to release file locks.
49- closeDb() - Closes singleton DB handle to release file locks.
49
50
@@ -85,6 +86,7 @@
85## server/routes/files.js
86## server/routes/files.js
86- GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
87- GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
87- GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
88- GET /api/files/roots - Adds a synthetic 'My folder' root for the authenticated user when userPath is configured.
89- GET /api/files/roots - Returns `lastDir` when the authenticated user's previously visited folder is still accessible and exists; clears stale/inaccessible saved folders.
88- loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
90- loadConfigAndRoots() - Loads config and effective roots together so route access checks stay consistent.
89- parseOctalMode(rawValue, fallback) - Parses optional octal chmod mode overrides from environment variables and falls back to secure defaults when invalid.
91- parseOctalMode(rawValue, fallback) - Parses optional octal chmod mode overrides from environment variables and falls back to secure defaults when invalid.
90- envFlagEnabled(name) - Boolean environment flag parser for file-route runtime feature toggles.
92- envFlagEnabled(name) - Boolean environment flag parser for file-route runtime feature toggles.
@@ -105,6 +107,7 @@
105- POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
107- POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
106- GET /api/files/search - Fuzzy-searches all readable roots (and personal folder when configured) for files, returning ranked matches with path metadata.
108- GET /api/files/search - Fuzzy-searches all readable roots (and personal folder when configured) for files, returning ranked matches with path metadata.
107- GET /api/files/list - Returns directory items including name/path/isDir plus size, mtime, and uploadedAt; uploadedAt comes from persisted `file_meta.uploaded_at` when present, otherwise it is backfilled from filesystem creation/change metadata and saved.
109- GET /api/files/list - Returns directory items including name/path/isDir plus size, mtime, and uploadedAt; uploadedAt comes from persisted `file_meta.uploaded_at` when present, otherwise it is backfilled from filesystem creation/change metadata and saved.
110- GET /api/files/list - Persists the authenticated user's most recently opened folder in `user_last_navigation` after a successful directory listing.
108- GET /api/files/list - When FILEMANAGER_LIST_ACCESS_CHMOD=1, runs a best-effort shallow chmod on the opened folder before listing (opened folder + direct children only; defaults: dirs 0777, files 0666; overrides via FILEMANAGER_LIST_ACCESS_CHMOD_DIR_MODE and FILEMANAGER_LIST_ACCESS_CHMOD_FILE_MODE).
111- GET /api/files/list - When FILEMANAGER_LIST_ACCESS_CHMOD=1, runs a best-effort shallow chmod on the opened folder before listing (opened folder + direct children only; defaults: dirs 0777, files 0666; overrides via FILEMANAGER_LIST_ACCESS_CHMOD_DIR_MODE and FILEMANAGER_LIST_ACCESS_CHMOD_FILE_MODE).
109- GET /api/files/search-images - Fuzzy-searches readable roots for image files with ready thumbnails, returning capped results plus scan-truncation metadata for scalable global favicon selection.
112- GET /api/files/search-images - Fuzzy-searches readable roots for image files with ready thumbnails, returning capped results plus scan-truncation metadata for scalable global favicon selection.
110- GET /api/files/global-favicon-image - Publicly serves the configured global favicon thumbnail file so browsers can load `<link rel="icon">` without auth headers.
113- GET /api/files/global-favicon-image - Publicly serves the configured global favicon thumbnail file so browsers can load `<link rel="icon">` without auth headers.
@@ -214,7 +217,10 @@
214- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
217- getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
215- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
218- saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
216- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
219- loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
220- loadRoots(opts) - Prefers local restoreDir/rootPath, then server-provided `lastDir`, and opens that folder automatically when still accessible.
217- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
221- api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
222- Browser popstate navigation - Maintains an in-app folder navigation array mirrored to History API state; browser back/forward steps through folder history.
223- onBrowserPopState(event) - When history reaches browse index 0, shows: "Do you want to close the application and return to the previous webpage?" and on Yes runs normal browser back navigation.
218- renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action.
224- renderDebugDashboardData(data) - Renders the debug dashboard panels, including the subtitle debug cache folder summary and open-folder action.
219- performLogout() - Explicit logout path that revokes server session and clears local session state.
225- performLogout() - Explicit logout path that revokes server session and clears local session state.
220- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
226- initAuth() - Restores prior session when valid and auto-logins without credential prompt.
.github/tests.md +1 −0
@@ -44,6 +44,7 @@
44 44 - `POST /api/files/upload`
45 45 - `POST /api/files/move`
46 46 - `root alias endpoints`
47 - `last visited folder persistence`
47 48 - `GET /api/files/thumbnail`
48 49 - `GET /api/files/root-access`
49 50 - `orphaned user folder access`
@@ -44,6 +44,7 @@
44- `POST /api/files/upload`
44- `POST /api/files/upload`
45- `POST /api/files/move`
45- `POST /api/files/move`
46- `root alias endpoints`
46- `root alias endpoints`
47- `last visited folder persistence`
47- `GET /api/files/thumbnail`
48- `GET /api/files/thumbnail`
48- `GET /api/files/root-access`
49- `GET /api/files/root-access`
49- `orphaned user folder access`
50- `orphaned user folder access`