feat: asset file apis (#25900)

* feat: asset file endpoints

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

Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>

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

Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>

---------

Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>

server/src/constants.ts

@@ -148,6 +148,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.ClusterGroups]:

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: 'Search asset files',
+    description: 'Returns all matching asset files.',
+    history: new HistoryBuilder().added('v3.2.0').alpha('v3.2.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 metadata about a specific asset file.',
+    history: new HistoryBuilder().added('v3.2.0').alpha('v3.2.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('v3.2.0').alpha('v3.2.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('v3.2.0').alpha('v3.2.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';
@@ -50,6 +51,7 @@ export const controllers = [
   AlbumController,
   AppController,
   AssetController,
+  AssetFilesController,
   AssetMediaController,
   AuthController,
   AuthAdminController,

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

@@ -0,0 +1,45 @@
+import { Selectable } from 'kysely';
+import { createZodDto } from 'nestjs-zod';
+import { AssetFileTypeSchema } from 'src/enum';
+import { AssetFileTable } from 'src/schema/tables/asset-file.table';
+import { isoDatetimeToDate, stringToBool } from 'src/validation';
+import z from 'zod';
+
+const AssetFileSearchSchema = z
+  .object({
+    assetId: z.uuidv4().describe('Asset ID to filter files by'),
+    type: AssetFileTypeSchema.optional().describe('Filter by type of file'),
+    isEdited: stringToBool.optional().describe('The file was generated from an edit'),
+    isProgressive: stringToBool.optional().describe('The file is a progressively encoded JPEG'),
+    isTransparent: stringToBool.optional().describe('The file is transparent'),
+  })
+  .meta({ id: 'AssetFileSearchDto' });
+
+const AssetFileResponseSchema = z
+  .object({
+    id: z.uuidv4().describe('Asset file ID'),
+    createdAt: isoDatetimeToDate.describe('Creation date'),
+    updatedAt: isoDatetimeToDate.describe('Update date'),
+    type: AssetFileTypeSchema.describe('Type of file'),
+    path: z.string().describe('File path'),
+    isEdited: z.boolean().describe('The file was generated from an edit'),
+    isProgressive: z.boolean().describe('The file is a progressively encoded JPEG'),
+    isTransparent: z.boolean().describe('The file is transparent'),
+  })
+  .meta({ id: 'AssetFileResponseDto' });
+
+export class AssetFileSearchDto extends createZodDto(AssetFileSearchSchema) {}
+export class AssetFileResponseDto extends createZodDto(AssetFileResponseSchema) {}
+
+export const mapAssetFile = (file: Selectable<AssetFileTable>): AssetFileResponseDto => {
+  return {
+    id: file.id,
+    createdAt: file.createdAt,
+    updatedAt: file.updatedAt,
+    type: file.type,
+    path: file.path,
+    isEdited: file.isEdited,
+    isProgressive: file.isProgressive,
+    isTransparent: file.isTransparent,
+  };
+};

server/src/enum.ts

@@ -62,6 +62,8 @@ export enum AssetFileType {
   EncodedVideo = 'encoded_video',
 }
 
+export const AssetFileTypeSchema = z.enum(AssetFileType).describe('Type of file').meta({ id: 'AssetFileType' });
+
 export enum AlbumUserRole {
   Editor = 'editor',
   Owner = 'owner',
@@ -131,6 +133,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',
@@ -1203,6 +1209,7 @@ export enum ApiTag {
   Authentication = 'Authentication',
   AuthenticationAdmin = 'Authentication (admin)',
   Assets = 'Assets',
+  AssetFiles = 'Asset files',
   ConfigUser = 'Config (user)',
   ConfigAdmin = 'Config (admin)',
   ConfigPublic = 'Config (public)',

server/src/queries/access.repository.sql

@@ -149,6 +149,17 @@ where
     "albumAssets"."livePhotoVideoId"
   ] && array[$2]::uuid[]
 
+-- AccessRepository.assetFile.checkOwnerAccess
+select
+  "asset_file"."id"
+from
+  "asset_file"
+  inner join "asset" on "asset"."id" = "asset_file"."assetId"
+where
+  "asset"."visibility" != $1
+  and "asset"."ownerId" = $2
+  and "asset_file"."id" in ($3)
+
 -- AccessRepository.authDevice.checkOwnerAccess
 select
   "session"."id"

server/src/repositories/access.repository.ts

@@ -278,6 +278,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>) {}
 
@@ -596,6 +618,7 @@ export class AccessRepository {
   activity: ActivityAccess;
   album: AlbumAccess;
   asset: AssetAccess;
+  assetFile: AssetFileAccess;
   authDevice: AuthDeviceAccess;
   duplicate: DuplicateAccess;
   memory: MemoryAccess;
@@ -614,6 +637,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.duplicate = new DuplicateAccess(db);
     this.memory = new MemoryAccess(db);

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

@@ -0,0 +1,31 @@
+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();
+  }
+
+  search(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!))
+      .$if(dto.isTransparent !== undefined, (qb) => qb.where('isTransparent', '=', dto.isTransparent!))
+      .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 { ClusterGroupRepository } from 'src/repositories/cluster-group.repository';
@@ -62,6 +63,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 { AssetFileType, CacheControl, JobName, 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';
+import { findOrFail } from 'src/utils/misc';
+
+@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.search(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 findOrFail(() => this.assetFileRepository.get(id), 'Asset file');
+    return mapAssetFile(file);
+  }
+
+  async download(auth: AuthDto, id: string) {
+    await this.requireAccess({ auth, permission: Permission.AssetFileDownload, ids: [id] });
+    const file = await findOrFail(() => this.assetFileRepository.get(id), 'Asset file');
+
+    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] });
+
+    const file = await findOrFail(() => this.assetFileRepository.get(id), 'Asset file');
+    // TODO consider implications of allowing sidecar files to be deleted
+    if (file.type === AssetFileType.Sidecar) {
+      throw new BadRequestException('Sidecar files cannot be deleted');
+    }
+
+    await this.assetFileRepository.delete(id);
+    await this.jobRepository.queue({ name: JobName.FileDelete, data: { files: [file.path] } });
+  }
+}

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 { ClusterGroupRepository } from 'src/repositories/cluster-group.repository';
@@ -74,6 +75,7 @@ export const BASE_SERVICE_DEPENDENCIES = [
   AppRepository,
   AssetRepository,
   AssetEditRepository,
+  AssetFileRepository,
   AssetJobRepository,
   ClusterGroupRepository,
   ConfigRepository,
@@ -135,6 +137,7 @@ export class BaseService {
     protected appRepository: AppRepository,
     protected assetRepository: AssetRepository,
     protected assetEditRepository: AssetEditRepository,
+    protected assetFileRepository: AssetFileRepository,
     protected assetJobRepository: AssetJobRepository,
     protected clusterGroupRepository: ClusterGroupRepository,
     protected configRepository: ConfigRepository,
@@ -205,6 +208,7 @@ export class BaseService {
       ctx.appRepository,
       ctx.assetRepository,
       ctx.assetEditRepository,
+      ctx.assetFileRepository,
       ctx.assetJobRepository,
       ctx.clusterGroupRepository,
       ctx.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 { AuthAdminService } from 'src/services/auth-admin.service';
@@ -56,6 +57,7 @@ export const services = [
   ActivityService,
   AlbumService,
   ApiService,
+  AssetFileService,
   AssetMediaService,
   AssetService,
   AuthService,

server/src/utils/access.ts

@@ -126,6 +126,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));
@@ -164,6 +168,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

@@ -24,6 +24,7 @@ import { AlbumUserRepository } from 'src/repositories/album-user.repository';
 import { AlbumRepository } from 'src/repositories/album.repository';
 import { ApiKeyRepository } from 'src/repositories/api-key.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 { ClusterGroupRepository } from 'src/repositories/cluster-group.repository';
@@ -467,6 +468,7 @@ const newRealRepository = <T extends BaseServiceDeps[number]>(key: T, db: Kysely
     case ApiKeyRepository:
     case AssetRepository:
     case AssetEditRepository:
+    case AssetFileRepository:
     case AssetJobRepository:
     case ClusterGroupRepository:
     case DuplicateRepository:

server/test/repositories/access.repository.mock.ts

@@ -33,6 +33,10 @@ export const newAccessRepositoryMock = (): IAccessRepositoryMock => {
       checkSharedLinkAccess: vitest.fn().mockResolvedValue(new Set()),
     },
 
+    assetFile: {
+      checkOwnerAccess: vitest.fn().mockResolvedValue(new Set()),
+    },
+
     album: {
       checkOwnerAccess: vitest.fn().mockResolvedValue(new Set()),
       checkSharedAlbumAccess: vitest.fn().mockResolvedValue(new Set()),

server/test/utils.ts

@@ -24,6 +24,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 { ClusterGroupRepository } from 'src/repositories/cluster-group.repository';
@@ -239,6 +240,7 @@ export type ServiceOverrides = {
   app: AppRepository;
   asset: AssetRepository;
   assetEdit: AssetEditRepository;
+  assetFile: AssetFileRepository;
   assetJob: AssetJobRepository;
   clusterGroup: ClusterGroupRepository;
   config: ConfigRepository;
@@ -323,6 +325,7 @@ export const getMocks = () => {
     albumUser: automock(AlbumUserRepository),
     asset: newAssetRepositoryMock(),
     assetEdit: automock(AssetEditRepository),
+    assetFile: automock(AssetFileRepository),
     assetJob: automock(AssetJobRepository),
     clusterGroup: automock(ClusterGroupRepository),
     app: automock(AppRepository, { strict: false }),
@@ -397,6 +400,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.clusterGroup || (mocks.clusterGroup as As<ClusterGroupRepository>),
     overrides.config || (mocks.config as As<ConfigRepository> as ConfigRepository),