feat(http): Wire Validator and Serializer in http request dispatcher

Allow to write the following

class PersonController extends Controller {
    public function create(#[RequestPayload] PersonDto $person): DataResponse {
        // $person is already deserialized and valid at this point
    }
}

Signed-off-by: Carl Schwan <carl@carlschwan.eu>

Author: CarlSchwan

lib/composer/composer/autoload_classmap.php

@@ -138,6 +138,7 @@
     'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\PublicPage' => $baseDir . '/lib/public/AppFramework/Http/Attribute/PublicPage.php',
     'OCP\\AppFramework\\Http\\Attribute\\RequestHeader' => $baseDir . '/lib/public/AppFramework/Http/Attribute/RequestHeader.php',
+    'OCP\\AppFramework\\Http\\Attribute\\RequestPayload' => $baseDir . '/lib/public/AppFramework/Http/Attribute/RequestPayload.php',
     'OCP\\AppFramework\\Http\\Attribute\\Route' => $baseDir . '/lib/public/AppFramework/Http/Attribute/Route.php',
     'OCP\\AppFramework\\Http\\Attribute\\StrictCookiesRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/StrictCookiesRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\SubAdminRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/SubAdminRequired.php',
@@ -157,6 +158,7 @@
     '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\\InvalidPayloadException' => $baseDir . '/lib/public/AppFramework/Http/InvalidPayloadException.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',
@@ -176,6 +178,7 @@
     'OCP\\AppFramework\\Http\\Template\\SimpleMenuAction' => $baseDir . '/lib/public/AppFramework/Http/Template/SimpleMenuAction.php',
     'OCP\\AppFramework\\Http\\TextPlainResponse' => $baseDir . '/lib/public/AppFramework/Http/TextPlainResponse.php',
     'OCP\\AppFramework\\Http\\TooManyRequestsResponse' => $baseDir . '/lib/public/AppFramework/Http/TooManyRequestsResponse.php',
+    'OCP\\AppFramework\\Http\\ValidationFailedException' => $baseDir . '/lib/public/AppFramework/Http/ValidationFailedException.php',
     'OCP\\AppFramework\\Http\\ZipResponse' => $baseDir . '/lib/public/AppFramework/Http/ZipResponse.php',
     'OCP\\AppFramework\\IAppContainer' => $baseDir . '/lib/public/AppFramework/IAppContainer.php',
     'OCP\\AppFramework\\Middleware' => $baseDir . '/lib/public/AppFramework/Middleware.php',
@@ -1225,6 +1228,7 @@
     'OC\\AppFramework\\Http\\Output' => $baseDir . '/lib/private/AppFramework/Http/Output.php',
     'OC\\AppFramework\\Http\\Request' => $baseDir . '/lib/private/AppFramework/Http/Request.php',
     'OC\\AppFramework\\Http\\RequestId' => $baseDir . '/lib/private/AppFramework/Http/RequestId.php',
+    'OC\\AppFramework\\Http\\RequestPayloadResolver' => $baseDir . '/lib/private/AppFramework/Http/RequestPayloadResolver.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',

lib/composer/composer/autoload_static.php

@@ -179,6 +179,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\PublicPage' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/PublicPage.php',
         'OCP\\AppFramework\\Http\\Attribute\\RequestHeader' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/RequestHeader.php',
+        'OCP\\AppFramework\\Http\\Attribute\\RequestPayload' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/RequestPayload.php',
         'OCP\\AppFramework\\Http\\Attribute\\Route' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/Route.php',
         'OCP\\AppFramework\\Http\\Attribute\\StrictCookiesRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/StrictCookiesRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\SubAdminRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/SubAdminRequired.php',
@@ -198,6 +199,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         '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\\InvalidPayloadException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/InvalidPayloadException.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',
@@ -217,6 +219,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\Template\\SimpleMenuAction' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Template/SimpleMenuAction.php',
         'OCP\\AppFramework\\Http\\TextPlainResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/TextPlainResponse.php',
         'OCP\\AppFramework\\Http\\TooManyRequestsResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/TooManyRequestsResponse.php',
+        'OCP\\AppFramework\\Http\\ValidationFailedException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/ValidationFailedException.php',
         'OCP\\AppFramework\\Http\\ZipResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/ZipResponse.php',
         'OCP\\AppFramework\\IAppContainer' => __DIR__ . '/../../..' . '/lib/public/AppFramework/IAppContainer.php',
         'OCP\\AppFramework\\Middleware' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Middleware.php',
@@ -1266,6 +1269,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\AppFramework\\Http\\Output' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Http/Output.php',
         'OC\\AppFramework\\Http\\Request' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Http/Request.php',
         'OC\\AppFramework\\Http\\RequestId' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Http/RequestId.php',
+        'OC\\AppFramework\\Http\\RequestPayloadResolver' => __DIR__ . '/../../..' . '/lib/private/AppFramework/Http/RequestPayloadResolver.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',

lib/private/AppFramework/Http/Dispatcher.php

