feat(config): implement config lexicon

Signed-off-by: Maxence Lange <[email protected]>

lib/composer/composer/autoload_classmap.php

@@ -216,6 +216,9 @@
     'OCP\\Comments\\MessageTooLongException' => $baseDir . '/lib/public/Comments/MessageTooLongException.php',
     'OCP\\Comments\\NotFoundException' => $baseDir . '/lib/public/Comments/NotFoundException.php',
     'OCP\\Common\\Exception\\NotFoundException' => $baseDir . '/lib/public/Common/Exception/NotFoundException.php',
+    'OCP\\ConfigLexicon\\ConfigLexiconEntry' => $baseDir . '/lib/public/ConfigLexicon/ConfigLexiconEntry.php',
+    'OCP\\ConfigLexicon\\IConfigLexicon' => $baseDir . '/lib/public/ConfigLexicon/IConfigLexicon.php',
+    'OCP\\ConfigLexicon\\IConfigLexiconEntry' => $baseDir . '/lib/public/ConfigLexicon/IConfigLexiconEntry.php',
     'OCP\\Config\\BeforePreferenceDeletedEvent' => $baseDir . '/lib/public/Config/BeforePreferenceDeletedEvent.php',
     'OCP\\Config\\BeforePreferenceSetEvent' => $baseDir . '/lib/public/Config/BeforePreferenceSetEvent.php',
     'OCP\\Console\\ConsoleEvent' => $baseDir . '/lib/public/Console/ConsoleEvent.php',

lib/composer/composer/autoload_static.php

@@ -249,6 +249,9 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Comments\\MessageTooLongException' => __DIR__ . '/../../..' . '/lib/public/Comments/MessageTooLongException.php',
         'OCP\\Comments\\NotFoundException' => __DIR__ . '/../../..' . '/lib/public/Comments/NotFoundException.php',
         'OCP\\Common\\Exception\\NotFoundException' => __DIR__ . '/../../..' . '/lib/public/Common/Exception/NotFoundException.php',
+        'OCP\\ConfigLexicon\\ConfigLexiconEntry' => __DIR__ . '/../../..' . '/lib/public/ConfigLexicon/ConfigLexiconEntry.php',
+        'OCP\\ConfigLexicon\\IConfigLexicon' => __DIR__ . '/../../..' . '/lib/public/ConfigLexicon/IConfigLexicon.php',
+        'OCP\\ConfigLexicon\\IConfigLexiconEntry' => __DIR__ . '/../../..' . '/lib/public/ConfigLexicon/IConfigLexiconEntry.php',
         'OCP\\Config\\BeforePreferenceDeletedEvent' => __DIR__ . '/../../..' . '/lib/public/Config/BeforePreferenceDeletedEvent.php',
         'OCP\\Config\\BeforePreferenceSetEvent' => __DIR__ . '/../../..' . '/lib/public/Config/BeforePreferenceSetEvent.php',
         'OCP\\Console\\ConsoleEvent' => __DIR__ . '/../../..' . '/lib/public/Console/ConsoleEvent.php',

lib/private/AppConfig.php

@@ -38,6 +38,9 @@
 
 use InvalidArgumentException;
 use JsonException;
+use OC\AppFramework\Bootstrap\Coordinator;
+use OCP\ConfigLexicon\ConfigLexiconEntry;
+use OCP\ConfigLexicon\IConfigLexiconEntry;
 use OCP\DB\Exception as DBException;
 use OCP\DB\QueryBuilder\IQueryBuilder;
 use OCP\Exceptions\AppConfigIncorrectTypeException;
