Skip to content

High performance self-hosted photo and video management solution.

33.2 KB
Raw Blame
import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
import { Insertable } from 'kysely';
import { isUndefined, omitBy } from 'lodash-es';
import type { JobItem, JobOf } from 'src/types.js';
import { Chunked, OnJob } from 'src/decorators.js';
import { BulkIdErrorReason, BulkIdResponseDto } from 'src/dtos/asset-ids.response.dto.js';
import { AuthDto } from 'src/dtos/auth.dto.js';
import {
  AssetFaceCreateDto,
  AssetFaceDeleteDto,
  AssetFaceResponseDto,
  AssetFaceUpdateDto,
  FaceDto,
  MergePersonDto,
  PeopleDeleteDto,
  PeopleResponseDto,
  PeopleUpdateDto,
  PeopleUsersUpsertDto,
  PersonCreateDto,
  PersonDeleteDto,
  PersonResponseDto,
  PersonSearchDto,
  PersonStatisticsResponseDto,
  PersonUpdateDto,
  PersonUsersDeleteDto,
  PersonUsersResponseDto,
  PersonUsersSearchDto,
  mapFaces,
  mapPerson,
  mapPersonUsers,
} from 'src/dtos/person.dto.js';
import {
  AssetVisibility,
  CacheControl,
  DatabaseLock,
  JobName,
  JobStatus,
  Permission,
  PersonPathType,
  QueueName,
  SourceType,
  SystemMetadataKey,
  VectorIndex,
} from 'src/enum.js';
import { BoundingBox } from 'src/repositories/machine-learning.repository.js';
import { PersonId } from 'src/repositories/person.repository.js';
import { DB } from 'src/schema/index.js';
import { AssetFaceTable } from 'src/schema/tables/asset-face.table.js';
import { FaceSearchTable } from 'src/schema/tables/face-search.table.js';
import { PersonUserTable } from 'src/schema/tables/person-user.table.js';
import { BaseService } from 'src/services/base.service.js';
import { getDimensions, getMyPartnerIds } from 'src/utils/asset.util.js';
import { ImmichFileResponse } from 'src/utils/file.js';
import { isHttpException } from 'src/utils/logger.js';
import { mimeTypes } from 'src/utils/mime-types.js';
import { batched, findOrFail, hasSomeDefined, isFacialRecognitionEnabled } from 'src/utils/misc.js';
import { Point, transformPoints } from 'src/utils/transform.js';

const personKey = ({ ownerId, personGroupId }: PersonId) => `${ownerId}/${personGroupId}`;

@Injectable()
export class PersonService extends BaseService {
  async getAll(auth: AuthDto, dto: PersonSearchDto): Promise<PeopleResponseDto> {
    const { withHidden = false, closestAssetId, closestPersonId, page, size, ...filters } = dto;
    const pagination = {
      take: size,
      skip: (page - 1) * size,
    };
    const partnerIds = await getMyPartnerIds({
      userId: auth.user.id,
      repository: this.partnerRepository,
    });
    const { items, hasNextPage, total, hidden } = await this.personRepository.getAllForUser(pagination, auth.user.id, {
      withHidden,
      partnerIds,
      closestFaceAssetId: closestAssetId,
      closestPersonId,
      ...filters,
    });

    return {
      people: items.map((person) => mapPerson(person)),
      hasNextPage,
      total,
      hidden,
    };
  }

