/image-metadata (#4788) * git push --force Implement background management in json lint upload multer weirdness, fix for timestamp * remove duplicated logic to generate backgrounds.json * remove duplicate logic to create backgrounds.js * remove excessive enodent eror handling * simplify shared extension constants * move backgrounds.json to backgrounds/index.json * use plimit * move user directory iteration to syncBackgroundsMetadata insetad of server main * create and move getBackgroundThumbnailResolution * nitpick * typdef * simplify checks * use read method * error -> regenerate * use fileExists * type error fix (maybe) * add object to jsdoc returns * typo * use getUniqueName from util.js * remove duplicated multer something or other * make skipped_extensions a set * remove strict comparison Co-authored-by: Cohee <18619528+Cohee1207@users.noreply.github.com> * create isAnimatedWebP and use it * use file creation date instead of server date * actually type BackgroundImageMetadata * use fileExists instead of try catch * response.sendStatus(500); * sync json to allow adding images to the folder without restart * lint * Generic image metadata endpoint. Remove tags and starred. No startup sync. * lint * Descriptive json and move to util.js * remove folders routes * It's a POST * Revert file name to index.json * Type errors fixing * Remove p-limit * Why? * apply codex suggestions * see comment * remove unused functions * remove path normalization for da path, not needed * Fix dimensions shadowing issue, circular imports, and apply bg res to only bg * move thumbnailsEnabled to the top level * Metadata now stored at {userDataRoot}/image-metadata.json instead of per-folder index.json Uses relative paths as keys (e.g., backgrounds/sunset.png) for easy file existence checking Added cleanupOrphanedMetadata() function and /api/image-metadata/cleanup endpoint for data-maid integration Simplified the API endpoint by removing folder-grouping logic * lint * update backgrounds.js imports * security check, .replaceAll * Remove useless function, pass type to cache invalidate and seperate file types * fix: normalize file paths to use POSIX separators in metadata functions * serve original --------- Co-authored-by: Cohee <18619528+Cohee1207@users.noreply.github.com>

f5b5350cf4ea20d6a6e1c869edabf65bf6815ab7

L <123923688+Vibecoder9000@users.noreply.github.com>

Signed

Parents: 5c62cf4a6ef7d3b73d9ac746c2b08e1ab026e8a9

package-lock.json+62 -20 Viewed

                 "host-validation-middleware": "^0.1.1",
                 "html-entities": "^2.6.0",
                 "iconv-lite": "^0.6.3",
+                "image-size": "^2.0.2",
                 "ip-matching": "^2.1.2",
                 "ip-regex": "^5.0.0",
                 "ipaddr.js": "^2.2.0",

             "integrity": "sha512-QpLcX9ZSsq3YYUUnD3nFDY8H7wctAhQj/TFKL8Ya8v5fMm3CFXxo8zStsLAl780ltoYoo1WvKUVGBQK+1ifr7g==",
             "license": "MIT"
         },
+        "node_modules/image-size": {
+            "version": "2.0.2",
+            "resolved": "https://registry.npmjs.org/image-size/-/image-size-2.0.2.tgz",
+            "integrity": "sha512-IRqXKlaXwgSMAMtpNzZa1ZAe8m+Sa1770Dhk8VkSsP9LS+iHD62Zd8FQKs8fbPiagBE7BzoFX23cxFnwshpV6w==",
+            "license": "MIT",
+            "bin": {
+                "image-size": "bin/image-size.js"
+            },
+            "engines": {
+                "node": ">=16.x"
+            }
+        },
         "node_modules/immediate": {
             "version": "3.0.6",
             "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",

                 "node": ">=10.12.0"
+            }
         },