@@ -82,6 +85,8 @@ class AppConfig implements IAppConfig {
 	private array $valueTypes = [];  // type for all config values
 	private bool $fastLoaded = false;
 	private bool $lazyLoaded = false;
+	/** @var array<array-key, array{entries: array<array-key, IConfigLexiconEntry>, strict: bool}> ['app_id' => ['strict' => bool, 'entries' => ['config_key' => IConfigLexiconEntry[]]] */
+	private array $configLexiconDetails = [];
 
 	/**
 	 * $migrationCompleted is only needed to manage the previous structure
@@ -457,6 +462,7 @@ private function getTypedValue(
 		int $type
 	): string {
 		$this->assertParams($app, $key, valueType: $type);
+		$this->compareRegisteredConfigValues($app, $key, $lazy, $type, $default);
 		$this->loadConfig($lazy);
 
 		/**
@@ -748,6 +754,7 @@ private function setTypedValue(
 		int $type
 	): bool {
 		$this->assertParams($app, $key);
+		$this->compareRegisteredConfigValues($app, $key, $lazy, $type);
 		$this->loadConfig($lazy);
 
 		$sensitive = $this->isTyped(self::VALUE_SENSITIVE, $type);
@@ -1567,4 +1574,74 @@ private function getSensitiveKeys(string $app): array {
 	public function clearCachedConfig(): void {
 		$this->clearCache();
 	}
+
+	/**
+	 * verify and compare current use of config values with defined lexicon
+	 *
+	 * @throws AppConfigUnknownKeyException
+	 * @throws AppConfigTypeConflictException
+	 */
+	private function compareRegisteredConfigValues(
+		string $app,
+		string $key,
+		bool &$lazy,
+		int &$type,
+		string &$default = '',
+	): void {
+		$configDetails = $this->getConfigDetailsFromLexicon($app);
+		if (!array_key_exists($key, $configDetails['entries'])) {
+			if ($configDetails['strict'] === true) {
+				throw new AppConfigUnknownKeyException('The key ' . $app . '/' . $key . ' is not defined in the config lexicon');
+			}
+			return;
+		}
+
+		/** @var ConfigLexiconEntry $configValue */
+		$configValue = $configDetails['entries'][$key];
+		$type &= ~self::VALUE_SENSITIVE;
+
+		if ($configValue->getValueType() !== match($type) {
+			self::VALUE_STRING => IConfigLexiconEntry::TYPE_STRING,
+			self::VALUE_INT => IConfigLexiconEntry::TYPE_INT,
+			self::VALUE_FLOAT => IConfigLexiconEntry::TYPE_FLOAT,
+			self::VALUE_BOOL => IConfigLexiconEntry::TYPE_BOOL,
+			self::VALUE_ARRAY => IConfigLexiconEntry::TYPE_ARRAY,
+		}) {
+			throw new AppConfigTypeConflictException('The key ' . $app . '/' . $key . ' is typed incorrectly in relation to the config lexicon');
+		}
+
+		$lazy = $configValue->isLazy();
+		$default = $configValue->getDefault() ?? $default;
+		if ($configValue->isSensitive()) {
+			$type |= self::VALUE_SENSITIVE;
+		}
+		if ($configValue->isDeprecated()) {
+			$this->logger->notice('config value ' . $app . '/' . $key . ' is set as deprecated.');
+		}
+	}
+
+	/**
+	 * extract details from registered $appId's config lexicon
+	 *
+	 * @param string $appId
+	 *
+	 * @return array{entries: array<array-key, IConfigLexiconEntry>, strict: bool}
+	 */
+	private function getConfigDetailsFromLexicon(string $appId): array {
+		if (!array_key_exists($appId, $this->configLexiconDetails)) {
+			$entries = [];
+			$bootstrapCoordinator = \OCP\Server::get(Coordinator::class);
+			$configLexicon = $bootstrapCoordinator->getRegistrationContext()?->getConfigLexicon($appId);
+			foreach ($configLexicon?->getAppConfigs() ?? [] as $configEntry) {
+				$entries[$configEntry->getKey()] = $configEntry;
+			}
+
+			$this->configLexiconDetails[$appId] = [
+				'entries' => $entries,
+				'strict' => $configLexicon?->isStrict() ?? false
+			];
+		}
+
+		return $this->configLexiconDetails[$appId];
+	}
 }

lib/private/AppFramework/Bootstrap/RegistrationContext.php

@@ -41,6 +41,7 @@
 use OCP\Calendar\Room\IBackend as IRoomBackend;
 use OCP\Capabilities\ICapability;
 use OCP\Collaboration\Reference\IReferenceProvider;
+use OCP\ConfigLexicon\IConfigLexicon;
 use OCP\Dashboard\IManager;
 use OCP\Dashboard\IWidget;
 use OCP\EventDispatcher\IEventDispatcher;
@@ -160,6 +161,9 @@ class RegistrationContext {
 	/** @var ServiceRegistration<IDeclarativeSettingsForm>[] */
 	private array $declarativeSettings = [];
 
+	/** @var array<array-key, string> */
+	private array $configLexiconClasses = [];
+
 	/** @var ServiceRegistration<ITeamResourceProvider>[] */
 	private array $teamResourceProviders = [];
 
@@ -411,6 +415,13 @@ public function registerDeclarativeSettings(string $declarativeSettingsClass): v
 					$declarativeSettingsClass
 				);
 			}
+
+			public function registerConfigLexicon(string $configLexiconClass): void {
+				$this->context->registerConfigLexicon(
+					$this->appId,
+					$configLexiconClass
+				);
+			}
 		};
 	}
 
@@ -590,6 +601,13 @@ public function registerDeclarativeSettings(string $appId, string $declarativeSe
 		$this->declarativeSettings[] = new ServiceRegistration($appId, $declarativeSettingsClass);
 	}
 
+	/**
+	 * @psalm-param class-string<IConfigLexicon> $configLexiconClass
+	 */
+	public function registerConfigLexicon(string $appId, string $configLexiconClass): void {
+		$this->configLexiconClasses[$appId] = $configLexiconClass;
+	}
+
 	/**
 	 * @param App[] $apps
 	 */
@@ -920,4 +938,20 @@ public function getTeamResourceProviders(): array {
 	public function getDeclarativeSettings(): array {
 		return $this->declarativeSettings;
 	}
+
+	/**
+	 * returns IConfigLexicon registered by the app.
+	 * null if none registered.
+	 *
+	 * @param string $appId
+	 *
+	 * @return IConfigLexicon|null
+	 */
+	public function getConfigLexicon(string $appId): ?IConfigLexicon {
+		if (!array_key_exists($appId, $this->configLexiconClasses)) {
+			return null;
+		}
+
+		return \OCP\Server::get($this->configLexiconClasses[$appId]);
+	}
 }

lib/public/AppFramework/Bootstrap/IRegistrationContext.php

@@ -410,4 +410,15 @@ public function registerSetupCheck(string $setupCheckClass): void;
 	 * @since 29.0.0
 	 */
 	public function registerDeclarativeSettings(string $declarativeSettingsClass): void;
+
+	/**
+	 * Register an implementation of \OCP\ConfigLexicon\IConfigLexicon that
+	 * will handle the implementation of config lexicon
+	 *
+	 * @param string $configLexiconClass
+	 * @psalm-param class-string<\OCP\ConfigLexicon\IConfigLexicon> $configLexiconClass
+	 * @return void
+	 * @since 30.0.0
+	 */
+	public function registerConfigLexicon(string $configLexiconClass): void;
 }