Improve dispatcher

lib/composer/composer/autoload_classmap.php

@@ -156,6 +156,8 @@
     'OCP\\AppFramework\\Http\\FileDisplayResponse' => $baseDir . '/lib/public/AppFramework/Http/FileDisplayResponse.php',
     'OCP\\AppFramework\\Http\\ICallbackResponse' => $baseDir . '/lib/public/AppFramework/Http/ICallbackResponse.php',
     'OCP\\AppFramework\\Http\\IOutput' => $baseDir . '/lib/public/AppFramework/Http/IOutput.php',
+    'OCP\\AppFramework\\Http\\InvalidEnumParameterException' => $baseDir . '/lib/public/AppFramework/Http/InvalidEnumParameterException.php',
+    'OCP\\AppFramework\\Http\\InvalidStringParameterException' => $baseDir . '/lib/public/AppFramework/Http/InvalidStringParameterException.php',
     'OCP\\AppFramework\\Http\\JSONResponse' => $baseDir . '/lib/public/AppFramework/Http/JSONResponse.php',
     'OCP\\AppFramework\\Http\\NotFoundResponse' => $baseDir . '/lib/public/AppFramework/Http/NotFoundResponse.php',
     'OCP\\AppFramework\\Http\\ParameterOutOfRangeException' => $baseDir . '/lib/public/AppFramework/Http/ParameterOutOfRangeException.php',
@@ -1207,6 +1209,7 @@
     'OC\\AppFramework\\Http\\RequestId' => $baseDir . '/lib/private/AppFramework/Http/RequestId.php',
     'OC\\AppFramework\\Middleware\\AdditionalScriptsMiddleware' => $baseDir . '/lib/private/AppFramework/Middleware/AdditionalScriptsMiddleware.php',
     'OC\\AppFramework\\Middleware\\CompressionMiddleware' => $baseDir . '/lib/private/AppFramework/Middleware/CompressionMiddleware.php',
+    'OC\\AppFramework\\Middleware\\InvalidParameterMiddleware' => $baseDir . '/lib/private/AppFramework/Middleware/InvalidParameterMiddleware.php',
     'OC\\AppFramework\\Middleware\\MiddlewareDispatcher' => $baseDir . '/lib/private/AppFramework/Middleware/MiddlewareDispatcher.php',
     'OC\\AppFramework\\Middleware\\NotModifiedMiddleware' => $baseDir . '/lib/private/AppFramework/Middleware/NotModifiedMiddleware.php',
     'OC\\AppFramework\\Middleware\\OCSMiddleware' => $baseDir . '/lib/private/AppFramework/Middleware/OCSMiddleware.php',

lib/composer/composer/autoload_static.php

@@ -197,6 +197,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\FileDisplayResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/FileDisplayResponse.php',
         'OCP\\AppFramework\\Http\\ICallbackResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/ICallbackResponse.php',
         'OCP\\AppFramework\\Http\\IOutput' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/IOutput.php',
+        'OCP\\AppFramework\\Http\\InvalidEnumParameterException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/InvalidEnumParameterException.php',
+        'OCP\\AppFramework\\Http\\InvalidStringParameterException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/InvalidStringParameterException.php',
         'OCP\\AppFramework\\Http\\JSONResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/JSONResponse.php',
         'OCP\\AppFramework\\Http\\NotFoundResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/NotFoundResponse.php',
         'OCP\\AppFramework\\Http\\ParameterOutOfRangeException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/ParameterOutOfRangeException.php',
@@ -1248,6 +1250,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\AppFramework\\Http\\RequestId' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Http/RequestId.php',
         'OC\\AppFramework\\Middleware\\AdditionalScriptsMiddleware' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/AdditionalScriptsMiddleware.php',
         'OC\\AppFramework\\Middleware\\CompressionMiddleware' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/CompressionMiddleware.php',
+        'OC\\AppFramework\\Middleware\\InvalidParameterMiddleware' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/InvalidParameterMiddleware.php',
         'OC\\AppFramework\\Middleware\\MiddlewareDispatcher' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/MiddlewareDispatcher.php',
         'OC\\AppFramework\\Middleware\\NotModifiedMiddleware' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/NotModifiedMiddleware.php',
         'OC\\AppFramework\\Middleware\\OCSMiddleware' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Middleware/OCSMiddleware.php',

lib/private/AppFramework/DependencyInjection/DIContainer.php

@@ -16,6 +16,7 @@
 use OC\AppFramework\Http\Output;
 use OC\AppFramework\Middleware\AdditionalScriptsMiddleware;
 use OC\AppFramework\Middleware\CompressionMiddleware;
+use OC\AppFramework\Middleware\InvalidParameterMiddleware;
 use OC\AppFramework\Middleware\MiddlewareDispatcher;
 use OC\AppFramework\Middleware\NotModifiedMiddleware;
 use OC\AppFramework\Middleware\OCSMiddleware;
