Skip to content

High performance self-hosted photo and video management solution.

11.7 KB
Raw Blame
import { BadRequestException, INestApplication } from '@nestjs/common';
import {
  ApiBodyOptions,
  DocumentBuilder,
  OpenAPIObject,
  SwaggerCustomOptions,
  SwaggerDocumentOptions,
  SwaggerModule,
} from '@nestjs/swagger';
import { get, isArray, isDate, isEmpty, isObject, orderBy, unset } from 'lodash-es';
import { cleanupOpenApiDoc } from 'nestjs-zod';
import { writeFileSync } from 'node:fs';
import path from 'node:path';
import picomatch from 'picomatch';
import { CLIP_MODEL_INFO, JOBS_ASSET_PAGINATION_SIZE, endpointTags, serverVersion } from 'src/constants.js';
import { extraModels } from 'src/decorators.js';
import { SystemConfig } from 'src/dtos/config.dto.js';
import { ApiCustomExtension, ImmichCookie, ImmichHeader, MetadataKey } from 'src/enum.js';
import { LoggingRepository } from 'src/repositories/logging.repository.js';

type OperationObject = NonNullable<OpenAPIObject['paths'][string]['get']>;
type ReferenceOrSchemaObject = Extract<ApiBodyOptions, { schema: unknown }>['schema'];
type ReferenceObject = Extract<ReferenceOrSchemaObject, { $ref: unknown }>;
type SchemaObject = Exclude<ReferenceOrSchemaObject, ReferenceObject>;

export class ImmichStartupError extends Error {}
export const isStartUpError = (error: unknown): error is ImmichStartupError => error instanceof ImmichStartupError;

export const getKeyByValue = (object: Record<string, unknown>, value: unknown) =>
  Object.keys(object).find((key) => object[key] === value);

export const getMethodNames = (instance: any) => {
  const ctx = Object.getPrototypeOf(instance);
  const methods: string[] = [];
  for (const property of Object.getOwnPropertyNames(ctx)) {
    const descriptor = Object.getOwnPropertyDescriptor(ctx, property);
    if (!descriptor || descriptor.get || descriptor.set) {
      continue;
    }

    const handler = instance[property];
    if (typeof handler !== 'function') {
      continue;
    }

    methods.push(property);
  }

  return methods;
};

export const getExternalDomain = (server: SystemConfig['server'], defaultDomain = 'https://my.immich.app') =>
  server.externalDomain || defaultDomain;

/** @returns a list of strings representing the keys of the object in dot notation */
export const getKeysDeep = (target: unknown, path: string[] = []) => {
  if (!target || typeof target !== 'object') {
    return [];
  }

  const obj = target as object;

  const properties: string[] = [];
  for (const key of Object.keys(obj as object)) {
    const value = obj[key as keyof object];
    if (value === undefined) {
      continue;
    }

    if (isObject(value) && !isArray(value) && !isDate(value)) {
      properties.push(...getKeysDeep(value, [...path, key]));
      continue;
    }

    properties.push([...path, key].join('.'));
  }

  return properties;
};

export const unsetDeep = (object: unknown, key: string) => {
  const parts = key.split('.');
  while (parts.length > 0) {
    unset(object, parts);
    parts.pop();
    if (!isEmpty(get(object, parts))) {
      break;
    }
  }

  return isEmpty(object) ? undefined : object;
};

const isMachineLearningEnabled = (machineLearning: SystemConfig['machineLearning']) => machineLearning.enabled;
export const isSmartSearchEnabled = (machineLearning: SystemConfig['machineLearning']) =>
  isMachineLearningEnabled(machineLearning) && machineLearning.clip.enabled;
export const isOcrEnabled = (machineLearning: SystemConfig['machineLearning']) =>
  isMachineLearningEnabled(machineLearning) && machineLearning.ocr.enabled;
export const isFacialRecognitionEnabled = (machineLearning: SystemConfig['machineLearning']) =>
  isMachineLearningEnabled(machineLearning) && machineLearning.facialRecognition.enabled;
