feat(server): start up folder checks (#12401)

server/src/services/storage.service.spec.ts

@@ -1,19 +1,29 @@
+import { SystemMetadataKey } from 'src/enum';
+import { IDatabaseRepository } from 'src/interfaces/database.interface';
 import { ILoggerRepository } from 'src/interfaces/logger.interface';
 import { IStorageRepository } from 'src/interfaces/storage.interface';
+import { ISystemMetadataRepository } from 'src/interfaces/system-metadata.interface';
 import { StorageService } from 'src/services/storage.service';
+import { newDatabaseRepositoryMock } from 'test/repositories/database.repository.mock';
 import { newLoggerRepositoryMock } from 'test/repositories/logger.repository.mock';
 import { newStorageRepositoryMock } from 'test/repositories/storage.repository.mock';
+import { newSystemMetadataRepositoryMock } from 'test/repositories/system-metadata.repository.mock';
 import { Mocked } from 'vitest';
 
 describe(StorageService.name, () => {
   let sut: StorageService;
+  let databaseMock: Mocked<IDatabaseRepository>;
   let storageMock: Mocked<IStorageRepository>;
   let loggerMock: Mocked<ILoggerRepository>;
+  let systemMock: Mocked<ISystemMetadataRepository>;
 
   beforeEach(() => {
+    databaseMock = newDatabaseRepositoryMock();
     storageMock = newStorageRepositoryMock();
     loggerMock = newLoggerRepositoryMock();
-    sut = new StorageService(storageMock, loggerMock);
+    systemMock = newSystemMetadataRepositoryMock();
+
+    sut = new StorageService(databaseMock, storageMock, loggerMock, systemMock);
   });
 
   it('should work', () => {
@@ -21,9 +31,35 @@ describe(StorageService.name, () => {
   });
 
   describe('onBootstrap', () => {
-    it('should create the library folder on initialization', () => {
-      sut.onBootstrap();
+    it('should enable mount folder checking', async () => {
+      systemMock.get.mockResolvedValue(null);
+
+      await expect(sut.onBootstrap()).resolves.toBeUndefined();
+
+      expect(systemMock.set).toHaveBeenCalledWith(SystemMetadataKey.SYSTEM_FLAGS, { mountFiles: true });
+      expect(storageMock.mkdirSync).toHaveBeenCalledWith('upload/encoded-video');
       expect(storageMock.mkdirSync).toHaveBeenCalledWith('upload/library');
+      expect(storageMock.mkdirSync).toHaveBeenCalledWith('upload/profile');
+      expect(storageMock.mkdirSync).toHaveBeenCalledWith('upload/thumbs');
+    });
+
+    it('should throw an error if .immich is missing', async () => {
+      systemMock.get.mockResolvedValue({ mountFiles: true });
+      storageMock.readFile.mockRejectedValue(new Error("ENOENT: no such file or directory, open '/app/.immich'"));
+
+      await expect(sut.onBootstrap()).rejects.toThrow('Failed to validate folder mount');
+
+      expect(storageMock.writeFile).not.toHaveBeenCalled();
+      expect(systemMock.set).not.toHaveBeenCalled();
+    });
+
+    it('should throw an error if .immich is present but read-only', async () => {
+      systemMock.get.mockResolvedValue({ mountFiles: true });
+      storageMock.writeFile.mockRejectedValue(new Error("ENOENT: no such file or directory, open '/app/.immich'"));
+
+      await expect(sut.onBootstrap()).rejects.toThrow('Failed to validate folder mount');
+
+      expect(systemMock.set).not.toHaveBeenCalled();
     });
   });
 

server/src/services/storage.service.ts

@@ -1,23 +1,52 @@
 import { Inject, Injectable } from '@nestjs/common';
+import { join } from 'node:path';
 import { StorageCore, StorageFolder } from 'src/cores/storage.core';
 import { OnEmit } from 'src/decorators';
+import { SystemMetadataKey } from 'src/enum';
+import { DatabaseLock, IDatabaseRepository } from 'src/interfaces/database.interface';
 import { IDeleteFilesJob, JobStatus } from 'src/interfaces/job.interface';
 import { ILoggerRepository } from 'src/interfaces/logger.interface';
 import { IStorageRepository } from 'src/interfaces/storage.interface';
+import { ISystemMetadataRepository } from 'src/interfaces/system-metadata.interface';
+import { ImmichStartupError } from 'src/utils/events';
 
 @Injectable()
 export class StorageService {
   constructor(
+    @Inject(IDatabaseRepository) private databaseRepository: IDatabaseRepository,
     @Inject(IStorageRepository) private storageRepository: IStorageRepository,
     @Inject(ILoggerRepository) private logger: ILoggerRepository,
+    @Inject(ISystemMetadataRepository) private systemMetadata: ISystemMetadataRepository,
   ) {
     this.logger.setContext(StorageService.name);
   }
 
   @OnEmit({ event: 'app.bootstrap' })
-  onBootstrap() {
-    const libraryBase = StorageCore.getBaseFolder(StorageFolder.LIBRARY);
-    this.storageRepository.mkdirSync(libraryBase);
+  async onBootstrap() {
+    await this.databaseRepository.withLock(DatabaseLock.SystemFileMounts, async () => {
+      const flags = (await this.systemMetadata.get(SystemMetadataKey.SYSTEM_FLAGS)) || { mountFiles: false };
+
+      this.logger.log('Verifying system mount folder checks');
+
+      // check each folder exists and is writable
+      for (const folder of Object.values(StorageFolder)) {
+        if (!flags.mountFiles) {
+          this.logger.log(`Writing initial mount file for the ${folder} folder`);
+          await this.verifyWriteAccess(folder);
+        }
+
+        await this.verifyReadAccess(folder);
+        await this.verifyWriteAccess(folder);
+      }
+
+      if (!flags.mountFiles) {
+        flags.mountFiles = true;
+        await this.systemMetadata.set(SystemMetadataKey.SYSTEM_FLAGS, flags);
+        this.logger.log('Successfully enabled system mount folders checks');
+      }
+
+      this.logger.log('Successfully verified system mount folder checks');
+    });
   }
 
   async handleDeleteFiles(job: IDeleteFilesJob) {
@@ -38,4 +67,38 @@ export class StorageService {
 
     return JobStatus.SUCCESS;
   }
+
+  private async verifyReadAccess(folder: StorageFolder) {
+    const { filePath } = this.getMountFilePaths(folder);
+    try {
+      await this.storageRepository.readFile(filePath);
+    } catch (error) {
+      this.logger.error(`Failed to read ${filePath}: ${error}`);
+      this.logger.error(
+        `The "${folder}" folder appears to be offline/missing, please make sure the volume is mounted with the correct permissions`,
+      );
+      throw new ImmichStartupError(`Failed to validate folder mount (read from "<MEDIA_LOCATION>/${folder}")`);
+    }
+  }
+
+  private async verifyWriteAccess(folder: StorageFolder) {
+    const { folderPath, filePath } = this.getMountFilePaths(folder);
+    try {
+      this.storageRepository.mkdirSync(folderPath);
+      await this.storageRepository.writeFile(filePath, Buffer.from(`${Date.now()}`));
+    } catch (error) {
+      this.logger.error(`Failed to write ${filePath}: ${error}`);
+      this.logger.error(
+        `The "${folder}" folder cannot be written to, please make sure the volume is mounted with the correct permissions`,
+      );
+      throw new ImmichStartupError(`Failed to validate folder mount (write to "<MEDIA_LOCATION>/${folder}")`);
+    }
+  }
+
+  private getMountFilePaths(folder: StorageFolder) {
+    const folderPath = StorageCore.getBaseFolder(folder);
+    const filePath = join(folderPath, '.immich');
+
+    return { folderPath, filePath };
+  }
 }