@@ -201,6 +202,7 @@ public function __construct(
 			$dispatcher->registerMiddleware($c->get(SameSiteCookieMiddleware::class));
 			$dispatcher->registerMiddleware($c->get(CORSMiddleware::class));
 			$dispatcher->registerMiddleware($c->get(OCSMiddleware::class));
+			$dispatcher->registerMiddleware($c->get(InvalidParameterMiddleware::class));
 
 			$securityMiddleware = new SecurityMiddleware(
 				$c->get(IRequest::class),

lib/private/AppFramework/Http/Dispatcher.php

@@ -16,6 +16,8 @@
 use OCP\App\IAppManager;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\Http\InvalidEnumParameterException;
+use OCP\AppFramework\Http\InvalidStringParameterException;
 use OCP\AppFramework\Http\ParameterOutOfRangeException;
 use OCP\AppFramework\Http\Response;
 use OCP\Diagnostics\IEventLogger;
@@ -160,6 +162,10 @@ private function executeController(Controller $controller, string $methodName):
 			} elseif ($value !== null && \in_array($type, $types, true)) {
 				settype($value, $type);
 				$this->ensureParameterValueSatisfiesRange($param, $value, $default);
+			} elseif ($value !== null && $type === 'string' && \is_string($value)) {
+				$this->ensureParameterValueSatisfiesStringConstraint($param, $value);
+			} elseif ($value !== null && $type !== null && !($value instanceof $type) && enum_exists($type) && is_a($type, \BackedEnum::class, true)) {
+				$value = $this->resolveBackedEnumValue($param, $type, $value);
 			} elseif ($value === null && $type !== null && $this->appContainer->has($type)) {
 				$value = $this->appContainer->get($type);
 			}
@@ -225,4 +231,40 @@ private function ensureParameterValueSatisfiesRange(string $param, $value, $defa
 			}
 		}
 	}
+
+	/**
+	 * @throws InvalidStringParameterException
+	 */
+	private function ensureParameterValueSatisfiesStringConstraint(string $param, string $value): void {
+		if (!$this->reflector->satisfiesStringConstraint($param, $value)) {
+			throw new InvalidStringParameterException($param, $this->reflector->getStringConstraint($param));
+		}
+	}
+
+	/**
+	 * @template T of \BackedEnum
+	 * @psalm-param class-string<T> $enumClass
+	 * @psalm-param mixed $value
+	 * @psalm-return T
+	 * @throws InvalidEnumParameterException
+	 */
+	private function resolveBackedEnumValue(string $param, string $enumClass, $value): \BackedEnum {
+		if (!is_scalar($value)) {
+			throw new InvalidEnumParameterException($param, get_debug_type($value), $enumClass);
+		}
+
+		$backingType = (new \ReflectionEnum($enumClass))->getBackingType();
+		assert($backingType instanceof \ReflectionNamedType);
+		$backingType = $backingType->getName();
+		if ($backingType === 'int') {
+			if (!is_numeric($value)) {
+				throw new InvalidEnumParameterException($param, (string)$value, $enumClass);
+			}
+			$value = (int)$value;
+		} else {
+			$value = (string)$value;
+		}
+
+		return $enumClass::tryFrom($value) ?? throw new InvalidEnumParameterException($param, (string)$value, $enumClass);
+	}
 }

lib/private/AppFramework/Middleware/InvalidParameterMiddleware.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\AppFramework\Middleware;
+
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\Http\InvalidEnumParameterException;
+use OCP\AppFramework\Http\InvalidStringParameterException;
+use OCP\AppFramework\Http\ParameterOutOfRangeException;
+use OCP\AppFramework\Http\Response;
+use OCP\AppFramework\Middleware;
+
+/**
+ * Turns a controller parameter validation failure detected by the Dispatcher
+ * into a 400 Bad Request response.
+ */
+class InvalidParameterMiddleware extends Middleware {
+	/**
+	 * @throws \Exception
+	 */
+	#[\Override]
+	public function afterException(Controller $controller, string $methodName, \Exception $exception): Response {
+		if ($exception instanceof ParameterOutOfRangeException
+			|| $exception instanceof InvalidStringParameterException
+			|| $exception instanceof InvalidEnumParameterException) {
+			return new DataResponse(['message' => $exception->getMessage()], Http::STATUS_BAD_REQUEST);
+		}
+
+		throw $exception;
+	}
+}

lib/private/AppFramework/Utility/ControllerMethodReflector.php

