feat: asset file apis

server/src/constants.ts

@@ -139,6 +139,7 @@ export const endpointTags: Record<ApiTag, string> = {
   [ApiTag.Albums]: 'An album is a collection of assets that can be shared with other users or via shared links.',
   [ApiTag.ApiKeys]: 'An api key can be used to programmatically access the Immich API.',
   [ApiTag.Assets]: 'An asset is an image or video that has been uploaded to Immich.',
+  [ApiTag.AssetFiles]: 'An asset file is a file associated with an asset, including edited versions, thumbnails, etc.',
   [ApiTag.Authentication]: 'Endpoints related to user authentication, including OAuth.',
   [ApiTag.AuthenticationAdmin]: 'Administrative endpoints related to authentication.',
   [ApiTag.DatabaseBackups]: 'Manage backups of the Immich database.',

server/src/controllers/asset-file.controller.ts

@@ -0,0 +1,72 @@
+import { Controller, Delete, Get, HttpCode, HttpStatus, Next, Param, Query, Res } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { NextFunction, Response } from 'express';
+import { Endpoint, HistoryBuilder } from 'src/decorators';
+import { AssetFileResponseDto, AssetFileSearchDto } from 'src/dtos/asset-file.dto';
+import { AuthDto } from 'src/dtos/auth.dto';
+import { ApiTag, Permission } from 'src/enum';
+import { Auth, Authenticated, FileResponse } from 'src/middleware/auth.guard';
+import { LoggingRepository } from 'src/repositories/logging.repository';
+import { AssetFileService } from 'src/services/asset-file.service';
+import { sendFile } from 'src/utils/file';
+import { UUIDParamDto } from 'src/validation';
+
+@ApiTags(ApiTag.AssetFiles)
+@Controller('asset-files')
+export class AssetFilesController {
+  constructor(
+    private service: AssetFileService,
+    private logger: LoggingRepository,
+  ) {}
+
+  @Get()
+  @Authenticated({ permission: Permission.AssetFileRead })
+  @Endpoint({
+    summary: 'Retrieve an asset file',
+    description: 'Returns a metadata about a specific asset file.',
+    history: new HistoryBuilder().added('v2.6.0').beta('v2.6.0'),
+  })
+  searchAssetFiles(@Auth() auth: AuthDto, @Query() dto: AssetFileSearchDto): Promise<AssetFileResponseDto[]> {
+    return this.service.search(auth, dto);
+  }
+
+  @Get(':id')
+  @Authenticated({ permission: Permission.AssetFileRead })
+  @Endpoint({
+    summary: 'Retrieve an asset file',
+    description: 'Returns a metadata about a specific asset file.',
+    history: new HistoryBuilder().added('v2.6.0').beta('v2.6.0'),
+  })
+  getAssetFile(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<AssetFileResponseDto> {
+    return this.service.get(auth, id);
+  }
+
+  @Delete(':id')
+  @Authenticated({ permission: Permission.AssetFileDelete })
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @Endpoint({
+    summary: 'Delete an asset file',
+    description: 'Delete a file and remove it from the database.',
+    history: new HistoryBuilder().added('v2.6.0').beta('v2.6.0'),
+  })
+  deleteAssetFile(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise<void> {
+    return this.service.delete(auth, id);
+  }
+
+  @Get(':id/download')
+  @FileResponse()
+  @Authenticated({ permission: Permission.AssetFileDownload })
+  @Endpoint({
+    summary: 'Download an asset file',
+    description: 'Serve the contents of a specific asset file.',
+    history: new HistoryBuilder().added('v2.6.0').beta('v2.6.0'),
+  })
+  async downloadAssetFile(
+    @Auth() auth: AuthDto,
+    @Param() { id }: UUIDParamDto,
+    @Res() res: Response,
+    @Next() next: NextFunction,
+  ) {
+    await sendFile(res, next, () => this.service.download(auth, id), this.logger);
+  }
+}

server/src/controllers/index.ts

@@ -2,6 +2,7 @@ import { ActivityController } from 'src/controllers/activity.controller';
 import { AlbumController } from 'src/controllers/album.controller';
 import { ApiKeyController } from 'src/controllers/api-key.controller';
 import { AppController } from 'src/controllers/app.controller';
+import { AssetFilesController } from 'src/controllers/asset-file.controller';
 import { AssetMediaController } from 'src/controllers/asset-media.controller';
 import { AssetController } from 'src/controllers/asset.controller';
 import { AuthAdminController } from 'src/controllers/auth-admin.controller';
@@ -44,6 +45,7 @@ export const controllers = [
   AlbumController,
   AppController,
   AssetController,
+  AssetFilesController,
   AssetMediaController,
   AuthController,
   AuthAdminController,

server/src/dtos/asset-file.dto.ts

@@ -0,0 +1,54 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Selectable } from 'kysely';
+import { AssetFileType } from 'src/enum';
+import { AssetFileTable } from 'src/schema/tables/asset-file.table';
+import { ValidateBoolean, ValidateEnum, ValidateUUID } from 'src/validation';
+
+export class AssetFileSearchDto {
+  @ValidateUUID({ description: 'Asset ID to filter files by' })
+  assetId!: string;
+
+  @ValidateEnum({ enum: AssetFileType, name: 'AssetFileType', optional: true, description: 'Filter by type of file' })
+  type?: AssetFileType;
+
+  @ValidateBoolean({ optional: true, description: 'The file was generated from an edit' })
+  isEdited?: boolean;
+
+  @ValidateBoolean({ optional: true, description: 'The file is a progressively encoded JPEG' })
+  isProgressive?: boolean;
+}
+
+export class AssetFileResponseDto {
+  @ApiProperty({ description: 'Asset file ID' })
+  id!: string;
+  @ApiProperty({ description: 'Creation date', format: 'date-time' })
+  createdAt!: Date;
+
+  @ApiProperty({ description: 'Update date', format: 'date-time' })
+  updatedAt!: Date;
+
+  @ValidateEnum({ enum: AssetFileType, name: 'AssetFileType', description: 'Type of file' })
+  type!: AssetFileType;
+
+  @ApiProperty({ description: 'File path' })
+  path!: string;
+
+  @ApiProperty({ description: 'The file was generated from an edit' })
+  isEdited!: boolean;
+
+  @ApiProperty({ description: 'The file is a progressively encoded JPEG' })
+  isProgressive!: boolean;
+}
+
+export const mapAssetFile = (file: Selectable<AssetFileTable>): AssetFileResponseDto => {
+  return {
+    id: file.id,
+    // assetId: file.assetId,
+    createdAt: file.createdAt,
+    updatedAt: file.updatedAt,
+    type: file.type,
+    path: file.path,
+    isEdited: file.isEdited,
+    isProgressive: file.isProgressive,
+  };
+};

server/src/enum.ts

@@ -108,6 +108,10 @@ export enum Permission {
   AssetCopy = 'asset.copy',
   AssetDerive = 'asset.derive',
 
+  AssetFileRead = 'assetFile.read',
+  AssetFileDelete = 'assetFile.delete',
+  AssetFileDownload = 'assetFile.download',
+
   AssetEditGet = 'asset.edit.get',
   AssetEditCreate = 'asset.edit.create',
   AssetEditDelete = 'asset.edit.delete',
@@ -852,6 +856,7 @@ export enum ApiTag {
   Authentication = 'Authentication',
   AuthenticationAdmin = 'Authentication (admin)',
   Assets = 'Assets',
+  AssetFiles = 'Asset files',
   DatabaseBackups = 'Database Backups (admin)',
   Deprecated = 'Deprecated',
   Download = 'Download',

server/src/repositories/access.repository.ts

@@ -265,6 +265,28 @@ class AssetAccess {
   }
 }
 
+class AssetFileAccess {
+  constructor(private db: Kysely<DB>) {}
+
+  @GenerateSql({ params: [DummyValue.UUID, DummyValue.UUID_SET] })
+  @ChunkedSet({ paramIndex: 1 })
+  async checkOwnerAccess(userId: string, fileIds: Set<string>, hasElevatedPermission: boolean | undefined) {
+    if (fileIds.size === 0) {
+      return new Set<string>();
+    }
+
+    return this.db
+      .selectFrom('asset_file')
+      .select('asset_file.id')
+      .innerJoin('asset', 'asset.id', 'asset_file.assetId')
+      .$if(!hasElevatedPermission, (eb) => eb.where('asset.visibility', '!=', AssetVisibility.Locked))
+      .where('asset.ownerId', '=', userId)
+      .where('asset_file.id', 'in', [...fileIds])
+      .execute()
+      .then((files) => new Set(files.map(({ id }) => id)));
+  }
+}
+
 class AuthDeviceAccess {
   constructor(private db: Kysely<DB>) {}
 
@@ -487,6 +509,7 @@ export class AccessRepository {
   activity: ActivityAccess;
   album: AlbumAccess;
   asset: AssetAccess;
+  assetFile: AssetFileAccess;
   authDevice: AuthDeviceAccess;
   memory: MemoryAccess;
   notification: NotificationAccess;
@@ -502,6 +525,7 @@ export class AccessRepository {
     this.activity = new ActivityAccess(db);
     this.album = new AlbumAccess(db);
     this.asset = new AssetAccess(db);
+    this.assetFile = new AssetFileAccess(db);
     this.authDevice = new AuthDeviceAccess(db);
     this.memory = new MemoryAccess(db);
     this.notification = new NotificationAccess(db);

server/src/repositories/asset-file.repository.ts

@@ -0,0 +1,30 @@
+import { Injectable } from '@nestjs/common';
+import { Kysely } from 'kysely';
+import { InjectKysely } from 'nestjs-kysely';
+import { AssetFileSearchDto } from 'src/dtos/asset-file.dto';
+import { DB } from 'src/schema';
+
+@Injectable()
+export class AssetFileRepository {
+  constructor(@InjectKysely() private db: Kysely<DB>) {}
+
+  get(id: string) {
+    return this.db.selectFrom('asset_file').where('id', '=', id).selectAll().executeTakeFirst();
+  }
+
+  getByAssetId(dto: AssetFileSearchDto) {
+    return this.db
+      .selectFrom('asset_file')
+      .where('assetId', '=', dto.assetId)
+      .$if(dto.type !== undefined, (qb) => qb.where('type', '=', dto.type!))
+      .$if(dto.isEdited !== undefined, (qb) => qb.where('isEdited', '=', dto.isEdited!))
+      .$if(dto.isProgressive !== undefined, (qb) => qb.where('isProgressive', '=', dto.isProgressive!))
+      .selectAll()
+      .execute();
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const { numDeletedRows } = await this.db.deleteFrom('asset_file').where('id', '=', id).executeTakeFirst();
+    return Number(numDeletedRows) === 1;
+  }
+}

server/src/repositories/index.ts

@@ -5,6 +5,7 @@ import { AlbumRepository } from 'src/repositories/album.repository';
 import { ApiKeyRepository } from 'src/repositories/api-key.repository';
 import { AppRepository } from 'src/repositories/app.repository';
 import { AssetEditRepository } from 'src/repositories/asset-edit.repository';
+import { AssetFileRepository } from 'src/repositories/asset-file.repository';
 import { AssetJobRepository } from 'src/repositories/asset-job.repository';
 import { AssetRepository } from 'src/repositories/asset.repository';
 import { AuditRepository } from 'src/repositories/audit.repository';
@@ -61,6 +62,7 @@ export const repositories = [
   AppRepository,
   AssetRepository,
   AssetEditRepository,
+  AssetFileRepository,
   AssetJobRepository,
   ConfigRepository,
   CronRepository,

server/src/services/asset-file.service.ts

@@ -0,0 +1,48 @@
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { AssetFileResponseDto, AssetFileSearchDto, mapAssetFile } from 'src/dtos/asset-file.dto';
+import { AuthDto } from 'src/dtos/auth.dto';
+import { CacheControl, Permission } from 'src/enum';
+import { BaseService } from 'src/services/base.service';
+import { getFilenameExtension, getFileNameWithoutExtension, ImmichFileResponse } from 'src/utils/file';
+import { mimeTypes } from 'src/utils/mime-types';
+
+@Injectable()
+export class AssetFileService extends BaseService {
+  async search(auth: AuthDto, dto: AssetFileSearchDto): Promise<AssetFileResponseDto[]> {
+    await this.requireAccess({ auth, permission: Permission.AssetRead, ids: [dto.assetId] });
+    const files = await this.assetFileRepository.getByAssetId(dto);
+    return files.map((file) => mapAssetFile(file));
+  }
+
+  async get(auth: AuthDto, id: string): Promise<AssetFileResponseDto> {
+    await this.requireAccess({ auth, permission: Permission.AssetFileRead, ids: [id] });
+    const file = await this.findOrFail(id);
+    return mapAssetFile(file);
+  }
+
+  async download(auth: AuthDto, id: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetFileDownload, ids: [id] });
+    const file = await this.findOrFail(id);
+
+    return new ImmichFileResponse({
+      path: file.path,
+      fileName: getFileNameWithoutExtension(file.path) + getFilenameExtension(file.path),
+      contentType: mimeTypes.lookup(file.path),
+      cacheControl: CacheControl.PrivateWithCache,
+    });
+  }
+
+  async delete(auth: AuthDto, id: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetFileDelete, ids: [id] });
+
+    await this.assetFileRepository.delete(id);
+  }
+
+  private async findOrFail(id: string) {
+    const file = await this.assetFileRepository.get(id);
+    if (!file) {
+      throw new BadRequestException('Asset file not found');
+    }
+    return file;
+  }
+}

server/src/services/base.service.ts

@@ -12,6 +12,7 @@ import { AlbumRepository } from 'src/repositories/album.repository';
 import { ApiKeyRepository } from 'src/repositories/api-key.repository';
 import { AppRepository } from 'src/repositories/app.repository';
 import { AssetEditRepository } from 'src/repositories/asset-edit.repository';
+import { AssetFileRepository } from 'src/repositories/asset-file.repository';
 import { AssetJobRepository } from 'src/repositories/asset-job.repository';
 import { AssetRepository } from 'src/repositories/asset.repository';
 import { AuditRepository } from 'src/repositories/audit.repository';
@@ -130,6 +131,7 @@ export class BaseService {
     protected appRepository: AppRepository,
     protected assetRepository: AssetRepository,
     protected assetEditRepository: AssetEditRepository,
+    protected assetFileRepository: AssetFileRepository,
     protected assetJobRepository: AssetJobRepository,
     protected auditRepository: AuditRepository,
     protected configRepository: ConfigRepository,

server/src/services/index.ts

@@ -2,6 +2,7 @@ import { ActivityService } from 'src/services/activity.service';
 import { AlbumService } from 'src/services/album.service';
 import { ApiKeyService } from 'src/services/api-key.service';
 import { ApiService } from 'src/services/api.service';
+import { AssetFileService } from 'src/services/asset-file.service';
 import { AssetMediaService } from 'src/services/asset-media.service';
 import { AssetService } from 'src/services/asset.service';
 import { AuditService } from 'src/services/audit.service';
@@ -55,6 +56,7 @@ export const services = [
   ApiService,
   AssetMediaService,
   AssetService,
+  AssetFileService,
   AuditService,
   AuthService,
   AuthAdminService,

server/src/utils/access.ts

@@ -131,6 +131,10 @@ const checkOtherAccess = async (access: AccessRepository, request: OtherAccessRe
       return setUnion(isOwner, isPartner);
     }
 
+    case Permission.AssetFileDownload: {
+      return access.assetFile.checkOwnerAccess(auth.user.id, ids, auth.session?.hasElevatedPermission);
+    }
+
     case Permission.AssetView: {
       const isOwner = await access.asset.checkOwnerAccess(auth.user.id, ids, auth.session?.hasElevatedPermission);
       const isAlbum = await access.asset.checkAlbumAccess(auth.user.id, setDifference(ids, isOwner));
@@ -169,6 +173,11 @@ const checkOtherAccess = async (access: AccessRepository, request: OtherAccessRe
       return await access.asset.checkOwnerAccess(auth.user.id, ids, auth.session?.hasElevatedPermission);
     }
 
+    case Permission.AssetFileRead:
+    case Permission.AssetFileDelete: {
+      return await access.assetFile.checkOwnerAccess(auth.user.id, ids, auth.session?.hasElevatedPermission);
+    }
+
     case Permission.AlbumRead: {
       const isOwner = await access.album.checkOwnerAccess(auth.user.id, ids);
       const isShared = await access.album.checkSharedAlbumAccess(

server/test/medium.factory.ts

@@ -20,6 +20,7 @@ import { ActivityRepository } from 'src/repositories/activity.repository';
 import { AlbumUserRepository } from 'src/repositories/album-user.repository';
 import { AlbumRepository } from 'src/repositories/album.repository';
 import { AssetEditRepository } from 'src/repositories/asset-edit.repository';
+import { AssetFileRepository } from 'src/repositories/asset-file.repository';
 import { AssetJobRepository } from 'src/repositories/asset-job.repository';
 import { AssetRepository } from 'src/repositories/asset.repository';
 import { ConfigRepository } from 'src/repositories/config.repository';
@@ -386,6 +387,7 @@ const newRealRepository = <T>(key: ClassConstructor<T>, db: Kysely<DB>): T => {
     case ActivityRepository:
     case AssetRepository:
     case AssetEditRepository:
+    case AssetFileRepository:
     case AssetJobRepository:
     case MemoryRepository:
     case NotificationRepository:

server/test/utils.ts

@@ -21,6 +21,7 @@ import { AlbumRepository } from 'src/repositories/album.repository';
 import { ApiKeyRepository } from 'src/repositories/api-key.repository';
 import { AppRepository } from 'src/repositories/app.repository';
 import { AssetEditRepository } from 'src/repositories/asset-edit.repository';
+import { AssetFileRepository } from 'src/repositories/asset-file.repository';
 import { AssetJobRepository } from 'src/repositories/asset-job.repository';
 import { AssetRepository } from 'src/repositories/asset.repository';
 import { AuditRepository } from 'src/repositories/audit.repository';
@@ -218,6 +219,7 @@ export type ServiceOverrides = {
   audit: AuditRepository;
   asset: AssetRepository;
   assetEdit: AssetEditRepository;
+  assetFile: AssetFileRepository;
   assetJob: AssetJobRepository;
   config: ConfigRepository;
   cron: CronRepository;
@@ -292,6 +294,7 @@ export const getMocks = () => {
     albumUser: automock(AlbumUserRepository),
     asset: newAssetRepositoryMock(),
     assetEdit: automock(AssetEditRepository),
+    assetFile: automock(AssetFileRepository),
     assetJob: automock(AssetJobRepository),
     app: automock(AppRepository, { strict: false }),
     config: newConfigRepositoryMock(),
@@ -360,6 +363,7 @@ export const newTestService = <T extends BaseService>(
     overrides.app || (mocks.app as As<AppRepository>),
     overrides.asset || (mocks.asset as As<AssetRepository>),
     overrides.assetEdit || (mocks.assetEdit as As<AssetEditRepository>),
+    overrides.assetFile || (mocks.assetFile as As<AssetFileRepository>),
     overrides.assetJob || (mocks.assetJob as As<AssetJobRepository>),
     overrides.audit || (mocks.audit as As<AuditRepository>),
     overrides.config || (mocks.config as As<ConfigRepository> as ConfigRepository),