feat: workflow foundation (#23621)

* feat: plugins * feat: table definition * feat: type and migration * feat: add repositories * feat: validate manifest with class-validator and load manifest info to database * feat: workflow/plugin controller/service layer * feat: implement workflow logic * feat: make trigger static * feat: dynamical instantiate plugin instances * fix: access control and helper script * feat: it works * chore: simplify * refactor: refactor and use queue for workflow execution * refactor: remove unsused property in plugin-schema * build wasm in prod * feat: plugin loader in transaction * fix: docker build arm64 * generated files * shell check * fix tests * fix: waiting for migration to finish before loading plugin * remove context reassignment * feat: use mise to manage extism tools (#23760) * pr feedback * refactor: create workflow now including create filters and actions * feat: workflow medium tests * fix: broken medium test * feat: medium tests * chore: unify workflow job * sign user id with jwt * chore: query plugin with filters and action * chore: read manifest in repository * chore: load manifest from server configs * merge main * feat: endpoint documentation * pr feedback * load plugin from absolute path * refactor:handle trigger * throw error and return early * pr feedback * unify plugin services * fix: plugins code * clean up * remove triggerConfig * clean up * displayName and methodName --------- Co-authored-by: Jason Rasmussen <jason@rasm.me> Co-authored-by: bo0tzz <git@bo0tzz.me>
2026-03-07 10:37:22 +03:00 · 2025-11-14 14:05:05 -06:00
parent d784d431d0
commit 4dcc049465
89 changed files with 7264 additions and 14 deletions
--- a/server/src/dtos/env.dto.ts
+++ b/server/src/dtos/env.dto.ts
@@ -57,6 +57,13 @@ export class EnvDto {
  @Type(() => Number)
  IMMICH_MICROSERVICES_METRICS_PORT?: number;

+  @ValidateBoolean({ optional: true })
+  IMMICH_PLUGINS_ENABLED?: boolean;
+
+  @Optional()
+  @Matches(/^\//, { message: 'IMMICH_PLUGINS_INSTALL_FOLDER must be an absolute path' })
+  IMMICH_PLUGINS_INSTALL_FOLDER?: string;
+
  @IsInt()
  @Optional()
  @Type(() => Number)
--- a/server/src/dtos/plugin-manifest.dto.ts
+++ b/server/src/dtos/plugin-manifest.dto.ts
@@ -0,0 +1,110 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMinSize,
+  IsArray,
+  IsEnum,
+  IsNotEmpty,
+  IsObject,
+  IsOptional,
+  IsSemVer,
+  IsString,
+  Matches,
+  ValidateNested,
+} from 'class-validator';
+import { PluginContext } from 'src/enum';
+import { JSONSchema } from 'src/types/plugin-schema.types';
+import { ValidateEnum } from 'src/validation';
+
+class PluginManifestWasmDto {
+  @IsString()
+  @IsNotEmpty()
+  path!: string;
+}
+
+class PluginManifestFilterDto {
+  @IsString()
+  @IsNotEmpty()
+  methodName!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  title!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  description!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @IsEnum(PluginContext, { each: true })
+  supportedContexts!: PluginContext[];
+
+  @IsObject()
+  @IsOptional()
+  schema?: JSONSchema;
+}
+
+class PluginManifestActionDto {
+  @IsString()
+  @IsNotEmpty()
+  methodName!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  title!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  description!: string;
+
+  @IsArray()
+  @ArrayMinSize(1)
+  @ValidateEnum({ enum: PluginContext, name: 'PluginContext', each: true })
+  supportedContexts!: PluginContext[];
+
+  @IsObject()
+  @IsOptional()
+  schema?: JSONSchema;
+}
+
+export class PluginManifestDto {
+  @IsString()
+  @IsNotEmpty()
+  @Matches(/^[a-z0-9-]+[a-z0-9]$/, {
+    message: 'Plugin name must contain only lowercase letters, numbers, and hyphens, and cannot end with a hyphen',
+  })
+  name!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @IsSemVer()
+  version!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  title!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  description!: string;
+
+  @IsString()
+  @IsNotEmpty()
+  author!: string;
+
+  @ValidateNested()
+  @Type(() => PluginManifestWasmDto)
+  wasm!: PluginManifestWasmDto;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => PluginManifestFilterDto)
+  @IsOptional()
+  filters?: PluginManifestFilterDto[];
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => PluginManifestActionDto)
+  @IsOptional()
+  actions?: PluginManifestActionDto[];
+}
--- a/server/src/dtos/plugin.dto.ts
+++ b/server/src/dtos/plugin.dto.ts
@@ -0,0 +1,77 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { PluginAction, PluginFilter } from 'src/database';
+import { PluginContext } from 'src/enum';
+import type { JSONSchema } from 'src/types/plugin-schema.types';
+import { ValidateEnum } from 'src/validation';
+
+export class PluginResponseDto {
+  id!: string;
+  name!: string;
+  title!: string;
+  description!: string;
+  author!: string;
+  version!: string;
+  createdAt!: string;
+  updatedAt!: string;
+  filters!: PluginFilterResponseDto[];
+  actions!: PluginActionResponseDto[];
+}
+
+export class PluginFilterResponseDto {
+  id!: string;
+  pluginId!: string;
+  methodName!: string;
+  title!: string;
+  description!: string;
+
+  @ValidateEnum({ enum: PluginContext, name: 'PluginContext' })
+  supportedContexts!: PluginContext[];
+  schema!: JSONSchema | null;
+}
+
+export class PluginActionResponseDto {
+  id!: string;
+  pluginId!: string;
+  methodName!: string;
+  title!: string;
+  description!: string;
+
+  @ValidateEnum({ enum: PluginContext, name: 'PluginContext' })
+  supportedContexts!: PluginContext[];
+  schema!: JSONSchema | null;
+}
+
+export class PluginInstallDto {
+  @IsString()
+  @IsNotEmpty()
+  manifestPath!: string;
+}
+
+export type MapPlugin = {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  author: string;
+  version: string;
+  wasmPath: string;
+  createdAt: Date;
+  updatedAt: Date;
+  filters: PluginFilter[];
+  actions: PluginAction[];
+};
+
+export function mapPlugin(plugin: MapPlugin): PluginResponseDto {
+  return {
+    id: plugin.id,
+    name: plugin.name,
+    title: plugin.title,
+    description: plugin.description,
+    author: plugin.author,
+    version: plugin.version,
+    createdAt: plugin.createdAt.toISOString(),
+    updatedAt: plugin.updatedAt.toISOString(),
+    filters: plugin.filters,
+    actions: plugin.actions,
+  };
+}
--- a/server/src/dtos/queue.dto.ts
+++ b/server/src/dtos/queue.dto.ts
@@ -91,4 +91,7 @@ export class QueuesResponseDto implements Record<QueueName, QueueResponseDto> {

  @ApiProperty({ type: QueueResponseDto })
  [QueueName.Ocr]!: QueueResponseDto;
+
+  @ApiProperty({ type: QueueResponseDto })
+  [QueueName.Workflow]!: QueueResponseDto;
 }
--- a/server/src/dtos/system-config.dto.ts
+++ b/server/src/dtos/system-config.dto.ts
@@ -224,6 +224,12 @@ class SystemConfigJobDto implements Record<ConcurrentQueueName, JobSettingsDto>
  @IsObject()
  @Type(() => JobSettingsDto)
  [QueueName.Notification]!: JobSettingsDto;
+
+  @ApiProperty({ type: JobSettingsDto })
+  @ValidateNested()
+  @IsObject()
+  @Type(() => JobSettingsDto)
+  [QueueName.Workflow]!: JobSettingsDto;
 }

 class SystemConfigLibraryScanDto {
--- a/server/src/dtos/workflow.dto.ts
+++ b/server/src/dtos/workflow.dto.ts
@@ -0,0 +1,120 @@
+import { Type } from 'class-transformer';
+import { IsNotEmpty, IsObject, IsString, IsUUID, ValidateNested } from 'class-validator';
+import { WorkflowAction, WorkflowFilter } from 'src/database';
+import { PluginTriggerType } from 'src/enum';
+import type { ActionConfig, FilterConfig } from 'src/types/plugin-schema.types';
+import { Optional, ValidateBoolean, ValidateEnum } from 'src/validation';
+
+export class WorkflowFilterItemDto {
+  @IsUUID()
+  filterId!: string;
+
+  @IsObject()
+  @Optional()
+  filterConfig?: FilterConfig;
+}
+
+export class WorkflowActionItemDto {
+  @IsUUID()
+  actionId!: string;
+
+  @IsObject()
+  @Optional()
+  actionConfig?: ActionConfig;
+}
+
+export class WorkflowCreateDto {
+  @ValidateEnum({ enum: PluginTriggerType, name: 'PluginTriggerType' })
+  triggerType!: PluginTriggerType;
+
+  @IsString()
+  @IsNotEmpty()
+  name!: string;
+
+  @IsString()
+  @Optional()
+  description?: string;
+
+  @ValidateBoolean({ optional: true })
+  enabled?: boolean;
+
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowFilterItemDto)
+  filters!: WorkflowFilterItemDto[];
+
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowActionItemDto)
+  actions!: WorkflowActionItemDto[];
+}
+
+export class WorkflowUpdateDto {
+  @IsString()
+  @IsNotEmpty()
+  @Optional()
+  name?: string;
+
+  @IsString()
+  @Optional()
+  description?: string;
+
+  @ValidateBoolean({ optional: true })
+  enabled?: boolean;
+
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowFilterItemDto)
+  @Optional()
+  filters?: WorkflowFilterItemDto[];
+
+  @ValidateNested({ each: true })
+  @Type(() => WorkflowActionItemDto)
+  @Optional()
+  actions?: WorkflowActionItemDto[];
+}
+
+export class WorkflowResponseDto {
+  id!: string;
+  ownerId!: string;
+  triggerType!: PluginTriggerType;
+  name!: string | null;
+  description!: string;
+  createdAt!: string;
+  enabled!: boolean;
+  filters!: WorkflowFilterResponseDto[];
+  actions!: WorkflowActionResponseDto[];
+}
+
+export class WorkflowFilterResponseDto {
+  id!: string;
+  workflowId!: string;
+  filterId!: string;
+  filterConfig!: FilterConfig | null;
+  order!: number;
+}
+
+export class WorkflowActionResponseDto {
+  id!: string;
+  workflowId!: string;
+  actionId!: string;
+  actionConfig!: ActionConfig | null;
+  order!: number;
+}
+
+export function mapWorkflowFilter(filter: WorkflowFilter): WorkflowFilterResponseDto {
+  return {
+    id: filter.id,
+    workflowId: filter.workflowId,
+    filterId: filter.filterId,
+    filterConfig: filter.filterConfig,
+    order: filter.order,
+  };
+}
+
+export function mapWorkflowAction(action: WorkflowAction): WorkflowActionResponseDto {
+  return {
+    id: action.id,
+    workflowId: action.workflowId,
+    actionId: action.actionId,
+    actionConfig: action.actionConfig,
+    order: action.order,
+  };
+}