@@ -16,6 +16,7 @@
 use OC\DB\ConnectionAdapter;
 use OCP\App\IAppManager;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\RequestPayload;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\InvalidEnumParameterException;
 use OCP\AppFramework\Http\InvalidStringParameterException;
@@ -53,6 +54,7 @@ public function __construct(
 		private readonly IEventLogger $eventLogger,
 		private readonly ContainerInterface $appContainer,
 		private readonly IUserSession $userSession,
+		private readonly RequestPayloadResolver $requestPayloadResolver,
 	) {
 	}
 
@@ -155,10 +157,19 @@ private function executeController(Controller $controller, string $methodName):
 		$types = ['int', 'integer', 'bool', 'boolean', 'float', 'double'];
 
 		foreach ($this->reflector->getParameters() as $param => $default) {
+			$type = $this->reflector->getType($param);
+
+			$payloadAttribute = $type !== null ? $this->reflector->getParameterAttribute($param, RequestPayload::class) : null;
+			if ($payloadAttribute !== null) {
+				/** @var RequestPayload $requestPayload */
+				$requestPayload = $payloadAttribute->newInstance();
+				$arguments[] = $this->requestPayloadResolver->resolve($param, $type, $this->request->getRawContent(), $requestPayload->validationGroups);
+				continue;
+			}
+
 			// try to get the parameter from the request object and cast
 			// it to the type annotated in the @param annotation
 			$value = $this->request->getParam($param, $default);
-			$type = $this->reflector->getType($param);
 
 			// Converted the string `'false'` to false when the controller wants a boolean
 			if ($value === 'false' && ($type === 'bool' || $type === 'boolean')) {

lib/private/AppFramework/Http/Request.php

@@ -90,6 +90,11 @@ class Request implements \ArrayAccess, \Countable, IRequest {
 	 */
 	private ?\JsonException $decodingException = null;
 
+	/**
+	 * The raw request body, when the Content-Type was JSON-compatible.
+	 */
+	private ?string $rawContent = null;
+
 	/**
 	 * @param array $vars Associative request data with the following optional keys:
 	 *                    - array 'urlParams' route parameters extracted from the URL
@@ -388,6 +393,7 @@ protected function decodeContent() {
 		if (preg_match(self::JSON_CONTENT_TYPE_REGEX, $this->getHeader('Content-Type')) === 1) {
 			$content = file_get_contents($this->inputStream);
 			if ($content !== '') {
+				$this->rawContent = $content;
 				try {
 					$params = json_decode($content, true, flags:JSON_THROW_ON_ERROR);
 				} catch (\JsonException $e) {
@@ -423,6 +429,12 @@ public function throwDecodingExceptionIfAny(): void {
 		}
 	}
 
+	#[\Override]
+	public function getRawContent(): ?string {
+		$this->decodeContent();
+		return $this->rawContent;
+	}
+
 	#[\Override]
 	public function passesCSRFCheck(): bool {
 		if ($this->csrfTokenManager === null) {

lib/private/AppFramework/Http/RequestPayloadResolver.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\AppFramework\Http;
+
+use OCP\AppFramework\Http\InvalidPayloadException;
+use OCP\AppFramework\Http\ValidationFailedException;
+use OCP\Serializer\Format;
+use OCP\Serializer\ISerializer;
+use OCP\Validator\IValidator;
+
+/**
+ * Builds a {@see \OCP\AppFramework\Http\Attribute\RequestPayload} controller argument from the
+ * raw JSON request body
+ */
+class RequestPayloadResolver {
+	public function __construct(
+		private readonly ISerializer $serializer,
+		private readonly IValidator $validator,
+	) {
+	}
+
+	/**
+	 * @template T
+	 * @param class-string<T> $type
+	 * @param string|string[]|null $validationGroups
+	 * @return T
+	 * @throws InvalidPayloadException if `$rawContent` is not valid JSON, or does not satisfy `$type`'s constructor
+	 * @throws ValidationFailedException if the built object does not satisfy its own validation constraints
+	 */
+	public function resolve(string $parameterName, string $type, ?string $rawContent, string|array|null $validationGroups): object {
+		try {
+			$payload = $this->serializer->deserialize($rawContent ?? '', $type, Format::JSON);
+		} catch (\Throwable $e) {
+			throw new InvalidPayloadException($parameterName, $e->getMessage());
+		}
+
+		$violations = $this->validator->validate($payload, $validationGroups);
+		if ($violations !== []) {
+			throw new ValidationFailedException($parameterName, $violations);
+		}
+
+		return $payload;
+	}
+}

lib/private/AppFramework/Middleware/InvalidParameterMiddleware.php

@@ -13,14 +13,18 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\InvalidEnumParameterException;
+use OCP\AppFramework\Http\InvalidPayloadException;
 use OCP\AppFramework\Http\InvalidStringParameterException;
 use OCP\AppFramework\Http\ParameterOutOfRangeException;
 use OCP\AppFramework\Http\Response;
+use OCP\AppFramework\Http\ValidationFailedException;
 use OCP\AppFramework\Middleware;
+use OCP\Validator\Violation;
 
 /**
- * Turns a controller parameter validation failure detected by the Dispatcher
- * into a 400 Bad Request response.
+ * Turns a controller parameter validation failure detected by the Dispatcher into a 400 Bad
+ * Request response, or a 422 Unprocessable Entity response for a failed
+ * {@see \OCP\AppFramework\Http\Attribute\RequestPayload} validation.
  */
 class InvalidParameterMiddleware extends Middleware {
 	/**
@@ -30,10 +34,24 @@ class InvalidParameterMiddleware extends Middleware {
 	public function afterException(Controller $controller, string $methodName, \Exception $exception): Response {
 		if ($exception instanceof ParameterOutOfRangeException
 			|| $exception instanceof InvalidStringParameterException
-			|| $exception instanceof InvalidEnumParameterException) {
+			|| $exception instanceof InvalidEnumParameterException
+			|| $exception instanceof InvalidPayloadException) {
 			return new DataResponse(['message' => $exception->getMessage()], Http::STATUS_BAD_REQUEST);
 		}
 
+		if ($exception instanceof ValidationFailedException) {
+			return new DataResponse([
+				'message' => $exception->getMessage(),
+				'violations' => array_map(
+					static fn (Violation $violation): array => [
+						'propertyPath' => $violation->propertyPath,
+						'message' => $violation->message,
+					],
+					$exception->violations,
+				),
+			], Http::STATUS_UNPROCESSABLE_ENTITY);
+		}
+
 		throw $exception;
 	}
 }

lib/private/AppFramework/Utility/ControllerMethodReflector.php

@@ -198,6 +198,24 @@ public function getAttribute(string $attributeClass): ?\ReflectionAttribute {
 		return null;
 	}
 
+	/**
+	 * @template T
+	 * @param class-string<T> $attributeClass
+	 * @return ?\ReflectionAttribute<T>
+	 */
+	public function getParameterAttribute(string $parameter, string $attributeClass): ?\ReflectionAttribute {
+		foreach ($this->reflectionMethod->getParameters() as $reflectionParameter) {
+			if ($reflectionParameter->name !== $parameter) {
+				continue;
+			}
+
+			$attributes = $reflectionParameter->getAttributes($attributeClass);
+			return $attributes[0] ?? null;
+		}
+
+		return null;
+	}
+
 	/**
 	 * Check if a method contains an annotation
 	 * @param string $name the name of the annotation

lib/public/AppFramework/Http/Attribute/RequestPayload.php

@@ -0,0 +1,44 @@
+<?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\Attribute;
+
+use Attribute;
+
+/**
+ * Marks a controller method parameter as populated from the JSON request body
+ *
+ * The parameter's type is deserialized from the request body with
+ * {@see \OCP\Serializer\ISerializer} and validated with {@see \OCP\Validator\IValidator}
+ * before the controller method is called. A malformed or unprocessable body never reaches
+ * the controller: it short-circuits into a 400 or 422 response.
+ *
+ * ```
+ * class PersonController extends Controller {
+ *     public function create(#[RequestPayload] PersonDto $person): DataResponse {
+ *         // $person is already deserialized and valid at this point
+ *     }
+ * }
+ * ```
+ *
+ * @since 36.0.0
+ */
+#[Attribute(Attribute::TARGET_PARAMETER)]
+final class RequestPayload {
+	/**
+	 * @param string|string[]|null $validationGroups only constraints tagged with one of these
+	 *                                               groups are checked, `null` checks every
+	 *                                               constraint regardless of its groups
+	 * @since 36.0.0
+	 */
+	public function __construct(
+		public readonly string|array|null $validationGroups = null,
+	) {
+	}
+}

lib/public/AppFramework/Http/InvalidPayloadException.php

@@ -0,0 +1,28 @@
+<?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;
+
+/**
+ * Thrown when a {@see \OCP\AppFramework\Http\Attribute\RequestPayload} parameter could not be
+ * built from the request body, e.g. because it is not valid JSON or is missing required fields
+ *
+ * @since 36.0.0
+ */
+class InvalidPayloadException extends \InvalidArgumentException {
+	/**
+	 * @since 36.0.0
+	 */
+	public function __construct(
+		public readonly string $parameterName,
+		string $reason,
+	) {
+		parent::__construct(sprintf('Parameter %s could not be built from the request body: %s', $parameterName, $reason));
+	}
+}

lib/public/AppFramework/Http/ValidationFailedException.php

@@ -0,0 +1,31 @@
+<?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;
+
+use OCP\Validator\Violation;
+
+/**
+ * Thrown when a {@see \OCP\AppFramework\Http\Attribute\RequestPayload} parameter was built from
+ * the request body but failed validation
+ *
+ * @since 36.0.0
+ */
+class ValidationFailedException extends \RuntimeException {
+	/**
+	 * @param Violation[] $violations
+	 * @since 36.0.0
+	 */
+	public function __construct(
+		public readonly string $parameterName,
+		public readonly array $violations,
+	) {
+		parent::__construct(sprintf('Parameter %s failed validation with %d violation(s)', $parameterName, count($violations)));
+	}
+}