export const isDuplicateDetectionEnabled = (machineLearning: SystemConfig['machineLearning']) =>
  isSmartSearchEnabled(machineLearning) && machineLearning.duplicateDetection.enabled;
export const isFaceImportEnabled = (metadata: SystemConfig['metadata']) => metadata.faces.import;

export const handlePromiseError = <T>(promise: Promise<T>, logger: LoggingRepository): void => {
  promise.catch((error: Error | any) => logger.error(`Promise error: ${error}`, error?.stack));
};

export const hasSomeDefined = (values: unknown[]) => values.some((value) => value !== undefined);

export const findOrFail = async <T>(find: () => Promise<T>, entity: string): Promise<NonNullable<T>> => {
  const value = await find();
  if (!value) {
    throw new BadRequestException(`${entity} not found`);
  }

  return value;
};

export async function* batched<T>(items: AsyncIterable<T>, size = JOBS_ASSET_PAGINATION_SIZE): AsyncGenerator<T[]> {
  let batch: T[] = [];

  for await (const item of items) {
    batch.push(item);

    if (batch.length < size) {
      continue;
    }

    yield batch;
    batch = [];
  }

  if (batch.length > 0) {
    yield batch;
  }
}

export interface OpenGraphTags {
  title: string;
  description: string;
  imageUrl?: string;
}

function cleanModelName(modelName: string): string {
  const token = modelName.split('/').at(-1);
  if (!token) {
    throw new Error(`Invalid model name: ${modelName}`);
  }

  return token.replaceAll(':', '_');
}

export function getCLIPModelInfo(modelName: string) {
  const modelInfo = CLIP_MODEL_INFO[cleanModelName(modelName)];
  if (!modelInfo) {
    throw new Error(`Unknown CLIP model: ${modelName}`);
  }

  return modelInfo;
}

function sortKeys<T>(target: T): T {
  if (!target || typeof target !== 'object' || Array.isArray(target)) {
    return target;
  }

  const result: Partial<T> = {};
  const keys = Object.keys(target).toSorted() as Array<keyof T>;
  for (const key of keys) {
    result[key] = sortKeys(target[key]);
  }
  return result as T;
}

export const routeToErrorMessage = (methodName: string) =>
  'Failed to ' + methodName.replaceAll(/[A-Z]+/g, (letter) => ` ${letter.toLowerCase()}`);

const isSchema = (schema: string | ReferenceObject | SchemaObject): schema is SchemaObject => {
  return !(typeof schema === 'string' || '$ref' in schema);
};

