@trokky/trokky 2.0.3

package/dist/adapters/filesystem-media/filesystem-media-adapter.js

@@ -0,0 +1,639 @@
+import { promises as fs, constants } from 'fs';
+import * as fsExtra from 'fs-extra';
+import * as path from 'path';
+import { SecurityValidator, InvalidInputError, createLogger } from '../../core/index.js';
+export class FilesystemMediaAdapter {
+    config;
+    logger = createLogger('adapter', 'FilesystemMediaAdapter');
+    // Security limits
+    MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+    constructor(config = {}) {
+        this.config = {
+            mediaDir: config.mediaDir || './media',
+            createDirs: config.createDirs ?? true,
+            prettyJson: config.prettyJson ?? true,
+            jsonSpaces: config.jsonSpaces ?? 2,
+            syncWrites: config.syncWrites ?? false,
+            fileMode: config.fileMode ?? 0o644,
+            dirMode: config.dirMode ?? 0o755,
+            silent: config.silent ?? false,
+            mediaBaseUrl: config.mediaBaseUrl
+        };
+        // Initialize directories
+        if (this.config.createDirs) {
+            this.initializeDirectories();
+        }
+        if (!this.config.silent) {
+            this.logger.info('FilesystemMediaAdapter initialized', {
+                mediaDir: this.config.mediaDir
+            });
+        }
+    }
+    async initializeDirectories() {
+        try {
+            await fsExtra.ensureDir(this.config.mediaDir, { mode: this.config.dirMode });
+        }
+        catch (error) {
+            if (!this.config.silent) {
+                this.logger.error('Failed to initialize media directories', error);
+            }
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // FILE OPERATIONS
+    // ==========================================================================
+    async uploadFile(file, metadata) {
+        try {
+            // Validate media metadata
+            this.validateMediaMetadata(metadata);
+            // Use secure path methods
+            const filePath = this.getMediaPath(metadata.id, metadata.extension);
+            const metadataPath = this.getMediaMetadataPath(metadata.id);
+            // Ensure media directory exists
+            await fsExtra.ensureDir(path.dirname(filePath), { mode: this.config.dirMode });
+            await fsExtra.ensureDir(path.dirname(metadataPath), { mode: this.config.dirMode });
+            // Write file content
+            const buffer = await this.fileToBuffer(file);
+            // Validate file size
+            if (buffer.length > this.MAX_FILE_SIZE) {
+                throw new InvalidInputError(`File too large (${buffer.length} bytes). Maximum size is ${this.MAX_FILE_SIZE} bytes.`, 'size');
+            }
+            await fs.writeFile(filePath, buffer, { mode: this.config.fileMode });
+            const now = new Date();
+            const fileMetadata = {
+                id: metadata.id,
+                filename: metadata.filename,
+                contentType: metadata.contentType,
+                size: metadata.size,
+                extension: metadata.extension,
+                originalPath: filePath,
+                createdAt: now,
+                updatedAt: now
+            };
+            // Write metadata atomically
+            const metadataContent = this.formatJson(fileMetadata);
+            await this.atomicWriteFile(metadataPath, metadataContent);
+            // Generate file URL (relative path for portability)
+            const relativeUrl = path.relative(process.cwd(), filePath).replace(/\\/g, '/');
+            const mediaFile = {
+                id: metadata.id,
+                filename: metadata.filename,
+                contentType: metadata.contentType,
+                size: metadata.size,
+                metadata: {
+                    path: relativeUrl,
+                    extension: metadata.extension,
+                    originalFilename: metadata.filename
+                },
+                _createdAt: now
+            };
+            if (!this.config.silent) {
+                this.logger.info('File uploaded', {
+                    id: metadata.id,
+                    filename: metadata.filename,
+                    size: metadata.size
+                });
+            }
+            return mediaFile;
+        }
+        catch (error) {
+            this.logger.error(`Failed to upload file ${metadata.filename}`, error);
+            throw error;
+        }
+    }
+    async getFile(id) {
+        try {
+            SecurityValidator.validateDocumentId(id);
+            const metadataPath = this.getMediaMetadataPath(id);
+            // Check if metadata file exists
+            try {
+                await fs.access(metadataPath, constants.F_OK);
+            }
+            catch {
+                return null;
+            }
+            const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+            const fileMetadata = this.safeParseJSON(metadataContent);
+            const filePath = this.getMediaPath(id, fileMetadata.extension);
+            // Check if actual file exists
+            try {
+                await fs.access(filePath, constants.F_OK);
+            }
+            catch {
+                // Metadata exists but file is missing
+                this.logger.warn(`Media file ${id} metadata found but file is missing`);
+                return null;
+            }
+            const relativeUrl = path.relative(process.cwd(), filePath).replace(/\\/g, '/');
+            const mediaFile = {
+                id: fileMetadata.id,
+                filename: fileMetadata.filename,
+                contentType: fileMetadata.contentType,
+                size: fileMetadata.size,
+                metadata: {
+                    path: relativeUrl,
+                    extension: fileMetadata.extension,
+                    originalFilename: fileMetadata.filename,
+                    title: fileMetadata.title,
+                    alt: fileMetadata.alt,
+                    author: fileMetadata.author,
+                    credit: fileMetadata.credit,
+                    tags: fileMetadata.tags,
+                    imageVariants: fileMetadata.imageVariants ?
+                        await this.updateVariantUrls(fileMetadata.imageVariants, fileMetadata.id) :
+                        undefined,
+                    originalDimensions: fileMetadata.originalDimensions
+                },
+                _createdAt: fileMetadata.createdAt
+            };
+            return mediaFile;
+        }
+        catch (error) {
+            this.logger.error(`Failed to get file ${id}`, error);
+            throw new Error(`Failed to get file: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    async updateFile(id, metadata) {
+        try {
+            SecurityValidator.validateDocumentId(id);
+            const metadataPath = this.getMediaMetadataPath(id);
+            // Check if metadata file exists
+            try {
+                await fs.access(metadataPath, constants.F_OK);
+            }
+            catch {
+                throw new Error(`Media file ${id} not found`);
+            }
+            const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+            const fileMetadata = this.safeParseJSON(metadataContent);
+            // Update metadata
+            const updatedMetadata = {
+                ...fileMetadata,
+                ...metadata,
+                id: fileMetadata.id, // Ensure ID cannot be changed
+                updatedAt: new Date()
+            };
+            // Write updated metadata
+            const jsonContent = this.formatJson(updatedMetadata);
+            await this.atomicWriteFile(metadataPath, jsonContent);
+            if (!this.config.silent) {
+                this.logger.info('File metadata updated', { id });
+            }
+            // Return updated media file
+            return (await this.getFile(id));
+        }
+        catch (error) {
+            this.logger.error(`Failed to update file ${id}`, error);
+            throw error;
+        }
+    }
+    async getFileContent(id) {
+        try {
+            SecurityValidator.validateDocumentId(id);
+            const mediaFile = await this.getFile(id);
+            if (!mediaFile) {
+                return null;
+            }
+            const filePath = this.getMediaPath(id, mediaFile.metadata?.extension);
+            try {
+                const buffer = await fs.readFile(filePath);
+                const sliced = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+                // Ensure we return ArrayBuffer, not SharedArrayBuffer
+                if (sliced instanceof ArrayBuffer) {
+                    return sliced;
+                }
+                else {
+                    // Copy SharedArrayBuffer to ArrayBuffer
+                    const arrayBuffer = new ArrayBuffer(sliced.byteLength);
+                    new Uint8Array(arrayBuffer).set(new Uint8Array(sliced));
+                    return arrayBuffer;
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+        catch (error) {
+            this.logger.error(`Failed to get file content for ${id}`, error);
+            return null;
+        }
+    }
+    async listMedia(options = {}) {
+        try {
+            // Check if media directory exists
+            try {
+                await fs.access(this.config.mediaDir, constants.F_OK);
+            }
+            catch {
+                return { items: [], total: 0 };
+            }
+            const files = await fs.readdir(this.config.mediaDir);
+            const metadataFiles = files.filter(file => file.endsWith('.meta.json'));
+            const mediaFiles = [];
+            for (const metadataFile of metadataFiles) {
+                try {
+                    const id = metadataFile.replace('.meta.json', '');
+                    // Read metadata directly - trust metadata as source of truth for listing
+                    const metadataPath = this.getMediaMetadataPath(id);
+                    const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+                    const fileMetadata = this.safeParseJSON(metadataContent);
+                    // Check if actual file exists for logging purposes, but don't filter it out
+                    const filePath = this.getMediaPath(id, fileMetadata.extension);
+                    let fileExists = false;
+                    try {
+                        await fs.access(filePath, constants.F_OK);
+                        fileExists = true;
+                    }
+                    catch {
+                        // File doesn't exist, but we'll still include it in the listing
+                        // Individual file serving will handle the missing file error when accessed
+                        this.logger.warn(`Media file ${id} has metadata but file is missing at ${filePath}`);
+                    }
+                    const relativeUrl = path.relative(process.cwd(), filePath).replace(/\\/g, '/');
+                    const mediaFile = {
+                        id: fileMetadata.id,
+                        filename: fileMetadata.filename,
+                        contentType: fileMetadata.contentType,
+                        size: fileMetadata.size,
+                        metadata: {
+                            path: relativeUrl,
+                            extension: fileMetadata.extension,
+                            originalFilename: fileMetadata.filename,
+                            title: fileMetadata.title,
+                            alt: fileMetadata.alt,
+                            author: fileMetadata.author,
+                            credit: fileMetadata.credit,
+                            tags: fileMetadata.tags,
+                            imageVariants: fileMetadata.imageVariants ?
+                                await this.updateVariantUrls(fileMetadata.imageVariants, fileMetadata.id) :
+                                undefined,
+                            originalDimensions: fileMetadata.originalDimensions,
+                            // Add file existence status for debugging
+                            _fileExists: fileExists
+                        },
+                        _createdAt: fileMetadata.createdAt
+                    };
+                    mediaFiles.push(mediaFile);
+                }
+                catch (error) {
+                    this.logger.warn(`Skipping invalid metadata file ${metadataFile}`, error);
+                    continue;
+                }
+            }
+            // Apply filters
+            let filteredFiles = mediaFiles;
+            if (options.contentType) {
+                filteredFiles = filteredFiles.filter(file => file.contentType.includes(options.contentType));
+            }
+            if (options.sizeRange) {
+                filteredFiles = filteredFiles.filter(file => {
+                    const size = file.size;
+                    if (options.sizeRange.min && size < options.sizeRange.min)
+                        return false;
+                    if (options.sizeRange.max && size > options.sizeRange.max)
+                        return false;
+                    return true;
+                });
+            }
+            if (options.dateRange) {
+                filteredFiles = filteredFiles.filter(file => {
+                    const date = file._createdAt;
+                    if (options.dateRange.from && date < options.dateRange.from)
+                        return false;
+                    if (options.dateRange.to && date > options.dateRange.to)
+                        return false;
+                    return true;
+                });
+            }
+            // Apply sorting - default to newest first if no sort specified
+            if (options.sort) {
+                this.sortMediaFiles(filteredFiles, options.sort, options.sortDirection);
+            }
+            else {
+                // Default: sort by date descending (newest first)
+                this.sortMediaFiles(filteredFiles, 'date', 'desc');
+            }
+            // Store total count before pagination
+            const total = filteredFiles.length;
+            // Apply pagination
+            const { offset = 0, limit } = options;
+            const start = offset;
+            const end = limit ? start + limit : undefined;
+            const items = filteredFiles.slice(start, end);
+            return { items, total };
+        }
+        catch (error) {
+            this.logger.error('Failed to list media files', error);
+            throw new Error(`Failed to list media: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    async deleteFile(id) {
+        try {
+            SecurityValidator.validateDocumentId(id);
+            const mediaFile = await this.getFile(id);
+            if (!mediaFile) {
+                throw new Error(`Media file ${id} not found`);
+            }
+            const filePath = this.getMediaPath(id, mediaFile.metadata?.extension);
+            const metadataPath = this.getMediaMetadataPath(id);
+            // Delete variant files first
+            await this.deleteVariantFiles(id);
+            // Delete metadata FIRST, then main file
+            // This ensures if file deletion fails, the file won't show up in listMedia()
+            // since listMedia() uses metadata files as source of truth
+            try {
+                await fs.unlink(metadataPath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+            // Then delete main file
+            try {
+                await fs.unlink(filePath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    // File deletion failed after metadata removal
+                    // Log for manual cleanup, but metadata is already gone
+                    this.logger.error('File deletion failed after metadata removal', {
+                        id,
+                        filePath,
+                        error: error.message
+                    });
+                    throw error;
+                }
+            }
+            if (!this.config.silent) {
+                this.logger.debug('File deleted', { id });
+            }
+        }
+        catch (error) {
+            this.logger.error(`Failed to delete file ${id}`, error);
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // VARIANT OPERATIONS
+    // ==========================================================================
+    async saveVariantFile(parentId, variantName, buffer, format) {
+        try {
+            SecurityValidator.validateDocumentId(parentId);
+            SecurityValidator.validateDocumentId(variantName);
+            // Create variants directory if it doesn't exist
+            const variantsDir = path.join(this.config.mediaDir, 'variants');
+            await fsExtra.ensureDir(variantsDir, { mode: this.config.dirMode });
+            // Create parent directory for this image's variants
+            const parentVariantsDir = path.join(variantsDir, parentId);
+            await fsExtra.ensureDir(parentVariantsDir, { mode: this.config.dirMode });
+            // Save variant file
+            const variantFilename = `${variantName}.${format}`;
+            const variantPath = path.join(parentVariantsDir, variantFilename);
+            await fs.writeFile(variantPath, buffer, { mode: this.config.fileMode });
+            if (!this.config.silent) {
+                this.logger.info('Variant file saved', { parentId, variantName, format });
+            }
+            // Return relative path for URL generation
+            return `variants/${parentId}/${variantFilename}`;
+        }
+        catch (error) {
+            this.logger.error(`Failed to save variant file ${parentId}/${variantName}`, error);
+            throw error;
+        }
+    }
+    async getVariantContent(parentId, variantName) {
+        try {
+            SecurityValidator.validateDocumentId(parentId);
+            SecurityValidator.validateDocumentId(variantName);
+            // First check if the parent media file exists
+            const mediaFile = await this.getFile(parentId);
+            if (!mediaFile) {
+                return null;
+            }
+            // Get variant info from metadata to determine format
+            const variants = mediaFile.metadata?.imageVariants;
+            if (!variants || !variants[variantName]) {
+                return null;
+            }
+            const variantInfo = variants[variantName];
+            const variantFilename = `${variantName}.${variantInfo.format || 'webp'}`;
+            const variantPath = path.join(this.config.mediaDir, 'variants', parentId, variantFilename);
+            // Security check: ensure the resolved path is still within the media directory
+            const resolvedPath = path.resolve(variantPath);
+            const mediaBaseDir = path.resolve(this.config.mediaDir);
+            if (!resolvedPath.startsWith(mediaBaseDir)) {
+                throw new Error('Access denied: path traversal detected');
+            }
+            // Check if variant file exists
+            try {
+                await fs.access(resolvedPath, constants.F_OK);
+                const stats = await fs.stat(resolvedPath);
+                if (!stats.isFile()) {
+                    return null;
+                }
+            }
+            catch {
+                return null;
+            }
+            // Read and return variant file content
+            const buffer = await fs.readFile(resolvedPath);
+            const sliced = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+            // Ensure we return ArrayBuffer, not SharedArrayBuffer
+            if (sliced instanceof ArrayBuffer) {
+                return sliced;
+            }
+            else {
+                // Copy SharedArrayBuffer to ArrayBuffer
+                const arrayBuffer = new ArrayBuffer(sliced.byteLength);
+                new Uint8Array(arrayBuffer).set(new Uint8Array(sliced));
+                return arrayBuffer;
+            }
+        }
+        catch (error) {
+            this.logger.error(`Failed to get variant content for ${parentId}/${variantName}`, error);
+            return null;
+        }
+    }
+    async deleteVariantFiles(parentId) {
+        try {
+            SecurityValidator.validateDocumentId(parentId);
+            const parentVariantsDir = path.join(this.config.mediaDir, 'variants', parentId);
+            // Check if directory exists before trying to delete
+            try {
+                await fs.access(parentVariantsDir, constants.F_OK);
+                await fs.rm(parentVariantsDir, { recursive: true, force: true });
+                if (!this.config.silent) {
+                    this.logger.debug('Variant files deleted', { parentId });
+                }
+            }
+            catch {
+                // Directory doesn't exist, nothing to delete
+            }
+        }
+        catch (error) {
+            this.logger.error(`Failed to delete variant files for ${parentId}`, error);
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // UTILITY OPERATIONS
+    // ==========================================================================
+    async healthCheck() {
+        try {
+            // Test directory access
+            await fs.access(this.config.mediaDir, constants.R_OK | constants.W_OK);
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Health check failed', error);
+            return false;
+        }
+    }
+    // ==========================================================================
+    // PRIVATE HELPER METHODS
+    // ==========================================================================
+    getMediaPath(id, extension) {
+        SecurityValidator.validateDocumentId(id);
+        // Basic validation for extension (no need for full document ID validation)
+        if (!extension || typeof extension !== 'string' || extension.length > 10) {
+            throw new InvalidInputError('Invalid file extension', 'extension');
+        }
+        return path.join(this.config.mediaDir, `${id}.${extension}`);
+    }
+    getMediaMetadataPath(id) {
+        SecurityValidator.validateDocumentId(id);
+        return path.join(this.config.mediaDir, `${id}.meta.json`);
+    }
+    validateMediaMetadata(metadata) {
+        if (!metadata.id || typeof metadata.id !== 'string') {
+            throw new InvalidInputError('Media metadata must have a valid ID', 'id');
+        }
+        if (!metadata.filename || typeof metadata.filename !== 'string') {
+            throw new InvalidInputError('Media metadata must have a valid filename', 'filename');
+        }
+        if (!metadata.contentType || typeof metadata.contentType !== 'string') {
+            throw new InvalidInputError('Media metadata must have a valid content type', 'contentType');
+        }
+        if (!metadata.extension || typeof metadata.extension !== 'string') {
+            throw new InvalidInputError('Media metadata must have a valid extension', 'extension');
+        }
+        if (typeof metadata.size !== 'number' || metadata.size <= 0) {
+            throw new InvalidInputError('Media metadata must have a valid size', 'size');
+        }
+    }
+    formatJson(data) {
+        if (this.config.prettyJson) {
+            return JSON.stringify(data, this.dateReplacer, this.config.jsonSpaces);
+        }
+        return JSON.stringify(data, this.dateReplacer);
+    }
+    dateReplacer(key, value) {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        return value;
+    }
+    dateReviver(key, value) {
+        if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/.test(value)) {
+            return new Date(value);
+        }
+        return value;
+    }
+    safeParseJSON(content) {
+        try {
+            return JSON.parse(content, this.dateReviver);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON content: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    async atomicWriteFile(filePath, content) {
+        const tempPath = `${filePath}.tmp`;
+        try {
+            await fs.writeFile(tempPath, content, {
+                mode: this.config.fileMode,
+                encoding: 'utf8'
+            });
+            if (this.config.syncWrites) {
+                const fd = await fs.open(tempPath, 'r+');
+                await fd.sync();
+                await fd.close();
+            }
+            await fs.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Clean up temp file on error
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    async fileToBuffer(file) {
+        const arrayBuffer = await file.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async getVariantUrl(parentId, variantName) {
+        try {
+            SecurityValidator.validateDocumentId(parentId);
+            SecurityValidator.validateDocumentId(variantName);
+            if (this.config.mediaBaseUrl) {
+                return ''; // No URL generation - let frontend handle URL construction
+            }
+            return `file://${path.resolve(this.config.mediaDir, 'variants', parentId, variantName)}`;
+        }
+        catch (error) {
+            this.logger.error(`Failed to get variant URL for ${parentId}/${variantName}`, error);
+            return null;
+        }
+    }
+    async updateVariantUrls(imageVariants, parentId) {
+        const updatedVariants = {};
+        for (const [variantName, variantData] of Object.entries(imageVariants)) {
+            const url = await this.getVariantUrl(parentId, variantName);
+            updatedVariants[variantName] = {
+                ...variantData,
+                url: url || variantData.url // Fall back to existing URL if generation fails
+            };
+        }
+        return updatedVariants;
+    }
+    sortMediaFiles(files, sortBy, direction = 'asc') {
+        files.sort((a, b) => {
+            let aValue;
+            let bValue;
+            switch (sortBy) {
+                case 'name':
+                    aValue = a.filename.toLowerCase();
+                    bValue = b.filename.toLowerCase();
+                    break;
+                case 'size':
+                    aValue = a.size;
+                    bValue = b.size;
+                    break;
+                case 'date':
+                    aValue = a._createdAt;
+                    bValue = b._createdAt;
+                    break;
+                case 'type':
+                    aValue = a.contentType;
+                    bValue = b.contentType;
+                    break;
+                default:
+                    return 0;
+            }
+            let comparison = 0;
+            if (aValue < bValue)
+                comparison = -1;
+            else if (aValue > bValue)
+                comparison = 1;
+            return direction === 'desc' ? -comparison : comparison;
+        });
+    }
+}
+//# sourceMappingURL=filesystem-media-adapter.js.map