| 1 | # Technical Reference
|
| 2 |
|
| 3 | ## server/index.js
|
| 4 | - start() - Initialises DB/keys, starts HTTP/HTTPS servers, and starts the background thumbnail cache loop.
|
| 5 | - shutdown(opts, ...servers) - Graceful teardown: stops thumbnail loop, closes DB/servers, exits with configurable code after drain/timeout.
|
| 6 |
|
| 7 | ## server/thumbnail-cache.js
|
| 8 | - syncThumbnailCacheOnce() - Mirrors configured roots into public/thumbs and generates 99x99-max WebP thumbnails for image files; removes stale thumbnails and updates manifest hashes while preserving prior cache entries for temporarily unavailable roots (e.g. removable mounts).
|
| 9 | - startThumbnailCacheLoop() - Schedules cache sync runs 5 seconds after boot and 5 seconds after each run completes.
|
| 10 | - stopThumbnailCacheLoop() - Stops scheduled background cache sync runs.
|
| 11 | - getCachedThumbnailInfo(sourceFile) - Returns cached thumbnail path/content-type when present; null when not ready.
|
| 12 | - getThumbPathForSourceFile(sourceFile) - Maps an absolute source file path to its mirrored cache thumbnail path.
|
| 13 | - getThumbRelPathForSourceFile(sourceFile) - Returns public-relative thumbnail path used in manifest entries.
|
| 14 | - getImagesWithThumbnailsInDir(dirPath) - Returns [{filePath, thumbRelPath}] for all images inside dirPath (recursive) that have a cached thumbnail; sorted by filePath.
|
| 15 | - getFolderIconSourceFile(folderPath) - Returns the source image path for a folder's icon: explicit assignment first, then auto-first cached image, null if none.
|
| 16 | - setFolderIconAssignment(folderPath, imagePath) - Saves an explicit folder icon assignment to .folder-icons.json; pass null to clear (auto-detect used instead).
|
| 17 |
|
| 18 | ## server/db.js
|
| 19 | - initDb() - Initializes SQLite schema for users, file metadata, and auth_sessions (idle timeout/revocation support).
|
| 20 | - getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
|
| 21 | - closeDb() - Closes singleton DB handle to release file locks.
|
| 22 |
|
| 23 | ## server/auth.js
|
| 24 | - createToken(username, req, fingerprint) - Creates JWT bound to IP/region/fingerprint and linked to a DB-backed session id.
|
| 25 | - requireAuth(req, res, next) - Verifies JWT + binding + session row + 1-hour idle timeout, updates last_seen_at, and attaches req.user.
|
| 26 | - requireAdmin(req, res, next) - Requires authenticated admin user.
|
| 27 | - revokeSession(sessionId) - Revokes a session row so future token use fails immediately.
|
| 28 | - getClientIp(req) - Normalizes request IP (including IPv4-mapped IPv6 loopback cases).
|
| 29 | - getRegion(ip) - Derives coarse region binding from geoip lookup or local fallback.
|
| 30 | - SESSION_IDLE_TIMEOUT_MS - Server-enforced idle timeout window (1 hour).
|
| 31 |
|
| 32 | ## server/routes/auth.js
|
| 33 | - extractCredentials(body) - Accepts encrypted payloads and compatibility plaintext payloads for login/setup.
|
| 34 | - makeAuthResponse(token, clientPublicKey) - Returns encrypted token when client key exists, plaintext token otherwise.
|
| 35 | - POST /api/auth/setup - Creates first admin and issues token.
|
| 36 | - POST /api/auth/login - Authenticates user by case-insensitive username match and issues token with canonical stored username.
|
| 37 | - GET /api/auth/me - Returns current authenticated user profile.
|
| 38 | - POST /api/auth/logout - Revokes the active session.
|
| 39 |
|
| 40 | ## server/routes/admin.js
|
| 41 | - POST /api/admin/users - Creates a new user and enforces case-insensitive username uniqueness.
|
| 42 | - normalizePermissions(permissions) - Normalizes permission maps and enforces that write access implies read access.
|
| 43 |
|
| 44 | ## server/routes/files.js
|
| 45 | - GET /api/files/roots - Returns readable roots with display label (alias when configured), originalName, and path.
|
| 46 | - POST /api/files/root-alias - Sets a display-only alias for an exact configured root path (no filesystem rename).
|
| 47 | - GET /api/files/root-access - Returns users who can access an exact configured root and their access mode (R / R+W).
|
| 48 | - GET /api/files/thumbnail - Serves cache-only thumbnail images for authorized files; returns 404 while cache is not ready.
|
| 49 | - GET /api/files/folder-images - Returns images inside a directory (recursive) that already have a cached thumbnail; only thumbnailed images are included per user requirement.
|
| 50 | - GET /api/files/folder-icon - Returns the current icon source file for a folder ({icon:{filePath}} or {icon:null}); explicit assignment takes priority over auto-first.
|
| 51 | - POST /api/files/folder-icon - Sets or clears a folder's explicit icon assignment; imagePath must have a cached thumbnail; write access required.
|
| 52 | - GET /api/files/download-zip?dir=<absolute-path> - Authenticated. Streams the directory as a zip archive; caches the zip for up to 1 day in zip-cache/.
|
| 53 | - makeTempUploadPath(dir, originalName) - Builds a hidden per-upload staging filename in the target directory for multipart uploads.
|
| 54 | - unlinkIfExists(targetPath, cb) - Removes a file during upload cleanup while ignoring already-missing temp files.
|
| 55 | - promoteUploadedFile(tempPath, finalPath, cb) - Atomically renames a completed staged upload into place on the Linux server.
|
| 56 | - splitNameExt(name) - Splits a filename into stem/ext, preserving dotless names and hidden-file behavior.
|
| 57 | - pickNumberedPath(dir, requestedName) - Finds the first free `name (n).ext` path inside a directory.
|
| 58 | - removePathRecursive(targetPath) - Deletes existing file or directory destination to support overwrite moves.
|
| 59 | - POST /api/files/upload - Streams multipart uploads into hidden temp files, cleans them up on abort, and only exposes final filenames after completion.
|
| 60 | - POST /api/files/move - Moves file/folder; supports conflict strategies: `error` (default), `overwrite`, or `rename` with optional `targetName`.
|
| 61 | - POST /api/files/video-stream - Creates a short-lived HLS session for a video and returns playlistUrl, subtitleTracks, and subtitleSummary ({total, converted, skipped}).
|
| 62 |
|
| 63 | ## server/routes/share.js
|
| 64 | - POST /api/share/create - Authenticated. Creates a 24-hour share token for a file or directory; returns {token, expiresAt}.
|
| 65 | - GET /api/share/info/:token - Public. Returns {name, isDir, expiresAt} for a valid non-expired token; 410 when expired, 404 when unknown.
|
| 66 | - GET /api/share/preview/:token - Public. Streams file content inline for preview (files only, max 50 MB); 400 for directories, 410 expired.
|
| 67 | - GET /api/share/download/:token - Public. Downloads the file or a zip of the directory for a valid token; 410 expired.
|
| 68 | - GET /api/share/video-stream/:token - Public. Creates a short-lived HLS session for a shared video and returns playlistUrl, subtitleTracks, and subtitleSummary ({total, converted, skipped}).
|
| 69 | - buildZip(dirPath, cacheKey) - Creates (or returns cached) zip in zip-cache/; prunes stale zips before building; exported for reuse in files.js.
|
| 70 | - pruneZipCache() - Deletes zip files in zip-cache/ older than 1 day; called automatically before each zip build.
|
| 71 | - ZIP_CACHE_DIR - Absolute path to the zip-cache/ directory (project root).
|
| 72 |
|
| 73 | ## server/video-stream.js
|
| 74 | - createVideoStreamSession(sourcePath) - Probes the input, attempts WebVTT conversion for all subtitle streams (skipping only failed conversions), starts ffmpeg HLS transcoding, and resolves once stream output begins; returns subtitleTracks plus subtitleSummary {total, converted, skipped}.
|
| 75 | - sendVideoStreamAsset(sessionId, assetPath, res) - Serves HLS playlists, segments, and extracted subtitle files from an active short-lived stream session.
|
| 76 | - STREAM_ROOT_DIR - Temporary root directory for active ffmpeg-backed stream sessions.
|
| 77 | - STREAM_SESSION_TTL_MS - Idle lifetime for a stream session before cleanup.
|
| 78 |
|
| 79 | ## server/db.js
|
| 80 | - initDb() - Initializes SQLite schema for users, file metadata, auth_sessions, and share_tokens (expires_at index).
|
| 81 | - getDb() - Returns singleton DB handle with WAL and foreign key pragmas.
|
| 82 | - closeDb() - Closes singleton DB handle to release file locks.
|
| 83 |
|
| 84 | ## public/share.html
|
| 85 | - Standalone public share page served at /share/:token; no auth required.
|
| 86 | - Timer bar - Live HH:MM:SS countdown showing remaining validity; turns red and disables download when expired.
|
| 87 | - tryPreview(name, isDir) - Renders inline preview (img/video/audio/text pre); no-op for unsupported types or directories.
|
| 88 | - Fetches /api/share/info/:token on load; shows error state for 404/410 responses.
|
| 89 | - Download link points to /api/share/download/:token; labelled "Download als .zip" for directories.
|
| 90 |
|
| 91 | ## public/index.html
|
| 92 | - Auth form - Login/setup form uses username plus mode-specific password autocomplete tokens so browser password managers behave correctly.
|
| 93 |
|
| 94 | ## public/app.js
|
| 95 | - showApp() - Reveals app shell; keeps sidebar folded by default on mobile and shows folder overview sidebar on desktop.
|
| 96 | - showAuthOverlay(setupMode) - Displays the login/setup overlay and switches the password autocomplete token between current-password and new-password based on mode.
|
| 97 | - getOrCreateClientBindingId() - Creates/loads a persistent local browser binding id used in auth fingerprint derivation.
|
| 98 | - getFingerprint() - Builds a stable fingerprint from binding id + stable browser properties (not viewport metrics) to avoid false session invalidation on UI/window-state changes.
|
| 99 | - saveSessionState() - Persists token, selected path, and last operation timestamp in localStorage.
|
| 100 | - loadSessionState() - Restores persisted state only when the last operation is within the 1-hour local idle window.
|
| 101 | - api(method, path, body, opts) - Central API caller; refreshes local session timestamp on successful authenticated calls.
|
| 102 | - performLogout() - Explicit logout path that revokes server session and clears local session state.
|
| 103 | - initAuth() - Restores prior session when valid and auto-logins without credential prompt.
|
| 104 | - showConfirm(title, message) - In-page confirm dialog; returns Promise<boolean>. Use instead of window.confirm().
|
| 105 | - showPrompt(title, message, defaultValue) - In-page text-input dialog; returns Promise<string|null>. Use instead of window.prompt().
|
| 106 | - showOverwrite(filename) - In-page overwrite-decision dialog for file conflicts; returns Promise<'yes'|'no'|'all'|'none'>.
|
| 107 | - splitNameExt(name) - Client-side filename splitter used for local conflict rename suggestions.
|
| 108 | - nextAvailableName(requestedName, existingNames) - Computes `name (n).ext` for upload/move rename options.
|
| 109 | - listDirNameSet(dir) - Fetches directory listing and returns a Set of existing names.
|
| 110 | - cloneFileWithName(file, newName) - Creates a renamed File object for non-overwrite uploads.
|
| 111 | - showFileConflictChoice(filename, renameTo, mode) - Dialog for single upload/move conflicts; returns overwrite/rename/cancel.
|
| 112 | - openShareModal(item) - Opens the Delen (share) popup, calls POST /api/share/create, shows the 24-hour URL with a copy button and OK to dismiss.
|
| 113 | - loadThumbnails() - Registers visible file icons for lazy thumbnail loading (both file thumbnails and folder icons); retries missing cache thumbnails during incremental refresh.
|
| 114 | - loadOneThumbnail(iconEl) - Loads thumbnails from server cache endpoint for images, text snapshots for text files, and badges for other files; marks image icons as pending when cache returns 404 and uses direct source SVG thumbnails for SVG files under 1MB.
|
| 115 | - observeFolderIcon(iconEl) - Registers a folder icon element with IntersectionObserver for lazy loading.
|
| 116 | - loadOneFolderIcon(iconEl) - Fetches /api/files/folder-icon then the thumbnail blob and overlays it inside the folder SVG; no-op if no icon available.
|
| 117 | - applyFolderThumbnail(iconEl, srcUrl) - Injects an SVG <image> element clipped to the folder outline path into the folder's icon SVG.
|
| 118 | - openFolderIconPicker(item) - Opens the folder icon picker modal; shows cached-thumbnail images from the folder; allows selection, clearing, and cancellation.
|
| 119 | - refreshAfterIconChange(item) - Resets and reloads the folder icon in both the grid tile and sidebar after set/clear operations.
|
| 120 | - disconnectFolderIconObserver() - Disconnects and clears the folder icon IntersectionObserver on grid rebuild.
|
| 121 | - getThumbnailKind(name) - Classifies files into image/text/badge thumbnail strategies.
|
| 122 | - observeThumbnailIcon(iconEl) - Defers thumbnail fetch work until file icons are near/in the viewport.
|
| 123 | - disconnectThumbnailObserver() - Clears active IntersectionObserver when the grid is rebuilt.
|
| 124 | - setThumbnailPending(iconEl, pending) - Toggles per-icon pending spinner state while a cached image thumbnail is not ready yet.
|
| 125 | - buildThumbnailSource(item, blob, kind) - Produces thumbnail image source (data/blob URL) for icon injection.
|
| 126 | - renderStreamedVideoPreview(item, targetEl) - Creates the Video.js player with HLS source and initial subtitle track config; warns when subtitle streams exist but none are web-compatible.
|
| 127 |
|
| 128 | ## tests/thumbnail-cache.test.js
|
| 129 | - thumbnail cache worker / creates cached thumbnail with dimensions smaller than 100px - Verifies cached image generation and manifest write.
|
| 130 | - thumbnail cache worker / removes cached thumbnail when source file is deleted - Verifies stale thumbnail cleanup behavior.
|
| 131 | - afterEach() cleanup - Removes temp roots with `fs.rmSync(...maxRetries...)` to tolerate transient Windows file locks.
|
| 132 | - detectCodeLanguage(name, mime) - Determines preview language for text/script files by MIME and extension.
|
| 133 | - prettyPrintCode(raw, lang) - Best-effort formatter for JSON/markup/script previews before rendering.
|
| 134 | - highlightCode(raw, lang) - Escapes and syntax-highlights preview text into HTML spans.
|
| 135 | - fileAccentColor(name) - Returns canonical file-type accent color used by icon strokes and preview sheet outline.
|
| 136 | - openFolderSidebar() - Persistent sidebar fallback view that shows current folder/root overview when no item is selected.
|
| 137 | - closeSidebar() - Clears selection; hides the panel entirely on mobile and restores folder overview sidebar on desktop.
|
| 138 | - isMobileViewport() - Central media-query helper for mobile-only sidebar/interaction behavior.
|
| 139 | - hideSidebarPanel() - Hides sidebar panel and removes sidebar-open layout class from the app shell.
|
| 140 | - renderBreadcrumb() - Builds clickable breadcrumb path and marks each folder segment as a drag-drop move target via .crumb-drop-target and data-path.
|
| 141 | - fetchFileBlob(item) - Downloads a file as Blob with auth headers for preview/download flows.
|
| 142 | - downloadOrView(item, sourceSvgEl) - Opens preview; prefers in-place expanded tile preview when invoked from a file icon, falls back to overlay when no source tile is available.
|
| 143 | - downloadOrView(item, sourceSvgEl) - Opens in-place expanded tile preview from a file icon; shows error toast if no source tile is found.
|
| 144 | - renderPreviewBody(item, blob, objectUrl, targetEl) - Renders preview content (image/video/audio/pdf/text) or unsupported message into a target container.
|
| 145 | - animateRect(el, fromRect, toRect, opts) - Helper that animates element rectangle (left/top/width/height) for expand/collapse transitions.
|
| 146 | - openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents the real file tile to body, expands it to viewport preview, injects close/download controls.
|
| 147 | - openExpandedTilePreview(item, tileEl, sourceSvgEl, blob, objectUrl) - Reparents tile to body, shows spinner during expand animation, renders content after animation; applies file-type accent colour to tile border and outline glow.
|
| 148 | - openExpandedTilePreview(item, tileEl, sourceSvgEl, loadPreviewContent) - Adds preview action buttons for Download and Share; Share opens the same modal flow as sidebar sharing.
|
| 149 | - closeExpandedTilePreview() - Collapses expanded tile preview back to original grid position and restores original icon markup.
|
| 150 | - closePreview() - Closes either expanded-tile preview or overlay preview, then revokes active preview object URL.
|
| 151 | - closePreview() - Closes expanded-tile preview and revokes active preview object URL.
|
| 152 | - openMovePicker(item) - Opens Move To selector modal with expandable folder tree across all writable roots and executes /api/files/move.
|
| 153 | - moveWithConflictResolution(item, targetDir) - Attempts move and handles 409 conflicts by prompting overwrite/rename/cancel then retries.
|
| 154 | - rootPermissionLabel(root) - Resolves permission key for a root using originalName when available (alias-safe permission checks).
|
| 155 | - ensureMoveModal() - Lazily creates and wires Move To modal UI (tree, selection state, confirm/cancel handlers).
|
| 156 | - createMoveNode(folderPath, label) - Builds an expandable/selectable folder node for the Move To tree.
|
| 157 | - loadMoveChildren(containerEl, dirPath) - Lazy-loads subfolders for a tree node via /api/files/list.
|
| 158 | - isInlinePreviewableBlob(blob, name) - Determines if a blob can be previewed inline by MIME/extension.
|
| 159 | - makeFileItem(item) - Builds a .file-item element; roots in Home now use folder-like interaction (single-click focus, double-click open), roots are non-draggable, and mobile long-press contextmenu suppression remains.
|
| 160 | - attachMobileLongPress(el, item) - Adds mobile long-press detection on file/folder tiles to open the item sidebar without desktop side effects.
|
| 161 | - openSidebar(item) - Renders item details/actions in sidebar; roots show alias + original name + usage stats, hide Move To/Delete, keep Rename.
|
| 162 | - fetchRootAccessList(rootPath) - Fetches root access users from the server for a specific configured root.
|
| 163 | - formatRootAccessList(users) - Formats root access entries as "username mode" values for sidebar rendering.
|
| 164 | - openSidebar(item) - Renders item details/actions in sidebar; root selections include alias/original name/usage/access list and keep Rename while hiding Move To/Delete.
|
| 165 | - openFolderSidebar() - Shows current folder details when nothing is selected; when at root base-level it also shows root access list.
|
| 166 | - openRenameModal(item) - Renames files/folders; for roots this writes display alias via /api/files/root-alias and reloads roots.
|
| 167 | - uploadFiles(fileList) - Uploads files one-by-one with per-file conflict prompt (overwrite/rename/cancel) when names already exist.
|
| 168 | - openUserModal(user, paths) - Admin user editor; enforces UI permission rule that Write is disabled/unchecked while Read is unchecked.
|
| 169 |
|
| 170 | ## public/drag-move.js
|
| 171 | - makeDraggable(el, item) - Attaches pointerdown to a .file-item; starts drag after threshold movement. Depends on: api(), canWrite(), navigateTo(), STATE, closeSidebar(), toast() from app.js.
|
| 172 | - makeDraggable(el, item) - Touch drag now requires a short hold before movement, uses pointer capture, and keeps drag responsive on mobile.
|
| 173 | - (internal) _beginDrag(e, el, item) - Lifts and re-parents the real .file-item to body, inserts hidden placeholder, and shows parent-folder drag target when applicable.
|
| 174 | - (internal) _moveDrag(e) - Moves the real dragged item, hit-tests folder tiles, breadcrumb segments, and parent-folder target, toggles target highlight state.
|
| 175 | - (internal) _endDrag() - On valid target: runs drop animation, calls moveWithConflictResolution() for overwrite/rename/cancel conflicts, then refreshes dir. Otherwise snap-back.
|
| 176 | - (internal) _cleanupDrag(reinsert) - Restores tile styles; reinserts into grid on failure/abort or removes before refresh on success, hides drag helper targets.
|
| 177 |
|
| 178 | ## public/drag-move.css
|
| 179 | - .file-item.dragging - Lifted style for real dragged tile.
|
| 180 | - .file-item.drop-target - Glows folder icon when drag hovers over it.
|
| 181 | - .drag-parent-target - Temporary top-left "move to parent" drop target shown while dragging in nested folders.
|
| 182 | - .crumb-drop-target.active - Highlight style for breadcrumb drop destinations during drag.
|
| 183 | - @keyframes drag-rise-spin-fall - Real tile rises, spins, falls/scales into folder on drop.
|
| 184 | - @keyframes folder-bounce - Target folder bounces down then back on accept.
|
| 185 | - .preview-backdrop/.file-item--preview/.preview-expand-* - In-place expanded tile preview styling (no separate overlay window), including preserved icon-outline layer.
|
| 186 | - .preview-expand-share - Secondary action button positioned next to .preview-expand-download in expanded file preview.
|
| 187 | - .move-modal/.move-tree/.move-node* - Move To tree picker styles with expandable/collapsible folder hierarchy.
|
| 188 |
|
| 189 | ## tests/auth.routes.test.js
|
| 190 | - session lifecycle / POST /api/auth/logout revokes active session - Verifies explicit logout invalidates token immediately.
|
| 191 | - session lifecycle / session expires after 1 hour of inactivity - Verifies server-side idle timeout enforcement.
|
| 192 |
|
| 193 | ## tests/page.load.test.js
|
| 194 | - bootClient() - Boots the app in jsdom and waits until app shell is visible or timeout before assertions.
|
| 195 | - waitFor(dom, predicate, timeoutMs) - Poll helper used by interaction tests to wait for rendered tiles.
|
| 196 | - login overlay uses username and current-password autocomplete tokens - Verifies normal sign-in mode exposes browser-friendly login autocomplete attributes.
|
| 197 | - first-run setup uses new-password autocomplete token - Verifies setup mode switches the password field to the browser-friendly new-password token.
|
| 198 | - expanded file preview shows a Share button next to Download - Verifies expanded preview UI includes both actions inside a dedicated footer below the preview content.
|
| 199 | - expanded video preview uses a stream session and video.js - Verifies streamed video preview uses the server-backed HLS session and registers subtitle tracks with video.js.
|
| 200 |
|
| 201 | ## tests/video-stream.test.js
|
| 202 | - createVideoStreamSession resolves once ffmpeg starts writing stream assets - Verifies session creation no longer waits for the final master playlist before preview can begin.
|
| 203 | - createVideoStreamSession configures flat segment filenames that match playlist URLs - Verifies ffmpeg segment output paths match the segment URLs emitted in the generated HLS playlists.
|