  async reassignFaces(auth: AuthDto, personGroupId: string, dto: AssetFaceUpdateDto): Promise<PersonResponseDto[]> {
    const ids = dto.data.map((item) => ({ personGroupId: item.personId, ownerId: item.userId ?? auth.user.id }));

    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonUpdate,
      ids: [{ personGroupId, ownerId: auth.user.id }, ...ids],
    });

    const person = await this.findOrFail(auth, personGroupId);

    const result: PersonResponseDto[] = [];
    const changeFeaturePhoto = new Map<string, PersonId>();
    for (const data of dto.data) {
      const faces = await this.personRepository.getFacesByIds(
        [{ personGroupId: data.personId, assetId: data.assetId }],
        { viewingUserId: auth.user.id },
      );

      for (const face of faces) {
        const ids = await this.checkAccess({ auth, permission: Permission.PersonCreate, ids: [face.id] });

        if (ids.size !== 1) {
          continue;
        }

        if (person.faceAssetId === null) {
          changeFeaturePhoto.set(personKey(person), person);
        }
        if (face.person && face.person.faceAssetId === face.id) {
          changeFeaturePhoto.set(personKey(face.person), face.person);
        }

        await this.personRepository.reassignFace(face.id, person.personGroupId);
      }

      result.push(mapPerson(person));
    }
    if (changeFeaturePhoto.size > 0) {
      await this.createNewFeaturePhoto(changeFeaturePhoto.values().toArray());
    }
    return result;
  }

  async reassignFacesById(auth: AuthDto, personGroupId: string, dto: FaceDto): Promise<PersonResponseDto> {
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonUpdate,
      ids: [{ personGroupId, ownerId: auth.user.id }],
    });
    await this.requireAccess({ auth, permission: Permission.PersonCreate, ids: [dto.id] });
    const face = await this.personRepository.getFaceById(dto.id, { viewingUserId: auth.user.id });
    const person = await this.findOrFail(auth, personGroupId);

    await this.personRepository.reassignFace(face.id, person.personGroupId);
    if (person.faceAssetId === null) {
      await this.createNewFeaturePhoto([person]);
    }
    if (face.person && face.person.faceAssetId === face.id) {
      await this.createNewFeaturePhoto([face.person]);
    }

    return mapPerson(await this.findOrFail(auth, personGroupId));
  }

  async getFacesById(auth: AuthDto, dto: FaceDto): Promise<AssetFaceResponseDto[]> {
    await this.requireAccess({ auth, permission: Permission.AssetRead, ids: [dto.id] });
    const faces = await this.personRepository.getFaces(dto.id, { viewingUserId: auth.user.id, isVisible: true });
    const asset = await this.assetRepository.getForFaces(dto.id);
    const assetDimensions = getDimensions(asset);

    return faces.map((face) => mapFaces(face, asset.edits, assetDimensions));
  }

  async createNewFeaturePhoto(changeFeaturePhoto: PersonId[]) {
    this.logger.debug(
      `Changing feature photos for ${changeFeaturePhoto.length} ${changeFeaturePhoto.length > 1 ? 'people' : 'person'}`,
    );

    const jobs: JobItem[] = [];
    for (const { ownerId, personGroupId } of changeFeaturePhoto) {
      const assetFace = await this.personRepository.getRandomFace(personGroupId);

      if (!assetFace) {
        continue;
      }

      await this.personRepository.update({ ownerId, personGroupId, faceAssetId: assetFace.id });
      jobs.push({ name: JobName.PersonGenerateThumbnail, data: { ownerId, personGroupId } });
    }

    await this.jobRepository.queueAll(jobs);
  }

  async getById(auth: AuthDto, personGroupId: string): Promise<PersonResponseDto> {
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonRead,
      ids: [{ personGroupId, ownerId: auth.user.id }],
    });
    return mapPerson(
      await findOrFail(() => this.personRepository.getByGroupId({ ownerId: auth.user.id, personGroupId }), 'Person'),
    );
  }

  async getStatistics(auth: AuthDto, personGroupId: string): Promise<PersonStatisticsResponseDto> {
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonRead,
      ids: [{ personGroupId, ownerId: auth.user.id }],
    });

    const partnerIds = await getMyPartnerIds({
      userId: auth.user.id,
      repository: this.partnerRepository,
    });
    return this.personRepository.getStatistics(personGroupId, { ownerId: auth.user.id, partnerIds });
  }

  async getThumbnail(auth: AuthDto, personGroupId: string): Promise<ImmichFileResponse> {
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonRead,
      ids: [{ personGroupId, ownerId: auth.user.id }],
    });
    const personGroup = await this.personRepository.getForThumbnail({ ownerId: auth.user.id, personGroupId });
    const thumbnailPath = personGroup?.thumbnailPath || personGroup?.sharedThumbnailPath;
    if (!thumbnailPath) {
      throw new NotFoundException();
    }

    return new ImmichFileResponse({
      path: thumbnailPath,
      contentType: mimeTypes.lookup(thumbnailPath),
      cacheControl: CacheControl.PrivateWithoutCache,
    });
  }

  async create(auth: AuthDto, dto: PersonCreateDto): Promise<PersonResponseDto> {
    const group = await this.personRepository.createGroup(auth.user.id);
    const person = await this.personRepository.create({
      ownerId: auth.user.id,
      personGroupId: group.id,
      name: dto.name,
      birthDate: dto.birthDate,
      isHidden: dto.isHidden,
      isFavorite: dto.isFavorite,
      color: dto.color,
    });

    return mapPerson(person);
  }

  async update(auth: AuthDto, personGroupId: string, dto: PersonUpdateDto): Promise<PersonResponseDto> {
    const { userId: userIdOverride, name, birthDate, isHidden, featureFaceAssetId: assetId, isFavorite, color } = dto;
    const targetOwnerId = userIdOverride ?? auth.user.id;
    const hasSharedProperties = hasSomeDefined([name, birthDate]);
    const hasPersonalProperties = hasSomeDefined([isHidden, isFavorite, color, assetId]);

    if (targetOwnerId !== auth.user.id && hasPersonalProperties) {
      throw new BadRequestException('Only name and birthDate can be updated for other users');
    }

    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonUpdate,
      ids: [{ personGroupId, ownerId: targetOwnerId }],
    });

    if (!userIdOverride && hasSharedProperties) {
      await this.personRepository.updateForWritableOwners({ userId: auth.user.id, personGroupId }, { name, birthDate });
    }

    let faceId: string | undefined;

    if (assetId) {
      await this.requireAccess({ auth, permission: Permission.AssetRead, ids: [assetId] });
      const face = await this.personRepository.getForFeatureFaceUpdate({ personGroupId, assetId });
      if (!face) {
        throw new BadRequestException('Invalid assetId for feature face or asset is offline');
      }

      faceId = face.id;
    }

    const person = await this.personRepository.update({
      ownerId: targetOwnerId,
      personGroupId,
      faceAssetId: faceId,
      name,
      birthDate,
      isHidden,
      isFavorite,
      color,
    });

    if (assetId) {
      await this.jobRepository.queue({
        name: JobName.PersonGenerateThumbnail,
        data: { ownerId: targetOwnerId, personGroupId },
      });
    }

    return mapPerson(person);
  }

  delete(auth: AuthDto, id: string, dto: PersonDeleteDto): Promise<void> {
    return this.deleteAll(auth, { ids: [id], ...dto });
  }

  async updateAll(auth: AuthDto, dto: PeopleUpdateDto): Promise<BulkIdResponseDto[]> {
    const results: BulkIdResponseDto[] = [];
    for (const person of dto.people) {
      try {
        await this.update(auth, person.id, {
          isHidden: person.isHidden,
          name: person.name,
          birthDate: person.birthDate,
          featureFaceAssetId: person.featureFaceAssetId,
          isFavorite: person.isFavorite,
          userId: person.userId,
        });
        results.push({ id: person.id, success: true });
      } catch (error: Error | any) {
        if (!isHttpException(error)) {
          this.logger.error(`Unable to update ${person.id} : ${error}`, error?.stack);
        }
        results.push({ id: person.id, success: false, error: BulkIdErrorReason.UNKNOWN });
      }
    }
    return results;
  }

  async deleteAll(auth: AuthDto, { ids, userId }: PeopleDeleteDto): Promise<void> {
    const ownerId = userId ?? auth.user.id;
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonDelete,
      ids: ids.map((id) => ({ personGroupId: id, ownerId })),
    });
    await this.removeAllPersonGroups(ids, ownerId);
    await this.personRepository.deleteEmptyGroups();
  }

  @Chunked()
  private async removeAllPersonGroups(groupIds: string[], ownerId?: string) {
    if (groupIds.length === 0) {
      return;
    }

    const people = await this.personRepository.delete(groupIds, ownerId);
    await Promise.all(people.map((person) => this.storageRepository.unlink(person.thumbnailPath)));
    this.logger.debug(`Deleted ${groupIds.length} people`);
  }

  @OnJob({ name: JobName.PersonCleanup, queue: QueueName.BackgroundTask })
  async handlePersonCleanup(): Promise<JobStatus> {
    // each step can leave the next one something to clean up, so the order matters
    const people = await this.personRepository.getAllWithoutFaces();
    await this.removeAllPersonGroups(people.map((person) => person.personGroupId));

    const personGroups = await this.personRepository.deleteEmptyGroups();
    const clusterGroups = await this.personRepository.deleteOrphanedClusterGroups();

    this.logger.debug(`Deleted ${personGroups} empty person groups and ${clusterGroups} orphaned cluster groups`);

    return JobStatus.Success;
  }

  @OnJob({ name: JobName.AssetDetectFacesQueueAll, queue: QueueName.FaceDetection })
  async handleQueueDetectFaces({ force }: JobOf<JobName.AssetDetectFacesQueueAll>): Promise<JobStatus> {
    const { machineLearning } = await this.getConfig({ withCache: false });
    if (!isFacialRecognitionEnabled(machineLearning)) {
      return JobStatus.Skipped;
    }

    if (force) {
      await this.personRepository.deleteFaces({ sourceType: SourceType.MachineLearning });
      await this.handlePersonCleanup();
      await this.vacuum('asset_face', 'person', 'face_search');
    }

    for await (const assets of batched(this.assetJobRepository.streamForDetectFacesJob(force))) {
      await this.jobRepository.queueAll(
        assets.map((asset) => ({ name: JobName.AssetDetectFaces, data: { id: asset.id } })),
      );
    }

    if (force === undefined) {
      await this.jobRepository.queue({ name: JobName.PersonCleanup });
    }

    return JobStatus.Success;
  }

  @OnJob({ name: JobName.AssetDetectFaces, queue: QueueName.FaceDetection })
  async handleDetectFaces({ id }: JobOf<JobName.AssetDetectFaces>): Promise<JobStatus> {
    const { machineLearning } = await this.getConfig({ withCache: true });
    if (!isFacialRecognitionEnabled(machineLearning)) {
      return JobStatus.Skipped;
    }

    const asset = await this.assetJobRepository.getForDetectFacesJob(id);
    const previewFile = asset?.previewFile;
    if (!asset || !previewFile) {
      return JobStatus.Failed;
    }

    if (asset.visibility === AssetVisibility.Hidden) {
      return JobStatus.Skipped;
    }

    const { imageHeight, imageWidth, faces } = await this.machineLearningRepository.detectFaces(
      previewFile.path,
      machineLearning.facialRecognition,
    );
    this.logger.debug(`${faces.length} faces detected in ${previewFile.path}`);

    const facesToAdd: (Insertable<AssetFaceTable> & { id: string })[] = [];
    const embeddings: FaceSearchTable[] = [];
    const mlFaceIds = new Set<string>();

    for (const face of asset.faces) {
      if (face.sourceType === SourceType.MachineLearning) {
        mlFaceIds.add(face.id);
      }
    }

    for (const { boundingBox, embedding } of faces) {
      const matches = asset.faces.filter((face) => this.iou(face, boundingBox, imageWidth, imageHeight) > 0.5);
      // prefer metadata faces over machine learning duplicates
      const match = matches.find((face) => face.sourceType !== SourceType.MachineLearning) ?? matches[0];

      if (match && !mlFaceIds.delete(match.id)) {
        embeddings.push({ faceId: match.id, embedding });
      } else if (!match) {
        const faceId = this.cryptoRepository.randomUUID();
        facesToAdd.push({
          id: faceId,
          assetId: asset.id,
          imageHeight,
          imageWidth,
          boundingBoxX1: boundingBox.x1,
          boundingBoxY1: boundingBox.y1,
          boundingBoxX2: boundingBox.x2,
          boundingBoxY2: boundingBox.y2,
        });
        embeddings.push({ faceId, embedding });
      }
    }
    const faceIdsToRemove = [...mlFaceIds];

    if (facesToAdd.length > 0 || faceIdsToRemove.length > 0 || embeddings.length > 0) {
      await this.personRepository.refreshFaces(facesToAdd, faceIdsToRemove, embeddings);
    }

    if (faceIdsToRemove.length > 0) {
      this.logger.log(`Removed ${faceIdsToRemove.length} faces below detection threshold in asset ${id}`);
    }

    if (facesToAdd.length > 0) {
      this.logger.log(`Detected ${facesToAdd.length} new faces in asset ${id}`);
      const jobs = facesToAdd.map((face) => ({ name: JobName.FacialRecognition, data: { id: face.id } }) as const);
      await this.jobRepository.queueAll([{ name: JobName.FacialRecognitionQueueAll, data: { force: false } }, ...jobs]);
    } else if (embeddings.length > 0) {
      this.logger.log(`Added ${embeddings.length} face embeddings for asset ${id}`);
    }

    await this.assetRepository.upsertJobStatus({ assetId: asset.id, facesRecognizedAt: new Date() });

    return JobStatus.Success;
  }

  private iou(
    face: {
      boundingBoxX1: number;
      boundingBoxY1: number;
      boundingBoxX2: number;
      boundingBoxY2: number;
      imageWidth: number;
      imageHeight: number;
    },
    newBox: BoundingBox,
    imageWidth: number,
    imageHeight: number,
  ): number {
    const box1 = {
      x1: face.boundingBoxX1 / face.imageWidth,
      y1: face.boundingBoxY1 / face.imageHeight,
      x2: face.boundingBoxX2 / face.imageWidth,
      y2: face.boundingBoxY2 / face.imageHeight,
    };
    const box2 = {
      x1: newBox.x1 / imageWidth,
      y1: newBox.y1 / imageHeight,
      x2: newBox.x2 / imageWidth,
      y2: newBox.y2 / imageHeight,
    };

    const x1 = Math.max(box1.x1, box2.x1);
    const y1 = Math.max(box1.y1, box2.y1);
    const x2 = Math.min(box1.x2, box2.x2);
    const y2 = Math.min(box1.y2, box2.y2);

    const intersection = Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
    const area1 = (box1.x2 - box1.x1) * (box1.y2 - box1.y1);
    const area2 = (box2.x2 - box2.x1) * (box2.y2 - box2.y1);
    const union = area1 + area2 - intersection;

    return intersection / union;
  }

  @OnJob({ name: JobName.FacialRecognitionQueueAll, queue: QueueName.FacialRecognition })
  async handleQueueRecognizeFaces({
    force,
    nightly,
    clusterGroupId,
  }: JobOf<JobName.FacialRecognitionQueueAll>): Promise<JobStatus> {
    return this.databaseRepository.withLock(DatabaseLock.FacialRecognition, async () => {
      const { machineLearning } = await this.getConfig({ withCache: false });
      if (!isFacialRecognitionEnabled(machineLearning)) {
        return JobStatus.Skipped;
      }

      await this.jobRepository.waitForQueueCompletion(QueueName.ThumbnailGeneration, QueueName.FaceDetection);

      if (nightly) {
        const [state, latestFaceDate] = await Promise.all([
          this.systemMetadataRepository.get(SystemMetadataKey.FacialRecognitionState),
          this.personRepository.getLatestFaceDate(),
        ]);

        if (state?.lastRun && latestFaceDate && state.lastRun > latestFaceDate) {
          this.logger.debug('Skipping facial recognition nightly since no face has been added since the last run');
          return JobStatus.Skipped;
        }
      }

      const { waiting } = await this.jobRepository.getJobCounts(QueueName.FacialRecognition);

      if (force) {
        await this.personRepository.unassignFaces({ clusterGroupId, sourceType: SourceType.MachineLearning });
        await this.handlePersonCleanup();
        await this.vacuum('asset_face', 'person');
      } else if (waiting) {
        this.logger.debug(
          `Skipping facial recognition queueing because ${waiting} job${waiting > 1 ? 's are' : ' is'} already queued`,
        );
        return JobStatus.Skipped;
      }

      await this.databaseRepository.prewarm(VectorIndex.Face);

      const lastRun = new Date().toISOString();

      const faces = this.personRepository.getAllFaces(
        force
          ? { clusterGroupId, sourceType: clusterGroupId ? SourceType.MachineLearning : undefined }
          : { personGroupId: null, clusterGroupId, sourceType: SourceType.MachineLearning },
      );
      for await (const batch of batched(faces)) {
        await this.jobRepository.queueAll(
          batch.map((face) => ({ name: JobName.FacialRecognition, data: { id: face.id, deferred: false } })),
        );
      }

      await this.systemMetadataRepository.set(SystemMetadataKey.FacialRecognitionState, { lastRun });

      return JobStatus.Success;
    });
  }

  @OnJob({ name: JobName.FacialRecognition, queue: QueueName.FacialRecognition })
  async handleRecognizeFaces({ id, deferred }: JobOf<JobName.FacialRecognition>): Promise<JobStatus> {
    return this.databaseRepository.withLock(DatabaseLock.FacialRecognition, async () => {
      const { machineLearning } = await this.getConfig({ withCache: true });
      if (!isFacialRecognitionEnabled(machineLearning)) {
        return JobStatus.Skipped;
      }

      const face = await this.personRepository.getFaceForFacialRecognitionJob(id);
      if (!face || !face.asset) {
        this.logger.warn(`Face ${id} not found`);
        return JobStatus.Failed;
      }

      if (face.sourceType !== SourceType.MachineLearning) {
        this.logger.warn(`Skipping face ${id} due to source ${face.sourceType}`);
        return JobStatus.Skipped;
      }

      if (!face.faceSearch?.embedding) {
        this.logger.warn(`Face ${id} does not have an embedding`);
        return JobStatus.Failed;
      }

      if (face.personGroupId) {
        this.logger.debug(`Face ${id} already has a person assigned`);
        return JobStatus.Skipped;
      }

      const { ownerId, clusterGroupId } = face.asset;
      const matches = await this.searchRepository.searchFaces({
        clusterGroupId,
        embedding: face.faceSearch.embedding,
        maxDistance: machineLearning.facialRecognition.maxDistance,
        numResults: machineLearning.facialRecognition.minFaces,
        minBirthDate: new Date(face.asset.fileCreatedAt),
      });

      // `matches` also includes the face itself
      if (machineLearning.facialRecognition.minFaces > 1 && matches.length <= 1) {
        this.logger.debug(`Face ${id} only matched the face itself, skipping`);
        return JobStatus.Skipped;
      }

      this.logger.debug(`Face ${id} has ${matches.length} matches`);

      const isCore =
        matches.length >= machineLearning.facialRecognition.minFaces &&
        face.asset.visibility === AssetVisibility.Timeline;
      if (!isCore && !deferred) {
        this.logger.debug(`Deferring non-core face ${id} for later processing`);
        await this.jobRepository.queue({ name: JobName.FacialRecognition, data: { id, deferred: true } });
        return JobStatus.Skipped;
      }

      let personGroupId = matches.find((match) => match.personGroupId)?.personGroupId;
      if (!personGroupId) {
        const [matchWithPerson] = await this.searchRepository.searchFaces({
          clusterGroupId,
          embedding: face.faceSearch.embedding,
          maxDistance: machineLearning.facialRecognition.maxDistance,
          numResults: 1,
          hasPerson: true,
          minBirthDate: new Date(face.asset.fileCreatedAt),
        });

        personGroupId = matchWithPerson?.personGroupId ?? undefined;
      }

      if (!personGroupId && isCore) {
        const group = await this.personRepository.createGroup(ownerId);
        personGroupId = group.id;
        this.logger.log(`Created person group ${personGroupId} for face ${id}`);
      }

      if (personGroupId) {
        const person = await this.personRepository.getByGroupId({ ownerId, personGroupId });
        if (person) {
          this.logger.debug(`Face ${id} matched person ${person.personGroupId}`);
        } else {
          await this.personRepository.create({ ownerId, faceAssetId: face.id, personGroupId });
          this.logger.log(`Created person for face ${id} in group ${personGroupId}`);
          await this.jobRepository.queue({
            name: JobName.PersonGenerateThumbnail,
            data: { ownerId, personGroupId },
          });
        }

        this.logger.debug(`Assigning face ${id} to person group ${personGroupId}`);
        await this.personRepository.reassignFaces({ faceIds: [id], newPersonGroupId: personGroupId });
      }

      return JobStatus.Success;
    });
  }

  @OnJob({ name: JobName.PersonFileMigration, queue: QueueName.Migration })
  async handlePersonMigration({ ownerId, personGroupId }: JobOf<JobName.PersonFileMigration>): Promise<JobStatus> {
    const person = await this.personRepository.getByGroupId({ ownerId, personGroupId });
    if (!person) {
      return JobStatus.Failed;
    }

    await this.storageCore.movePersonFile(person, PersonPathType.Face);

    return JobStatus.Success;
  }

  async mergePeople(auth: AuthDto, { ids }: MergePersonDto): Promise<BulkIdResponseDto[]> {
    if (ids.length < 2) {
      throw new BadRequestException('At least two people are required for merging');
    }

    if (new Set(ids).size !== ids.length) {
      throw new BadRequestException('Cannot merge a person into themselves');
    }

    const allowed = await this.checkPersonAccess({
      auth,
      permission: Permission.PersonMerge,
      ids: ids.map((id) => ({ personGroupId: id, ownerId: auth.user.id })),
    });
    const allowedIds = new Set(allowed.values().map((item) => item.personGroupId));
    const results = new Map<string, BulkIdResponseDto>(
      ids.map((id) => [
        id,
        {
          id,
          success: false,
          error: allowedIds.has(id) ? BulkIdErrorReason.NOT_FOUND : BulkIdErrorReason.NO_PERMISSION,
        },
      ]),
    );

    const orderedIds = ids.filter((id) => allowedIds.has(id));
    const [targetId, ...sourceIds] = orderedIds;
    const people = targetId ? await this.personRepository.getForMergePerson(orderedIds) : [];
    const lookup = new Map(people.map((person) => [personKey(person), person]));
    const ownerIds = new Set([auth.user.id, ...people.map((person) => person.ownerId)]);
    const targets = new Map(
      people.filter((person) => person.personGroupId === targetId).map((person) => [person.ownerId, person]),
    );

    if (targets.has(auth.user.id)) {
      results.set(targetId, { id: targetId, success: true });
    }

    for (const id of sourceIds) {
      for (const ownerId of ownerIds) {
        const isAuthUser = ownerId === auth.user.id;
        const source = lookup.get(personKey({ ownerId, personGroupId: id }));
        let target = targets.get(ownerId);
        if (!source) {
          continue;
        }

        // skip other users when there are conflicts
        if (!isAuthUser && target && ((target.name && source.name) || (target.birthDate && source.birthDate))) {
          continue;
        }

        try {
          if (!target) {
            // user has no person in the target group yet, so this one is updated to it
            targets.set(
              ownerId,
              await this.personRepository.updateGroupId({ ownerId, oldPersonGroupId: id, newPersonGroupId: targetId }),
            );
            continue;
          }

          const changes = omitBy(
            {
              name: source.name && !target.name ? source.name : undefined,
              birthDate: source.birthDate && !target.birthDate ? source.birthDate : undefined,
            },
            isUndefined,
          );
          if (Object.keys(changes).length > 0) {
            target = await this.personRepository.update({ ownerId, personGroupId: targetId, ...changes });
            targets.set(ownerId, target);
          }

          await this.personRepository.reassignFaces({ oldPersonGroupId: id, newPersonGroupId: targetId, ownerId });
          await this.removeAllPersonGroups([id], ownerId);
          this.logger.log(`Merged ${source.name || id} into ${target.name || targetId}`);

          if (isAuthUser) {
            results.set(id, { id, success: true });
          }
        } catch (error: any) {
          this.logger.error(`Unable to merge ${id} into ${targetId}: ${error}`, error?.stack);
          if (isAuthUser) {
            results.set(id, { id, success: false, error: BulkIdErrorReason.UNKNOWN });
          }
        }
      }
    }

    await this.personRepository.deleteEmptyGroups();

    return results.values().toArray();
  }

  private findOrFail(auth: AuthDto, personGroupId: string) {
    return findOrFail(() => this.personRepository.getByGroupId({ ownerId: auth.user.id, personGroupId }), 'Person');
  }

  // TODO return a asset face response
  async createFace(auth: AuthDto, dto: AssetFaceCreateDto): Promise<void> {
    await Promise.all([
      this.requireAccess({ auth, permission: Permission.AssetUpdate, ids: [dto.assetId] }),
      this.requirePersonAccess({
        auth,
        permission: Permission.PersonRead,
        ids: [{ personGroupId: dto.personId, ownerId: auth.user.id }],
      }),
    ]);

    const [asset, person] = await Promise.all([
      this.assetRepository.getById(dto.assetId, { edits: true, exifInfo: true }),
      this.findOrFail(auth, dto.personId),
    ]);

    if (!asset) {
      throw new NotFoundException('Asset not found');
    }

    const edits = asset.edits || [];

    let topLeft: Point = { x: dto.x, y: dto.y };
    let bottomRight: Point = { x: dto.x + dto.width, y: dto.y + dto.height };

    // the coordinates received from the client are based on the edited preview image
    // we need to convert them to the coordinate space of the original unedited image
    if (edits.length > 0) {
      if (!asset.width || !asset.height || !asset.exifInfo?.exifImageWidth || !asset.exifInfo?.exifImageHeight) {
        throw new BadRequestException('Asset does not have valid dimensions');
      }

      // convert from preview to full dimensions
      const scaleFactor = asset.width / dto.imageWidth;
      topLeft = { x: topLeft.x * scaleFactor, y: topLeft.y * scaleFactor };
      bottomRight = { x: bottomRight.x * scaleFactor, y: bottomRight.y * scaleFactor };
      const [invertedTopLeft, invertedBottomRight] = transformPoints(
        [topLeft, bottomRight],
        edits,
        { width: asset.width, height: asset.height },
        { inverse: true },
      ).points;

      // make sure topLeft is top-left and bottomRight is bottom-right
      topLeft = {
        x: Math.min(invertedTopLeft.x, invertedBottomRight.x),
        y: Math.min(invertedTopLeft.y, invertedBottomRight.y),
      };
      bottomRight = {
        x: Math.max(invertedTopLeft.x, invertedBottomRight.x),
        y: Math.max(invertedTopLeft.y, invertedBottomRight.y),
      };

      // now coordinates are in original image space
      const originalDimensions = getDimensions(asset.exifInfo);
      dto.imageWidth = originalDimensions.width;
      dto.imageHeight = originalDimensions.height;
    }

    await this.personRepository.createAssetFace({
      personGroupId: person.personGroupId,
      assetId: dto.assetId,
      imageHeight: dto.imageHeight,
      imageWidth: dto.imageWidth,
      boundingBoxX1: Math.round(topLeft.x),
      boundingBoxX2: Math.round(bottomRight.x),
      boundingBoxY1: Math.round(topLeft.y),
      boundingBoxY2: Math.round(bottomRight.y),
      sourceType: SourceType.Manual,
    });

    if (!person.faceAssetId) {
      await this.createNewFeaturePhoto([person]);
    }
  }

  async deleteFace(auth: AuthDto, id: string, dto: AssetFaceDeleteDto): Promise<void> {
    await this.requireAccess({ auth, permission: Permission.FaceDelete, ids: [id] });

    return dto.force ? this.personRepository.deleteAssetFace(id) : this.personRepository.softDeleteAssetFaces(id);
  }

  async getUsersForPeople(auth: AuthDto, dto: PersonUsersSearchDto): Promise<PersonUsersResponseDto> {
    const sharedUsers = await this.personUserRepository.searchPeopleUsers(auth.user.id, dto);

    return mapPersonUsers(sharedUsers);
  }

  async upsertPeopleUsers(auth: AuthDto, dto: PeopleUsersUpsertDto) {
    if (dto.sharedWithIds.includes(auth.user.id)) {
      throw new BadRequestException('Cannot share a person with yourself');
    }

    if (dto.personIds) {
      await this.requirePersonAccess({
        auth,
        permission: Permission.PersonUpdate,
        ids: dto.personIds.map((item) => ({ personGroupId: item, ownerId: auth.user.id })),
      });
    }

    const user = await findOrFail(() => this.userRepository.get(auth.user.id, {}), 'User');
    const clusterGroupUsers = await this.clusterGroupRepository.getUsers({
      clusterGroupId: user.clusterGroupId,
      userId: user.id,
    });
    const clusterGroupUserIds = new Set(clusterGroupUsers.map(({ id }) => id));

    for (const sharedWithId of dto.sharedWithIds) {
      if (!clusterGroupUserIds.has(sharedWithId)) {
        throw new BadRequestException('All users must be in the same cluster group');
      }
    }

    const sharedById = auth.user.id;

    if (dto.personIds) {
      const items: Insertable<PersonUserTable>[] = [];
      for (const sharedWithId of dto.sharedWithIds) {
        for (const personGroupId of dto.personIds) {
          items.push({ personGroupId, sharedById, sharedWithId, role: dto.role });
        }
      }

      await this.personUserRepository.createAll(items);
    } else {
      await this.personUserRepository.createAllForOwner({
        ownerId: sharedById,
        sharedWithIds: dto.sharedWithIds,
        role: dto.role,
      });
    }
  }

  async removeUsersFromPeople(auth: AuthDto, dto: PersonUsersDeleteDto) {
    await this.requirePersonAccess({
      auth,
      permission: Permission.PersonUpdate,
      ids: dto.map((item) => ({ personGroupId: item.personId, ownerId: item.sharedById ?? auth.user.id })),
    });
    await this.personUserRepository.deleteAll(auth.user.id, dto);
  }

  private vacuum(...tables: (keyof DB)[]): Promise<unknown> {
    return Promise.all(
      tables.map((table) =>
        this.databaseRepository
          .vacuum({ analyze: true, table })
          .then(() => this.databaseRepository.reindex(table, { concurrently: true })),
      ),
    );
  }
}