feat(core): Add cluster check interface and decorator (no-changelog)

packages/@n8n/decorators/package.json

@@ -30,6 +30,7 @@
     "zod": "catalog:"
   },
   "dependencies": {
+    "@n8n/api-types": "workspace:*",
     "@n8n/constants": "workspace:*",
     "@n8n/di": "workspace:*",
     "@n8n/permissions": "workspace:*",

packages/@n8n/decorators/src/cluster-check/__tests__/cluster-check-metadata.test.ts

@@ -0,0 +1,159 @@
+import { Container, Service } from '@n8n/di';
+
+import type { ClusterCheckContext, ClusterCheckResult, IClusterCheck } from '../cluster-check';
+import { ClusterCheck, ClusterCheckMetadata } from '../cluster-check-metadata';
+
+describe('ClusterCheckMetadata', () => {
+	let metadata: ClusterCheckMetadata;
+
+	beforeEach(() => {
+		metadata = new ClusterCheckMetadata();
+	});
+
+	it('should register check classes', () => {
+		class TestCheck implements IClusterCheck {
+			checkDescription = { name: 'test.check' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		metadata.register({ class: TestCheck });
+
+		expect(metadata.getClasses()).toContain(TestCheck);
+	});
+
+	it('should return registered classes in registration order', () => {
+		class FirstCheck implements IClusterCheck {
+			checkDescription = { name: 'first.check' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+		class SecondCheck implements IClusterCheck {
+			checkDescription = { name: 'second.check' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		metadata.register({ class: FirstCheck });
+		metadata.register({ class: SecondCheck });
+
+		expect(metadata.getClasses()).toEqual([FirstCheck, SecondCheck]);
+	});
+});
+
+describe('@ClusterCheck decorator', () => {
+	let metadata: ClusterCheckMetadata;
+
+	beforeEach(() => {
+		vi.resetAllMocks();
+
+		metadata = new ClusterCheckMetadata();
+		Container.set(ClusterCheckMetadata, metadata);
+	});
+
+	it('should register the decorated class in ClusterCheckMetadata', () => {
+		@ClusterCheck()
+		class TestCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.test' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		const registered = metadata.getClasses();
+
+		expect(registered).toContain(TestCheck);
+		expect(registered).toHaveLength(1);
+	});
+
+	it('should register multiple decorated classes', () => {
+		@ClusterCheck()
+		class VersionCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.versionMismatch' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		@ClusterCheck()
+		class LeaderCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.leaderMissing' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		const registered = metadata.getClasses();
+
+		expect(registered).toContain(VersionCheck);
+		expect(registered).toContain(LeaderCheck);
+		expect(registered).toHaveLength(2);
+	});
+
+	it('should apply @Service() so the class is resolvable via DI', () => {
+		@ClusterCheck()
+		class TestCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.test' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		expect(Container.has(TestCheck)).toBe(true);
+
+		const instance = Container.get(TestCheck);
+
+		expect(instance).toBeInstanceOf(TestCheck);
+		expect(instance.checkDescription).toEqual({ name: 'cluster.test' });
+	});
+
+	it('should support checks with constructor-injected dependencies', () => {
+		@Service()
+		class Logger {
+			log(message: string) {
+				return message;
+			}
+		}
+
+		@ClusterCheck()
+		class TestCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.test' };
+			constructor(private readonly logger: Logger) {}
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				this.logger.log('run');
+				return {};
+			}
+		}
+
+		const instance = Container.get(TestCheck);
+
+		expect(instance).toBeInstanceOf(TestCheck);
+	});
+
+	it('should expose different description names for different checks', () => {
+		@ClusterCheck()
+		class VersionCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.versionMismatch', displayName: 'Version Mismatch' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		@ClusterCheck()
+		class LeaderCheck implements IClusterCheck {
+			checkDescription = { name: 'cluster.leaderMissing', displayName: 'Leader Missing' };
+			async run(_context: ClusterCheckContext): Promise<ClusterCheckResult> {
+				return {};
+			}
+		}
+
+		const versionInstance = Container.get(VersionCheck);
+		const leaderInstance = Container.get(LeaderCheck);
+
+		expect(versionInstance.checkDescription.name).toBe('cluster.versionMismatch');
+		expect(leaderInstance.checkDescription.name).toBe('cluster.leaderMissing');
+	});
+});

packages/@n8n/decorators/src/cluster-check/cluster-check-metadata.ts

@@ -0,0 +1,143 @@
+import { Container, Service } from '@n8n/di';
+
+import { ClusterCheckClass } from './cluster-check';
+
+/**
+ * Registry entry for a cluster check.
+ *
+ * Lightweight wrapper around the check class constructor, modelled on
+ * `ContextEstablishmentHookEntry`. Kept as a wrapper (rather than storing the
+ * class directly) so the entry shape can grow — e.g. module source, feature
+ * flag, license flag — without breaking the registration API.
+ *
+ * @internal
+ */
+type ClusterCheckEntry = {
+	/** The check class constructor for DI container instantiation. */
+	class: ClusterCheckClass;
+};
+
+/**
+ * Low-level metadata registry for cluster checks.
+ *
+ * `ClusterCheckMetadata` is a simple collection of every class decorated with
+ * `@ClusterCheck()`. It is populated automatically at module load time, before
+ * the Leader Service starts, so checks are discoverable without any manual
+ * registration code.
+ *
+ * **Architecture:**
+ * ```
+ * @ClusterCheck()   →   ClusterCheckMetadata   →   Cluster Check Registry   →   Leader Service
+ *   (registration)         (collection)               (instantiation)              (execution)
+ * ```
+ *
+ * **Responsibilities kept here:**
+ * - Storing registered check classes.
+ * - Exposing them for downstream consumers.
+ *
+ * **Responsibilities explicitly NOT here:**
+ * - Instantiating checks (DI container).
+ * - Validating name uniqueness (higher-level registry).
+ * - Executing checks (Leader Service).
+ *
+ * @see ClusterCheck decorator for automatic registration.
+ * @see IClusterCheck for the check contract.
+ */
+@Service()
+export class ClusterCheckMetadata {
+	/**
+	 * Internal collection of registered cluster check entries.
+	 *
+	 * Uses `Set` for efficient deduplication (though duplicate registration
+	 * should not occur with correct decorator usage).
+	 */
+	private readonly clusterChecks: Set<ClusterCheckEntry> = new Set();
+
+	/**
+	 * Registers a cluster check class in the metadata collection.
+	 *
+	 * Called automatically by the `@ClusterCheck()` decorator at module load
+	 * time. Should not be called directly by application code.
+	 *
+	 * Name uniqueness and any other semantic validation is the responsibility
+	 * of the higher-level Cluster Check Registry, not this service.
+	 *
+	 * @param entry - The check class entry to register.
+	 * @internal Called by decorator only.
+	 */
+	register(entry: ClusterCheckEntry) {
+		this.clusterChecks.add(entry);
+	}
+
+	/**
+	 * Retrieves all registered check class constructors in registration order.
+	 *
+	 * This is the primary method consumed by the Cluster Check Registry to
+	 * instantiate checks via the DI container.
+	 *
+	 * @returns Array of check class constructors ready for DI instantiation.
+	 *
+	 * @example
+	 * ```typescript
+	 * @Service()
+	 * export class ClusterCheckRegistry {
+	 *   constructor(private readonly metadata: ClusterCheckMetadata) {
+	 *     this.checks = this.metadata.getClasses().map((cls) => Container.get(cls));
+	 *   }
+	 * }
+	 * ```
+	 */
+	getClasses() {
+		return [...this.clusterChecks.values()].map((entry) => entry.class);
+	}
+}
+
+/**
+ * Class decorator that registers a cluster check for auto-discovery.
+ *
+ * Performs two distinct operations at class-definition time:
+ * 1. **Registers** the class in {@link ClusterCheckMetadata} so the higher-level
+ *    registry can discover it without manual wiring.
+ * 2. **Enables DI** by applying `@Service()`, making the class constructor
+ *    resolvable via `Container.get()` (including dependencies).
+ *
+ * The decorator takes no arguments — all check metadata lives on the check
+ * instance itself via {@link IClusterCheck.checkDescription}.
+ *
+ * **Requirements:**
+ * - Decorated class MUST implement {@link IClusterCheck}.
+ * - Decorated class MUST expose a `checkDescription` with a unique `name`.
+ *
+ * **Notes:**
+ * - Registration happens eagerly at module load, not lazily.
+ * - Duplicate decoration of the same class is safe (`Set` deduplicates).
+ * - Checks are registered as singletons via `@Service()`.
+ *
+ * @example
+ * ```typescript
+ * @ClusterCheck()
+ * export class VersionMismatchCheck implements IClusterCheck {
+ *   checkDescription = {
+ *     name: 'cluster.versionMismatch',
+ *     displayName: 'Cluster Version Mismatch',
+ *   };
+ *
+ *   async run({ currentState }: ClusterCheckContext): Promise<ClusterCheckResult> {
+ *     // ... check logic
+ *     return {};
+ *   }
+ * }
+ * ```
+ *
+ * @returns A class decorator that registers the check and enables DI for it.
+ */
+export const ClusterCheck =
+	<T extends ClusterCheckClass>() =>
+	(target: T) => {
+		Container.get(ClusterCheckMetadata).register({
+			class: target,
+		});
+
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+		return Service()(target);
+	};