const patchOpenAPI = (document: OpenAPIObject) => {
  const removeOpenApi30IncompatibleKeys = (target: unknown) => {
    if (!target || typeof target !== 'object') {
      return;
    }

    if (Array.isArray(target)) {
      for (const item of target) {
        removeOpenApi30IncompatibleKeys(item);
      }
      return;
    }

    const object = target as Record<string, unknown>;
    delete object.propertyNames;
    delete object.contentEncoding;

    for (const value of Object.values(object)) {
      removeOpenApi30IncompatibleKeys(value);
    }
  };

  document.paths = sortKeys(document.paths);
  // Allowed in OpenAPI v3.1 (JSON Schema 2020-12), but not in OpenAPI v3.0 (current spec).
  removeOpenApi30IncompatibleKeys(document);

  if (document.components?.schemas) {
    const schemas = document.components.schemas as Record<string, SchemaObject>;

    for (const schema of Object.values(schemas)) {
      delete (schema as Record<string, unknown>).id;

      // documents a property as required even though it is optional during body validation
      for (const [key, value] of Object.entries(schema.properties ?? {})) {
        if (!(ApiCustomExtension.Required in value)) {
          continue;
        }

        delete (value as Record<string, unknown>)[ApiCustomExtension.Required];
        (schema.required ??= []).push(key);
      }
    }

    document.components.schemas = sortKeys(schemas);

    const errors: string[] = [];

    for (const [schemaName, schema] of Object.entries(schemas)) {
      if (!schema.properties) {
        continue;
      }

      schema.properties = sortKeys(schema.properties);

      for (const [key, initialValue] of Object.entries(schema.properties)) {
        if (typeof initialValue === 'string' || !isSchema(initialValue)) {
          continue;
        }

        // check array types
        let value: SchemaObject | ReferenceObject = initialValue;
        if (value.type === 'array' && value.items) {
          value = value.items;
        }

        if (!(isSchema(value) && value.type === 'number')) {
          continue;
        }

        if (value.format === 'float') {
          errors.push(`Invalid number format: ${schemaName}.${key}=float (use double instead). `);
        }

        // verify it was meant to be a number (and not an integer)
        if (!value.format) {
          errors.push(
            `${schemaName}.${key} is a number (not an integer) and requires a format (e.g .meta({ format: 'double' })). `,
          );
        }
      }
      schema.required?.sort();

      if (errors.length > 0) {
        throw new Error(`Schema validation failed:\n  ${errors.join('\n  ')}`);
      }
    }
  }

  for (const [key, value] of Object.entries(document.paths)) {
    const newKey = key.replace('/api/', '/');
    delete document.paths[key];
    document.paths[newKey] = value;
  }

  for (const path of Object.values(document.paths)) {
    const operations = {
      get: path.get,
      put: path.put,
      post: path.post,
      delete: path.delete,
      options: path.options,
      head: path.head,
      patch: path.patch,
      trace: path.trace,
    };

    for (const operation of Object.values(operations) as Array<
      OperationObject & {
        [ApiCustomExtension.AdminOnly]?: boolean;
        [ApiCustomExtension.Permission]?: string;
      }
    >) {
      if (!operation) {
        continue;
      }

      if (operation.summary === '') {
        delete operation.summary;
      }

      if (operation.description === '') {
        delete operation.description;
      }

      if (operation.operationId) {
        // console.log(`${routeToErrorMessage(operation.operationId).padEnd(40)} (${operation.operationId})`);
      }

      if (operation.parameters) {
        operation.parameters = orderBy(operation.parameters, 'name');
      }
    }
  }

  return document;
};

export const useSwagger = (app: INestApplication, { write }: { write: boolean }) => {
  const builder = new DocumentBuilder()
    .setTitle('Immich')
    .setDescription('Immich API')
    .setVersion(serverVersion.toString())
    .addBearerAuth({
      type: 'http',
      scheme: 'Bearer',
      in: 'header',
    })
    .addCookieAuth(ImmichCookie.AccessToken)
    .addApiKey(
      {
        type: 'apiKey',
        in: 'header',
        name: ImmichHeader.ApiKey,
      },
      MetadataKey.ApiKeySecurity,
    )
    .addServer('/api');

  for (const [tag, description] of Object.entries(endpointTags)) {
    builder.addTag(tag, description);
  }
  const config = builder.build();

  const options: SwaggerDocumentOptions = {
    operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
    extraModels,
    ignoreGlobalPrefix: true,
  };

  const specification = SwaggerModule.createDocument(app, config, options);
  const openApiDoc = cleanupOpenApiDoc(specification);

  const customOptions: SwaggerCustomOptions = {
    swaggerOptions: {
      persistAuthorization: true,
    },
    jsonDocumentUrl: '/api/spec.json',
    yamlDocumentUrl: '/api/spec.yaml',
    customSiteTitle: 'Immich API Documentation',
  };

  SwaggerModule.setup('doc', app, openApiDoc, customOptions);

  // Generate API Documentation only in development mode
  if (!write) {
    return;
  }

  const outputPath = path.resolve(process.cwd(), '../open-api/immich-openapi-specs.json');
  writeFileSync(outputPath, JSON.stringify(patchOpenAPI(openApiDoc), null, 2), { encoding: 'utf8' });
};

// Compiles a glob to the equivalent Postgres regex (Postgres's Advanced Regular Expression
// dialect is a superset of what picomatch emits, so the two stay in sync with `picomatch.isMatch`,
// including which paths a lone `*` may cross vs `/`).
export const globToPostgresRegex = (glob: string) => picomatch.makeRe(glob).source;

export function clamp(value: number, min: number, max: number) {
  return Math.max(min, Math.min(max, value));
}