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>

server/src/repositories/access.repository.ts

@@ -462,6 +462,26 @@ class TagAccess {
   }
 }
 
+class WorkflowAccess {
+  constructor(private db: Kysely<DB>) {}
+
+  @GenerateSql({ params: [DummyValue.UUID, DummyValue.UUID_SET] })
+  @ChunkedSet({ paramIndex: 1 })
+  async checkOwnerAccess(userId: string, workflowIds: Set<string>) {
+    if (workflowIds.size === 0) {
+      return new Set<string>();
+    }
+
+    return this.db
+      .selectFrom('workflow')
+      .select('workflow.id')
+      .where('workflow.id', 'in', [...workflowIds])
+      .where('workflow.ownerId', '=', userId)
+      .execute()
+      .then((workflows) => new Set(workflows.map((workflow) => workflow.id)));
+  }
+}
+
 @Injectable()
 export class AccessRepository {
   activity: ActivityAccess;
@@ -476,6 +496,7 @@ export class AccessRepository {
   stack: StackAccess;
   tag: TagAccess;
   timeline: TimelineAccess;
+  workflow: WorkflowAccess;
 
   constructor(@InjectKysely() db: Kysely<DB>) {
     this.activity = new ActivityAccess(db);
@@ -490,5 +511,6 @@ export class AccessRepository {
     this.stack = new StackAccess(db);
     this.tag = new TagAccess(db);
     this.timeline = new TimelineAccess(db);
+    this.workflow = new WorkflowAccess(db);
   }
 }

server/src/repositories/config.repository.ts

@@ -85,6 +85,7 @@ export interface EnvData {
       root: string;
       indexHtml: string;
     };
+    corePlugin: string;
   };
 
   redis: RedisOptions;
@@ -102,6 +103,11 @@ export interface EnvData {
 
   workers: ImmichWorker[];
 
+  plugins: {
+    enabled: boolean;
+    installFolder?: string;
+  };
+
   noColor: boolean;
   nodeVersion?: string;
 }
@@ -304,6 +310,7 @@ const getEnv = (): EnvData => {
         root: folders.web,
         indexHtml: join(folders.web, 'index.html'),
       },
+      corePlugin: join(buildFolder, 'corePlugin'),
     },
 
     storage: {
@@ -319,6 +326,11 @@ const getEnv = (): EnvData => {
 
     workers,
 
+    plugins: {
+      enabled: !!dto.IMMICH_PLUGINS_ENABLED,
+      installFolder: dto.IMMICH_PLUGINS_INSTALL_FOLDER,
+    },
+
     noColor: !!dto.NO_COLOR,
   };
 };

server/src/repositories/crypto.repository.ts

@@ -1,5 +1,6 @@
 import { Injectable } from '@nestjs/common';
 import { compareSync, hash } from 'bcrypt';
+import jwt from 'jsonwebtoken';
 import { createHash, createPublicKey, createVerify, randomBytes, randomUUID } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 
@@ -57,4 +58,12 @@ export class CryptoRepository {
   randomBytesAsText(bytes: number) {
     return randomBytes(bytes).toString('base64').replaceAll(/\W/g, '');
   }
+
+  signJwt(payload: string | object | Buffer, secret: string, options?: jwt.SignOptions): string {
+    return jwt.sign(payload, secret, { algorithm: 'HS256', ...options });
+  }
+
+  verifyJwt<T = any>(token: string, secret: string): T {
+    return jwt.verify(token, secret, { algorithms: ['HS256'] }) as T;
+  }
 }

server/src/repositories/event.repository.ts

@@ -4,6 +4,7 @@ import { ClassConstructor } from 'class-transformer';
 import _ from 'lodash';
 import { Socket } from 'socket.io';
 import { SystemConfig } from 'src/config';
+import { Asset } from 'src/database';
 import { EventConfig } from 'src/decorators';
 import { AuthDto } from 'src/dtos/auth.dto';
 import { ImmichWorker, JobStatus, MetadataKey, QueueName, UserAvatarColor, UserStatus } from 'src/enum';