@@ -20,6 +20,7 @@ class ControllerMethodReflector implements IControllerMethodReflector {
 	private array $types = [];
 	private array $parameters = [];
 	private array $ranges = [];
+	private array $stringConstraints = [];
 	private int $startLine = 0;
 	private string $file = '';
 	private ?\ReflectionMethod $reflectionMethod = null;
@@ -38,6 +39,7 @@ public function reflect($object, string $method) {
 		$this->types = [];
 		$this->parameters = [];
 		$this->ranges = [];
+		$this->stringConstraints = [];
 		$this->reflectionMethod = new \ReflectionMethod($object, $method);
 		$this->startLine = $this->reflectionMethod->getStartLine();
 		$this->file = $this->reflectionMethod->getFileName();
@@ -79,6 +81,23 @@ public function reflect($object, string $method) {
 					'max' => $matches['rangeMax'][$index] === 'max' ? PHP_INT_MAX : (int)$matches['rangeMax'][$index],
 				];
 			}
+
+			// extract psalm int aliases that imply a fixed range
+			preg_match_all('/@(?:psalm-)?param\h+(\?)?(?P<type>positive-int|non-negative-int|negative-int|non-positive-int)(\|null)?\h+\$(?P<var>\w+)/', $docs, $matches);
+			foreach ($matches['var'] as $index => $varName) {
+				$this->ranges[$varName] = match ($matches['type'][$index]) {
+					'positive-int' => ['min' => 1, 'max' => PHP_INT_MAX],
+					'non-negative-int' => ['min' => 0, 'max' => PHP_INT_MAX],
+					'negative-int' => ['min' => PHP_INT_MIN, 'max' => -1],
+					'non-positive-int' => ['min' => PHP_INT_MIN, 'max' => 0],
+				};
+			}
+
+			// extract psalm scalar string types
+			preg_match_all('/@(?:psalm-)?param\h+(\?)?(?P<type>non-empty-lowercase-string|non-falsy-string|non-empty-string|lowercase-string|numeric-string)(\|null)?\h+\$(?P<var>\w+)/', $docs, $matches);
+			foreach ($matches['var'] as $index => $varName) {
+				$this->stringConstraints[$varName] = $matches['type'][$index];
+			}
 		}
 
 		foreach ($this->reflectionMethod->getParameters() as $param) {
@@ -120,6 +139,25 @@ public function getRange(string $parameter): ?array {
 		return null;
 	}
 
+	public function getStringConstraint(string $parameter): ?string {
+		return $this->stringConstraints[$parameter] ?? null;
+	}
+
+	/**
+	 * Whether $value satisfies the psalm string type annotated for $parameter,
+	 * or true if none was annotated
+	 */
+	public function satisfiesStringConstraint(string $parameter, string $value): bool {
+		return match ($this->getStringConstraint($parameter)) {
+			'non-empty-string' => $value !== '',
+			'non-empty-lowercase-string' => $value !== '' && $value === strtolower($value),
+			'lowercase-string' => $value === strtolower($value),
+			'non-falsy-string' => $value !== '' && $value !== '0',
+			'numeric-string' => is_numeric($value),
+			default => true,
+		};
+	}
+
 	/**
 	 * @return array the arguments of the method with key => default value
 	 */

lib/public/AppFramework/Http/InvalidEnumParameterException.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Http;
+
+/**
+ * @since 35.0.0
+ */
+class InvalidEnumParameterException extends \InvalidArgumentException {
+	/**
+	 * @since 35.0.0
+	 */
+	public function __construct(
+		protected string $parameterName,
+		protected string $value,
+		protected string $enumClass,
+	) {
+		parent::__construct(
+			sprintf('Parameter %s with value "%s" is not a valid case of %s', $this->parameterName, $this->value, $this->enumClass)
+		);
+	}
+
+	/**
+	 * @since 35.0.0
+	 */
+	public function getParameterName(): string {
+		return $this->parameterName;
+	}
+
+	/**
+	 * @since 35.0.0
+	 */
+	public function getValue(): string {
+		return $this->value;
+	}
+
+	/**
+	 * @since 35.0.0
+	 */
+	public function getEnumClass(): string {
+		return $this->enumClass;
+	}
+}

lib/public/AppFramework/Http/InvalidStringParameterException.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Http;
+
+/**
+ * @since 35.0.0
+ */
+class InvalidStringParameterException extends \InvalidArgumentException {
+	/**
+	 * @since 35.0.0
+	 */
+	public function __construct(
+		protected string $parameterName,
+		protected string $constraint,
+	) {
+		parent::__construct(
+			sprintf('Parameter %s must be a %s', $this->parameterName, $this->constraint)
+		);
+	}
+
+	/**
+	 * @since 35.0.0
+	 */
+	public function getParameterName(): string {
+		return $this->parameterName;
+	}
+
+	/**
+	 * @since 35.0.0
+	 */
+	public function getConstraint(): string {
+		return $this->constraint;
+	}
+}