+        "node_modules/node-persist/node_modules/p-limit": {
+            "version": "3.1.0",
+            "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
+            "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
+            "license": "MIT",
+            "dependencies": {
+                "yocto-queue": "^0.1.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/node-persist/node_modules/yocto-queue": {
+            "version": "0.1.0",
+            "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
+            "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=10"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
         "node_modules/node-releases": {
             "version": "2.0.18",
             "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.18.tgz",

                 "node": ">=8"
+            }
         },
-        "node_modules/p-limit": {
+        "node_modules/p-locate": {
+            "version": "5.0.0",
+            "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz",
+            "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "p-limit": "^3.0.2"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/p-locate/node_modules/p-limit": {
             "version": "3.1.0",
             "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
             "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
+            "dev": true,
             "license": "MIT",
             "dependencies": {
                 "yocto-queue": "^0.1.0"

                 "url": "https://github.com/sponsors/sindresorhus"
+            }
         },
-        "node_modules/p-locate": {
+        "node_modules/p-locate/node_modules/yocto-queue": {
-            "version": "5.0.0",
+            "version": "0.1.0",
-            "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz",
+            "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
-            "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==",
+            "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
             "dev": true,
             "license": "MIT",
-            "dependencies": {
-                "p-limit": "^3.0.2"
-            },
             "engines": {
                 "node": ">=10"
             },

                 "node": ">=12"
+            }
         },
-        "node_modules/yocto-queue": {
-            "version": "0.1.0",
-            "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
-            "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
-            "license": "MIT",
-            "engines": {
-                "node": ">=10"
-            },
-            "funding": {
-                "url": "https://github.com/sponsors/sindresorhus"
-            }
-        },
         "node_modules/zip-stream": {
             "version": "6.0.1",
             "resolved": "https://registry.npmjs.org/zip-stream/-/zip-stream-6.0.1.tgz",

package.json+1 -0 Viewed

         "host-validation-middleware": "^0.1.1",
         "html-entities": "^2.6.0",
         "iconv-lite": "^0.6.3",
+        "image-size": "^2.0.2",
         "ip-matching": "^2.1.2",
         "ip-regex": "^5.0.0",
         "ipaddr.js": "^2.2.0",

src/endpoints/backgrounds.js+3 -2 Viewed

 import express from 'express';
 import sanitize from 'sanitize-filename';
-import { dimensions, invalidateThumbnail } from './thumbnails.js';
+import { invalidateThumbnail } from './thumbnails.js';
+import { thumbnailDimensions } from './image-metadata.js';
 import { getImages } from '../util.js';
 import { getFileNameValidationFunction } from '../middleware/validateFileName.js';

 router.post('/all', function (request, response) {
     const images = getImages(request.user.directories.backgrounds);
-    const config = { width: dimensions.bg[0], height: dimensions.bg[1] };
+    const config = { width: thumbnailDimensions.bg[0], height: thumbnailDimensions.bg[1] };
     response.json({ images, config });
 });

src/endpoints/image-metadata.js+417 -0 Viewed

+/**
+ * Generic image metadata service.
+ * Provides on-demand metadata generation with file mtime-based caching.
+ */
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { imageSize } from 'image-size';
+import writeFileAtomic from 'write-file-atomic';
+import express from 'express';
+import { Jimp } from '../jimp.js';
+import { getConfigValue, isPathUnderParent } from '../util.js';
+export const METADATA_FILE = 'image-metadata.json';
+/**
+ * @typedef {Object} ImageMetadata
+ * @property {string} hash - SHA-256 hash of the image file.
+ * @property {number} aspectRatio - Aspect ratio (width / height) of the image.
+ * @property {boolean} isAnimated - Whether the image is animated.
+ * @property {string} dominantColor - Dominant color in hex format (e.g., '#RRGGBB').
+ * @property {string[]} folderIds - Array of virtual folder IDs the image belongs to.
+ * @property {number} addedTimestamp - Timestamp when the image was added.
+ * @property {number} thumbnailResolution - Thumbnail resolution (width * height) for cache invalidation.
+ * @property {number} [mtime] - File modification time for cache invalidation (internal use).
+ */
+/**
+ * @typedef {Object} MetadataIndex
+ * @property {number} version - Metadata version.
+ * @property {Object.<string, ImageMetadata>} images - Mapping of relative paths to their metadata.
+ * @property {Array<{id: string, name: string, thumbnailFile: string}>} folders - Virtual folders.
+ */
+/**
+ * @typedef {'bg' | 'avatar' | 'persona'} ThumbnailType
+ */
+/** @type {Record<string, number[]>} */
+export const thumbnailDimensions = {
+    'bg': getConfigValue('thumbnails.dimensions.bg', [160, 90]),
+    'avatar': getConfigValue('thumbnails.dimensions.avatar', [96, 144]),
+    'persona': getConfigValue('thumbnails.dimensions.persona', [96, 144]),
+};
+/**
+ * Gets the configured resolution for a given thumbnail type.
+ * @param {ThumbnailType} type Thumbnail type
+ * @returns {number} Resolution (width * height)
+ */
+export function getThumbnailResolution(type) {
+    const dims = thumbnailDimensions[type];
+    if (Array.isArray(dims) && dims.length >= 2) {
+        return Number(dims[0]) * Number(dims[1]);
+    }
+    return 0;
+}
+/**
+ * Checks if a buffer contains an animated PNG (APNG) by looking for the 'acTL' chunk.
+ * @param {Buffer} buffer The file buffer.
+ * @returns {boolean}
+ */
+function isAnimatedApng(buffer) {
+    return buffer.subarray(0, 200).includes('acTL');
+}
+/**
+ * Checks if a WebP buffer is animated by looking for 'ANIM' or 'ANMF' chunks.
+ * @param {Buffer} buffer The WebP file buffer (can be full file or header)
+ * @returns {boolean} True if the WebP is animated
+ */
+export function isAnimatedWebP(buffer) {
+    const headerBuffer = buffer.length > 200 ? buffer.subarray(0, 200) : buffer;
+    return headerBuffer.includes('ANIM') || headerBuffer.includes('ANMF');
+}
+/**
+ * Calculate average color using Jimp.
+ * Resizes the image to 1x1 to efficiently get the average color.
+ * @param {Buffer} buffer The image buffer.
+ * @returns {Promise<string>} The average color as a hex string (e.g., '#RRGGBB').
+ */
+async function getAverageColorWithJimp(buffer) {
+    try {
+        const image = await Jimp.read(buffer);
+        image.resize({ w: 1, h: 1 });
+        const colorInt = image.getPixelColor(0, 0);
+        const r = (colorInt >> 24) & 255;
+        const g = (colorInt >> 16) & 255;
+        const b = (colorInt >> 8) & 255;
+        const toHex = (c) => c.toString(16).padStart(2, '0');
+        return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+    } catch (error) {
+        console.warn('[Jimp] Failed to calculate average color:', error.message);
+        return '#808080';
+    }
+}
+/**
+ * Generates metadata for a single image file.
+ * @param {string} filePath - The full path to the image file.
+ * @param {ThumbnailType} type - The thumbnail type for resolution calculation.
+ * @returns {Promise<ImageMetadata>} A metadata object. Throws an error if processing fails.
+ */
+export async function generateImageMetadata(filePath, type) {
+    const buffer = await fs.readFile(filePath);
+    const hash = crypto.createHash('sha256').update(buffer).digest('hex');
+    const dimensions = imageSize(buffer);
+    if (!dimensions || !dimensions.width || !dimensions.height) {
+        throw new Error('Could not determine image dimensions.');
+    }
+    const aspectRatio = dimensions.width / dimensions.height;
+    let isAnimated = false;
+    switch (dimensions.type) {
+        case 'gif':
+            isAnimated = true;
+            break;
+        case 'png':
+            isAnimated = isAnimatedApng(buffer);
+            break;
+        case 'webp':
+            isAnimated = isAnimatedWebP(buffer);
+            break;
+    }
+    let dominantColor;
+    if (isAnimated) {
+        dominantColor = '#808080';
+    } else {
+        dominantColor = await getAverageColorWithJimp(buffer);
+    }
+    let addedTimestamp;
+    try {
+        const stats = await fs.stat(filePath);
+        addedTimestamp = Math.floor(stats.birthtimeMs || stats.mtimeMs);
+    } catch {
+        addedTimestamp = Date.now();
+    }
+    return {
+        hash,
+        aspectRatio: parseFloat(aspectRatio.toFixed(4)),
+        isAnimated,
+        dominantColor,
+        folderIds: [],
+        addedTimestamp,
+        thumbnailResolution: getThumbnailResolution(type),
+    };
+}
+/**
+ * Reads the centralized metadata index from the user data root.
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @returns {Promise<MetadataIndex>} The metadata index
+ */
+export async function readMetadataIndex(userDataRoot) {
+    const indexPath = path.join(userDataRoot, METADATA_FILE);
+    try {
+        const rawData = await fs.readFile(indexPath, 'utf8');
+        return JSON.parse(rawData);
+    } catch {
+        return { version: 1, images: {}, folders: [] };
+    }
+}
+/**
+ * Writes the centralized metadata index to the user data root.
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @param {MetadataIndex} metadata - The metadata to write
+ */
+export async function writeMetadataIndex(userDataRoot, metadata) {
+    const indexPath = path.join(userDataRoot, METADATA_FILE);
+    const jsonString = JSON.stringify(metadata, null, 4);
+    await writeFileAtomic(indexPath, jsonString, 'utf8');
+}
+/**
+ * Gets metadata for multiple images, generating on-demand as needed.
+ * Uses relative paths from the user data root as keys in the centralized index.
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @param {string[]} relativePaths - Array of relative paths from userDataRoot
+ * @param {ThumbnailType} type - The thumbnail type for resolution calculation.
+ * @returns {Promise<Object.<string, ImageMetadata>>} Map of relativePath to metadata
+ */
+export async function getOrGenerateMetadataBatch(userDataRoot, relativePaths, type) {
+    /** @type {Object.<string, ImageMetadata>} */
+    const results = {};
+    const index = await readMetadataIndex(userDataRoot);
+    let indexModified = false;
+    for (const relativePath of relativePaths) {
+        // Normalize the path to use forward slashes for consistent keys
+        const posixPath = relativePath.replaceAll(path.sep, path.posix.sep);
+        const fullPath = path.join(userDataRoot, relativePath);
+        let stats;
+        try {
+            stats = await fs.stat(fullPath);
+        } catch {
+            continue; // File doesn't exist, skip
+        }
+        const currentMtime = stats.mtimeMs;
+        const cached = index.images[posixPath];
+        // If cached and not modified, use cached
+        if (cached && cached.mtime === currentMtime) {
+            results[relativePath] = cached;
+            continue;
+        }
+        // Generate new metadata
+        try {
+            const metadata = await generateImageMetadata(fullPath, type);
+            metadata.mtime = currentMtime;
+            // Preserve folderIds if they existed
+            if (cached?.folderIds) {
+                metadata.folderIds = cached.folderIds;
+            }
+            index.images[posixPath] = metadata;
+            results[relativePath] = metadata;
+            indexModified = true;
+        } catch (error) {
+            console.warn(`[ImageMetadata] Failed to generate metadata for ${relativePath}:`, error.message);
+        }
+    }
+    // Write index if modified
+    if (indexModified) {
+        await writeMetadataIndex(userDataRoot, index);
+    }
+    return results;
+}
+/**
+ * Removes metadata for an image from the centralized index.
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @param {string} relativePath - The relative path to remove
+ */
+export async function removeMetadata(userDataRoot, relativePath) {
+    const posixPath = relativePath.replaceAll(path.sep, path.posix.sep);
+    const index = await readMetadataIndex(userDataRoot);
+    if (index.images[posixPath]) {
+        delete index.images[posixPath];
+        await writeMetadataIndex(userDataRoot, index);
+    }
+}
+/**
+ * Updates metadata for an image (e.g., after rename).
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @param {string} oldRelativePath - The old relative path
+ * @param {string} newRelativePath - The new relative path
+ * @returns {Promise<ImageMetadata|null>} The updated metadata
+ */
+export async function renameMetadata(userDataRoot, oldRelativePath, newRelativePath) {
+    const posixOldPath = oldRelativePath.replaceAll(path.sep, path.posix.sep);
+    const posixNewPath = newRelativePath.replaceAll(path.sep, path.posix.sep);
+    const index = await readMetadataIndex(userDataRoot);
+    const data = index.images[posixOldPath];
+    if (!data) {
+        throw new Error(`Image '${oldRelativePath}' not found in metadata.`);
+    }
+    delete index.images[posixOldPath];
+    index.images[posixNewPath] = data;
+    await writeMetadataIndex(userDataRoot, index);
+    return data;
+}
+/**
+ * Cleans up orphaned entries from the metadata index.
+ * Iterates over all entries and removes those whose files no longer exist.
+ * @param {string} userDataRoot - Path to the user data directory root
+ * @returns {Promise<string[]>} Array of removed paths
+ */
+export async function cleanupOrphanedMetadata(userDataRoot) {
+    const index = await readMetadataIndex(userDataRoot);
+    const orphanedPaths = [];
+    for (const relativePath of Object.keys(index.images)) {
+        const fullPath = path.resolve(userDataRoot, relativePath);
+        if (!isPathUnderParent(userDataRoot, fullPath)) {
+            orphanedPaths.push(relativePath);
+            delete index.images[relativePath];
+            continue;
+        }
+        try {
+            await fs.access(fullPath);
+        } catch {
+            // File doesn't exist, mark for removal
+            orphanedPaths.push(relativePath);
+            delete index.images[relativePath];
+        }
+    }
+    if (orphanedPaths.length > 0) {
+        await writeMetadataIndex(userDataRoot, index);
+        console.log(`[ImageMetadata] Cleaned up ${orphanedPaths.length} orphaned metadata entries`);
+    }
+    return orphanedPaths;
+}
+export const router = express.Router();
+/**
+ * POST /api/image-metadata
+ * Get metadata for image(s) by path.
+ */
+router.post('/', async function (request, response) {
+    try {
+        const { path: singlePath, paths, type } = request.body;
+        if (!singlePath && !paths) {
+            return response.status(400).json({ error: 'Either "path" or "paths" is required.' });
+        }
+        const userDataRoot = request.user.directories.root;
+        // Helper to validate a path is under user data directory
+        const validatePath = (relativePath) => {
+            const fullPath = path.resolve(userDataRoot, relativePath);
+            if (!isPathUnderParent(userDataRoot, fullPath)) {
+                throw new Error(`Path "${relativePath}" is outside the user data directory.`);
+            }
+            return relativePath;
+        };
+        // Handle single path
+        if (singlePath && !paths) {
+            const relativePath = validatePath(singlePath);
+            const fullPath = path.join(userDataRoot, relativePath);
+            try {
+                await fs.access(fullPath);
+            } catch {
+                return response.status(404).json({ error: 'File not found.' });
+            }
+            const metadataResults = await getOrGenerateMetadataBatch(userDataRoot, [relativePath], type);
+            const metadata = metadataResults[relativePath];
+            if (!metadata) {
+                return response.status(404).json({ error: 'Could not generate metadata for file.' });
+            }
+            return response.json(metadata);
+        }
+        // Handle multiple paths
+        if (paths && Array.isArray(paths)) {
+            /** @type {Object.<string, ImageMetadata|{error: string}>} */
+            const results = {};
+            const validPaths = [];
+            // Validate all paths first
+            for (const relativePath of paths) {
+                try {
+                    validatePath(relativePath);
+                    validPaths.push(relativePath);
+                } catch (error) {
+                    results[relativePath] = { error: error.message };
+                }
+            }
+            // Process all valid paths in a single batch
+            const batchMetadata = await getOrGenerateMetadataBatch(userDataRoot, validPaths, type);
+            for (const relativePath of validPaths) {
+                if (batchMetadata[relativePath]) {
+                    results[relativePath] = batchMetadata[relativePath];
+                } else {
+                    results[relativePath] = { error: 'File not found or could not process.' };
+                }
+            }
+            return response.json(results);
+        }
+        return response.status(400).json({ error: 'Invalid request format.' });
+    } catch (error) {
+        console.error('[ImageMetadata] API error:', error);
+        return response.status(500).json({ error: 'Internal server error.' });
+    }
+});
+/**
+ * POST /api/image-metadata/cleanup
+ * Clean up orphaned metadata entries (files that no longer exist).
+ */
+router.post('/cleanup', async function (request, response) {
+    try {
+        const userDataRoot = request.user.directories.root;
+        const removed = await cleanupOrphanedMetadata(userDataRoot);
+        return response.json({ removed, count: removed.length });
+    } catch (error) {
+        console.error('[ImageMetadata] Cleanup error:', error);
+        return response.status(500).json({ error: 'Internal server error.' });
+    }
+});

src/endpoints/thumbnails.js+172 -121 Viewed

 import fs from 'node:fs';
-import { promises as fsPromises } from 'node:fs';
 import path from 'node:path';
-import mime from 'mime-types';
 import express from 'express';
 import sanitize from 'sanitize-filename';
 import { Jimp, JimpMime } from '../jimp.js';
 import { sync as writeFileAtomicSync } from 'write-file-atomic';
+import { imageSize as sizeOf } from 'image-size';
 import { getConfigValue, invalidateFirefoxCache } from '../util.js';
+import { getThumbnailResolution, isAnimatedWebP, thumbnailDimensions as dimensions } from './image-metadata.js';
+import { ResizeStrategy } from '@jimp/plugin-resize';
+export const publicRouter = express.Router();
+export const apiRouter = express.Router();
+export const SKIPPED_EXTENSIONS = new Set(['.apng', '.mp4', '.webm', '.avi', '.mkv', '.flv', '.gif']);
+export const ALLOWED_IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.tif', '.tiff', '.apng']);
 const thumbnailsEnabled = !!getConfigValue('thumbnails.enabled', true, 'boolean');
 const quality = Math.min(100, Math.max(1, parseInt(getConfigValue('thumbnails.quality', 95, 'number'))));

  * @typedef {'bg' | 'avatar' | 'persona'} ThumbnailType
  */
-/** @type {Record<string, number[]>} */
-export const dimensions = {
-    'bg': getConfigValue('thumbnails.dimensions.bg', [160, 90]),
-    'avatar': getConfigValue('thumbnails.dimensions.avatar', [96, 144]),
-    'persona': getConfigValue('thumbnails.dimensions.persona', [96, 144]),
-};
 /**
  * Gets a path to thumbnail folder based on the type.

+}
 /**
- * Generates a thumbnail for the given file.
+ * Generates or retrieves a thumbnail for a given file.
- * @param {import('../users.js').UserDirectoryList} directories User directories
+ * @param {import('../users.js').UserDirectoryList} directories - User's directory configuration.
- * @param {ThumbnailType} type Type of the thumbnail
+ * @param {ThumbnailType} type - Type of thumbnail ('bg', 'avatar', 'persona').
- * @param {string} file Name of the file
+ * @param {string} file - The filename of the image.
- * @returns
+ * @param {boolean} [forceGenerate=false] - Whether to force generation even if a thumbnail exists.
+ * @param {boolean|null} [isKnownAnimated=null] - If true, skips generation. If false, assumes static. If null, checks.
+ * @returns {Promise<{path: string|null, aspectRatio: number|null, resolution: number|null}>} Path to thumbnail, its aspect ratio, and resolution.
  */
-async function generateThumbnail(directories, type, file) {
+export async function generateThumbnail(directories, type, file, forceGenerate = false, isKnownAnimated = null) {
-    let thumbnailFolder = getThumbnailFolder(directories, type);
+    // If the caller has already determined the file is animated, skip processing.
-    let originalFolder = getOriginalFolder(directories, type);
+    if (isKnownAnimated) {
+        return { path: null, aspectRatio: null, resolution: null };
+    }
+    const thumbnailFolder = getThumbnailFolder(directories, type);
+    const originalFolder = getOriginalFolder(directories, type);
     if (thumbnailFolder === undefined || originalFolder === undefined) throw new Error('Invalid thumbnail type');
     const pathToCachedFile = path.join(thumbnailFolder, file);
-    const pathToOriginalFile = path.join(originalFolder, file);
-    const cachedFileExists = fs.existsSync(pathToCachedFile);
+    try {
-    const originalFileExists = fs.existsSync(pathToOriginalFile);
+        const pathToOriginalFile = path.join(originalFolder, file);
-    // to handle cases when original image was updated after thumb creation
+        // Check if thumbnail already exists and return it if not forcing regeneration
-    let shouldRegenerate = false;
+        if (!forceGenerate && fs.existsSync(pathToCachedFile)) {
+            try {
-    if (cachedFileExists && originalFileExists) {
+                // Check if original image was updated after thumbnail creation
-        const originalStat = fs.statSync(pathToOriginalFile);
+                const originalFileExists = fs.existsSync(pathToOriginalFile);
-        const cachedStat = fs.statSync(pathToCachedFile);
+                if (originalFileExists) {
+                    const originalStat = fs.statSync(pathToOriginalFile);
-        if (originalStat.mtimeMs > cachedStat.ctimeMs) {
+                    const cachedStat = fs.statSync(pathToCachedFile);
-            //console.warn('Original file changed. Regenerating thumbnail...');
-            shouldRegenerate = true;
+                    if (originalStat.mtimeMs > cachedStat.ctimeMs) {
+                        // Original file changed, regenerate thumbnail
+                        forceGenerate = true;
+                    }
+                }
+                if (!forceGenerate) {
+                    const buffer = fs.readFileSync(pathToCachedFile);
+                    const fileDimensions = sizeOf(buffer);
+                    const ratio = (fileDimensions.height > 0) ? (fileDimensions.width / fileDimensions.height) : 1.0;
+                    // When a thumbnail exists, return the current resolution from config so the JSON can be updated.
+                    const resolution = getThumbnailResolution(type);
+                    return { path: pathToCachedFile, aspectRatio: ratio, resolution };
+                }
+            } catch (e) {
+                forceGenerate = true;
+            }
+        }
+        if (!fs.existsSync(pathToOriginalFile)) {
+            console.error(`[generateThumbnail] Cannot generate thumbnail, original file not found: ${pathToOriginalFile}`);
+            return { path: null, aspectRatio: null, resolution: null };
+        }
-    }
-    if (cachedFileExists && !shouldRegenerate) {
-        return pathToCachedFile;
-    }
-    if (!originalFileExists) {
+        const fileExtension = path.extname(file).toLowerCase();
-        return null;
-    }
-    try {
+        // For WebP files, we must check if they are animated, as Jimp cannot process them.
-        let buffer;
+        // If isKnownAnimated is false, we assume the caller knows it is static and skip this check.
+        if (fileExtension === '.webp' && isKnownAnimated !== false) {
-        try {
+            const buffer = fs.readFileSync(pathToOriginalFile);
-            const size = dimensions[type];
+            const isAnimated = isAnimatedWebP(buffer);
-            const image = await Jimp.read(pathToOriginalFile);
+            if (isAnimated) {
-            const width = !isNaN(size?.[0]) && size?.[0] > 0 ? size[0] : image.bitmap.width;
+                // The client is expected to handle it.
-            const height = !isNaN(size?.[1]) && size?.[1] > 0 ? size[1] : image.bitmap.height;
+                return { path: null, aspectRatio: null, resolution: null };
-            image.cover({ w: width, h: height });
+            }
-            buffer = pngFormat
-                ? await image.getBuffer(JimpMime.png)
-                : await image.getBuffer(JimpMime.jpeg, { quality: quality, jpegColorSpace: 'ycbcr' });
+        }
-        catch (inner) {
-            console.warn(`Thumbnailer can not process the image: ${pathToOriginalFile}. Using original size`, inner);
+        if (SKIPPED_EXTENSIONS.has(fileExtension)) {
-            buffer = fs.readFileSync(pathToOriginalFile);
+            return { path: null, aspectRatio: null, resolution: null };
+        }
-        writeFileAtomicSync(pathToCachedFile, buffer);
+        // Process the image to generate thumbnail
-    }
+        const result = await processSingleImage(file, originalFolder, thumbnailFolder, type);
-    catch (outer) {
+        if (result.success) {
-        return null;
+            return { path: pathToCachedFile, aspectRatio: result.aspectRatio ?? null, resolution: result.resolution ?? null };
+        } else {
+            console.error(`[generateThumbnail] Failed to process image ${file}:`, result.error);
+            return { path: null, aspectRatio: null, resolution: null };
+        }
+    } catch (error) {
+        console.error(`[generateThumbnail] Unexpected error processing ${file}:`, error);
+        return { path: null, aspectRatio: null, resolution: null };
+    }
-    return pathToCachedFile;
+}
 /**
- * Ensures that the thumbnail cache for backgrounds is valid.
+ * Processes a single image to generate its thumbnail.
- * @param {import('../users.js').UserDirectoryList[]} directoriesList User directories
+ * @param {string} file - The filename of the image.
- * @returns {Promise<void>} Promise that resolves when the cache is validated
+ * @param {string} originalFolder - Path to the original image folder.
+ * @param {string} thumbnailFolder - Path to the thumbnail output folder.
+ * @param {ThumbnailType} type - The type of thumbnail to generate.
+ * @returns {Promise<{success: boolean, filename?: string, error?: string, aspectRatio?: number, resolution?: number}>} Result of the processing.
  */
-export async function ensureThumbnailCache(directoriesList) {
+async function processSingleImage(file, originalFolder, thumbnailFolder, type) {
-    for (const directories of directoriesList) {
+    const pathToOriginalFile = path.join(originalFolder, file);
-        const cacheFiles = fs.readdirSync(directories.thumbnailsBg);
+    const pathToCachedFile = path.join(thumbnailFolder, file);
-        // files exist, all ok
+    try {
-        if (cacheFiles.length) {
+        const fileBuffer = fs.readFileSync(pathToOriginalFile);
-            continue;
+        const image = await Jimp.read(fileBuffer);
+        // Calculate aspect ratio from original image dimensions
+        const originalWidth = image.bitmap.width;
+        const originalHeight = image.bitmap.height;
+        const aspectRatio = (originalHeight > 0) ? (originalWidth / originalHeight) : 1.0;
+        const thumbImage = image.clone();
+        const thumbnailResolution = getThumbnailResolution(type);
+        if (type === 'bg') {
+            const [configWidth, configHeight] = dimensions[type];
+            const targetPixelArea = configWidth * configHeight;
+            // Calculate thumbnail dimensions to maintain target pixel area while preserving aspect ratio
+            // For aspect ratio w:h, if area = w*h and ratio = w/h, then:
+            // w = sqrt(area * ratio) and h = sqrt(area / ratio)
+            const thumbWidth = Math.round(Math.sqrt(targetPixelArea * aspectRatio));
+            const thumbHeight = Math.round(Math.sqrt(targetPixelArea / aspectRatio));
+            thumbImage.resize({ w: thumbWidth, h: thumbHeight, mode: ResizeStrategy.BILINEAR });
+        } else if (type === 'avatar' || type === 'persona') {
+            // Crop and resize to fixed dimensions
+            const [configWidth, configHeight] = dimensions[type];
+            thumbImage.cover({ w: configWidth, h: configHeight });
+        }
-        console.info('Generating thumbnails cache. Please wait...');
+        const buffer = pngFormat
+            ? await thumbImage.getBuffer(JimpMime.png)
-        const bgFiles = fs.readdirSync(directories.backgrounds);
+            : await thumbImage.getBuffer(JimpMime.jpeg, { quality: quality, jpegColorSpace: 'ycbcr' });
-        const tasks = [];
-        for (const file of bgFiles) {
+        writeFileAtomicSync(pathToCachedFile, buffer);
-            tasks.push(generateThumbnail(directories, 'bg', file));
-        }
-        await Promise.all(tasks);
+        return { success: true, aspectRatio, resolution: thumbnailResolution };
-        console.info(`Done! Generated: ${bgFiles.length} preview images`);
+    } catch (error) {
+        console.warn(`[Thumbnails] Failed to process image ${file}:`, error);
+        return { success: false, filename: file, error: error.message };
+    }
+}
-export const router = express.Router();
+/**
+ * Public endpoint for serving thumbnails.
-// Important: This route must be mounted as '/thumbnail'. It is used in the client code and saved to chat files.
+ * @param {express.Request} request - The Express request object.
-router.get('/', async function (request, response) {
+ * @param {express.Response} response - The Express response object.
-    try{
+ */
-        if (typeof request.query.file !== 'string' || typeof request.query.type !== 'string') {
+publicRouter.get('/', async function (request, response) {
-            return response.sendStatus(400);
+    try {
-        }
+        const { file: rawFile, type, animated } = request.query;
+        if (typeof rawFile !== 'string' || typeof type !== 'string') return response.sendStatus(400);
-        const type = request.query.type;
-        const file = sanitize(request.query.file);
-        if (!type || !file) {
-            return response.sendStatus(400);
-        }
         if (!(type === 'bg' || type === 'avatar' || type === 'persona')) {
             return response.sendStatus(400);
+        }
-        if (sanitize(file) !== file) {
+        const file = sanitize(rawFile);
-            console.error('Malicious filename prevented');
+        if (file !== rawFile) return response.sendStatus(403);
-            return response.sendStatus(403);
-        }
-        if (!thumbnailsEnabled) {
+        const serveOriginal = () => {
             const folder = getOriginalFolder(request.user.directories, type);
+            const pathToOriginalFile = path.resolve(path.join(folder, file));
-            if (folder === undefined) {
+            if (!fs.existsSync(pathToOriginalFile)) return response.sendStatus(404);
-                return response.sendStatus(400);
-            }
-            const pathToOriginalFile = path.join(folder, file);
-            if (!fs.existsSync(pathToOriginalFile)) {
-                return response.sendStatus(404);
-            }
-            const contentType = mime.lookup(pathToOriginalFile) || 'image/png';
-            const originalFile = await fsPromises.readFile(pathToOriginalFile);
-            response.setHeader('Content-Type', contentType);
             invalidateFirefoxCache(pathToOriginalFile, request, response);
+            return response.sendFile(pathToOriginalFile);
+        };
-            return response.send(originalFile);
+        if (!thumbnailsEnabled) {
+            return serveOriginal();
+        }
-        const pathToCachedFile = await generateThumbnail(request.user.directories, type, file);
+        const animatedEnabled = animated === 'true';
+        const fileExtension = path.extname(file).toLowerCase();
+        const isAnimatedFormat = SKIPPED_EXTENSIONS.has(fileExtension);
-        if (!pathToCachedFile) {
+        // Serve original for animated formats or GIFs
-            return response.sendStatus(404);
+        if (animatedEnabled && isAnimatedFormat) {
+            return serveOriginal();
+        }
+        if (fileExtension === '.gif') {
+            return serveOriginal();
+        }
+        const thumbnailFolder = getThumbnailFolder(request.user.directories, type);
+        const pathToCachedFile = path.join(thumbnailFolder, file);
+        // Try to generate thumbnail if it doesn't exist
         if (!fs.existsSync(pathToCachedFile)) {
-            return response.sendStatus(404);
+            const thumbResult = await generateThumbnail(request.user.directories, type, file, false);
+            // If generation failed (path is null), serve the original file
+            if (!thumbResult.path) {
+                return serveOriginal();
+            }
+        }
-        const contentType = mime.lookup(pathToCachedFile) || 'image/jpeg';
+        if (fs.existsSync(pathToCachedFile)) {
-        const cachedFile = await fsPromises.readFile(pathToCachedFile);
+            invalidateFirefoxCache(pathToCachedFile, request, response);
-        response.setHeader('Content-Type', contentType);
+            return response.sendFile(path.resolve(pathToCachedFile));
+        }
-        invalidateFirefoxCache(file, request, response);
+        // Send a 404 so the frontend can display a placeholder
+        return response.sendStatus(404);
-        return response.send(cachedFile);
     } catch (error) {
         console.error('Failed getting thumbnail', error);
         return response.sendStatus(500);
+    }
 });
+export const router = express.Router();
+router.use(publicRouter);
+router.use(apiRouter);

src/server-main.js+0 -2 Viewed

     getConfigValue,
 } from './util.js';
 import { UPLOADS_DIRECTORY } from './constants.js';
-import { ensureThumbnailCache } from './endpoints/thumbnails.js';
 // Routers
 import { router as usersPublicRouter } from './endpoints/users-public.js';

     const directories = await getUserDirectoriesList();
     await migrateGroupChatsMetadataFormat(directories);
     await checkForNewContent(directories);
-    await ensureThumbnailCache(directories);
     await diskCache.verify(directories);
     migrateFlatSecrets(directories);
     cleanUploads();

src/server-startup.js+2 -0 Viewed

 import { router as minimaxRouter } from './endpoints/minimax.js';
 import { router as dataMaidRouter } from './endpoints/data-maid.js';
 import { router as backupsRouter } from './endpoints/backups.js';
+import { router as imageMetadataRouter } from './endpoints/image-metadata.js';
 import { router as volcengineRouter } from './endpoints/volcengine.js';
 /**

     app.use('/api/minimax', minimaxRouter);
     app.use('/api/data-maid', dataMaidRouter);
     app.use('/api/backups', backupsRouter);
+    app.use('/api/image-metadata', imageMetadataRouter);
+}
 /**