@@ -41,6 +42,7 @@ type EventMap = {
   AlbumInvite: [{ id: string; userId: string }];
 
   // asset events
+  AssetCreate: [{ asset: Asset }];
   AssetTag: [{ assetId: string }];
   AssetUntag: [{ assetId: string }];
   AssetHide: [{ assetId: string; userId: string }];

server/src/repositories/index.ts

@@ -28,6 +28,7 @@ import { OAuthRepository } from 'src/repositories/oauth.repository';
 import { OcrRepository } from 'src/repositories/ocr.repository';
 import { PartnerRepository } from 'src/repositories/partner.repository';
 import { PersonRepository } from 'src/repositories/person.repository';
+import { PluginRepository } from 'src/repositories/plugin.repository';
 import { ProcessRepository } from 'src/repositories/process.repository';
 import { SearchRepository } from 'src/repositories/search.repository';
 import { ServerInfoRepository } from 'src/repositories/server-info.repository';
@@ -46,6 +47,7 @@ import { UserRepository } from 'src/repositories/user.repository';
 import { VersionHistoryRepository } from 'src/repositories/version-history.repository';
 import { ViewRepository } from 'src/repositories/view-repository';
 import { WebsocketRepository } from 'src/repositories/websocket.repository';
+import { WorkflowRepository } from 'src/repositories/workflow.repository';
 
 export const repositories = [
   AccessRepository,
@@ -78,6 +80,7 @@ export const repositories = [
   OcrRepository,
   PartnerRepository,
   PersonRepository,
+  PluginRepository,
   ProcessRepository,
   SearchRepository,
   SessionRepository,
@@ -96,4 +99,5 @@ export const repositories = [
   ViewRepository,
   VersionHistoryRepository,
   WebsocketRepository,
+  WorkflowRepository,
 ];

server/src/repositories/plugin.repository.ts

@@ -0,0 +1,176 @@
+import { Injectable } from '@nestjs/common';
+import { Kysely } from 'kysely';
+import { jsonArrayFrom } from 'kysely/helpers/postgres';
+import { InjectKysely } from 'nestjs-kysely';
+import { readdir } from 'node:fs/promises';
+import { columns } from 'src/database';
+import { DummyValue, GenerateSql } from 'src/decorators';
+import { PluginManifestDto } from 'src/dtos/plugin-manifest.dto';
+import { DB } from 'src/schema';
+
+@Injectable()
+export class PluginRepository {
+  constructor(@InjectKysely() private db: Kysely<DB>) {}
+
+  /**
+   * Loads a plugin from a validated manifest file in a transaction.
+   * This ensures all plugin, filter, and action operations are atomic.
+   * @param manifest The validated plugin manifest
+   * @param basePath The base directory path where the plugin is located
+   */
+  async loadPlugin(manifest: PluginManifestDto, basePath: string) {
+    return this.db.transaction().execute(async (tx) => {
+      // Upsert the plugin
+      const plugin = await tx
+        .insertInto('plugin')
+        .values({
+          name: manifest.name,
+          title: manifest.title,
+          description: manifest.description,
+          author: manifest.author,
+          version: manifest.version,
+          wasmPath: `${basePath}/${manifest.wasm.path}`,
+        })
+        .onConflict((oc) =>
+          oc.column('name').doUpdateSet({
+            title: manifest.title,
+            description: manifest.description,
+            author: manifest.author,
+            version: manifest.version,
+            wasmPath: `${basePath}/${manifest.wasm.path}`,
+          }),
+        )
+        .returningAll()
+        .executeTakeFirstOrThrow();
+
+      const filters = manifest.filters
+        ? await tx
+            .insertInto('plugin_filter')
+            .values(
+              manifest.filters.map((filter) => ({
+                pluginId: plugin.id,
+                methodName: filter.methodName,
+                title: filter.title,
+                description: filter.description,
+                supportedContexts: filter.supportedContexts,
+                schema: filter.schema,
+              })),
+            )
+            .onConflict((oc) =>
+              oc.column('methodName').doUpdateSet((eb) => ({
+                pluginId: eb.ref('excluded.pluginId'),
+                title: eb.ref('excluded.title'),
+                description: eb.ref('excluded.description'),
+                supportedContexts: eb.ref('excluded.supportedContexts'),
+                schema: eb.ref('excluded.schema'),
+              })),
+            )
+            .returningAll()
+            .execute()
+        : [];
+
+      const actions = manifest.actions
+        ? await tx
+            .insertInto('plugin_action')
+            .values(
+              manifest.actions.map((action) => ({
+                pluginId: plugin.id,
+                methodName: action.methodName,
+                title: action.title,
+                description: action.description,
+                supportedContexts: action.supportedContexts,
+                schema: action.schema,
+              })),
+            )
+            .onConflict((oc) =>
+              oc.column('methodName').doUpdateSet((eb) => ({
+                pluginId: eb.ref('excluded.pluginId'),
+                title: eb.ref('excluded.title'),
+                description: eb.ref('excluded.description'),
+                supportedContexts: eb.ref('excluded.supportedContexts'),
+                schema: eb.ref('excluded.schema'),
+              })),
+            )
+            .returningAll()
+            .execute()
+        : [];
+
+      return { plugin, filters, actions };
+    });
+  }
+
+  async readDirectory(path: string) {
+    return readdir(path, { withFileTypes: true });
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getPlugin(id: string) {
+    return this.db
+      .selectFrom('plugin')
+      .select((eb) => [
+        ...columns.plugin,
+        jsonArrayFrom(
+          eb.selectFrom('plugin_filter').selectAll().whereRef('plugin_filter.pluginId', '=', 'plugin.id'),
+        ).as('filters'),
+        jsonArrayFrom(
+          eb.selectFrom('plugin_action').selectAll().whereRef('plugin_action.pluginId', '=', 'plugin.id'),
+        ).as('actions'),
+      ])
+      .where('plugin.id', '=', id)
+      .executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.STRING] })
+  getPluginByName(name: string) {
+    return this.db
+      .selectFrom('plugin')
+      .select((eb) => [
+        ...columns.plugin,
+        jsonArrayFrom(
+          eb.selectFrom('plugin_filter').selectAll().whereRef('plugin_filter.pluginId', '=', 'plugin.id'),
+        ).as('filters'),
+        jsonArrayFrom(
+          eb.selectFrom('plugin_action').selectAll().whereRef('plugin_action.pluginId', '=', 'plugin.id'),
+        ).as('actions'),
+      ])
+      .where('plugin.name', '=', name)
+      .executeTakeFirst();
+  }
+
+  @GenerateSql()
+  getAllPlugins() {
+    return this.db
+      .selectFrom('plugin')
+      .select((eb) => [
+        ...columns.plugin,
+        jsonArrayFrom(
+          eb.selectFrom('plugin_filter').selectAll().whereRef('plugin_filter.pluginId', '=', 'plugin.id'),
+        ).as('filters'),
+        jsonArrayFrom(
+          eb.selectFrom('plugin_action').selectAll().whereRef('plugin_action.pluginId', '=', 'plugin.id'),
+        ).as('actions'),
+      ])
+      .orderBy('plugin.name')
+      .execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getFilter(id: string) {
+    return this.db.selectFrom('plugin_filter').selectAll().where('id', '=', id).executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getFiltersByPlugin(pluginId: string) {
+    return this.db.selectFrom('plugin_filter').selectAll().where('pluginId', '=', pluginId).execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getAction(id: string) {
+    return this.db.selectFrom('plugin_action').selectAll().where('id', '=', id).executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getActionsByPlugin(pluginId: string) {
+    return this.db.selectFrom('plugin_action').selectAll().where('pluginId', '=', pluginId).execute();
+  }
+}

server/src/repositories/storage.repository.ts

@@ -113,6 +113,10 @@ export class StorageRepository {
     }
   }
 
+  async readTextFile(filepath: string): Promise<string> {
+    return fs.readFile(filepath, 'utf8');
+  }
+
   async checkFileExists(filepath: string, mode = constants.F_OK): Promise<boolean> {
     try {
       await fs.access(filepath, mode);

server/src/repositories/workflow.repository.ts

@@ -0,0 +1,139 @@
+import { Injectable } from '@nestjs/common';
+import { Insertable, Kysely, Updateable } from 'kysely';
+import { InjectKysely } from 'nestjs-kysely';
+import { DummyValue, GenerateSql } from 'src/decorators';
+import { PluginTriggerType } from 'src/enum';
+import { DB } from 'src/schema';
+import { WorkflowActionTable, WorkflowFilterTable, WorkflowTable } from 'src/schema/tables/workflow.table';
+
+@Injectable()
+export class WorkflowRepository {
+  constructor(@InjectKysely() private db: Kysely<DB>) {}
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getWorkflow(id: string) {
+    return this.db.selectFrom('workflow').selectAll().where('id', '=', id).executeTakeFirst();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getWorkflowsByOwner(ownerId: string) {
+    return this.db.selectFrom('workflow').selectAll().where('ownerId', '=', ownerId).orderBy('name').execute();
+  }
+
+  @GenerateSql({ params: [PluginTriggerType.AssetCreate] })
+  getWorkflowsByTrigger(type: PluginTriggerType) {
+    return this.db
+      .selectFrom('workflow')
+      .selectAll()
+      .where('triggerType', '=', type)
+      .where('enabled', '=', true)
+      .execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID, PluginTriggerType.AssetCreate] })
+  getWorkflowByOwnerAndTrigger(ownerId: string, type: PluginTriggerType) {
+    return this.db
+      .selectFrom('workflow')
+      .selectAll()
+      .where('ownerId', '=', ownerId)
+      .where('triggerType', '=', type)
+      .where('enabled', '=', true)
+      .execute();
+  }
+
+  async createWorkflow(
+    workflow: Insertable<WorkflowTable>,
+    filters: Insertable<WorkflowFilterTable>[],
+    actions: Insertable<WorkflowActionTable>[],
+  ) {
+    return await this.db.transaction().execute(async (tx) => {
+      const createdWorkflow = await tx.insertInto('workflow').values(workflow).returningAll().executeTakeFirstOrThrow();
+
+      if (filters.length > 0) {
+        const newFilters = filters.map((filter) => ({
+          ...filter,
+          workflowId: createdWorkflow.id,
+        }));
+
+        await tx.insertInto('workflow_filter').values(newFilters).execute();
+      }
+
+      if (actions.length > 0) {
+        const newActions = actions.map((action) => ({
+          ...action,
+          workflowId: createdWorkflow.id,
+        }));
+        await tx.insertInto('workflow_action').values(newActions).execute();
+      }
+
+      return createdWorkflow;
+    });
+  }
+
+  async updateWorkflow(
+    id: string,
+    workflow: Updateable<WorkflowTable>,
+    filters: Insertable<WorkflowFilterTable>[] | undefined,
+    actions: Insertable<WorkflowActionTable>[] | undefined,
+  ) {
+    return await this.db.transaction().execute(async (trx) => {
+      if (Object.keys(workflow).length > 0) {
+        await trx.updateTable('workflow').set(workflow).where('id', '=', id).execute();
+      }
+
+      if (filters !== undefined) {
+        await trx.deleteFrom('workflow_filter').where('workflowId', '=', id).execute();
+        if (filters.length > 0) {
+          const filtersWithWorkflowId = filters.map((filter) => ({
+            ...filter,
+            workflowId: id,
+          }));
+          await trx.insertInto('workflow_filter').values(filtersWithWorkflowId).execute();
+        }
+      }
+
+      if (actions !== undefined) {
+        await trx.deleteFrom('workflow_action').where('workflowId', '=', id).execute();
+        if (actions.length > 0) {
+          const actionsWithWorkflowId = actions.map((action) => ({
+            ...action,
+            workflowId: id,
+          }));
+          await trx.insertInto('workflow_action').values(actionsWithWorkflowId).execute();
+        }
+      }
+
+      return await trx.selectFrom('workflow').selectAll().where('id', '=', id).executeTakeFirstOrThrow();
+    });
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  async deleteWorkflow(id: string) {
+    await this.db.deleteFrom('workflow').where('id', '=', id).execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getFilters(workflowId: string) {
+    return this.db
+      .selectFrom('workflow_filter')
+      .selectAll()
+      .where('workflowId', '=', workflowId)
+      .orderBy('order', 'asc')
+      .execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  async deleteFiltersByWorkflow(workflowId: string) {
+    await this.db.deleteFrom('workflow_filter').where('workflowId', '=', workflowId).execute();
+  }
+
+  @GenerateSql({ params: [DummyValue.UUID] })
+  getActions(workflowId: string) {
+    return this.db
+      .selectFrom('workflow_action')
+      .selectAll()
+      .where('workflowId', '=', workflowId)
+      .orderBy('order', 'asc')
+      .execute();
+  }
+}