From a9e2a38b0e8aca851284cc4058964057c05323da Mon Sep 17 00:00:00 2001 From: Maxence Lange Date: Sat, 31 Aug 2024 21:30:07 -0100 Subject: [PATCH] feat(preferences): IUserPreferences Signed-off-by: Maxence Lange --- .../Version31000Date20240814184402.php | 39 + lib/composer/composer/autoload_classmap.php | 9 + lib/composer/composer/autoload_static.php | 9 + lib/private/Server.php | 2 + lib/private/UserPreferences.php | 1483 +++++++++++++++++ .../Exceptions/IncorrectTypeException.php | 15 + .../Exceptions/TypeConflictException.php | 15 + .../Exceptions/UnknownKeyException.php | 15 + .../Exceptions/UserPreferencesException.php | 17 + .../UserPreferences/IUserPreferences.php | 517 ++++++ lib/public/UserPreferences/ValueType.php | 111 ++ .../UserPreferences/ValueTypeDefinition.php | 30 + version.php | 2 +- 13 files changed, 2263 insertions(+), 1 deletion(-) create mode 100644 core/Migrations/Version31000Date20240814184402.php create mode 100644 lib/private/UserPreferences.php create mode 100644 lib/public/UserPreferences/Exceptions/IncorrectTypeException.php create mode 100644 lib/public/UserPreferences/Exceptions/TypeConflictException.php create mode 100644 lib/public/UserPreferences/Exceptions/UnknownKeyException.php create mode 100644 lib/public/UserPreferences/Exceptions/UserPreferencesException.php create mode 100644 lib/public/UserPreferences/IUserPreferences.php create mode 100644 lib/public/UserPreferences/ValueType.php create mode 100644 lib/public/UserPreferences/ValueTypeDefinition.php diff --git a/core/Migrations/Version31000Date20240814184402.php b/core/Migrations/Version31000Date20240814184402.php new file mode 100644 index 0000000000000..482c548a074ff --- /dev/null +++ b/core/Migrations/Version31000Date20240814184402.php @@ -0,0 +1,39 @@ +getTable('preferences'); + $table->addColumn('lazy', Types::SMALLINT, ['notnull' => true, 'default' => 0, 'length' => 1, 'unsigned' => true]); + $table->addColumn('type', Types::INTEGER, ['notnull' => true, 'default' => 2, 'unsigned' => true]); + $table->addIndex(['userid', 'lazy'], 'up_uid_lazy_i'); + + return $schema; + } +} diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php index b8d0dd35f123d..bbd04b64902fb 100644 --- a/lib/composer/composer/autoload_classmap.php +++ b/lib/composer/composer/autoload_classmap.php @@ -832,6 +832,13 @@ 'OCP\\UserMigration\\ISizeEstimationMigrator' => $baseDir . '/lib/public/UserMigration/ISizeEstimationMigrator.php', 'OCP\\UserMigration\\TMigratorBasicVersionHandling' => $baseDir . '/lib/public/UserMigration/TMigratorBasicVersionHandling.php', 'OCP\\UserMigration\\UserMigrationException' => $baseDir . '/lib/public/UserMigration/UserMigrationException.php', + 'OCP\\UserPreferences\\Exceptions\\IncorrectTypeException' => $baseDir . '/lib/public/UserPreferences/Exceptions/IncorrectTypeException.php', + 'OCP\\UserPreferences\\Exceptions\\TypeConflictException' => $baseDir . '/lib/public/UserPreferences/Exceptions/TypeConflictException.php', + 'OCP\\UserPreferences\\Exceptions\\UnknownKeyException' => $baseDir . '/lib/public/UserPreferences/Exceptions/UnknownKeyException.php', + 'OCP\\UserPreferences\\Exceptions\\UserPreferencesException' => $baseDir . '/lib/public/UserPreferences/Exceptions/UserPreferencesException.php', + 'OCP\\UserPreferences\\IUserPreferences' => $baseDir . '/lib/public/UserPreferences/IUserPreferences.php', + 'OCP\\UserPreferences\\ValueType' => $baseDir . '/lib/public/UserPreferences/ValueType.php', + 'OCP\\UserPreferences\\ValueTypeDefinition' => $baseDir . '/lib/public/UserPreferences/ValueTypeDefinition.php', 'OCP\\UserStatus\\IManager' => $baseDir . '/lib/public/UserStatus/IManager.php', 'OCP\\UserStatus\\IProvider' => $baseDir . '/lib/public/UserStatus/IProvider.php', 'OCP\\UserStatus\\IUserStatus' => $baseDir . '/lib/public/UserStatus/IUserStatus.php', @@ -1374,6 +1381,7 @@ 'OC\\Core\\Migrations\\Version30000Date20240717111406' => $baseDir . '/core/Migrations/Version30000Date20240717111406.php', 'OC\\Core\\Migrations\\Version30000Date20240814180800' => $baseDir . '/core/Migrations/Version30000Date20240814180800.php', 'OC\\Core\\Migrations\\Version30000Date20240815080800' => $baseDir . '/core/Migrations/Version30000Date20240815080800.php', + 'OC\\Core\\Migrations\\Version31000Date20240814184402' => $baseDir . '/core/Migrations/Version31000Date20240814184402.php', 'OC\\Core\\Notification\\CoreNotifier' => $baseDir . '/core/Notification/CoreNotifier.php', 'OC\\Core\\ResponseDefinitions' => $baseDir . '/core/ResponseDefinitions.php', 'OC\\Core\\Service\\LoginFlowV2Service' => $baseDir . '/core/Service/LoginFlowV2Service.php', @@ -1983,6 +1991,7 @@ 'OC\\Updater\\Exceptions\\ReleaseMetadataException' => $baseDir . '/lib/private/Updater/Exceptions/ReleaseMetadataException.php', 'OC\\Updater\\ReleaseMetadata' => $baseDir . '/lib/private/Updater/ReleaseMetadata.php', 'OC\\Updater\\VersionCheck' => $baseDir . '/lib/private/Updater/VersionCheck.php', + 'OC\\UserPreferences' => $baseDir . '/lib/private/UserPreferences.php', 'OC\\UserStatus\\ISettableProvider' => $baseDir . '/lib/private/UserStatus/ISettableProvider.php', 'OC\\UserStatus\\Manager' => $baseDir . '/lib/private/UserStatus/Manager.php', 'OC\\User\\AvailabilityCoordinator' => $baseDir . '/lib/private/User/AvailabilityCoordinator.php', diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php index 646a41626b7b6..19c9018db05a0 100644 --- a/lib/composer/composer/autoload_static.php +++ b/lib/composer/composer/autoload_static.php @@ -865,6 +865,13 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OCP\\UserMigration\\ISizeEstimationMigrator' => __DIR__ . '/../../..' . '/lib/public/UserMigration/ISizeEstimationMigrator.php', 'OCP\\UserMigration\\TMigratorBasicVersionHandling' => __DIR__ . '/../../..' . '/lib/public/UserMigration/TMigratorBasicVersionHandling.php', 'OCP\\UserMigration\\UserMigrationException' => __DIR__ . '/../../..' . '/lib/public/UserMigration/UserMigrationException.php', + 'OCP\\UserPreferences\\Exceptions\\IncorrectTypeException' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/Exceptions/IncorrectTypeException.php', + 'OCP\\UserPreferences\\Exceptions\\TypeConflictException' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/Exceptions/TypeConflictException.php', + 'OCP\\UserPreferences\\Exceptions\\UnknownKeyException' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/Exceptions/UnknownKeyException.php', + 'OCP\\UserPreferences\\Exceptions\\UserPreferencesException' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/Exceptions/UserPreferencesException.php', + 'OCP\\UserPreferences\\IUserPreferences' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/IUserPreferences.php', + 'OCP\\UserPreferences\\ValueType' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/ValueType.php', + 'OCP\\UserPreferences\\ValueTypeDefinition' => __DIR__ . '/../../..' . '/lib/public/UserPreferences/ValueTypeDefinition.php', 'OCP\\UserStatus\\IManager' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IManager.php', 'OCP\\UserStatus\\IProvider' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IProvider.php', 'OCP\\UserStatus\\IUserStatus' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IUserStatus.php', @@ -1407,6 +1414,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OC\\Core\\Migrations\\Version30000Date20240717111406' => __DIR__ . '/../../..' . '/core/Migrations/Version30000Date20240717111406.php', 'OC\\Core\\Migrations\\Version30000Date20240814180800' => __DIR__ . '/../../..' . '/core/Migrations/Version30000Date20240814180800.php', 'OC\\Core\\Migrations\\Version30000Date20240815080800' => __DIR__ . '/../../..' . '/core/Migrations/Version30000Date20240815080800.php', + 'OC\\Core\\Migrations\\Version31000Date20240814184402' => __DIR__ . '/../../..' . '/core/Migrations/Version31000Date20240814184402.php', 'OC\\Core\\Notification\\CoreNotifier' => __DIR__ . '/../../..' . '/core/Notification/CoreNotifier.php', 'OC\\Core\\ResponseDefinitions' => __DIR__ . '/../../..' . '/core/ResponseDefinitions.php', 'OC\\Core\\Service\\LoginFlowV2Service' => __DIR__ . '/../../..' . '/core/Service/LoginFlowV2Service.php', @@ -2016,6 +2024,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2 'OC\\Updater\\Exceptions\\ReleaseMetadataException' => __DIR__ . '/../../..' . '/lib/private/Updater/Exceptions/ReleaseMetadataException.php', 'OC\\Updater\\ReleaseMetadata' => __DIR__ . '/../../..' . '/lib/private/Updater/ReleaseMetadata.php', 'OC\\Updater\\VersionCheck' => __DIR__ . '/../../..' . '/lib/private/Updater/VersionCheck.php', + 'OC\\UserPreferences' => __DIR__ . '/../../..' . '/lib/private/UserPreferences.php', 'OC\\UserStatus\\ISettableProvider' => __DIR__ . '/../../..' . '/lib/private/UserStatus/ISettableProvider.php', 'OC\\UserStatus\\Manager' => __DIR__ . '/../../..' . '/lib/private/UserStatus/Manager.php', 'OC\\User\\AvailabilityCoordinator' => __DIR__ . '/../../..' . '/lib/private/User/AvailabilityCoordinator.php', diff --git a/lib/private/Server.php b/lib/private/Server.php index 01d5bdac0b66f..848b81aa07dff 100644 --- a/lib/private/Server.php +++ b/lib/private/Server.php @@ -238,6 +238,7 @@ use OCP\User\Events\UserLoggedInWithCookieEvent; use OCP\User\Events\UserLoggedOutEvent; use OCP\User\IAvailabilityCoordinator; +use OCP\UserPreferences\IUserPreferences; use Psr\Container\ContainerExceptionInterface; use Psr\Container\ContainerInterface; use Psr\Log\LoggerInterface; @@ -606,6 +607,7 @@ public function __construct($webRoot, \OC\Config $config) { /** @deprecated 19.0.0 */ $this->registerDeprecatedAlias('AppConfig', \OC\AppConfig::class); $this->registerAlias(IAppConfig::class, \OC\AppConfig::class); + $this->registerAlias(IUserPreferences::class, \OC\UserPreferences::class); $this->registerService(IFactory::class, function (Server $c) { return new \OC\L10N\Factory( diff --git a/lib/private/UserPreferences.php b/lib/private/UserPreferences.php new file mode 100644 index 0000000000000..34df58c090d68 --- /dev/null +++ b/lib/private/UserPreferences.php @@ -0,0 +1,1483 @@ +>> ['user_id' => ['app_id' => ['key' => 'value']]] */ + private array $fastCache = []; // cache for normal preference keys + /** @var array>> ['user_id' => ['app_id' => ['key' => 'value']]] */ + private array $lazyCache = []; // cache for lazy preference keys + /** @var array>> ['user_id' => ['app_id' => ['key' => bitflag]]] */ + private array $valueTypes = []; // type for all preference values + /** @var array ['user_id' => bool] */ + private array $fastLoaded = []; + /** @var array ['user_id' => bool] */ + private array $lazyLoaded = []; + + public function __construct( + protected IDBConnection $connection, + protected LoggerInterface $logger, + protected ICrypto $crypto, + ) { + } + + /** + * @inheritDoc + * + * @param string $appId optional id of app + * + * @return string[] list of userIds + * @since 31.0.0 + */ + public function getUserIds(string $appId = ''): array { + $this->assertParams(app: $appId, allowEmptyUser: true, allowEmptyApp: true); + + $qb = $this->connection->getQueryBuilder(); + $qb->from('preferences'); + $qb->select('userid'); + $qb->groupBy('userid'); + if ($appId !== '') { + $qb->where($qb->expr()->eq('app_id', $qb->createNamedParameter($appId))); + } + + $result = $qb->executeQuery(); + $rows = $result->fetchAll(); + $userIds = []; + foreach ($rows as $row) { + $userIds[] = $row['userid']; + } + + return $userIds; + } + + /** + * @inheritDoc + * + * @return string[] list of app ids + * @since 31.0.0 + */ + public function getApps(string $userId): array { + $this->assertParams($userId, allowEmptyApp: true); + $this->loadPreferencesAll($userId); + $apps = array_merge(array_keys($this->fastCache[$userId]), array_keys($this->lazyCache[$userId])); + sort($apps); + + return array_values(array_unique($apps)); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * + * @return string[] list of stored preference keys + * @since 31.0.0 + */ + public function getKeys(string $userId, string $app): array { + $this->assertParams($userId, $app); + $this->loadPreferencesAll($userId); + $keys = array_merge(array_keys($this->fastCache[$userId][$app] ?? []), array_keys($this->lazyCache[$userId][$app] ?? [])); + sort($keys); + + return array_values(array_unique($keys)); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool|null $lazy TRUE to search within lazy loaded preferences, NULL to search within all preferences + * + * @return bool TRUE if key exists + * @since 31.0.0 + */ + public function hasKey(string $userId, string $app, string $key, ?bool $lazy = false): bool { + $this->assertParams($userId, $app, $key); + $this->loadPreferences($userId, $lazy); + + if ($lazy === null) { + $appCache = $this->getAllValues($userId, $app); + return isset($appCache[$key]); + } + + if ($lazy) { + return isset($this->lazyCache[$userId][$app][$key]); + } + + return isset($this->fastCache[$userId][$app][$key]); + } + + /** + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool|null $lazy TRUE to search within lazy loaded preferences, NULL to search within all preferences + * + * @return bool + * @throws UnknownKeyException if preference key is not known + * @since 29.0.0 + */ + public function isSensitive(string $userId, string $app, string $key, ?bool $lazy = false): bool { + $this->assertParams($userId, $app, $key); + $this->loadPreferences($userId, $lazy); + + if (!isset($this->valueTypes[$userId][$app][$key])) { + throw new UnknownKeyException('unknown preference key'); + } + + return $this->isTyped(ValueType::SENSITIVE, $this->valueTypes[$userId][$app][$key]); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app if of the app + * @param string $key preference key + * + * @return bool TRUE if preference is lazy loaded + * @throws UnknownKeyException if preference key is not known + * @see IUserPreferences for details about lazy loading + * @since 29.0.0 + */ + public function isLazy(string $userId, string $app, string $key): bool { + // there is a huge probability the non-lazy preferences are already loaded + if ($this->hasKey($userId, $app, $key, false)) { + return false; + } + + // key not found, we search in the lazy preferences + if ($this->hasKey($userId, $app, $key, true)) { + return true; + } + + throw new UnknownKeyException('unknown preference key'); + } + + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $prefix preference keys prefix to search + * @param bool $filtered TRUE to hide sensitive preference values. Value are replaced by {@see IConfig::SENSITIVE_VALUE} + * + * @return array [key => value] + * @since 31.0.0 + */ + public function getAllValues(string $userId, string $app, string $prefix = '', bool $filtered = false): array { + $this->assertParams($userId, $app, $prefix); + // if we want to filter values, we need to get sensitivity + $this->loadPreferencesAll($userId); + // array_merge() will remove numeric keys (here preference keys), so addition arrays instead + $values = $this->formatAppValues($userId, $app, ($this->fastCache[$userId][$app] ?? []) + ($this->lazyCache[$userId][$app] ?? [])); + $values = array_filter( + $values, + function (string $key) use ($prefix): bool { + return str_starts_with($key, $prefix); // filter values based on $prefix + }, ARRAY_FILTER_USE_KEY + ); + + if (!$filtered) { + return $values; + } + + $result = []; + foreach ($values as $key => $value) { + $result[$key] = $this->isTyped(ValueType::SENSITIVE, $this->valueTypes[$userId][$app][$key] ?? 0) ? IConfig::SENSITIVE_VALUE : $value; + } + + return $result; + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $key preference key + * @param bool $lazy search within lazy loaded preferences + * @param int|null $typedAs enforce type for the returned values ({@see ValueType::STRING} and others) + * + * @return array [appId => value] + * @since 31.0.0 + */ + public function searchValuesByApps(string $userId, string $key, bool $lazy = false, ?ValueType $typedAs = null): array { + $this->assertParams($userId, '', $key, allowEmptyApp: true); + $this->loadPreferences($userId, $lazy); + + /** @var array> $cache */ + if ($lazy) { + $cache = $this->lazyCache[$userId]; + } else { + $cache = $this->fastCache[$userId]; + } + + $values = []; + foreach (array_keys($cache) as $app) { + if (isset($cache[$app][$key])) { + $value = $cache[$app][$key]; + try { + $value = $this->convertTypedValue($value, $typedAs ?? $this->getValueType($userId, (string)$app, $key, $lazy)); + } catch (IncorrectTypeException|UnknownKeyException) { + } + $values[$app] = $value; + } + } + + return $values; + } + + /** + * @inheritDoc + * + * @param string $app id of the app + * @param string $key preference key + * @param ValueType|null $typedAs enforce type for the returned values + * @param array|null $userIds limit to a list of user ids + * + * @return array [userId => value] + * @since 31.0.0 + */ + public function searchValuesByUsers( + string $app, + string $key, + ?ValueType $typedAs = null, + ?array $userIds = null + ): array { + $this->assertParams('', $app, $key, allowEmptyUser: true); + + $qb = $this->connection->getQueryBuilder(); + $qb->select('userid', 'configvalue', 'type') + ->from('preferences') + ->where($qb->expr()->eq('appid', $qb->createNamedParameter($app))) + ->andWhere($qb->expr()->eq('configkey', $qb->createNamedParameter($key))); + + $values = []; + // this nested function will execute current Query and store result within $values. + $executeAndStoreValue = function(IQueryBuilder $qb) use (&$values, $typedAs): IResult { + $result = $qb->executeQuery(); + while ($row = $result->fetch()) { + $value = $row['configvalue']; + try { + $value = $this->convertTypedValue($value, $typedAs ?? $this->extractValueType($row['type'])); + } catch (IncorrectTypeException) { + } + $values[$row['userid']] = $value; + } + return $result; + }; + + // if no userIds to filter, we execute query as it is and returns all values ... + if ($userIds === null) { + $result = $executeAndStoreValue($qb); + $result->closeCursor(); + return $values; + } + + // if userIds to filter, we chunk the list and execute the same query multiple times until we get all values + $result = null; + $qb->andWhere($qb->expr()->in('userid', $qb->createParameter('userIds'))); + foreach (array_chunk($userIds, 50, true) as $chunk) { + $qb->setParameter('userIds', $chunk, IQueryBuilder::PARAM_STR_ARRAY); + $result = $executeAndStoreValue($qb); + } + $result?->closeCursor(); + + return $values; + } + + /** + * Get the preference value as string. + * If the value does not exist the given default will be returned. + * + * Set lazy to `null` to ignore it and get the value from either source. + * + * **WARNING:** Method is internal and **SHOULD** not be used, as it is better to get the value with a type. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $default preference value + * @param null|bool $lazy get preference as lazy loaded or not. can be NULL + * + * @return string the value or $default + * @throws TypeConflictException + * @internal + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see getValueString() + * @see getValueInt() + * @see getValueFloat() + * @see getValueBool() + * @see getValueArray() + */ + public function getValueMixed( + string $userId, + string $app, + string $key, + string $default = '', + ?bool $lazy = false + ): string { + try { + $lazy = ($lazy === null) ? $this->isLazy($userId, $app, $key) : $lazy; + } catch (UnknownKeyException) { + return $default; + } + + return $this->getTypedValue( + $userId, + $app, + $key, + $default, + $lazy, + ValueType::MIXED + ); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return string stored preference value or $default if not set in database + * @throws InvalidArgumentException if one of the argument format is invalid + * @throws TypeConflictException in case of conflict with the value type set in database + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function getValueString( + string $userId, + string $app, + string $key, + string $default = '', + bool $lazy = false + ): string { + return $this->getTypedValue($userId, $app, $key, $default, $lazy, ValueType::STRING); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param int $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return int stored preference value or $default if not set in database + * @throws InvalidArgumentException if one of the argument format is invalid + * @throws TypeConflictException in case of conflict with the value type set in database + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function getValueInt( + string $userId, + string $app, + string $key, + int $default = 0, + bool $lazy = false + ): int { + return (int)$this->getTypedValue($userId, $app, $key, (string)$default, $lazy, ValueType::INT); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param float $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return float stored preference value or $default if not set in database + * @throws InvalidArgumentException if one of the argument format is invalid + * @throws TypeConflictException in case of conflict with the value type set in database + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function getValueFloat( + string $userId, + string $app, + string $key, + float $default = 0, + bool $lazy = false + ): float { + return (float)$this->getTypedValue($userId, $app, $key, (string)$default, $lazy, ValueType::FLOAT); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return bool stored preference value or $default if not set in database + * @throws InvalidArgumentException if one of the argument format is invalid + * @throws TypeConflictException in case of conflict with the value type set in database + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function getValueBool( + string $userId, + string $app, + string $key, + bool $default = false, + bool $lazy = false + ): bool { + $b = strtolower($this->getTypedValue($userId, $app, $key, $default ? 'true' : 'false', $lazy, ValueType::BOOL)); + return in_array($b, ['1', 'true', 'yes', 'on']); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param array $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return array stored preference value or $default if not set in database + * @throws InvalidArgumentException if one of the argument format is invalid + * @throws TypeConflictException in case of conflict with the value type set in database + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function getValueArray( + string $userId, + string $app, + string $key, + array $default = [], + bool $lazy = false + ): array { + try { + $defaultJson = json_encode($default, JSON_THROW_ON_ERROR); + $value = json_decode($this->getTypedValue($userId, $app, $key, $defaultJson, $lazy, ValueType::ARRAY), true, flags: JSON_THROW_ON_ERROR); + + return is_array($value) ? $value : []; + } catch (JsonException) { + return []; + } + } + + /** + * @param string $userId + * @param string $app id of the app + * @param string $key preference key + * @param string $default default value + * @param bool $lazy search within lazy loaded preferences + * @param ValueType $type value type + * + * @return string + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + */ + private function getTypedValue( + string $userId, + string $app, + string $key, + string $default, + bool $lazy, + ValueType $type + ): string { + $this->assertParams($userId, $app, $key, valueType: $type); + $this->loadPreferences($userId, $lazy); + + /** + * We ignore check if mixed type is requested. + * If type of stored value is set as mixed, we don't filter. + * If type of stored value is defined, we compare with the one requested. + */ + $knownType = $this->valueTypes[$userId][$app][$key] ?? 0; + if (!$this->isTyped(ValueType::MIXED, $type->value) + && $knownType > 0 + && !$this->isTyped(ValueType::MIXED, $knownType) + && !$this->isTyped($type, $knownType)) { + $this->logger->warning('conflict with value type from database', ['app' => $app, 'key' => $key, 'type' => $type, 'knownType' => $knownType]); + throw new TypeConflictException('conflict with value type from database'); + } + + /** + * - the pair $app/$key cannot exist in both array, + * - we should still return an existing non-lazy value even if current method + * is called with $lazy is true + * + * This way, lazyCache will be empty until the load for lazy preferences value is requested. + */ + if (isset($this->lazyCache[$userId][$app][$key])) { + $value = $this->lazyCache[$userId][$app][$key]; + } elseif (isset($this->fastCache[$userId][$app][$key])) { + $value = $this->fastCache[$userId][$app][$key]; + } else { + return $default; + } + + $sensitive = $this->isTyped(ValueType::SENSITIVE, $knownType); + if ($sensitive && str_starts_with($value, self::ENCRYPTION_PREFIX)) { + // Only decrypt values that are stored encrypted + $value = $this->crypto->decrypt(substr($value, self::ENCRYPTION_PREFIX_LENGTH)); + } + + return $value; + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * + * @return ValueType type of the value + * @throws UnknownKeyException if preference key is not known + * @throws IncorrectTypeException if preferences value type is not known + * @since 31.0.0 + */ + public function getValueType(string $userId, string $app, string $key, ?bool $lazy = null): ValueType { + $this->assertParams($userId, $app, $key); + $this->loadPreferences($userId, $lazy); + + if (!isset($this->valueTypes[$userId][$app][$key])) { + throw new UnknownKeyException('unknown preference key'); + } + + return $this->extractValueType($this->valueTypes[$userId][$app][$key]); + } + + /** + * convert bitflag from value type to ValueType + * + * @param int $type + * + * @return ValueType + * @throws IncorrectTypeException + */ + private function extractValueType(int $type): ValueType { + $type &= ~ValueType::SENSITIVE->value; + + try { + return ValueType::from($type); + } catch (ValueError) { + throw new IncorrectTypeException('invalid value type'); + } + } + + /** + * Store a preference key and its value in database as VALUE_MIXED + * + * **WARNING:** Method is internal and **MUST** not be used as it is best to set a real value type + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $value preference value + * @param bool $lazy set preference as lazy loaded + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED + * @internal + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueString() + * @see setValueInt() + * @see setValueFloat() + * @see setValueBool() + * @see setValueArray() + */ + public function setValueMixed( + string $userId, + string $app, + string $key, + string $value, + bool $lazy = false, + bool $sensitive = false + ): bool { + return $this->setTypedValue( + $userId, + $app, + $key, + $value, + $lazy, + $sensitive, + ValueType::MIXED + ); + } + + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $value preference value + * @param bool $lazy set preference as lazy loaded + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function setValueString( + string $userId, + string $app, + string $key, + string $value, + bool $lazy = false, + bool $sensitive = false + ): bool { + return $this->setTypedValue( + $userId, + $app, + $key, + $value, + $lazy, + $sensitive, + ValueType::STRING + ); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param int $value preference value + * @param bool $lazy set preference as lazy loaded + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function setValueInt( + string $userId, + string $app, + string $key, + int $value, + bool $lazy = false, + bool $sensitive = false + ): bool { + if ($value > 2000000000) { + $this->logger->debug('You are trying to store an integer value around/above 2,147,483,647. This is a reminder that reaching this theoretical limit on 32 bits system will throw an exception.'); + } + + return $this->setTypedValue( + $userId, + $app, + $key, + (string)$value, + $lazy, + $sensitive, + ValueType::INT + ); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param float $value preference value + * @param bool $lazy set preference as lazy loaded + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function setValueFloat( + string $userId, + string $app, + string $key, + float $value, + bool $lazy = false, + bool $sensitive = false + ): bool { + return $this->setTypedValue( + $userId, + $app, + $key, + (string)$value, + $lazy, + $sensitive, + ValueType::FLOAT + ); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $value preference value + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function setValueBool( + string $userId, + string $app, + string $key, + bool $value, + bool $lazy = false + ): bool { + return $this->setTypedValue( + $userId, + $app, + $key, + ($value) ? '1' : '0', + $lazy, + false, + ValueType::BOOL + ); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param array $value preference value + * @param bool $lazy set preference as lazy loaded + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * + * @return bool TRUE if value was different, therefor updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @throws JsonException + * @since 29.0.0 + * @see IUserPreferences for explanation about lazy loading + */ + public function setValueArray( + string $userId, + string $app, + string $key, + array $value, + bool $lazy = false, + bool $sensitive = false + ): bool { + try { + return $this->setTypedValue( + $userId, + $app, + $key, + json_encode($value, JSON_THROW_ON_ERROR), + $lazy, + $sensitive, + ValueType::ARRAY + ); + } catch (JsonException $e) { + $this->logger->warning('could not setValueArray', ['app' => $app, 'key' => $key, 'exception' => $e]); + throw $e; + } + } + + /** + * Store a preference key and its value in database + * + * If preference key is already known with the exact same preference value and same sensitive/lazy status, the + * database is not updated. If preference value was previously stored as sensitive, status will not be + * altered. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $value preference value + * @param bool $lazy preferences set as lazy loaded + * @param ValueType $type value type + * + * @return bool TRUE if value was updated in database + * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one + * @see IUserPreferences for explanation about lazy loading + */ + private function setTypedValue( + string $userId, + string $app, + string $key, + string $value, + bool $lazy, + bool $sensitive, + ValueType $type + ): bool { + $this->assertParams($userId, $app, $key, valueType: $type); + $this->loadPreferences($userId, $lazy); + + $inserted = $refreshCache = false; + $origValue = $value; + $typeValue = $type->value; + if ($sensitive || ($this->hasKey($userId, $app, $key, $lazy) && $this->isSensitive($userId, $app, $key, $lazy))) { + $value = self::ENCRYPTION_PREFIX . $this->crypto->encrypt($value); + $typeValue = $typeValue | ValueType::SENSITIVE->value; + } + + if ($this->hasKey($userId, $app, $key, $lazy)) { + /** + * no update if key is already known with set lazy status and value is + * not different, unless sensitivity is switched from false to true. + */ + if ($origValue === $this->getTypedValue($userId, $app, $key, $value, $lazy, $type) + && (!$sensitive || $this->isSensitive($userId, $app, $key, $lazy))) { + return false; + } + } else { + /** + * if key is not known yet, we try to insert. + * It might fail if the key exists with a different lazy flag. + */ + try { + $insert = $this->connection->getQueryBuilder(); + $insert->insert('preferences') + ->setValue('userid', $insert->createNamedParameter($userId)) + ->setValue('appid', $insert->createNamedParameter($app)) + ->setValue('lazy', $insert->createNamedParameter(($lazy) ? 1 : 0, IQueryBuilder::PARAM_INT)) + ->setValue('type', $insert->createNamedParameter($typeValue, IQueryBuilder::PARAM_INT)) + ->setValue('configkey', $insert->createNamedParameter($key)) + ->setValue('configvalue', $insert->createNamedParameter($value)); + $insert->executeStatement(); + $inserted = true; + } catch (DBException $e) { + if ($e->getReason() !== DBException::REASON_UNIQUE_CONSTRAINT_VIOLATION) { + throw $e; // TODO: throw exception or just log and returns false !? + } + } + } + + /** + * We cannot insert a new row, meaning we need to update an already existing one + */ + if (!$inserted) { + $currType = $this->valueTypes[$userId][$app][$key] ?? 0; + if ($currType === 0) { // this might happen when switching lazy loading status + $this->loadPreferencesAll($userId); + $currType = $this->valueTypes[$userId][$app][$key] ?? 0; + } + + /** + * This should only happen during the upgrade process from 28 to 29. + * We only log a warning and set it to VALUE_MIXED. + */ + if ($currType === 0) { + $this->logger->warning('Value type is set to zero (0) in database. This is fine only during the upgrade process from 28 to 29.', ['app' => $app, 'key' => $key]); + $currType = ValueType::MIXED->value; + } + +// if ($type->isSensitive()) {} + + /** + * we only accept a different type from the one stored in database + * if the one stored in database is not-defined (VALUE_MIXED) + */ + if (!$this->isTyped(ValueType::MIXED, $currType) && + ($type->value | ValueType::SENSITIVE->value) !== ($currType | ValueType::SENSITIVE->value)) { + try { + $currType = $this->extractValueType($currType)->getDefinition(); + $type = $type->getDefinition(); + } catch (IncorrectTypeException) { + $type = $type->value; + } + throw new TypeConflictException('conflict between new type (' . $type . ') and old type (' . $currType . ')'); + } + + // we fix $type if the stored value, or the new value as it might be changed, is set as sensitive +// if ($sensitive || $this->isTyped(ValueType::SENSITIVE, $currType)) { +// $type |= ValueType::SENSITIVE; +// } + + if ($lazy !== $this->isLazy($userId, $app, $key)) { + $refreshCache = true; + } + + $update = $this->connection->getQueryBuilder(); + $update->update('preferences') + ->set('configvalue', $update->createNamedParameter($value)) + ->set('lazy', $update->createNamedParameter(($lazy) ? 1 : 0, IQueryBuilder::PARAM_INT)) + ->set('type', $update->createNamedParameter($typeValue, IQueryBuilder::PARAM_INT)) + ->where($update->expr()->eq('userid', $update->createNamedParameter($userId))) + ->andWhere($update->expr()->eq('appid', $update->createNamedParameter($app))) + ->andWhere($update->expr()->eq('configkey', $update->createNamedParameter($key))); + + $update->executeStatement(); + } + + if ($refreshCache) { + $this->clearCache($userId); + return true; + } + + // update local cache + if ($lazy) { + $this->lazyCache[$userId][$app][$key] = $value; + } else { + $this->fastCache[$userId][$app][$key] = $value; + } + $this->valueTypes[$userId][$app][$key] = $typeValue; + + return true; + } + + /** + * Change the type of preference value. + * + * **WARNING:** Method is internal and **MUST** not be used as it may break things. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param ValueType $type value type + * + * @return bool TRUE if database update were necessary + * @throws UnknownKeyException if $key is now known in database + * @throws IncorrectTypeException if $type is not valid + * @internal + * @since 31.0.0 + */ + public function updateType(string $userId, string $app, string $key, ValueType $type = ValueType::MIXED): bool { + $this->assertParams($userId, $app, $key, valueType: $type); + $this->loadPreferencesAll($userId); + $this->isLazy($userId, $app, $key); // confirm key exists + $typeValue = $type->value; + + $currType = $this->valueTypes[$userId][$app][$key]; + if (($typeValue | ValueType::SENSITIVE->value) === ($currType | ValueType::SENSITIVE->value)) { + return false; + } + + // we complete with sensitive flag if the stored value is set as sensitive + if ($this->isTyped(ValueType::SENSITIVE, $currType)) { + $typeValue = $typeValue | ValueType::SENSITIVE->value; + } + + $update = $this->connection->getQueryBuilder(); + $update->update('preferences') + ->set('type', $update->createNamedParameter($typeValue, IQueryBuilder::PARAM_INT)) + ->where($update->expr()->eq('userid', $update->createNamedParameter($userId))) + ->andWhere($update->expr()->eq('appid', $update->createNamedParameter($app))) + ->andWhere($update->expr()->eq('configkey', $update->createNamedParameter($key))); + $update->executeStatement(); + $this->valueTypes[$userId][$app][$key] = $typeValue; + + return true; + } + + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $sensitive TRUE to set as sensitive, FALSE to unset + * + * @return bool TRUE if entry was found in database and an update was necessary + * @since 31.0.0 + */ + public function updateSensitive(string $userId, string $app, string $key, bool $sensitive): bool { + $this->assertParams($userId, $app, $key); + $this->loadPreferencesAll($userId); + + try { + if ($sensitive === $this->isSensitive($userId, $app, $key, null)) { + return false; + } + } catch (UnknownKeyException $e) { + return false; + } + + $lazy = $this->isLazy($userId, $app, $key); + if ($lazy) { + $cache = $this->lazyCache; + } else { + $cache = $this->fastCache; + } + + if (!isset($cache[$userId][$app][$key])) { + throw new UnknownKeyException('unknown preference key'); + } + + /** + * type returned by getValueType() is already cleaned from sensitive flag + * we just need to update it based on $sensitive and store it in database + */ + $typeValue = $this->getValueType($userId, $app, $key)->value; + $value = $cache[$userId][$app][$key]; + if ($sensitive) { + $typeValue |= ValueType::SENSITIVE->value; + $value = self::ENCRYPTION_PREFIX . $this->crypto->encrypt($value); + } else { + $value = $this->crypto->decrypt(substr($value, self::ENCRYPTION_PREFIX_LENGTH)); + } + + $update = $this->connection->getQueryBuilder(); + $update->update('preferences') + ->set('type', $update->createNamedParameter($typeValue, IQueryBuilder::PARAM_INT)) + ->set('configvalue', $update->createNamedParameter($value)) + ->where($update->expr()->eq('userid', $update->createNamedParameter($userId))) + ->andWhere($update->expr()->eq('appid', $update->createNamedParameter($app))) + ->andWhere($update->expr()->eq('configkey', $update->createNamedParameter($key))); + $update->executeStatement(); + + $this->valueTypes[$userId][$app][$key] = $typeValue; + + return true; + } + + public function updateGlobalSensitive(string $app, string $key, bool $sensitive): void { + + } + + + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset + * + * @return bool TRUE if entry was found in database and an update was necessary + * @since 31.0.0 + */ + public function updateLazy(string $userId, string $app, string $key, bool $lazy): bool { + $this->assertParams($userId, $app, $key); + $this->loadPreferencesAll($userId); + + try { + if ($lazy === $this->isLazy($userId, $app, $key)) { + return false; + } + } catch (UnknownKeyException) { + return false; + } + + $update = $this->connection->getQueryBuilder(); + $update->update('preferences') + ->set('lazy', $update->createNamedParameter($lazy ? 1 : 0, IQueryBuilder::PARAM_INT)) + ->where($update->expr()->eq('userid', $update->createNamedParameter($userId))) + ->andWhere($update->expr()->eq('appid', $update->createNamedParameter($app))) + ->andWhere($update->expr()->eq('configkey', $update->createNamedParameter($key))); + $update->executeStatement(); + + // At this point, it is a lot safer to clean cache + $this->clearCache($userId); + + return true; + } + + public function updateGlobalLazy(string $app, string $key, bool $lazy): void { + + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * + * @return array + * @throws UnknownKeyException if preference key is not known in database + * @since 31.0.0 + */ + public function getDetails(string $userId, string $app, string $key): array { + $this->assertParams($userId, $app, $key); + $this->loadPreferencesAll($userId); + $lazy = $this->isLazy($userId, $app, $key); + + if ($lazy) { + $cache = $this->lazyCache[$userId]; + } else { + $cache = $this->fastCache[$userId]; + } + + $type = $this->getValueType($userId, $app, $key); + try { + $typeString = $type->getDefinition(); + } catch (IncorrectTypeException $e) { + $this->logger->warning('type stored in database is not correct', ['exception' => $e, 'type' => $type]); + $typeString = (string)$type->value; + } + + if (!isset($cache[$app][$key])) { + throw new UnknownKeyException('unknown preference key'); + } + + $value = $cache[$app][$key]; + $sensitive = $this->isSensitive($userId, $app, $key, null); + if ($sensitive && str_starts_with($value, self::ENCRYPTION_PREFIX)) { + $value = $this->crypto->decrypt(substr($value, self::ENCRYPTION_PREFIX_LENGTH)); + } + + return [ + 'userId' => $userId, + 'app' => $app, + 'key' => $key, + 'value' => $value, + 'type' => $type, + 'lazy' => $lazy, + 'typeString' => $typeString, + 'sensitive' => $sensitive + ]; + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * + * @since 31.0.0 + */ + public function deletePreference(string $userId, string $app, string $key): void { + $this->assertParams($userId, $app, $key); + $qb = $this->connection->getQueryBuilder(); + $qb->delete('preferences') + ->where($qb->expr()->eq('userid', $qb->createNamedParameter($userId))) + ->andWhere($qb->expr()->eq('appid', $qb->createNamedParameter($app))) + ->andWhere($qb->expr()->eq('configkey', $qb->createNamedParameter($key))); + $qb->executeStatement(); + + unset($this->lazyCache[$userId][$app][$key]); + unset($this->fastCache[$userId][$app][$key]); + } + + /** + * @inheritDoc + * + * @param string $app id of the app + * @param string $key preference key + * + * @since 31.0.0 + */ + public function deleteKey(string $app, string $key): void { + $this->assertParams('', $app, $key, allowEmptyUser: true); + $qb = $this->connection->getQueryBuilder(); + $qb->delete('preferences') + ->where($qb->expr()->eq('appid', $qb->createNamedParameter($app))) + ->andWhere($qb->expr()->eq('configkey', $qb->createNamedParameter($key))); + $qb->executeStatement(); + + $this->clearCacheAll(); + } + + /** + * @inheritDoc + * + * @param string $app id of the app + * + * @since 31.0.0 + */ + public function deleteApp(string $app): void { + $this->assertParams('', $app, allowEmptyUser: true); + $qb = $this->connection->getQueryBuilder(); + $qb->delete('preferences') + ->where($qb->expr()->eq('appid', $qb->createNamedParameter($app))); + $qb->executeStatement(); + + $this->clearCacheAll(); + } + + /** + * @inheritDoc + * + * @param string $userId id of the user + * @param bool $reload set to TRUE to refill cache instantly after clearing it. + * + * @since 31.0.0 + */ + public function clearCache(string $userId, bool $reload = false): void { + $this->assertParams($userId, allowEmptyApp: true); + $this->lazyLoaded[$userId] = $this->fastLoaded[$userId] = false; + $this->lazyCache[$userId] = $this->fastCache[$userId] = $this->valueTypes[$userId] = []; + + if (!$reload) { + return; + } + + $this->loadPreferencesAll($userId); + } + + /** + * @inheritDoc + * + * @since 31.0.0 + */ + public function clearCacheAll(): void { + $this->lazyLoaded = $this->fastLoaded = []; + $this->lazyCache = $this->fastCache = $this->valueTypes = []; + } + + + /** + * For debug purpose. + * Returns the cached data. + * + * @return array + * @since 31.0.0 + * @internal + */ + public function statusCache(): array { + return [ + 'fastLoaded' => $this->fastLoaded, + 'fastCache' => $this->fastCache, + 'lazyLoaded' => $this->lazyLoaded, + 'lazyCache' => $this->lazyCache, + 'valueTypes' => $this->valueTypes, + ]; + } + + /** + * @param ValueType $needle bitflag to search + * @param int $type known value + * + * @return bool TRUE if bitflag $needle is set in $type + */ + private function isTyped(ValueType $needle, int $type): bool { + return (($needle->value & $type) !== 0); + } + + /** + * Confirm the string set for app and key fit the database description + * + * @param string $userId + * @param string $app assert $app fit in database + * @param string $prefKey assert preference key fit in database + * @param bool $allowEmptyUser + * @param bool $allowEmptyApp $app can be empty string + * @param ValueType|null $valueType assert value type is only one type + */ + private function assertParams( + string $userId = '', + string $app = '', + string $prefKey = '', + bool $allowEmptyUser = false, + bool $allowEmptyApp = false, + ?ValueType $valueType = null + ): void { + if (!$allowEmptyUser && $userId === '') { + throw new InvalidArgumentException('userId cannot be an empty string'); + } + if (!$allowEmptyApp && $app === '') { + throw new InvalidArgumentException('app cannot be an empty string'); + } + if (strlen($userId) > self::USER_MAX_LENGTH) { + throw new InvalidArgumentException('Value (' . $userId . ') for userId is too long (' . self::USER_MAX_LENGTH . ')'); + } + if (strlen($app) > self::APP_MAX_LENGTH) { + throw new InvalidArgumentException('Value (' . $app . ') for app is too long (' . self::APP_MAX_LENGTH . ')'); + } + if (strlen($prefKey) > self::KEY_MAX_LENGTH) { + throw new InvalidArgumentException('Value (' . $prefKey . ') for key is too long (' . self::KEY_MAX_LENGTH . ')'); + } + if ($valueType !== null) { + $valueFlag = $valueType->value; + $valueFlag &= ~ValueType::SENSITIVE->value; + if (ValueType::tryFrom($valueFlag) === null) { + throw new InvalidArgumentException('Unknown value type'); + } + } + } + + private function loadPreferencesAll(string $userId): void { + $this->loadPreferences($userId, null); + } + + /** + * Load normal preferences or preferences set as lazy loaded + * + * @param bool|null $lazy set to TRUE to load preferences set as lazy loaded, set to NULL to load all preferences + */ + private function loadPreferences(string $userId, ?bool $lazy = false): void { + if ($this->isLoaded($userId, $lazy)) { + return; + } + + if (($lazy ?? true) !== false) { // if lazy is null or true, we debug log + $this->logger->debug('The loading of lazy UserPreferences values have been requested', ['exception' => new \RuntimeException('ignorable exception')]); + } + + $qb = $this->connection->getQueryBuilder(); + $qb->from('preferences'); + $qb->select('userid', 'appid', 'configkey', 'configvalue', 'type'); + $qb->where($qb->expr()->eq('userid', $qb->createNamedParameter($userId))); + + // we only need value from lazy when loadPreferences does not specify it + if ($lazy !== null) { + $qb->andWhere($qb->expr()->eq('lazy', $qb->createNamedParameter($lazy ? 1 : 0, IQueryBuilder::PARAM_INT))); + } else { + $qb->addSelect('lazy'); + } + + $result = $qb->executeQuery(); + $rows = $result->fetchAll(); + foreach ($rows as $row) { + if (($row['lazy'] ?? ($lazy ?? 0) ? 1 : 0) === 1) { + $this->lazyCache[$row['userid']][$row['appid']][$row['configkey']] = $row['configvalue'] ?? ''; + } else { + $this->fastCache[$row['userid']][$row['appid']][$row['configkey']] = $row['configvalue'] ?? ''; + } + $this->valueTypes[$row['userid']][$row['appid']][$row['configkey']] = (int)($row['type'] ?? 0); + } + $result->closeCursor(); + $this->setAsLoaded($userId, $lazy); + } + + /** + * if $lazy is: + * - false: will returns true if fast preferences are loaded + * - true : will returns true if lazy preferences are loaded + * - null : will returns true if both preferences are loaded + * + * @param string $userId + * @param bool $lazy + * + * @return bool + */ + private function isLoaded(string $userId, ?bool $lazy): bool { + if ($lazy === null) { + return ($this->lazyLoaded[$userId] ?? false) && ($this->fastLoaded[$userId] ?? false); + } + + return $lazy ? $this->lazyLoaded[$userId] ?? false : $this->fastLoaded[$userId] ?? false; + } + + /** + * if $lazy is: + * - false: set fast preferences as loaded + * - true : set lazy preferences as loaded + * - null : set both preferences as loaded + * + * @param string $userId + * @param bool $lazy + */ + private function setAsLoaded(string $userId, ?bool $lazy): void { + if ($lazy === null) { + $this->fastLoaded[$userId] = $this->lazyLoaded[$userId] = true; + return; + } + + if ($lazy) { + $this->lazyLoaded[$userId] = true; + } else { + $this->fastLoaded[$userId] = true; + } + } + + /** + * **Warning:** avoid default NULL value for $lazy as this will + * load all lazy values from the database + * + * @param string $app + * @param array $values ['key' => 'value'] + * @param bool|null $lazy + * + * @return array + */ + private function formatAppValues(string $userId, string $app, array $values, ?bool $lazy = null): array { + foreach($values as $key => $value) { + try { + $type = $this->getValueType($userId, $app, $key, $lazy); + } catch (UnknownKeyException $e) { + continue; + } + + $values[$key] = $this->convertTypedValue($value, $type); + } + + return $values; + } + + /** + * convert string value to the expected type + * + * @param string $value + * @param ValueType $type + * + * @return string|int|float|bool|array + */ + private function convertTypedValue(string $value, ValueType $type): string|int|float|bool|array { + switch ($type) { + case ValueType::INT: + return (int)$value; + case ValueType::FLOAT: + return (float)$value; + case ValueType::BOOL: + return in_array(strtolower($value), ['1', 'true', 'yes', 'on']); + case ValueType::ARRAY: + try { + return json_decode($value, true, flags: JSON_THROW_ON_ERROR); + } catch (JsonException) { + // ignoreable + } + break; + } + return $value; + } +} diff --git a/lib/public/UserPreferences/Exceptions/IncorrectTypeException.php b/lib/public/UserPreferences/Exceptions/IncorrectTypeException.php new file mode 100644 index 0000000000000..5c8f83dee5efe --- /dev/null +++ b/lib/public/UserPreferences/Exceptions/IncorrectTypeException.php @@ -0,0 +1,15 @@ + [key => value] + * @since 30.0.0 + */ + public function getAllValues(string $userId, string $app, string $prefix = '', bool $filtered = false): array; + + /** + * List all apps storing a specific preference key and its stored value. + * Returns an array with appId as key, stored value as value. + * + * @param string $userId id of the user + * @param string $key preference key + * @param bool $lazy search within lazy loaded preferences + * @param int|null $typedAs enforce type for the returned values {@see self::VALUE_STRING} and others + * + * @return array [appId => value] + * @since 31.0.0 + */ + public function searchValuesByApps(string $userId, string $key, bool $lazy = false, ?ValueType $typedAs = null): array; + + /** + * List all users storing a specific preference key and its stored value. + * Returns an array with userId as key, stored value as value. + * + * **Warning** + * + * @param string $app id of the app + * @param string $key preference key + * @param int|null $typedAs enforce type for the returned values {@see self::VALUE_STRING} and others + * + * @return array [userId => value] + * @since 31.0.0 + */ + public function searchValuesByUsers(string $app, string $key, ?ValueType $typedAs = null, ?array $userIds = null): array; + + /** + * Get user preference assigned to a preference key. + * If preference key is not found in database, default value is returned. + * If preference key is set as lazy loaded, the $lazy argument needs to be set to TRUE. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return string stored preference value or $default if not set in database + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see getValueInt() + * @see getValueFloat() + * @see getValueBool() + * @see getValueArray() + */ + public function getValueString(string $userId, string $app, string $key, string $default = '', bool $lazy = false): string; + + /** + * Get preference value assigned to a preference key. + * If preference key is not found in database, default value is returned. + * If preference key is set as lazy loaded, the $lazy argument needs to be set to TRUE. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param int $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return int stored preference value or $default if not set in database + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see getValueString() + * @see getValueFloat() + * @see getValueBool() + * @see getValueArray() + */ + public function getValueInt(string $userId, string $app, string $key, int $default = 0, bool $lazy = false): int; + + /** + * Get preference value assigned to a preference key. + * If preference key is not found in database, default value is returned. + * If preference key is set as lazy loaded, the $lazy argument needs to be set to TRUE. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param float $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return float stored preference value or $default if not set in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see getValueString() + * @see getValueInt() + * @see getValueBool() + * @see getValueArray() + */ + public function getValueFloat(string $userId, string $app, string $key, float $default = 0, bool $lazy = false): float; + + /** + * Get preference value assigned to a preference key. + * If preference key is not found in database, default value is returned. + * If preference key is set as lazy loaded, the $lazy argument needs to be set to TRUE. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return bool stored preference value or $default if not set in database + * @since 30.0.0 + * @see IUserPrefences for explanation about lazy loading + * @see getValueString() + * @see getValueInt() + * @see getValueFloat() + * @see getValueArray() + */ + public function getValueBool(string $userId, string $app, string $key, bool $default = false, bool $lazy = false): bool; + + /** + * Get preference value assigned to a preference key. + * If preference key is not found in database, default value is returned. + * If preference key is set as lazy loaded, the $lazy argument needs to be set to TRUE. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param array $default default value + * @param bool $lazy search within lazy loaded preferences + * + * @return array stored preference value or $default if not set in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see getValueString() + * @see getValueInt() + * @see getValueFloat() + * @see getValueBool() + */ + public function getValueArray(string $userId, string $app, string $key, array $default = [], bool $lazy = false): array; + + /** + * returns the type of preference value + * + * **WARNING:** ignore lazy filtering, all preference values are loaded from database + * unless lazy is set to false + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool|null $lazy + * + * @return ValueType type of the value + * @throws UnknownKeyException if preference key is not known + * @throws IncorrectTypeException if preferences value type is not known + * @since 31.0.0 + */ + public function getValueType(string $userId, string $app, string $key, ?bool $lazy = null): ValueType; + + /** + * Store a preference key and its value in database + * + * If preference key is already known with the exact same preference value, the database is not updated. + * If preference key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded. + * + * If preference value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param string $value preference value + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueInt() + * @see setValueFloat() + * @see setValueBool() + * @see setValueArray() + */ + public function setValueString(string $userId, string $app, string $key, string $value, bool $lazy = false, bool $sensitive = false): bool; + + /** + * Store a preference key and its value in database + * + * When handling huge value around and/or above 2,147,483,647, a debug log will be generated + * on 64bits system, as php int type reach its limit (and throw an exception) on 32bits when using huge numbers. + * + * When using huge numbers, it is advised to use {@see \OCP\Util::numericToNumber()} and {@see setValueString()} + * + * If preference key is already known with the exact same preference value, the database is not updated. + * If preference key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded. + * + * If preference value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param int $value preference value + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueString() + * @see setValueFloat() + * @see setValueBool() + * @see setValueArray() + */ + public function setValueInt(string $userId, string $app, string $key, int $value, bool $lazy = false, bool $sensitive = false): bool; + + /** + * Store a preference key and its value in database. + * + * If preference key is already known with the exact same preference value, the database is not updated. + * If preference key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded. + * + * If preference value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param float $value preference value + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueString() + * @see setValueInt() + * @see setValueBool() + * @see setValueArray() + */ + public function setValueFloat(string $userId, string $app, string $key, float $value, bool $lazy = false, bool $sensitive = false): bool; + + /** + * Store a preference key and its value in database + * + * If preference key is already known with the exact same preference value, the database is not updated. + * If preference key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded. + * + * If preference value was previously stored as lazy loaded, status cannot be altered without using {@see deleteKey()} first + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $value preference value + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @since 30.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueString() + * @see setValueInt() + * @see setValueFloat() + * @see setValueArray() + */ + public function setValueBool(string $userId, string $app, string $key, bool $value, bool $lazy = false): bool; + + /** + * Store a preference key and its value in database + * + * If preference key is already known with the exact same preference value, the database is not updated. + * If preference key is not supposed to be read during the boot of the cloud, it is advised to set it as lazy loaded. + * + * If preference value was previously stored as sensitive or lazy loaded, status cannot be altered without using {@see deleteKey()} first + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param array $value preference value + * @param bool $sensitive if TRUE value will be hidden when listing preference values. + * @param bool $lazy set preference as lazy loaded + * + * @return bool TRUE if value was different, therefor updated in database + * @since 31.0.0 + * @see IUserPreferences for explanation about lazy loading + * @see setValueString() + * @see setValueInt() + * @see setValueFloat() + * @see setValueBool() + */ + public function setValueArray(string $userId, string $app, string $key, array $value, bool $lazy = false, bool $sensitive = false): bool; + + /** + * switch sensitive status of a preference value + * + * **WARNING:** ignore lazy filtering, all preference values are loaded from database + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $sensitive TRUE to set as sensitive, FALSE to unset + * + * @return bool TRUE if database update were necessary + * @since 31.0.0 + */ + public function updateSensitive(string $userId, string $app, string $key, bool $sensitive): bool; + + /** + * switch sensitive loading status of a preference key for all users + * + * @param string $app id of the app + * @param string $key preference key + * @param bool $sensitive TRUE to set as sensitive, FALSE to unset + * @since 31.0.0 + */ + public function updateGlobalSensitive(string $app, string $key, bool $sensitive): void; + + /** + * switch lazy loading status of a preference value + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset + * + * @return bool TRUE if database update was necessary + * @since 31.0.0 + */ + public function updateLazy(string $userId, string $app, string $key, bool $lazy): bool; + + /** + * switch lazy loading status of a preference key for all users + * + * @param string $app id of the app + * @param string $key preference key + * @param bool $lazy TRUE to set as lazy loaded, FALSE to unset + * @since 31.0.0 + */ + public function updateGlobalLazy(string $app, string $key, bool $lazy): void; + + /** + * returns an array contains details about a preference value + * + * ``` + * [ + * "app" => "myapp", + * "key" => "mykey", + * "value" => "its_value", + * "lazy" => false, + * "type" => 4, + * "typeString" => "string", + * 'sensitive' => true + * ] + * ``` + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * + * @return array + * @throws UnknownKeyException if preference key is not known in database + * @since 31.0.0 + */ + public function getDetails(string $userId, string $app, string $key): array; + + /** + * Delete single preference key from database. + * + * @param string $userId id of the user + * @param string $app id of the app + * @param string $key preference key + * + * @since 31.0.0 + */ + public function deletePreference(string $userId, string $app, string $key): void; + + /** + * @param string $app id of the app + * @param string $key preference key + * + * @since 31.0.0 + */ + public function deleteKey(string $app, string $key): void; + + /** + * delete all preference keys linked to an app + * + * @param string $app id of the app + * @since 31.0.0 + */ + public function deleteApp(string $app): void; + + /** + * Clear the cache for a single user + * + * The cache will be rebuilt only the next time a user preference is requested. + * + * @param string $userId id of the user + * @param bool $reload set to TRUE to refill cache instantly after clearing it + * + * @since 31.0.0 + */ + public function clearCache(string $userId, bool $reload = false): void; + + /** + * Clear the cache for all users. + * The cache will be rebuilt only the next time a user preference is requested. + * + * @since 31.0.0 + */ + public function clearCacheAll(): void; +} diff --git a/lib/public/UserPreferences/ValueType.php b/lib/public/UserPreferences/ValueType.php new file mode 100644 index 0000000000000..57f65b504c7ff --- /dev/null +++ b/lib/public/UserPreferences/ValueType.php @@ -0,0 +1,111 @@ +fromValueDefinition(ValueTypeDefinition::from($definition)); + } catch (ValueError) { + throw new IncorrectTypeException('unknown string definition'); + } + } + + /** + * get ValueType from ValueTypeDefinition + * + * @param ValueTypeDefinition $definition + * + * @return self + * @throws IncorrectTypeException + * @since 31.0.0 + */ + public function fromValueDefinition(ValueTypeDefinition $definition): self { + try { + return match ($definition) { + ValueTypeDefinition::MIXED => self::MIXED, + ValueTypeDefinition::STRING => self::STRING, + ValueTypeDefinition::INT => self::INT, + ValueTypeDefinition::FLOAT => self::FLOAT, + ValueTypeDefinition::BOOL => self::BOOL, + ValueTypeDefinition::ARRAY => self::ARRAY + }; + } catch (UnhandledMatchError) { + throw new IncorrectTypeException('unknown definition ' . $definition->value); + } + } + + /** + * get string definition for current enum value + * + * @return string + * @throws IncorrectTypeException + * @since 31.0.0 + */ + public function getDefinition(): string { + return $this->getValueTypeDefinition()->value; + } + + /** + * get ValueTypeDefinition for current enum value + * + * @return ValueTypeDefinition + * @throws IncorrectTypeException + * @since 31.0.0 + */ + public function getValueTypeDefinition(): ValueTypeDefinition { + try { + /** @psalm-suppress UnhandledMatchCondition */ + return match ($this) { + self::MIXED => ValueTypeDefinition::MIXED, + self::STRING => ValueTypeDefinition::STRING, + self::INT => ValueTypeDefinition::INT, + self::FLOAT => ValueTypeDefinition::FLOAT, + self::BOOL => ValueTypeDefinition::BOOL, + self::ARRAY => ValueTypeDefinition::ARRAY, + }; + } catch (UnhandledMatchError) { + throw new IncorrectTypeException('unknown type definition ' . $this->value); + } + } +} diff --git a/lib/public/UserPreferences/ValueTypeDefinition.php b/lib/public/UserPreferences/ValueTypeDefinition.php new file mode 100644 index 0000000000000..116c20b3bafb0 --- /dev/null +++ b/lib/public/UserPreferences/ValueTypeDefinition.php @@ -0,0 +1,30 @@ +